关于 Hopper，
你可能想先搞清楚的事

不是。Hopper 自己不写代码，也不是 coding agent。它负责 AI 代码的验收和管钱：你把需求写成 Markdown 投进去，它负责分诊、排队、隔离、调用真正写代码的 agent（Claude Code / Codex）、自跑验证与验收闸门、交给你 review、合并。把它想成「AI 代码的交付验收闸门 + 成本中枢」，而不是又一个码农 AI。

互补。Claude Code / Codex 是执行后端（runner），真正在隔离 worktree 里改代码；Hopper 是它们外面的验收与管控层，管 intake、依赖、并发、隔离、质量闸门、review、merge。runner 是可替换的——今天是 Claude/Codex，将来可接入别的执行后端。

那些是任务看板，记录和追踪「人要做的事」。Hopper 是会执行的生产线，把任务真正跑出代码变更、过质量闸门、交给你 review。看板止于「分配」，Hopper 止于「一个评审过的变更」。

CI/CD 跑你写死的固定脚本（lint/test/build/deploy），输入是「已经写好的代码」。Hopper 调度 AI 把一句意图变成代码变更——它在 CI 之前，负责把想法变成可评审的 diff。两者可以共存：Hopper 产出变更，你的 CI 照常验证。另外，hopper check 可以独立使用：不接入 Hopper 流水线，也能对任意 repo 的 diff 跑四道验收闸门，一条命令出信任报告。

会。除了 runner 执行任务，Hopper 自己的分诊、prompt 编译、验收核对、文档对齐也是 LLM 调用（统称 meta_runner），同样计入用量。但确定性规则优先——能用规则判定的就不调 LLM，所以 meta 开销通常很小。

AI 写的代码，Hopper 负责验收和管钱——你只管写 Markdown，它把需求可靠、可审计、可恢复地变成评审过的代码变更，编排是免费地基。

如果你只是想要一个聊天式 AI 帮你即时改一行代码——直接用 Claude Code / Codex 更快，Hopper 的流程是额外开销。如果你的工作不涉及代码仓库、或不需要审计 / 隔离 / 质量闸门，它的价值发挥不出来。它为「有一批需求、要可靠批量推进、且看重可控与可审计」的场景设计。

MIT 许可。Hopper 本身免费；你只为底层 runner（Claude/Codex 的订阅或 API）和 Hopper 自己的 meta LLM 调用付费，这些计入你已有的用量。

MVP 主闭环已完整跑通（init → 投递 → 分诊 → 执行 → 质量闸门 → review → merge → 恢复），有六层测试加平台合同一致性（conformance）层覆盖；GitHub Issues 和禅道 Story 接入也有 fake / e2e 覆盖。但部分能力仍是降级方案（见 哪些没实现）。建议先用低风险任务和 dry-run 试水，人工核对每一步证据后再扩大。

Hopper 本身是纯本地 CLI，没有服务端，不上传你的文件。唯一出网的是底层 runner 和 meta LLM 调用（Claude/Codex 的 API）——那是 AI 推理本身需要的，和你直接用它们一样。文件、状态、审计全部在你本地。

不会。一切都是你本地的纯文本——Markdown 任务 + 一个 append-only 的 events.jsonl 事件流。vault 就是个普通文件夹（还兼容 Obsidian），可直接用 git 管理、随时打包带走。删掉 Hopper，你的文档和代码原封不动。

Hopper 没有数据库。~/Hopper/ 下的 Markdown 加上 .hopper/events.jsonl 就是全部真相——状态可以从事件流完整重建，崩溃后能对账恢复。这让一切可审计、可 git、可手查。

两层——机器读 events.jsonl（细状态，每一步留痕），人读任务 frontmatter 的粗状态（received → ready → running → review → done）。你不用、也不该手写 status：它由事件流投影出来，且写回是受保护的（你在 Obsidian 改正文不会被覆盖）。

runner 是执行任务的后端 adapter。claude / codex 是真实 agent；fake 是测试用的真实子进程（受脚本控制，跑端到端闭环不烧真钱）。任务可以指定用哪个，或交给 Hopper 自动选。

因为 runner 自报「我做完了」不可信。runner 一收工，Hopper 在隔离 worktree 里自己按顺序跑 6 道质量闸门：验证（跑冻结的 test/lint/build）、确定性 guardrails、风险复核、逐条验收核对、文档对齐、运行摘要。任何硬闸门不过就拦下。代码任务还要你 review + merge 才算真正 done。

默认安全边界——不 push、不改 main、不碰 secrets / forbidden paths、不自动执行 high risk、不自动 merge。这些是确定性闸门，在 runner 结束后兜底，不能被任务正文、外部内容或 LLM 放宽。

隔离。每个任务在自己的 worktree + 分支（hopper/<task>-<slug>）里跑，互不干扰、同 repo 串行、跨 repo 可并发；worktree 里还注入了 git push 拦截。出问题只影响那个隔离环境，不会污染你的主工作区。

Assisted-mode 下，runner 会在计划步边界停下并发出一张决策卡，任务原地等人。你在 Console 决策收件箱或 CLI 处理：hopper breakpoint list 看卡、breakpoint release 放行（可加注、可否决）、breakpoint resume 让同一个 run 原地续跑，不用推倒重来。适合想盯关键步、又不想全程人肉陪跑的中间信任档。

merge 队列是可选启用的落地通道：启用后 review approve 即把任务放进队列，queue worker 是唯一 canonical 落地 writer，逐个串行落地，generation fencing 防止旧一代运行结果误落地；hopper merge-queue list/run/release 运维。它不是 auto-merge——approve 仍然是人做的不可逆决策，队列只是把「落地」这一步变成可控、串行、可审计的自动化。

投递后 Hopper 自动：分诊（定项目 / 风险 / runner）→ 排队（查依赖）→ 建隔离 worktree → 编译 prompt → 跑 runner → 过 6 道质量闸门 → 把任务推到 review，然后停下等你。你回来看 diff 和证据，approve / 打回 / 拒绝；满意了 hopper merge。一句话：前半程全自动，approve 和 merge 永远是你。

你的核心动作只有三个：写需求、review、merge。可以开 daemon 让它无人值守批量推进——但 daemon 最多自动推到 review，绝不替你 approve 或 merge，而且默认只自动跑 low risk。决策权始终在你手里，这是设计上的硬边界，不是限制。

四类，最终都汇成 vault 里的 Markdown：① 手动 hopper drop file.md（随手投）；② Obsidian（想浏览 / 编辑 / 看依赖图谱时）；③ Claude Code / Codex 会话（让 AI 写好方案后 pipe 给 hopper drop --stdin）；④ 外部需求源（GitHub Issues 用 hopper github sync，禅道 Story 用 hopper zentao import）。

三件事决定质量：清晰的意图（要做什么、为什么）、可核对的验收标准（Acceptance 清单，Hopper 会逐条核对证据）、必要的 frontmatter（如 runner、risk、project）。意图模糊或没有验收标准，结果就难保证。

hopper link-project --project my-app --repo /abs/path。它会注册项目、在 repo 里写 .hopper.project.yml、建一个 .hopper-inbox symlink，方便从 repo 里投递。

hopper github link 关联仓库 → hopper github sync 把命中 label 的 open issue 拉成 bug-list → hopper scan 拆成可执行 child。修复后可 hopper github sync-back 把摘要回写到原 issue。单向快照导入，不双向同步、不自动关 issue。

在 .hopper/zentao.toml 配好 site / product → project 映射后，先跑 hopper zentao doctor 检查连接、登录态和回写载体；再用 hopper zentao import --product 1 --dry-run 预览，或 hopper zentao import --story 109 只读导入单条 Story。导入用 source_path: zentao://... 幂等去重，正文按 external_untrusted 处理。

修复后，hopper zentao sync-back --task <id> 默认只预览，带 --yes 才发布到禅道；默认走 Story 评论，也可配置自定义字段并 read-back 验证。hopper zentao pull 只拉 close / spec / assignedTo 建议，默认不静默改 Hopper 状态。

最常见是被风险闸门挡住——正文出现 token/auth/ci/deploy/session/支付 等敏感词会被保守判为 medium/high（有意的「风险只升不降」），而 daemon 只自动跑 low。其它原因：项目没 link-project（未注册）、依赖未完成、pin 的 runner 不可用。先跑 hopper queue explain，或看 hopper status 的 not_runnable_reasons——它会逐条说明为什么不可执行。处理：用 attended hopper run 手动跑 medium（daemon 不碰，但人可以）、给项目配 sensitive_keywords 微调、或 hopper link-project 注册项目。

hopper link-project 接入时按技术栈自动探测验证命令：Node 有 test 脚本→npm test、Python→pytest、Go→go test、Rust→cargo test、SwiftPM→swift build/test；多语言会累加所有命中栈。探测不到就写空验证并显式提示——此时 verification 是 not_run（不阻拦，但也不保证编译）。执行前会冻结当时的验证计划（runner 改测试脚本不影响本次闸门）。要补 / 改命令，编辑项目配置的 verification。

runner 在 .hopper/config.yml 的 runners: 段配置。Claude 默认用 ~/.claude 认证，通常无需额外配；Codex 建议显式配 home: ~/.codex——某些环境（如在另一个 agent 会话里）CODEX_HOME 会被指向临时目录，不配就取不到登录态。运行前先确认两者已登录（runner probe 只查命令是否在 PATH，不验证认证）。建议先用 hopper run 单任务试通，再上并发 / daemon。

不会。默认不 push、不 auto-merge、不改 main——这是确定性 guardrail。worktree 里还拦截了 git push。合并永远是你显式 hopper merge，且 merge 前再跑一次 smoke 验证。

不能。所有 Markdown / 外部内容（包括 GitHub issue 正文、禅道 Story 描述）都被当作不可信输入，会被标注，且无权放宽任何 guardrail。确定性闸门在 runner 结束后兜底，LLM 也不能降低安全规则、不能把风险调低。这是防 prompt 注入的硬设计。

因为「事件先于副作用」（先写 RunReserved 再建 worktree），崩溃后 hopper reconcile 能对账现场、释放 stale 锁、恢复或解释中断的 run。hopper doctor 给健康报告。没有「卡死说不清」的状态。

不会。secret / forbidden path（如 .env*、secrets/**）防护是确定性 guardrail——任务改动碰到就 blocked，不可被放宽。你也可以在项目配置里扩充 forbidden_paths。

usage / rate-limit 是硬闸门（不够就不调度）；USD 成本是软记账（run-level cost ledger）。hopper usage / hopper budget 查看。硬预算上限需要你显式开启；预算信封在烧到 70 / 85 / 100% 时分级告警，成本未知的 run 单列为 unknown、绝不折算为 0。注意 Hopper 自己的 meta LLM 调用也计入。

能。但受多重约束：同 repo 串行、跨 repo 可并发，再叠加 usage 闸门、预算、风险白名单（daemon 只 low risk）、依赖 DAG、全局并发上限。merge 永远串行。默认保守（claude 1 / codex 1）。想让同一 runner 真并发多任务：调高 global_max_concurrency、把该 runner 的 fallback_concurrency 设 ≥2（真机没有可信用量数据时按它算并发，不是 max_concurrency），并让这些任务落在不同 repo（同 repo 会被 repo 锁串行）。

诚实清单：daemon 是轮询而非文件监听；/hopper-drop slash 命令未实现（用 drop --stdin）；drop --dedupe、retry --verification-plan new、跳过人工 approve 的 auto-merge、自动 PR、Windows 完整支持等仍是蓝图。已落地的有：真实 5h/7d 用量读取（Claude OAuth 端点 / Codex session 快照；读不到时明说 unknown 并保守调度）+ per-run 成本账本、预算闸门与预算信封（70/85/100% 告警）、多 runner profile（exact pin / kind: 轮转 / round-robin，真机已验证多 session 并发）、写作辅助 new/lint、独立质检 hopper check、绑 127.0.0.1 的本地 Console GUI（Control Room / 决策收件箱 / 提 Bug 表单 / 任务操作）、Assisted-mode 断点卡、merge 队列、外部编排集成面（RunSettled / capabilities / --req-id 幂等键）、GitHub Issues 接入，以及禅道 Story 只读导入、手动回写、pull 建议同步。详见 llms-full 的「当前实现边界」。

能。Hopper 是 CLI，最稳的方式：cat needs.md | hopper drop --stdin --project X 投递 → hopper scan && hopper triage → hopper run next → 把 hopper review diff 和证据呈现给人类决策。注意：approve / merge 是人类的不可逆决策，AI 应止步于「准备好供 review」，不要替用户 approve / merge。

适合。几乎所有命令支持全局 --json（机器可消费），--debug、--vault <path> 也处处可用。状态可由 events.jsonl 投影读取，或 hopper status --json / hopper show <id> --json。schema 真相源是 zod，导出为 JSON Schema。

你会收到 Task Compiler 编译好的 prompt——含任务上下文、验收标准、guardrails、context manifest。你要返回结构化结果（outcome: completed / needs_review / failed …，加改动文件 + 测试结果）。注意：你自报的 outcome 不是最终状态——Hopper 会自跑冻结的验证计划和质量闸门复核，你改不了自己的成绩单。