wiki-lint

Wiki Lint

检查 Wiki 的健康状况并生成报告。绝不会修改 Wiki 内容。

---

配置发现

每次调用都从这里开始。 Wiki 根目录是包含 wiki-config.md 的目录。技能会在运行时确定该目录。本技能检查的页面会根据 wiki-schema.md 中的结构进行验证——这两个文件都必须存在。

1. 确定范围：确定你的文件系统范围根目录，即文件系统工具可访问的顶层目录。

2. 范围检查——必须停止：如果范围是裸驱动器根目录（C:\、D:\、/）、操作系统根目录或用户主目录（C:\Users\X、/home/X、/Users/X）→ 立即停止。不要搜索。不要尝试查找 wiki-config.md。 直接转到第 6 步。

3. 在 <available_skills> 中查找 wiki-config。 记录它是否可用——下方的建议会据此调整。随附的 references/setup-help.md 也可用；如果用户需要指引或你遇到困难，请阅读该文件。

4. 查找并读取 wiki-config.md：递归搜索（匹配到第一个即停止，最多 5 层）。如果找到，读取其中的设置（blacklist、index_excludes、ingested_folder、ingested_subdirs、log_format）。如果未找到，跳到第 6 步。

5. 查找并读取 wiki-schema.md——强制检查：在与 wiki-config.md 相同的目录中，确认 wiki-schema.md 存在且能解析为 YAML。在明确判定其状态（存在／缺失／格式错误）之前，不得继续下面的工作流。 然后：

   • 存在且解析正常 → 读取架构（mandatory_fields、conditional_fields、enums），然后继续工作流。

   • 缺失 → 停止。不要继续。不要部署。根据 <available_skills> 中是否有 wiki-config（第 3 步的结果）采取相应措施：

     • wiki-config 可用： 严格按以下模式输出——"你的 Wiki 缺少 wiki-schema.md。运行 /wiki-config 部署该文件并完成设置。完成后我再继续。" 本轮到此结束。不要提供随附的部署方案，也不要给出其他选项。wiki-config 的引导式流程是正确路径。

     • wiki-config 不可用： 提供随附的备用方案——"你的 Wiki 缺少 wiki-schema.md，且未安装 wiki-config 技能。我可以从随附的参考文件部署默认版本，但建议安装 wiki-config 以使用引导式设置。要部署随附的默认版本吗？" 等待用户明确确认。用户同意后，从 references/wiki-schema.md 部署。

   • 格式错误 → 停止。采用相同的两种分支：

     • wiki-config 可用： "你的 wiki-schema.md 格式错误。运行 /wiki-config——它提供引导式修复流程，并会保留你所做的自定义设置。我会等你处理完。" 本轮到此结束。不要尝试修复，也不要用随附版本覆盖。

     • wiki-config 不可用： 指引用户参考 references/setup-help.md 手动修复。如果用户明确要求重置（而不是自动采用备用方案），请警告这会覆盖所有自定义设置；只有在用户明确同意后，才部署默认版本。

   如果第 4 步发现 wiki-config.md 本身格式错误，也适用同样的两分支结构：wiki-config 可用 → 停止并建议运行 /wiki-config，本轮结束；不可用 → 通过 setup-help.md 引导手动修复。

6. 完全找不到配置：请用户提供 Wiki 根目录路径，并在该路径下搜索（最多 5 层）。如果仍然找不到，说明用户尚未创建 Wiki——按上面的“缺失”分支处理（建议运行 /wiki-config；如果该技能不可用，则提供随附的部署方案）。

---

能力要求

此技能需要文件系统读取权限（扫描所有页面）和对 archive/ 的写入权限（保存 lint 报告）。如果没有读取权限，此技能无法继续。---

工作流

配置发现步骤已将 wiki-config.md 和 wiki-schema.md 加载到上下文中。不要重新读取；从这里继续，并假设这两个文件都已可用。

第 1 步 - 构建页面清单

递归列出知识库中的所有 .md 文件。完全排除 blacklist 中的路径；不要扫描其中的内容。index_excludes（raw\、archive\、ingested\）中的路径不作为 wiki 页面，但仍可读取以验证链接目标：如果一个有效的 wiki 页面链接到 archive/ 或 ingested/ 中的文件，该链接必须能解析到真实文件。根据同时位于 blacklist 和 index_excludes 之外的文件，构建范围内页面集合。另外，列出黑名单路径、raw\、archive\ 和 ingested\ 之外的所有非 Markdown 文件，作为潜在的孤立二进制资源。

第 2 步 - 读取 index.md

读取 index.md。解析所有维基链接引用和文件路径。构建 index.md 中列出的页面及其引用路径的集合。

第 3 步 - 检查失效的维基链接

对每个范围内的 wiki 页面，提取所有 [[wikilinks]]。尝试将每个链接解析到实际文件。如果找不到匹配文件：将其标记为失效的维基链接，并注明发现该链接的页面、失效的链接文本，以及明显时可提供的修正建议。

还要标记：任何包含指向 raw/ 的链接的 wiki 页面。wiki-ingest 将文件移至 ingested/ 后，指向 raw/ 的源文件链接将失效。将这些标记为未来失效警告："[[Page]] links to raw/: will break after ingestion. Update to ingested// once ingest is complete." 这些链接目前尚未失效，但之后一定会失效。

第 4 步 - 检查孤立页面

对范围内的每个页面，检查：

• 是否列在 index.md 中？
• 是否被其他范围内页面中的维基链接引用？

如果两者都不是：将其标记为孤立页面。新页面可能是合理的孤立页面；仍需标记，由人工判断。

第 5 步 - 检查过时的索引条目

对 index.md 中列出的每个页面，检查所引用的文件是否存在。如果不存在：将其标记为过时的索引条目。

第 5b 步 - 检查过长的索引条目

对 index.md 中的每个条目，测量单行描述（]]: 与末尾的 `path` 之间的文本）。如果超过 150 个字符，将其标记为过长的索引条目（软性警告）。每次运行时，每项操作技能都会完整读取 index.md，因此过长的描述会增加每次运行的成本。建议的修正方法：精简至最多 150 个字符。

第 6 步 - 定性与结构检查

概念问题： 阅读 Overview.md 并检查明显的矛盾或过时信息；查找与特定 wiki 页面似乎相矛盾的说法，或明显过时的页面。仅做定性检查，不进行完整的内容审查。

缺少的关联： 扫描 index.md 中的描述，查找彼此没有链接的页面对之间的重要术语重叠。如果页面的索引描述共享多个关键概念，但没有相互的维基链接，则可能缺少关联。标记有实质性重叠的页面对；不要标记牵强的关键词巧合。这是一项轻量级启发式检查；如果用户认可关联确实存在，wiki-integrate 会负责实际添加链接。

第 6b 步 - 检查页面标题和文件名中的长破折号

页面文件名和 title: frontmatter 字段中的长破折号（—）是 LLM 输出中持续存在的问题。它们会导致维基链接失效（指向 [[Topic - Subtopic]] 的链接无法解析到名为 Topic — Subtopic.md 的文件），使页面无法通过预期名称搜索到，并违反知识库的长破折号规范。

对每个范围内页面：

1. 检查文件名是否包含任何 — 字符
2. 读取 title: frontmatter 字段，检查其中是否包含任何 — 字符

将每处都标记为长破折号违规，并注明文件路径、发现位置（文件名 / title 字段）、违规字符串，以及建议的修正方法：将 — 替换为 -（空格-连字符-空格）。

步骤 6c - 检查过时页面

对于每个范围内的页面，检查以下情况：

缺少日期字段（错误）： 如果页面的 frontmatter 中既没有 date:，也没有 updated:，则标记为缺少日期字段错误。两个字段都缺失，说明创建时出了问题——该页面不是由技能编写的，或者 frontmatter 格式错误。

过时（软警告）： 如果页面有 updated: 字段，且其日期距今天超过 90 天，则标记为过时页面。以下情况不纳入此检查：

• status: artefact、status: snapshot、status: archived —— 按定义已冻结
• page_type: reference —— 参考页面的内容大多是静态的，预期更新不频繁

没有 updated: 字段（但有 date:）的页面会被静默跳过——缺少 updated: 不算错误。

对每个过时页面，标记：路径、updated: 日期、距上次更新的天数。 对每个缺少日期字段错误，标记：路径、缺少哪些字段。

步骤 6d - Schema 合规性检查（来源信息字段）

对于每个范围内的页面，验证四个来源信息字段（status:、description:、source:、reliability:）。检查结果分为两类：

错误（硬性标记）：

• 有 source:，但没有 reliability: —— 存在 source:，但缺少 reliability:。这两个字段相互关联，缺少其中一个属于内部不一致。标记为schema 错误，并注明：路径、受影响的字段对。
• status: 值无效 —— 存在 status:，但其值不属于有效枚举值（active、stub、artefact、archived、snapshot）。标记为schema 错误，并注明：路径、字段、发现的无效值、有效值。
• reliability: 值无效 —— 存在 reliability:，但其值不属于（high、medium、low）。标记为schema 错误，并注明：路径、字段、发现的无效值、有效值。
• page_type: 值无效 —— 存在 page_type:，但其值不在 wiki-schema.md 定义的有效枚举列表中。标记为schema 错误，并注明：路径、字段、发现的无效值，以及 schema 中的有效值。

软警告（提示信息）：

• 由技能处理的页面缺少 status: 或 description: —— 页面有 updated:（表示技能在 3b 之后写入过该页面），且 page_type: 为 knowledge、research-note 或 survey，但缺少 status: 或 description:。没有 updated: 的旧页面会被静默跳过——它们早于 3b，后续再次处理时会补上这些字段。标记为缺少来源信息字段，并注明：路径、缺少的字段。
• 存在 source:，但没有 ## Sources 章节 —— frontmatter 中的 source: 表示内容有采集来源；正文应包含 ## Sources 章节，以便追踪补充信息。缺少该章节不属于硬性错误，但值得标记。标记为缺少 Sources 章节，并注明：路径。
• 由技能处理的页面缺少 page_type: —— 页面有 updated:（表示技能写入过该页面），但缺少 page_type:。没有 updated: 的页面会被静默跳过——它们早于此功能，后续再次处理时会补上该字段。标记为缺少 page_type，并注明：路径。

步骤 6e - 检查 log.md 大小

统计 log.md 中的 ## [ 条目数。log.md 只会在开头新增内容，而且 crystallize 和 lint 每次运行时都会完整读取，因此日志过大会持续占用上下文。如果条目超过 150 个，则标记为日志过大，并注明条目数和阈值（150）。lint 从不修改 log.md；解决方法是运行 wiki-crystallize，它会询问是否归档最早的条目，并保留最近的 50 条。

第 7 步 - 检查孤立的二进制资源

对于黑名单路径 raw\、archive\ 和 ingested\ 之外的每个非 Markdown 文件：在所有范围内页面中搜索对该文件名的引用。如果未找到：标记为孤立的二进制资源。如果文件在上下文中与相关内容放在一起（例如，某个领域子文件夹中的 PDF 被该领域的页面引用），则不算孤立；只有在任何位置都没有 Wiki 引用的文件才应标记。

第 7a 步 - 检查 ingested/ 中的孤立来源

ingested/ 中的每个文件都应至少由一个 Wiki 页面引用；引用应位于页面正文的 Sources 部分，并包含 ingested/ 路径。没有 Wiki 引用的来源已经处理过，却在知识图谱中没有留下任何痕迹。

对于 ingested/ 中的每个文件（包括所有子目录和 assets/）：

1. 在所有范围内的 Wiki 页面中搜索该文件的相对路径（例如 ingested/documentation/foo.md）。检查完整页面内容：## Sources 部分正文、changes: frontmatter 字段，或任何其他可能出现路径引用的位置。无论匹配出现在何处，都视为有效引用。
2. 如果未找到匹配项：标记为孤立来源："ingested/[subdir]/filename 没有 Wiki 页面引用它"

ingested/assets/ 中没有引用的来源属于预期情况（它在摄入时无法读取）；应以较低严重级别将其标记为备注而不是警告，以便用户知道它的存在，并在能力有所提升时重新尝试摄入。

第 8 步 - 编写 lint 报告

创建 [wiki-root]/archive/lint-YYYY-MM-DD.md：

---
title: Lint Report YYYY-MM-DD
date: YYYY-MM-DD
---

# Lint Report - YYYY-MM-DD

## Summary
- Broken wikilinks: N
- Future breakage warnings (raw/ links): N
- Orphan pages: N
- Stale index entries: N
- Over-length index entries: N
- Missing connections (candidates): N
- Em-dash violations (titles/filenames): N
- Missing date fields (errors): N
- Stale pages (updated: > 90 days): N
- Schema errors (invalid enum values, missing field pairs): N
- Missing provenance fields (skill-touched pages): N
- Missing page_type: (skill-touched pages): N
- Missing Sources sections: N
- Orphaned binary assets: N
- Orphaned sources in ingested/: N (+ N notes in assets/)
- Conceptual flags: N
- Log size: N entries (flagged if over 150)

## Broken Wikilinks
[page where found, broken link, suggested fix]

## Future Breakage Warnings
[page where found, raw/ link, suggested post-ingest destination]

## Orphan Pages
[page path, reason it may be orphaned]

## Stale Index Entries
[index entry, the path that no longer resolves]

## Over-length Index Entries
[index entry, current description length, suggested: tighten to 150 chars max]

## Missing Connections
[page pair, overlapping terms, suggested action: run wiki-integrate]

## Em-dash Violations
[file path, where found (filename / title field), suggested fix: replace — with ' - ']

## Missing Date Fields
[file path, which of date: / updated: are absent; likely indicates malformed frontmatter or non-skill creation]

## Stale Pages
[file path, updated: date, days since last touch; not flagged if status: artefact/snapshot/archived or page_type: reference]

## Schema Errors
[file path, field(s) affected, nature of error (invalid enum value / source: without reliability: / invalid page_type: value)]

## Missing Provenance Fields
[file path, which of status: / description: are absent; page has updated: and is a fact-establishing page_type]

## Missing page_type:
[file path, page has updated: but page_type: is absent; add page_type: using values from wiki-schema.md, or run wiki-integrate to infer and confirm]

## Missing Sources Sections
[file path, has source: in frontmatter but no ## Sources section in body]

## Orphaned Binary Assets
[file path, reason it has no wiki references]

## Orphaned Sources in ingested/
[file path, no wiki page references this source; consider re-ingesting or archiving]

## Notes: ingested/assets/
[file path, was unreadable at ingest time; re-attempt if capabilities have improved]

## Conceptual Flags
[page, nature of potential issue]

## Log Size
[log.md entry count; flagged if over 150 - run wiki-crystallize to archive the oldest entries, keeping the 50 most recent]

第 9 步 - 添加到 log.md 开头

在 log.md 顶部、标题行下方、所有现有条目上方添加新条目。

## [YYYY-MM-DD] lint | Full wiki pass
Summary: N broken links, N orphans, N stale entries, N missing connections, N date-field errors, N stale pages, N schema errors, N missing provenance/page_type fields, N orphaned assets.
Report: archive/lint-YYYY-MM-DD.md

第 10 步 - 呈现检查结果

报告摘要。不要提出自动修复。建议后续操作：

• 损坏的 Wiki 链接 -> 手动修复，或对受影响的页面运行 wiki-integrate
• 未来损坏警告 -> 下次摄入运行后，将 raw/ 链接更新为 ingested/ 路径
• 孤立页面 -> 运行 wiki-integrate；如果已弃用，则移至 archive/
• 过时的索引条目 -> 从 index.md 中移除，或更新路径
• 超长的索引条目 -> 将描述缩短至最多 150 个字符
• 缺少关联 -> 对标记的页面对运行 wiki-integrate
• 破折号违规 -> 重命名文件（将 — 替换为 -），并更新其 title: 字段；搜索指向旧名称的所有 Wiki 链接并更新
• 缺少日期字段 -> 检查页面；如果由 skill 编写，则说明 frontmatter 格式错误，应手动修复
• 过时页面 -> 检查并更新；如果页面有意冻结，则设置 status: artefact、snapshot 或 archived
• Schema 错误 -> 手动修复 frontmatter：在存在 source: 时添加缺失的 reliability:，并更正 status:、reliability: 或 page_type: 的无效枚举值
• 缺少来源信息字段 -> 对页面重新运行 wiki-ingest 或 wiki-crystallize，以补充 status: 和 description:；或者根据 schema 手动添加
• 缺少 page_type：-> 根据 wiki-schema.md 中的枚举值，在页面 frontmatter 中添加 page_type:；或者运行 wiki-integrate，由其推断并确认类型
• 缺少 Sources 部分 -> 在页面正文中添加 ## Sources 部分，并引用 source: 中的路径
• 孤立的二进制资源 -> 移至合适的位置；如果不需要，则删除
• ingested/ 中的孤立来源 -> 重新摄入源文件（将其放回 raw/ 并运行 wiki-ingest），或调查为何没有创建 Wiki 页面
• ingested/assets/ 中的备注 -> 如果有新的工具或能力可用，则重新尝试摄入
• 日志过大 -> 运行 wiki-crystallize；它会提供归档最旧日志条目的选项，并保留最近的 50 条

关键规则

1. 绝不修改 wiki 页面——只读，唯一例外是将 lint 报告写入 archive/
2. 绝不删除文件——仅标记；由人工决定
3. 不要将放置位置符合上下文的文件标记为问题——文件所在领域中有 wiki 引用，就不算孤立文件
4. 完全跳过列入黑名单的路径——lint 不会扫描黑名单目录中的内容
5. index_excludes 中的内容不是 wiki 页面，但可作为有效链接目标——即使 archive/ 和 ingested/ 不在页面清单中，仍可读取它们以解析链接
6. 报告应存放在 archive/，而不是 wiki 根目录

---

云同步保险库

存储在云同步服务中的保险库可能包含尚未下载到本地的文件，这些文件会显示为零字节占位符。如果读取文件时意外返回空内容，请将其标记为可能的同步问题，并在重试前询问用户确认。不要将零字节文件视为已成功处理的空文件。