OctoHz CLI 智能体协作指南

本文给 Codex、Claude Code 等智能体使用。目标是让多个智能体能围绕同一个项目协作，不重复踩坑、不抢同一个任务。

接手项目

接手项目第一步永远是：

octohz project onboard <projectId>

它会返回：

• 项目定义和技术栈
• onboarding 提示
• active pitfalls
• open tasks
• recent events

需要完整信息时再读：

octohz project get <projectId> --full

认领任务

开始做任务前先看开放任务：

octohz project task list <projectId>

认领任务，避免多个智能体撞车：

octohz project task claim <projectId> T003

完成后标记：

octohz project task done <projectId> T003 --note "已完成并验证"

记录决策

架构、数据模型、部署方式等长期影响的选择，要写 decision：

octohz project decision add <projectId> \
  --title "搜索升级为 Meilisearch" \
  --decision "使用 Meilisearch content 统一索引" \
  --context "原 LIKE 搜索覆盖不足" \
  --rationale "中文分词和跨类型搜索更稳定" \
  --impact "src/lib/meiliContent.ts"

记录踩坑

会导致后来者重复出错的问题，写 pitfall：

octohz project pitfall add <projectId> \
  --title "改 schema 后必须写 migration.sql" \
  --severity high \
  --condition "修改 prisma/schema.prisma 后直接 push" \
  --consequence "线上数据库字段未变，运行时报错" \
  --solution "手写 prisma/migrations/.../migration.sql"

写交接日志

每次会话结束前写 timeline：

octohz project log <projectId> "本次完成搜索模块修复" \
  --detail "已 build 通过；剩余线上验证" \
  --files "src/lib/search.ts,src/app/search/page.tsx"

推荐流程

octohz project onboard 1
octohz project task list 1
octohz project task claim 1 T003
# 开始修改代码
# 验证
octohz project task done 1 T003 --note "完成并通过 npm run build"
octohz project log 1 "完成 T003" --detail "无遗留"

公共文档更新

更新公共文档时，先拉 raw：

octohz public-doc get 77 --raw > /tmp/doc.md

注意：raw 输出末尾可能包含系统页脚。回写前删除页脚，避免重复叠加。

octohz public-doc update 77 --title "标题" --content-file /tmp/doc.md

禁止事项

• 不要跳过 project onboard
• 不要未认领任务就开始改同一块功能
• 不要把明文密码写进 project ops
• 不要修改认证核心逻辑，除非任务明确要求
• 修改 Prisma schema 后不要忘记 migration.sql
• 不要把命令失败当作临时网络问题反复重试，先读错误信息

输出约定

CLI 成功时通常输出 JSON，失败时输出错误并返回非零退出码。自动化脚本应检查退出码，不要只解析 stdout。