opencode-wiki-historian 0.6.2 → 0.7.0
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.en.md +156 -42
- package/README.md +127 -360
- package/dist/anchor.js +4 -4
- package/dist/config.d.ts +8 -4
- package/dist/config.js +12 -13
- package/dist/index.d.ts +14 -4
- package/dist/index.js +21 -52
- package/dist/lint.d.ts +2 -2
- package/dist/lint.js +2 -2
- package/dist/maintain.d.ts +2 -2
- package/dist/maintain.js +7 -7
- package/dist/map.d.ts +1 -1
- package/dist/map.js +1 -1
- package/dist/migrate-apply.d.ts +1 -1
- package/dist/migrate-apply.js +1 -1
- package/dist/migrate-score.d.ts +2 -2
- package/dist/migrate-score.js +3 -3
- package/dist/migrate-store.d.ts +1 -1
- package/dist/migrate-store.js +1 -1
- package/dist/migrate.d.ts +2 -2
- package/dist/migrate.js +2 -2
- package/dist/prompts.d.ts +20 -0
- package/dist/prompts.js +46 -0
- package/dist/skills.d.ts +33 -0
- package/dist/skills.js +88 -0
- package/dist/surface.d.ts +1 -1
- package/dist/surface.js +2 -2
- package/dist/templates/evidence.d.ts +1 -1
- package/dist/templates/evidence.js +1 -1
- package/dist/templates/genres.d.ts +5 -5
- package/dist/templates/genres.js +7 -7
- package/dist/templates/skeletons.d.ts +3 -3
- package/dist/templates/skeletons.js +3 -3
- package/dist/tools/anchor.js +2 -2
- package/dist/tools/create.js +1 -1
- package/dist/tools/local.js +1 -1
- package/dist/tools/mutate.d.ts +1 -1
- package/dist/tools/mutate.js +1 -1
- package/dist/tools/shared.d.ts +3 -3
- package/dist/tools/shared.js +10 -10
- package/dist/tools.d.ts +2 -2
- package/dist/tools.js +2 -2
- package/dist/translate.d.ts +1 -1
- package/dist/translate.js +14 -3
- package/dist/v2.d.ts +114 -0
- package/dist/v2.js +249 -0
- package/dist/wiki/assets.d.ts +1 -1
- package/dist/wiki/assets.js +1 -1
- package/dist/wiki/client.d.ts +2 -3
- package/dist/wiki/client.js +2 -3
- package/dist/wiki/locale.d.ts +1 -1
- package/dist/wiki/locale.js +3 -3
- package/dist/wiki/pages.read.d.ts +1 -1
- package/dist/wiki/pages.write.d.ts +1 -1
- package/package.json +1 -1
- package/skills/historian/SKILL.md +2 -2
package/README.md
CHANGED
|
@@ -1,437 +1,204 @@
|
|
|
1
1
|
# opencode-historian
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> 中文(本页) | [English →](README.en.md)
|
|
4
4
|
|
|
5
|
-
> OpenCode 插件:双语 wiki.js
|
|
5
|
+
> OpenCode 插件:双语 wiki.js 知识库管理。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## 这是什么
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
opencode-historian 把 wiki.js 的读写、翻译、页型规范和迁移工具打包成 OpenCode 插件。
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
* Skill v5 随插件自动注入(config hook),无需手动安装 skill 文件
|
|
13
|
-
* G1 至 G6 页型契约,每种页型对应专属骨架模板(v4 新增 G6 操作手册/how-to)
|
|
14
|
-
* 双语孪生页面(en/zh)自动翻译,翻译引擎可配置
|
|
15
|
-
* 页面地图缓存、本地镜像、时间轴聚合视图与 `maintain` 维护策展报告(light/deep 两档)
|
|
16
|
-
* `options.sections` 路径前缀白名单强制生效:配置非空时越界写入硬拒(`ConfigError`,请求发出前拒绝);`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence` 系统路径恒豁免;默认 `[]` = 不限制
|
|
17
|
-
* `historian_search` 标签过滤:`tags` 1-5 个,`tagsMode` 默认 `all`(服务端 AND)、`any` 为客户端逐标签 fan-out 求并集
|
|
18
|
-
* 顶层 `home` 落地页解锁:仅豁免精确顶层 `home`,其余保留字(login/register/graphql/healthz/_assets/favicon)与嵌套 `home` 照旧拒绝
|
|
19
|
-
* 开工前置查阅回路(reading loop,默认关,双信号启用;v4 advisory:先查索引、update 优先、引页引日期、标注过期)+ `/historian-capture` 会话留痕(默认关)
|
|
20
|
-
* 试点与评测均通过:pilot 7 页迁移 PASS,eval 7/7 场景首跑全过
|
|
11
|
+
AI agent 装上它,就能直接管理双语知识库:写入的是结构化页面,回报的是双语链接。
|
|
21
12
|
|
|
22
|
-
##
|
|
13
|
+
## 为什么存在
|
|
23
14
|
|
|
24
|
-
|
|
15
|
+
这台机器由一个人加一群 AI agent 操作。会话一结束,细节就随滚动条消失;上下文一压缩,细节就丢了。
|
|
25
16
|
|
|
26
|
-
|
|
17
|
+
部署过什么、出过什么事故、踩过什么坑、做过什么决定——三个月后,人和 AI 都查无可查。
|
|
27
18
|
|
|
28
|
-
|
|
29
|
-
|---|---|
|
|
30
|
-
| 中文 | 序言不可侵犯(多数读者只读序言,要点前置);可供查证(举证责任在添加内容的一方);金字塔原理的结论先行;阮一峰式行文纪律(句 ≤40 字、一文一事);企业事件复盘模板(摘要→背景→时间线→影响量化→根因→改进,改进措施是复盘最重要的部分,行动项必须带负责人、期限与验证方式) |
|
|
31
|
-
| 英文 | WP:LEAD 导言自足、篇幅按重要性分配;Good Article 六项质量门;Diátaxis 四象限(tutorial / how-to / reference / explanation,模式混杂是文档烂的根源,参考页要像地图一样镜像系统结构);Google 技术写作"≥3 个相关字段就上表格";SRE blameless postmortem |
|
|
32
|
-
| 德文 | 条目开头先定义、门外汉可懂、一文一概念反碎片化、禁止"杂项"小节;引证义务 Belegpflicht:"宁要格式错的引注,不要没有引注";评价必须归属到人,不带情绪(sine ira et studio) |
|
|
33
|
-
| 法文 | 中立、非个人化、清晰、精确、易懂、有教学性六种品质;溢美词强制转成事实(用排名、奖项、销量替代"最伟大的"这类断言);耐久过滤:明天就会过时的内容不值得写 |
|
|
34
|
-
| 俄文 | ХС/ИС 条目门槛(导言普通读者可懂、术语最少、不少于 10 行);二手权威来源优先于一手(АИ);每种观点按影响力分配篇幅、禁止虚假平衡(ВЕС);风格要求精确、简明、无歧义,同时保持内容饱和 |
|
|
35
|
-
|
|
36
|
-
SRE postmortem 文化单独值得点名:它把"事件"当一等文档对待。先证据后结论的证据链四段式,正是 `/historian-capture` 命令的正文契约:证据链→方法→修复手段→函数级实现。模板见 `src/index.ts` 的 `CAPTURE_COMMAND_TEMPLATE`。"改进项要有负责人和可验证终态"落在了 G1 行动项表格里。
|
|
37
|
-
|
|
38
|
-
把这些文化做成插件的直接动因,是一个机构记忆问题:这台机器由一个人加一群 AI agent 操作。会话结束,终端滚动条就没了;上下文压缩,细节就丢了。部署过什么、发生过什么事故、踩过什么坑、做过什么决定,三个月后人和 AI 都无从查起。史官要解决的,就是让这台机器的历史变得可检索。
|
|
39
|
-
|
|
40
|
-
### 目的 / Purpose
|
|
41
|
-
|
|
42
|
-
让"这台机器上部署过什么、发生过什么、踩过什么坑、做过什么决定"成为一等知识。人和 AI 都能索引它、引用它、审计它:
|
|
43
|
-
|
|
44
|
-
* 知识落进结构化双语 wiki 页,而不是一次性的会话回复
|
|
45
|
-
* 每个写操作强制回报 en + zh 双 URL(`URL_MANDATE`,`src/tools/shared.ts:39`),引用链可回溯
|
|
46
|
-
* wiki 成为任何 agent 会话开工前先查的权威来源,而不是锁在某个会话里的私有记忆
|
|
47
|
-
|
|
48
|
-
### 作用 / What it does
|
|
49
|
-
|
|
50
|
-
六柱页型契约,加上读写两条自动化回路:
|
|
51
|
-
|
|
52
|
-
| 能力 | 机制 | 落点 |
|
|
53
|
-
|---|---|---|
|
|
54
|
-
| 六柱页型 | G1 事件复盘 / G2 对比选型 / G3 清单索引 / G4 概念原理 / G5 现状账本 / G6 操作手册,写前声明页型,套固定骨架、过来源列检查 | `src/templates/genres.ts`,skill Phase 1.5 |
|
|
55
|
-
| 三视图 | 地图视图(en/zh 对应关系,Locale/Twin 列)+ 时间轴视图(ISO 周分组,支持 `days` 窗口与 `path` 前缀过滤,人读周表 + 机读 weeks JSON)+ 维护策展报告(`action:'maintain'`:双语缺口、近似重复标题、过期、孤儿候选、标签词表、章节分布;light 档只扫地图行加每 locale 一次 `pages.list`,`deep:true` 逐页读正文补新鲜度标记与 Redirect 存根识别) | `historian_map` 的 `action:'show'` / `'timeline'` / `'maintain'` |
|
|
56
|
-
| 迁移与评分门禁 | 存量页按骨架重排:dry-run 评分在前,`apply=true` 自动 pre-image 备份;每页写入后过 10 项自检门 | `historian_migrate`,`selfReviewChecklist()` |
|
|
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
|
-
| 主动留痕 | `/historian-capture` 命令把当前会话总结成 G1 事件页;开启 `capture.enabled` 后额外在会话空闲时弹一次提醒,仅提醒,绝不自动写页 | `src/index.ts` 的 `config` / `event` 钩子 |
|
|
59
|
-
|
|
60
|
-
G5 现状卡回答"现在跑着什么",timeline 回答"最近两周变了什么"。比如问"`service-a` 现在监听哪个端口",答案应当是现状账本里的一行,带上次核实日期与验证命令(形如 `example.com:8000`)。它不该来自某次会话的聊天记录。这两样合起来,wiki 才从文档堆变成可查询的运维账本。
|
|
61
|
-
|
|
62
|
-
知识库要同时满足四种诉求——档案、手册、百科、知识库(速查)。六柱页型加索引层按层分工:
|
|
63
|
-
|
|
64
|
-
| 层诉求 | 回答的问题 | 对应页型 | 承载机制 |
|
|
65
|
-
|---|---|---|---|
|
|
66
|
-
| 档案 | 发生过什么、现在跑着什么 | G1 事件复盘 + G5 现状账本 | G1 时间线带来源列;G5 每行带「上次核实于」+ 验证命令 |
|
|
67
|
-
| 手册 | 怎么把一件事做完 | G6 操作手册 | 目标句式标题、步骤三段(动作+预期结果+失败处置)、上次核实+复核周期 |
|
|
68
|
-
| 百科 | 它是什么、为什么 | G4 概念原理 | 概念定义 → 图示 → 示例 |
|
|
69
|
-
| 知识库(速查) | 该选哪个、去哪查 | G2 对比选型 + G3 清单索引 | 对比表带来源列;可勾选检查项 |
|
|
70
|
-
| 索引层 | 从哪读起 | ——(不是页型) | `wiki-index` 人策展目录 + `historian_map` 的 show/timeline/maintain |
|
|
71
|
-
|
|
72
|
-
### 使用方式 / Usage
|
|
73
|
-
|
|
74
|
-
端到端最短路径(适配你自己 wiki 的六步完整指南见 `skills/historian/references/adapting-your-own-wiki.md`):
|
|
75
|
-
|
|
76
|
-
1. **安装**:`opencode.json[c]` 的 `plugin` 数组加 `"opencode-wiki-historian"`(npm 发布后)或 `"file:///home/<you>/workspace/opencode-historian"`(本地开发),细节见下文「安装」。
|
|
77
|
-
2. **配置**:最小三个选项;翻译腿可以不配,双语孪生会优雅降级为 pending:
|
|
78
|
-
|
|
79
|
-
```jsonc
|
|
80
|
-
["opencode-wiki-historian", {
|
|
81
|
-
"baseUrl": "http://<your-wiki>:3000",
|
|
82
|
-
"apiKeyPath": "~/.wiki-key",
|
|
83
|
-
"sections": ["team-notes/"]
|
|
84
|
-
}]
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
3. **口述写史**:对 opencode 说自然语言,史官完成分诊→放置→页型→骨架→自检→写入,并回报双语 URL:
|
|
88
|
-
|
|
89
|
-
> `service-a` 今天 OOM 重启,根因是缓存没设上限,已加告警,记下来。
|
|
90
|
-
|
|
91
|
-
→ 分诊为事件复盘,声明 G1 → `historian_page_create`(`genre: "G1"`)→ 回报 `http://<your-wiki>:3000/team-notes/<slug>` 与它的 `/zh/` 孪生页。
|
|
92
|
-
4. **检索与整理**:`historian_search` 按主题查,可按标签过滤(`tags` 1-5 个,`tagsMode` 默认 `all` 即服务端 AND,`any` 为客户端逐标签 fan-out 并集);`historian_map` 的 `show` 看双语地图、`timeline`(可选 `days` / `path`)看最近变动、`maintain`(可选 `deep:true`)出维护策展报告;存量页不合规用 `historian_migrate` 先 dry-run 再 apply。
|
|
93
|
-
5. **开关**:reading loop 默认 false,开启需配置+哨兵双确认,两步缺一不可:
|
|
94
|
-
|
|
95
|
-
1. 插件二元组第二参数写 `"readingLoop": true`:`["opencode-wiki-historian", { "readingLoop": true }]`
|
|
96
|
-
2. 人工写入本机哨兵文件(agent 不能自我启用):
|
|
19
|
+
史官只做一件事:让这台机器的历史变得可以查。
|
|
97
20
|
|
|
98
|
-
|
|
99
|
-
cat > ~/.config/opencode/historian-reading-loop.json <<'EOF'
|
|
100
|
-
{"version":1,"confirmed":true}
|
|
101
|
-
EOF
|
|
102
|
-
```
|
|
21
|
+
它的写作规则不是发明的,蒸馏自五种语言的 wiki 工程传统,加上 SRE 的复盘文化。
|
|
103
22
|
|
|
104
|
-
|
|
23
|
+
五种传统各取一句:
|
|
105
24
|
|
|
106
|
-
|
|
25
|
+
- 中文:结论先行,序言不可侵犯;行动项必须带负责人和验证方式。
|
|
26
|
+
- 英文:Diátaxis 四象限;参考页要像地图一样镜像系统结构。
|
|
27
|
+
- 德文:先定义再展开,一页一概念;宁要格式错的引注,不要没有引注。
|
|
28
|
+
- 法文:溢美词必须改成事实;明天就过时的内容不写。
|
|
29
|
+
- 俄文:导言要好读,术语要少;篇幅按影响力分配,禁止虚假平衡。
|
|
107
30
|
|
|
108
|
-
|
|
31
|
+
调研全文见 `docs/research/cross-cultural-wiki-writing-digest.md`,每条主张附原文引用。
|
|
109
32
|
|
|
110
|
-
|
|
111
|
-
* 翻译腿零内置地址:解析链只有 `translate.endpoint` 选项 → 环境变量 `HISTORIAN_TRANSLATE_ENDPOINT` → 未配置,未配置时孪生降级 pending,不发任何网络请求
|
|
112
|
-
* `tools/privacy-audit.mjs` 对 `npm pack` 清单里的每个随包文件跑隐私红线 regex。红线覆盖真实主机、本机路径、本机章节名、密钥形态、个人身份。任何命中即非零退出,拦住发布。它已接入 `prepublishOnly`(build → test → audit)
|
|
113
|
-
* 随包文本里的示例全部占位符化:`http://<your-wiki>:3000`、`team-notes/`、`example.com`
|
|
33
|
+
## 它能干什么
|
|
114
34
|
|
|
115
|
-
|
|
35
|
+
- 11 个 `historian_*` 工具:创建、更新、追加、阅读、搜索、删除、移动。
|
|
36
|
+
- 另有地图、时间线、维护报告、迁移、翻译片段、锚印封存。
|
|
37
|
+
- 页型契约:G1–G6 六种页型,各有固定骨架,见下方表格。
|
|
38
|
+
- 双语孪生:en 和 zh 页面自动翻译,翻译引擎由你配置。
|
|
39
|
+
- 每个写操作强制回报 en 与 zh 两个可访问 URL。
|
|
40
|
+
- 地图与时间线:双语缺口、迁移变化,一条命令可枚举。
|
|
41
|
+
- 维护报告:近似重复标题、过期页面、孤儿候选,一次扫清。
|
|
42
|
+
- 迁移门禁:存量页按骨架重排,先试评,后落笔。
|
|
43
|
+
- 口述留痕:`/historian-capture` 把当前会话总结成事件页。
|
|
116
44
|
|
|
117
|
-
|
|
118
|
-
Source repository is managed by the maintainer; the public distribution channel for this package is the npm registry (`opencode-wiki-historian`).
|
|
45
|
+
## 快速上手
|
|
119
46
|
|
|
120
|
-
|
|
47
|
+
三步开始:
|
|
121
48
|
|
|
122
|
-
|
|
49
|
+
1. 在 `opencode.jsonc` 的 `plugin` 数组里加上包名。
|
|
50
|
+
2. 配置 wiki 地址和 API key 文件路径。
|
|
51
|
+
3. 对 agent 说人话,例如:「service-a 今天 OOM 重启,根因是缓存没上限,记下来」。
|
|
123
52
|
|
|
124
|
-
|
|
53
|
+
史官会分诊、选页型、过自检、写入 wiki,然后回报两个 URL。
|
|
125
54
|
|
|
126
|
-
|
|
55
|
+
最小配置:
|
|
127
56
|
|
|
128
57
|
```jsonc
|
|
129
|
-
{
|
|
130
|
-
"
|
|
131
|
-
|
|
58
|
+
["opencode-wiki-historian", {
|
|
59
|
+
"baseUrl": "http://<your-wiki>:3000",
|
|
60
|
+
"apiKeyPath": "~/.wiki-key"
|
|
61
|
+
}]
|
|
132
62
|
```
|
|
133
63
|
|
|
134
|
-
|
|
64
|
+
翻译腿可以不配。不配时双语孪生降级为 pending,不发任何网络请求。
|
|
135
65
|
|
|
136
|
-
|
|
66
|
+
## 安装
|
|
137
67
|
|
|
138
|
-
|
|
68
|
+
两种装法,都经过实测。
|
|
139
69
|
|
|
140
|
-
|
|
70
|
+
**方式一:npm 包(推荐)。** 在 `opencode.json[c]` 的 `plugin` 数组添加:
|
|
141
71
|
|
|
142
72
|
```jsonc
|
|
143
|
-
{
|
|
144
|
-
"plugin": ["file:///home/<you>/workspace/opencode-historian"]
|
|
145
|
-
}
|
|
73
|
+
{ "plugin": ["opencode-wiki-historian"] }
|
|
146
74
|
```
|
|
147
75
|
|
|
148
|
-
|
|
76
|
+
注意 npm 包名是 `opencode-wiki-historian`,仓库名是 `opencode-historian`,两者不同。
|
|
149
77
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
插件注入的 skill 会注册 `/historian` 命令。验证方法:
|
|
153
|
-
|
|
154
|
-
```bash
|
|
155
|
-
opencode run --command historian --message "historian_map show"
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
如果工具列表中出现 `historian_page_create` 等 11 个工具,安装成功。
|
|
159
|
-
|
|
160
|
-
> **升级提示**:如果你之前使用过 historian v2 的扁平 skill 文件(如 `~/.config/opencode/skills/historian.md`),需要先重命名为 `historian.md.v2-disabled` 或移到别处。插件通过 config hook 自动注入 v5 skill,两个同名 skill 不能共存。
|
|
161
|
-
|
|
162
|
-
## 配置 / Configuration
|
|
163
|
-
|
|
164
|
-
插件支持元组形式传入选项:
|
|
78
|
+
**方式二:本地路径(开发用)。** 指向本地检出目录:
|
|
165
79
|
|
|
166
80
|
```jsonc
|
|
167
|
-
{
|
|
168
|
-
"plugin": [
|
|
169
|
-
["opencode-wiki-historian", {
|
|
170
|
-
"baseUrl": "http://your-wiki:3000",
|
|
171
|
-
"apiKeyPath": "~/.wiki-key",
|
|
172
|
-
"translate": {
|
|
173
|
-
"endpoint": "https://<your-anthropic-compatible-gateway>/v1",
|
|
174
|
-
"model": "<your-authorized-model>",
|
|
175
|
-
"apiKey": "<YOUR_KEY>",
|
|
176
|
-
"providerKey": "my-provider"
|
|
177
|
-
},
|
|
178
|
-
"sections": ["team-notes", "infra"],
|
|
179
|
-
"locales": ["en", "zh"]
|
|
180
|
-
}]
|
|
181
|
-
]
|
|
182
|
-
}
|
|
81
|
+
{ "plugin": ["file:///home/<you>/workspace/opencode-historian"] }
|
|
183
82
|
```
|
|
184
83
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
### 选项全表
|
|
188
|
-
|
|
189
|
-
| 字段 | 类型 | 默认值 | 说明 |
|
|
190
|
-
|---|---|---|---|
|
|
191
|
-
| `baseUrl` | string | `http://localhost:3000` | wiki.js GraphQL 端点 |
|
|
192
|
-
| `apiKeyPath` | string | `~/.wikijs-api-key` | wiki API key 文件路径(tilde 在读取时展开) |
|
|
193
|
-
| `translate.endpoint` | string | 未配置(见下方链) | 翻译 API 端点 |
|
|
194
|
-
| `translate.model` | string | 未配置(调用时响亮报错) | 翻译模型;包内不内置设备模型默认(L-MACHINE-LOCAL),可用 env `HISTORIAN_TRANSLATE_MODEL` 兜底腿 |
|
|
195
|
-
| `translate.apiKey` | string | 见下方链 | 翻译 API 密钥 |
|
|
196
|
-
| `translate.providerKey` | string | 未配置 | jsonc 兜底腿读取的 provider 名;须显式设置才会启用该腿 |
|
|
197
|
-
| `sections` | string[] | `[]`(不限制) | 写入路径前缀白名单。v4 起强制生效:非空时 create/update/append/delete/move(目标路径) 在发出请求前做 `sectionGuard` 检查,越界返回 `ConfigError`;`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence` 恒豁免;按首路径段匹配、区分大小写 |
|
|
198
|
-
| `locales` | string[] | `["en", "zh"]` | 启用的语言列表 |
|
|
199
|
-
| `readingLoop` | boolean | `false` | 开工前置查阅 advisory,向每次请求注入"先查 wiki"提示;默认 false,true 需配置+哨兵双确认(见「使用方式」开关步骤);单块合并追加到最后一个 system 块,绝不产生第二条 system 消息,vLLM 等拒绝多条 system 的严格后端同样安全 |
|
|
200
|
-
| `capture.enabled` | boolean | `false` | 开启后会话空闲时弹一次 `/historian-capture` 留痕提醒;仅提醒,不自动写页 |
|
|
84
|
+
改完即生效,适合调试。
|
|
201
85
|
|
|
202
|
-
|
|
86
|
+
**装完验证**:跑一条 `opencode run --command historian --message "historian_map show"`。工具列表出现 11 个 `historian_*`,即安装成功。
|
|
203
87
|
|
|
204
|
-
|
|
88
|
+
**从 v2 升级**:先把旧的扁平 skill 文件改名停用,否则两个同名 skill 会冲突。对照表见 [DEVELOPMENT.md](DEVELOPMENT.md)。
|
|
205
89
|
|
|
206
|
-
|
|
90
|
+
## 配置
|
|
207
91
|
|
|
208
|
-
|
|
92
|
+
完整示例:
|
|
209
93
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
key 缺失时 `ConfigError` 记录一次日志,插件工具全部禁用,opencode 正常启动不受影响。`translate.endpoint` 未配置时双语孪生功能降级为 pending 状态(`twinReason: 'translate.endpoint not configured — ...'`),创建页面只写入请求 locale 的内容,不会发起任何翻译网络请求。
|
|
224
|
-
|
|
225
|
-
### 已知限制
|
|
94
|
+
```jsonc
|
|
95
|
+
["opencode-wiki-historian", {
|
|
96
|
+
"baseUrl": "http://<your-wiki>:3000",
|
|
97
|
+
"apiKeyPath": "~/.wiki-key",
|
|
98
|
+
"translate": {
|
|
99
|
+
"endpoint": "https://<your-gateway>/v1",
|
|
100
|
+
"model": "<your-model>",
|
|
101
|
+
"apiKey": "<YOUR_KEY>"
|
|
102
|
+
},
|
|
103
|
+
"sections": ["team-notes/"],
|
|
104
|
+
"locales": ["en", "zh"]
|
|
105
|
+
}]
|
|
106
|
+
```
|
|
226
107
|
|
|
227
|
-
|
|
|
108
|
+
| 字段 | 默认 | 说明 |
|
|
228
109
|
|---|---|---|
|
|
229
|
-
|
|
|
230
|
-
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
110
|
+
| `baseUrl` | `http://localhost:3000` | wiki.js 地址 |
|
|
111
|
+
| `apiKeyPath` | `~/.wikijs-api-key` | wiki API key 文件 |
|
|
112
|
+
| `translate.endpoint` | 未配置 | 翻译 API 地址 |
|
|
113
|
+
| `translate.model` | 未配置 | 未配置时首次调用即报错 |
|
|
114
|
+
| `translate.apiKey` | 未配置 | 三种给法,见下 |
|
|
115
|
+
| `translate.providerKey` | 未配置 | 从 opencode 配置兜底读 key |
|
|
116
|
+
| `sections` | `[]`(不限制) | 可写路径前缀白名单 |
|
|
117
|
+
| `locales` | `["en","zh"]` | 启用的语言 |
|
|
118
|
+
| `readingLoop` | `false` | 开工前置「先查 wiki」提示 |
|
|
119
|
+
| `capture.enabled` | `false` | 空闲时提醒留痕,只提醒 |
|
|
237
120
|
|
|
238
|
-
|
|
239
|
-
* **Active Namespaces** 包含 `en` 和 `zh`
|
|
240
|
-
* zh 命名空间是语言切换器和 URL 路由的前提
|
|
121
|
+
翻译 key 三种给法,先到先用:配置字段、环境变量、opencode 的 provider 兜底。
|
|
241
122
|
|
|
242
|
-
|
|
123
|
+
`sections` 非空即强制生效:越界写入在发出请求前被拒,并点名越界的首段。
|
|
243
124
|
|
|
244
|
-
|
|
245
|
-
* 需要的 scope:`write:pages`、`delete:pages`、`manage:pages`、`manage:system`
|
|
246
|
-
* 将 token 写入 `apiKeyPath` 文件或设为 `WIKIJS_API_KEY` 环境变量
|
|
125
|
+
密钥链、降级细节与豁免路径清单,见 [DEVELOPMENT.md](DEVELOPMENT.md)。
|
|
247
126
|
|
|
248
|
-
|
|
127
|
+
**开工前置回路**(`readingLoop`)是双确认开关。配置打开,还要人工写一个哨兵文件:
|
|
249
128
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
* wiki.js 自动生成目录(TOC),通过 Admin > Theme 配置位置,页面内容里**不要**写 `{{toc}}`
|
|
256
|
-
* 自定义 CSS/HTML 注入入口在 Admin > Theme
|
|
257
|
-
* 建议关闭评论功能,避免知识库页面被评论干扰
|
|
258
|
-
|
|
259
|
-
## 中文页面在哪看 / Viewing Chinese Pages
|
|
260
|
-
|
|
261
|
-
中文页面的 URL 格式:
|
|
262
|
-
|
|
263
|
-
```
|
|
264
|
-
http://<host>/zh/<path>
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
例如 `ops/deploy-checklist` 的中文版在 `http://<host>/zh/ops/deploy-checklist`。英文版不带 locale 前缀:`http://<host>/ops/deploy-checklist`。
|
|
268
|
-
|
|
269
|
-
**语言切换器**出现在页面右上角的前提是 namespacing 已开启且 zh 在 Active Namespaces 里。看不到切换器时,检查 Admin > General > Multilingual 设置。
|
|
270
|
-
|
|
271
|
-
**工具返回值**:每个写入操作的结果都会同时回显 en 和 zh 的 URL,格式如:
|
|
272
|
-
|
|
273
|
-
```
|
|
274
|
-
en: http://<host>/ops/example
|
|
275
|
-
zh: http://<host>/zh/ops/example
|
|
129
|
+
```bash
|
|
130
|
+
cat > ~/.config/opencode/historian-reading-loop.json <<'EOF'
|
|
131
|
+
{"version":1,"confirmed":true}
|
|
132
|
+
EOF
|
|
276
133
|
```
|
|
277
134
|
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
**时间轴视图**:`historian_map action:'timeline'` 把镜像行按 ISO 周分组,可选 `days` 窗口与 `path` 前缀过滤。输出人读周表 + 机读 `weeks` JSON,回答"最近哪些页面变过"。
|
|
281
|
-
|
|
282
|
-
**维护视图**:`historian_map action:'maintain'` 输出策展报告——双语缺口、近似重复标题、过期页面、孤儿/扩散候选、标签词表、章节分布。默认 light 档只扫地图行加每个 locale 一次 `pages.list`;`deep:true` 逐页读正文,补新鲜度标记与 Redirect 存根识别。
|
|
135
|
+
两个信号缺一不可。配置已开而哨兵缺失时,加载期会打印提示,不会静默失灵。删除哨兵文件即刻回退。
|
|
283
136
|
|
|
284
|
-
##
|
|
137
|
+
## 前置要求(wiki.js 侧)
|
|
285
138
|
|
|
286
|
-
|
|
139
|
+
插件不替你执行任何管理端操作。安装前请确认:
|
|
287
140
|
|
|
288
|
-
|
|
141
|
+
- 多语言:启用 namespacing,Active Namespaces 包含 `en` 和 `zh`。
|
|
142
|
+
- API token:在 Admin > API Access 创建,覆盖页面的读、写、删除。
|
|
143
|
+
- token 内容写入 `apiKeyPath` 文件,或设为环境变量 `WIKIJS_API_KEY`。
|
|
144
|
+
- 组的页面规则要覆盖 `sections` 声明的路径前缀。
|
|
145
|
+
- 建议关闭评论功能,知识库页面不该被评论干扰。
|
|
289
146
|
|
|
290
|
-
|
|
291
|
-
|---|---|---|
|
|
292
|
-
| G1 事件复盘 | 故障、踩坑、事后分析 | 时间线 → 根因 → 影响 → 行动项 → 教训,附来源列 |
|
|
293
|
-
| G2 对比 | 技术选型、方案比较 | 来源声明 + 对比表格 + 结论 |
|
|
294
|
-
| G3 清单 | 操作步骤、检查项 | 可勾选的检查项列表 |
|
|
295
|
-
| G4 概念 | 架构说明、原理讲解 | 概念定义 → 图示 → 示例 |
|
|
296
|
-
| G5 现状账本 | 此刻的部署/运行态,回答"现在跑着什么" | 状态块 → 部署物清单(每行带「上次核实于」+ 验证命令)→ 失效策略,禁止叙事正文 |
|
|
297
|
-
| G6 操作手册 | how-to,回答"怎么把一件事做完",目标句式标题 | 前置条件 → 操作步骤(每步含预期结果+失败处置)→ 回退 → 元数据表(上次核实 + 复核周期)→ 相关页面 |
|
|
298
|
-
|
|
299
|
-
### 10 项自检门
|
|
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 项要求元数据表含「上次核实」与「复核周期」行:
|
|
147
|
+
## 中文页面在哪看
|
|
302
148
|
|
|
303
|
-
|
|
304
|
-
2. **句长上限**:中文句 ≤20 字、英文句 ≤25 词
|
|
305
|
-
3. **表格判据**:≥3 字段的结构化枚举入表,成对数据用描述列表
|
|
306
|
-
4. **对比表来源列**(G2):对比表/枚举表每行有来源列,行序固定、无合并单元格;G5 变体:部署物清单每行带「上次核实于」列
|
|
307
|
-
5. **时间线来源列**(G1):时间线每行有来源列,仅日志可证事实;G5 变体:验证方法含可执行复核命令
|
|
308
|
-
6. **行动项五要素**(G1):类型|负责人|期限|验证|状态 五列,措施是行内容;G5 变体:无叙事正文,只有状态块 + 表格
|
|
309
|
-
7. **无杂项筐**:除 参见/附录 之外没有 "其他/杂项" 类 catch-all 小节
|
|
310
|
-
8. **无溢美词**:领先/强大/灵活/高效 等 bare claim 改事实或删除
|
|
311
|
-
9. **双语 URL 已回报**(写后核销):报告含 /en/ 与 /zh/ 两个可访问 URL
|
|
312
|
-
10. **孪生已建或 zh_status:pending 声明**(写后核销):twin created OR zh_status pending recorded and declared in report
|
|
149
|
+
URL 规则:中文页在路径前加 `/zh/`,英文页不带前缀。
|
|
313
150
|
|
|
314
|
-
|
|
151
|
+
例如 `ops/deploy-checklist` 的中文版是 `/zh/ops/deploy-checklist`。
|
|
315
152
|
|
|
316
|
-
|
|
153
|
+
每个写操作的返回值自带 en 与 zh 两条 URL,直接点开即可。
|
|
317
154
|
|
|
318
|
-
|
|
155
|
+
看不到语言切换器时,检查 namespacing 与 zh 命名空间是否启用。
|
|
319
156
|
|
|
320
|
-
|
|
157
|
+
## 六种页型与索引层
|
|
321
158
|
|
|
322
|
-
|
|
|
159
|
+
| 页型 | 回答的问题 | 骨架一句话 |
|
|
323
160
|
|---|---|---|
|
|
324
|
-
|
|
|
325
|
-
|
|
|
326
|
-
|
|
|
161
|
+
| G1 事件复盘 | 发生过什么 | 时间线→根因→影响→行动项 |
|
|
162
|
+
| G2 对比选型 | 该选哪个 | 来源声明+对比表+结论 |
|
|
163
|
+
| G3 清单索引 | 从哪读起 | 可勾选的检查项 |
|
|
164
|
+
| G4 概念原理 | 它是什么、为何 | 定义→图示→示例 |
|
|
165
|
+
| G5 现状账本 | 现在跑着什么 | 每行带「上次核实于」 |
|
|
166
|
+
| G6 操作手册 | 怎么把事做完 | 每步:动作+预期+失败处置 |
|
|
327
167
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
```jsonc
|
|
331
|
-
// 大段原始材料先落证据页,再在人读页附录里给链接
|
|
332
|
-
historian_page_create({ path: "_evidence/<topic>--<yyyymmdd>", tier: "evidence", content: "<原始件全文>" })
|
|
333
|
-
```
|
|
168
|
+
索引层不算页型:`wiki-index` 是人策展的目录,配合地图与时间线视图。
|
|
334
169
|
|
|
335
|
-
|
|
336
|
-
- **镜像与快照页分工**:本地镜像 `~/.config/opencode/historian-map.json` 是活查询的唯一来源(`historian_map show` 直接读它);`_meta/page-map` wiki 页是审计账本,`historian_map refresh` 每次提交一个新修订,wiki 的页面历史即全库变更时间线。
|
|
170
|
+
每次写入后过 10 项自检门:句子要短、枚举进表格、时间线带来源列、双语 URL 必回报。
|
|
337
171
|
|
|
338
|
-
|
|
172
|
+
自检门全表与 20 条写作细则,见 [DEVELOPMENT.md](DEVELOPMENT.md)。
|
|
339
173
|
|
|
340
|
-
|
|
174
|
+
## 内容三层
|
|
341
175
|
|
|
342
|
-
|
|
|
176
|
+
| 层 | 位置 | 用途 |
|
|
343
177
|
|---|---|---|
|
|
344
|
-
|
|
|
345
|
-
|
|
|
346
|
-
|
|
|
347
|
-
| 定义列表 | `term\n: definition` | 术语表用 |
|
|
348
|
-
| 数学公式 | `$...$` 行内、`$$...$$` 块 | KaTeX 渲染,默认开启 |
|
|
349
|
-
| 流程图 | ` ```mermaid ` 代码块 | mermaid 渲染,默认开启 |
|
|
350
|
-
| 标签页 | `{tabset}` + `## Tab Name` | 多标签内容切换 |
|
|
351
|
-
|
|
352
|
-
**禁用项**:
|
|
353
|
-
|
|
354
|
-
* `{{toc}}`(目录由主题配置自动生成)
|
|
355
|
-
* `:::` 容器(wiki.js 不解析)
|
|
356
|
-
* YAML frontmatter(API 创建页面不经过 frontmatter 解析)
|
|
178
|
+
| 人读页 | 主题章节 | 提炼后的内容,双语孪生,进索引 |
|
|
179
|
+
| 后台 | `_meta/` 加本地镜像 | 机器记账,不进人读正文 |
|
|
180
|
+
| 证据页 | `_evidence/` | 日志、转写等原始件;匿名不可读 |
|
|
357
181
|
|
|
358
|
-
|
|
182
|
+
人读页贴入超长代码块时,工具会附一条「建议搬到证据页」的提醒。只提醒,不拦截。
|
|
359
183
|
|
|
360
|
-
|
|
184
|
+
## 已知限制
|
|
361
185
|
|
|
362
|
-
|
|
|
186
|
+
| 事实 | 定性 |
|
|
363
187
|
|---|---|
|
|
364
|
-
|
|
|
365
|
-
|
|
|
366
|
-
|
|
|
367
|
-
| 空 content 被拒绝 | 引擎 pre-check `ContentEmptyError`;不传 content 时走 template-only 模式,不发 GraphQL 写请求 |
|
|
368
|
-
| 移动页面不能用 update 改路径 | 用独立的 `pages.move` mutation |
|
|
369
|
-
| `singleByPath` 必须传 locale | 所有查询强制带 locale 参数 |
|
|
370
|
-
| 上传附件字段名必须是 `mediaUpload` | 内部固定字段名(`src/wiki/assets.ts`) |
|
|
371
|
-
| `isPublished: false` 的页面匿名访问报 404/403 | 创建草稿时在工具输出中标注 |
|
|
372
|
-
| 路径不能以 locale 前缀开头 | `validatePath` 拒绝 `zh/...` 形式的输入 |
|
|
373
|
-
|
|
374
|
-
## 从 historian v2 迁移 / Migrating from v2
|
|
375
|
-
|
|
376
|
-
旧版 historian v2 依赖 `/opt/wiki-ops/` 下的 Python 脚本(`wiki-ops.py`、`wiki-biling.py`)。插件完全替代了这些脚本。旧脚本保留在原位不动(标记 LEGACY),不需要删除。
|
|
377
|
-
|
|
378
|
-
### 命令映射表
|
|
379
|
-
|
|
380
|
-
| wiki-ops.py 子命令 | historian 工具 | 备注 |
|
|
381
|
-
|---|---|---|
|
|
382
|
-
| `list` | `historian_map` (show) | 地图缓存替代全量列表 |
|
|
383
|
-
| `read <id>` | `historian_read` (path) | 改用 path 定位,不再用数字 ID |
|
|
384
|
-
| `append <id> <file>` | `historian_page_append` | 直接传 section 内容,不用写临时文件 |
|
|
385
|
-
| `create "Title" "path" <file>` | `historian_page_create` | content 参数直接传,可省文件 |
|
|
386
|
-
| `rebuild-tree` | `historian_map` (refresh) | 从 wiki 重建地图缓存 |
|
|
387
|
-
| `search "keyword"` | `historian_search` (kind=title) | 标题搜索 |
|
|
388
|
-
| `search-content "keyword"` | `historian_search` (kind=content) | 全文搜索 |
|
|
389
|
-
| `fetch <id>` / `fetch-paths <path>` | `historian_read` | 按 path + locale 读取 |
|
|
390
|
-
| `cache-read` | `historian_map` (show) | 本地镜像 |
|
|
391
|
-
| `cache-refresh` | `historian_map` (refresh) | 重建缓存 |
|
|
392
|
-
| `delete <id> --confirm` | `historian_delete` | confirm 参数必须为 `"yes"` |
|
|
393
|
-
|
|
394
|
-
| wiki-biling.py 子命令 | historian 工具 | 备注 |
|
|
395
|
-
|---|---|---|
|
|
396
|
-
| `create-bilingual` | `historian_page_create` (twin=true) | twin 默认开启 |
|
|
397
|
-
| `append-bilingual` | `historian_page_append` + sectionZh | sectionZh 参数携带中文内容 |
|
|
398
|
-
| `translate-snippet` | `historian_translate_snippet` | 纯本地翻译,不写 wiki |
|
|
399
|
-
| `status` | `historian_map` (show) | 双语状态在地图中展示 |
|
|
400
|
-
| `checkpoint` | migrate store 文件 | 迁移进度持久化 |
|
|
401
|
-
| `run` / `run --path` | `historian_migrate` (apply=true) | 支持 dry-run(apply=false) |
|
|
402
|
-
|
|
403
|
-
### 升级步骤
|
|
188
|
+
| 翻译 key 全缺时,翻译相关工具整体禁用 | 按设计;补齐配置即恢复;部分降级在议 |
|
|
189
|
+
| 自进化驱动默认关,作者本机也尚未点亮 | 状态如实;代码与测试就绪,但文档不假装它在跑 |
|
|
190
|
+
| npm 包名与仓库名不同 | `opencode-historian` 已被无关同名包占用 |
|
|
404
191
|
|
|
405
|
-
|
|
406
|
-
2. 在 `opencode.json[c]` 的 `plugin` 数组中添加 `opencode-wiki-historian`
|
|
407
|
-
3. 重启 opencode,`/historian` 命令可用即表示 v5 skill 已注入
|
|
192
|
+
## 与任何机器解耦
|
|
408
193
|
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
1. **先 dry-run**:`apply=false`(默认),查看骨架预览和自检评分
|
|
416
|
-
2. **再 apply**:`apply=true`,引擎在首次写入前自动生成 pre-image 备份
|
|
417
|
-
3. **回滚**:读备份 JSON,用 `historian_page_update` 推回原始内容
|
|
418
|
-
|
|
419
|
-
备份文件写在运行侧的 `results/pilot-backup-*.json`(该目录为迁移执行记录,不随包分发,外部读者仓库里看不到属预期)。迁移进度存储在 `~/.config/opencode/historian-migrate.json`,支持断点续跑。
|
|
420
|
-
|
|
421
|
-
### 评测框架
|
|
422
|
-
|
|
423
|
-
评测框架是维护方的私有 harness 仓库,与插件仓库同工作区,不对外公开。它提供 7 个行为验收场景:创建、追加、重叠整合、整理、价值门控、G1 格式、zh URL 报告。v3 插件最近一轮内部评测:7/7 PASS、51/58 适用分、G=1、零重试。此行为维护记录声明,外部读者无法在本仓库复算,请以此为界。(`results/2026-09-02-v3-plugin.md`)。
|
|
424
|
-
|
|
425
|
-
## 开发 / Development
|
|
426
|
-
|
|
427
|
-
```bash
|
|
428
|
-
npm run build # tsc 编译到 dist/
|
|
429
|
-
npm test # vitest run(593 tests, 26 files;其中 4 条依赖本机 tools/redlines.local.json,缺该文件时自动跳过,fresh clone 为 589 跑 + 4 跳过)
|
|
430
|
-
npm pack --dry-run # 检查打包文件列表
|
|
431
|
-
```
|
|
194
|
+
- 包内不携带真实主机、真实章节分类或页面数据。
|
|
195
|
+
- `sections` 默认不限制;实际写权限由你 wiki token 的页面规则决定。
|
|
196
|
+
- 翻译地址零内置:不配置就降级 pending,绝不发网络请求。
|
|
197
|
+
- 发布前每个随包文件过隐私红线扫描,命中即拦下发布。
|
|
198
|
+
- 示例全部占位符化:`http://<your-wiki>:3000`、`team-notes/`。
|
|
432
199
|
|
|
433
|
-
|
|
200
|
+
## 源码与许可证
|
|
434
201
|
|
|
435
|
-
|
|
202
|
+
公开分发渠道是 npm(包名 `opencode-wiki-historian`)。许可证 MIT。
|
|
436
203
|
|
|
437
|
-
|
|
204
|
+
开发、内部机制、发布流程、v2 迁移对照:全部在 [DEVELOPMENT.md](DEVELOPMENT.md)。
|
package/dist/anchor.js
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Anchor sealing core (
|
|
3
|
-
*
|
|
2
|
+
* Anchor sealing core (merged into the historian 2026-10-01): a human
|
|
3
|
+
* order/approval message living in the engine's own
|
|
4
4
|
* session store is located by (session, ordinal) or by unique exact body match,
|
|
5
5
|
* hashed two ways (raw + canonical), and the receipt is written as an
|
|
6
6
|
* _evidence/anchors page. `verify` re-reads the store and re-computes: MATCH /
|
|
7
7
|
* MISMATCH / ABSENT — never a silent repair.
|
|
8
8
|
*
|
|
9
|
-
* The canonical-text rule is a CLOSED list (
|
|
10
|
-
*
|
|
9
|
+
* The canonical-text rule is a CLOSED list (fixed normalization discipline):
|
|
10
|
+
* trailing <dcp-message-id ...>...</dcp-message-id>
|
|
11
11
|
* block and surrounding whitespace. Anything else — including the engine
|
|
12
12
|
* merging several user turns into one message while the agent is busy — is
|
|
13
13
|
* NOT normalized away: a seal is only as atomic as the store row it names, and
|
package/dist/config.d.ts
CHANGED
|
@@ -78,7 +78,7 @@ export declare const DEFAULT_BASE_URL = "http://localhost:3000";
|
|
|
78
78
|
export declare const DEFAULT_API_KEY_PATH = "~/.wikijs-api-key";
|
|
79
79
|
/** Env leg of the endpoint chain: raw option → this env var → unset (''). */
|
|
80
80
|
export declare const ENV_TRANSLATE_ENDPOINT = "HISTORIAN_TRANSLATE_ENDPOINT";
|
|
81
|
-
/**
|
|
81
|
+
/** Package-portability rule (decided 2026-10-01, re-confirmed 2026-10-02): the portable
|
|
82
82
|
* package must NOT pin the operator's model choice. Resolution is
|
|
83
83
|
* explicit-option -> env leg -> unset (''), and an unset model fails loudly
|
|
84
84
|
* at first translate call (see translate.ts), never silently defaults. */
|
|
@@ -87,9 +87,9 @@ export declare const ENV_TRANSLATE_MODEL = "HISTORIAN_TRANSLATE_MODEL";
|
|
|
87
87
|
export declare const DEFAULT_SECTIONS: readonly string[];
|
|
88
88
|
export declare const DEFAULT_LOCALES: readonly ["en", "zh"];
|
|
89
89
|
/** Reading loop is opt-in: activated only when configured true AND the local
|
|
90
|
-
* sentinel confirms it (
|
|
90
|
+
* sentinel confirms it (see src/loop-state.ts). */
|
|
91
91
|
export declare const DEFAULT_READING_LOOP = false;
|
|
92
|
-
/** Capture reminders are opt-in
|
|
92
|
+
/** Capture reminders are opt-in. */
|
|
93
93
|
export declare const DEFAULT_CAPTURE_ENABLED = false;
|
|
94
94
|
/**
|
|
95
95
|
* Resolve raw plugin options against defaults, env vars and the machine's
|
|
@@ -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
|