| name | knowledge-check |
| description | 实现后知识检查、知识库维护、项目经验沉淀。用于代码、配置、脚本、文档或流程变更完成后，判断是否需要记录项目知识，并将知识路由到 AGENTS、docs/dev-knowledge、docs/plan、docs/lessons-learned 或项目 skill。 |
知识检查
本 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；该报告只提供建议，不会自动修改知识文件。
如果任务中途遇到非显而易见的失败或绕路做法，但最终还没决定是否落库，可用 scripts/add-knowledge-note.ps1 追加临时 note，让候选报告把它路由到这里。
通常值得记录的知识分为：
- 可复用的项目事实或位置 → 按
.agents/skills/dev-knowledge/SKILL.md 的存放表路由。
- 内容改动（feat） →
docs/dev-knowledge/content-map.md，记录新增或有意调整的玩家体验、实现位置和验证状态。
- 兼容与问题修复（bugfix/compat） →
docs/dev-knowledge/compatibility-patches.md，记录问题、上游变化、补丁位置、验证与复核条件。
- 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 而改变分类。
- 恢复预期行为、修复错误或回归、适配上游版本变更 →
docs/dev-knowledge/compatibility-patches.md；不因补丁目录而将其误归为 feat。
- 候选报告会对可能改变玩法的整合包文件同时列出两种台账；依据改动目的选择，不确定时先检查玩家可见结果与问题描述。
- 与具体补丁无关、未来会反复遇到的根因或非显而易见的 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 步：写入更新
更新知识文件时遵守这些规则：
- 保持简洁：每个事实尽量一句话，不写长篇说明。
- 说明原因：非显而易见的规则必须写出失败模式或原因。
- 避免重复：如果信息已存在于其他文件，改用引用，不要复制。
- 控制 AGENTS 行数：根
AGENTS.md 不超过 150 行，子目录 AGENTS.md 不超过 80 行；超限先精简。
- lessons 条目：包含 Problem、Fix/Lesson 和日期。
- skill 条目：触发条件写进 YAML
description；正文聚焦可执行流程。
- dev-knowledge 条目：使用表格行、路径和链接；不要复制长篇设计理由。
- 迭代式维护：只有出现重复错误或具体发现后才新增规则；删除 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 更新前，必须确认：
- 行数：根
AGENTS.md 是否 ≤150 行，子目录 AGENTS.md 是否 ≤80 行？超限先精简。
- 无重复：同一事实是否已存在于其他知识文件？如果存在，改为引用。
- 简洁：每个条目是否能继续删字而不丢信息？
- 原因：非显而易见的规则是否写清失败模式或理由？
- 过期检查：正在追加的文件是否已有过期条目？如有，标记或删除。
- skill 检查：这是 workflow、checklist 或工具序列吗？如果是，应写入 skill，而不是常驻 AGENTS。
- 位置检查：目标文件是否符合 dev-knowledge 存放表和本 skill 的覆盖规则？
任何一项失败，都先修正再保存；这一步是长期保持知识库质量的主要机制。
