# Hopper — 完整产品与使用手册（llms-full）

> 给 AI / LLM 的一站式完整内容：聚合官网首页、FAQ 与使用文档（docs）的核心，可一次读全。
> 站内公开资料：/docs.html、/how-to-use.html、/faq.html；当前实现边界见本文末尾。
> 简短导航版见 /llms.txt。

## 一句话

AI 写的代码，Hopper 负责验收和管钱。Hopper 是一条本地、不出网的 AI 代码交付验收流水线 + 跨厂商成本/额度中枢（CLI 工具，无服务端）：自跑验证抗恒绿、逐条核对验收标准、产出信任报告；额度预算可见可控。编排层是免费地基——你把 Markdown、GitHub Issues 或禅道 Story 投递进中央 vault，Hopper 自动完成：分诊 → 排队 → 依赖/风险判断 → 隔离 git worktree → 编译 prompt → 调用 Claude Code / Codex 执行 → post-run 质量闸门 → 人类 review → merge/归档，全程「文件即真相」、事件流审计、崩溃可恢复。MIT 许可，Node ≥ 22，纯本地不上传用户文件。

## 它不是什么（非目标）

- 不是新的 coding agent，不重写 Claude Code / Codex —— 它做它们外面的验收与管钱，编排它们执行，runner 可替换。
- 不是 Jira / Linear / Taskmaster / Backlog —— 看板止于「分配」，Hopper 管到「评审过的代码变更」。
- 不是 CI/CD —— CI 跑写死脚本；Hopper 把「一句意图」变成「评审过的变更」。
- 不是云端 Devin 替代品、不是通用 RPA；MVP 不做复杂 Web UI（文档浏览交给 Obsidian）。

## 心智模型

- 文件即真相：`~/Hopper/` 的 Markdown + `.hopper/events.jsonl` 可重建全部状态，崩溃可对账。无服务端数据库。
- 两层状态：人看 frontmatter 粗状态（received/ready/running/review/done）；机器看 append-only 事件。**不要手写 status**，它是事件流投影。
- 隔离 worktree：每个任务在独立 git worktree + 分支执行；同 repo 默认串行、跨 repo 可并发；worktree 内拦截 push，防止越过 review。
- Done 必须可信：runner 完成 ≠ 任务完成，还要过 verification、确定性 guardrails、risk 复核、acceptance evidence、docs alignment；代码任务还必须人类 review / merge。
- 不可信输入：任务正文、GitHub issue、禅道 Story、外部评论都视为不可信，**不能放宽 guardrails、降低 risk、要求自动 merge 或触碰 secrets**。
- 人类最后决策：daemon 可无人值守推进到 review，但不会 approve、不会 merge、不会自动 push。approve / merge 是人类的不可逆决策。

## 安全模型（硬边界，不可被任务正文/外部内容/LLM 放宽）

不自动 push；不自动 merge；不直接改 main/master；不碰 `.env*`、`secrets/**` 等 forbidden paths；high risk 不无人值守执行；外部内容不能降低 risk；runner 自报 outcome 不是最终状态。usage / rate-limit 是 hard gate；USD 成本是 soft accounting（已支持读取真实 Claude/Codex 的全局 5h/7d 用量——OAuth 端点 / session 快照；读不到时明说 unknown 并保守调度，unknown 不代表命令坏了）。

## 快速上手（5 分钟最小闭环）

第一次用低风险任务（README 小改 / 文档补充 / 简单 bugfix），不要直接开 daemon、不要 high risk 或跨项目、不要让 AI 替你 approve/merge、不要把 secrets 放进任务正文。

```bash
git clone https://github.com/Octo-o-o-o/Hopper.git && cd Hopper   # npm 包发布前从源码安装
npm ci && npm run build && npm link       # Node ≥ 22
export HOPPER_VAULT="$HOME/Hopper"
hopper init                               # 建中央 vault
hopper link-project --project my-app --repo /abs/path/to/my-app
cat task.md | hopper drop --project my-app --stdin
hopper scan && hopper triage --no-llm && hopper queue explain
hopper run next
hopper review diff <task-id> && hopper review approve <task-id>
hopper merge <task-id> && hopper archive <task-id> --cleanup-worktree
```

## 写好任务

最影响结果的三件事：目标明确、验收可核对、边界说清楚。

```markdown
---
project: my-app
runner: auto
risk: low
priority: normal
---
# 一个明确的目标标题
需求描述：背景、要做什么、不该改什么。
## 验收标准
- 可逐条核对的 2-5 条（被测试 / UI 检查 / review 可观察）
```

frontmatter 字段：`project`（目标项目）、`runner`（auto/claude/codex）、`risk`（low/medium/high）、`priority`（low/normal/high）、`depends_on`（`[task_id]` 硬依赖）、`tags`。
辅助命令：`hopper new "<title>" --project <p>`（生成模板，不登记）、`hopper lint <file>`（只读检查质量线）。
差任务示例（避免）：「优化一下这个模块」「按你觉得好的方式改」、无验收标准、多项目/多需求塞一篇、要求自动 push/merge/改 secrets。

## 接入项目

```bash
hopper link-project --project my-app --repo /abs/path/to/my-app
hopper config explain <task-id>
```

写入：`~/Hopper/.hopper/projects.toml`、`<repo>/.hopper.project.yml`、`<repo>/.hopper-inbox -> ~/Hopper/00-Inbox/my-app`。
验证命令探测（按技术栈）：Node `npm test`（仅当 package.json 有真实 test 脚本）、Python `pytest`、Go `go test ./...`、Rust `cargo test`、SwiftPM `swift build`/`swift test`。polyglot repo 累加命中栈；探测不到则 verification 为空、运行结果标 `not_run`（不阻断、但也不证明能编译）。

## 外部需求源（只是入口，不是真相源）

不要让 GitHub issue 或禅道 Story 直接驱动 execute / approve / merge；它们最多提供输入、回写和建议，状态仍由本地事件流决定；导入内容一律标记 `external_untrusted`。

GitHub Issues：
```bash
hopper github link --project my-app --repo owner/my-app --labels bug,regression
hopper github sync --project my-app [--dry-run]
hopper github status --project my-app
hopper github sync-back --task <task-id> [--dry-run]
```
命中 label 的 open issue 导入为 bug-list；`scan` 拆成可执行 child draft；修复后可手动 comment 回源 issue；不自动 close、不做实时双向同步。

禅道 Story：
```bash
hopper zentao configure --site <url> --product <id|name> --project <p>  # 幂等生成 .hopper/zentao.toml
hopper zentao doctor
hopper zentao import --product <id> | --story <id> [--dry-run]
hopper zentao attach --task <id> --story <id>   # 把原生任务关联到已有 story，之后可 sync-back
hopper zentao sync-back --task <id>          # 默认只预览
hopper zentao sync-back --task <id> --yes    # 发布到禅道
hopper zentao pull [--apply --yes]           # 只给 close/spec/assignedTo 建议
```
`configure` 幂等生成映射（免手写）；`import` 只读、按 `zentao://` 幂等；`attach` 把无 source_path 的原生任务关联到已有 story（写 StateStore + 外部 baseline + 审计事件 ZentaoAttached，使 sync-back/pull 可见，不创建 story）；`sync-back` 默认预览、`--yes` 才发布，默认回写 Story 评论，配置自定义字段时会 read-back 验证（只配一个字段会报错）；`pull` 只给建议、默认不静默改状态。

## 外部编排系统集成面

如果你有自己的编排/工单系统要驱动 Hopper，走这几个稳定接口，不要猜内部状态：

- `RunSettled` 终结事件：一次 run 的处理链结束信号（settle barrier）——消费方以它判定 run 已终结；SIGKILL 级崩溃场景经 `hopper reconcile` 对账终结。
- `hopper capabilities`：能力/版本握手，事件类型、任务状态、mutation 命令枚举自 schema 单源，`--json` 供机器；外部 bridge 启动断言用。
- `hopper project show <name>`：单项目配置解析后快照（缺省值补齐），dispatch 前 preflight 读口。
- `--req-id` 幂等键：同 req_id 重放返回首次结果、不重复执行（`drop`（单文件/stdin）、`review approve/request-changes/reject`、`cancel`、`unblock` 等支持）。
- `--origin` 审计标注 / `--receipt` 外部审批收据不透明存证回显（`review approve` 与 `merge`）：只进事件 payload 审计，不改变任何权限或闸门判定。
- `hopper run <task-id>`：定向执行触发口，闸门与 `run next` 完全一致（依赖 DAG / 风险白名单 / usage / budget / repo 锁），不是绕闸门的后门；不可执行时输出机器可读 skip reason，未执行时退出码 1。
- 状态文件：daemon 心跳 `.hopper/daemon-heartbeat.json`（每 tick 原子写 `{pid, ts, tick_seq, executed_total}`，ts 超阈值（建议 30s）即判 daemon 死）；vault 身份 `.hopper/vault.json`（`{vault_id, created_at}` 永不改写——「同路径换 vault」的 identity 信号）。

边界不变：外部系统拿到的与人类是同一套闸门，`--origin/--receipt` 是审计字段而非信任依据。

## 执行与并发

```bash
hopper queue explain          # 解释每个 ready 任务为何（不）可执行
hopper run next               # 执行恰好一个 ready 任务
hopper run <task-id>          # 定向执行指定 ready 任务（闸门与 run next 完全一致）
hopper run --parallel         # 当前 ready 集合执行一次
hopper drain --max 5 ; hopper drain stop
hopper daemon --max 10 ; hopper daemon pause ; hopper daemon resume   # 受控自动执行，只推进到 review
```
调度规则：同 repo 串行、跨 repo 并发、**merge 永远串行**；daemon 默认只自动跑 low risk；medium 可 attended run、high 需人类明确处理；usage unknown 时保守调度。
信任分级（自动化四档）：`observe`（只观察记录）→ `assisted`（计划步边界停下发断点卡，人放行才继续）→ `low_risk_autonomous`（仅 low risk 无人值守推进到 review）→ `full_controlled`（更大自动化面，但 S3 级敏感操作恒为人工）。
预算信封：给一段时间的开销设信封，烧到 70/85/100% 分级告警；成本未知的 run 单列 `unknown`、绝不折算为 0；叠加在 usage 硬闸门与 per-run 成本账本之上。
runner：可替换执行后端 adapter（Claude / Codex / 测试用 fake）；多 profile 支持 exact pin、`kind:` 轮转、round-robin、per-profile slots。真实接入前：确认命令在 PATH、Claude/Codex 已登录、Codex 显式设 `home: ~/.codex`、先跑低风险任务人工核对四类证据再扩大。

多 runner profile 配置（`~/.hopper/config.yml`，两个 Claude 账号 + 一个 Codex）：
```yaml
runners:
  claude:            # 默认 Claude 账号
    kind: claude
    home: "~/.claude"
    command: claude
  claude-work:       # 第二个 Claude（不同登录态）
    kind: claude
    home: "~/.claude-work"
    command: claude
  codex:
    kind: codex
    home: "~/.codex"
    command: codex
```
任务 frontmatter 里 `runner: auto`（自动选）/ `runner: kind:claude`（同类轮转）/ `runner: claude-work`（精确 pin）。`hopper runner detect` 扫 `~/.claude* ~/.codex*` 生成建议配置。

## Review / Merge（人类闸门）

```bash
hopper review list ; hopper review show <id> ; hopper review diff <id>
hopper review patch <id> --out /tmp/h.patch ; hopper review open <id>
hopper review approve <id> [--waive <kind:target> --reason "..."]
hopper review request-changes <id> --message "..." ; hopper review reject <id> --message "..."
hopper retry <id> [--runner codex] [--message "..."] [--keep-worktree]
hopper merge <id> ; hopper archive <id> --cleanup-worktree
```
合并前至少看：diff 只改预期文件、verification 是否运行且失败可解释、acceptance 逐条有证据、docs alignment 文档义务、risk 是否被 post-run 升级、是否触碰 forbidden paths/secrets、waiver 必须有理由。
merge 行为：检查 approved/verification/acceptance/docs/risk，真正合并前再跑 smoke；冲突进入 conflict 状态并保留现场；`merge_policy=pr_only` 输出手动 PR handoff，不自动建 PR。
断点协作（Assisted-mode）：runner 在计划步边界停下发决策卡，任务原地等人；`hopper breakpoint list` 看卡、`breakpoint release <decisionId>` 放行（`--note` 加注 / 可否决）、`breakpoint resume <decisionId>` 让同一个 run 原地续跑；Console 决策收件箱可处理同一批卡。
merge 队列（可选启用）：approve 即入队，queue worker 是唯一 canonical 落地 writer，逐个串行落地，generation fencing 防旧一代运行结果误落地；`hopper merge-queue list/run/release` 运维。不是 auto-merge——approve 仍是人做的不可逆决策。

## 安全与恢复

```bash
hopper usage ; hopper budget
hopper reconcile [--dry-run] ; hopper doctor [privacy]
hopper cancel <id> ; hopper unblock <id>
```
事件先于副作用：先写 `RunReserved` 再创建 worktree。崩溃后 `reconcile` 可解释 stale lock、orphan worktree、缺失 RunnerFinished、frontmatter/event 冲突，并尽量安全修复。

## 本地控制台 Console（可选 GUI，绑 127.0.0.1）

```bash
hopper console [--no-open] [--port 8787]
```
CLI 的本地网页皮肤，读同一份文件真相、写同一条 mutation 队列，不接管状态机，关掉它 CLI 照常工作。能力：首跑向导（init/link/选 runner）、Control Room 一屏六区（活动 run/待决策/预算燃烧/风险/近期结果/运营指标）、决策收件箱（风险审批/review/blocked/failed 聚合，决议绑定 digest/revision 防对着旧状态拍板）、Review 控制台（diff/verification/acceptance/docs/risk）、任务详情操作（failed→Retry / blocked→Unblock / Archive）、提任务/提 Bug 双 tab（自由 Markdown，或结构化 Bug 表单生成规范 Markdown + 投递前确定性 triage 预判 chip）、禅道导入预览、草稿防丢（编辑中不吞输入 + localStorage 兜底）、界面中英双语切换、daemon pause/resume。边界：不代跑任务、不替你 approve/merge；执行仍由 run/drain/daemon；全部 API 要求随机 Bearer token，写操作再加 Origin 校验。

## CLI 命令全集（按阶段）

- 初始化 / 写作：`init` `setup` `link-project` `git init` `new` `lint`
- 投递 / 外部：`drop` `scan` `triage` `github link|sync|status|sync-back` `zentao configure|doctor|import|attach|sync-back|pull`
- 队列 / 执行：`dep add|remove|accept|graph|explain|ready|suggest` `queue explain` `run next` `run <task-id>` `run --parallel` `drain` `daemon pause|resume`
- 状态 / 审查：`status` `show` `logs` `usage` `budget` `review list|show|diff|patch|open|approve|request-changes|reject` `retry` `merge` `archive`
- 独立质检：`check [--base <ref>] [--staged] [--criteria <file|->] [--ci]`（对任意 git repo 的 diff 跑四道闸门，退出码 0-4，报告三件套 md/json/html）
- 恢复 / 运维：`reconcile` `doctor [privacy]` `cancel` `unblock` `move` `reassign`
- Schema / Runner / Console：`schema validate|export` `runner list|show|probe|detect` `console` `config explain`
- 集成握手：`capabilities` `project show <name>`
- 平台运维：`cmd <verb> <target>`（统一命令服务：durable/幂等/五终态）`stop [--release|--status]`（急停）`breakpoint list|release|resume`（Assisted-mode 断点卡）`merge-queue list|run|release`（merge 队列）`credentials resume`（凭证暂停一键恢复）`intake list|resolve`（提案决议）`attest request|confirm|reject|list`（真人裁决签名回执）`project contract lint|propose|seal|refresh` `project gate <task-id>` `project coverage` `project enroll …`（交付合同与覆盖链）`converge <task-id>`（C0–C10 收敛管线）`release <task-id>`（轻量发布：tag + 机械 notes）

全局开关：`--vault <path>`（覆盖 `HOPPER_VAULT` 或默认 `~/Hopper`）、`--json`（机器可读，适合 AI / 脚本）、`--debug`、`--no-llm`（全局禁用一切 meta_runner LLM 调用）。

## 常见排障

- 任务卡在 ready：`hopper queue explain` / `hopper status --json`。常见原因：risk 非 low、项目未 link、依赖未完成、runner 不可用、usage/budget 不足、同 repo 已有任务在跑。
- verification 是 not_run：接入时没探测到验证命令或为空；编辑 `projects.toml` 的 `verification` 再重跑。
- probe 通过但真实运行失败：probe 只证明命令在 PATH、不证明已登录；检查 Claude/Codex 登录，Codex 显式设 `home: ~/.codex`。
- merge 被挡：`hopper review show <id>` / `hopper docs show <id>` / `hopper logs <id>`。原因：未 approve、verification failed、acceptance unsupported、docs obligation 未处理、risk 升级、merge conflict。
- 禅道回写没生效：默认无 `--yes` 只预览；自定义字段需禅道后台已创建并通过 read-back 验证，只配一个字段会报错。
- 状态看起来冲突：`hopper reconcile --dry-run` / `hopper doctor`；不要手改 frontmatter status（事件流是机器真相，frontmatter 是投影）。

## FAQ 精要

- 与 Claude Code / Codex 的区别：它们写代码，Hopper 在外面验收和管钱（排队/隔离/质检/review/merge 是免费地基），runner 可替换。（同理适用于 Cursor 等编辑器内 AI）
- 与 Jira / CI 的区别：看板止于分配、CI 跑写死脚本；Hopper 把意图变成评审过的代码变更。
- 数据安全：纯本地 CLI、无服务端、不上传用户文件；真正出网的只有 Claude/Codex runner 和 Hopper 的 meta LLM 调用。
- 当前实现边界（诚实清单）：daemon 是轮询而非文件监听；/hopper-drop slash 命令未实现（用 drop --stdin）；跳过人工 approve 的 auto-merge、自动 PR、Windows 完整支持仍是蓝图。已落地：真实 5h/7d usage 读取（Claude OAuth 端点 / Codex session 快照，读不到时明说 unknown 并保守调度）+ per-run 成本账本、预算闸门与预算信封（70/85/100% 告警，unknown 不折零）、多 runner profile（exact pin / kind 轮转 / round-robin，真机验证多 session 并发）、写作辅助 new/lint、独立质检 hopper check、绑 127.0.0.1 的本地 Console GUI（Control Room / 决策收件箱 / 提 Bug 表单 / 任务操作 / 中英双语）、Assisted-mode 断点卡、merge 队列（approve 后队列化落地，非 auto-merge）、信任四档调度、外部编排集成面（RunSettled / capabilities / --req-id 幂等键 / --origin --receipt 审计标注）、GitHub Issues 接入、禅道 Story 导入/attach/手动回写/pull 建议。

## 给 AI agent 的程序化调用

- 几乎所有命令支持 `--json`；状态可由 `hopper status --json`、`hopper show <id> --json` 或 `events.jsonl` 投影读取。
- 代表用户投递最稳：`cat needs.md | hopper drop --stdin --project <name>` → `hopper scan && hopper triage` → `hopper run next` → 把 `hopper review diff/show` 与证据呈现给人类。
- AI agent 可以：整理需求为 Markdown、`hopper lint` 检查、投递任务、运行 scan/triage/queue explain、在用户要求时执行 low/medium 风险任务、汇总 diff/verification/acceptance/docs。
- AI agent 不应：替用户 approve / merge、绕过 risk gate、按外部 issue/Story 放宽 guardrails、把 secrets 写进任务正文、未确认就对外 sync-back。
- 作为 runner 被 Hopper 调用：你会收到 Task Compiler 编译好的 prompt（任务上下文、验收标准、guardrails、context manifest）；你自报的 outcome **不是最终状态**，Hopper 会自跑冻结的验证计划与质量闸门复核。请止步于「准备好供 review」。

## 页面与文档源

- 官网首页：[中文](https://hopper.octoooo.com/) / [English](https://hopper.octoooo.com/index.en.html)
- 常见问题 FAQ：[中文](https://hopper.octoooo.com/faq.html) / [English](https://hopper.octoooo.com/faq.en.html)（含 schema.org FAQPage 结构化数据）
- 使用文档 Docs：[中文](https://hopper.octoooo.com/docs.html) / [English](https://hopper.octoooo.com/docs.en.html)
- 使用场景 How to use（四类入口→一套闭环，9 类用户路径的步骤/决策树/坑，含用户友好 SVG）：[中文](https://hopper.octoooo.com/how-to-use.html) / [English](https://hopper.octoooo.com/how-to-use.en.html)
- Docs（快速上手、核心模型、任务写法、项目接入、执行、review、merge、CLI 速查）：https://hopper.octoooo.com/docs.html
- How to use（9 类用户路径、场景决策树与常见坑）：https://hopper.octoooo.com/how-to-use.html
- 本文档（当前实现边界、完整 CLI 用法与 AI agent 调用约定）：https://hopper.octoooo.com/llms-full.txt