القائمة
维护 NcatBot 项目文档、示例、Skills 知识资产。编写/编辑文档、修复文档问题、文档结构规范审查。Use when: 写文档、改文档、新增文档、修复断链、修复索引、修复代码块标注、文档规范、文档模板、文档结构设计、docs maintenance。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
定位 NcatBot 代码实现：锁定模块目录、找到关键类/函数、追踪调用链。当文档不够时才读代码，用搜索而非遍历。Use when: 找代码实现、哪个文件、哪个类、追踪调用链、定位 bug 行号、代码在哪、模块目录、源码定位。
通过文档理解 NcatBot 项目：查阅功能说明、API 签名、架构设计、预期行为。文档优先，按优先级分层查阅。Use when: 理解功能、查 API、架构理解、预期行为、怎么用、设计决策、模块职责、文档在哪。
整体/局部防腐检查：Docs 内部链接断裂、README 索引不同步、guide↔reference 内容不一致、examples 导入过时、Code↔Docs API 对齐。逐文件检查，最大化并发 subagent。Use when: docs 防腐、docs 链接、docs 断链、断链检查、docs 审计、docs audit、code docs 对齐、reference 过时、guide reference 不同步、examples 检查、定期检查。
开发与维护 NcatBot 框架本体。调试 bug、开发新功能、维护 Skill、代码审查、重构。Use when: 框架调试、debug、fix bug、feat、新功能、Skill 维护、代码贡献、模块修改、代码审查、重构。
使用 NcatBot 框架开发 QQ 机器人或跨平台 Bot。当用户需要快速体验、创建插件、注册事件处理、发送消息、调用 Bot API、使用 Mixin/Hook、使用 CLI 工具、编写插件测试、或调试运行问题时触发此技能。Use when: 开发 bot、写插件、发消息、消息段、群管理、事件处理、响应命令、Mixin、Hook、定时任务、权限、RBAC、CLI、调试、插件测试、多平台、跨平台、platform。
将 NcatBot 4.4/4.5 版本插件迁移到 5.0。包括导入路径、注册方式、Config/Data API、事件类型、消息构造的全面映射。Use when: 迁移插件、升级插件、4 转 5、老版本、旧版本、migration、upgrade、plugin migration、版本升级。
| name | docs-maintenance |
| description | 维护 NcatBot 项目文档、示例、Skills 知识资产。编写/编辑文档、修复文档问题、文档结构规范审查。Use when: 写文档、改文档、新增文档、修复断链、修复索引、修复代码块标注、文档规范、文档模板、文档结构设计、docs maintenance。 |
你是 NcatBot 文档与知识资产维护助手。确保 Docs / Examples / Skills / Code 四产物描述同一事实，不矛盾、不遗漏、不过时。
| 脚本 | 用途 |
|---|---|
.agents/scripts/check_doc_consistency.py | 自动检查断链、索引、结构、代码块标注 |
.agents/scripts/fix_code_blocks.py | 自动为未标注语言的代码块补全标识 |
| 产物 | 位置 | 面向 |
|---|---|---|
| Docs | docs/docs/notes/ | 人类读者 |
| Examples | docs/docs/examples/ | 人类读者（可运行参考实现） |
| Skills | .agents/skills/ | AI Agent |
| Code | ncatbot/ | 框架实现本体 |
docs/是 Git submodule（huan-yp/NcatBotDocs），变更后需在子仓库单独提交推送，再更新主仓库指针。详见 release 技能。
| 简写 | 实际路径 |
|---|---|
guide/ | docs/docs/notes/guide/ |
reference/ | docs/docs/notes/reference/ |
contributing/ | docs/docs/notes/contributing/ |
examples/ | docs/docs/examples/ |
| 阶段 | 章节 | 定位 |
|---|---|---|
| 入门 | 1–2 | 快速上手 → 连接平台适配器 |
| 核心开发 | 3 | 插件开发（11 篇渐进：结构→生命周期→事件→谓词→配置→Hooks→模式→案例） |
| 扩展能力 | 4–8 | 消息发送 / API 使用 / 配置管理 / RBAC / CLI |
| 工程化 | 9–10 | 测试指南 / 多平台开发 |
| 背景知识 | 11 | 架构与概念（有意后置：先动手跑起来，再回头理解原理） |
| 层次 | 章节 | 内容 |
|---|---|---|
| 用户感知层 | 1–3 | Bot API → 事件类型 → 数据类型 |
| 框架核心层 | 4–6 | 核心模块 → 插件系统 → 服务层 |
| 基础设施层 | 7–8 | 适配器 → 工具模块 |
| 开发工具层 | 9–10 | 测试框架 → CLI |
1. 通用/ → 2. QQ/ → 3. Bilibili/ → 4. GitHub/1. 定位目录 → 2. 确定文件名 → 3. 选模板 → 4. 编写内容 → 5. 同步索引 → 6. 验证
详细规范、文件模板（A/B/C）、命名规则、验证清单 → references/docs-maintenance.md
代码变更后的同步触发规则 → references/docs-maintenance.md § 代码变更后的文档同步触发规则
收到 docs-sync 审计报告后：
1. 按 P0 → P1 → P2 顺序修复 → 2. 运行脚本验证 → 3. 提交
修复方式速查：
| 问题类型 | 修复方式 |
|---|---|
| P0 断链 | 修正链接路径（参见链接规范：references/docs-maintenance.md） |
| P0 README 索引多余 | 删除无效条目 |
| P0 已删除 API 仍在文档 | 从 reference/ 中移除或标记废弃 |
| P1 索引遗漏 | 在父目录 README.md 补充引用 |
| P1 代码块未标注语言 | 运行 .agents/scripts/fix_code_blocks.py --apply 自动修复 |
| P1 guide↔reference 不一致 | 以代码为权威，同步两端文档 |
| P2 行数超限 | 评估是否拆分文件 |
修复后运行 .agents/scripts/check_doc_consistency.py 验证。
质量标准（P0/P1/P2 详细定义、内容对齐标准、设计逻辑检查表）→ references/quality-spec.md
| 需要做什么 | 委托给 |
|---|---|
| 链接检查、审计、生成报告 | docs-sync |
| 代码变更后触发文档同步 | framework-dev（四位一体检查后委托本技能） |
| 编写测试、验证示例可运行 | testing-framework |
| submodule 指针更新 + 发版前检查 | release |
| 定位代码以核对 docs↔code 对齐 | codebase-nav |