Hopper — 用户只管理文档，Hopper 管生产线

SHEET 01

这是什么 · 不是什么

一个本地的
开发生产线编排层。

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

01

文件即真相

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

02

Done 必须可信

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

03

不可信输入模型

所有 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——四个入口最终都汇成 vault 里的 Markdown，由同一套 drop → scan → triage 闭环处理。

四种入口汇入中央 vault 枢纽的等距工程蓝图插画 — PLATE 04 · 笔记 / 图谱 / 终端 / issue 四管汇入中央 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 接入

单向快照导入：命中 label 的 open issue 拉成 bug-list，scan 拆成 child，修复后手动回写 comment（不自动 close）。

$ hopper github link --repo owner/app

$ hopper github sync && hopper scan

$ hopper github sync-back --task <id>

每条 issue 标 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），可以硬阻断。风险复核只升不降，验收与文档即使有问题也只记录、交人判断。

代码任务还要 merge。review 通过 ≠ done——必须 hopper merge，且 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（默认不初始化）

投递与 GitHubdrop · github

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

分诊与编译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 --parallel执行当前 ready 集合一次后退出

hopper drain --parallel --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

审查 · 合并 · 归档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）

文档 · 恢复 · 运维docs · reconcile · doctor

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* 打印建议

SHEET 08

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

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

一条 hopper console 起一个只绑 127.0.0.1 的本地网页：看队列、看进度、做 review 决策、投递 Markdown，全部读同一份文件真相、写同一条 mutation 队列。它是 CLI 的皮肤，不接管状态机——关掉它，CLI 照常工作。

$hopper console

它能做什么onboarding · dashboard · review

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

Dashboard一屏三问：有哪些任务、哪些在跑、哪些需要我决策

Progress事件流实时刷新（SSE），状态机高亮当前阶段

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

Drop浏览器里贴一段 Markdown 投递到指定项目

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

SHEET 09

快速上手 · 一条最小闭环

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

最小闭环 · bash

# 0 · 安装并构建（Node ≥ 22）
npm install && npm run build

# 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。

用户只管理文档，Hopper 管生产线。

一个本地的开发生产线编排层。