选对你的场景，
照着走完一次闭环。
不论需求来自手写笔记 / Obsidian、Claude Code / Codex 会话、GitHub Issues 还是 禅道 Story——四类入口最终都汇成 vault 里的 Markdown，由同一套 drop → scan → triage 闭环处理。这页给你 9 类用户路径的「最短可行步骤 + 坑」。
需求从哪来不重要，
都汇成一份 Markdown。
Hopper 不在乎你的需求最初长什么样。手写灵感、Obsidian 笔记、和 Claude Code / Codex 聊出来的方案、GitHub Issue、禅道 Story——投进中央 vault（默认 ~/Hopper）后，都成为同一种「文件驱动」的任务，走同一条流水线。
FIG.01 — 四类入口汇成 vault Markdown，走同一套 drop → scan → triage → ready
任务进 vault 后，
9 个场景走的是同一段。
记住这套闭环，下面 9 个场景就只剩「前半段差异」（vault 怎么来、project 怎么接、任务从哪进）。后半段一律一样：
# 进 vault 后，任何场景都一样 hopper scan # 登记 + 确定性分诊 hopper triage --no-llm # （可选）重跑分诊，不调 LLM hopper status # 看队列/状态 hopper queue explain # （可选）解释各 ready 任务为何（未）被选中 hopper run next # 执行一个 ready 任务（或 hopper drain / daemon） hopper review list hopper review show <id> # 看执行结果与证据 hopper review diff <id> # 看代码改动 hopper review approve <id> hopper merge <id> # 代码任务必须 merge 才算 done；非代码任务 approve 后 archive 即 done
一次性配置（每 vault/项目一次）
- hopper setup 建 vault（首跑）
- hopper link-project 接入已存在的 repo
- 接 ZenTao：hopper zentao configure 生成映射 → doctor 校验
日常重复（每轮新需求）
- 纯 Hopper：new/drop → scan → run → review → merge
- +ZenTao：zentao import → … → sync-back --yes
- 拉远端变化：zentao pull [--apply --yes]
两三个问题，
定位到你的那一类。
「新用户 / 老用户」的本质区别 = 一次性配置是否已完成；「纯 Hopper / +ZenTao」的区别 = 需求真相源在不在禅道。顺着下图走到一个编号，再翻到对应场景卡片。
FIG.02 — 场景决策树：从「需求真相源 / vault 是否存在 / 有没有 repo」路由到 9 类路径
# 谁 vault repo ZenTao 任务入口 能 sync-back?
1 纯 Hopper 新用户·无项目 新建 无→可后建 — drop→_unassigned —
2 纯 Hopper 新用户·有老 repo 新建 已有 — drop / Inbox —
3 纯 Hopper 老用户 已有 已接 — new / drop —
4 +ZenTao 新·从 Hopper 起 新建 新建 后接 new 需先 attach
5 +ZenTao 新·从 ZenTao 起·新项目 新建 已有/新建 先配 zentao import ✅
6 +ZenTao 新·从 ZenTao 导老项目 新建 老 repo 先配 zentao import ✅
7 +ZenTao 新·从 Hopper 导老项目 新建 老 repo 后接 drop / Inbox 需先 attach
8 +ZenTao 老·在 Hopper 项目里 已有 已接 已配 new/drop(+import) import / attach 后
9 +ZenTao 老·在 ZenTao 项目里 已有 已接 已配 zentao import/pull ✅场景 1–3：
只用 Hopper 管生产线。
场景 1 · 新用户，之前没有项目
适用：手上没有现成 repo，先想用 Hopper 管想法 / 需求 / 方案；代码项目可能从零起。
hopper setup # 建 vault；问到 link repo 可先答否 # A) 只收集想法：投到 _unassigned 先沉淀 cat idea.md | hopper drop --stdin hopper scan && hopper triage --no-llm # B) 要跑代码：先有 repo → 注册 → 建任务 mkdir -p ~/Work/my-app && cd ~/Work/my-app && git init hopper link-project --project my-app --repo "$PWD" hopper new "初始化项目骨架" --project my-app
坑：没有 repo 时只能收集文档，worktree / verification / merge 都需已注册 repo；Hopper 不提供 project create / 代码脚手架，git init 是你自己的事。
场景 2 · 新用户，有老项目要导入
适用：已有一个本地代码 repo，从没用过 Hopper。
hopper setup --link-repo /abs/path/to/old-repo --project old-repo # 等价：hopper init → hopper link-project --project old-repo --repo … hopper drop --project old-repo a.md b.md # 多个文件；批量可用 shell 通配：hopper drop --project old-repo *.md hopper scan && hopper triage --no-llm
坑：没有「导入整个旧 repo 历史 issue 并自动拆分」的命令；老代码靠 link-project 接入，老需求靠 drop / Inbox 进。投递总是去重（内容相同 → duplicate_ignored）。
场景 3 · 老用户，在之前的项目里继续用
适用：~/Hopper 与 project / 任务历史都在，跳过全部一次性配置。
hopper status hopper new "修复登录错误提示" --project old-project hopper scan && hopper drain hopper review approve <id> && hopper merge <id> # 健康检查：投影与事件不一致时优先跑 hopper reconcile --dry-run hopper doctor
坑：别手改 .hopper/events.jsonl / state/ / locks/；Obsidian 改正文 OK（受保护投影），但 frontmatter 的 status 由事件流投影，不要手写。
场景 4–7：
第一次把 Hopper 接上禅道。
映射文件用 hopper zentao configure 幂等生成（免手写）；ZenTao 是只读上游，唯一写回是 sync-back。前置：装并登录 zentao-cli（账号密码走它自己的 login，绝不传给 Hopper）。
场景 4 · 从 Hopper 启动新项目（ZenTao 以后再接）
适用：想先在 Hopper 里写需求 / 执行，ZenTao 以后再接。
hopper setup mkdir -p ~/Work/my-app && cd ~/Work/my-app && git init hopper link-project --project my-app --repo "$PWD" hopper new "第一个功能任务" --project my-app # 之后接 ZenTao（前提：ZenTao 侧已有 product/story） hopper zentao configure --site https://zentao.example.com --product 1 --project my-app hopper zentao doctor
坑（核心限制）：Hopper 不能从原生任务创建 ZenTao story。原生任务默认无 zentao:// source_path，要回写得先 hopper zentao attach --task <id> --story <id> 关联到已有 story。若 ZenTao 必须当真相源、story 该由它先建 → 直接走场景 5 更顺。
场景 5 · 从 ZenTao 启动新项目（最顺）
适用：ZenTao 管产品 / 版本 / story，Hopper 当执行生产线。任务自带 zentao:// source_path，能完整闭环到 sync-back。
hopper setup --link-repo /abs/path/to/repo --project my-app hopper zentao configure --site https://zentao.example.com --product 1 --project my-app hopper zentao doctor hopper zentao import --product 1 --dry-run # 预览 Markdown + 预测 triage hopper zentao import --product 1 && hopper scan # … 通用闭环 run → review → merge … hopper zentao sync-back --task <id> # 无 --yes 只预览 hopper zentao sync-back --task <id> --yes # 确认后发布（默认贴评论）
坑：import 后任务是 received（不是 ready），必须走分诊；正文标 external_untrusted，不放宽 guardrails。doctor 要求映射目标 project 已注册，故 link-project/configure 要先于 import。
场景 6 · 从 ZenTao 导入老项目
适用：ZenTao 有老 product / story，本地也有（或准备接）对应老 repo。
hopper init hopper link-project --project legacy-app --repo /abs/path/to/legacy-repo hopper zentao configure --site https://zentao.example.com --product 1 --project legacy-app hopper zentao import --product 1 --release 2026-Q3 --dry-run # 看阻塞项/缺验收 hopper zentao import --product 1 --release 2026-Q3 hopper scan && hopper triage --no-llm
坑：当前只导 story（task/bug/用例/计划页不在范围）；老 story 常缺验收标准，dry-run 会给 warning，需人工补齐。后续远端变化用 hopper zentao pull。
场景 7 · 从 Hopper 导入老项目（未来可能接 ZenTao）
适用：已有老 repo + 老 Markdown 需求，先用 Hopper 接管。
hopper setup --link-repo /abs/path/to/legacy-repo --project legacy-app hopper drop --project legacy-app old-1.md old-2.md # 多文件投递 hopper scan && hopper triage --no-llm # 若 ZenTao 已有对应 story，可关联后回写： hopper zentao attach --task <id> --story 109
坑（与场景 4 同源）：没有「把 Hopper 老任务批量建成 ZenTao story」的命令；attach 只能关联已存在的 story。若团队要求 ZenTao 是真相源，老需求最好先整理进 ZenTao story，再按场景 6 导入。
场景 8–9：
稳态日常与远端同步。
场景 8 · 在之前的 Hopper 项目里继续用
适用：vault / project 已在，后来接了（或想接）ZenTao。
hopper zentao doctor hopper zentao import --product 1 --dry-run # 看新增/重复/跳过 hopper zentao import --product 1 && hopper scan hopper drain hopper review approve <id> && hopper merge <id> hopper zentao sync-back --task <id> --yes hopper zentao pull && hopper zentao pull --apply --yes # 同步远端 close/spec
坑：只有 import 来的任务有 zentao:// source_path 可直接 sync-back；原生老任务需先 zentao attach 到已有 story。重 import 同源 story 不会静默覆盖在途任务（只覆盖 received/draft）。
场景 9 · 在之前的 ZenTao 项目里继续用
适用：ZenTao 是团队既有入口，已跑过 Hopper+ZenTao，稳态日常。
hopper zentao import --product 1 --release 2026-Q3 --dry-run hopper zentao import --product 1 --release 2026-Q3 # 或只处理一条：hopper zentao import --story 109 hopper scan && hopper triage --no-llm # … run → review → merge … 然后回写 hopper zentao sync-back --task <id> --yes hopper zentao pull # 只看建议 hopper zentao pull --apply --yes # close→archive；spec 变更且本地 done→建 follow-up
坑：无后台轮询、全手动；assignedTo / 远端 status 变化只展示不自动改；spec 变更只在本地任务已 done 后才报为可应用建议。
接下来读什么。
操作与命令
- Docs — 初始化、接入、执行、review、merge、CLI 速查
- FAQ — 常见疑问与边界
- llms-full.txt — 完整公开手册与实现边界
设计与场景
- 9 类用户路径 — 本页的场景索引与决策树
- 公开资料入口 — 权威设计口径和站内资料
- llms-full.txt — 给 AI 的完整上下文