npc-learning — NPC 学习与知识沉淀
何时使用
- 需要扫描 CNB 公开仓库中 NPC 的 SKILL.md / system prompt / 代码结构
- 提取 NPC 高级用法模式（工具编排、容错策略、记忆管理等）
- 生成 NPC 模式库或每日学习报告
- 定时任务自动学习新出现的优质 NPC
何时不使用
| 场景 | 替代 Skill / 方式 |
|---|---|
| 派任务给 NPC 执行 | ai-pipeline-factory 或直接 @NPC |
| 查询 NPC 列表/库存 | CNB OpenAPI GET /orgs/npc/-/repos |
| 修改 NPC 代码 | 直接在目标仓库开 Issue @NPC |
| 生成 NPC 报告摘要 | auto-report |
学习来源
| 来源 | 提取内容 | 获取方式 |
|---|---|---|
| NPC 仓库 SKILL.md | 触发条件、工具声明、执行步骤 | CNB API GET /repos/{repo}/contents/SKILL.md |
| 热门 NPC 代码结构 | 目录组织、入口文件、配置模式 | Git clone + 文件遍历 |
| NPC 实战 PR/Issue | 对话策略、错误恢复、边界处理 | CNB API Issues/Comments |
| NPC system prompt | 人设、约束、输出格式 | SKILL.md frontmatter + 正文 |
已沉淀的 NPC 模式（持续更新）
1. Skill 结构模式
- Frontmatter 规范：
name+description+alwaysApply+compatibility+allowed-tools - 分级触发：description 精确匹配优先，宽泛关键词兜底
2. 工具编排模式
- 链式调用：搜索 → 读取 → 执行（减少无效调用）
- 容错降级：主工具失败 → 备选方案 → 友好提示
- 批量合并：多个 API 调用合并减少请求次数
3. 记忆管理模式
- 分层存储：长期 MEMORY.md + 每日 memory/YYYY-MM-DD.md + 规则 rules/
- 按需加载：只读相关文件，避免上下文膨胀
4. 质量保障模式
- 输入验证：检查环境变量、文件存在性后再执行
- 结构化输出：JSON Schema / Markdown 模板
- 防御性编程：不信任外部输入，全路径容错
安装与运行
# 克隆仓库
git clone https://cnb.cool/cnbll/npc-learning.git
cd npc-learning
# 安装依赖
pip install -r requirements.txt
# 运行学习模块
python main.py
环境变量要求：
- CNB_TOKEN：CNB API 认证令牌（必须）
执行步骤
- 扫描目标仓库：通过 CNB API 获取 NPC 组织下所有公开仓库列表
- 提取 SKILL.md：逐个获取仓库中的 SKILL.md 内容
- 模式识别：解析 frontmatter + 正文，识别工具编排、记忆管理、容错等模式
- 归档沉淀：将识别到的模式写入模式库
output/npc-pattern-library.md - 生成报告：输出每日学习报告
output/npc-learning-YYYY-MM-DD.md
输出格式
每日学习报告
# NPC 学习报告 YYYY-MM-DD
## 扫描概要
- 扫描仓库数：N
- 新增模式数：N
- 更新模式数：N
## 新发现模式
### 模式名：<模式名称>
- **来源仓库**：<repo-path>
- **模式类型**：工具编排 / 记忆管理 / 容错策略 / 触发优化
- **描述**：<一段话描述>
- **代码示例**：
<关键代码片段>
- **可复用场景**：<适用于哪些 NPC 开发场景>
## 模式库更新摘要
- 模式库总计：N 个模式
- 本日新增：N 个
模式库结构
{
"pattern_id": "tool-chaining-search-read-execute",
"name": "搜索→读取→执行链式调用",
"category": "tool_orchestration",
"source_repos": ["npc/open-code", "npc/claude-code"],
"description": "先搜索定位目标，再读取确认内容，最后执行修改。减少盲操作。",
"example": "...",
"applicable_scenarios": ["代码修改", "文件重构", "配置更新"]
}
错误处理与降级
| 错误 | 处理方式 |
|---|---|
| CNB API 返回 429（限流） | 等待 Retry-After 后重试，最多 3 次 |
| 仓库无 SKILL.md | 跳过，记录到日志，不中断流程 |
| SKILL.md 解析失败 | 记录原始内容和错误信息，人工复查 |
| 网络超时 | 单仓库超时 30s，跳过继续下一个 |
| CNB_TOKEN 无效 | 立即终止并提示检查 Token 配置 |
与其他 Skill 的协作
- ai-pipeline-factory：学习到的 NPC 模式可反馈到流水线工厂，优化 NPC 编排
- cnb-openapi-skills：底层依赖 CNB API 进行仓库扫描和内容获取
- auto-report：学习报告可由 auto-report 格式化后推送
许可
MIT
