wiki-lint

Wiki Lint

将 wiki 审核作为一个四阶段流水线，避免将页面正文载入主上下文：确定性脚本（阶段 1）和各集群的子 Agent（阶段 2）负责大量阅读工作；主线程只汇总发现。生成分类报告，提供具体修复方案，并记录操作。

前置条件

查找 SCHEMA.md（从当前工作目录向上搜索，或在 ~/wikis/ 中搜索）。如果未找到，请告知用户先运行 wiki-init。阅读该文件以获取 wiki 根路径和约定。

链接样式。 从 SCHEMA.md 读取 link_style:。如果缺少该字段，或 <wiki-root>/config/link-style.md 不存在，则默认使用 obsidian（[[slug]]）。否则，读取 <wiki-root>/config/link-style.md。以下所有链接扫描均使用该文件中的 ## Parse 规则（可能匹配多种形式）。你撰写的 lint 报告本身也是一个 wiki 页面，因此其中的交叉引用使用 ## Emit 规则。

流水线说明

旧版的全 wiki 扫描会将每个页面正文都载入同一个上下文——随着 wiki 增长，这会耗尽上下文窗口。替代方案如下：

• 阶段 1 运行 bin/lint-mechanical.py，在不使用大模型、也不将正文载入上下文的情况下，计算确定性检查（图关系和字符串属性），并输出供阶段 2 使用的标签集群列表。
• 阶段 2 为每个标签集群派发一个子 Agent。每个子 Agent 只读取其集群中的页面（正文仅存在于子 Agent 的上下文中，返回后即丢弃），并报告跨页面和正文级别的发现。你只汇总精简后的发现，绝不汇总正文。

阶段 1 会穷尽检查整个 wiki。阶段 2 的检查则限定于集群范围：与其他任何页面都没有共同标签的页面不会接受正文检查（这是方案 A 可接受的召回率限制——见阶段 2）。请定期运行 lint（每导入 5–10 次后运行一次），让限定范围的检查逐步累积覆盖率。

流程

阶段 0 — 重新生成索引

运行 python bin/generate-index.py，使索引反映当前页面的 frontmatter。

阶段 1 — 确定性检查（脚本，不使用大模型）

运行 python bin/lint-mechanical.py 并解析其 JSON。它会返回：

{ "findings": { "broken_links": [...], "missing_frontmatter": [...], "orphans": [...],
                "slug_collisions": [...], "stale_date": [...], "missing_concept": [...] },
  "clusters": [ {"pages": ["slug-a", "slug-b"], "split": false}, ... ] }

这些内容会直接对应报告章节：

• 🔴 损坏的链接 — broken_links（{page, link}）。
• 🔴 缺少 frontmatter — missing_frontmatter（{page, missing:[...]}）。overview.md 位于 wiki/，而非 wiki/pages/，因此不受此项检查。
• 🟡 孤立页面 — orphans（{page}）：没有任何入站 [[slug]] 链接。
• 🟡 slug 冲突 — slug_collisions（{token, pages:[...]}）：裸 slug 与限定形式冲突（mercury 与 mercury-element）。标记这组冲突；切勿自动重命名——重命名属于 wiki-merge 拆分操作。
• 🟡 过期声明 — stale_date（{page}）：90 天未更新，且正文仍包含 current/latest/recent/state-of-the-art，或提到至少 2 年前的年份。
• 🔵 缺少概念页面 — missing_concept（{slug, count}）：[[slug]] 被引用至少 3 次，但没有对应页面。

不要自行通过阅读页面重新推导这些结果——以脚本为准。

第 2 阶段 — 集群子 Agent（矛盾 + 正文级检查）

针对第 1 阶段 clusters 列表中的每个集群，分派一个子 Agent（并行扇出，分批处理以限制并发）。提供该集群的页面路径，并发送以下指令：

阅读这些页面。仅限这些页面内，以简洁列表报告发现的问题——每项按 {type, pages:[slug,...], detail} 格式列出；若没有发现问题，则写 clean：

• contradiction — 两个页面描述同一实体，但日期、数量、名称或关系存在冲突。
• missing-xref — 两个页面明确讨论同一实体，但没有互相添加 [[link]]。
• merge-candidate — 两个页面使用不同 slug 描述同一概念（标题近似重复 / Description 部分几乎相同）。
• chronological-section — 页面正文包含带日期的日志标题（## [Month]、**[Month] N update），应将其整合到正文相应位置。
• addable-line-range — 脚注引用了可按文本定位的原始文件（markdown / 纯文本 / 代码 / 缓存的 HTML），但没有 L<start>-<end> 标记。豁免：PDF、文字记录、实时 URL — 绝不标记这些内容。 仅返回发现的问题——不要返回页面正文。

在主线程中汇总所有子 Agent 的发现，并按 (type, sorted(pages), detail-entity) 去重——一个页面可能带有 K 个标签，因此会出现在 K 个集群中，同一发现可能重复出现。

**覆盖范围说明：**由于子 Agent 只能看到各自的集群，正文级发现仅限于集群范围。与其他页面没有任何共同标签的页面不会进行正文检查。这是基于标签集群范围进行检查所接受的限制；第 1 阶段（图关系 / 字符串检查）仍会覆盖所有页面。

第 3 阶段 — 覆盖缺口，然后整理报告

首先，进行唯一一项无需页面正文的正文级检查：阅读 wiki/overview.md，并标记🔵 覆盖缺口 — 可通过网络搜索或新导入内容解答的开放问题。

然后编写 wiki/pages/lint-<today>.md（不要请求许可 — 始终写入此文件），合并第 1 阶段发现的问题、第 2 阶段去重后的发现以及覆盖缺口。以下模板为便于阅读，以 Obsidian 格式显示 slug 引用；在实际编写报告时，所有 slug 引用都必须遵循 config/link-style.md 中的 ## Emit 规则：

---
title: Lint Report <today>
category: Maintenance
summary: <N> errors, <N> warnings, <N> info
tags: [lint, maintenance]
sources: []
created: <today>
updated: <today>
---

# Lint Report — <today>

## Summary
- 🔴 Errors: N
- 🟡 Warnings: N
- 🔵 Info: N


## 🔴 Broken Links
- [[source-page]] references [[missing-slug]] — does not exist
  Fix: create the page or remove the reference

## 🔴 Missing Frontmatter
- [[page]] is missing: title, updated

## 🟡 Orphan Pages
- [[slug]] — no inbound links
  Fix: add link from [[related-page]], or delete if no longer relevant

## 🟡 Contradictions
- [[page-a]] says: "<claim>"
- [[page-b]] says: "<conflicting claim>"
  Recommendation: <which to trust, or "investigate further">

## 🟡 Stale Claims
- [[page]] last updated <date>, contains "latest" — may be outdated
  Fix: re-verify claims or add a "as of <date>" qualifier

## 🟡 Colliding Slugs
- [[mercury]] and [[mercury-element]] share base token "mercury" — possible undisambiguated homonym
  Fix: qualify the bare slug via wiki-merge split (e.g. mercury → mercury-planet)

## 🟡 Chronological Update Sections
- [[page]] has date-stamped journal headers — integrate the updates in-place

## 🔵 Missing Concept Pages
- [[slug]] referenced N times but no page exists
  Fix: run wiki-ingest or create a stub

## 🔵 Coverage Gaps
- Open question from overview.md: "<question>"
  Suggestion: search for <X> or ingest <source type>

## 🔵 Missing Cross-References
- [[page-a]] and [[page-b]] both discuss <entity> but don't link to each other

## 🔵 Merge Candidates
- [[page-a]] and [[page-b]] appear to describe the same concept under two slugs
  Fix: run wiki-merge to consolidate into one page (rewrites inbound links)

## 🔵 Addable Line-Ranges
- [[page]] [^3] cites text source [[markdown-source]] with no line-range
  Fix: add an `L<start>-<end>` token so wiki-audit can verify it deterministically

lint 报告的 frontmatter 中包含 category: Maintenance，因此会自动进入索引 — 不要手动编辑 index.md。运行 python bin/generate-index.py。

提供具体的修复方案

针对每个可修复类别，提供以下选项：

• 失效链接：“移除失效的 slug 引用？（写入前我会展示每项更改）”
• 缺失的交叉引用：“在这些页面对之间添加缺失的链接？”
• 冲突的 slug / 合并候选项：“这些看起来描述的是同一概念（或是需要消歧的同形词）— 要运行 wiki-merge 来合并或拆分吗？”不要在 wiki-lint 中修复这些问题；交由 wiki-merge 处理。
• 孤立页面标签：“要为孤立页面的 frontmatter 添加 status: orphan 吗？”
• 缺失的 frontmatter：“要使用占位值补充缺失的 frontmatter 字段吗？”

写入前，展示每项更改的准确差异。仅在确认后应用更改。

记录操作

按照 SCHEMA 的操作日志与提交约定：

• **Git wiki：**建议提交（已应用修复时默认使用 Conventional Commits fix:，仅生成报告时使用 chore:，并附上 trailer）；确认后提交。

  fix: resolve <what lint fixed>
  
  Wiki-Op: lint
  

• **非 Git wiki：**追加到 wiki/log.md：

  ## [<today>] lint | <N errors> errors, <N warnings> warnings, <N info> info
  Report: <slug reference to lint-<today>, in the wiki's link_style>
  Fixed: <list what was auto-fixed, or "none">