Lint 教程
LLM Wiki 会变乱，这是正常的。真正重要的是：它能不能定期被整理回来。Lint 就是让 Agent 给知识库做体检。
如果 ingest 是吸收资料，query 是使用资料，那么 lint 是保持系统健康。
先说结论
- Lint 不是润色文章，而是检查知识库结构和可信度。
- 一次好的 lint 至少检查：孤岛页面、重复概念、缺引用、冲突、过时、缺失页面、index、log。
- Lint 结果应该写成 report，而不是直接大规模改文件。
- 对新手来说，最好的节奏是每 ingest 5-10 篇资料做一次 lint。
1. 为什么需要 lint
Wiki 会自然产生这些问题：
| 问题 | 表现 |
|---|---|
| 孤岛页面 | 页面没有任何入口，之后找不到 |
| 重复页面 | llm-wiki.md 和 agent-maintained-wiki.md 讲同一件事 |
| 缺引用 | 页面有结论，但不知道来自哪里 |
| 过时结论 | 新 source 推翻了旧说法 |
| 冲突说法 | 两个页面说法不一致 |
| 概念缺失 | 很多页面提到一个词，但没有独立概念页 |
| index 过时 | 新页面没进导航 |
| log 缺记录 | 做过操作但没有时间线 |
这些不是 Agent 特有的问题。
人类维护 Wiki 也会这样。
区别是：Agent 可以帮你定期查。
2. Lint 的标准 prompt
请对当前 LLM Wiki 做一次 lint。
要求：
1. 不要直接修改文件。
2. 先读取 index.md 和 log.md。
3. 扫描 wiki/ 下的页面。
4. 检查以下问题：
- 孤岛页面；
- 重复概念；
- 缺引用页面；
- 过时结论；
- 页面之间的冲突；
- 应该新建但缺失的概念页；
- index.md 是否漏页面；
- log.md 是否缺关键记录。
5. 生成一份 lint report 草稿。
6. 按 P0 / P1 / P2 标注优先级。
7. 给出建议修复顺序。
8. 在我确认前，不要改文件。为什么先不要改？
因为 lint 可能涉及合并、删除、改名。
这类操作最好先让人看一眼。
3. Lint report 模板
建议输出到：
wiki/synthesis/wiki-lint-2026-04-25.md内容：
---
type: synthesis
created: 2026-04-25
updated: 2026-04-25
tags: [wiki-lint]
status: active
---
# Wiki Lint Report 2026-04-25
## 总结
- 扫描页面数：
- P0 问题：
- P1 问题：
- P2 问题：
## P0：需要立刻处理
### 1. index.md 漏掉关键页面
- 页面：
- 问题：
- 建议：
## P1：建议近期处理
### 1. 重复概念页
- 页面 A：
- 页面 B：
- 建议合并到：
## P2：可逐步优化
### 1. 缺少反向链接
- 页面：
- 建议：
## 建议修复顺序
1. ...
2. ...
## 后续问题
- ...4. 八类检查怎么做
4.1 孤岛页面
定义：
没有被
index.md或其他 wiki 页面链接的页面。
检查 prompt：
请找出 wiki/ 下没有出现在 index.md，也没有被其他 wiki 页面链接的页面。
这些页面可能是孤岛。处理方式：
| 情况 | 动作 |
|---|---|
| 页面有价值 | 加到 index，补相关链接 |
| 页面重复 | 合并 |
| 页面临时无价值 | 标注 archived，先不删 |
新手不要直接删除页面。
先归档：
status: archived4.2 重复概念
典型重复：
wiki/concepts/llm-wiki.md
wiki/concepts/agent-maintained-wiki.md
wiki/concepts/persistent-wiki.md处理 prompt：
请找出语义上可能重复的 concept pages。
对每组重复，给出：
1. 推荐保留页面；
2. 应合并的信息；
3. 应建立的 redirect 或交叉链接；
4. 不要直接删除，等我确认。合并原则：
- 保留命名最清晰的页面；
- 把别名写进页面；
- 在 index 中只保留主页面；
- 旧页面可以保留一小段指向主页面。
4.3 缺引用
检查：
请找出 wiki/concepts 和 wiki/synthesis 中没有 sources 字段，或正文没有“相关来源”的页面。处理方式：
- 能补来源就补；
- 找不到来源就标
待确认； - 如果全是推断，移动到 synthesis，不要放 concept 定义里。
4.4 过时结论
过时结论通常来自时间。
比如：
当前不需要搜索工具。但后来 Wiki 已经有 300 页。
处理 prompt：
请检查包含“当前”“现在”“不需要”“已经”等强判断的页面。
判断这些说法是否可能因后续 log 记录而过时。4.5 冲突说法
例子：
- 页面 A：LLM Wiki 小规模不需要搜索。
- 页面 B：超过 150 页后应该优先上图谱导航。
这不一定矛盾，但需要解释边界。
处理方式：
## 边界
小规模时 index.md 足够；页面数量增长后，搜索和图谱导航会变得更重要。4.6 缺失概念页
如果很多页面提到同一个词，却没有页面，它就是候选概念。
Prompt：
请扫描 wiki/，找出被多次提到但没有独立 concept page 的术语。
按出现频率和重要性排序。输出：
| 候选概念 | 出现位置 | 建议 |
| --- | --- | --- |
| wiki-lint | 5 | 新建 concept |
| source-summary | 4 | 新建 concept |4.7 index 是否过时
检查：
请列出 wiki/ 下存在但 index.md 未收录的页面。
请列出 index.md 中链接但文件不存在的页面。这类问题可以直接修。
4.8 log 是否缺记录
如果 Git diff 里有很多文件变化，但 log.md 没写，就是问题。
Prompt：
请根据最近修改过的 wiki 页面，检查 log.md 是否记录了对应 ingest/query/lint。
如果缺记录，建议补一条 log entry。5. Lint 后怎么修
不要一次修所有。
推荐顺序：
- 修 index 链接；
- 补 log；
- 补缺引用；
- 合并重复概念；
- 处理冲突；
- 新建缺失概念页；
- 最后再优化文风。
为什么？
因为 index 和 log 是导航与历史。
它们不对，后面越修越乱。
6. Lint 修复 prompt
确认 report 后，可以说：
请根据 wiki/synthesis/wiki-lint-2026-04-25.md 修复 P0 问题。
要求：
1. 只修 P0。
2. 不删除页面。
3. 如果需要合并页面，先创建合并后的目标页，再把旧页面标记为 archived。
4. 更新 index.md。
5. 追加 log.md。
6. 最后列出修改文件。分批修。
不要让 Agent 一次“全面优化 Wiki”。
这句话很危险。
7. Lint 频率
| Wiki 规模 | 建议频率 |
|---|---|
| 1-20 页 | 每 5 次 ingest 后 |
| 20-100 页 | 每 10 次 ingest 后 |
| 100-300 页 | 每周或每个主题阶段 |
| 300 页以上 | 需要搜索 + 更严格的 lint |
如果你的 Wiki 是项目知识库，建议每周固定一次。
如果是学习 Wiki，建议每完成一个小主题做一次。
8. 把 lint 写进 AGENTS.md
补上：
## Lint 修复规则
- Lint 默认只生成 report，不直接改文件。
- P0 是结构性错误，如 index 缺失、断链、log 丢失。
- P1 是质量问题，如重复概念、缺引用、冲突说法。
- P2 是优化问题，如页面太长、链接不足、命名不佳。
- 修复时一次只处理一个优先级。
- 删除页面前必须先询问用户。练习
在你前面生成的 Wiki 上做一次 lint：
请对当前 LLM Wiki 做第一次 lint。
只生成 report，不改文件。然后让它修 P0：
请根据 lint report，只修复 P0。
不要处理 P1/P2。最后检查：
- index 是否完整；
- log 是否追加；
- 是否误删页面。
小结
Lint 是让 LLM Wiki 长期可用的关键。
它解决的不是“写得好不好”，而是：
- 找不找得到；
- 有没有重复；
- 有没有依据；
- 有没有冲突；
- 有没有过时；
- 维护动作有没有记录。
下一篇讲 Obsidian：怎么把这个 Markdown Wiki 变成可浏览、可连接、可感知结构的工作环境。