多 Agent 协作刷新 README 的最佳实践

文档版本：v1.0
更新时间：2026-06-19
作者：Kimi CLI（基于 madao 真实试点记录整理）
关联事项：GitCode Issue #2、Multica TES-7

背景

为什么要用多 Agent 协作刷新 README？

README 是仓库的「门面」，但在实际项目中经常面临以下问题：

• 定位模糊：一句话描述说不清楚项目到底解决什么问题。
• 结构残缺：缺少架构上下文、进展时间线、仓库结构说明。
• 原则空洞：只写口号，没有反面案例和验收标准。
• 参与入口固化：把临时入口写死，后续入口迁移时 README 过期。

传统做法通常由一个人（或一个 Agent）直接修改 README，存在两个问题：

1. 缺少 review：写作者视角单一，容易漏掉读者真正关心的信息。
2. 产物不可追踪：改动可能留在本地或 Agent 工作区，没有真正进入代码仓库，也没有和原始 Issue 形成闭环。

多 Agent 协作的核心价值在于：

• 分工明确：一个 Agent 负责编写，一个 Agent 负责 Review，人在关键节点确认。
• 质量门禁：Review Agent 从可复现性、完整性、准确性角度把关。
• 全程可追踪：从 GitCode Issue → Multica 任务 → Git commit → GitCode 评论闭环，所有动作都有记录。

架构图

角色分工

前置条件

• 已安装并配置 码道 CLI（华为云代码 Agent，直接面向开发者）
• 已安装并登录 multica CLI。
• 已配置 Kimi Code CLI、Claude CLI 等 Agent runtime。
• 已配置 GitCode 个人访问令牌（PAT），用于 API 评论（可选，可人工替代）。
• 目标仓库 madao 已克隆到本地，例如 /Users/ming/madao。
• 仓库 remote 已指向 GitCode：https://gitcode.com/lming112/madao.git。

操作步骤

步骤 1：在 GitCode 创建 Issue，写清需求

目标：把「刷新 README」拆成可验收的具体任务。

1.1 需求描述应包含

1. 背景：为什么要改 README，当前存在什么问题。
2. 具体改动点：逐条列出必须完成的内容，例如：
   • 明确仓库定位，解决「定位不鲜明」问题。
   • 补充架构分层与选型理由。
   • 增加试点进展时间线与里程碑。
   • 完善仓库结构说明。
   • 为每条原则补充反面案例。
3. 交付要求：
   • 文件路径。
   • commit message 格式。
   • 必须 push 到 origin main。
   • 必须在原 Issue 评论确认。
4. 操作路径：明确告诉 Agent 在 /Users/ming/madao 直接操作，不要留在 Multica workdir。

1.2 示例 Issue 内容

## 背景
当前 README 定位不鲜明、架构缺上下文、进展缺时间线、仓库结构偏空、原则不够具体。

## 必须完成的改动
1. 用一句话清晰描述仓库定位与解决的问题。
2. 架构分层表增加「为什么选它」列。
3. P0/P1 增加起始日期、里程碑、验收标准。
4. 仓库结构说明补齐各目录职责。
5. 每条原则补充反面案例。

## 交付要求
- 修改 `/Users/ming/madao/README.md`。
- commit message: `docs: refresh README with clear positioning and details`。
- push 到 origin main。
- 在本 Issue 评论确认完成。

步骤 2：在 Multica 创建任务并分配给执行 Agent

目标：把 GitCode Issue 转成可跟踪的 Multica 任务。

# 推荐把描述写入文件，避免 shell 转义问题
cat > /tmp/issue_desc.md << 'EOF'
## 背景
...
## 必须完成的改动
...
## 交付要求
- 修改 /Users/ming/madao/README.md
- commit: docs: refresh README with clear positioning and details
- push 到 origin main
- 在 GitCode Issue #1 评论确认
EOF

multica issue create \
  --title "刷新 README，更清晰地描述仓库定位" \
  --description-file /tmp/issue_desc.md \
  --assignee "Kimi CLI" \
  --status todo

说明：--status todo 会立即触发 Agent 执行；如果是串行任务，后续步骤可设为 backlog。

步骤 3：执行 Agent 读取上下文并完成作业

目标：让 Agent 在正确的路径产出正确结果。

执行 Agent（如 Kimi CLI）被触发后，会收到任务描述。为了提升输出质量，任务描述中应明确：

• 操作路径（例如 /Users/ming/madao）。
• 交付文件路径。
• commit message 格式。
• 是否需要返回 GitCode Issue 评论。

Agent 执行示意：

cd /Users/ming/madao
# 1. 读取原始 README 和实操记录
cat README.md
cat pilots/multica-readme-best-practice-20260619/实操记录.md

# 2. 按模板修改 README
# ... 编辑 README.md ...

# 3. 提交并推送
git add README.md
git commit -m "docs: refresh README with clear positioning and details"
git push origin main

踩坑预警：如果任务描述没有指定操作路径，Agent 可能只在 Multica workdir 中修改，导致原始仓库没有变化。见下文「踩坑记录」。

步骤 4：创建 Review 任务

目标：由另一个 Agent 对产物进行独立 Review。

multica issue create \
  --title "Review README 刷新改动" \
  --description-file /tmp/review_desc.md \
  --assignee "Codex" \
  --parent <执行任务的 issue-id>

Review 描述应指定检查点：

• 是否满足 Issue 中列出的所有改动点。
• 可复现性：步骤是否清晰、命令是否可直接运行。
• 准确性：踩坑记录是否与真实操作一致。
• 交付物是否已正确 push。

步骤 5：根据 Review 修订并定稿

目标：把 Review 意见合并到最终产物。

1. 读取 Review 任务的评论或状态。
2. 在原始仓库中修改对应文件。
3. 重新 commit / push。
4. 在 Multica 中将执行 Issue 状态更新为 in_review 或 done。

multica issue status <issue-id> in_review
# 修订后
multica issue status <issue-id> done

步骤 6：GitCode 闭环

目标：让 GitCode Issue 知道任务已完成。

6.1 在 GitCode Issue 下评论确认

如果已配置 GitCode PAT，可通过 API 评论：

TOKEN="your_gitcode_pat"
ISSUE_NUMBER=1
REPO="lming112/madao"

curl -X POST "https://gitcode.com/api/v5/repos/${REPO}/issues/${ISSUE_NUMBER}/comments?access_token=${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "README 刷新已完成，commit: b492ad4，改动已 push 到 origin main。"
  }'

如果没有 PAT，可手动在网页端评论，评论内容应包含：

• 完成状态。
• 关联 commit hash。
• 关键改动摘要。

6.2 关闭 Issue

目前 GitCode Issue 建议通过网页手动关闭。API 的 state_event=close 在不同版本下行为可能不一致，关闭后建议在评论中同步原因。

踩坑记录

关键经验

1. 任务描述要具体：不要只说「刷新 README」，要列出每个改动点、交付物、操作路径、commit message。
2. Agent 在原始仓库操作：在任务描述中写明 --workdir 或绝对路径，避免改动留在 Multica workdir。
3. 先验证 runtime 兼容性：创建 agent 前确认 model 在 runtime 中可用，避免运行后 401/400。
4. 环境变量隔离：不同 runtime 的 API Key 不要混用，建议在各自配置文件中独立管理。
5. Review 不是可选步骤：多 Agent 协作必须指定 Review 检查点，否则容易流于形式。
6. GitCode API 有限制：Issue 关闭等操作建议预留人工步骤，不要把 API 调用作为强依赖。
7. 全程保留证据：最终产物必须是 Git commit，最佳实践文档本身也要进入 repo。

验证结果

README 改动

本次 README 刷新通过两次迭代完成，最终 commit 为 b492ad4。

主要改动：

• 用一句话明确 madao 定位：面向研发团队的 Agent 工具平台选型与落地知识库。
• 架构分层表新增「为什么选它」列，补充选型理由。
• P0/P1 增加起始日期、里程碑、验收标准。
• 新增「参与方式」章节，避免入口固化。
• 仓库结构说明补齐目录职责，并标注 coming soon。
• 每条原则补充反面案例，增强说服力。

本次最佳实践文档

本实践文章已写入：

pilots/multica-readme-best-practice-20260619/实践文章.md

并通过 Git commit docs: add multi-agent README refresh best practice 提交到 origin/main。

常见问题

Q1：Agent 明明说完成了，为什么仓库里没有变化？

原因：Agent 可能在 Multica workdir（例如 /Users/ming/multica_workspaces/.../workdir）中操作，而不是原始仓库。

解决：在任务描述中明确操作路径，例如「直接在 /Users/ming/madao 仓库操作，不要新建或切换到其他目录」。

Q2：Review Agent 只给了很浅的反馈，怎么办？

原因：Review 任务描述太泛，没有给出检查清单。

解决：在 Review 任务的描述中逐条列出检查点，例如：

• 是否完成 Issue 中的 5 点改动？
• 命令示例是否可直接复制运行？
• 踩坑记录是否准确？
• 是否已 push 到 origin main？

Q3：GitCode Issue 评论失败怎么办？

原因：缺少 GitCode PAT，或 token 权限未勾选 issues。

解决：在 GitCode 个人设置 → Access Tokens 创建带 issue 权限的 PAT；若暂无可用的 token，改为人工在网页评论。

安全最佳实践

1. 不要把 PAT 写入代码或任务描述：使用环境变量或 keychain 管理。
2. 为不同用途创建不同 scope 的 token：例如只读、issue、repo 分离。
3. 定期轮换 PAT：发现泄露立即在 GitCode 后台撤销。
4. Agent 不直接合并到 main：高风险动作保留人工审批。
5. commit message 中不含敏感信息：避免在 commit 中暴露 token、内网地址等。

资源清理

本实践无需额外资源清理。完成后建议：

• 检查 GitCode Issue 是否已关闭。
• 确认文档在 origin/main 可访问。
• 若创建了临时 PAT，按需保留或删除。

参考资料

• GitCode Issue #1 — 刷新 README 原始需求
• GitCode Issue #2 — 输出多 Agent 协作最佳实践
• madao 仓库 README
• Multica CLI 文档（假设）
• [Cat Café 协作治理规则]（如仓库中存在）

文档版本：v1.0
更新时间：2026-06-19
作者：Kimi CLI