opencode-wiki-historian 0.3.0 → 0.5.0

package/README.md

@@ -6,12 +6,15 @@ opencode-historian 把 wiki.js 的读写、翻译、页型规范、迁移工具
 
 功能一览:
 
-* 10 个 `historian_*` 工具，覆盖创建、更新、追加、翻译、搜索、阅读、地图/时间轴、迁移、删除、移动
+* 10 个 `historian_*` 工具，覆盖创建、更新、追加、翻译、搜索、阅读、地图/时间轴/维护报告、迁移、删除、移动
 * Skill v5 随插件自动注入（config hook），无需手动安装 skill 文件
-* G1 至 G5 页型契约，每种页型对应专属骨架模板
+* G1 至 G6 页型契约，每种页型对应专属骨架模板（v4 新增 G6 操作手册/how-to）
 * 双语孪生页面（en/zh）自动翻译，翻译引擎可配置
-* 页面地图缓存、本地镜像与时间轴聚合视图
-* 开工前置查阅回路（reading loop，默认关，双信号启用）+ `/historian-capture` 会话留痕（默认关）
+* 页面地图缓存、本地镜像、时间轴聚合视图与 `maintain` 维护策展报告（light/deep 两档）
+* `options.sections` 路径前缀白名单强制生效：配置非空时越界写入硬拒（`ConfigError`，请求发出前拒绝）；`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence` 系统路径恒豁免；默认 `[]` = 不限制
+* `historian_search` 标签过滤：`tags` 1-5 个，`tagsMode` 默认 `all`（服务端 AND）、`any` 为客户端逐标签 fan-out 求并集
+* 顶层 `home` 落地页解锁：仅豁免精确顶层 `home`，其余保留字（login/register/graphql/healthz/_assets/favicon）与嵌套 `home` 照旧拒绝
+* 开工前置查阅回路（reading loop，默认关，双信号启用；v4 advisory：先查索引、update 优先、引页引日期、标注过期）+ `/historian-capture` 会话留痕（默认关）
 * 试点与评测均通过：pilot 7 页迁移 PASS，eval 7/7 场景首跑全过
 
 ## 史官宣言 / The Historian's Manifest
@@ -28,7 +31,7 @@ opencode-historian 把 wiki.js 的读写、翻译、页型规范、迁移工具
 | 法文 | 中立、非个人化、清晰、精确、易懂、有教学性六种品质；溢美词强制转成事实（用排名、奖项、销量替代"最伟大的"这类断言）；耐久过滤：明天就会过时的内容不值得写 |
 | 俄文 | ХС/ИС 条目门槛（导言普通读者可懂、术语最少、不少于 10 行）；二手权威来源优先于一手（АИ）；每种观点按影响力分配篇幅、禁止虚假平衡（ВЕС）；风格要求精确、简明、无歧义，同时保持内容饱和 |
 
-SRE postmortem 文化单独值得点名：它把"事件"当一等文档对待，过程/原因/后果/改进四段式正是 `/historian-capture` 命令的输出协议（`src/index.ts` 的 capture 模板），而"改进项要有负责人和可验证终态"落在了 G1 行动项表格里。
+SRE postmortem 文化单独值得点名：它把"事件"当一等文档对待，先证据后结论的证据链四段式（`src/index.ts` 的 `CAPTURE_COMMAND_TEMPLATE` 模板）正是 `/historian-capture` 命令的正文契约：证据链→方法→修复手段→函数级实现，而"改进项要有负责人和可验证终态"落在了 G1 行动项表格里。
 
 把这些文化做成插件的直接动因，是一个机构记忆问题：这台机器由一个人加一群 AI agent 操作。会话结束，终端滚动条就没了；上下文压缩，细节就丢了。部署过什么、发生过什么事故、踩过什么坑、做过什么决定，三个月后人和 AI 都无从查起。史官要解决的，就是让这台机器的历史变得可检索。
 
@@ -42,18 +45,28 @@ SRE postmortem 文化单独值得点名：它把"事件"当一等文档对待，
 
 ### 作用 / What it does
 
-五柱页型契约，加上读写两条自动化回路：
+六柱页型契约，加上读写两条自动化回路：
 
 | 能力 | 机制 | 落点 |
 |---|---|---|
-| 五柱页型 | G1 事件复盘 / G2 对比选型 / G3 清单索引 / G4 概念原理 / G5 现状账本，写前声明页型，套固定骨架、过来源列检查 | `src/templates/genres.ts`，skill Phase 1.5 |
-| 双视图 | 地图视图（en/zh 对应关系，Locale/Twin 列）+ 时间轴视图（ISO 周分组，支持 `days` 窗口与 `path` 前缀过滤，人读周表 + 机读 weeks JSON） | `historian_map` 的 `action:'show'` / `action:'timeline'` |
+| 六柱页型 | G1 事件复盘 / G2 对比选型 / G3 清单索引 / G4 概念原理 / G5 现状账本 / G6 操作手册，写前声明页型，套固定骨架、过来源列检查 | `src/templates/genres.ts`，skill Phase 1.5 |
+| 三视图 | 地图视图（en/zh 对应关系，Locale/Twin 列）+ 时间轴视图（ISO 周分组，支持 `days` 窗口与 `path` 前缀过滤，人读周表 + 机读 weeks JSON）+ 维护策展报告（`action:'maintain'`：双语缺口、近似重复标题、过期、孤儿候选、标签词表、章节分布；light 档只扫地图行加每 locale 一次 `pages.list`，`deep:true` 逐页读正文补新鲜度标记与 Redirect 存根识别） | `historian_map` 的 `action:'show'` / `'timeline'` / `'maintain'` |
 | 迁移与评分门禁 | 存量页按骨架重排：dry-run 评分在前，`apply=true` 自动 pre-image 备份；每页写入后过 10 项自检门 | `historian_migrate`，`selfReviewChecklist()` |
-| 前置查阅回路 | 向每次请求的 system 提示注入"先查 wiki"指令（单块合并：追加到最后一个 system 块，绝不产生第二条 system 消息；双信号门控：选项与本机哨兵文件同时到位才注入）：动这台机器的部署/历史/坑/决定之前先 `historian_search`、查 timeline、核对 G5 卡的核实日期，引用查过的页面 URL | `readingLoop` 选项（默认 false，开启需配置+哨兵双确认）+ 哨兵文件 `~/.config/opencode/historian-reading-loop.json`，`src/index.ts` 的 `experimental.chat.system.transform` 钩子 |
+| 前置查阅回路 | 向每次请求的 system 提示注入"先查 wiki"指令（单块合并：追加到最后一个 system 块，绝不产生第二条 system 消息；双信号门控：选项与本机哨兵文件同时到位才注入）：v4 advisory 四条——先读 `wiki-index` / `historian_map show` 定位再 `historian_search`（index-first）；update 优先于 create；引用页面时带 URL 与日期；发现矛盾/过期在页内标注（supersede 或复核章）而非静默覆盖，G5 账本逐行核对「上次核实于」 | `readingLoop` 选项（默认 false，开启需配置+哨兵双确认）+ 哨兵文件 `~/.config/opencode/historian-reading-loop.json`，`src/index.ts` 的 `experimental.chat.system.transform` 钩子 |
 | 主动留痕 | `/historian-capture` 命令把当前会话总结成 G1 事件页；开启 `capture.enabled` 后额外在会话空闲时弹一次提醒，仅提醒，绝不自动写页 | `src/index.ts` 的 `config` / `event` 钩子 |
 
 G5 现状卡回答"现在跑着什么"，timeline 回答"最近两周变了什么"。比如问"`service-a` 现在监听哪个端口"，应当命中现状账本里的一行（形如 `example.com:8000`，带上次核实日期与验证命令），而不是某次会话的聊天记录。这两样合起来，wiki 才从文档堆变成可查询的运维账本。
 
+知识库要同时满足四种诉求——档案、手册、百科、知识库（速查）。六柱页型加索引层按层分工：
+
+| 层诉求 | 回答的问题 | 对应页型 | 承载机制 |
+|---|---|---|---|
+| 档案 | 发生过什么、现在跑着什么 | G1 事件复盘 + G5 现状账本 | G1 时间线带来源列；G5 每行带「上次核实于」+ 验证命令 |
+| 手册 | 怎么把一件事做完 | G6 操作手册 | 目标句式标题、步骤三段（动作+预期结果+失败处置）、上次核实+复核周期 |
+| 百科 | 它是什么、为什么 | G4 概念原理 | 概念定义 → 图示 → 示例 |
+| 知识库（速查） | 该选哪个、去哪查 | G2 对比选型 + G3 清单索引 | 对比表带来源列；可勾选检查项 |
+| 索引层 | 从哪读起 | ——（不是页型） | `wiki-index` 人策展目录 + `historian_map` 的 show/timeline/maintain |
+
 ### 使用方式 / Usage
 
 端到端最短路径（适配你自己 wiki 的六步完整指南见 `skills/historian/references/adapting-your-own-wiki.md`）：
@@ -74,7 +87,7 @@ G5 现状卡回答"现在跑着什么"，timeline 回答"最近两周变了什
    > `service-a` 今天 OOM 重启，根因是缓存没设上限，已加告警，记下来。
 
    → 分诊为事件复盘，声明 G1 → `historian_page_create`（`genre: "G1"`）→ 回报 `http://<your-wiki>:3000/team-notes/<slug>` 与它的 `/zh/` 孪生页。
-4. **检索与整理**：`historian_search` 按主题查；`historian_map` 的 `show` 看双语地图、`timeline`（可选 `days` / `path`）看最近变动；存量页不合规用 `historian_migrate` 先 dry-run 再 apply。
+4. **检索与整理**：`historian_search` 按主题查，可按标签过滤（`tags` 1-5 个，`tagsMode` 默认 `all` 即服务端 AND，`any` 为客户端逐标签 fan-out 并集）；`historian_map` 的 `show` 看双语地图、`timeline`（可选 `days` / `path`）看最近变动、`maintain`（可选 `deep:true`）出维护策展报告；存量页不合规用 `historian_migrate` 先 dry-run 再 apply。
 5. **开关**：reading loop 默认 false，开启需配置+哨兵双确认，两步缺一不可：
 
    1. 插件二元组第二参数写 `"readingLoop": true`：`["opencode-wiki-historian", { "readingLoop": true }]`
@@ -179,14 +192,14 @@ opencode run --command historian --message "historian_map show"
 | `translate.model` | string | `qwen3.7-plus` | 翻译模型 |
 | `translate.apiKey` | string | 见下方链 | 翻译 API 密钥 |
 | `translate.providerKey` | string | 未配置 | jsonc 兜底腿读取的 provider 名；须显式设置才会启用该腿 |
-| `sections` | string[] | `[]`（不限制） | 插件可操作的 wiki 路径前缀白名单 |
+| `sections` | string[] | `[]`（不限制） | 写入路径前缀白名单。v4 起强制生效：非空时 create/update/append/delete/move(目标路径) 在发出请求前做 `sectionGuard` 检查，越界返回 `ConfigError`；`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence` 恒豁免；按首路径段匹配、区分大小写 |
 | `locales` | string[] | `["en", "zh"]` | 启用的语言列表 |
 | `readingLoop` | boolean | `false` | 开工前置查阅 advisory，向每次请求注入"先查 wiki"提示；默认 false，true 需配置+哨兵双确认（见「使用方式」开关步骤）；单块合并追加到最后一个 system 块，绝不产生第二条 system 消息，vLLM 等拒绝多条 system 的严格后端同样安全 |
 | `capture.enabled` | boolean | `false` | 开启后会话空闲时弹一次 `/historian-capture` 留痕提醒；仅提醒，不自动写页 |
 
 `translate.endpoint` 解析链（优先级从高到低）：`translate.endpoint` 选项 → 环境变量 `HISTORIAN_TRANSLATE_ENDPOINT` → 未配置。包内**不**内置任何网关地址；未配置时翻译调用直接以 `translate.endpoint not configured` 失败（见降级行为）。
 
-`sections` 默认为空列表 = 不限制路径前缀（任意合法路径可写，实际权限由 wiki.js token 的 page rules 决定）。按机器通过选项传入白名单，例如 `["team-notes", "infra", "ops"]`。
+`sections` 默认为空列表 = 不限制路径前缀（任意合法路径可写，实际权限由 wiki.js token 的 page rules 决定）。按机器通过选项传入白名单，例如 `["team-notes", "infra", "ops"]`。传入非空列表即强制生效（v4）：五个写入工具先过 `sectionGuard`（`src/tools/shared.ts`），不在白名单内的路径直接以 `ConfigError` 拒绝、不发任何写请求；报错信息会点名越界的首段并提示把它加进 `sections`。两个细节：匹配按首路径段、区分大小写，`doc` 授权 `doc` 与 `doc/x` 但不授权 `docs/x`；配置项首尾斜杠可省。`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence` 是插件自记账与索引胶水所需，恒豁免。
 
 ### API Key 获取优先级
 
@@ -212,6 +225,7 @@ key 缺失时 `ConfigError` 记录一次日志，插件工具全部禁用，open
 | 现象 | 定性 | 说明 |
 |---|---|---|
 | 裸配置未传 `translate` 选项（三段 key 链 `translate.apiKey` → `DASHSCOPE_API_KEY` → `translate.providerKey` 全缺）时插件工具全部禁用 | by design | 翻译腿是写操作的前提，缺 key 时宁可整体禁用也不静默半成品；配置按上方选项全表补齐即恢复。缺配置时的部分降级（工具照常注册、仅翻译调用失败）在议 |
+| 自进化驱动（readingLoop + capture）默认关闭，作者本机也尚未点亮 | 状态如实 | 两个开关缺省均为 `false`（`src/config.ts:100` `DEFAULT_READING_LOOP`、`src/config.ts:102` `DEFAULT_CAPTURE_ENABLED`），readingLoop 还需配置+哨兵双确认。v0.4.0 发布仍待人工 2FA 步骤（`npm publish` 需 OTP），本机启用要等发布落地后进行；回路代码与测试已就绪，但在真正点亮之前本文档不假装它在跑 |
 
 ## wiki.js 前置检查 / Prerequisites
 
@@ -263,11 +277,13 @@ zh: http://<host>/zh/ops/example
 
 **时间轴视图**：`historian_map action:'timeline'` 把镜像行按 ISO 周分组（可选 `days` 窗口与 `path` 前缀过滤），输出人读周表 + 机读 `weeks` JSON，回答"最近哪些页面变过"。
 
+**维护视图**：`historian_map action:'maintain'` 输出策展报告——双语缺口、近似重复标题、过期页面、孤儿/扩散候选、标签词表、章节分布。默认 light 档只扫地图行加每个 locale 一次 `pages.list`；`deep:true` 逐页读正文，补新鲜度标记与 Redirect 存根识别。
+
 ## 写作质量体系 / Quality System
 
-### G1 至 G5 页型
+### G1 至 G6 页型
 
-插件根据内容形态把每页归入五种页型之一，每种有专属骨架模板：
+插件根据内容形态把每页归入六种页型之一，每种有专属骨架模板：
 
 | 页型 | 用途 | 骨架结构 |
 |---|---|---|
@@ -276,10 +292,11 @@ zh: http://<host>/zh/ops/example
 | G3 清单 | 操作步骤、检查项 | 可勾选的检查项列表 |
 | G4 概念 | 架构说明、原理讲解 | 概念定义 → 图示 → 示例 |
 | G5 现状账本 | 此刻的部署/运行态，回答"现在跑着什么" | 状态块 → 部署物清单（每行带「上次核实于」+ 验证命令）→ 失效策略，禁止叙事正文 |
+| G6 操作手册 | how-to，回答"怎么把一件事做完"，目标句式标题 | 前置条件 → 操作步骤（每步含预期结果+失败处置）→ 回退 → 元数据表（上次核实 + 复核周期）→ 相关页面 |
 
 ### 10 项自检门
 
-每页写入后过一遍自检清单（源码 `src/templates/genres.ts` `selfReviewChecklist()`，参考文件 `skills/historian/references/rules.md` + `genres.md`）。dry-run 阶段评 1–8，apply 后评 9–10。genre-specific 条目对不匹配的页型记 N/A=PASS；G5 页的第 4–6 项换成账本变体（`G5_CHECKLIST_VARIANTS`）：
+每页写入后过一遍自检清单（源码 `src/templates/genres.ts` `selfReviewChecklist()`，参考文件 `skills/historian/references/rules.md` + `genres.md`）。dry-run 阶段评 1–8，apply 后评 9–10。genre-specific 条目对不匹配的页型记 N/A=PASS；G5 页的第 4–6 项换成账本变体（`G5_CHECKLIST_VARIANTS`），G6 页换成手册变体（`G6_CHECKLIST_VARIANTS`）：第 4 项要求标题是目标句式 "How to X" / "如何/怎么做X"，第 5 项要求每条操作步骤三段（动作 + 预期结果 + 失败处置），第 6 项要求元数据表含「上次核实」与「复核周期」行：
 
 1. **导言占比 10–15%**：导言 ≈ 正文的 10–15%，每个重要小节在导言至少占一句
 2. **句长上限**：中文句 ≤20 字、英文句 ≤25 词
@@ -302,7 +319,7 @@ wiki 内容按读者分三层，工具按层执行不同语义（`historian_page
 
 | 层 | 位置 | 职责 |
 |---|---|---|
-| 前台 (front) | 主题章节的 G1-G5 页 | 人写人读的知识页；双语孪生、进索引；只放提炼后的内容与链接 |
+| 前台 (front) | 主题章节的 G1-G6 页 | 人写人读的知识页；双语孪生、进索引；只放提炼后的内容与链接 |
 | 后台 (backstage) | `_meta/` 页 + 本地镜像文件 | 机器记账：page-map 缓存页、迁移 checkpoint、reading loop 哨兵文件；不参与人读正文 |
 | 证据 (evidence) | `_evidence/` | 超 10 行原始件（日志、转写、大 diff）的归宿：单语 en、不发布（匿名访问 404 是 by design），人类页面只链接不复制 |
 
@@ -407,7 +424,7 @@ harness repo（与本插件仓库同工作区）提供 7 个行为验收场景
 
 ```bash
 npm run build       # tsc 编译到 dist/
-npm test            # vitest run（331 tests, 15 files）
+npm test            # vitest run（493 tests, 20 files）
 npm pack --dry-run  # 检查打包文件列表
 ```
 

package/dist/index.js

@@ -40,29 +40,47 @@ const skillsDir = fileURLToPath(new URL('../skills/', import.meta.url));
 function unique(items) {
     return [...new Set(items)];
 }
-/** Reading-loop advisory (plan v2 todo 8): the machine wiki is the
- *  authoritative institutional memory; consult it before acting, cite URLs.
- *  Shipped text — generic wording only (privacy-audit scans dist). */
+/** Reading-loop advisory (plan v4 todo 8 / D6): the machine wiki is the
+ *  authoritative institutional memory; consult it index-first before acting,
+ *  prefer updating over duplicating, cite pages+dates, mark staleness.
+ *  Hard budget ≤8 lines (context-rot). Shipped text — generic wording only
+ *  (privacy-audit scans dist). */
 const READING_LOOP_ADVISORY = [
     'You have a historian: a wiki.js knowledge base acting as this machine\'s authoritative institutional memory.',
-    'Before doing work that touches this machine\'s deployments, history, pitfalls, or decisions, consult it first:',
-    '- historian_search by topic for relevant pages; historian_map action:"timeline" for what changed recently;',
-    '- G5 current-state ledger pages answer "what is deployed/running now" — check each row\'s verified date before trusting it.',
-    'Cite the wiki page URLs you relied on. If you learn something new worth keeping, offer to record it as a page.',
+    'Before doing work that touches this machine\'s deployments, history, pitfalls, or decisions, consult it index-first:',
+    '- Read the curated map before blind search: historian_read wiki-index or historian_map action:"show", then historian_search by topic;',
+    '- PREFER UPDATE over CREATE: if a page may already exist, historian_read it first, then historian_page_update rather than creating a duplicate;',
+    '- CITE evidence: name the wiki page URL and its date whenever you quote it;',
+    '- MARK stale rows instead of silently overwriting: supersede or review-stamp contradictions (G5 ledger: check each row\'s verified date).',
+    'If you learn something new worth keeping, offer to record it as a page.',
 ].join('\n');
-/** /historian-capture command (plan v2 todo 9): the always-available manual
- *  path from "notable session" to "G1 event page" — registered regardless of
- *  capture.enabled; the enabled-gated toast only nudges toward it. Agent-facing
- *  instruction text, generic wording only (ships in the tarball). */
+/** /historian-capture command (plan v2 todo 9, upgraded by v4 todo-10 / D2+D3):
+ *  the always-available manual path from "notable session" to "G1 event page" —
+ *  trigger list, 四段式 evidence-chain body contract, evidence split, and the
+ *  draft→review→Active publish flow are the drive surface (idle toast is
+ *  non-observable; this template text is the contract). Registered regardless
+ *  of capture.enabled; the enabled-gated toast only nudges toward it.
+ *  Agent-facing instruction text, generic wording only (ships in the tarball).
+ *  Context-rot budget ≤~30 lines. */
 const CAPTURE_COMMAND_DESCRIPTION = '把本次会话记为史官事件页 / record this session as a historian event page';
 const CAPTURE_COMMAND_TEMPLATE = [
-    'Summarize the current session as a historian G1 event page (an append-only record of what happened).',
+    'Summarize the current session as a historian G1 event page — only if it produced capture-worthy knowledge.',
     '',
-    '1. Draft four sections: 过程/Process (what was done, in order), 原因/Cause (why it was needed), 后果/Consequence (impact, artifacts), 改进/Improvement (follow-ups, preventions).',
+    '0. Capture triggers — proceed only if at least one matches, else say so and skip writing:',
+    '   事故闭环 incident closed with a root cause | 部署完成 deployment completed | bug修复合入 bugfix merged',
+    '   | 探针结论 probe/eval conclusion | 被否决方案 rejected option (record the 否决理由 veto reason).',
+    '1. Draft the body in the 四段式 evidence-chain order: 证据链/Evidence (what was observed, artifacts first)',
+    '   → 方法/Method (how it was proven) → 修复手段/Fix (what changed, or the decision) → 函数级实现/Implementation (file:symbol detail).',
     "2. Run historian_map action:'show' to see existing sections, then choose a short factual path under one.",
-    '3. If the session produced raw artifacts (logs, transcripts, big diffs), first store each via historian_page_create with tier:"evidence" under `_evidence/`, then cite those URLs in the G1 appendix.',
-    '4. Save with historian_page_create (genre "G1"); the zh twin is auto-created. If the session only repeated known knowledge, say so and skip writing.',
-    '5. Echo both page URLs (en + zh) back to the user.',
+    '3. Evidence split (G1 appendix contract): store the full 四段 material via historian_page_create with tier:"evidence"',
+    '   under `_evidence/`; the main page body stays the cited/summarized form linking to those evidence pages.',
+    '4. Carry SRE discipline in the 元数据表 metadata table rows: 影响/impact | 负责人/owner',
+    '   | 后续动作/action items (owner + 优先级/priority + verifiable done-state) | 来源类型/source type.',
+    '5. Pre-write self-check: create the page (genre "G1", 状态:draft, content included) so the 十项自检 scoring',
+    '   advisory runs on the draft; fix its FAIL items via historian_page_update before publishing.',
+    '6. Publish flow capture→review→Active: the page starts 状态:draft; once the self-check passes,',
+    '   historian_page_update it to Active. The zh twin is auto-created.',
+    '7. Echo both page URLs (en + zh) back to the user.',
 ].join('\n');
 const CAPTURE_TOAST_MESSAGE = '会话空闲：有值得留存的决定/修复/踩坑就跑 /historian-capture。Session idle — run /historian-capture if it produced decisions, fixes, or pitfalls worth keeping.';
 async function server(input, options) {

package/dist/lint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Body lint: one fence-aware pass over a page body producing the structural
+ * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
+ * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
+ * tools lint drafts before they hit the API. This is the module the
+ * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
+ * here was optional before, which is exactly how a page with five empty
+ * sections shipped for three days claiming `状态: Active`.
+ */
+import type { Locale } from './wiki/pages.read.js';
+/** Machine rule keys; the human report renders zh labels from these. */
+export type GateViolation = 'redirect-stub-no-exit' | 'active-with-unfinished-skeleton';
+export interface LintFinding {
+    readonly key: 'todo-markers' | 'empty-sections' | 'intro-empty' | 'no-related-pages' | 'no-state-block' | 'h1-mismatch' | 'zh-english-dominant' | 'claims-without-stamp';
+    readonly detail: string;
+}
+export interface PageLink {
+    /** Normalized wiki path (locale prefix stripped, leading `/` removed, no anchor/query). */
+    readonly path: string;
+    readonly locale: Locale;
+    /** True when the raw target was a same-page anchor (`#…`) — never resolved. */
+    readonly anchor: boolean;
+}
+export interface ClaimCounts {
+    readonly ports: number;
+    readonly paths: number;
+    readonly commands: number;
+}
+export interface BodyLint {
+    readonly isRedirectStub: boolean;
+    readonly redirectTarget: string | null;
+    readonly stubHasLink: boolean;
+    readonly hasStateBlock: boolean;
+    readonly state: 'active' | 'draft' | 'superseded' | 'deprecated' | null;
+    readonly todoMarkers: number;
+    /** Heading text of sections whose body (before the next heading ≤ level) is empty. */
+    readonly emptySections: readonly string[];
+    readonly introEmpty: boolean;
+    readonly hasRelatedPages: boolean;
+    readonly h1: string | null;
+    /** All heading spans in document order (twin-parity + structure checks). */
+    readonly headings: readonly HeadingSpan[];
+    readonly links: readonly PageLink[];
+    readonly hasStamp: boolean;
+    readonly claims: ClaimCounts;
+    readonly claimTotal: number;
+    /** CJK chars / non-whitespace chars, zh body only meaningful; 0..1. */
+    readonly cjkRatio: number;
+}
+export interface HeadingSpan {
+    readonly level: number;
+    readonly heading: string;
+    /** Subtree body: weighted length until the next heading ≤ level, INCLUDING
+     *  descendant sections' content (masked+comment-free). */
+    readonly bodyChars: number;
+    /** Direct body only: weighted length until the next heading at ANY level.
+     *  Used for the intro ratio so an H1 span never swallows the whole page. */
+    readonly directChars: number;
+}
+/** Section headings (##+) whose SUBTREE holds no content. A parent that groups
+ *  non-empty subsections is an outline container, not an unfinished product;
+ *  only wholly-empty subtrees indicate an unfilled skeleton section. */
+export declare function emptySectionsOf(headings: readonly HeadingSpan[]): readonly string[];
+export interface LinkScanOpts {
+    readonly baseUrl: string;
+}
+/** Extract internal page links (relative wiki paths + same-host absolute URLs). */
+export declare function extractLinks(masked: string, opts: LinkScanOpts): readonly PageLink[];
+export interface LintOpts {
+    readonly locale: Locale;
+    readonly baseUrl: string;
+    /** Page title for the h1-mismatch check. */
+    readonly title?: string;
+}
+export declare function lintBody(body: string, opts: LintOpts): BodyLint;
+/** Structural h1≠title flag (kept out of BodyLint's hot fields on purpose). */
+export declare function h1TitleMismatch(lint: BodyLint, title: string | undefined): boolean;
+/** The two hard publish-gate rules (shared.ts refuses the write on a hit). */
+export declare function publishGateViolations(lint: BodyLint): readonly GateViolation[];

package/dist/lint.js

@@ -0,0 +1,254 @@
+/**
+ * Body lint: one fence-aware pass over a page body producing the structural
+ * facts every hard gate and surface detector reuses (plan v0.5.0 #6).
+ * Pure functions, zero wiki I/O — the deep scanner injects bodies, the write
+ * tools lint drafts before they hit the API. This is the module the
+ * architecture-page audit (HANDOFF Issue #6) forced into existence: nothing
+ * here was optional before, which is exactly how a page with five empty
+ * sections shipped for three days claiming `状态: Active`.
+ */
+// --- fence + comment masking ----------------------------------------------------
+/** Blank out fenced code-block interiors (keep line structure) so markers,
+ *  headings and links inside code fences never count (SYN fence rule). */
+function maskFences(body) {
+    const lines = body.split('\n');
+    let fence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = /^(`{3,}|~{3,})/.exec(line.trimStart());
+        if (fence === null && m !== null) {
+            fence = m[1][0];
+            continue;
+        }
+        if (fence !== null) {
+            if (line.trimStart().startsWith(fence.repeat(3))) {
+                fence = null;
+            }
+            else {
+                lines[i] = '';
+            }
+        }
+    }
+    return lines.join('\n');
+}
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+// --- redirect stub --------------------------------------------------------------
+const REDIRECT_LINE_RE = /^>\s*Redirect:\s*(\S.*?)\s*$/im;
+function redirectTarget(masked) {
+    const m = REDIRECT_LINE_RE.exec(masked);
+    return m !== null ? m[1] : null;
+}
+/** Clickable exit (Issue #5.1): a stub only lives if it carries at least one
+ *  real internal link — a bare `<code>` path or an in-page anchor is a dead
+ *  end for the reader who lands here. Wrong-target links belong to the
+ *  dead-link scanner, not this gate. */
+function hasClickableExit(visibleNoAnchors) {
+    return visibleNoAnchors > 0;
+}
+// --- status block -----------------------------------------------------------------
+const STATE_LINE_RE = /(?:^|\n)\s*\*{0,2}\s*(?:状态\s*\/\s*Status|状态|Status)\s*\*{0,2}\s*[:：]\s*([A-Za-z\u4e00-\u9fff][^\n·|<]*)/i;
+function parseState(maskedNoComments) {
+    const m = STATE_LINE_RE.exec(maskedNoComments);
+    if (m === null)
+        return { has: false, state: null };
+    const v = m[1].trim().toLowerCase();
+    if (v.startsWith('active'))
+        return { has: true, state: 'active' };
+    if (v.startsWith('draft'))
+        return { has: true, state: 'draft' };
+    if (v.startsWith('superseded'))
+        return { has: true, state: 'superseded' };
+    if (v.startsWith('deprecated'))
+        return { has: true, state: 'deprecated' };
+    return { has: true, state: null };
+}
+// --- markers, headings, intro -------------------------------------------------------
+const TODO_COMMENT_RE = /(TODO|TBD|PLACEHOLDER|占位)/i;
+const LITERAL_TODO_RE = /\bTODO:/g;
+function countTodoMarkers(masked) {
+    let n = 0;
+    for (const m of masked.matchAll(COMMENT_RE)) {
+        if (TODO_COMMENT_RE.test(m[0]))
+            n++;
+    }
+    // literal TODO: outside comments (comments already masked to '' for this pass)
+    const noComments = masked.replace(COMMENT_RE, '');
+    n += (noComments.match(LITERAL_TODO_RE) ?? []).length;
+    return n;
+}
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*$/;
+const STATUS_BOILERPLATE_RE = /状态\s*\/\s*Status|日期\s*\/\s*Date|本页回答|This page answers/i;
+/** Parse headings + emptiness over masked, comment-stripped text. Also returns
+ *  the intro span (before the first heading) for the 导言占比 detector. */
+function parseStructure(masked) {
+    const noComments = masked.replace(COMMENT_RE, '');
+    const lines = noComments.split('\n');
+    const headings = [];
+    let h1 = null;
+    let intro = 0;
+    const stack = [];
+    // CJK glyphs carry ~3x the visual weight of a latin char per cell — count
+    // weight, not raw chars, so a terse Chinese intro is not flagged empty.
+    const weight = (s) => {
+        const stripped = s.replace(/\s/g, '');
+        const cjk = (stripped.match(CJK_WEIGHT_RE) ?? []).length;
+        return cjk * 3 + (stripped.length - cjk);
+    };
+    const closeTo = (level) => {
+        const closing = [];
+        for (;;) {
+            const s = stack[stack.length - 1];
+            if (s === undefined || s.level < level)
+                break;
+            stack.pop();
+            closing.push({ level: s.level, heading: s.heading, bodyChars: s.subtree, directChars: s.direct });
+        }
+        // inner-first pop order must be flipped back to document order
+        headings.push(...closing.reverse());
+    };
+    for (const line of lines) {
+        const m = HEADING_RE.exec(line);
+        if (m !== null) {
+            const level = m[1].length;
+            closeTo(level);
+            if (level === 1 && h1 === null)
+                h1 = m[2].trim();
+            stack.push({ level, heading: m[2].trim(), direct: 0, subtree: 0 });
+            continue;
+        }
+        if (STATUS_BOILERPLATE_RE.test(line))
+            continue;
+        const w = weight(line);
+        if (stack.length === 0) {
+            intro += w;
+            continue;
+        }
+        for (const s of stack)
+            s.subtree += w;
+        stack[stack.length - 1].direct += w;
+    }
+    closeTo(1);
+    // The intro is the H1 section's DIRECT span (real pages all open with
+    // `# 标题`); the pre-heading accumulator only carries weight on heading-less bodies.
+    const firstH1 = headings.find((h) => h.level === 1);
+    const introWeight = firstH1 !== undefined ? firstH1.directChars : intro;
+    return { headings, introEmpty: introWeight < 40, h1 };
+}
+/** Section headings (##+) whose SUBTREE holds no content. A parent that groups
+ *  non-empty subsections is an outline container, not an unfinished product;
+ *  only wholly-empty subtrees indicate an unfilled skeleton section. */
+export function emptySectionsOf(headings) {
+    return headings.filter((h) => h.level >= 2 && h.bodyChars === 0).map((h) => h.heading);
+}
+// --- links -----------------------------------------------------------------------
+const LINK_MD_RE = /\]\(([^)\s]+)[^)]*\)/g;
+const LINK_HREF_RE = /href="([^"]+)"/gi;
+/** Extract internal page links (relative wiki paths + same-host absolute URLs). */
+export function extractLinks(masked, opts) {
+    const out = [];
+    const host = opts.baseUrl.replace(/\/+$/, '');
+    const seen = new Set();
+    const push = (raw) => {
+        let target = raw.trim();
+        if (target === '' || target.startsWith('#')) {
+            if (target.startsWith('#'))
+                out.push({ path: target.slice(1), locale: 'en', anchor: true });
+            return;
+        }
+        if (/^(mailto:|javascript:)/i.test(target))
+            return;
+        let locale = 'en';
+        if (/^https?:\/\//i.test(target)) {
+            if (!target.toLowerCase().startsWith(host.toLowerCase()))
+                return; // external
+            target = target.slice(host.length);
+        }
+        if (/\.(png|jpe?g|gif|svg|webp|pdf|zip|css|js)\b/i.test(target))
+            return;
+        target = target.split('#')[0];
+        target = target.split('?')[0];
+        target = target.replace(/^\/+/, '');
+        if (target === '')
+            return;
+        if (target.startsWith('zh/')) {
+            locale = 'zh';
+            target = target.slice(3);
+        }
+        else if (target.startsWith('en/')) {
+            target = target.slice(3);
+        }
+        const key = `${locale}\u0000${target}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ path: target, locale, anchor: false });
+    };
+    for (const re of [LINK_MD_RE, LINK_HREF_RE]) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(masked)) !== null)
+            push(m[1] ?? '');
+    }
+    return out;
+}
+// --- claims + stamps + language -----------------------------------------------------
+const STAMP_RE = /上次核实|上次验证|last verified/i;
+const PORT_RE = /:\d{4,5}\b/g;
+const FS_PATH_RE = /\/(?:opt|var|etc|usr|srv)\/[\w./-]+/g;
+const CMD_RE = /\b(?:systemctl|journalctl|docker|curl|nc|wget|iptables|nginx|caddy)\b/gi;
+const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff]/g;
+const CJK_WEIGHT_RE = /[\u3400-\u4dbf\u4e00-\u9fff\u3040-\u30ff]/g;
+function distinct(text, re) {
+    return new Set(text.match(re) ?? []).size;
+}
+// --- main entry ---------------------------------------------------------------------
+export function lintBody(body, opts) {
+    const masked = maskFences(body);
+    const visible = masked.replace(COMMENT_RE, '');
+    const target = redirectTarget(masked);
+    const isRedirectStub = /^\s*>\s*Redirect:/im.test(masked);
+    const { headings, introEmpty, h1 } = parseStructure(masked);
+    const links = extractLinks(visible, { baseUrl: opts.baseUrl }).filter((l) => !l.anchor);
+    const nonSpace = (visible.match(/\S/g) ?? []).length;
+    const cjk = (visible.match(CJK_RE) ?? []).length;
+    const claims = {
+        ports: distinct(visible, PORT_RE),
+        paths: distinct(visible, FS_PATH_RE),
+        commands: distinct(visible, CMD_RE),
+    };
+    const stateInfo = parseState(visible);
+    return {
+        isRedirectStub,
+        redirectTarget: target,
+        stubHasLink: !isRedirectStub || hasClickableExit(links.length),
+        hasStateBlock: stateInfo.has,
+        state: stateInfo.state,
+        todoMarkers: countTodoMarkers(masked),
+        emptySections: emptySectionsOf(headings),
+        introEmpty,
+        hasRelatedPages: /^#{1,6}\s+.*(相关页面|Related Pages)/im.test(masked),
+        h1,
+        headings,
+        links,
+        hasStamp: STAMP_RE.test(visible),
+        claims,
+        claimTotal: claims.ports + claims.paths + claims.commands,
+        cjkRatio: nonSpace === 0 ? 0 : cjk / nonSpace,
+    };
+}
+/** Structural h1≠title flag (kept out of BodyLint's hot fields on purpose). */
+export function h1TitleMismatch(lint, title) {
+    if (title === undefined || lint.h1 === null)
+        return false;
+    return lint.h1.trim().toLowerCase() !== title.trim().toLowerCase();
+}
+/** The two hard publish-gate rules (shared.ts refuses the write on a hit). */
+export function publishGateViolations(lint) {
+    const out = [];
+    if (lint.isRedirectStub && !lint.stubHasLink)
+        out.push('redirect-stub-no-exit');
+    if (lint.state === 'active' && (lint.todoMarkers > 0 || lint.emptySections.length > 0)) {
+        out.push('active-with-unfinished-skeleton');
+    }
+    return out;
+}