本地 · 不出网 · AI 代码验收闸门 + 成本中枢

AI 写的代码，
Hopper 负责验收和管钱。

agent 自报的「完成」不可信。Hopper 自己重跑验证（改了测试就在 base 版测试上还原重跑，抗恒绿）、逐条核对验收标准证据、产出可分享的信任报告；同时把 Claude / Codex 的真实额度与预算收进可见可控的闸门。编排层（Markdown / GitHub Issues / 禅道 intake → 调度 → worktree → review → merge）是承载这一切的免费地基。

开始上手看它怎么跑

$git clone https://github.com/Octo-o-o-o/Hopper.git && cd Hopper && npm ci && npm run build && node bin/hopper.mjs init

FIG.00 — 文档投递 → 分诊 → 隔离 worktree → 质检闸门 → 输出

SHEET 01

这是什么 · 不是什么

一条本地的
AI 代码交付验收流水线。

Hopper 是一个 CLI 工具，没有服务端。你把 Markdown 投递进中央 vault，它自动完成分诊 → 排队 → 依赖/风险判断 → 选 runner → 隔离 worktree → 编译 prompt → 执行 → 验证 → 验收 → 文档对齐 → 人类 review → merge/归档，全程事件审计。

工程视角：文件系统是真相，Git 是审计，runner 是可替换执行后端，scheduler 管排队/并发/依赖/锁，merge gate 管安全边界。

非目标 · 它不做

不做新的 coding agent，不重写 Claude Code / Codex
不做新的 Jira / Linear / Taskmaster / Backlog
不做云端 Devin 替代品、通用 RPA
MVP 阶段不做复杂 Web UI —— 文档 UI 交给 Obsidian

文件即真相

~/Hopper/ 下的 Markdown 加上 .hopper/events.jsonl 可重建全部状态。崩溃也能对账恢复。

Done 必须可信

runner 完成 ≠ 任务完成。要过 Hopper 自跑的验证、逐条验收、文档对齐、人类 review，代码任务还要 merge。

不可信输入模型

所有 Markdown / 外部内容都是不可信输入，不能放宽 guardrails。确定性闸门在 runner 结束后兜底，LLM 不能降低安全规则。

SHEET 02

心智模型 · 一条装配线

从一份 Markdown
到一次可信的 merge。

每个任务都在同一条流水线上流动。runner 完成只是中间一站——后面还有自动质检、人类审查和合并闸门。下面这张图就是 Hopper 的全部。

FIG.02 — 单任务生命周期 · 末事件决定任务最终落到 failed / blocked / review

工位 1–2

投递 → 分诊

四类入口投进 Inbox，去重；parser → rules → 可选 LLM 三层分诊，编译出带上下文与验收标准的 prompt。

工位 3–4

排队 → 隔离

依赖 DAG、风险、usage/预算共同决定能否跑；先写 RunReserved 再建 worktree，在独立分支里跑 Claude/Codex。

工位 5

质检闸门

Hopper 自跑验证、确定性 guardrails、风险复核、验收证据、文档对齐——逐步 emit 事件，末事件定状态。

工位 6–7

审查 → 合并

人类 approve / 加 waiver / 打回重试；merge 前再跑一次 smoke 验证，冲突保留现场，最后归档。

SHEET 03

文件即真相 · 两层状态

状态从不直接写——
它是事件流的投影。

机器读 events.jsonl 的细状态，人读 frontmatter 的粗状态。你永远不用手写 status：它由事件流投影出来，且写回是「受保护」的——你在 Obsidian 里改正文，不会被覆盖。

FIG.03 — 同一份真相的两个视图 · events.jsonl 可重建全部状态

Vault 布局 · ~/Hopper/

~/Hopper/

├─ 00-Inbox/ · 投递入口 _unassigned/ 或 <project>/

├─ 10-Projects/ · Tasks / Plans / Research / Reviews

├─ 20-Runs/ · 给人看的运行 / 验证 / review 摘要

├─ 80-Attachments/ · 图片 / PDF / 日志

├─ 90-Archive/ · 归档

├─ .obsidian/ · Obsidian 配置

└─ .hopper/ · 机器态 · 默认 gitignore

├─ events.jsonl 真相源

├─ config.yml · projects.toml

└─ locks/ runs/ worktrees/ state/ …

▬ 用户可见（进 Obsidian 图谱） ▬ 机器态（别手动碰）

可以改

任务 Markdown 正文与验收标准
frontmatter 里的 priority / runner / depends_on / tags / do_not_run
用 Obsidian 浏览、双链、看运行摘要

别手动碰

.hopper/events.jsonl · state/ · locks/ · requests/
frontmatter 的 status / updated_at / last_run_id（投影字段）
状态冲突时跑 hopper reconcile --dry-run

SHEET 04

四类入口 · 同一条生产线

想怎么写需求，
就怎么投。

手写笔记、Obsidian、Claude Code / Codex 会话、GitHub Issues / 禅道 Story 等外部需求源——四类入口最终都汇成 vault 里的 Markdown，由同一套 drop → scan → triage 闭环处理。

四类入口汇入中央 vault 枢纽的等距工程蓝图插画 — PLATE 04 · 笔记 / 图谱 / 终端 / 外部需求源汇入中央 vault

FIG.04 — 四类入口 → 中央 vault → 同一条闭环

入口 01

手动维护 Markdown

最直接：写一个 .md，frontmatter 写 runner / risk，正文写需求 + Acceptance 清单，drop 进去。

$ hopper drop ./task.md --project my-app

$ hopper move <id> --to-project my-app

未指定 project 进 _unassigned，可再改派。

入口 02

在 Obsidian 里维护

vault 就是 Obsidian vault。用属性视图筛 status/project、用图谱看依赖、读 20-Runs/ 摘要——开箱即用，Hopper 不自研文档 UI。

把 ~/Hopper 作为 vault 打开
编辑正文 / 调 priority、depends_on
双链跳转任务 ↔ 验收 ↔ 运行摘要

入口 03

在 Claude Code / Codex 里维护

让 AI 写好方案，正文直接 pipe 给 Hopper；或在业务 repo 内用 .hopper-inbox symlink 投递。

$ cat needs.md | hopper drop --stdin \

--project my-app

/hopper-drop slash 命令暂未实现，pipe stdin 最稳。

入口 04

从外部需求源接入

GitHub Issues 可单向快照导入并回写 comment；禅道 Story 可只读导入、手动回写评论/字段，并通过 pull 给出 close/spec/assignedTo 建议。

$ hopper github link --repo owner/app

$ hopper github sync && hopper scan

$ hopper zentao import --story 109

$ hopper zentao sync-back --task <id> --yes

外部正文一律标 external_untrusted，不能放宽 guardrails。

SHEET 05

任务状态机 · 14 个粗状态

每个任务
都走在这张图上。

主生命线是 received → ready → running → review → done。其余状态是分支与回环：验证不过回 failed、guardrail 命中进 blocked、人工打回重试……都能解释、都能恢复。

FIG.05 — 实线=主路径 · 虚线=分类/回环 · 颜色按状态分组 · 不变量「末事件定状态」

ready依赖满足，可立即执行

running执行中或在过质检闸门

review等人类决策（approve/打回）

failed执行/验证失败，可 retry

blockedguardrail 硬失败，需人工

conflictmerge 冲突，保留现场

done已合并并通过全部闸门

archived最终态：归档/拒绝/搁置

SHEET 06

质量闸门 · Done 必须可信

runner 说"完成"，
只是体检开始。

runner 一收工，Hopper 在隔离 worktree 里按顺序跑 6 道闸门。顺序即优先级：前置闸门失败立即中止，由最后一个事件决定任务落到 failed / blocked / review。

五道质检闸门安检流水线的等距工程蓝图插画，琥珀色高亮当前闸门，失败包裹分流到侧轨 — PLATE 06 · 安检流水线 · 当前闸门高亮 · 失败件分流到侧轨

FIG.06 — 6 道闸门顺序执行 · 每步 emit 事件 · 末事件定状态

为什么要冻结验证计划

验证用的是任务开始时、在 base commit 状态冻结的 plan。runner 就算改了测试脚本，也影响不了本次闸门——它没法给自己放水。

确定性优先，LLM 只建议

前两道是确定性闸门（不调 LLM），可以硬阻断。风险复核只升不降，验收与文档即使有问题也只记录、交人判断。

断点协作 · Assisted-mode

Assisted-mode 下 runner 在计划步边界停下发决策卡，你在 Console 或 CLI（hopper breakpoint release）放行 / 加注 / 否决后，同一个 run 原地续跑——不用推倒重来。

merge 队列 · 可选

启用后 approve 即入队，queue worker 是唯一 canonical 落地 writer，逐个串行落地；generation fencing 防旧一代运行结果误落地。approve 仍然是你。

代码任务还要 merge。review 通过 ≠ done——必须 hopper merge（或启用 merge 队列后由 queue worker 落地），且 merge 前再跑一次 smoke 验证。

SHEET 07

命令速查 · 一张规格表

全部命令，
分门别类。

全局开关 --json（脚本友好）、--debug、--vault <path>（覆盖 HOPPER_VAULT 或默认 ~/Hopper）几乎处处可用。

初始化与接入setup · link

hopper init [path]创建 / 幂等更新中央 vault 布局

hopper setup --link-repo --project -y最小交互首跑：建 vault + 可选 link repo

hopper link-project --project --repo接入业务 repo，写 .hopper.project.yml + symlink

hopper git init把 vault 初始化为 Git repo（默认不初始化）

投递与外部接入drop · github · zentao

hopper drop [file] --project --stdin投递 Markdown 进 Inbox 并即时去重

hopper github link --project --repo关联已注册项目到 GitHub repo

hopper github sync --project|--all --dry-run命中 label 的 open issue → bug-list

hopper github status --project查看同步状态 / 已导入数

hopper github sync-back --task --dry-run把修复摘要 comment 回源 issue

hopper zentao doctor检查禅道配置、登录态和回写载体

hopper zentao import --product|--story --dry-run只读导入 Story，按 source_path 幂等

hopper zentao sync-back --task --yes手动回写评论或自定义字段，默认先预览

hopper zentao pull --apply --yes拉取 close / spec / assignedTo 建议，人确认后应用

分诊与编译scan · triage · prompt

hopper scan发现并登记新 Inbox 文件 + 确定性 triage

hopper triage [task-id] --all --no-llm(重新)分诊，可选 LLM 建议

hopper prompt compile <task-id>预览编译的 prompt + context manifest

依赖与队列dep · queue

hopper dep add <task> --after <dep>添加 / 移除（remove）硬依赖

hopper dep accept <task> --reason接受系统建议的依赖

hopper dep graph · explain · ready依赖图 / 解释 / ready 集合

hopper queue explain解释每个 ready 任务为何（不）可执行

执行run · drain · daemon

hopper run next执行恰好一个 ready 任务

hopper run <task-id>定向执行指定 ready 任务，闸门与 run next 完全一致

hopper run --parallel执行当前 ready 集合一次后退出

hopper drain --max <n>持续取任务直到队列空 / 被 stop（并发由配置决定）

hopper daemon --max <n>受控自动执行（只到 review，不 merge）

hopper daemon pause · resume暂停 / 恢复 claim 新任务

状态与证据status · show · usage

hopper status由事件流投影展示任务状态

hopper show <task-id>任务详情：frontmatter + 事件投影

hopper logs <task-id>最近一次 run 的 raw log

hopper usage · budgetrunner 用量 / USD soft accounting

hopper project show <name>单项目配置解析后快照（缺省值补齐）

hopper capabilities能力 / 版本握手：枚举事件、状态、mutation 命令，--json 供机器

审查 · 合并 · 归档review · merge · retry

hopper review list · show · diff · patch · open列表 / 详情 / diff / 导出 patch / 打开 worktree

hopper review approve --waive <kind:target> --reason批准，可结构化豁免缺口

hopper review request-changes · reject --message要求修改 / 拒绝

hopper merge <task-id>merge（前置 smoke 验证，冲突保留现场）

hopper retry --runner --message --keep-worktree重试，可切 runner

hopper archive --cleanup-worktree --status归档（archived/rejected/deferred）

写作 · 文档 · 恢复 · 运维new · lint · docs · reconcile

hopper new <title> --project创建任务模板文件，不登记、不分诊

hopper lint <file>只读检查 Hopper 任务文档质量线

hopper check --base --staged --criteria对任意 repo 的 diff 独立跑四道闸门，产出信任报告

hopper docs check · show <task-id>重跑 / 查看 Documentation Alignment Gate

hopper reconcile --dry-run对账 + 安全修复（释放 stale 锁、恢复崩溃 run）

hopper doctor [privacy]健康检查 + 对账报告 / 敏感数据自检

hopper cancel · unblock · move · reassign取消 / 解封 / 改派任务

Schema · Runnerschema · runner

hopper schema validate [path] · export --out校验 / 从 zod 派生 JSON Schema

hopper runner list · show · probe <id>列出 / 详情 / 探测 runner 能力

hopper runner detect --home扫描 ~/.claude* ~/.codex* 打印建议

平台运维cmd · stop · breakpoint · merge-queue

hopper cmd <verb> <target>统一命令服务：durable / 幂等 / 五终态，与 Console 共用

hopper stop --release --status急停：冻结 intake、停止领取，按 severity 处置执行中任务

hopper breakpoint list · release · resume <decisionId>Assisted-mode 断点卡：列出 / 放行（可加注）/ 同 run 续跑

hopper merge-queue list · run · release <task>merge 队列：看队列 / 跑 queue worker / 放行 manual_release 项

hopper credentials resume凭证 401 / quota 自动暂停后的一键恢复

hopper intake list · resolve <proposalId> --choiceintake 提案卡：列出 / 决议（accept 即注册 project + 投首任务）

hopper attest request · confirm · reject · listattestation：真人裁决 → 签名回执

hopper project contract lint · propose · seal · refresh交付合同生命周期

hopper project gate <task-id> · coverage单任务交付门检查 / 项目覆盖度报告

hopper project enroll …交付链登记入口（同级还有 project artifact-put / challenge / attest / lease 等）

SHEET 08

本地控制台 · 可选图形界面

不想敲命令？
开一个本地控制台。

一条 hopper console 起一个只绑 127.0.0.1 的本地网页：Control Room 看全局、决策收件箱做 review、双 tab 提任务 / 提 Bug，全部读同一份文件真相、写同一条 mutation 队列。它是 CLI 的皮肤，不接管状态机——关掉它，CLI 照常工作。

$hopper console

它能做什么control room · decisions · bug report

首跑向导空 vault 几步配好：建 vault → 接入 repo（自动探测验证命令）→ 选 runner

Control Room一屏六区：活动 run · 待决策 · 预算燃烧 · 风险 · 近期结果 · 运营指标

决策收件箱风险审批 / review / blocked / failed 聚合一处；决议绑定 digest / revision，杜绝对着旧状态拍板

Review 控制台看 diff / 验证 / 验收 / 文档对齐 / 风险，一键 approve · merge · retry

任务详情操作failed → Retry、blocked → Unblock、Archive，按任务实际风险给指引

提任务 / 提 Bug 双 tab自由 Markdown，或结构化 Bug 表单生成规范 Markdown；投递前给确定性 triage 预判 chip

导入预览预览禅道 Story 渲染结果和外部来源标记，再决定是否导入

草稿防丢编辑中不吞输入（刷新不打断），localStorage 兜底草稿

界面双语跟随浏览器语言的中 / 英切换，可手动切换

只绑 127.0.0.1、随机 token + Origin 校验，数据不出本机；执行仍由 daemon / CLI 调度，控制台不代跑任务、不替你 approve / merge。

SHEET 09

快速上手 · 一条最小闭环

五分钟，
跑通第一条任务。

最小闭环 · bash

# 0 · 克隆并构建（Node ≥ 22；npm 包发布前从源码安装）
git clone https://github.com/Octo-o-o-o/Hopper.git && cd Hopper
npm ci && npm run build && npm link

# 1 · 初始化 vault，接入你的 repo
export HOPPER_VAULT="$HOME/Hopper"
hopper init
hopper link-project --project my-app --repo /abs/my-app

# 2 · 投递一个任务
cat task.md | hopper drop --project my-app --stdin

# 3 · 分诊 → 排队 → 执行
hopper scan
hopper triage --no-llm
hopper queue explain
hopper run next

# 4 · 审查 → 合并 → 归档
hopper review diff <task-id>
hopper review approve <task-id>
hopper merge <task-id>
hopper archive <task-id> --cleanup-worktree

无人值守到 review

daemon 只自动推进到 review，绝不替你 approve / merge。

$ hopper daemon --max 10

$ hopper review list

真实 runner 怎么起步

先用低风险任务试水：README typo、文档小节
人工核对 diff / verification / acceptance / docs 再扩大
hopper runner probe claude|codex 先验能力

vault 即 Obsidian vault。用 Obsidian 打开 ~/Hopper 就能浏览任务、运行摘要、review 与归档——无需任何额外 UI。

AI 写的代码，Hopper 负责验收和管钱。

一条本地的AI 代码交付验收流水线。