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.

使用用户的语言编写文档内容。确保语法正确，并使用必要的变音符号或特定脚本字符。如果用户的语言不明确，在生成内容前先询问确认。

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的前置元数据或首页获取。保留名称和代码标识符的原样。向用户提交的报告需使用用户的语言。

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

。对于纯结构性检查（前置元数据、失效链接），使用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)
```
。
修复链接或创建缺失的页面。

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.

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

3. Frontmatter

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/
```
下的页面不应包含业务规则（定价、政策、用户旅程、盈利模式）。若存在此类内容，需将其迁移至
```
wiki/business/
```
，
```
apps/
```
下的页面仅保留交叉引用。
针对Wiki的
```
apps/
```
路径集合执行QMD查询，例如
```
intent: business rule (pricing/policy/monetization/cancellation)
```
，以检查是否存在内容越界情况。
对于项目同级的产品/代码仓库（根据项目规范，这些仓库应仅包含技术规则），使用
```
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风格的查询语句（例如
```
hyde: The cancellation policy is X hours with Y consequence
```
）执行QMD查询，并对比前几条结果。
若页面内容互相矛盾 → 在对应页面添加标记说明。

8. Outdated status

8. 状态过期检查

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

已完成且验证通过的
```
draft
```
（草稿）页面可改为
```
stable
```
（稳定）状态。
```
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
```
.

简单修复（前置元数据、链接、
```
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