---
name: linting-the-wiki
description: "检查知识库健康度。当用户说'检查知识库'、'知识库有什么问题'时使用。"
version: 0.3.0
owner_repo: Optima-Chat/kb-skills
---

# Linting The Wiki

检查 wiki 随时间推移后的完整性和可维护性。

## 启动 SOP

0. 自动迁移与同步（静默执行，无需告知用户）：
   ```bash
   [ -d ~/kb/.git ] && kb migrate
   [ -n "$KB_BACKEND_URL" ] && kb sync
   ```
1. `ls ~/kb/REGISTRY.md`
   - 不存在 → 告诉用户"还没有知识库，需要先创建一个"，引导使用 initializing-kb
2. 读 `~/kb/REGISTRY.md` — 获取所有 active 的 KB 列表
3. 确定目标 KB：
   - 用户明确指定了 KB slug 或主题 → 直接用
   - 用户说"全部 lint" → 遍历所有 active KB
   - 只有一个 active KB → 用它
   - 多个 active → 列出让用户选
4. 读 `~/kb/<slug>/AGENTS.md` 了解该 KB 的契约

## Lint 流程

1. 先跑 CLI 自动扫描：

   ```bash
   kb lint --dir ~/kb/<slug>
   ```

   CLI 会检测：断链、index.md 覆盖不足、index entry 格式错误、重复 index entry、孤立页面（无入链）、log.md heading 格式。输出为每行一条 issue，退出码 0 表示无问题。

2. 基于 CLI 报告 + 人工阅读，补充 CLI 无法检测的问题（见下方"要检查什么"）
3. 按类型归类所有问题：链接、覆盖度、过时、矛盾、重复、页面规模或索引问题
4. 除非用户要求更大范围修复，否则只应用小而明确的修补
5. 清楚报告仍未解决的问题
6. 追加 `~/kb/PROGRESS.md`
7. Git 同步：
   ```bash
   cd ~/kb/<slug>
   git remote get-url origin &>/dev/null && git pull --rebase
   git add -A && git commit -m "lint: <发现N个问题，修复M个>"
   git remote get-url origin &>/dev/null && git push
   ```

## 要检查什么（CLI 之外的人工检查）

CLI 已覆盖断链、孤立页面、index 覆盖和格式问题。以下需要人工判断：

- 被反复提及但没有独立页面的实体或概念
- 本应并入 overview 的 analysis 页面，或反过来的情况
- 新来源进入后仍未更新的旧综述
- `index.md` 与实际长期页面之间的漂移
- 为了清晰起见应被拆分的大页面
- 由于缺少来源而无法回答、但明显值得继续调查的问题

## 修复边界

安全的 lint 修复通常包括：

- 增加缺失链接
- 更新 `index.md`
- 澄清过时标签
- 就地标出矛盾

不要把 lint 变成无边界重写。需要更深层次调整时，明确说出来并停下，除非用户明确要求继续。

## 最小交付标准

一次成功的 lint 至少应留下：

- 一份简短但具体的问题清单
- 已经完成的有边界修复
- 已修复问题与剩余债务之间的清晰区分
- 需要通过新来源或 web search 继续补足的空白点
