| name | framework-dev |
| description | 开发与维护 NcatBot 框架本体。调试 bug、开发新功能、维护 Skill、代码审查、重构。Use when: 框架调试、debug、fix bug、feat、新功能、Skill 维护、代码贡献、模块修改、代码审查、重构。 |
| license | MIT |
技能指令
你是 NcatBot 框架开发助手。帮助用户对框架本体进行一切变更：修 bug、加功能、重构代码。
设计哲学：四位一体
NcatBot 项目中，skill、docs、code、test 是不可分割的整体。任何变更都必须同时触及这四项：
| 产物 | 说明 | 不同步的后果 |
|---|
| Code | 实现代码 | 功能不存在 |
| Test | 测试代码 | 无法验证正确性，回归无保障 |
| Docs | 用户文档 + 参考文档 | 用户不知道怎么用，贡献者不知道怎么改 |
| Skill | Agent 技能知识 | AI 助手无法正确引导后续开发 |
变更检查清单（每次提交前过一遍）：
协作技能
| 需要做什么 | 委托给 |
|---|
| 定位代码、理解模块、导航文档 | codebase-nav |
| 理解设计意图、查阅架构与 API | doc-nav |
| 编写测试、运行测试、调试测试 | testing-framework |
| 编写/编辑文档、一致性检查、索引同步 | docs-maintenance |
| 发布版本、推送变更、管理 docs submodule | release |
Fix 工作流（fix/）
核心原则：日志优先，禁止通过纯代码阅读推演定位根因。
完整生命周期：症状 → 插桩日志 → 最小复现测试 → 从日志定根因 → 修复 → 回归 → （按需）同步文档
→ 详见 references/hard-bug-debugging.md（完整流程、插桩位置速查、实战案例）
Feat 工作流（feat/）
核心原则：先读文档理解设计意图，再找实现位置；接口设计优先于编码。
流程：读文档（doc-nav）→ 接口设计 → 编码 → 写文档（docs-maintenance）
→ 详见 references/feat-workflow.md（文档路径速查、接口设计检查点、docs 委托指南）
Refactor 工作流（refactor/）
核心原则：现有测试即契约，外部行为不得改变。
- 以现有测试套件确认外部行为基线
- 修改内部实现，保持最小改动范围
- 如有内部模块文档需更新，委托 docs-maintenance 同步
contributing/
Docs 工作流（docs/）
→ 委托 docs-maintenance 技能执行。
收尾（每次变更后）
- 四位一体检查：Code ✓ Test ✓ Docs ✓ Skill ✓
- 代码风格：
ruff format . + ruff check . --fix
- docs submodule：若改动了
docs/ 文件 → 参见 release 技能的 commit 编排流程
- 留痕：在
memory/ 目录创建工作记录 → 模板见 references/memory-template.md
- 多平台变更：若涉及新平台或跨平台接口 → 见 references/multi-platform.md
导入规范
详见 references/import-conventions.md。核心原则：
- 跨 layer 绝对导入，最多到二级平台子模块（
from ncatbot.<layer> import ...），禁止三级及更深
- 同 layer 内部相对导入（
from ..module import ...）
- 新增公共 API 必须在对应 layer 的
__init__.py 中注册
分支与提交
- 分支命名：
feat/xxx、fix/xxx、refactor/xxx、docs/xxx
- Commit 格式：Conventional Commits
- 代码风格：
ruff format . + ruff check . --fix
