# 常见错误与避免方法

## 错误 1：将 Q&A 当作编译任务处理

**表现**：用户提问时，直接去创建 `practices/` 或 `concepts/` 下的文档

**避免**：先看"任务路由"，Q&A 应该归档到 `wiki/queries/`

## 错误 2：忘记添加参考文档清单

**表现**：回答了问题，但没有链接到相关 wiki 页面

**避免**：Q&A 回答模板中必须包含"参考文档"部分

## 错误 3：归档后不更新 INDEX.md

**表现**：创建了 `wiki/queries/` 下的文档，但 INDEX.md 中没有入口

**避免**：使用 Q&A 检查清单，确保步骤 5 完成

## 错误 4：大文档只读取开头部分

**表现**：学术论文或长篇技术文章只基于开头部分生成简短摘要

**避免**：使用"大文档处理要求"的检查清单

## 错误 5：Wikilink 格式错误

**表现**：`[[Harness Engineering|Harness 工程]]` 而不是 `[[Harness-Engineering|Harness 工程]]`

**避免**：参考 Wikilink 格式规范

## 总体执行清单

* [ ] **任务路由确认**：已阅读任务路由，确认当前任务属于正确场景
* [ ] **Raw Check**: `raw/` 目录中是否包含待处理的新素材（图片/文档）？
* [ ] **Asset Sync**: `raw/images/` 下的所有图片是否已同步到 `wiki/assets/`？
* [ ] **Glossary Lock**: 是否已锁定全局术语表，确保翻译不漂移？
* [ ] **Multimodal Sync**: 图片是否已转化为可编辑的文字解析/Mermaid？
* [ ] **文件名规范**: 所有 wiki 页面文件是否使用 kebab-case（连字符分隔）命名？
* [ ] **Wikilink 格式检查**: 所有 `[[文件名|显示文本]]` 链接中的文件名部分是否与实际文件名完全匹配？
* [ ] **Wikilink Check**: 所有的核心概念是否都已变成 `[[可点击的链接]]`？
* [ ] **Marp Check**: 是否为需要汇报的内容生成了幻灯片格式？
* [ ] **Orphan Check**: 是否存在无法从 `INDEX.md` 触达的"孤儿页面"？

## Linting 检查清单

- [ ] **一致性检查**：扫描 `wiki/`，发现术语冲突时自动统一
- [ ] **孤岛扫描**：识别没有任何链接指向的页面，强制挂载到导航树
- [ ] **补丁发布**：当 `raw/` 有新版本时，在对应 Wiki 页面顶部发布摘要

## 最佳实践提示

* **手离开键盘**：不要手动修改 `wiki/` 目录下的内容，所有的修改应通过"向 LLM 发出 Lint 任务"或"添加 raw 素材后重新编译"来完成
* **搜索即创作**：把每一次对知识库的提问看作是一次"知识合成"，务必将高质量的回答存回库中
* **结构化思考**：在生成任何长篇文档前，先让 LLM 在内存中构建该主题的"概念地图"
* **利用编译日志**：遇到问题时，先查看 `wiki/compile.log` 了解之前的编译过程