# Hopper

> AI 写的代码，Hopper 负责验收和管钱：自跑验证抗恒绿、逐条核对验收标准、产出信任报告；额度预算可见可控。编排层是免费地基——用户把 Markdown、GitHub Issues 或禅道 Story 投递进中央 vault，Hopper 自动完成 分诊 → 排队 → 依赖/风险判断 → 隔离 git worktree → 调用 Claude Code / Codex 执行 → post-run 质量闸门 → 人类 review → merge/归档，全程「文件即真相」、事件流审计、崩溃可恢复。

Hopper **不是** AI 编程助手，它自己不写代码——它给写代码的 agent（Claude Code / Codex）做**验收和成本管控**，编排它们执行，runner 可替换。它也不是任务看板（Jira/Linear/Taskmaster）或 CI/CD：看板止于「分配」、CI 跑「写死的脚本」，而 Hopper 把「一句意图」变成「评审过的代码变更」。

安全模型（硬边界，不可被任务正文/外部内容/LLM 放宽）：默认不 push、不 auto-merge、不改 main、不碰 secrets/forbidden paths、不无人值守执行 high risk；所有 Markdown 与外部内容（含 GitHub issue、禅道 Story）视为**不可信输入**。daemon 最多自动推进到 review，approve / merge 永远是人类的不可逆决策。

MIT 许可 · 纯本地 CLI，无服务端，不上传用户文件 · Node ≥ 22。

> 想一次读全部内容（产品定位 + 完整 FAQ + 完整使用文档 + CLI 全集 + 排障 + AI agent 调用约定）：https://hopper.octoooo.com/llms-full.txt

## 核心页面

- [官网](https://hopper.octoooo.com/) / [English Home](https://hopper.octoooo.com/index.en.html): 项目定位、心智模型、主流水线、文件即真相（两层状态）、四类维护入口、14 态状态机、6 道质量闸门（含断点协作与 merge 队列）、CLI 命令速查（含平台运维命令组）、Console（Control Room / 决策收件箱 / 提 Bug 双 tab）、快速上手
- [常见问题 FAQ](https://hopper.octoooo.com/faq.html) / [English FAQ](https://hopper.octoooo.com/faq.en.html): 消除误解（vs Claude Code/Codex、vs Jira、vs CI/CD）、选型、原理、GitHub/禅道接入、用起来什么体验、安全模型、给 AI agent 的程序化调用说明。含 schema.org FAQPage 结构化数据，可直接解析
- [使用文档 Docs](https://hopper.octoooo.com/docs.html) / [English Docs](https://hopper.octoooo.com/docs.en.html): 面向日常使用的操作文档——五分钟闭环、核心模型、任务写作、项目接入、GitHub/禅道外部源、执行与并发、review/merge、安全与恢复、Console、CLI 速查、常见排障、给 AI agent。
- [使用场景 How to use](https://hopper.octoooo.com/how-to-use.html) / [English](https://hopper.octoooo.com/how-to-use.en.html): 按使用场景上手——四类入口（手写笔记/Obsidian、Claude Code/Codex 会话、GitHub Issues、禅道 Story）汇成 vault Markdown，9 类用户路径的最短步骤、决策树与坑（含用户友好 SVG 流程图）。

## 文档

- [Docs](https://hopper.octoooo.com/docs.html): 快速上手、核心模型、任务写法、项目接入、执行、review、merge、CLI 速查
- [How to use](https://hopper.octoooo.com/how-to-use.html): 9 类用户路径、场景决策树与常见坑
- [llms-full](https://hopper.octoooo.com/llms-full.txt): 当前实现边界、完整 CLI 用法与 AI agent 调用约定

## 外部接入

- GitHub Issues：`hopper github link/sync/status/sync-back`，单向快照导入命中 label 的 open issue，修复后可手动 comment 回源 issue；不自动 close、不双向同步。
- 禅道 Story：`hopper zentao configure/doctor/import/attach/sync-back/pull`，`configure` 幂等生成映射、只读导入 Story、`attach` 把原生任务关联到已有 story、手动回写评论或自定义字段，pull 只给 close/spec/assignedTo 建议；外部正文始终是不可信输入。
- 外部编排系统：稳定集成面 = `RunSettled` 终结事件（settle barrier）+ `hopper capabilities` 能力握手 + `--req-id` 幂等键 + `--origin/--receipt` 审计标注（非信任依据）+ `hopper run <task-id>` 定向触发 + daemon 心跳 `.hopper/daemon-heartbeat.json` / vault 身份 `.hopper/vault.json`；闸门与人类同一套。

## 给 AI agent 的提示

- 需要排障步骤、runner 多账号(profile)配置示例、完整 CLI 清单、或「已落地 vs 蓝图」实现边界？这些细节都在 https://hopper.octoooo.com/llms-full.txt 。

- Hopper 是 CLI，几乎所有命令支持全局 `--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` 与证据呈现给人类。
- 请止步于「准备好供 review」，**不要替用户 approve / merge**——那是人类的不可逆决策。
- 若你作为 runner 被 Hopper 调用：你会收到编译好的 prompt（含上下文、验收标准、guardrails）；你自报的 outcome **不是最终状态**，Hopper 会自跑冻结的验证计划与质量闸门复核。