Knowledge Check

知识检查

本 skill 用于在实现工作结束后，判断是否学到了值得未来会话复用的项目知识，并把它写到正确位置。

何时使用

在以下情况调用本 skill：

• 刚完成代码改动、bug 修复或配置更新。
• 发现了非显而易见的项目模式、坑点或约束。
• 修正了未来 agent 可能再次犯的错误。
• 当前任务明确要求维护或整理知识库。

以下情况不要调用：

• 纯研究或探索，且没有代码/配置/文档改动。
• 完全按既有文档执行的琐碎改动。
• 与本项目无关的通用知识。

流程

第 1 步：判断是否值得记录

先问：“我是否学到了未来会话会受益的项目特定知识？”

如果存在 tmp-opencode/knowledge-candidate-report.md，先读取它再决定；除非当前任务明确要求维护知识库，否则 process note 候选需要用户接受后再落库。

Codex（.codex/hooks.json）和 ZCode（.zcode/config.json 的 Stop hooks）都会运行 scripts/validate-knowledge-base.ps1，并写入 tmp-opencode/knowledge-candidate-report.md；该报告只提供建议，不会自动修改知识文件。报告覆盖范围为工作区改动加上自上次报告以来的全部未报告提交；仅当上次报告基线缺失或不再是 HEAD 祖先（如 rebase）时，才回看最近 -RecentCommits 个提交（默认 1）。有候选的报告会按时间戳归档到 tmp-opencode/knowledge-candidate-history/（保留最近 50 份，空报告不归档）；漏记的知识候选可从归档或 git 提交历史回溯补记。

diff 扫描只覆盖代码改动，看不到任务过程中发现的信息。因此任务进行中遇到非显而易见的失败、绕路、根因或约束时，立即用 scripts/add-knowledge-note.ps1 追加临时 note，不要等任务结束再回忆；候选报告会读取这些 note 并把它路由到这里。

通常值得记录的知识分为：

• 可复用的项目事实或位置 → 按 .agents/skills/dev-knowledge/SKILL.md 的存放表路由。
• 内容改动（feat） → docs/dev-knowledge/content-map.md，记录新增或有意调整的玩家体验、实现位置和验证状态。
• 模组兼容补丁 → docs/dev-knowledge/compatibility-patches.md，记录外部模组缺陷，或由外部模组版本、API、数据和运行时行为差异触发的兼容补丁；由 CDR 承载的 workaround 同样准入。
• bug、坑点或历史教训 → 优先写入 docs/lessons-learned.md。
• 知识路由或 skill 行为变化 → 更新受影响的 skill。
• 成组项目技术资料或其生成脚本 → 以 docs/dev-knowledge/<专题>/README.md 作为专题入口；内容/兼容台账只保留分类与入口链接，不复制专题事实与操作流程。
• 没有可复用项目价值 → 不记录。

第 2 步：选择知识形态

读取 .agents/skills/dev-knowledge/SKILL.md，以其中的存放表作为知识落点的唯一来源。

第 3 步：选择目标文件

应用 dev-knowledge 存放表后，再检查这些覆盖规则：

• 新增或有意调整配方、平衡、NPC、剧情、任务、物品、机器或系统 → docs/dev-knowledge/content-map.md；不因实现位于 KubeJS、配置、hotai、CDC 或 mixin 而改变分类。
• 仅当根因是外部模组缺陷，或 CDR 与外部模组、多个外部模组之间存在版本、API、数据或运行时行为差异，且补丁会随上游变化而复核或移除时 → docs/dev-knowledge/compatibility-patches.md；由 CDR 承载的 workaround 同样准入，普通 CDR 内部 bug 不因“修复错误”、实现位置或调用第三方 API 而自动准入。
• 纯 CDR 内部修复若未形成可脱离具体实现复用的经验，则不记录；不要把局部空值、容量或自有数据读写修复写入兼容台账。
• 候选报告会对可能改变玩法的整合包文件同时列出两种台账；依据改动目的选择，不确定时先检查玩家可见结果与问题描述。
• 与具体补丁无关、未来会反复遇到的根因或非显而易见的 workaround → docs/lessons-learned.md。
• 新的 KubeJS helper/API 参考 → 内容很短时写入 kubejs/AGENTS.md 的 UNIQUE STYLES；否则写入 dev-knowledge how-to 或提升为 skill。
• hotai/ 补丁、docs/dev-knowledge/hotai/ 专题资料或 scripts/update-hotai-docs.ps1 → 使用 /hotai skill；逐文件语义和生成状态写入 docs/dev-knowledge/hotai/，玩家体验与兼容修复仍按目的分别登记到对应台账。
• knowledge-check prompt、候选报告路由或触发时机 → .agents/skills/knowledge-check/SKILL.md。
• dev-knowledge 存放规则 → .agents/skills/dev-knowledge/SKILL.md。

第 4 步：写入更新

更新知识文件时遵守这些规则：

1. 保持简洁：每个事实尽量一句话，不写长篇说明。
2. 说明原因：非显而易见的规则必须写出失败模式或原因。
3. 避免重复：如果信息已存在于其他文件，改用引用，不要复制。
4. 控制 AGENTS 行数：根 AGENTS.md 不超过 150 行，子目录 AGENTS.md 不超过 80 行；超限先精简。
5. lessons 条目：包含 Problem、Fix/Lesson 和日期。
6. skill 条目：触发条件写进 YAML description；正文聚焦可执行流程。
7. dev-knowledge 条目：使用表格行、路径和链接；不要复制长篇设计理由。
8. 迭代式维护：只有出现重复错误或具体发现后才新增规则；删除 agent 已稳定遵守的规则。

允许的知识维护动作：

• 编辑根或模块级 AGENTS.md。
• 编辑 docs/lessons-learned.md。
• 编辑 docs/dev-knowledge/。
• 编辑 .agents/skills/ 或 .opencode/plugins/。

作为 knowledge-check 调用时禁止：

• 修改与知识维护无关的代码、配方或配置。
• 运行 build/test 命令。
• 执行 Git 操作。

第 5 步：输出总结

如果应用或拒绝候选报告，决策后运行 scripts/resolve-knowledge-candidate.ps1 -Status applied|rejected，避免临时 process note 重复出现。

最后输出：

Knowledge Check
- Learned: [1-3 条，或 “nothing significant”]
- Updated: [文件路径，或 “no update needed”]
- Reason: [一句话说明]

如果没有值得记录的内容，只输出：Knowledge: no update needed。

反模式

• 记录与本项目无关的通用编程知识。
• 在多个 AGENTS 或知识文件中复制同一事实。
• 文件超出行数限制时继续追加，而不是先精简。
• 用长篇散文替代简洁条目。
• 把知识维护流程规则放回根 AGENTS.md，而不是放在本 skill。

最终自检

保存任何 AGENTS.md 或 docs/lessons-learned.md 更新前，必须确认：

1. 行数：根 AGENTS.md 是否 ≤150 行，子目录 AGENTS.md 是否 ≤80 行？超限先精简。
2. 无重复：同一事实是否已存在于其他知识文件？如果存在，改为引用。
3. 简洁：每个条目是否能继续删字而不丢信息？
4. 原因：非显而易见的规则是否写清失败模式或理由？
5. 过期检查：正在追加的文件是否已有过期条目？如有，标记或删除。
6. skill 检查：这是 workflow、checklist 或工具序列吗？如果是，应写入 skill，而不是常驻 AGENTS。
7. 位置检查：目标文件是否符合 dev-knowledge 存放表和本 skill 的覆盖规则？

任何一项失败，都先修正再保存；这一步是长期保持知识库质量的主要机制。