wiki-lint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lint — Wiki health check

Lint — Wiki健康检查

wiki/CONVENTIONS.md

for format conventions, frontmatter, and links.

请遵循

wiki/CONVENTIONS.md

中的格式规范、frontmatter和链接规则。

Language

语言

Write the artifact in the user's language. Apply correct grammar and any required diacritics or script-specific characters. If the user's language is unclear, ask before generating output.

使用用户的语言编写产物。应用正确的语法以及所需的变音符号或特定脚本字符。如果用户的语言不明确，请在生成输出前询问。

Project root

项目根目录

This skill writes artifacts at paths relative to the project root (the repo where the work happens), not the agent's current working directory.

If invoked from inside the project, use the relative paths shown in this skill.
If invoked from another directory (e.g., a sibling repo, or when the project lives elsewhere), prepend
```
<project-root>/
```
to every artifact path.
When the project root is ambiguous, confirm with the user via the harness question tool before writing.

本Skill会在相对于项目根目录（执行工作的仓库）的路径下编写产物，而非Agent的当前工作目录。

如果从项目内部调用，请使用本Skill中所示的相对路径。
如果从其他目录调用（例如，同级仓库，或项目位于其他位置），请在每个产物路径前添加
```
<project-root>/
```
。
当项目根目录不明确时，请在编写前通过harness问题工具与用户确认。

Prompting

提示规范

Follow the project-wide convention in

CLAUDE.md

AGENTS.md

("Skill Prompting Conventions"). Use the harness's structured-question tool —

AskUserQuestion

(Claude Code),

ask_user_question

(Codex), or

question

(OpenCode) — for the decision points below. Use free-form text only where a path/name/value cannot be enumerated.

Decision point	Why structured	Suggested options
Scope (multi-select)	Affects what is checked	Frontmatter · Links · Drift · Empty subfolders · All
Auto-fix safe issues	Hard-to-undo edits	Report-only · Auto-fix · Ask per issue

Free-form prompts (no structured tool):

Custom rule descriptions

No-pause mode: if the user has explicitly disabled mid-skill clarification, convert every structured prompt into an entry under Open questions (or equivalent) and proceed without blocking.

遵循

CLAUDE.md

AGENTS.md

中的项目级规范（“Skill提示规范”）。对于以下决策点，使用harness的结构化问题工具：

AskUserQuestion

（Claude Code）、

ask_user_question

（Codex）或

question

（OpenCode）。仅当路径/名称/值无法枚举时，才使用自由格式文本。

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

自由格式提示（不使用结构化工具）：

自定义规则描述

无暂停模式：如果用户明确禁用了Skill执行中的澄清环节，请将每个结构化提示转换为“未解决问题”（或等效项）下的条目，然后继续执行而不中断。

Query language alignment

查询语言对齐

For semantic lint checks, query in the wiki language. Determine it from

.wiki-guardrails.yml

(

query_language

language

), then from wiki frontmatter/index if guardrails are absent. Preserve exact names and code identifiers. Reports to the user should remain in the user's language.

对于语义lint检查，请使用Wiki的语言进行查询。首先从

.wiki-guardrails.yml

（

query_language

或

language

）中确定语言，如果没有防护配置文件，则从Wiki的frontmatter或首页确定。保留确切的名称和代码标识符。向用户提交的报告应使用用户的语言。

Retrieval — prefer QMD when available

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

Use QMD (local hybrid search) for the semantic checks (orphans, missing cross-refs, contradictions). Setup is one-time per repo — see

docs/wiki/qmd-setup.md

. For purely structural checks (frontmatter, broken links), grep/glob is fine and faster.

Use
```
mcp__qmd__query
```
(MCP) or
```
qmd query --json --files
```
(CLI) when looking for semantic neighbors of a page (orphan candidates, contradiction candidates, missing cross-refs).
Always pass an
```
intent:
```
line to QMD describing what you are looking for.
Do not run
```
qmd embed
```
/
```
qmd update
```
automatically — flag the need at the end of the lint if the wiki has changed and the index is stale.

使用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结束时标记需要执行此操作。

Checklist

检查清单

Go through the items in order. If the user asked for something specific (e.g., "just the links"), focus on that part.

按顺序完成以下项目。如果用户有特定要求（例如，“只检查链接”），则专注于该部分。

1. Broken cross-refs

1. 无效交叉引用

Relative links
```
[text](./path.md)
```
that point to nonexistent pages.
Fix the link OR create the missing page.

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

2. Orphan pages

2. 孤立页面

Wiki pages (except
```
CONVENTIONS.md
```
,
```
index.md
```
,
```
log.md
```
) with no inbound link in
```
wiki/index.md
```
.
For each orphan candidate, run a QMD query with
```
intent: page describing <topic of orphan>
```
to find which existing pages should link to it.
If it has valid content → add it to
```
index.md
```
and add cross-refs from semantically-adjacent pages.
If irrelevant → suggest deletion to the human.

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

3. Frontmatter

All wiki pages must have:

Field	Required	Validation
`title`	yes	Present and not empty
`audience`	yes	One of: `business` , `dev` , `ops` , `mixed`
`sources`	yes	Non-empty list
`updated`	yes	ISO date. Flag if > 90 days
`tags`	yes	Non-empty list
`status`	yes	One of: `draft` , `stable` , `stale`

所有Wiki页面必须包含以下字段：

字段	是否必填	验证规则
`title`	是	存在且非空
`audience`	是	可选值： `business` 、 `dev` 、 `ops` 、 `mixed`
`sources`	是	非空列表
`updated`	是	ISO日期。如果超过90天则标记
`tags`	是	非空列表
`status`	是	可选值： `draft` 、 `stable` 、 `stale`

4. raw/ ↔ wiki/sources/ consistency

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

Cross-reference

raw/index.md

with

wiki/sources/

Sources without summary — referenced in
```
raw/index.md
```
as ingested but missing
```
<slug>.md
```
.
Summaries without source —
```
wiki/sources/<slug>.md
```
whose
```
sources:
```
points to a nonexistent file.

交叉比对

raw/index.md

与

wiki/sources/

：

无摘要的源文件 — 在
```
raw/index.md
```
中被引用为已导入，但缺少
```
<slug>.md
```
。
无源文件的摘要 —
```
wiki/sources/<slug>.md
```
的
```
sources:
```
指向不存在的文件。

5. Audience boundary check

5. 受众边界检查

Pages in
```
wiki/apps/
```
should not contain business rules (pricing, policies, journeys, monetization). If they do, those rules must move to
```
wiki/business/
```
and the
```
apps/
```
page should keep only a cross-ref.
Run a QMD query like
```
intent: business rule (pricing/policy/monetization/cancellation)
```
against the wiki collection (path-prefixed to
```
apps/
```
) to spot leakage inside the wiki itself.
For product/code repos that the project keeps as siblings (and that the project's convention says should hold only technical rules), audit them with
```
grep
```
/
```
Read
```
rather than indexing them into QMD. Indexing those repos blurs the "wiki is canonical" boundary by inviting agents to treat product-repo prose as authoritative. Surface any business-rule language found as a candidate for migration into
```
wiki/business/
```
.

```
wiki/apps/
```
中的页面不应包含业务规则（定价、政策、流程、monetization）。如果包含，这些规则必须移至
```
wiki/business/
```
，且
```
apps/
```
页面应仅保留交叉引用。
针对Wiki集合（路径前缀为
```
apps/
```
）运行QMD查询，例如
```
intent: business rule (pricing/policy/monetization/cancellation)
```
，以发现Wiki内部的内容越界情况。
对于项目作为同级仓库保存的产品/代码仓库（且项目规范规定这些仓库应仅包含技术规则），使用
```
grep
```
/
```
Read
```
进行审计，而非将其索引到QMD中。将这些仓库索引到QMD会模糊“Wiki是权威来源”的边界，导致Agent将产品仓库中的文本视为权威内容。将发现的任何业务规则语言标记为需要迁移到
```
wiki/business/
```
的候选内容。

6. Missing cross-refs

6. 缺失交叉引用

For each substantive wiki page, run a QMD query for its title/topic and inspect the top 5-10 hits. Pages that semantically belong together but do not link should be flagged.
Suggest to the human (do not fix automatically — it may introduce noise).

对于每个实质性Wiki页面，针对其标题/主题运行QMD查询，检查前5-10个结果。标记语义相关但未互相链接的页面。
向人工提出建议（不要自动修复 — 可能会引入冗余内容）。

7. Contradictions

7. 矛盾内容

For each topic that appears on multiple pages, run QMD for a hyde-style query of the canonical statement (e.g.
```
hyde: The cancellation policy is X hours with Y consequence
```
) and compare the top hits.
If pages contradict each other → flag with a note on the page.

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

8. Outdated status

8. 过时状态

```
draft
```
that could be
```
stable
```
(complete and validated content).
```
stable
```
with
```
updated
```
> 90 days → consider marking as
```
stale
```
.

可标记为
```
stable
```
的
```
draft
```
页面（内容完整且已验证）。
```
updated
```
超过90天的
```
stable
```
页面 → 考虑标记为
```
stale
```
。

9. index.md statistics

9. index.md 统计信息

Does the page count match reality?
Are page descriptions up to date?

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

10. QMD index health (only if QMD is configured)

10. QMD索引健康状况（仅当已配置QMD时）

Call
```
mcp__qmd__status
```
(or
```
qmd status
```
).
If
```
needsEmbedding > 0
```
→ tell the owner to run
```
qmd embed
```
.
If file count in
```
wiki/
```
differs significantly from
```
totalDocuments
```
for the wiki collection → tell the owner to run
```
qmd update
```
.

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

Behavior

行为规范

Simple fixes (frontmatter, links,
```
updated
```
) → do them automatically.
Content changes → ask the human first.
Response to the human: focus on the actionable:
1. Pending items that need a human decision
2. Improvement opportunities
3. Numerical summary (total issues / automatic fixes)
4. QMD reindex commands the owner needs to run (if any)
Do not list all automatic fixes in the response — the detail goes into
```
log.md
```
.

简单修复（frontmatter、链接、
```
updated
```
字段）→ 自动执行。
内容变更 → 先询问人工。
向人工反馈：聚焦于可执行事项：
1. 需要人工决策的待处理项
2. 改进机会
3. 数值汇总（总问题数 / 自动修复数）
4. 所有者需要运行的QMD重新索引命令（如果有）
不要列出所有自动修复的详情 — 细节记录在
```
log.md
```
中。

Logging

日志记录

Update

wiki/log.md

(insert at the top, after the header):

undefined

更新

wiki/log.md

（插入到顶部，标题之后）：

undefined

[YYYY-MM-DD] lint | health check

Automatic fixes

Pending (human decision)

Suggestions

QMD reindex needed

qmd update / qmd embed (only if applicable)

undefined

qmd update / qmd embed (only if applicable)

undefined