opencode-wiki-historian 0.6.1 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,7 +8,7 @@ opencode-historian 把 wiki.js 的读写、翻译、页型规范、迁移工具
8
8
 
9
9
  功能一览:
10
10
 
11
- * 10 个 `historian_*` 工具,覆盖创建、更新、追加、翻译、搜索、阅读、地图/时间轴/维护报告、迁移、删除、移动
11
+ * 11 个 `historian_*` 工具:创建、更新、追加、翻译、搜索、阅读、地图/时间线/维护报告、迁移、删除、移动。另有锚印封存 `historian_anchor`:在引擎会话库中定位人类订单/批准消息,哈希并落证据页回执,供事后对账
12
12
  * Skill v5 随插件自动注入(config hook),无需手动安装 skill 文件
13
13
  * G1 至 G6 页型契约,每种页型对应专属骨架模板(v4 新增 G6 操作手册/how-to)
14
14
  * 双语孪生页面(en/zh)自动翻译,翻译引擎可配置
@@ -23,7 +23,7 @@ opencode-historian 把 wiki.js 的读写、翻译、页型规范、迁移工具
23
23
 
24
24
  ### 灵感 / Inspiration
25
25
 
26
- 这个插件的写作规则不是发明的,是从五种语言文化的 wiki 工程传统加一种运维文化里蒸馏出来的(调研全文见仓库内 `docs/research/cross-cultural-wiki-writing-digest.md`,每条主张附原文引用):
26
+ 这个插件的写作规则不是发明的。它们蒸馏自五种语言文化的 wiki 工程传统,再加一种运维文化。调研全文见仓库内 `docs/research/cross-cultural-wiki-writing-digest.md`,每条主张附原文引用:
27
27
 
28
28
  | 文化 | 给史官的贡献 |
29
29
  |---|---|
@@ -33,13 +33,13 @@ opencode-historian 把 wiki.js 的读写、翻译、页型规范、迁移工具
33
33
  | 法文 | 中立、非个人化、清晰、精确、易懂、有教学性六种品质;溢美词强制转成事实(用排名、奖项、销量替代"最伟大的"这类断言);耐久过滤:明天就会过时的内容不值得写 |
34
34
  | 俄文 | ХС/ИС 条目门槛(导言普通读者可懂、术语最少、不少于 10 行);二手权威来源优先于一手(АИ);每种观点按影响力分配篇幅、禁止虚假平衡(ВЕС);风格要求精确、简明、无歧义,同时保持内容饱和 |
35
35
 
36
- SRE postmortem 文化单独值得点名:它把"事件"当一等文档对待,先证据后结论的证据链四段式(`src/index.ts` 的 `CAPTURE_COMMAND_TEMPLATE` 模板)正是 `/historian-capture` 命令的正文契约:证据链→方法→修复手段→函数级实现,而"改进项要有负责人和可验证终态"落在了 G1 行动项表格里。
36
+ SRE postmortem 文化单独值得点名:它把"事件"当一等文档对待。先证据后结论的证据链四段式,正是 `/historian-capture` 命令的正文契约:证据链→方法→修复手段→函数级实现。模板见 `src/index.ts` 的 `CAPTURE_COMMAND_TEMPLATE`。"改进项要有负责人和可验证终态"落在了 G1 行动项表格里。
37
37
 
38
38
  把这些文化做成插件的直接动因,是一个机构记忆问题:这台机器由一个人加一群 AI agent 操作。会话结束,终端滚动条就没了;上下文压缩,细节就丢了。部署过什么、发生过什么事故、踩过什么坑、做过什么决定,三个月后人和 AI 都无从查起。史官要解决的,就是让这台机器的历史变得可检索。
39
39
 
40
40
  ### 目的 / Purpose
41
41
 
42
- 让"这台机器上部署过什么、发生过什么、踩过什么坑、做过什么决定"成为人和 AI 都可索引、可引用、可审计的一等知识:
42
+ 让"这台机器上部署过什么、发生过什么、踩过什么坑、做过什么决定"成为一等知识。人和 AI 都能索引它、引用它、审计它:
43
43
 
44
44
  * 知识落进结构化双语 wiki 页,而不是一次性的会话回复
45
45
  * 每个写操作强制回报 en + zh 双 URL(`URL_MANDATE`,`src/tools/shared.ts:39`),引用链可回溯
@@ -57,7 +57,7 @@ SRE postmortem 文化单独值得点名:它把"事件"当一等文档对待,
57
57
  | 前置查阅回路 | 向每次请求的 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` 钩子 |
58
58
  | 主动留痕 | `/historian-capture` 命令把当前会话总结成 G1 事件页;开启 `capture.enabled` 后额外在会话空闲时弹一次提醒,仅提醒,绝不自动写页 | `src/index.ts` 的 `config` / `event` 钩子 |
59
59
 
60
- G5 现状卡回答"现在跑着什么",timeline 回答"最近两周变了什么"。比如问"`service-a` 现在监听哪个端口",应当命中现状账本里的一行(形如 `example.com:8000`,带上次核实日期与验证命令),而不是某次会话的聊天记录。这两样合起来,wiki 才从文档堆变成可查询的运维账本。
60
+ G5 现状卡回答"现在跑着什么",timeline 回答"最近两周变了什么"。比如问"`service-a` 现在监听哪个端口",答案应当是现状账本里的一行,带上次核实日期与验证命令(形如 `example.com:8000`)。它不该来自某次会话的聊天记录。这两样合起来,wiki 才从文档堆变成可查询的运维账本。
61
61
 
62
62
  知识库要同时满足四种诉求——档案、手册、百科、知识库(速查)。六柱页型加索引层按层分工:
63
63
 
@@ -109,7 +109,7 @@ G5 现状卡回答"现在跑着什么",timeline 回答"最近两周变了什
109
109
 
110
110
  * `sections` 默认空列表 = 不设路径前缀限制,实际写权限由 wiki.js token 的 page rules 决定;包内不携带任何真实主机、真实章节分类学或页面数据
111
111
  * 翻译腿零内置地址:解析链只有 `translate.endpoint` 选项 → 环境变量 `HISTORIAN_TRANSLATE_ENDPOINT` → 未配置,未配置时孪生降级 pending,不发任何网络请求
112
- * `tools/privacy-audit.mjs` 对 `npm pack` 清单里的每个随包文件跑隐私红线 regex(真实主机 / 本机路径 / 本机章节名 / 密钥形态 / 个人身份),任何命中即非零退出、拦住发布;已接入 `prepublishOnly`(build → test → audit)
112
+ * `tools/privacy-audit.mjs` 对 `npm pack` 清单里的每个随包文件跑隐私红线 regex。红线覆盖真实主机、本机路径、本机章节名、密钥形态、个人身份。任何命中即非零退出,拦住发布。它已接入 `prepublishOnly`(build → test → audit)
113
113
  * 随包文本里的示例全部占位符化:`http://<your-wiki>:3000`、`team-notes/`、`example.com`
114
114
 
115
115
  ## 仓库 / Repository
@@ -133,7 +133,7 @@ Source repository is managed by the maintainer; the public distribution channel
133
133
 
134
134
  > 注:npm 包名为 opencode-wiki-historian(opencode-historian 已被注册表上一无关同名包占用);仓库与插件 id 仍为 opencode-historian。
135
135
 
136
- 发布准备状态:包已按 0.1.0 打包就绪(`npm pack` 验证通过),npm 发布需账号 2FA 一次性完成(`npm publish --access public --otp=<code>`)。在发布完成前,方式二 `file://` 为当前可用安装路径。
136
+ 发布状态:包已上架 npm(当前 0.6.2,走 GitHub Actions Trusted Publishing / OIDC,不再需要账号 2FA OTP)。方式一 `npm install` 与方式二 `file://` 两条安装路径均可用;方式二仍是开发态调试首选(改完即生效,无需发版)。
137
137
 
138
138
  ### 方式二:本地路径(开发用)
139
139
 
@@ -145,7 +145,7 @@ Source repository is managed by the maintainer; the public distribution channel
145
145
  }
146
146
  ```
147
147
 
148
- 此方式已通过 `opencode run` 验证,10 个 historian 工具全部注册成功(`.qa/12.txt`)。
148
+ 此方式已通过 `opencode run` 验证,11 个 historian 工具全部注册成功(验证记录为本机 `.qa/` 内部产物,不随包分发)。
149
149
 
150
150
  ### 安装后验证
151
151
 
@@ -155,7 +155,7 @@ Source repository is managed by the maintainer; the public distribution channel
155
155
  opencode run --command historian --message "historian_map show"
156
156
  ```
157
157
 
158
- 如果工具列表中出现 `historian_page_create` 等 10 个工具,安装成功。
158
+ 如果工具列表中出现 `historian_page_create` 等 11 个工具,安装成功。
159
159
 
160
160
  > **升级提示**:如果你之前使用过 historian v2 的扁平 skill 文件(如 `~/.config/opencode/skills/historian.md`),需要先重命名为 `historian.md.v2-disabled` 或移到别处。插件通过 config hook 自动注入 v5 skill,两个同名 skill 不能共存。
161
161
 
@@ -201,7 +201,7 @@ opencode run --command historian --message "historian_map show"
201
201
 
202
202
  `translate.endpoint` 解析链(优先级从高到低):`translate.endpoint` 选项 → 环境变量 `HISTORIAN_TRANSLATE_ENDPOINT` → 未配置。包内**不**内置任何网关地址;未配置时翻译调用直接以 `translate.endpoint not configured` 失败(见降级行为)。
203
203
 
204
- `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` 是插件自记账与索引胶水所需,恒豁免。
204
+ `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` 是插件自记账与索引胶水所需,恒豁免。
205
205
 
206
206
  ### API Key 获取优先级
207
207
 
@@ -227,7 +227,7 @@ key 缺失时 `ConfigError` 记录一次日志,插件工具全部禁用,open
227
227
  | 现象 | 定性 | 说明 |
228
228
  |---|---|---|
229
229
  | 裸配置未传 `translate` 选项(三段 key 链 `translate.apiKey` → `DASHSCOPE_API_KEY` → `translate.providerKey` 全缺)时插件工具全部禁用 | by design | 翻译腿是写操作的前提,缺 key 时宁可整体禁用也不静默半成品;配置按上方选项全表补齐即恢复。缺配置时的部分降级(工具照常注册、仅翻译调用失败)在议 |
230
- | 自进化驱动(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),本机启用要等发布落地后进行;回路代码与测试已就绪,但在真正点亮之前本文档不假装它在跑 |
230
+ | 自进化驱动(readingLoop + capture)默认关闭,作者本机也尚未点亮 | 状态如实 | 两个开关缺省均为 `false`(`src/config.ts:100` `DEFAULT_READING_LOOP`、`src/config.ts:102` `DEFAULT_CAPTURE_ENABLED`),readingLoop 还需配置+哨兵双确认。v0.4.0 时代的人工 2FA 发布流程已被 Trusted Publishing(OIDC)取代,npm 已上架至 0.6.2;回路本机启用仍待点亮;回路代码与测试已就绪,但在真正点亮之前本文档不假装它在跑 |
231
231
 
232
232
  ## wiki.js 前置检查 / Prerequisites
233
233
 
@@ -277,7 +277,7 @@ zh: http://<host>/zh/ops/example
277
277
 
278
278
  **地图视图**:`historian_map show` 输出包含 Locale 和 Twin 列,展示每个路径的双语对应关系。本地镜像文件保存在 `~/.config/opencode/historian-map.json`(`getMap` 读取,带过期秒数);`_meta/page-map` 是 wiki 端的缓存页,由 `historian_map` refresh 写入。
279
279
 
280
- **时间轴视图**:`historian_map action:'timeline'` 把镜像行按 ISO 周分组(可选 `days` 窗口与 `path` 前缀过滤),输出人读周表 + 机读 `weeks` JSON,回答"最近哪些页面变过"。
280
+ **时间轴视图**:`historian_map action:'timeline'` 把镜像行按 ISO 周分组,可选 `days` 窗口与 `path` 前缀过滤。输出人读周表 + 机读 `weeks` JSON,回答"最近哪些页面变过"。
281
281
 
282
282
  **维护视图**:`historian_map action:'maintain'` 输出策展报告——双语缺口、近似重复标题、过期页面、孤儿/扩散候选、标签词表、章节分布。默认 light 档只扫地图行加每个 locale 一次 `pages.list`;`deep:true` 逐页读正文,补新鲜度标记与 Redirect 存根识别。
283
283
 
@@ -298,7 +298,7 @@ zh: http://<host>/zh/ops/example
298
298
 
299
299
  ### 10 项自检门
300
300
 
301
- 每页写入后过一遍自检清单(源码 `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 项要求元数据表含「上次核实」与「复核周期」行:
301
+ 每页写入后过一遍自检清单(源码 `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 项要求元数据表含「上次核实」与「复核周期」行:
302
302
 
303
303
  1. **导言占比 10–15%**:导言 ≈ 正文的 10–15%,每个重要小节在导言至少占一句
304
304
  2. **句长上限**:中文句 ≤20 字、英文句 ≤25 词
@@ -332,7 +332,7 @@ wiki 内容按读者分三层,工具按层执行不同语义(`historian_page
332
332
  historian_page_create({ path: "_evidence/<topic>--<yyyymmdd>", tier: "evidence", content: "<原始件全文>" })
333
333
  ```
334
334
 
335
- - **软提醒语义(soft advisory)**:写前台页时若内容含超过 30 行的围栏代码块,工具结果附一条 `advisory`,提示把原始件搬到 `_evidence/` 页、正文改放决定性摘录(每段 ≤10 行)+ 证据页链接 + 外部链接(commit/PR/告警)。提醒归提醒,写入永不阻断;证据层页自身不跑这项检查。
335
+ - **软提醒语义(soft advisory)**:写前台页时若内容含超过 30 行的围栏代码块,工具结果附一条 `advisory`。它提示把原始件搬到 `_evidence/` 页,正文改放决定性摘录(每段 ≤10 行)+ 证据页链接 + 外部链接(commit/PR/告警)。提醒归提醒,写入永不阻断;证据层页自身不跑这项检查。
336
336
  - **镜像与快照页分工**:本地镜像 `~/.config/opencode/historian-map.json` 是活查询的唯一来源(`historian_map show` 直接读它);`_meta/page-map` wiki 页是审计账本,`historian_map refresh` 每次提交一个新修订,wiki 的页面历史即全库变更时间线。
337
337
 
338
338
  ## wiki.js 用法与定制化 / Usage Guide
@@ -416,17 +416,17 @@ wiki.js GraphQL API 有 9 个常见陷阱。插件在内部处理了每一个(
416
416
  2. **再 apply**:`apply=true`,引擎在首次写入前自动生成 pre-image 备份
417
417
  3. **回滚**:读备份 JSON,用 `historian_page_update` 推回原始内容
418
418
 
419
- 备份文件位于 `results/pilot-backup-*.json`。迁移进度存储在 `~/.config/opencode/historian-migrate.json`,支持断点续跑。
419
+ 备份文件写在运行侧的 `results/pilot-backup-*.json`(该目录为迁移执行记录,不随包分发,外部读者仓库里看不到属预期)。迁移进度存储在 `~/.config/opencode/historian-migrate.json`,支持断点续跑。
420
420
 
421
421
  ### 评测框架
422
422
 
423
- harness repo(与本插件仓库同工作区)提供 7 个行为验收场景,覆盖创建、追加、重叠整合、整理、价值门控、G1 格式、zh URL 报告。v3 插件评测结果:7/7 PASS,51/58 适用分,G=1,零重试(`results/2026-09-02-v3-plugin.md`)。
423
+ 评测框架是维护方的私有 harness 仓库,与插件仓库同工作区,不对外公开。它提供 7 个行为验收场景:创建、追加、重叠整合、整理、价值门控、G1 格式、zh URL 报告。v3 插件最近一轮内部评测:7/7 PASS、51/58 适用分、G=1、零重试。此行为维护记录声明,外部读者无法在本仓库复算,请以此为界。(`results/2026-09-02-v3-plugin.md`)。
424
424
 
425
425
  ## 开发 / Development
426
426
 
427
427
  ```bash
428
428
  npm run build # tsc 编译到 dist/
429
- npm test # vitest run(493 tests, 20 files)
429
+ npm test # vitest run(593 tests, 26 files;其中 4 条依赖本机 tools/redlines.local.json,缺该文件时自动跳过,fresh clone 为 589 跑 + 4 跳过)
430
430
  npm pack --dry-run # 检查打包文件列表
431
431
  ```
432
432
 
package/dist/index.d.ts CHANGED
@@ -7,7 +7,7 @@
7
7
  * The server() hook resolves plugin options and returns:
8
8
  * - config: mutates cfg.skills.paths to ship the bundled skills/ directory
9
9
  * and registers the /historian-capture command (todo 9)
10
- * - tool: 10 historian_* tools wired by buildTools(opts)
10
+ * - tool: 11 historian_* tools wired by buildTools(opts)
11
11
  * - experimental.chat.system.transform: merges the historian-first reading
12
12
  * loop advisory into the LAST system block (single-block-safe append — a
13
13
  * second entry is never added). v3 double gate: 默认 false,true 需配置+哨兵双确认.
package/dist/index.js CHANGED
@@ -7,7 +7,7 @@
7
7
  * The server() hook resolves plugin options and returns:
8
8
  * - config: mutates cfg.skills.paths to ship the bundled skills/ directory
9
9
  * and registers the /historian-capture command (todo 9)
10
- * - tool: 10 historian_* tools wired by buildTools(opts)
10
+ * - tool: 11 historian_* tools wired by buildTools(opts)
11
11
  * - experimental.chat.system.transform: merges the historian-first reading
12
12
  * loop advisory into the LAST system block (single-block-safe append — a
13
13
  * second entry is never added). v3 double gate: 默认 false,true 需配置+哨兵双确认.
package/dist/map.d.ts CHANGED
@@ -59,6 +59,7 @@ export interface RefreshResult {
59
59
  * An existing cache page is patched content-only — updatePage is a full RMW,
60
60
  * so the machine-fact isPrivate/isPublished/tags survive (pitfall #1). */
61
61
  export declare function refreshMapCache(deps: MapDeps, opts?: RefreshOptions): Promise<RefreshResult>;
62
- /** Read the local mirror with staleness in whole seconds; absent or damaged
63
- * mirror → a live build (read-only — no cache page write, no mirror write). */
64
62
  export declare function getMap(deps: MapDeps, homeDir?: string): Promise<MapSnapshot>;
63
+ /** Pure-local mirror read for consumer fallback paths (historian_search zero-hit
64
+ * chain): never touches the network, never builds. Null = absent or damaged. */
65
+ export declare function readMirrorSnapshot(home: string): MapSnapshot | null;
package/dist/map.js CHANGED
@@ -195,6 +195,13 @@ export async function refreshMapCache(deps, opts) {
195
195
  // --- getMap -----------------------------------------------------------------
196
196
  /** Read the local mirror with staleness in whole seconds; absent or damaged
197
197
  * mirror → a live build (read-only — no cache page write, no mirror write). */
198
+ function snapshotOf(mirror) {
199
+ const parsed = Date.parse(mirror.generatedAt);
200
+ const staleSeconds = Number.isNaN(parsed)
201
+ ? null
202
+ : Math.max(0, Math.floor((Date.now() - parsed) / 1000));
203
+ return { rows: mirror.rows, stats: mirror.stats, generatedAt: mirror.generatedAt, staleSeconds };
204
+ }
198
205
  export async function getMap(deps, homeDir) {
199
206
  const home = homeDir ?? homedir();
200
207
  const mirror = readMirror(home);
@@ -202,9 +209,11 @@ export async function getMap(deps, homeDir) {
202
209
  const { rows, stats } = await buildPageMap(deps);
203
210
  return { rows, stats, generatedAt: null, staleSeconds: null };
204
211
  }
205
- const parsed = Date.parse(mirror.generatedAt);
206
- const staleSeconds = Number.isNaN(parsed)
207
- ? null
208
- : Math.max(0, Math.floor((Date.now() - parsed) / 1000));
209
- return { rows: mirror.rows, stats: mirror.stats, generatedAt: mirror.generatedAt, staleSeconds };
212
+ return snapshotOf(mirror);
213
+ }
214
+ /** Pure-local mirror read for consumer fallback paths (historian_search zero-hit
215
+ * chain): never touches the network, never builds. Null = absent or damaged. */
216
+ export function readMirrorSnapshot(home) {
217
+ const mirror = readMirror(home);
218
+ return mirror === null ? null : snapshotOf(mirror);
210
219
  }
@@ -5,7 +5,8 @@
5
5
  */
6
6
  import { tool } from '@opencode-ai/plugin';
7
7
  import { normalizeLocale } from '../wiki/locale.js';
8
- import { listPages, readPage, searchPages } from '../wiki/pages.js';
8
+ import { listPages, readPage, searchPages, } from '../wiki/pages.js';
9
+ import { readMirrorSnapshot } from '../map.js';
9
10
  import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
10
11
  const s = tool.schema;
11
12
  const READ_ARGS = {
@@ -126,10 +127,90 @@ async function unionByAnyTag(client, tags) {
126
127
  return { rows, failed: failures.map((f) => f.tag) };
127
128
  }
128
129
  // --- historian_search --------------------------------------------------------
130
+ const SPLIT_ROW_CAP = 25;
131
+ const MIRROR_ROW_CAP = 10;
132
+ /**
133
+ * Zero-hit fallback chain (live-measured: multi-word queries return 0 from
134
+ * wiki.js even when every sub-word hits; freshly written pages lag the index):
135
+ * 1. whitespace token fan-out, merged by (path, locale), ranked by distinct
136
+ * token hits — a multi-word query must not answer 0 while sub-words hit;
137
+ * 2. pure-local page-map mirror scan on title/path substrings — closes the
138
+ * index-lag window for addressable titles without any network fan-out;
139
+ * 3. honest hint — the remaining content-level lag is named, never hidden
140
+ * behind a bare zero.
141
+ * The direct-hit path is byte-identical to the legacy behavior: one request,
142
+ * no extra envelope fields. Leg failures are dropped and named (same
143
+ * resilience contract as unionByAnyTag); only an all-legs-failed split throws.
144
+ */
145
+ async function searchFallback(client, homeDir, query, direct) {
146
+ if (direct.results.length > 0)
147
+ return { resp: direct, fallback: {} };
148
+ const tokens = [...new Set(query.trim().split(/\s+/).filter((t) => t.length > 0))];
149
+ if (tokens.length >= 2) {
150
+ const legs = await Promise.allSettled(tokens.map((t) => searchPages(client, t)));
151
+ const failed = [];
152
+ const byKey = new Map();
153
+ legs.forEach((leg, i) => {
154
+ if (leg.status === 'rejected') {
155
+ failed.push(tokens[i]);
156
+ return;
157
+ }
158
+ for (const r of leg.value.results) {
159
+ const k = matchKey(r.path, r.locale);
160
+ const seen = byKey.get(k);
161
+ if (seen === undefined)
162
+ byKey.set(k, { row: r, hits: 1 });
163
+ else
164
+ seen.hits += 1;
165
+ }
166
+ });
167
+ if (failed.length === tokens.length)
168
+ throw legs[0].status === 'rejected' ? legs[0].reason : new Error('token-split failed');
169
+ if (byKey.size > 0) {
170
+ const rows = [...byKey.values()]
171
+ .sort((a, b) => b.hits - a.hits || (a.row.path < b.row.path ? -1 : a.row.path > b.row.path ? 1 : 0) || (a.row.locale < b.row.locale ? -1 : 1))
172
+ .slice(0, SPLIT_ROW_CAP)
173
+ .map((v) => v.row);
174
+ return {
175
+ resp: { results: rows, suggestions: direct.suggestions, totalHits: rows.length },
176
+ fallback: { strategy: 'token-split', tokens, ...(failed.length > 0 ? { splitFailed: failed } : {}) },
177
+ };
178
+ }
179
+ }
180
+ const snap = readMirrorSnapshot(homeDir);
181
+ if (snap !== null && tokens.length > 0) {
182
+ const lowered = tokens.map((t) => t.toLowerCase());
183
+ const hits = snap.rows
184
+ .filter((r) => lowered.some((t) => r.title.toLowerCase().includes(t) || r.path.toLowerCase().includes(t)))
185
+ .slice(0, MIRROR_ROW_CAP);
186
+ if (hits.length > 0) {
187
+ const rows = hits.map((r) => ({
188
+ id: String(r.id),
189
+ title: r.title,
190
+ description: '',
191
+ path: r.path,
192
+ locale: r.locale,
193
+ }));
194
+ return {
195
+ resp: { results: rows, suggestions: direct.suggestions, totalHits: rows.length },
196
+ fallback: { strategy: 'map-mirror', tokens, mapGeneratedAt: snap.generatedAt, mapStaleSeconds: snap.staleSeconds },
197
+ };
198
+ }
199
+ }
200
+ return {
201
+ resp: direct,
202
+ fallback: {
203
+ hint: 'no text-index or mirror hit; content written in the last minutes may lag the search index — verify via historian_read / historian_map',
204
+ },
205
+ };
206
+ }
129
207
  export function makeSearchTool(deps) {
130
208
  return tool({
131
209
  description: `Full-text search over the wiki. kind is informational intent only — the live wiki.js ` +
132
210
  `search indexes title AND content (the engine signature is search(query, path, locale), no field scope). ` +
211
+ `A zero-hit answer is auto-widened: multi-word queries fan out per word and merge (` +
212
+ `strategy "token-split"), then a local page-map mirror scans titles/paths (strategy "map-mirror"); ` +
213
+ `a bare zero without those carries a hint. ` +
133
214
  `Optional tags filter: tagsMode "all" (DEFAULT) requires EVERY tag on the page (server-side ` +
134
215
  `AND); "any" matches AT LEAST ONE tag. Result rows carry each page's tags. ` +
135
216
  `Results carry their en/zh URLs. ${URL_MANDATE}.`,
@@ -138,7 +219,8 @@ export function makeSearchTool(deps) {
138
219
  const args = SearchArgsSchema.parse(raw);
139
220
  try {
140
221
  const client = deps.getClient();
141
- const resp = await searchPages(client, args.query);
222
+ const direct = await searchPages(client, args.query);
223
+ const { resp, fallback } = await searchFallback(client, deps.homeDir, args.query, direct);
142
224
  const results = resp.results.map((r) => {
143
225
  try {
144
226
  const locale = normalizeLocale(r.locale);
@@ -163,6 +245,7 @@ export function makeSearchTool(deps) {
163
245
  totalHits: resp.totalHits,
164
246
  suggestions: resp.suggestions,
165
247
  results,
248
+ ...fallback,
166
249
  });
167
250
  }
168
251
  const wanted = [...new Set(args.tags.map((t) => t.trim()))];
@@ -202,6 +285,7 @@ export function makeSearchTool(deps) {
202
285
  totalHits: matched.length,
203
286
  suggestions: resp.suggestions,
204
287
  results: matched,
288
+ ...fallback,
205
289
  });
206
290
  }
207
291
  catch (err) {
@@ -73,6 +73,9 @@ export declare function enforceTierPath(tier: Tier, path: string): string | null
73
73
  export declare function tierMismatchJson(message: string): ToolResult;
74
74
  /** Evidence-tier zh-side input → refusal envelope (monolingual invariant). */
75
75
  export declare function monolingualRefusalJson(toolName: string, argumentName: string): ToolResult;
76
+ /** historian_page_append got a non-empty `content` that `section` does not carry →
77
+ * refuse loudly instead of silently dropping it (infra handoff 2026-10-23). */
78
+ export declare function contentArgRefusalJson(): ToolResult;
76
79
  /** Soft-gate advisory for front-tier raw dumps: null when nothing to say
77
80
  * (evidence tier NEVER checked — machine pages are the raw-material home;
78
81
  * fence at or under the limit). The advisory is informational only: every
@@ -142,6 +142,17 @@ export function monolingualRefusalJson(toolName, argumentName) {
142
142
  actionableHint: 'Drop the zh-side argument (locale "zh" / sectionZh) — evidence machine pages never carry a bilingual twin.',
143
143
  });
144
144
  }
145
+ /** historian_page_append got a non-empty `content` that `section` does not carry →
146
+ * refuse loudly instead of silently dropping it (infra handoff 2026-10-23). */
147
+ export function contentArgRefusalJson() {
148
+ return dump({
149
+ ok: false,
150
+ error: 'append-content-arg-ignored',
151
+ errorKind: 'AppendContentArgError',
152
+ message: 'historian_page_append ignores the "content" argument; only "section" is appended. A non-empty content that section does not already contain would be silently lost, so this call is refused.',
153
+ actionableHint: 'Re-call with section set to the full text to append (title + body). A content already contained in section is accepted and ignored.',
154
+ });
155
+ }
145
156
  // --- Front-tier raw-dump soft gate (v3 todo 6) --------------------------------
146
157
  /** Contract band (SKILL.md SYN-16): a human page stays a 5-10 line excerpt;
147
158
  * longer raw material belongs on an evidence page. Strictly ABOVE this many
@@ -7,7 +7,7 @@
7
7
  import { tool } from '@opencode-ai/plugin';
8
8
  import { appendSection, createPage, updatePage, PageNotFoundError } from '../wiki/pages.js';
9
9
  import { readPage } from '../wiki/pages.read.js';
10
- import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, publishGateRefusalJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
10
+ import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, contentArgRefusalJson, okJson, publishGateRefusalJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
11
11
  const s = tool.schema;
12
12
  const UPDATE_ARGS = {
13
13
  path: s.string(),
@@ -100,6 +100,7 @@ const APPEND_ARGS = {
100
100
  locale: s.enum(['en', 'zh']).default('en'),
101
101
  sectionZh: s.string().optional().describe('Explicit zh section; when absent the zh side falls back to translation/wiring'),
102
102
  tier: s.enum(TIERS).optional().describe('Explicit tier; absent → inferred from the path (first segment _meta/ or _evidence/ ⇒ evidence, else front)'),
103
+ content: s.string().optional().describe('UNUSED on append — all text must go in section; a non-empty content not contained in section makes the call refuse'),
103
104
  };
104
105
  const AppendArgsSchema = s.object(APPEND_ARGS);
105
106
  export function makeAppendTool(deps) {
@@ -111,6 +112,10 @@ export function makeAppendTool(deps) {
111
112
  args: APPEND_ARGS,
112
113
  execute: async (raw) => {
113
114
  const args = AppendArgsSchema.parse(raw);
115
+ // Loud guard: `content` is not an append channel — never drop text silently.
116
+ if (args.content !== undefined && args.content.trim() !== '' && !args.section.includes(args.content.trim())) {
117
+ return contentArgRefusalJson();
118
+ }
114
119
  // Exactly ONE resolution rule: explicit tier arg wins; otherwise infer
115
120
  // from the path prefix (internal namespace ⇒ evidence).
116
121
  const tier = args.tier ?? inferredTier(args.path);
package/dist/tools.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * historian_* tool surface (todo 11) — barrel + composition.
3
3
  *
4
- * buildTools wires the 10 custom tools from the engine modules; this file
4
+ * buildTools wires the 11 custom tools from the engine modules; this file
5
5
  * holds no engine logic, only wiring. Per-call construction (no module-level
6
6
  * cache — each buildTools call resolves a fresh client/translator), and the
7
7
  * client is resolved LAZILY: a missing/invalid wiki key surfaces as a
package/dist/tools.js CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * historian_* tool surface (todo 11) — barrel + composition.
3
3
  *
4
- * buildTools wires the 10 custom tools from the engine modules; this file
4
+ * buildTools wires the 11 custom tools from the engine modules; this file
5
5
  * holds no engine logic, only wiring. Per-call construction (no module-level
6
6
  * cache — each buildTools call resolves a fresh client/translator), and the
7
7
  * client is resolved LAZILY: a missing/invalid wiki key surfaces as a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-wiki-historian",
3
- "version": "0.6.1",
3
+ "version": "0.6.2",
4
4
  "description": "opencode plugin that manages a wiki.js knowledge base with bilingual pages, genre templates, and migration tooling.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -28,6 +28,9 @@
28
28
  "vitest": "^2.1.4",
29
29
  "zod": "^3.23.8"
30
30
  },
31
+ "engines": {
32
+ "node": ">=20"
33
+ },
31
34
  "scripts": {
32
35
  "build": "tsc",
33
36
  "test": "vitest run",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: historian
3
- description: "Wiki.js 史官插件技能:双语孪生页面管理(en/zh)、G1-G6 页型骨架、V6 进化驱动机构记忆层(三回路:捕获 /historian-capture 触发器 + 策展 maintain 报告 + 闸门 reading loop/十项自检/sections guard)、可发布 OpenCode 插件。Phase 1.5 页型分类确保每页匹配正确的知识形态。操作 10 个 historian_* 工具完成搜索、阅读、创建、更新、追加、翻译、迁移、移动、删除与页面地图/时间线/维护扫描。"
3
+ description: "Wiki.js 史官插件技能:双语孪生页面管理(en/zh)与 G1-G6 页型骨架,是可发布 OpenCode 插件。V6 进化驱动机构记忆层三回路:捕获、策展、闸门。捕获走 /historian-capture 触发器;策展出 maintain 报告;闸门含 reading loop、十项自检、sections guard。Phase 1.5 页型分类确保每页匹配正确的知识形态。操作 11 个 historian_* 工具:搜索、阅读、创建、更新、追加、翻译、迁移、移动、删除。另有锚印封存(anchor:人类订单/批准消息的哈希封存与对账)与页面地图/时间线/维护扫描。"
4
4
  ---
5
5
 
6
6
  # 史官 (Historian) — 行为契约 V6 进化驱动
@@ -14,7 +14,7 @@ description: "Wiki.js 史官插件技能:双语孪生页面管理(en/zh)
14
14
  3. **一页一问**。回答了两个问题就拆;两个页面答同一个就合并或 supersede。
15
15
  4. **每页可达**。无入链的页面是孤儿债。创建的每个页面在同一次运行中拿到反向链接。
16
16
  5. **索引是每次变更的一部分**。让 wiki-index 过期的变更是未完成的变更。
17
- 6. **回路闭环**。捕获有触发器、策展有报告、写入有闸门——每条回路都跑完自己的处置,不留半截。
17
+ 6. **回路各有终点**。捕获有触发器、策展有报告、写入有闸门——每条回路都跑完自己的处置,不留半截。
18
18
 
19
19
  ### 分层职责 (Tier responsibilities)
20
20
 
@@ -28,7 +28,7 @@ description: "Wiki.js 史官插件技能:双语孪生页面管理(en/zh)
28
28
 
29
29
  ## 三回路总览 (Three Loops)
30
30
 
31
- V6 的机构记忆层由三条回路组成,共用同一套 10 个 `historian_*` 工具:
31
+ V6 的机构记忆层由三条回路组成,共用同一套 11 个 `historian_*` 工具:
32
32
 
33
33
  ```
34
34
  回路 驱动方式 入口 产出
@@ -69,7 +69,7 @@ V6 的机构记忆层由三条回路组成,共用同一套 10 个 `historian_*
69
69
 
70
70
  ### 章节分类学
71
71
 
72
- 顶级章节**按机器配置**,插件不内置任何特定部署的章节表:可写前缀白名单由插件选项 `sections` 传入(默认为空 = 不限制前缀;实际权限由 wiki.js token 的 page rules 决定)。当前实例的章节布局以 `historian_map show` 输出或用户说明为准,不要臆断。豁免段(`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence`)恒可写,见闸门回路 sections guard。
72
+ 顶级章节**按机器配置**,插件不内置任何特定部署的章节表。可写前缀白名单由插件选项 `sections` 传入,默认为空 = 不限制前缀。实际权限由 wiki.js token 的 page rules 决定。当前实例的章节布局以 `historian_map show` 输出或用户说明为准,不要臆断。豁免段(`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence`)恒可写,见闸门回路 sections guard。
73
73
 
74
74
  假想实例的占位示例(仅示意,非真实章节表):
75
75
 
@@ -196,16 +196,16 @@ G5 现状卡的硬约束:状态块是机读单行(`Active` / `Superseded-by:
196
196
  |------|------|----------|
197
197
  | `historian_page_create` | 创建页面(含孪生) | `path`, `title`, `content`(缺省=返回本地骨架), `genre`(G1-G6), `locale`(en/zh, 缺省 en), `isPublished`(缺省 true), `tags`(缺省 []), `twin`(缺省 true), `tier`(缺省前台;`"evidence"`=证据层) |
198
198
  | `historian_page_update` | 更新页面(全量合并) | `path`, `locale`, `title?`, `content?`, `description?`, `tags?` |
199
- | `historian_page_append` | 追加到页面(双 locale) | `path`, `section`, `locale`, `sectionZh?` |
199
+ | `historian_page_append` | 追加到页面(双 locale)。**正文一律放 `section`**;`content` 参数对追加无效——传入非空且未被 section 包含的 content 会被当场拒绝而非静默丢弃 | `path`, `section`, `locale`, `sectionZh?` |
200
200
  | `historian_translate_snippet` | 翻译片段 | `text`, `from`(en/zh), `to`(en/zh) |
201
- | `historian_search` | 搜索页面 | `query`, `kind`(title/content), `tags?`(1-5 个), `tagsMode?`(all 缺省/any) |
201
+ | `historian_search` | 搜索页面。多词查询 0 命中时自动按词拆分合并(信封 `strategy:"token-split"`),再落本地页镜像按标题/路径兜底(`"map-mirror"`,行带滞后秒数);纯 0 命中带 `hint` 指路。注意:刚写入的正文进全文索引有延迟,写入后验证一律用 `historian_read`,勿用 search | `query`, `kind`(title/content), `tags?`(1-5 个), `tagsMode?`(all 缺省/any) |
202
202
  | `historian_read` | 读取页面 | `path`, `locale` |
203
203
  | `historian_map` | 页面地图/时间线/维护扫描 | `action`(show/refresh/timeline/maintain);maintain 可选 `deep`(缺省 false=light 扫);timeline 可选 `days`(近 N 天)与 `path`(前缀过滤);输出人读 markdown + 机读 JSON,zh/en 行独立;maintain 同时返回 surface 接口面体检(信封 `historian.maintain.v3`) |
204
204
  | `historian_migrate` | 迁移页面到规范 | `path`, `genre?`, `apply`(false/true) |
205
205
  | `historian_delete` | 删除页面 | `path`, `locale`, `confirm`(必须 "yes") |
206
206
  | `historian_move` | 移动页面 | `path`, `locale`, `newPath`, `newLocale?`, `confirm`(必须 "yes") |
207
207
 
208
- 删除/移动前,先确认内容已在别处留存(preimage 快照、`_evidence/` 证据页或备份):`confirm: "yes"` 只是防误触闸门,口头确认不等于已留存。
208
+ 删除/移动前,先确认内容已在别处留存(preimage 快照、`_evidence/` 证据页或备份)。`confirm: "yes"` 只是防误触闸门,口头确认不等于已留存。
209
209
 
210
210
  ### 翻译失败处理
211
211
 
@@ -280,7 +280,7 @@ historian_map action:'refresh'
280
280
 
281
281
  ## 进化驱动 (V6):三回路细则
282
282
 
283
- 插件从"被动工具集"经"机构记忆层"两轮演进,到 V6 升级为"进化驱动":机器侧三回路闭环,均不影响上述人工分诊/写作闸门。
283
+ 插件从"被动工具集"经"机构记忆层"两轮演进,到 V6 升级为"进化驱动"。机器侧三条回路各自完整运转,均不影响上述人工分诊/写作闸门。
284
284
 
285
285
  ### 捕获回路 (capture):/historian-capture
286
286
 
@@ -290,7 +290,7 @@ historian_map action:'refresh'
290
290
 
291
291
  | 触发器 | 信号 | 必留要点 |
292
292
  |--------|------|----------|
293
- | 事故闭环 incident closed | 故障已定位根因并闭环 | 症状→根因→修复→预防的完整证据 |
293
+ | 事故闭环 incident closed | 故障已定位根因,修复经验证生效(状态令牌名沿用历史写法) | 症状→根因→修复→预防的完整证据 |
294
294
  | 部署完成 deployment completed | 部署落地并验证 | 版本/端口/验证命令 + 核实日期 |
295
295
  | bug修复合入 bugfix merged | 修复合入主干 | 触发条件 ↔ 修复函数的对应关系 |
296
296
  | 探针结论 probe/eval conclusion | 探针/评测得出可复用结论 | 数据、判据、结论三件套 |
@@ -307,7 +307,7 @@ historian_map action:'refresh'
307
307
 
308
308
  超 10 行的原始件一律拆到 `_evidence/` 证据页(`historian_page_create` 传 `tier:"evidence"`:单语 en、不发布),主页面只放引用/摘要 + 证据页链接。
309
309
 
310
- 引用模型的字面特殊标记文本(如 `<|im_start|>` 一类控制 token)时,永不把原始 token 写入档案:用语言描述它(如"思考结束标记 / end-of-thinking marker"),避免原始标记回流污染下游模型会话。
310
+ 引用模型的字面特殊标记文本(如 `<|im_start|>` 一类控制 token)时,永不把原始 token 写入档案。用语言描述它,如"思考结束标记 / end-of-thinking marker",避免原始标记回流污染下游模型会话。
311
311
 
312
312
  #### SRE 元数据表
313
313
 
@@ -327,7 +327,7 @@ historian_map action:'refresh'
327
327
  - **light 扫:每次批量写后必跑**——只基于地图行 + 每 locale 一次只读 `pages.list`(便宜,随批走)
328
328
  - **deep 扫:每周至多一次**——逐页读正文,跑新鲜度(缺「上次核实于」/ 复核过期)与 `> Redirect:` 存根计数(贵,克制用)
329
329
 
330
- light 扫在 maintain 行之外附带 **surface-light**:`coverage`(live 页面与地图不一致)、`nav`(侧栏真相=实时导航树:mode 非 STATIC 即把页面树镜像回侧栏 / 树内挂 `_` 段链接 / 章节缺落地页→面包屑 404)、`tagsEmpty`;deep 扫附带 **surface-deep**:正文级检测,逐页一次读取、双消费者共享缓存。
330
+ light 扫在 maintain 行之外附带 **surface-light** 三类:`coverage`(live 页面与地图不一致)、`nav`、`tagsEmpty`。`nav` 的真相源是实时导航树:mode 非 STATIC 即把页面树镜像回侧栏;树内挂 `_` 段链接、章节缺落地页会造成面包屑 404。deep 扫附带 **surface-deep**:正文级检测,逐页一次读取、双消费者共享缓存。
331
331
 
332
332
  报告行 → 处置映射表:
333
333
 
@@ -355,11 +355,11 @@ light 扫在 maintain 行之外附带 **surface-light**:`coverage`(live 页
355
355
 
356
356
  #### Reading loop(自动注入,默认关闭)
357
357
 
358
- 插件经 `experimental.chat.system.transform` 钩子向每次请求的 system 提示注入一段"wiki 优先"advisory:动手前先查索引(`historian_read wiki-index` 或 `historian_map action:"show"`)再 `historian_search`、近期变更查 `historian_map action=timeline`、当前部署态看 G5 现状卡并核实行「上次核实于」、优先更新已有页而非新建、引用所依赖的页面 URL。agent 的义务是**执行**它,不是忽略它。
358
+ 插件经 `experimental.chat.system.transform` 钩子向每次请求的 system 提示注入一段"wiki 优先"advisory。它要求:动手前先查索引(`historian_read wiki-index` 或 `historian_map action:"show"`),再 `historian_search`。近期变更查 `historian_map action=timeline`。当前部署态看 G5 现状卡,并核实行「上次核实于」。优先更新已有页而非新建,并引用所依赖的页面 URL。agent 的义务是**执行**它,不是忽略它。
359
359
 
360
360
  - 双信号门控:仅当**同时**满足两条信号才注入——插件二元组第二参数配 `"readingLoop": true`,**且**本机存在哨兵文件 `~/.config/opencode/historian-reading-loop.json`(内容 `{"version":1,"confirmed":true}`)。任一缺失即不注入。开关默认 false,开启需配置+哨兵双确认;启用步骤见 `references/adapting-your-own-wiki.md`。
361
361
  - 配置已开而哨兵缺失时,插件加载期打一条 console.error(给出哨兵路径与内容),不会静默失灵。
362
- - 注入语义为**单块追加**:advisory 拼接到 system 提示的最后一个块(`\n\n` 分隔),system 为空数组时才新建块——绝不产生第二条 system 消息。严格 OpenAI 兼容后端(如 vLLM)会以 `System message must be at the beginning.` 拒绝多 system 请求,单块追加从根上规避此坑。
362
+ - 注入语义为**单块追加**:advisory 拼接到 system 提示的最后一个块,以 `\n\n` 分隔。system 为空数组时才新建块,绝不产生第二条 system 消息。严格 OpenAI 兼容后端(如 vLLM)会以 `System message must be at the beginning.` 拒绝多 system 请求,单块追加从根上规避此坑。
363
363
  - 幂等去重:同一请求的任一 system 块已含 `historian_search` 字样则跳过注入。
364
364
 
365
365
  #### 发布闸门 publish gate(写入硬拒,v0.5.0)
@@ -387,7 +387,7 @@ light 扫在 maintain 行之外附带 **surface-light**:`coverage`(live 页
387
387
 
388
388
  ### Opportunistic backfill(顺手补骨架)
389
389
 
390
- - **touch=顺手 migrate**:因任何任务编辑某页时,若该页仍是旧版自由文本,顺手 `historian_migrate`(先 dry-run 评分再 apply)补当前页型骨架——触碰即进化,零额外调度。
390
+ - **touch=顺手 migrate**:因任何任务编辑某页时,若该页仍是旧版自由文本,顺手 `historian_migrate` 补当前页型骨架:先 dry-run 评分,再 apply。触碰即进化,零额外调度。
391
391
  - **尾部页不专项清扫**:不为补骨架专门发起全库扫尾;低频页等下一次 touch。deep maintain 的 staleness/freshness 报告是唯一的尾部线索来源,按报告行处置即可。
392
392
 
393
393
  ---