NPC Workflow Builder Skill

标准化工作流：CNB NPC 多 Agent 协作 — 从单功能到完整项目

一句话

CNB Issue + @NPC 触发流水线 → NPC 沙箱执行 → 人工代推 PR → 审查修复 → 冲突解决 → 合并。

两种使用模式

架构总览

用户/Agent（AI Agent）                   CNB 平台                       NPC 沙箱
    │                                       │                               │
    ├─ Phase 1: 分析需求 ──────────────────→│                               │
    ├─ Phase 2: 创建 Issue ── @NPC ────────→│──── 触发流水线 ────────────→  │
    │                                       │◄── NPC 执行代码到沙箱 ──────┤
    ├─ Phase 3: 读取 NPC 评论 ←── 轮询 ────→│                               │
    ├─ Phase 4: 本地代推 ── git push + PR ─→│                               │
    ├─ Phase 5: @NPC Review ──────────────→│──── 触发审查流水线 ────────→  │
    │                                       │◄── NPC 评论修复建议 ────────┤
    ├─ Phase 6: 解决冲突 + 按序合并 ────────→│                               │
    ├─ Phase 7: Chat 链路（可选）──────────→│──── Issue → NPC ────────────→  │
    │                                       │◄── 轮询评论 ───────────────┤
    └──────────────────────────────────────←─│◄── 展示回复                ─┘

关键限制

模式 B 快速入口：完整项目 7 阶段

> 从零搭建完整项目（参考 GEO-NPC 实战验证：20 Issues → 2 NPC → 15 PRs → 全部合并）

Phase B1：项目规划（~2h）

提示词：

我要克隆/构建 [参考URL] 的系统，构建 NPC 版本。
请先分析参考站点功能，输出：
1. 完整功能清单和优先级（P0/P1/P2）
2. 技术架构设计（前后端分离 + 模块化）
3. 各功能模块的工作量估算
4. NPC 分工方案

产出：PRD 文档 + NPC 架构设计

创建仓库：

POST /{org}/-/repos {"name": "PROJECT-NPC", "visibility": "Public"}

Phase B2：多 NPC Issue 看板（~30min）

NPC 分工：

创建标签：

POST /{repo}/-/labels {"name":"backend","color":"#0052cc"}
POST /{repo}/-/labels {"name":"frontend","color":"#d73a4f"}

创建 Issue 看板（每个 Issue @mention 指定 NPC）：

在 [仓库路径] 创建 Issue 看板：

P0 核心功能：
- [AI蒸馏] → @npc/CodeWhale(CodeWhale-pro)
- [计费系统] → @O.o/CodeBuddy(glm-5.1)
- [API网关] → @npc/CodeWhale(CodeWhale-pro) + @O.o/CodeBuddy(glm-5.1)

P1 重要功能：
- [前端页面] → @O.o/CodeBuddy(glm-5.1)

每个 Issue body 需含：需求描述 + 技术要求 + 验收标准 + 末尾 @NPC
详见 assets/issue-templates/multi-npc-board.md

Phase B3-B7

与模式 A 的 Phase 2-6 相同，但需要：
- 批量创建分支和 PR（N个模块 → N个分支 → N个 PR）
- 按依赖顺序合并（计费→功能→网关→前端）
- 集中解决多 PR 冲突

Phase B7：Chat 链路（可选，~45min）

> 详见 references/chat-pipeline-pattern.md

对话式 Agent 编排：用户 → Chat UI → FastAPI → CNB Issue(@NPC) → NPC 回复 → 轮询展示

模式 A：单功能开发 — 10 步标准工作流

> 已有项目，新增 1 个功能时的标准流程。

Phase 1：分析需求（~10min）

Step 1：阅读参考 Skill（如有）

GET /{org}/{repo}/-/git/raw/main/SKILL.md
GET /{org}/{repo}/-/git/contents/{path}

Step 2：分析目标项目结构

GET /{org}/{repo}/-/git/contents/          # 根目录
GET /{org}/{repo}/-/git/raw/main/{file}     # 关键文件

确定：现有模块、需新增的文件列表、NPC 任务

Step 3：规划交付物

| 文件 | 类型 | 功能 | 行数估计 |
|------|------|------|---------|

Phase 2：触发 NPC 流水线（~5min）

Step 4：创建 Issue 触发 @NPC

POST /{repo}/-/issues {
  "title": "feat: {功能描述} — {目标}",
  "body": "@{NPC全称}\n\n## 任务目标\n{描述}\n\n## 现有架构\n{现状}\n\n## 交付物\n{文件列表}\n\n## 约束\n{限制}\n\n## 完成标准\n{标准}",
  "labels": ["enhancement", "npc"],
  "priority": "P0"
}

Issue body 提示词：

@{NPC全称}

## 任务目标
{一句话描述}。**先把链路跑通。**

## 现有架构
项目已有以下模块（均已在 main 分支）：
- `{文件路径}` — {功能描述}

## 需要实现的架构（参考 {参考链接}）

### 核心链路
{ASCII 链路图}

### 具体交付物

#### 1. `{文件路径}`（约 {N} 行）
{详细描述}

## 关键约束
- **{约束1}**：{原因和解决方式}

## 完成标准
1. {标准1}
2. {标准2}

> 完整模板见 assets/issue-templates/feature-request.md

Step 5：监控 NPC 响应

# 每 20-30 秒检查，注意：每页10条，必须遍历！
GET /{repo}/-/issues/{issue_number}/comments?page=1

• ✅ NPC 成功 → Phase 3
• ❌ NPC 未响应 → 等60s后追加评论 @{NPC全称} 请开始处理
• ⚠️ NPC 无推送权限 → 正常现象

Phase 3：NPC 响应处理（~30min）

Step 6：分析 NPC 输出

NPC 评论中通常包含：文件列表、架构说明、无推送权限说明

注意：NPC 代码留沙箱中。需人工提取或根据描述实现。

Step 7：人工实现代码

git clone https://user:token@cnb.cool/{org}/{repo}.git
git checkout -b {branch_name} main
# 创建/修改文件
git add -A && git commit -m "feat: {描述}" && git push origin {branch_name}

Phase 4：推送 PR（~10min）

Step 8：创建 PR

POST /{repo}/-/pulls {
  "base": "refs/heads/main",        # ⚠️ 必须含 refs/heads/
  "head": "refs/heads/{branch}",    # ⚠️ 必须含 refs/heads/
  "title": "feat: {模块名} — {简述}",
  "body": "## 变更概述\n{摘要}\n\n## 新增文件\n{列表}\n\n## 关联\nCloses #{issue_number}\n\n@{NPC全称} 请复审"
}

> PR body 模板见 references/prompt-templates.md

Phase 5：审查与合并（~10min）

Step 9：触发 NPC 审查

POST /{repo}/-/pulls/{pr_number}/comments {
  "body": "@{NPC全称}\n\n## 审查任务\nPR #{pr_number} 已提交。\n\n请进行代码初审并修复：\n1. 安全问题（SQL注入、XSS等）\n2. 错误处理完整性\n3. 代码质量\n\n发现问题请直接给出修复建议。"
}

> 审查模板见 assets/issue-templates/code-review.md

NPC 审查后，合并改进点：

git checkout {branch}
# 根据 NPC 意见修改
git add -A && git commit -m "fix: {NPC名称} 初审修复 — {摘要}" && git push origin {branch}

Step 10：解决冲突 + 合并

# 冲突时
git fetch origin && git rebase origin/main
# 解决冲突（策略见下）
git push origin {branch} --force-with-lease

# 合并
PUT /{repo}/-/pulls/{pr_number}/merge {
  "commit_title": "Merge PR #{number}: {title}",
  "commit_message": "合并 {摘要}\n\nReviewed-by: @{NPC全称}",
  "merge_style": "squash"
}

# 关闭 Issue
PATCH /{repo}/-/issues/{number} {"state": "closed"}

Phase 6：多 PR 合并管理（完整项目模式）

> 仅模式 B 需要

合并顺序（关键）：基础模块先合并

1. 计费/配置（其他模块依赖）
2. 各功能模块（互相独立，可并行）
3. API 网关（依赖所有功能）
4. 前端页面（依赖后端）
5. Chat 链路（可选）

冲突解决策略：

CNB API 踩坑速查

> 完整踩坑文档见 references/pitfalls-and-fixes.md

NPC 完整路径参考

> 以下格式经过实战验证，不要简写

耗时预估

模式 A：单功能

模式 B：完整项目

实战案例

GEO-NPC 项目（https://cnb.cool/zhanxiaoyu/GEO-NPC）完整工作流：
- 20 Issues（#1-#62）→ 2 NPC（CodeWhale-pro + CodeBuddy）→ 15 PRs（#41-#63）→ 全部合并
- 7 大 GEO 功能 + API 网关 + 前端 9 页面 + Chat 对话链路
- 70+ 文件，完整可运行项目

> 详见 references/workflow-review.md