opencode-wiki-historian 0.3.0 → 0.5.0

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`。