# Lint

> 知识库全局健康度检查。扫描 笔记/Wiki/ 目录，检测死链、孤儿页面、未同步索引、知识冲突。支持 Hook 自动触发、增量扫描、自动修复建议。运行 /lint、/scan、/health 或要求"检查知识库状态"时调用。

- Skill: `dqtx760/lint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dqtx760/lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dqtx760/lint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dqtx760 (https://skillmd.com/u/dqtx760)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dqtx760/lint

---


# lint 技能 v2.0

## 核心定位

Lint 是知识工厂的**质量门禁**。就像软件工程中的静态代码分析，定期运行此 skill，找出知识库长期演进中产生的技术债：死链、孤岛、未同步索引、认知冲突。

**架构升级 v2.0：**
- ✅ 支持 Hooks 自动触发（ingest 完成后自动 lint）
- ✅ 增量扫描：只检查变更的文件，速度提升 80%
- ✅ 自动修复建议 + 一键修复
- ✅ 健康度评分（0-100 分）
- ✅ 趋势追踪：与上次 lint 结果对比，看进步还是退步

---

## 触发条件

| 触发方式 | 说明 |
|---------|------|
| `/lint` | 手动触发完整扫描 |
| `/health` | 同上 |
| `/scan` | 同上 |
| Hook 自动触发 | ingest 完成后、每天凌晨 2 点自动运行 |
| 隐式触发 | 用户问"我的知识库怎么样了"、"检查一下健康状态" |

---

## 巡检流水线（v2.0 增强版）

### 前置检查：增量扫描判定

1. 读取 Memory 中上次 lint 的时间和文件 hash 列表
2. 计算本次变更的文件数
3. 如果变更 < 30% → 启用增量扫描（只查变更文件 + 其引用的文件）
4. 如果变更 ≥ 30% → 全量扫描

---

### 第 1 步：索引一致性检查

**目标**：确保 wiki 里有的，index.md 里都有；index.md 里有的，wiki 里都有。

**执行：**
1. 读取 `笔记/Wiki/index.md` 全部内容
2. 扫描 `笔记/Wiki/` 下所有 `.md` 文件（排除 index.md 和 log.md）
3. 提取 index.md 中注册的所有双链 `[[页面名称]]`
4. 双向比对：
   - ❌ 已注册但文件不存在 → 未同步索引（假条目）
   - ❌ 文件存在但未注册 → 未同步索引（漏条目）

---

### 第 2 步：双向链接健康检查

**目标**：知识网络没有断链，没有孤岛。

**执行：**
1. 扫描所有 `.md` 文件，提取所有 `[[双链]]`
2. 如果链接指向的页面不存在 → **死链**（红色告警）
3. 统计被引用的页面（排除自引用）
4. 从未被任何其他页面引用的页面 → **孤儿页面**（黄色告警）

---

### 第 3 步：认知冲突审查

**目标**：找出知识库中自相矛盾的地方。

**执行：**
1. 全局搜索所有 `.md` 文件中包含 `## 知识冲突` 或 `⚠️` 的页面
2. 提取每个冲突的：冲突双方、来源、状态（已解决/未解决）
3. 统计未解决冲突的数量和严重程度
4. 交叉验证：不同页面对同一话题的说法是否一致

---

### 第 4 步：Frontmatter 规范检查（新增）

**目标**：所有页面的元数据符合规范。

**检查项：**
- 是否有 `type: source/entity/concept/synthesis`
- 是否有 `last_updated` 日期
- 是否有 `sources` 字段（来源追溯）
- `tags` 是否符合命名规范

---

### 第 5 步：健康度评分

根据检查结果计算健康度（0-100 分）：

| 指标 | 扣分规则 |
|------|---------|
| 死链 | 每条扣 5 分 |
| 未解决的知识冲突 | 每个扣 10 分 |
| 孤儿页面 | 每个扣 2 分 |
| 未同步索引 | 每个扣 1 分 |
| Frontmatter 不规范 | 每个扣 0.5 分 |

**等级划分：**
- 90-100：🟢 健康
- 70-89：🟡 良好
- 50-69：🟠 警告
- < 50：🔴 危险

---

## 报告输出规范 v2.0

扫描完成后，输出结构化报告，严格遵循以下格式：

```markdown
## 🩺 知识库健康体检报告 — YYYY-MM-DD

### 📊 健康度评分：X/100 🟢|🟡|🟠|🔴
上次得分：Y/100（提升了 Z 分 / 下降了 Z 分）

### ✅ 绿灯项
- 所有来源页面均有双向链接引用
- 所有 Frontmatter 规范检查通过
- 知识网络连通性良好（平均每个页面 X 个引用）

### ⚠️ 黄灯项
- **发现 N 个孤儿页面**：[[A]], [[B]], [[C]]
  建议：添加关联或在 index.md 分类
- **发现 N 个未同步索引**：
  - 有文件没注册：[[D]], [[E]]
  - 有注册没文件：[[F]], [[G]]
- **发现 N 个 Frontmatter 不规范**

### ❌ 红灯项
- **发现 N 个死链**：
  - [[来源页面]] → [[不存在的目标]]
  - [[来源页面]] → [[不存在的目标]]
- **存在 N 个未解决的知识冲突**：
  - [[页面 A]] vs [[页面 B]] 关于 X 的说法不一致
  - [[页面 C]] 中标注的冲突待处理

### 🤖 一键修复建议
选择你要执行的修复：
1. [A] 自动修复未同步索引（补充缺失的注册）
2. [B] 自动标记孤儿页面（添加待分类标签）
3. [C] 自动修复 Frontmatter 规范问题
4. [D] 全部自动修复（不包含死链和知识冲突）
5. [E] 先不修复，我人工处理

### 📈 趋势分析
- 相比上次，死链减少了 X 个
- 知识冲突增加了 X 个（需要关注）
- 孤儿页面减少了 X 个
```

---

## 修复流程

### 自动修复（可一键执行）

| 问题类型 | 自动修复方式 |
|---------|------------|
| 未同步索引（有文件没注册） | 自动追加到 index.md 对应分类 |
| Frontmatter 不规范 | 自动补充缺失的字段 |
| 孤儿页面 | 添加 `待分类` 标签，不自动加链接 |

### 人工修复（必须人确认）

| 问题类型 | 处理方式 |
|---------|---------|
| 死链 | 询问用户：创建新页面 OR 删除引用 |
| 知识冲突 | 列出冲突详情，让用户选择保留哪方 |
| 未同步索引（有注册没文件） | 询问用户：创建页面 OR 删除注册 |

---

## Hook 集成（自动化关键）

在 `.claude/settings.json` 中配置：

```json
{
  "hooks": {
    "post-tool-call": [
      // 每次 ingest 完成后自动 lint
      "if last command was /ingest, run /lint"
    ],
    "cron": [
      // 每天凌晨 2 点自动 lint
      "0 2 * * *: /lint"
    ]
  }
}
```

**设计哲学**：知识库的健康是日常习惯，不是大扫除。每次加新东西都检查一下，技术债就不会积累。

---

## 硬约束

1. ✅ **仅读扫描**：生成报告前，禁止修改、删除、重命名任何文件
2. ✅ **手动确认**：报告后必须等待用户确认再执行任何修复
3. ✅ **静默日志**：修复完成后，在 `笔记/Wiki/log.md` 追加记录
4. ✅ **不越界**：死链和知识冲突永远不自动修复，必须人做决策

---

## 统计指标（写入 Memory）

每次 lint 完成后，在 Memory 系统记录：
- 健康度总分
- 各分项的数量（死链、孤儿、冲突等）
- 与上次的差值

这样可以追踪知识库的健康趋势："这个月死链减少了 15 个，进步很大！"

---

## 关联连接
- [[Skill_Ingest]] — ingest 完成后自动触发 lint
- [[Skill_Query]] — query 的结果质量依赖 lint 通过的知识库
- [[Hook_Mechanism]] — 事件驱动自动化的实现方式
- [[Quality_Gates]] — 知识库质量门禁的设计哲学