| name | dev-knowledge |
| description | 开发知识路由、知识库整理、实现记录、代码位置索引、设计规划归档、技术 how-to。用于查找或记录 Create-Delight Remake 项目知识，或判断信息应写入 AGENTS、docs/dev-knowledge、docs/plan、docs/lessons-learned 还是项目 skill。 |
开发知识
当任务涉及开发知识存放位置、查找既有实现上下文，或在功能/调查后记录新知识时，使用本 skill。
本 skill 是知识存放路由的唯一来源；knowledge-check 应引用这里的存放表，而不是重复维护一份规则。
存放表
| 知识类型 | 目标位置 | 使用场景 |
|---|
| 常驻约束和入口路由 | AGENTS.md、kubejs/AGENTS.md、CDC-mod-src/AGENTS.md | 每次相关任务都必须看到的事实。 |
| 内容改动（feat） | docs/dev-knowledge/content-map.md | 记录有意新增或调整的玩家体验、玩法与平衡，以及实现位置。 |
| 兼容与问题修复（bugfix/compat） | docs/dev-knowledge/compatibility-patches.md | 记录恢复预期行为、修复回归或适配上游变更的补丁、验证与后续复核条件。 |
| 轻量技术做法 | docs/dev-knowledge/how-to-index.md | 记录“想做某类修改该怎么做”，但复杂度还不足以成为 skill。 |
| 项目技术专题参考 | docs/dev-knowledge/<专题>/ 下的专题文档 | 记录与仓库实现和维护直接相关的机制、状态与参考；多文件专题以 README.md 为唯一入口。 |
| 可重复或脆弱流程 | .agents/skills/<name>/SKILL.md | 任务依赖步骤顺序、命令、验证规则或触发描述。 |
| 历史故障和绕路经验 | docs/lessons-learned.md | 主要价值是避免再次踩同一个坑。 |
| 稳定设计说明和参考 | docs/<专题>/ 下的专题文档 | 功能需要叙述当前设计、取舍或参考资料；专题有多份关联文档时以 README.md 作为唯一入口。 |
| 前瞻设计规划 | docs/plan/ 下的专题文档 | 功能仍在规划、分阶段推进或描述未来扩展。 |
内容地图条目
当一个功能已经足够具体，未来 agent 需要知道以下信息时，更新 docs/dev-knowledge/content-map.md：
- 玩家能感知到的变化。
- 实现的大致方式。
- 主要代码、数据或配置位置。
- 相关设计文档。
- 当前状态和验证备注。
条目保持短小；长篇设计理由只链接 docs/ 或 docs/plan/ 的专题文档，不复制正文。
仅新增、升级、降级或移除第三方模组（以及对应的 Packwiz 元数据、完整性清单或模组列表更新）不属于内容地图条目；这些变更由 mods/*.pw.toml 和模组清单文档记录。只有在模组接入之外实施了整合包自定义玩法、平衡或体验改动时，才写入 content-map.md。
兼容与问题修复条目
当改动的主要目的为恢复预期行为、修复错误或适配上游模组更新时，更新 docs/dev-knowledge/compatibility-patches.md。
- 每个明确修复一行，记录问题或上游变化、受影响模组与版本、补丁文件、验证方式、上游跟踪位置和复核/移除条件。
- 不按 KubeJS、配置、hotai、CDC 或 mixin 的目录决定落点：有意新增或调整玩家体验的是 feat；恢复预期行为、修复回归或适配上游的是 bugfix/compat。
- 同一目标的一组配方或配置可合并为一行，避免逐文件流水账；纯翻译、格式化或不改变行为的资源不入账。
- 同一事实不再重复写入
docs/lessons-learned.md；只有可脱离具体补丁复用的通用踩坑才写 lesson。
技术做法条目
当未来任务可能会问“某类修改该怎么做”时，更新 docs/dev-knowledge/how-to-index.md。
- 每个条目保持为紧凑 checklist。
- 优先写具体路径和已有 helper 名称。
- 一旦条目变成多步骤流程、包含重复命令或有明显踩坑风险，就提升为
.agents/skills/<name>/SKILL.md。
- 已有专题入口或专用 skill 时，只保留链接和分类，不复制专题事实或操作步骤。
语言规则
docs/dev-knowledge/ 和本 skill 的正文必须以中文为主；mod 名、文件路径、命令、函数名、英文术语可保留英文。- 新增条目的叙述性文字必须写中文；
scripts/validate-knowledge-base.ps1 会检查 dev-knowledge Markdown 正文中是否存在无中文的英文叙述行。
更新流程
- 搜索
docs/dev-knowledge/、AGENTS.md、相关模块 AGENTS.md、.agents/skills/ 和 docs/lessons-learned.md。
- 按存放表选择最小且持久的目标位置。
- 一个事实只写在一个地方；需要关联时使用链接，不复制内容。
- 修改 AGENTS、skill 或 dev-knowledge 索引后，运行
scripts/validate-knowledge-base.ps1。
