wiki-lint

Lint — Wiki 健康检查

遵循 wiki/CONVENTIONS.md 中的格式约定、frontmatter 和链接规范。

语言

使用用户的语言编写产物。遵循正确的语法，并使用任何必需的变音符号或特定文字字符。如果无法确定用户使用的语言，请先询问，再生成输出。

项目根目录

此技能会在相对于项目根目录（即开展工作的仓库）的路径下写入产物，而不是相对于 Agent 当前的工作目录。

• 如果从项目内部调用，请使用此技能中显示的相对路径。
• 如果从其他目录调用（例如，相邻的仓库，或项目位于其他位置），请在每个产物路径前添加 <project-root>/。
• 如果项目根目录不明确，请通过 harness 的提问工具向用户确认，再进行写入。

提示

遵循 CLAUDE.md / AGENTS.md 中项目范围的约定（“Skill Prompting Conventions”）。对于以下决策点，请使用 harness 的结构化提问工具：AskUserQuestion（Claude Code）、ask_user_question（Codex）或 question（OpenCode）。

决策点	使用结构化提问的原因	建议选项
范围（多选）	会影响检查内容	Frontmatter · 链接 · 内容漂移 · 空子文件夹 · 全部
自动修复安全问题	难以撤销的编辑	仅报告 · 自动修复 · 逐项询问

自由文本提问（不使用结构化工具）：

• 自定义规则说明

无暂停模式：如果用户已明确禁用技能运行期间的澄清，将每个结构化提问转换为“未决问题”（或同类部分）下的一项，然后继续，不要暂停。

查询语言对齐

对于语义 lint 检查，请使用 wiki 的语言进行查询。先从 .wiki-guardrails.yml（query_language 或 language）确定语言；如果没有 guardrails 配置，则从 wiki frontmatter 或索引确定。保留精确名称和代码标识符。向用户提供的报告应使用用户的语言。

检索 — 优先使用 QMD（如可用）

使用 QMD（本地混合搜索）进行语义检查（孤立页面、缺失的交叉引用、矛盾）。每个仓库只需设置一次，详见 docs/wiki/qmd-setup.md。对于纯结构检查（frontmatter、失效链接），使用 grep/glob 即可，速度更快。

• 查找页面的语义邻近内容（孤立页面候选项、矛盾候选项、缺失的交叉引用）时，使用 mcp__qmd__query（MCP）或 qmd query --json --files（CLI）。
• 始终向 QMD 传入一行 intent:，说明要查找的内容。
• 不要自动运行 qmd embed / qmd update；如果 wiki 有变动且索引已过时，请在 lint 结束时指出需要更新。

检查清单

按顺序逐项检查。如果用户提出了具体要求（例如“只检查链接”），则重点检查相应部分。

1. 失效的交叉引用

• 指向不存在页面的相对链接 [text](./path.md)。
• 修复链接或创建缺失的页面。

2. 孤立页面

• 没有从 wiki/index.md 获得入链的 wiki 页面（CONVENTIONS.md、index.md、log.md 除外）。
• 对每个孤立页面候选项，运行 QMD 查询，并使用 intent: page describing <topic of orphan>，以查找哪些现有页面应当链接到它。
• 如果内容有效 → 将页面添加到 index.md，并在语义相关的页面中添加交叉引用。
• 如果内容无关 → 建议人工删除。

3. Frontmatter

所有 wiki 页面都必须包含：

字段	必填	验证
title	是	存在且不为空
audience	是	必须为以下值之一：business、dev、ops、mixed
sources	是	非空列表
updated	是	ISO 日期。超过 90 天时标记
tags	是	非空列表
status	是	必须为以下值之一：draft、stable、stale

类型化页面例外（kind: decision / kind: rule）： ADR 和规则由类型化架构（wiki/_schemas/typed-schema.yaml）管理，不适用此通用表格。其 status 使用类型化枚举（决策为 proposed | accepted | superseded | deprecated；规则为 active | deprecated），其 frontmatter 由 wiki-policy-check（validate-schema 模式）验证。 当页面的 kind: decision 或 kind: rule 时，不要根据 draft|stable|stale 标记其 status，也不要将通用表格中的要求视为阻塞项——应以类型化架构为准。（类型化页面仍可包含 sources / updated，且从 v1.1.0 起，类型化架构已允许这些字段。）

4. raw/ ↔ wiki/sources/ 一致性

交叉核对 raw/index.md 与 wiki/sources/：

• 有来源无摘要 — 在 raw/index.md 中标记为已摄取，但缺少 <slug>.md。
• 有摘要无来源 — wiki/sources/<slug>.md 中的 sources: 指向不存在的文件。

5. 受众边界检查

• wiki/apps/ 中的页面不应包含业务规则（定价、政策、用户旅程、变现）。如果包含，应将这些规则移至 wiki/business/，并让 apps/ 页面仅保留交叉引用。
• 针对 wiki 集合运行类似 intent: business rule (pricing/policy/monetization/cancellation) 的 QMD 查询（将路径限定为 apps/），以发现 wiki 内部的越界内容。
• 对于项目作为同级目录保留的产品/代码仓库（且项目约定规定其中只应包含技术规则），应使用 grep / Read 审查，而不是将它们编入 QMD 索引。索引这些仓库会模糊“wiki 是权威来源”的边界，使 Agent 误将产品仓库中的文字视为权威内容。将发现的任何业务规则表述列为迁移至 wiki/business/ 的候选内容。

6. 缺少交叉引用

• 对每个实质性 wiki 页面，针对其标题/主题运行 QMD 查询，并检查排名前 5-10 的结果。语义上相关但没有链接的页面应予以标记。
• 向人工审核者提出建议（不要自动修复——这可能引入噪声）。

7. 矛盾

• 对于出现在多个页面上的每个主题，针对规范表述运行 Hyde 风格的 QMD 查询（例如 hyde: The cancellation policy is X hours with Y consequence），并比较排名靠前的结果。
• 如果页面内容互相矛盾 → 在页面上添加说明并标记。

8. 状态过期

• draft 页面若内容完整且已验证，可考虑改为 stable。
• stable 页面若 updated 超过 90 天，可考虑标记为 stale。

9. index.md 统计信息

• 页面数量是否与实际情况一致？
• 页面描述是否为最新？

10. QMD 索引健康状况（仅在配置了 QMD 时）

• 调用 mcp__qmd__status（或 qmd status）。
• 如果 needsEmbedding > 0 → 告知所有者运行 qmd embed。
• 如果 wiki/ 中的文件数量与 wiki 集合的 totalDocuments 差异显著 → 告知所有者运行 qmd update。

行为

• 简单修复（frontmatter、链接、updated）→ 自动完成。
• 内容变更 → 先征求人工审核者同意。
• 回复人工审核者时：聚焦于可执行事项：
  1. 需要人工决策的待处理事项
  2. 改进机会
  3. 数量摘要（问题总数 / 自动修复数）
  4. 所有者需要运行的 QMD 重建索引命令（如有）
• 不要在回复中列出所有自动修复内容——详情记入 log.md。

日志

更新 wiki/log.md（插入到顶部，标题之后）：

## [YYYY-MM-DD] lint | health check

### Automatic fixes
- ...

### Pending (human decision)
- ...

### Suggestions
- ...

### QMD reindex needed
- qmd update / qmd embed (only if applicable)

强类型模式验证（可选启用）

当 wiki 目标采用强类型模式（ADR、规则、事件依据中央文件 wiki/_schemas/typed-schema.yaml 进行验证）时，lint 可以选择通过以 validate-schema 模式调用 wiki-policy-check 技能来加入模式检查。

模式

读取 wiki 的 .wiki-guardrails.yml 中的 lint.includeSchema：

模式	行为	适用场景
off（默认）	完全跳过模式验证。无额外开销。报告中不提及。	未采用强类型模式的 wiki；安全的全局默认值，可避免影响未使用该模式的项目。
warning	运行 validate-schema；将模式警告作为结构化字段报告；不进行阻止（即使存在模式问题，LINT_RESULT: PASS 仍成立）。	初始推广阶段——暴露偏差，但不会中断 ETL 或阻止导入。
block	运行 validate-schema；如果存在任何模式错误、重复 ID 或孤立引用，lint 将失败（LINT_RESULT: FAIL）。	在 warning 模式稳定运行 1-2 个 sprint，且 ≥80% 的项目至少有 1 个有效 ADR/规则之后——参见下文的升级标准。

启用

1. 检查 <wiki-path>/_schemas/typed-schema.yaml 是否存在。
2. 读取 .wiki-guardrails.yml → lint.includeSchema（如果缺失，默认为 off）。
3. 如果模式 != off，则调用：

   bun ~/.claude/skills/wiki-policy-check/scripts/validate-schema.ts \
     --wiki-path <wiki-path> \
     --format json
   

4. 解析 JSON 输出：
   • summary.invalid + summary.duplicate_ids + summary.orphan_refs → 模式问题总数。
   • 每个 validations.decisions[i].errors、validations.rules[i].errors、validations.events[i].errors → 单项问题。

集成到 lint 报告

将以下内容添加到 lint 报告中（自动运行时写入 wiki/log.md，或在对话回复中提供）：

## [YYYY-MM-DD] lint | health check

### Schema validation (mode: warning|block)
- schema-warnings: <N>   (or schema-errors if mode=block)
- valid: <ADRs>+<Rules>+<events>
- invalid: <N> (with file+field+message details for each)
- duplicate_ids: <N>
- orphan_refs: <N>

### Automatic fixes
- ...

当模式为 off 时，省略整个部分。

升级标准（warning → block）

当以下条件全部满足时，将 wiki 从 warning 升级为 block：

1. wiki 中至少有 3 个项目各自拥有至少 1 个有效 ADR 或规则（证明该模式已落地）。
2. 连续 2 个 sprint 处于 warning 模式，且追溯检查未发现阻止性模式错误（证明该模式适用于实际数据）。
3. 所有者明确确认（通过单行 PR 评论或提交消息确认升级）。

在 wiki 的 wiki/log.md 中记录此次升级；如果升级时放宽了任何模式约束（较少见），则递增模式的 version 字段。

限制

• 此功能按 wiki 选择启用（通过 .wiki-guardrails.yml），并非全局启用。未采用强类型模式的 wiki 不会有任何行为变化。
• 技能 wiki-policy-check --mode validate-schema 是判定有效性的权威来源。此技能（wiki-lint）只负责协调调用并整合输出。
• block 模式绝不应设为全局默认值——没有 typed-schema.yaml 的 wiki 会报错。

参考

• wiki-policy-check §Mode 2 — 脚本驱动的验证器（epic #4 Story 02 do wiki-service）。
• ADR-0009 typed-schema（没有 knowledge-center 仓库）— 模式规范 + 13 项锁定决策。
• Epic #4 Story 05（wiki-lint-integration-gradual）— 此集成。