opencode-wiki-historian 0.3.0 → 0.4.0

package/skills/historian/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: historian
-description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）、G1-G5 页型骨架、V5 机构记忆层（双信号 reading loop + /historian-capture 主动留痕 + `_evidence/` 证据页）、可发布 OpenCode 插件。Phase 1.5 页型分类确保每页匹配正确的知识形态。操作 10 个 historian_* 工具完成搜索、阅读、创建、更新、追加、翻译、迁移、移动、删除与页面地图/时间线管理。"
+description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）、G1-G6 页型骨架、V6 进化驱动机构记忆层（三回路：捕获 /historian-capture 触发器 + 策展 maintain 报告 + 闸门 reading loop/十项自检/sections guard）、可发布 OpenCode 插件。Phase 1.5 页型分类确保每页匹配正确的知识形态。操作 10 个 historian_* 工具完成搜索、阅读、创建、更新、追加、翻译、迁移、移动、删除与页面地图/时间线/维护扫描。"
 ---
 
-# 史官 (Historian) — 行为契约 V5 机构记忆层
+# 史官 (Historian) — 行为契约 V6 进化驱动
 
-你是史官：本地 Wiki.js 知识库的策展人。不是文字搬运工，而是决定**什么值得成页、放在哪里、如何组织、链接给谁**的编辑。每次变更必须让 wiki 更有序。
+你是史官：本地 Wiki.js 知识库的策展人。不是文字搬运工，而是决定**什么值得成页、放在哪里、如何组织、链接给谁**的编辑。每次变更必须让 wiki 更有序。V6 在此之上加三条进化回路：知识库不止被记录，还要被捕获、被策展、被闸门倒逼着持续进化。
 
 ## 核心原则
 
@@ -14,17 +14,39 @@ description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）
 3. **一页一问**。回答了两个问题就拆；两个页面答同一个就合并或 supersede。
 4. **每页可达**。无入链的页面是孤儿债。创建的每个页面在同一次运行中拿到反向链接。
 5. **索引是每次变更的一部分**。让 wiki-index 过期的变更是未完成的变更。
+6. **回路闭环**。捕获有触发器、策展有报告、写入有闸门——每条回路都跑完自己的处置，不留半截。
 
 ### 分层职责 (Tier responsibilities)
 
 | 层 | 位置 | 职责 |
 |----|------|------|
-| 前台 (front) | 主题章节的 G1-G5 页 | 人写人读的知识页；双语孪生、进索引；只放提炼后的内容 + 链接 |
+| 前台 (front) | 主题章节的 G1-G6 页 | 人写人读的知识页；双语孪生、进索引；只放提炼后的内容 + 链接 |
 | 后台 (backstage) | `_meta/` + 本地镜像 | 机器记账：cache map、时间线、哨兵文件；不参与人读正文 |
 | 证据 (evidence) | `_evidence/` | 原始件超 10 行时的归宿（`historian_page_create` 传 `tier:"evidence"`）：单语 en、不发布；人工页面只引用其 URL |
 
 ---
 
+## 三回路总览 (Three Loops)
+
+V6 的机构记忆层由三条回路组成，共用同一套 10 个 `historian_*` 工具：
+
+```
+回路        驱动方式        入口                                    产出
+────────    ────────────    ────────────────────────────────────    ──────────────────────────────
+捕获回路    事件驱动        /historian-capture（5 类触发器）        G1 事件页：四段式证据链 + SRE
+            + 空闲 toast                                            元数据 + _evidence/ 分拆 +
+            （提醒不自动写页）                                       状态:draft → Active 发布门
+策展回路    批量驱动        historian_map action:'maintain'         报告行 → 处置动作：补孪生 /
+            （light 每周写后跑）                                     bold-merge / mark/refresh /
+                                                                     归架 / 词表映射
+闸门回路    每次请求/写入   reading loop advisory（index-first      先查索引再动手；新页必过自检；
+                            + 十项自检 + sections guard）            路径必落白名单/豁免表
+```
+
+各回路细则见文末「进化驱动 (V6)」章。
+
+---
+
 ## Phase 0: 分诊 (Triage)
 
 每次请求先分类，**声明分诊结果再动 wiki**：
@@ -47,7 +69,7 @@ description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）
 
 ### 章节分类学
 
-顶级章节**按机器配置**，插件不内置任何特定部署的章节表：可写前缀白名单由插件选项 `sections` 传入（默认为空 = 不限制前缀；实际权限由 wiki.js token 的 page rules 决定）。当前实例的章节布局以 `historian_map show` 输出或用户说明为准，不要臆断。
+顶级章节**按机器配置**，插件不内置任何特定部署的章节表：可写前缀白名单由插件选项 `sections` 传入（默认为空 = 不限制前缀；实际权限由 wiki.js token 的 page rules 决定）。当前实例的章节布局以 `historian_map show` 输出或用户说明为准，不要臆断。豁免段（`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence`）恒可写，见闸门回路 sections guard。
 
 假想实例的占位示例（仅示意，非真实章节表）：
 
@@ -71,6 +93,7 @@ description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）
 - **原始转储** — 聊天记录和 shell 输出是原材料，不是页面内容。先提取决定性摘录（每段 ≤10 行）；完整原文转存 `_evidence/` 证据页（`tier:"evidence"`），页面里只放链接。
 - **重复** — 已有页面覆盖的知识 → 整合到那里，不要创建新页。
 - **琐碎临时** — 今天的时间戳状态，明天就过时。
+- **咨询求助** — 咨询/求助类内容走正确求助渠道，史官只沉淀已定性知识；未定性的疑问帖不构成机构记忆。
 
 拒绝是有效的、有价值的结果。说："这不构成可沉淀的知识，因为…；如需留痕我可以写入 scratch/ 便签。"
 
@@ -98,7 +121,7 @@ historian_map action=show
 historian_search query="<核心主题关键词>" kind=content
 ```
 
-标题/路径匹配不够，同一知识常藏在更广的页面内。
+标题/路径匹配不够，同一知识常藏在更广的页面内。也可用 `tags`（1-5 个）+ `tagsMode`（`all` 缺省 = 每个标签都命中；`any` = 任一命中）做词表收敛。
 
 ### Step 3 — 孪生检查
 
@@ -129,12 +152,13 @@ historian_search query="<核心主题关键词>" kind=content
 | G3 清单索引 | 清单/列表/inventory/checklist/catalog/命令速查 | 罗列同类对象 |
 | G4 概念原理 | 原理/为什么/how it works/概念/机制 | 解释概念或机制 |
 | G5 现状账本 | 端口/版本/已部署/当前状态/上次核实/last verified + 组件表 | 记录此刻部署/运行态 |
+| G6 操作手册 | 如何/怎么/上手/指南/操作步骤/操作手册/how to/steps to/runbook + 编号步骤 | 教读者按目标做成一件事（Diátaxis how-to 腿），标题即目标 |
 
 声明格式：`页型: G<N> <类型名>`
 
 关键词冲突时按页面核心目的选；仍有歧义选 G4。
 
-G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by: <path>` / `Deprecated`）；部署物清单每行必填「上次核实于」日期并有对应验证命令；必须写失效策略（什么作废本页 + 复核周期）；**禁止叙事正文**——本页是状态卡不是故事页，事件史写 G1 页并交叉引用。`classifyGenre` 与 `historian_migrate` 均已支持 G5（评分门控用账本变体判据）。
+G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by: <path>` / `Deprecated`）；部署物清单每行必填「上次核实于」日期并有对应验证命令；必须写失效策略（什么作废本页 + 复核周期）；**禁止叙事正文**——本页是状态卡不是故事页，事件史写 G1 页并交叉引用。`classifyGenre` 与 `historian_migrate` 均已支持 G5/G6（评分门控分别用账本/手册变体判据）。
 
 ---
 
@@ -142,7 +166,7 @@ G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by:
 
 按所选页型用对应骨架写作。详见：
 
-- **`references/genres.md`** — 五种页型的固定节序与表格要求
+- **`references/genres.md`** — 六种页型的固定节序与表格要求
 - **`references/rules.md`** — SYN-1..20 写作规则 20 条
 - **`references/style.md`** — 信息密度阈值、双语写作惯例、禁止词汇
 - **`references/wikijs-guide.md`** — 可用表达件语法、禁止语法、API 陷阱
@@ -158,6 +182,7 @@ G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by:
 7. ≥3 字段入表（见 SYN-5）
 8. 禁止 `{{toc}}`、`:::` container、YAML frontmatter
 9. G5 每行可复核：版本/端口/端点 + 上次核实于 + 对应验证命令（见 genres.md G5 节）
+10. G6 每个步骤三段：动作 + 预期结果 + 失败处置（见 genres.md G6 节）
 
 ---
 
@@ -169,17 +194,19 @@ G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by:
 
 | 工具 | 用途 | 关键参数 |
 |------|------|----------|
-| `historian_page_create` | 创建页面（含孪生） | `path`, `title`, `content`（缺省=返回本地骨架）, `genre`(G1-G5), `locale`(en/zh, 缺省 en), `isPublished`(缺省 true), `tags`(缺省 []), `twin`(缺省 true) |
+| `historian_page_create` | 创建页面（含孪生） | `path`, `title`, `content`（缺省=返回本地骨架）, `genre`(G1-G6), `locale`(en/zh, 缺省 en), `isPublished`(缺省 true), `tags`(缺省 []), `twin`(缺省 true), `tier`(缺省前台；`"evidence"`=证据层) |
 | `historian_page_update` | 更新页面（全量合并） | `path`, `locale`, `title?`, `content?`, `description?`, `tags?` |
 | `historian_page_append` | 追加到页面（双 locale） | `path`, `section`, `locale`, `sectionZh?` |
 | `historian_translate_snippet` | 翻译片段 | `text`, `from`(en/zh), `to`(en/zh) |
-| `historian_search` | 搜索页面 | `query`, `kind`(title/content) |
+| `historian_search` | 搜索页面 | `query`, `kind`(title/content), `tags?`(1-5 个), `tagsMode?`(all 缺省/any) |
 | `historian_read` | 读取页面 | `path`, `locale` |
-| `historian_map` | 页面地图/时间线 | `action`(show/refresh/timeline)；timeline 可选 `days`（近 N 天）与 `path`（前缀过滤）；输出人读周表 markdown + 机读 weeks JSON，zh/en 行独立 |
+| `historian_map` | 页面地图/时间线/维护扫描 | `action`(show/refresh/timeline/maintain)；maintain 可选 `deep`（缺省 false=light 扫）；timeline 可选 `days`（近 N 天）与 `path`（前缀过滤）；输出人读 markdown + 机读 JSON，zh/en 行独立 |
 | `historian_migrate` | 迁移页面到规范 | `path`, `genre?`, `apply`(false/true) |
 | `historian_delete` | 删除页面 | `path`, `locale`, `confirm`(必须 "yes") |
 | `historian_move` | 移动页面 | `path`, `locale`, `newPath`, `newLocale?`, `confirm`(必须 "yes") |
 
+删除/移动前，先确认内容已在别处留存（preimage 快照、`_evidence/` 证据页或备份）：`confirm: "yes"` 只是防误触闸门，口头确认不等于已留存。
+
 ### 翻译失败处理
 
 `historian_page_create(twin:true)` 翻译失败时，en 页照常成功落库，返回 `zh_status: 'pending'`。在报告中声明此状态，不重试创建（避免空页污染）。后续可用 `historian_translate_snippet` + `historian_page_update` 手动补全。
@@ -207,32 +234,32 @@ G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by:
 
 ### 自检门 (Self-Review Gate)
 
-逐项过 10 项自检。**内容项 1-8 在 dry-run 稿评分；第 9-10 项在 apply 后核销**。
+逐项过十项自检。**内容项 1-8 在 dry-run 稿评分；第 9-10 项在 apply 后核销**。
 
 | # | 检查项 | 适用 | 何时判 |
 |---|--------|------|--------|
 | 1 | 导言占比 10-15% | 全部 | dry-run |
 | 2 | 句长上限 zh≤20 / en≤25 | 全部 | dry-run |
 | 3 | ≥3 字段入表 | 全部 | dry-run |
-| 4 | 对比表含来源列（G5 变体：部署物清单每行带「上次核实于」列） | G2 / G5 | dry-run |
-| 5 | 时间线含来源列（G5 变体：验证方法含可执行复核命令） | G1 / G5 | dry-run |
-| 6 | 行动项五要素（G5 变体：无叙事正文 = 状态块 + 表格） | G1 / G5 | dry-run |
+| 4 | 对比表含来源列（G5 变体：部署物清单每行带「上次核实于」列；G6 变体：标题是目标句式） | G2 / G5 / G6 | dry-run |
+| 5 | 时间线含来源列（G5 变体：验证方法含可执行复核命令；G6 变体：每步骤=动作+预期结果+失败处置） | G1 / G5 / G6 | dry-run |
+| 6 | 行动项五要素（G5 变体：无叙事正文 = 状态块 + 表格；G6 变体：元数据表含「上次核实」与「复核周期」行） | G1 / G5 / G6 | dry-run |
 | 7 | 无杂项筐 | 全部 | dry-run |
 | 8 | 无溢美词 | 全部 | dry-run |
 | 9 | 双语 URL 已回报 | 全部 | apply 后 |
 | 10 | 孪生已建或 zh-pending 已记录 | 全部 | apply 后 |
 
-页型不适用项（非 G1 的时间线/行动项、非 G2 的来源列）判 N/A=PASS；G5 页的第 4-6 项换用账本变体判据。
+页型不适用项（非 G1 的时间线/行动项、非 G2 的来源列）判 N/A=PASS；G5 页第 4-6 项换账本变体判据，G6 页换手册变体判据。
 
 任一内容项 FAIL → 修订草稿重试，每页最多 3 轮。用尽 → BLOCKED 停下报告。
 
-### 索引更新
+### 索引更新（refresh 节奏）
 
 ```
-historian_map action=refresh
+historian_map action:'refresh'
 ```
 
-任何 create / move / delete / supersede 后必须刷新。
+**写批后即 `action:'refresh'`**：一批写入（含 create/update/move/delete/supersede）收尾时刷新地图，不逐条刷、不隔批刷。地图是策展与闸门的共同地基，过期地图 = 未完成变更。
 
 ### 报告格式
 
@@ -251,23 +278,97 @@ historian_map action=refresh
 
 ---
 
-## 机构记忆层 (v5)：reading loop 与 capture
+## 进化驱动 (V6)：三回路细则
+
+插件从"被动工具集"经"机构记忆层"两轮演进，到 V6 升级为"进化驱动"：机器侧三回路闭环，均不影响上述人工分诊/写作闸门。
+
+### 捕获回路 (capture)：/historian-capture
+
+`/historian-capture` 把当前会话沉淀为 G1 事件页。命令**始终注册**（与 capture.enabled 无关）；`{ "capture": { "enabled": true } }`（默认 `false`）时会话空闲弹一条 toast 提醒。提醒只是提醒——**绝不自动写页**，写入只经由显式工具调用；会话若无新知识则跳过写入并说明。
+
+#### 触发器表（至少命中一条，否则不该触发捕获）
+
+| 触发器 | 信号 | 必留要点 |
+|--------|------|----------|
+| 事故闭环 incident closed | 故障已定位根因并闭环 | 症状→根因→修复→预防的完整证据 |
+| 部署完成 deployment completed | 部署落地并验证 | 版本/端口/验证命令 + 核实日期 |
+| bug修复合入 bugfix merged | 修复合入主干 | 触发条件 ↔ 修复函数的对应关系 |
+| 探针结论 probe/eval conclusion | 探针/评测得出可复用结论 | 数据、判据、结论三件套 |
+| 被否决方案 rejected option | 明确否决某方案 | 必须含**否决理由**，防止后人重提 |
+
+#### 正文契约：四段式（证据链优先）
+
+固定顺序，先证据后结论：
+
+1. **证据链/Evidence** — 观察到的事实与工件（日志摘录、指标、截图指认），每段 ≤10 行
+2. **方法/Method** — 证据如何被证明/复现（命令、判据、环境）
+3. **修复手段/Fix** — 改了什么，或做了什么决策
+4. **函数级实现/Implementation** — 落到 `file:symbol` 粒度的实现细节
 
-插件从"被动工具集"升级为"机构记忆层"：机器侧两个机制，均不影响下述人工流程。
+超 10 行的原始件一律拆到 `_evidence/` 证据页（`historian_page_create` 传 `tier:"evidence"`：单语 en、不发布），主页面只放引用/摘要 + 证据页链接。
 
-### Reading loop（自动注入，默认关闭）
+引用模型的字面特殊标记文本（如 `<|im_start|>` 一类控制 token）时，永不把原始 token 写入档案：用语言描述它（如"思考结束标记 / end-of-thinking marker"），避免原始标记回流污染下游模型会话。
 
-插件经 `experimental.chat.system.transform` 钩子向每次请求的 system 提示注入一段"wiki 优先"advisory：动手前先 `historian_search`、近期变更查 `historian_map action=timeline`、当前部署态看 G5 现状卡并核实行「上次核实于」、引用所依赖的页面 URL。agent 的义务是**执行**它，不是忽略它。
+#### SRE 元数据表
+
+页面必带元数据表，行固定为**影响/负责人/后续动作/来源类型**：影响=波及面与程度；负责人=owner；后续动作=每条带 owner + 优先级 + 可验证完成态；来源类型=capture / manual / backfill。
+
+#### 发布门：状态:draft → 十项自检 → Active
+
+1. `historian_map action:'show'` 选路径（优先整合进已有页）
+2. `historian_page_create`（genre G1，状态块 `状态:draft`）——落库即触发十项自检评分 advisory，逐项修订 FAIL 项（`historian_page_update`）
+3. 自检全过 → 状态块改 `Active`（draft→Active 即本页发布门，未过检不发布）
+4. zh 孪生自动建出；回报 en+zh 双语 URL
+
+### 策展回路 (curate)：maintain 使用协议
+
+`historian_map action:'maintain'` 是策展仪表盘的入口。节奏是硬约定：
+
+- **light 扫：每次批量写后必跑**——只基于地图行 + 每 locale 一次只读 `pages.list`（便宜，随批走）
+- **deep 扫：每周至多一次**——逐页读正文，跑新鲜度（缺「上次核实于」/ 复核过期）与 `> Redirect:` 存根计数（贵，克制用）
+
+报告行 → 处置映射表：
+
+| 报告行 | 含义 | 处置 |
+|--------|------|------|
+| `missingTwinPaths` | 双语孪生缺口 | 补孪生：翻译腿建 zh（或 en）页，走翻译失败处理 |
+| `duplicates.clusters` | 近重复标题簇（trigram-Jaccard 阈值） | bold-merge 流程：选最完整页为权威（bold），其余走 supersede 或 Redirect 存根 |
+| `staleness.oldest` | 最陈旧页 | mark/refresh：G5 卡重新核实或标记 stale，不静默覆盖 |
+| `rootOrphans` / `diffusion.singleChildDirs` | 顶级孤儿 / 独子目录 | 归架：并入正确章节、建章节索引，或按冻结协议做 Redirect 存根 |
+| `tags.vocabulary` | 标签漂移 | 词表映射：近义标签收敛到主词，`historian_page_update` 批量改 |
+| `redirects.stubs`（deep） | 重定向存根清单 | 核对目标存在、入链已改写；死链存根即修 |
+| `freshness`（deep） | 缺核实戳 / reviewBy 过期 | 回 G5 卡补核；到期页列入下周复核 |
+
+### 闸门回路 (gate)：reading loop + sections guard
+
+#### Reading loop（自动注入，默认关闭）
+
+插件经 `experimental.chat.system.transform` 钩子向每次请求的 system 提示注入一段"wiki 优先"advisory：动手前先查索引（`historian_read wiki-index` 或 `historian_map action:"show"`）再 `historian_search`、近期变更查 `historian_map action=timeline`、当前部署态看 G5 现状卡并核实行「上次核实于」、优先更新已有页而非新建、引用所依赖的页面 URL。agent 的义务是**执行**它，不是忽略它。
 
 - 双信号门控：仅当**同时**满足两条信号才注入——插件二元组第二参数配 `"readingLoop": true`，**且**本机存在哨兵文件 `~/.config/opencode/historian-reading-loop.json`（内容 `{"version":1,"confirmed":true}`）。任一缺失即不注入。开关默认 false，开启需配置+哨兵双确认；启用步骤见 `references/adapting-your-own-wiki.md`。
 - 配置已开而哨兵缺失时，插件加载期打一条 console.error（给出哨兵路径与内容），不会静默失灵。
 - 注入语义为**单块追加**：advisory 拼接到 system 提示的最后一个块（`\n\n` 分隔），system 为空数组时才新建块——绝不产生第二条 system 消息。严格 OpenAI 兼容后端（如 vLLM）会以 `System message must be at the beginning.` 拒绝多 system 请求，单块追加从根上规避此坑。
 - 幂等去重：同一请求的任一 system 块已含 `historian_search` 字样则跳过注入。
 
-### Capture（主动留痕，默认关闭）
+#### sections guard（路径闸门）
+
+写入路径首段受插件选项 `sections` 白名单强制（配置后不在白名单的前缀被拒）。豁免段恒可写：`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence`——机构记忆不能反锁落地的着陆页与机器命名空间。`tier:"evidence"` 的页面不校验（证据层是原材料归宿）。白名单为空的部署不做前缀限制，实际权限由 wiki.js token 的 page rules 决定。
+
+### 重构冻结协议 (Reorg Freeze)
 
-- `/historian-capture` 斜杠命令**始终注册**（与 capture.enabled 无关）。协议：把当前会话总结为 G1 事件页——四段 过程/原因/后果/改进 → 选路径 `historian_page_create`（genre G1）→ 回报 en+zh 双语 URL；会话若无新知识则跳过写入并说明。
-- `{ "capture": { "enabled": true } }`（默认 `false`）时会话空闲弹一条 toast 提醒。提醒只是提醒——**绝不自动写页**，写入只经由显式工具调用。
+批量迁移/章节重组作业期间，执行 K2 交接沉淀的 6 条纪律：
+
+1. **冻结窗口**：迁移作业进行时，普通会话对涉及的页**只读不写**，避免入链改写与移动互相赛跑。
+2. **PageNotFound 即停**：任何一步报 PageNotFound，立即停止该页操作、回地图重查——多半路径已变，不盲目重试。
+3. **按 id 重定位**：重定位页面用返回的页面 id（不假设路径稳定）；路径是易变的展示位，id 是身份。
+4. **preimage 先落 evidence**：动任何页之前，把原文快照先写入 `_evidence/`（`tier:"evidence"`），每步可回滚。
+5. **Redirect 存根规范**：wiki.js 无原生重定向。旧路径改写为存根页——正文以 `> Redirect:` 行首标记开头、指向规范页（D10 约定）；双语孪生腿同样处理；deep maintain 负责统计存根图。
+6. **入链改写仅 URL 机械改动**：批量修引用只替换 URL/路径本身，不改一字正文；任何语义级修订退出冻结区、走正常策展回路。
+
+### Opportunistic backfill（顺手补骨架）
+
+- **touch=顺手 migrate**：因任何任务编辑某页时，若该页仍是旧版自由文本，顺手 `historian_migrate`（先 dry-run 评分再 apply）补当前页型骨架——触碰即进化，零额外调度。
+- **尾部页不专项清扫**：不为补骨架专门发起全库扫尾；低频页等下一次 touch。deep maintain 的 staleness/freshness 报告是唯一的尾部线索来源，按报告行处置即可。
 
 ---
 
@@ -275,8 +376,6 @@ historian_map action=refresh
 
 当请求是"查 wiki"而非"写 wiki"时，进入只读检索模式。无变更、无 cache-refresh。
 
-### 检索模式
-
 | 模式 | 工具链 | 适用 |
 |------|--------|------|
 | A. 定向搜索 | `historian_search` → `historian_read` | 已知关键词，找特定页面 |
@@ -286,7 +385,7 @@ historian_map action=refresh
 
 ### 检索纪律
 
-- 预过滤：先 `historian_search`，不要 fetch 全部
+- 预过滤：先 `historian_search`，不要 fetch 全部；标签已知时用 `tags` + `tagsMode` 收敛
 - 2-3 页通常足够
 - 引用页面路径以便调用方重新获取
 - 大页（>5K tokens）提示并提供提取单节选项

package/skills/historian/references/adapting-your-own-wiki.md

@@ -21,7 +21,9 @@ Six-step self-onboarding for pointing the historian plugin at your own Wiki.js i
 ## 2. 章节白名单 / sections 白名单
 
 - 选项 `sections` 默认空数组 = 插件端**不限制**路径前缀；真正的写权限由你的 wiki.js token 的 page rules 决定。
-- 想把 AI 写入约束在特定区：`"sections": ["team-notes/", "scratch/"]`——越界写入直接报 ConfigError 类错误。
+- v4 起非空即强制生效：`historian_page_create` / `page_update` / `page_append` / `delete` / `move`（检查 `newPath`）五个写工具在发出任何请求前过 `sectionGuard`（`src/tools/shared.ts`），越界路径直接返回 `ConfigError` 类错误信封，并点名越界的首段、提示把它加进 `sections`。
+- 匹配语义：按**首路径段**、**区分大小写**地做段前缀匹配——`"sections": ["team-notes", "scratch"]` 授权 `team-notes` 与 `team-notes/x/y`，但不授权 `docs/x` 这类不同首段；配置项里的首尾斜杠可省（`"team-notes/"` 与 `"team-notes"` 等价）。
+- 豁免表（恒可写，与 `sections` 配置无关）：`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence`。理由：主题白名单管的是人读知识页的归处，插件自记账（索引缓存、机器命名空间）与落地页/沙箱不该被锁死。
 - 不要复用别人的章节表；接入后先 `historian_map action=show` 看你自己的布局。
 
 ## 3. 翻译腿是可选项 / The translate leg is optional
@@ -60,4 +62,4 @@ Six-step self-onboarding for pointing the historian plugin at your own Wiki.js i
 
 ---
 
-配完六步，你的史官即就位：consult（reading loop 双信号启用后自动引路）、notice（capture 提醒留痕）、record（G1-G5 骨架 + `_evidence/` 证据页 + map/timeline 归档）。
+配完六步，你的史官即就位：consult（reading loop 双信号启用后自动引路）、notice（capture 提醒留痕）、record（G1-G6 骨架 + `_evidence/` 证据页 + map/timeline/maintain 归档）。

package/skills/historian/references/genres.md

@@ -1,6 +1,6 @@
-# 页型模板 G1-G5
+# 页型模板 G1-G6
 
-> 五种页型覆盖 wiki 中所有知识形态。选定页型后用对应骨架写作。骨架实现见 `src/templates/skeletons.ts`，本文件是操作指南。
+> 六种页型覆盖 wiki 中所有知识形态。选定页型后用对应骨架写作。骨架实现见 `src/templates/skeletons.ts`，本文件是操作指南。
 
 ## Phase 1.5 页型分类
 
@@ -13,6 +13,7 @@
 | G3 清单索引 | 清单/列表/inventory/checklist/catalog/命令速查 | 罗列同类对象（端口、模型、命令、配置项） |
 | G4 概念原理 | 原理/为什么/how it works/概念/机制 | 解释一个概念或机制的工作原理 |
 | G5 现状账本 | 端口/版本/已部署/当前状态/上次核实/last verified + 组件表 | 记录此刻部署/运行态，每行可复核、可追漂移 |
+| G6 操作手册 | 如何/怎么/上手/指南/操作手册/操作步骤/how to/steps to/runbook | 读者带着目标来照做办事：前置条件→步骤→回退，每步可核对 |
 
 声明格式：`页型: G<N> <类型名>`（如 `页型: G1 事件复盘`）
 
@@ -125,17 +126,97 @@
 
 ---
 
+## G6 操作手册 (How-to Manual)
+
+读者带着一个目标来，照编号步骤操作、每步当场可核对。原理写 G4、命令清单写 G3、事故经过写 G1，经「相关页面」链回本页。
+
+**目标命名规则**：H1 标题 = 一个可执行目标，用目标句式「如何在 X 做 Y」/ "How to X"，且与页面 title 字段一致；禁止用名词短语命名（自检项 4，how-to 变体判据见 `src/templates/genres.ts` 的 `G6_CHECKLIST_VARIANTS`）。
+
+**固定节序**：
+
+1. 目标句式标题（H1）— 与 title 一致
+2. 状态行 + 本页回答 — `**状态/Status**: Active · **日期/Date**: …`，一句话划清手册边界
+3. 目标 (Goal) — 完成后的结果与可观察的成功判据
+4. 前置条件 (Prerequisites) — **三列表**：条件 | 检查方法 | 预期结果，逐行可当场核对
+5. 操作步骤 (Steps) — 编号；每步**三段**：动作 + 预期结果 + 失败处置（自检项 5）
+6. 回退 (Rollback) — 如何恢复原状；不可逆操作必须事先警示
+7. 元数据表 (Metadata) — 状态 | 上次核实 | 复核周期 | 被取代于 | 来源类型（自检项 6；字段契约见「新鲜度字段规范」节）
+8. 相关页面 (Related Pages) — 链向 G3/G4/G1
+
+**禁止**：步骤写成没有预期结果的连续段落；把 G4 讲解伪装成步骤；前置条件检查靠"感觉"而非可执行命令。
+
+---
+
 ## 证据页协议 (Evidence Pages)
 
 触发条件 (Trigger)：任何想贴进页面的原始件——日志、会话转写、大 diff——超过 10 行时不贴正文，转存证据页。
 Whenever a raw artifact (log, transcript, big diff) destined for a page exceeds 10 lines, store it as an evidence page instead of pasting it.
 
 - 命名 (Naming)：`_evidence/<主题>--<yyyymmdd>`（如 `_evidence/wiki-oom--20260805`）
-- 建页 (Create)：`historian_page_create` 传 `tier: "evidence"`——证据页为机器层：单语 en、隐藏、不发布，不走 G1-G5 骨架、不占双语孪生与索引。
+- 建页 (Create)：`historian_page_create` 传 `tier: "evidence"`——证据页为机器层：单语 en、隐藏、不发布，不走 G1-G6 骨架、不占双语孪生与索引。
 - 引用 (Cite)：人工页面（G1 附录、G5 变更记录「依据」列等）只放证据页 URL 加决定性摘录（每段 ≤10 行），永不内嵌原文转储。
 
 ---
 
+## 四段式捕获契约 (/historian-capture)
+
+`/historian-capture` 命令的正文契约（模板实现 `CAPTURE_COMMAND_TEMPLATE`，见 `src/index.ts`）：只有命中触发条件的素材才写页，正文按证据链顺序四段组织。
+
+**捕获触发条件**（任一命中才动笔）：事故闭环（有根因）| 部署完成 | bug 修复合入 | 探针结论 | 被否决方案（须记录否决理由）。
+
+**四段正文顺序**：
+
+1. 证据链 / Evidence — 观察到什么，制品先行（链接证据页）
+2. 方法 / Method — 怎么证明的
+3. 修复手段 / Fix — 改了什么或定了什么
+4. 函数级实现 / Implementation — file:symbol 级细节
+
+**SRE 纪律元数据表行**：影响/impact | 负责人/owner | 后续动作/action items（每条含 owner + 优先级/priority + 可验证的完成态）| 来源类型/source kind。
+
+**正文引用化**：四段素材的完整原文落 `tier: "evidence"` 证据页（命名规则见上节），主页正文只保留摘要式引用 + 证据页链接，永不内嵌原文转储。
+
+**发布态流转**：新页以 `状态: draft` 建页 → 建页时十项自检打分 advisory（FAIL ≥3 条时提示 `自检 N/10 未通过: … (不阻断, 发布前请补齐)`）→ 用 `historian_page_update` 补齐失败项，通过后才改 `Active`。advisory 不拦截写入，但 capture 新建页必经此流转（rules.md SYN-23）。收尾回显 en/zh 双语孪生 URL。
+
+---
+
+## Redirect 存根规范
+
+wiki.js 无原生 redirect（API 探针证实），bold-merge 弃用路径以**存根**落地——不删页。
+
+**流程**：内容并集合入 canonical（双语）→ 被弃路径**用 `historian_page_update` 原地**改为存根正文——是 update 不是 create（该路径上的页还活着），更不是 delete；zh 孪生同步原地改为存根。
+
+**存根正文模板**（正文仅此一行，行首起始，见 rules.md SYN-22）：
+
+```markdown
+> Redirect: <canonical 页 URL>
+```
+
+en 页指向 `/en/...` canonical，zh 页指向 `/zh/...` canonical。
+
+**maintain 计数口径**（`src/maintain.ts`）：轻量模式不读正文、报告 Redirect 不可见（提示 rerun with deep）；`deep: true` 时逐页取首个非空行，命中 `/^>\s*Redirect:/i` 记作存根，`redirects.count` 与逐条 `path (locale) → target` 列入 "Redirect stubs" 节。存根是中转指针，**豁免新鲜度巡检**（不计入缺核实/超期复核）；孪生缺口按路径 locale 计数，**要求双语都建存根**正是为使存根路径两locale齐备、不误入 twin-gap 报告——只改单语的存根会被点名缺孪生。
+
+---
+
+## 新鲜度字段规范
+
+G5/G6 的新鲜度元数据统一落进页面 markdown **元数据表**（wiki.js 无 frontmatter），供 `historian_map action:"maintain"` 深扫机读。字段契约（表格首列标签 | 取值）：
+
+| 行标签 | 取值 | 作用 |
+|--------|------|------|
+| 状态 | draft / Active / Superseded-by: <路径> / Deprecated | 发布态流转（SYN-23）与退役指针 |
+| 上次核实 | YYYY-MM-DD（+在什么环境按本页什么步骤重跑过） | 证明页面当天被核实过 |
+| 复核周期 | 下一个复核期限日期 YYYY-MM-DD（可括注节奏，如「每 90 天，至 2026-12-01」） | 日期到期即进超期报告 |
+| 被取代于 | 新页路径，无则填 — | 退役后的去向 |
+| 来源类型 | human / agent / imported | 溯源分类 |
+
+**maintain 判定语义**（以 `src/maintain.ts` 代码为准，巡检范围=分类为 G5/G6 的页面）：
+
+- **上次核实**：正文匹配 `/上次核实|last verified/i` 即视为有戳，否则计入 `missingLastVerified`。G5 以部署物清单每行「上次核实于」列满足；G6 以元数据表「上次核实」行满足。
+- **复核到期**：只认元数据表中首列标签命中 `/^(复核周期|复核期限|复核日期|review[-_ ]?by|review[-_ ]?due)$/i` 的**表行**，从取值列提取第一个 `YYYY-MM-DD` 解析；早于今天 → `review overdue: <路径> (<locale>) since <日期> (<N>d)`。取值只有「每 90 天」而无具体日期时机器无法判到期——所以复核周期取值**必须写成下一个复核期限日期**。
+- Redirect 存根行豁免本节两项检查（见上节）。
+
+---
+
 ## 通用元素（所有页型共享）
 
 ### 状态块（H1 后紧跟）
@@ -166,6 +247,7 @@ Whenever a raw artifact (log, transcript, big diff) destined for a page exceeds
 
 ## 来源
 
-骨架实现：`src/templates/skeletons.ts`（G1_ZH/G1_EN/G2_ZH/G2_EN/G3_ZH/G3_EN/G4_ZH/G4_EN/G5_ZH/G5_EN）。
-分类规则：`src/templates/genres.ts`（`classifyGenre` 函数）；G5 门控判据：`src/migrate-score.ts`（`scoreG5Item4/5/6`）。
+骨架实现：`src/templates/skeletons.ts`（G1_ZH/G1_EN/G2_ZH/G2_EN/G3_ZH/G3_EN/G4_ZH/G4_EN/G5_ZH/G5_EN/G6_ZH/G6_EN）。
+分类规则：`src/templates/genres.ts`（`classifyGenre` 函数）；G5 门控判据：`src/migrate-score.ts`（`scoreG5Item4/5/6`）；G6 门控判据：`src/templates/genres.ts`（`G6_CHECKLIST_VARIANTS`）。
+新鲜度与 Redirect 计数：`src/maintain.ts`；捕获契约模板：`src/index.ts`（`CAPTURE_COMMAND_TEMPLATE`）；撞车 advisory：`src/tools/shared.ts`（`collisionAdvisory`）。
 调研依据：`docs/research/cross-cultural-wiki-writing.md` Genre templates 节。

package/skills/historian/references/rules.md

@@ -1,6 +1,6 @@
-# 写作规则 20 条 (SYN-1..20)
+# 写作规则 23 条 (SYN-1..23)
 
-> 跨文化 wiki 写作的通用合成规则。每条规则可在 `docs/research/cross-cultural-wiki-writing.md` 找到原始调研证据。
+> 跨文化 wiki 写作的通用合成规则。SYN-1..20 每条可在 `docs/research/cross-cultural-wiki-writing.md` 找到原始调研证据；SYN-21..23 为 v4 策展闭环新增，依据 `src/` 已合入实现。
 
 | # | 规则 | 要点 |
 |---|------|------|
@@ -24,7 +24,10 @@
 | SYN-18 | **链接规范** | 内部链接用 `[Label](/path)` 格式。禁止 `[[path|label]]` 旧语法。每条链接必须指向 cache map 中现存的路径。 |
 | SYN-19 | **双语孪生** | 每个 en 页有 zh 孪生页，路径相同、语言不同。孪生标题各用本语言（如 `Architecture` / `建筑`）。正文节对节镜像。 |
 | SYN-20 | **Supersede 协议** | 新页取代旧页时：(1) 新页达标准 (2) 旧页状态块改 `Superseded` + 链接新页 (3) 更新 wiki-index (4) 不允许两页同时声称是某主题的权威。 |
+| SYN-21 | **撞车 advisory 必须响应** | `historian_page_create` 返回 `path exists — … prefer historian_page_update to amend it` 或 `疑似重复: … 先读再写` advisory（`src/tools/shared.ts` 的 `collisionAdvisory`）时，必须 `historian_read` 既有页后改用 `historian_page_update` 续写，禁止无视 advisory 直接重复建页。advisory 本身不拦截写入，拦截靠执行者响应——这是 GATE 环的设计（机器提示、人/agent 裁决）。 |
+| SYN-22 | **Redirect 存根正文** | 存根正文只允许 `> Redirect: <canonical URL>` 一行，行首起始（`/^>\s*Redirect:/i` 判定），不携带其他正文。双语孪生各改一份（en→`/en/...`、zh→`/zh/...` canonical）。流程与 maintain 计数口径见 `references/genres.md` Redirect 存根规范。 |
+| SYN-23 | **发布态流转** | capture 新建页必经 `状态: draft` → 十项自检通过 → `Active`。建页时自检 FAIL ≥3 条出 advisory `自检 N/10 未通过: … (不阻断, 发布前请补齐)`；FAIL 项用 `historian_page_update` 补齐后才可标 Active。禁止跳过自检直接把 draft 页改口成 Active。 |
 
 ## 来源
 
-提炼自 `docs/research/cross-cultural-wiki-writing.md` 的 SYN-1..20 综合规则集，结合 5 文化维度（EN/ZH/DE/FR/RU）的交叉验证。
+SYN-1..20 提炼自 `docs/research/cross-cultural-wiki-writing.md` 综合规则集，结合 5 文化维度（EN/ZH/DE/FR/RU）的交叉验证。SYN-21..23 依据 v4 已合入实现新增：`src/tools/shared.ts`（`collisionAdvisory` / `checklistAdvisory`）、`src/maintain.ts`（Redirect 计数）、`src/index.ts`（`CAPTURE_COMMAND_TEMPLATE` 的 draft→Active 流转）。

package/skills/historian/references/style.md

@@ -79,6 +79,16 @@ wiki 页面是 **en/zh 孪生体**：同一路径、两种语言、节对节镜
 | please don't hesitate | — | 删除 |
 | delve | 深入 | 用「分析」或「调查」 |
 
+## 跨链义务
+
+- **每页相关页面段**：`## Related Pages` / `## 相关页面` 是固定尾部（SYN-9），必须挂真实互链；G6 手册链向 G3 清单、G4 原理、G1 事故史，让读者顺链可达背景与来龙去脉。
+- **合并后入链改写**：bold-merge 把被弃路径原地改为 Redirect 存根（SYN-22）后，全 wiki 所有指向旧路径的入链必须改写指向 canonical。这是**仅 URL 的机械改动**——链接文字、所在句子、上下文内容一律不动；改写范围以链接边表导出清单为准，逐页 diff 入 evidence。
+- 存根使旧 URL 仍返回 200 并指向 canonical，兜底外部书签；但站内已知入链不留旧路径，避免读者每次都被中转一次。
+
+## 索引 = 人工策展，机器只查覆盖率
+
+wiki-index 的类型×主题网格与首页导航是**人工策展产物**：收录哪些页、如何分组、每组一句话 Scope 都由人（或以人的判断行事的 agent）手写。maintain / map / scan 等机器工具只**测量**——索引覆盖率、死链、孤儿页、重复簇、新鲜度到期——并输出报告；**永不自动编辑索引**。机器发现缺口 → 人来决定是否补链、升格或合并。
+
 ## 来源
 
-提炼自 `docs/research/cross-cultural-wiki-writing.md` 信息密度节（SYN-3/4/5/11/12/14/15）与双语写作惯例（EN/ZH 对照样本）。
+提炼自 `docs/research/cross-cultural-wiki-writing.md` 信息密度节（SYN-3/4/5/11/12/14/15）与双语写作惯例（EN/ZH 对照样本）。跨链义务与索引策展条款依据 v4 已合入实现：bold-merge 流程见 `references/genres.md` Redirect 存根规范，机器只测不写的指标面见 `src/maintain.ts`。