logo
1
0
WeChat Login
Add README.md to introduce the repository design

NPC Workspace

基于 CNB 平台的多 Agent 协作工作流仓库,通过 5 个角色化 NPC Agent 实现「需求拆解 → 开发 → 评审 → 测试 → 验收」的全流程自动化。

架构概览

用户提交父 Issue(待完善)
        │
        ▼
   ┌─────────┐
   │  张姐-PM  │  分析需求 → 拆解子 Issue → 设置依赖与验证契约
   └────┬─────┘
        │  子 Issue(待处理)
        ▼
   ┌──────────────┐
   │ CodeBuddy Code │  编码实现 → 自验证 → 提交 PR(待评审)
   └──────┬────────┘
          │  PR(待评审)
          ▼
   ┌──────────────┐
   │  老李-评审员   │  代码评审 → 合并 PR → 推进 Issue(待测试)
   └──────┬────────┘
          │  Issue(待测试)
          ▼
   ┌──────────┐
   │ 小美-测试  │  执行验证契约 → 回写测试结果
   └──────┬────┘
          │  Issue(测试通过/不通过)
          ▼
   ┌───────────────┐
   │ 老推-流程推进   │  中间层晋升 → 依赖放行 → 根 Issue 验收
   └───────────────┘

5 个 NPC 角色

角色NPC 名称职责Agent 规范CI 唤醒规范
项目经理张姐-PM需求分析、拆解父 Issue、创建子 Issue、管理依赖与标签spec/agent/pm.mdspec/ci/pm-call.md
开发者CodeBuddy Code编码实现、自验证、提交 PRspec/agent/dev.mdspec/ci/dev-call.md
评审员老李-评审员PR 代码评审、合并、Issue 状态推进spec/agent/reviewer.mdspec/ci/reviewer-call.md
测试者小美-测试执行验证契约、回写结构化测试结果spec/agent/tester.mdspec/ci/tester-call.md
验收者老推-流程推进中间层晋升、依赖放行、根 Issue 验收spec/agent/checker.mdspec/ci/checker-call.md

Issue 树结构

仓库使用 树形 Issue 结构 管理需求拆解:

  • 根节点:用户提交的原始需求(父 Issue)
  • 中间层:按功能模块分组的子需求(非叶子节点,不参与开发流转)
  • 叶子节点:最小可交付的开发单元,包含验证契约,是唯一进入开发流转的节点

每个叶子 Issue 正文包含以下结构化字段:

节点类型: 叶子节点
父节点: #[父 Issue 编号]
依赖项: none / #[依赖 Issue 编号]
变更范围: 模块/目录范围
执行边界: 仅按当前 Issue 范围执行
解锁条件: 测试通过
构建验证: [可执行命令]
启动命令: [可执行命令]
探活地址: [URL]
期望状态码: [HTTP 状态码]
接口冒烟: [验证命令]
界面冒烟: [验证命令]
Docker构建命令: [构建命令]

标签流转体系

父 Issue(根节点 / 中间层)

待完善 → 完善中 → 处理中 → 汇总中 → 待验收

叶子 Issue

完善中 → 待处理 → 开发中 → 待评审 → 评审中 → 待测试 → 测试中 → 测试通过
                                                          ↘ 测试不通过 → 开发中(返工)
  • 存在未满足依赖时:完善中 → 阻塞中,依赖满足后由 Checker 放行至 待处理
  • 能力重复时:标记为 无需处理

完整标签定义与操作规范见 spec/shared/label-rules.md

CI 调度机制

CI 通过定时巡检(每 5 分钟)扫描仓库 Issue/PR 状态,识别需要处理的节点,并通过 scripts/post_issue_comment.sh 发送唤醒评论触发对应 NPC Agent:

  1. PM Call:扫描标签为 待完善 的父 Issue → 唤醒张姐-PM
  2. Dev Call:扫描标签为 待处理 / 开发中 / 测试不通过 的叶子 Issue → 唤醒 CodeBuddy Code
  3. Reviewer Call:扫描标签为 待评审 / 评审中 的 PR → 唤醒老李-评审员
  4. Tester Call:扫描标签为 待测试 / 测试中 的叶子 Issue → 唤醒小美-测试
  5. Checker Call:扫描标签为 处理中 / 汇总中 的中间层/根节点 → 唤醒老推-流程推进

CI 侧仅做轻量判断与唤醒,不执行任何业务逻辑。所有 Agent 被唤醒后自行做状态检查与幂等检查。

防并发与幂等机制

  • 运行标记:每个 Agent 执行前回写 XX状态: 运行中 作为占位锁,防止 CI 重复唤醒
  • 超时释放:运行标记 30 分钟超时,超时后可重新触发
  • 拆分计划标记:PM 输出拆分计划后,重复触发时只补齐缺失子 Issue
  • 能力重复检查:各 Agent 均会检查兄弟 Issue 是否已实现相同能力
  • 重复催办保护:Agent 发送催办评论前检查是否有新变化

仓库目录结构

.
├── .cnb/
│   └── settings.yml          # NPC 角色定义(名称、头像、Prompt)
├── .cnb.yml                   # CI/CD 流水线 + NPC 触发配置
├── assets/                    # NPC 角色头像
│   ├── pm.png
│   ├── dev.png
│   ├── reviewer.png
│   ├── tester.png
│   └── checker.png
├── scripts/
│   └── post_issue_comment.sh  # NPC 唤醒评论发送脚本(设置 work_mode)
└── spec/
    ├── agent/                 # Agent 执行规范(各角色的完整工作流)
    │   ├── pm.md
    │   ├── dev.md
    │   ├── reviewer.md
    │   ├── tester.md
    │   └── checker.md
    ├── ci/                    # CI 唤醒规范(轻量判断 + 触发逻辑)
    │   ├── pm-call.md
    │   ├── dev-call.md
    │   ├── reviewer-call.md
    │   ├── tester-call.md
    │   └── checker-call.md
    └── shared/
        └── label-rules.md     # 标签操作公共规范(状态定义、流转、API 映射)

关键设计约束

  1. 叶子 Issue 独立闭环:每个叶子 Issue 可独立完成「开发 → 验证 → 合并」,禁止跨节点扩展需求
  2. PR 只关联叶子 Issue:PR body 必须包含 Fixes #<叶子Issue编号>,禁止引用中间层或根节点
  3. 验证契约不可替换:开发和测试必须使用 Issue 正文中的原始验证命令,禁止自行替换
  4. 中间层不进入开发流转:中间层 Issue 仅标签为 完善中 / 阻塞中 / 处理中 / 测试通过 / 无需处理
  5. 标签操作原子性:迁移标签必须按「查询 → 删除 → 添加 → 验证」四步执行,不得跳过
  6. 禁止播报式评论:所有 Agent 禁止输出无决策价值的流程总结评论