# Knowledge Check

> 实现后知识检查、知识库维护、项目经验沉淀。用于代码、配置、脚本、文档或流程变更完成后，判断是否需要记录项目知识，并将知识路由到 AGENTS、docs/dev-knowledge、docs/plan、docs/lessons-learned 或项目 skill。

- Skill: `jasons-impart/knowledge-check` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jasons-impart/knowledge-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jasons-impart/knowledge-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jasons-impart (https://skillmd.com/u/jasons-impart)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jasons-impart/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 重复出现。

最后输出：

```text
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 的覆盖规则？

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