opencode-wiki-historian 0.6.1 → 0.6.3
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 +17 -17
- package/dist/config.d.ts +5 -1
- package/dist/config.js +9 -10
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/map.d.ts +3 -2
- package/dist/map.js +14 -5
- package/dist/tools/read.js +86 -2
- package/dist/tools/shared.d.ts +3 -0
- package/dist/tools/shared.js +11 -0
- package/dist/tools/write.js +6 -1
- package/dist/tools.d.ts +1 -1
- package/dist/tools.js +1 -1
- package/dist/translate.js +13 -2
- package/package.json +4 -1
- package/skills/historian/SKILL.md +14 -14
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ opencode-historian 把 wiki.js 的读写、翻译、页型规范、迁移工具
|
|
|
8
8
|
|
|
9
9
|
功能一览:
|
|
10
10
|
|
|
11
|
-
*
|
|
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
|
-
|
|
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 文化单独值得点名:它把"事件"
|
|
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
|
-
让"这台机器上部署过什么、发生过什么、踩过什么坑、做过什么决定"
|
|
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` 现在监听哪个端口"
|
|
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
|
|
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
|
-
|
|
136
|
+
发布状态:包已上架 npm(当前 0.6.3,走 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` 验证,
|
|
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` 等
|
|
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` 默认为空列表 =
|
|
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
|
|
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.3;回路本机启用仍待点亮;回路代码与测试已就绪,但在真正点亮之前本文档不假装它在跑 |
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
419
|
+
备份文件写在运行侧的 `results/pilot-backup-*.json`(该目录为迁移执行记录,不随包分发,外部读者仓库里看不到属预期)。迁移进度存储在 `~/.config/opencode/historian-migrate.json`,支持断点续跑。
|
|
420
420
|
|
|
421
421
|
### 评测框架
|
|
422
422
|
|
|
423
|
-
harness
|
|
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(
|
|
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/config.d.ts
CHANGED
|
@@ -100,7 +100,11 @@ export declare const DEFAULT_CAPTURE_ENABLED = false;
|
|
|
100
100
|
* 2. env DASHSCOPE_API_KEY
|
|
101
101
|
* 3. jsonc provider[translate.providerKey].options.apiKey — only when
|
|
102
102
|
* `translate.providerKey` is set explicitly (no default provider name)
|
|
103
|
-
* 4.
|
|
103
|
+
* 4. unset ('') — deferred: the first translate call fails loudly as
|
|
104
|
+
* TranslateError('config') with the three-leg prescription (translate.ts).
|
|
105
|
+
* Absence NEVER disables the wiki tools at load time — an operator who
|
|
106
|
+
* binds no translation model still gets every other tool, with twins
|
|
107
|
+
* degrading to pending (the README config-table contract).
|
|
104
108
|
*
|
|
105
109
|
* Translation endpoint priority: raw.translate.endpoint →
|
|
106
110
|
* env HISTORIAN_TRANSLATE_ENDPOINT → unset (''). There is no baked-in
|
package/dist/config.js
CHANGED
|
@@ -46,7 +46,11 @@ export const DEFAULT_CAPTURE_ENABLED = false;
|
|
|
46
46
|
* 2. env DASHSCOPE_API_KEY
|
|
47
47
|
* 3. jsonc provider[translate.providerKey].options.apiKey — only when
|
|
48
48
|
* `translate.providerKey` is set explicitly (no default provider name)
|
|
49
|
-
* 4.
|
|
49
|
+
* 4. unset ('') — deferred: the first translate call fails loudly as
|
|
50
|
+
* TranslateError('config') with the three-leg prescription (translate.ts).
|
|
51
|
+
* Absence NEVER disables the wiki tools at load time — an operator who
|
|
52
|
+
* binds no translation model still gets every other tool, with twins
|
|
53
|
+
* degrading to pending (the README config-table contract).
|
|
50
54
|
*
|
|
51
55
|
* Translation endpoint priority: raw.translate.endpoint →
|
|
52
56
|
* env HISTORIAN_TRANSLATE_ENDPOINT → unset (''). There is no baked-in
|
|
@@ -83,16 +87,11 @@ function resolveTranslationApiKey(raw, env, homeDir, providerKey) {
|
|
|
83
87
|
if (isNonEmpty(envKey))
|
|
84
88
|
return envKey;
|
|
85
89
|
if (providerKey !== '') {
|
|
86
|
-
|
|
87
|
-
if (isNonEmpty(jsoncKey))
|
|
88
|
-
return jsoncKey;
|
|
90
|
+
return readProviderApiKeyFromJsonc(homeDir, providerKey) ?? '';
|
|
89
91
|
}
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
throw new ConfigError('missing-translation-key', `Missing translation api key: set plugin option translate.apiKey, ` +
|
|
94
|
-
`export DASHSCOPE_API_KEY, or ${jsoncHint} ` +
|
|
95
|
-
`in ${opencodeJsoncPath(homeDir)}.`);
|
|
92
|
+
// No leg produced a key: yield '' (deferred). Load-time absence is a supported
|
|
93
|
+
// state (wiki tools alive, twins pending); the loud failure is at call time.
|
|
94
|
+
return '';
|
|
96
95
|
}
|
|
97
96
|
/**
|
|
98
97
|
* Read the wiki.js api key. Priority: key file (path from options.apiKeyPath,
|
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
|
+
* - 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
|
+
* - 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
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
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
|
}
|
package/dist/tools/read.js
CHANGED
|
@@ -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
|
|
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) {
|
package/dist/tools/shared.d.ts
CHANGED
|
@@ -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
|
package/dist/tools/shared.js
CHANGED
|
@@ -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
|
package/dist/tools/write.js
CHANGED
|
@@ -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
|
|
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
|
|
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/translate.js
CHANGED
|
@@ -102,9 +102,13 @@ export function pickResponseText(json) {
|
|
|
102
102
|
const out = isRecord(content[0]) && content[0].type === 'text' && typeof content[0].text === 'string'
|
|
103
103
|
? content[0].text
|
|
104
104
|
: texts.join('');
|
|
105
|
-
|
|
105
|
+
// Wrapping whitespace is transport residue, never translation content: some
|
|
106
|
+
// adaptor lanes pad text parts with leading blank lines, and chunk-rejoining
|
|
107
|
+
// ('.join('\n\n')) would bake that padding into page bodies.
|
|
108
|
+
const trimmed = out.trim();
|
|
109
|
+
if (trimmed === '')
|
|
106
110
|
throw new TranslateError('malformed', 'response text is empty');
|
|
107
|
-
return
|
|
111
|
+
return trimmed;
|
|
108
112
|
}
|
|
109
113
|
// --- System prompt ----------------------------------------------------------
|
|
110
114
|
/** Machine-consumed routing tokens (DIRECTION, GLOSSARY table) plus the
|
|
@@ -132,6 +136,13 @@ export async function callMessages(opts, deps, call) {
|
|
|
132
136
|
'env HISTORIAN_TRANSLATE_MODEL to a model YOUR device is authorized for ' +
|
|
133
137
|
'(L-MACHINE-LOCAL: the package ships no device model defaults).');
|
|
134
138
|
}
|
|
139
|
+
if (opts.translate.apiKey.trim() === '') {
|
|
140
|
+
const hint = opts.translate.providerKey !== ''
|
|
141
|
+
? `or add provider["${opts.translate.providerKey}"].options.apiKey`
|
|
142
|
+
: 'or set translate.providerKey and add provider["<name>"].options.apiKey';
|
|
143
|
+
throw new TranslateError('config', 'Missing translation api key — set plugin option translate.apiKey, ' +
|
|
144
|
+
`export DASHSCOPE_API_KEY, ${hint} in ~/.config/opencode/opencode.jsonc.`);
|
|
145
|
+
}
|
|
135
146
|
const url = normalizeMessagesUrl(opts.translate.endpoint);
|
|
136
147
|
const key = opts.translate.apiKey;
|
|
137
148
|
const fetchImpl = deps?.fetchImpl ?? fetch;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "opencode-wiki-historian",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.3",
|
|
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
|
|
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 的机构记忆层由三条回路组成,共用同一套
|
|
31
|
+
V6 的机构记忆层由三条回路组成,共用同一套 11 个 `historian_*` 工具:
|
|
32
32
|
|
|
33
33
|
```
|
|
34
34
|
回路 驱动方式 入口 产出
|
|
@@ -69,7 +69,7 @@ V6 的机构记忆层由三条回路组成,共用同一套 10 个 `historian_*
|
|
|
69
69
|
|
|
70
70
|
### 章节分类学
|
|
71
71
|
|
|
72
|
-
|
|
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
|
|
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` |
|
|
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/`
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
390
|
+
- **touch=顺手 migrate**:因任何任务编辑某页时,若该页仍是旧版自由文本,顺手 `historian_migrate` 补当前页型骨架:先 dry-run 评分,再 apply。触碰即进化,零额外调度。
|
|
391
391
|
- **尾部页不专项清扫**:不为补骨架专门发起全库扫尾;低频页等下一次 touch。deep maintain 的 staleness/freshness 报告是唯一的尾部线索来源,按报告行处置即可。
|
|
392
392
|
|
|
393
393
|
---
|