HopJIT

HopJIT 是 HopSpec v3 的执行运行时——一套面向 LLM Agent 的结构化执行引擎。你用 HopSpec markdown 声明任务结构（步骤类型、数据流、循环/分支/并行、人机介入点），HopJIT 负责执行状态管理、变量存储、retry/adaptive 修复、None 传播等流控。

📖 新用户从这里开始：USAGE.md — 从安装到在 Claude Code 里跑通第一个 spec 的完整上手指南。

两种驱动模式：

• 复用模式（reuse）：外层 LLM（如 Claude Code）当推理引擎，HopJIT 只做纯流控——不需要 API key。配套 hopspec skill 驱动。
• 独立模式（standalone）：HopJIT 内部 StepDispatcher 直调 LLM API 执行——需 @anthropic-ai/sdk + ANTHROPIC_API_KEY。

包名、命令名、文件

一句话理清三层：装 包 @hoplogic/hopjit → 得到 命令 hopjit → 它执行包内的 dist/cli.js。

# 全局 CLI
npm install -g @hoplogic/hopjit

# 或项目内
npm install @hoplogic/hopjit

# 开发期（克隆本仓库）
npm install && npm run build && npm link

装好后 hopjit --help 可用（bin 命令名是 hopjit，与包名 scope 无关）。

CLI 用法

hopjit validate <spec.md>        # 校验 spec 合法性（放行前闸门，验证规则）
hopjit list <dir>                # 列出目录下可执行 spec
hopjit run <spec.md> [--params '<json>']   # 启动执行（复用模式由 skill 驱动，见下）
hopjit status --state-dir <dir> [--instance <id>]   # 查执行进度
hopjit resume --state-dir <dir> [--instance <id>]   # 从中断恢复
hopjit install-skill [--dir <目标>] [--carrier cc|codex]   # 安装驱动 skill（见下）

其余子命令（init / submit_and_fetch_next / join_parallel / fanout-plan / fanout-next / debug_step / vars）由驱动层（skill / dispatcher）调用，一般不手动跑。

Quickstart（校验你自己的 spec）：

hopjit validate my-spec.md

spec 范本见项目仓库 examples/（未随 npm 包发布——多为引擎自测范本）。

复用模式：安装驱动 skill

复用模式下外层 LLM（Claude Code / Codex）通过 skill 驱动引擎。一条命令安装（自动把包内 driver/ 源展开到正确布局，免手动 cp）：

# Claude Code（默认，装到 .claude/skills/）
hopjit install-skill

# Codex（装到指定目录，用 AGENTS.md 载体）
hopjit install-skill --carrier codex --dir .

# 覆盖已存在的（改过 skill 想重置时）
hopjit install-skill --force

install-skill 展开的布局（CC）：

.claude/skills/
├── hopspec/
│   ├── SKILL.md          # 主 skill（源 driver/hopspec-skill.md 改名）
│   └── references/       # 载体中立共享（cli-discovery / driver-subagent / …）
└── hopskill-build/
    ├── SKILL.md
    └── references/

skill 启动时自举探测 hopjit 位置（全局命令 → 项目 node_modules → 包内 dist → 开发期 fallback），无需硬编码路径——见 references/cli-discovery.md。

之后在 Claude Code 里：

/hopspec run <spec.md>          # 驱动执行一个 spec
/hopspec list [dir]             # 列出可执行 spec
/hopskill-build                 # 把 prose skill 翻译成 hopskill

Codex 载体见 driver/codex/AGENTS.md——同构 CC，只换四处载体原语（触发 / 起 subagent / 问人 / act 工具）。

依赖说明

• 运行时依赖：commander（CLI）+ @anthropic-ai/sdk（仅独立模式的 StepDispatcher 用；复用模式不触发）。
• 复用模式（skill 驱动）不需要 API key——推理由外层 LLM 承担。

文档

• 项目仓库 examples/ — 端到端 spec 范本（data-quality / doc-review / parallel-* / fact-check 等；未随 npm 包发布）。
• HopSpec v3 语法与执行语义见项目概念层文档（HopSpec V3 核心规范 / 配套 HopJIT 运行时能力）。

License

MIT