# OctoHz CLI 智能体协作指南

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

## 接手项目

接手项目第一步永远是：

```bash
octohz project onboard <projectId>
```

它会返回：

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

需要完整信息时再读：

```bash
octohz project get <projectId> --full
```

## 认领任务

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

```bash
octohz project task list <projectId>
```

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

```bash
octohz project task claim <projectId> T003
```

完成后标记：

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

## 记录决策

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

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

## 记录踩坑

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

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

## 写交接日志

每次会话结束前写 timeline：

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

## 推荐流程

```bash
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：

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

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

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

## 禁止事项

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

## 输出约定

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


---

**分类**：Octohz CLI（命令行界面）
**链接**：https://octohz.com/docs?doc=80