opencode-wiki-historian 0.2.0

package/dist/wiki/pages.write.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Page WRITE operations: create (with optional twin), update (full
+ * read-modify-write), append, move, delete.
+ *
+ * Split from pages.ts (read ops + shared types live in pages.read.ts) to keep
+ * every source file under the 250-LOC ceiling. Field names are LIVE-
+ * INTROSPECTED on the running wiki.js instance, never guessed. Pitfalls this
+ * module encodes:
+ *
+ *   #1 update() wipes any field the payload omits → every mutable field is
+ *      echoed from the read and merged with the patch
+ *   #2 tags is required on update → always present in the payload
+ *   #4 create() rejects empty content → pre-checked client-side
+ *   #5 path moves go through move(id, destinationPath, destinationLocale),
+ *      never update(path:)
+ *   #8 create()'s response id is unreliable → authoritative id always comes
+ *      from a follow-up readPage lookup
+ *   live mutation fields are scriptCss/scriptJs (not styleCss/styleJs)
+ *   live mutation RESPONSES crash on page.locale ('Cannot return null for
+ *   non-nullable field Page.locale.' — wiki.js 2.5.314) while the side effect
+ *   still commits; the selection is therefore page { id path } and the
+ *   authoritative full state always comes from a readPage lookup
+ */
+import { type GqlClient } from './client.js';
+import { type LocalePair } from './locale.js';
+import type { HistorianOptions } from '../config.js';
+import { type Locale, type TranslateFn, type PageRecord } from './pages.read.js';
+export interface PageDeps {
+    readonly client: GqlClient;
+    readonly options: HistorianOptions;
+    readonly translate?: TranslateFn;
+}
+export interface CreateInput {
+    readonly path: string;
+    readonly locale: Locale;
+    readonly title: string;
+    readonly content: string;
+    readonly tags?: readonly string[];
+    readonly isPublished?: boolean;
+    readonly isPrivate?: boolean;
+    readonly twin?: boolean;
+    readonly description?: string;
+}
+export interface CreateResult extends LocalePair {
+    readonly pageId: number;
+    readonly twinStatus: 'created' | 'pending' | 'skipped';
+    readonly twinReason?: string;
+    readonly twinId?: number;
+}
+export interface UpdatePatch {
+    readonly title?: string;
+    readonly content?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly isPublished?: boolean;
+    readonly isPrivate?: boolean;
+    readonly publishStartDate?: string;
+    readonly publishEndDate?: string;
+    readonly scriptCss?: string;
+    readonly scriptJs?: string;
+}
+export interface UpdateResult extends LocalePair {
+    readonly pageId: number;
+    readonly page: PageRecord;
+}
+export interface WriteResult extends LocalePair {
+    readonly pageId: number;
+}
+export declare class ContentEmptyError extends Error {
+    constructor(message: string);
+}
+export declare class ConfirmRequiredError extends Error {
+    constructor(message: string);
+}
+export declare class PageNotFoundError extends Error {
+    constructor(message: string);
+}
+interface MutableState {
+    readonly id: number;
+    readonly path: string;
+    readonly locale: Locale;
+    readonly title: string;
+    readonly description: string;
+    readonly content: string;
+    readonly isPublished: boolean;
+    readonly isPrivate: boolean;
+    readonly tags: readonly string[];
+    readonly publishStartDate: string;
+    readonly publishEndDate: string;
+    readonly scriptCss: string;
+    readonly scriptJs: string;
+    readonly editor: string;
+}
+/** Full mutable state of one page (single(id)) — exported for the migrate
+ *  engine (todo 14), whose pre-image backup must capture publishStartDate/
+ *  publishEndDate alongside the readPage fields (the pilot restore replays
+ *  the backup through updatePage; RMW needs the write-side field contract). */
+export type { MutableState };
+/** Read the full mutable state of one page by id (threshold for the
+ *  read-modify-write in updatePage; also the migrate engine's pre-image
+ *  source — see {@link MutableState}). */
+export declare function readPageState(client: GqlClient, id: number): Promise<MutableState>;
+export declare function createPage(deps: PageDeps, input: CreateInput): Promise<CreateResult>;
+/** Full read-modify-write: the mutation payload ALWAYS carries every mutable
+ *  field from the read, merged with the patch (pitfalls #1 + #2). */
+export declare function updatePage(deps: PageDeps, id: number, patch: UpdatePatch): Promise<UpdateResult>;
+export declare function appendSection(deps: PageDeps, path: string, locale: Locale, section: string): Promise<UpdateResult>;
+export declare function movePage(deps: PageDeps, path: string, locale: Locale, newPath: string, newLocale?: Locale, confirm?: string): Promise<WriteResult>;
+export declare function deletePage(deps: PageDeps, path: string, locale: Locale, confirm?: string): Promise<WriteResult>;

package/dist/wiki/pages.write.js

@@ -0,0 +1,201 @@
+/**
+ * Page WRITE operations: create (with optional twin), update (full
+ * read-modify-write), append, move, delete.
+ *
+ * Split from pages.ts (read ops + shared types live in pages.read.ts) to keep
+ * every source file under the 250-LOC ceiling. Field names are LIVE-
+ * INTROSPECTED on the running wiki.js instance, never guessed. Pitfalls this
+ * module encodes:
+ *
+ *   #1 update() wipes any field the payload omits → every mutable field is
+ *      echoed from the read and merged with the patch
+ *   #2 tags is required on update → always present in the payload
+ *   #4 create() rejects empty content → pre-checked client-side
+ *   #5 path moves go through move(id, destinationPath, destinationLocale),
+ *      never update(path:)
+ *   #8 create()'s response id is unreliable → authoritative id always comes
+ *      from a follow-up readPage lookup
+ *   live mutation fields are scriptCss/scriptJs (not styleCss/styleJs)
+ *   live mutation RESPONSES crash on page.locale ('Cannot return null for
+ *   non-nullable field Page.locale.' — wiki.js 2.5.314) while the side effect
+ *   still commits; the selection is therefore page { id path } and the
+ *   authoritative full state always comes from a readPage lookup
+ */
+import { gql, GraphQLError } from './client.js';
+import { assertLocalePair, normalizeLocale, validatePath } from './locale.js';
+import { str, num, bool, mapTags, readPage } from './pages.read.js';
+// --- Errors -----------------------------------------------------------------
+export class ContentEmptyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ContentEmptyError';
+    }
+}
+export class ConfirmRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfirmRequiredError';
+    }
+}
+export class PageNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PageNotFoundError';
+    }
+}
+// --- GraphQL shapes (introspection-verified) --------------------------------
+const MUTABLE_FIELDS = 'id path locale title description content isPublished isPrivate tags { tag } publishStartDate publishEndDate scriptCss scriptJs editor createdAt updatedAt';
+const SINGLE_QUERY = `query s($id: Int!) { pages { single(id: $id) { ${MUTABLE_FIELDS} } } }`;
+const CREATE_MUTATION = `mutation c($path: String!, $locale: String!, $title: String!, $content: String!, $description: String!, $editor: String!, $isPublished: Boolean!, $isPrivate: Boolean!, $tags: [String!]!) { pages { create(path: $path, locale: $locale, title: $title, content: $content, description: $description, editor: $editor, isPublished: $isPublished, isPrivate: $isPrivate, tags: $tags) { responseResult { succeeded errorCode slug message } page { id path } } } }`;
+const UPDATE_MUTATION = `mutation u($id: Int!, $path: String!, $locale: String!, $title: String!, $content: String!, $description: String!, $editor: String!, $isPublished: Boolean!, $isPrivate: Boolean!, $tags: [String]!, $publishStartDate: Date, $publishEndDate: Date, $scriptCss: String, $scriptJs: String) { pages { update(id: $id, path: $path, locale: $locale, title: $title, content: $content, description: $description, editor: $editor, isPublished: $isPublished, isPrivate: $isPrivate, tags: $tags, publishStartDate: $publishStartDate, publishEndDate: $publishEndDate, scriptCss: $scriptCss, scriptJs: $scriptJs) { responseResult { succeeded errorCode slug message } page { id path } } } }`;
+const MOVE_MUTATION = `mutation m($id: Int!, $destinationPath: String!, $destinationLocale: String!) { pages { move(id: $id, destinationPath: $destinationPath, destinationLocale: $destinationLocale) { responseResult { succeeded errorCode slug message } } } }`;
+const DELETE_MUTATION = `mutation d($id: Int!) { pages { delete(id: $id) { responseResult { succeeded errorCode slug message } } } }`;
+function mapState(raw) {
+    return {
+        id: num(raw.id),
+        path: str(raw.path),
+        locale: normalizeLocale(str(raw.locale)),
+        title: str(raw.title),
+        description: str(raw.description),
+        content: str(raw.content),
+        isPublished: bool(raw.isPublished),
+        isPrivate: bool(raw.isPrivate),
+        tags: mapTags(raw.tags),
+        publishStartDate: str(raw.publishStartDate),
+        publishEndDate: str(raw.publishEndDate),
+        scriptCss: str(raw.scriptCss),
+        scriptJs: str(raw.scriptJs),
+        editor: str(raw.editor),
+    };
+}
+/** Read the full mutable state of one page by id (threshold for the
+ *  read-modify-write in updatePage; also the migrate engine's pre-image
+ *  source — see {@link MutableState}). */
+export async function readPageState(client, id) {
+    try {
+        const data = await gql(client, SINGLE_QUERY, { id });
+        if (data.pages.single === null)
+            throw new PageNotFoundError(`page ${id} does not exist`);
+        return mapState(data.pages.single);
+    }
+    catch (err) {
+        if (err instanceof GraphQLError && err.message.includes('does not exist')) {
+            throw new PageNotFoundError(`page ${id} does not exist`);
+        }
+        throw err;
+    }
+}
+// --- createPage --------------------------------------------------------------
+export async function createPage(deps, input) {
+    validatePath(input.path);
+    if (input.content.trim() === '') {
+        throw new ContentEmptyError(`content is empty after trimming (wiki.js rejects empty content)`);
+    }
+    const locale = normalizeLocale(input.locale);
+    const pair = assertLocalePair(input.path, locale, deps.options.baseUrl);
+    const base = {
+        path: input.path,
+        locale,
+        title: input.title,
+        content: input.content,
+        description: input.description ?? '',
+        editor: 'markdown',
+        isPublished: input.isPublished ?? true,
+        isPrivate: input.isPrivate ?? false,
+        tags: [...(input.tags ?? [])],
+    };
+    await gql(deps.client, CREATE_MUTATION, base);
+    // pitfall #8: create()'s response page.id is unreliable — the authoritative
+    // id comes from a fresh lookup of (path, locale).
+    const page = await readPage(deps.client, input.path, locale);
+    if (page === null) {
+        throw new Error(`create reported success but the lookup of '${input.path}' (${locale}) returned nothing`);
+    }
+    if (input.twin === false)
+        return { ...pair, pageId: page.id, twinStatus: 'skipped' };
+    if (deps.translate === undefined) {
+        return { ...pair, pageId: page.id, twinStatus: 'pending', twinReason: 'translator-not-wired' };
+    }
+    try {
+        const twinLocale = pair.twinLocale;
+        const [twinTitle, twinContent] = await Promise.all([
+            deps.translate(input.title, locale, twinLocale),
+            deps.translate(input.content, locale, twinLocale),
+        ]);
+        await gql(deps.client, CREATE_MUTATION, { ...base, locale: twinLocale, title: twinTitle, content: twinContent });
+        const twin = await readPage(deps.client, input.path, twinLocale);
+        if (twin === null)
+            throw new Error('twin create reported success but its lookup returned nothing');
+        return { ...pair, pageId: page.id, twinStatus: 'created', twinId: twin.id };
+    }
+    catch (err) {
+        // Twin-failure contract: a failing translator or twin write NEVER fails
+        // the primary result — the twin degrades to 'pending' with a reason.
+        return {
+            ...pair,
+            pageId: page.id,
+            twinStatus: 'pending',
+            twinReason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+// --- updatePage --------------------------------------------------------------
+/** Full read-modify-write: the mutation payload ALWAYS carries every mutable
+ *  field from the read, merged with the patch (pitfalls #1 + #2). */
+export async function updatePage(deps, id, patch) {
+    const current = await readPageState(deps.client, id);
+    const vars = {
+        id,
+        path: current.path,
+        locale: current.locale,
+        title: patch.title ?? current.title,
+        content: patch.content ?? current.content,
+        description: patch.description ?? current.description,
+        editor: current.editor,
+        isPublished: patch.isPublished ?? current.isPublished,
+        isPrivate: patch.isPrivate ?? current.isPrivate,
+        publishStartDate: patch.publishStartDate ?? current.publishStartDate,
+        publishEndDate: patch.publishEndDate ?? current.publishEndDate,
+        scriptCss: patch.scriptCss ?? current.scriptCss,
+        scriptJs: patch.scriptJs ?? current.scriptJs,
+        tags: [...(patch.tags ?? current.tags)],
+    };
+    await gql(deps.client, UPDATE_MUTATION, vars);
+    const page = await readPage(deps.client, current.path, current.locale);
+    if (page === null) {
+        throw new Error(`update succeeded but the re-read of '${current.path}' (${current.locale}) returned nothing`);
+    }
+    return { ...assertLocalePair(current.path, current.locale, deps.options.baseUrl), pageId: id, page };
+}
+// --- appendSection -----------------------------------------------------------
+export async function appendSection(deps, path, locale, section) {
+    const page = await readPage(deps.client, path, locale);
+    if (page === null)
+        throw new PageNotFoundError(`page '${path}' (${locale}) does not exist`);
+    return updatePage(deps, page.id, { content: `${page.content}\n\n${section}` });
+}
+// --- movePage / deletePage ----------------------------------------------------
+export async function movePage(deps, path, locale, newPath, newLocale, confirm) {
+    if (confirm !== 'yes') {
+        throw new ConfirmRequiredError(`movePage requires confirm:'yes' (got ${JSON.stringify(confirm)})`);
+    }
+    validatePath(newPath);
+    const destLocale = newLocale ?? locale;
+    const page = await readPage(deps.client, path, locale);
+    if (page === null)
+        throw new PageNotFoundError(`page '${path}' (${locale}) does not exist`);
+    // pitfall #5: a path change is the move operation — update(path:) would
+    // bypass destination-permission checks or silently misbehave.
+    await gql(deps.client, MOVE_MUTATION, { id: page.id, destinationPath: newPath, destinationLocale: destLocale });
+    return { ...assertLocalePair(newPath, destLocale, deps.options.baseUrl), pageId: page.id };
+}
+export async function deletePage(deps, path, locale, confirm) {
+    if (confirm !== 'yes') {
+        throw new ConfirmRequiredError(`deletePage requires confirm:'yes' (got ${JSON.stringify(confirm)})`);
+    }
+    const page = await readPage(deps.client, path, locale);
+    if (page === null)
+        throw new PageNotFoundError(`page '${path}' (${locale}) does not exist`);
+    await gql(deps.client, DELETE_MUTATION, { id: page.id });
+    return { ...assertLocalePair(path, locale, deps.options.baseUrl), pageId: page.id };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "opencode-wiki-historian",
+  "version": "0.2.0",
+  "description": "opencode plugin that manages a wiki.js knowledge base with bilingual pages, genre templates, and migration tooling.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4",
+    "zod": "^3.23.8"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npx vitest run && node tools/privacy-audit.mjs"
+  }
+}

package/skills/historian/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: historian
+description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）、G1-G5 页型骨架、V4 机构记忆层（reading loop 自动注入 + /historian-capture 主动留痕）、可发布 OpenCode 插件。Phase 1.5 页型分类确保每页匹配正确的知识形态。操作 10 个 historian_* 工具完成搜索、阅读、创建、更新、追加、翻译、迁移、移动、删除与页面地图/时间线管理。"
+---
+
+# 史官 (Historian) — 行为契约 V4 机构记忆层
+
+你是史官：本地 Wiki.js 知识库的策展人。不是文字搬运工，而是决定**什么值得成页、放在哪里、如何组织、链接给谁**的编辑。每次变更必须让 wiki 更有序。
+
+## 核心原则
+
+1. **策展，不转储**。wiki 是知识库，不是剪贴板。原始日志和未修约的数字是原材料，你的工作是提取持久知识并结构化。
+2. **整合，不堆叠**。默认动作是把新知识编织进已有页面的正确位置，而不是往底部追加或创建近似重复页。
+3. **一页一问**。回答了两个问题就拆；两个页面答同一个就合并或 supersede。
+4. **每页可达**。无入链的页面是孤儿债。创建的每个页面在同一次运行中拿到反向链接。
+5. **索引是每次变更的一部分**。让 wiki-index 过期的变更是未完成的变更。
+
+---
+
+## Phase 0: 分诊 (Triage)
+
+每次请求先分类，**声明分诊结果再动 wiki**：
+
+```
+分诊 (Triage): <知识类型> → <目标章节> → <create | integrate-into <path> | index-only | decline> — <一行理由>
+```
+
+### 知识类型
+
+| 类型 | 信号 | 归处 |
+|------|------|------|
+| 持久发现/配置 | "记录这个"、基准结论、调参、架构决策 | 对应主题章节 |
+| 事件复盘 | 症状→根因→修复→预防 | `incidents/` |
+| 服务操作手册 | 启停、健康检查、配置、回滚 | `ops/` |
+| 参考/清单 | 长期有效的列表（模型、端口、硬件） | 根概览页或章节索引 |
+| 会话草稿 | 当前会话的临时笔记 | `scratch/`（日后有价值再提升） |
+| 仅检索 | "查一下 wiki 里有没有 X" | 只读，无变更，无 cache-refresh |
+| 当前状态/部署台账 | "现在部署了什么"、端口/版本/端点、"上次核实于" | G5 现状卡页（配 `historian_map action=timeline` 追漂移） |
+
+### 章节分类学
+
+顶级章节**按机器配置**，插件不内置任何特定部署的章节表：可写前缀白名单由插件选项 `sections` 传入（默认为空 = 不限制前缀；实际权限由 wiki.js token 的 page rules 决定）。当前实例的章节布局以 `historian_map show` 输出或用户说明为准，不要臆断。
+
+假想实例的占位示例（仅示意，非真实章节表）：
+
+| 章节 | 用途 |
+|------|------|
+| 根页面 | 概览类页面（如 `wiki-index`） |
+| `ops/` | 服务运维：启停、健康、配置、回滚 |
+| `infra/` | 基础设施：部署、网络、环境配置 |
+| `team-notes/` | 团队约定、决策记录 |
+| `scratch/` | 临时会话笔记；持久发现日后提升 |
+| `_sandbox/` | 评测/测试区。仅当 brief 显式说"eval sandbox"时使用。沙箱页默认 `isPublished: false`（fixture 惯例）；当 brief 要求匿名可访问（如"两版 URL 都能开"）时跟随 brief 用默认 `true`。 |
+
+`_sandbox/` 规则以字面路径前缀 `_sandbox/` 为准，与 `sections` 配置无关。
+
+### 值不值得写 — 入门门控
+
+以下材料**拒绝写入 wiki**（附一行解释给用户），或提供 `scratch/` 便签替代：
+
+- **无教训的临时操作** — "重启了容器就好了，不知道为什么"没有可复用知识。故障复盘页至少需要根因或可复现的修复。
+- **秘密** — 凭证、token、私钥绝不入 wiki。
+- **原始转储** — 聊天记录和 shell 输出是原材料，不是页面内容。先提取。
+- **重复** — 已有页面覆盖的知识 → 整合到那里，不要创建新页。
+- **琐碎临时** — 今天的时间戳状态，明天就过时。
+
+拒绝是有效的、有价值的结果。说："这不构成可沉淀的知识，因为…；如需留痕我可以写入 scratch/ 便签。"
+
+### Slug 规则
+
+- `lowercase-hyphen`，按主题命名，不按人/日期。仅活动/事件页用日期（`prefill-optimization-campaign-2026-07-08`）。
+- 模式：`{section}/{topic-slug}`。最深 2 级。不在根层级（除非是服务级概览）。
+- Slug 比内容版本活得久，不在 slug 里编码版本号。
+
+---
+
+## Phase 1: 放置 (Placement)
+
+### Step 1 — 加载地图
+
+```
+historian_map action=show
+```
+
+扫描地图找同主题或相邻页面。不要在变更后再次调用（Phase 4 统一 refresh）。"最近改了什么"类问题直接用 `historian_map action=timeline`（可加 `days` / `path`），不必翻全表。
+
+### Step 2 — 内容级查重
+
+```
+historian_search query="<核心主题关键词>" kind=content
+```
+
+标题/路径匹配不够，同一知识常藏在更广的页面内。
+
+### Step 3 — 孪生检查
+
+读目标路径时检查孪生状态。如果 en 页存在但 zh 缺失，优先补全孪生而非创建新页。
+
+### Step 4 — 决策
+
+| 情况 | 决策 |
+|------|------|
+| 已有页面覆盖此主题 | **整合**：读取 → 把新材料编织进正确节 → `historian_page_update`（全量替换）。绝不底部追加参考内容。 |
+| 有页面重叠但范围不同 | 整合属于那里的 + 双向交叉链接；或提议合并/supersede（见 Supersede 协议）。 |
+| 无归处；匹配已有章节 | **创建**在该章节。 |
+| 无归处；无章节匹配 | **问用户**再发明新顶级章节。提供 2-3 个放置选项。 |
+| 材料质量仅草稿级 | `scratch/` 笔记，或按入门门控拒绝。 |
+
+---
+
+## Phase 1.5 页型分类
+
+在开始写作前，声明选中哪个页型。详见 `references/genres.md`。
+
+### 分类规则
+
+| 页型 | 关键词信号 | 何时选 |
+|------|-----------|--------|
+| G1 事件复盘 | 故障/复盘/事故/incident/postmortem/outage | 记录已发生事件 |
+| G2 对比选型 | 对比/选型/vs/versus/compare/benchmark/alternatives | 比较方案给建议 |
+| G3 清单索引 | 清单/列表/inventory/checklist/catalog/命令速查 | 罗列同类对象 |
+| G4 概念原理 | 原理/为什么/how it works/概念/机制 | 解释概念或机制 |
+| G5 现状账本 | 端口/版本/已部署/当前状态/上次核实/last verified + 组件表 | 记录此刻部署/运行态 |
+
+声明格式：`页型: G<N> <类型名>`
+
+关键词冲突时按页面核心目的选；仍有歧义选 G4。
+
+G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by: <path>` / `Deprecated`）；部署物清单每行必填「上次核实于」日期并有对应验证命令；必须写失效策略（什么作废本页 + 复核周期）；**禁止叙事正文**——本页是状态卡不是故事页，事件史写 G1 页并交叉引用。`classifyGenre` 与 `historian_migrate` 均已支持 G5（评分门控用账本变体判据）。
+
+---
+
+## Phase 2: 骨架写作
+
+按所选页型用对应骨架写作。详见：
+
+- **`references/genres.md`** — 五种页型的固定节序与表格要求
+- **`references/rules.md`** — SYN-1..20 写作规则 20 条
+- **`references/style.md`** — 信息密度阈值、双语写作惯例、禁止词汇
+- **`references/wikijs-guide.md`** — 可用表达件语法、禁止语法、API 陷阱
+
+### 写作纪律
+
+1. 每页 H1 后紧跟**状态块**（见 SYN-10）
+2. 尾部必须有 `## Related Pages` / `## 相关页面`（见 SYN-9）
+3. 时间线表三列：时间 | 事件 | 来源（见 SYN-7）
+4. 对比表含来源列（见 SYN-6）
+5. 行动项表六列（含五要素）：措施 | 类型 | 负责人 | 期限 | 验证 | 状态（见 SYN-8）
+6. 中文句 ≤20 字，英文句 ≤25 词（见 SYN-4）
+7. ≥3 字段入表（见 SYN-5）
+8. 禁止 `{{toc}}`、`:::` container、YAML frontmatter
+9. G5 每行可复核：版本/端口/端点 + 上次核实于 + 对应验证命令（见 genres.md G5 节）
+
+---
+
+## Phase 3: 变更
+
+只用 `historian_*` 工具操作 wiki。
+
+### 工具表
+
+| 工具 | 用途 | 关键参数 |
+|------|------|----------|
+| `historian_page_create` | 创建页面（含孪生） | `path`, `title`, `content`（缺省=返回本地骨架）, `genre`(G1-G5), `locale`(en/zh, 缺省 en), `isPublished`(缺省 true), `tags`(缺省 []), `twin`(缺省 true) |
+| `historian_page_update` | 更新页面（全量合并） | `path`, `locale`, `title?`, `content?`, `description?`, `tags?` |
+| `historian_page_append` | 追加到页面（双 locale） | `path`, `section`, `locale`, `sectionZh?` |
+| `historian_translate_snippet` | 翻译片段 | `text`, `from`(en/zh), `to`(en/zh) |
+| `historian_search` | 搜索页面 | `query`, `kind`(title/content) |
+| `historian_read` | 读取页面 | `path`, `locale` |
+| `historian_map` | 页面地图/时间线 | `action`(show/refresh/timeline)；timeline 可选 `days`（近 N 天）与 `path`（前缀过滤）；输出人读周表 markdown + 机读 weeks JSON，zh/en 行独立 |
+| `historian_migrate` | 迁移页面到规范 | `path`, `genre?`, `apply`(false/true) |
+| `historian_delete` | 删除页面 | `path`, `locale`, `confirm`(必须 "yes") |
+| `historian_move` | 移动页面 | `path`, `locale`, `newPath`, `newLocale?`, `confirm`(必须 "yes") |
+
+### 翻译失败处理
+
+`historian_page_create(twin:true)` 翻译失败时，en 页照常成功落库，返回 `zh_status: 'pending'`。在报告中声明此状态，不重试创建（避免空页污染）。后续可用 `historian_translate_snippet` + `historian_page_update` 手动补全。
+
+### Supersede 协议
+
+当页面 B 取代页面 A：
+
+1. B 达到骨架标准
+2. `historian_page_update` A：状态块改 `Superseded` + 链接 B，保留 A 的持久内容（历史记录）
+3. 更新 wiki-index：A 标 Superseded → 链接 B；B 列为权威
+4. 不允许两页同时声称是某主题的权威
+
+### 需要问用户的情况
+
+- 创建**新顶级章节**（提供放置选项）
+- **删除**任何页面
+- **重写**大量（>100 行）历史页面而非 supersede
+- **发布**未发布的页面
+- **合并**两个重要页面
+
+---
+
+## Phase 4: 收尾
+
+### 自检门 (Self-Review Gate)
+
+逐项过 10 项自检。**内容项 1-8 在 dry-run 稿评分；第 9-10 项在 apply 后核销**。
+
+| # | 检查项 | 适用 | 何时判 |
+|---|--------|------|--------|
+| 1 | 导言占比 10-15% | 全部 | dry-run |
+| 2 | 句长上限 zh≤20 / en≤25 | 全部 | dry-run |
+| 3 | ≥3 字段入表 | 全部 | dry-run |
+| 4 | 对比表含来源列（G5 变体：部署物清单每行带「上次核实于」列） | G2 / G5 | dry-run |
+| 5 | 时间线含来源列（G5 变体：验证方法含可执行复核命令） | G1 / G5 | dry-run |
+| 6 | 行动项五要素（G5 变体：无叙事正文 = 状态块 + 表格） | G1 / G5 | dry-run |
+| 7 | 无杂项筐 | 全部 | dry-run |
+| 8 | 无溢美词 | 全部 | dry-run |
+| 9 | 双语 URL 已回报 | 全部 | apply 后 |
+| 10 | 孪生已建或 zh-pending 已记录 | 全部 | apply 后 |
+
+页型不适用项（非 G1 的时间线/行动项、非 G2 的来源列）判 N/A=PASS；G5 页的第 4-6 项换用账本变体判据。
+
+任一内容项 FAIL → 修订草稿重试，每页最多 3 轮。用尽 → BLOCKED 停下报告。
+
+### 索引更新
+
+```
+historian_map action=refresh
+```
+
+任何 create / move / delete / supersede 后必须刷新。
+
+### 报告格式
+
+```markdown
+## 史官工作报告
+- **动作**: created `incidents/wiki-oom-restart` / updated `wiki-index` / moved …
+- **分诊**: incident postmortem → incidents/ → create (无现存页面覆盖该主题)
+- **页型**: G1 事件复盘
+- **链接**: backlink from `wiki-index`, cross-link to `ops/wiki`
+- **en URL**: http://<your-wiki>:3000/<path>
+- **zh URL**: http://<your-wiki>:3000/zh/<path>
+- **遗留**: <延期事项或问题 — 或 "无">
+```
+
+报告必须含 en/zh 双语 URL 行。缺 URL 行=报告不完整。
+
+---
+
+## 机构记忆层 (v4)：reading loop 与 capture
+
+插件从"被动工具集"升级为"机构记忆层"：机器侧两个机制，均不影响下述人工流程。
+
+### Reading loop（自动注入，默认开启）
+
+插件经 `experimental.chat.system.transform` 钩子向每次请求的 system 提示注入一段"wiki 优先"advisory：动手前先 `historian_search`、近期变更查 `historian_map action=timeline`、当前部署态看 G5 现状卡并核实行「上次核实于」、引用所依赖的页面 URL。agent 的义务是**执行**它，不是忽略它。
+
+- 选项 `readingLoop` 默认 `true`；关闭用插件二元组第二参数：`["<plugin-url>", { "readingLoop": false }]`。
+- 严格 OpenAI 兼容后端（如 vLLM）拒绝多条 system 消息（报 `System message must be at the beginning.`）——此类部署必须设 `readingLoop: false`。
+
+### Capture（主动留痕，默认关闭）
+
+- `/historian-capture` 斜杠命令**始终注册**（与 capture.enabled 无关）。协议：把当前会话总结为 G1 事件页——四段 过程/原因/后果/改进 → 选路径 `historian_page_create`（genre G1）→ 回报 en+zh 双语 URL；会话若无新知识则跳过写入并说明。
+- `{ "capture": { "enabled": true } }`（默认 `false`）时会话空闲弹一条 toast 提醒。提醒只是提醒——**绝不自动写页**，写入只经由显式工具调用。
+
+---
+
+## 检索模式
+
+当请求是"查 wiki"而非"写 wiki"时，进入只读检索模式。无变更、无 cache-refresh。
+
+### 检索模式
+
+| 模式 | 工具链 | 适用 |
+|------|--------|------|
+| A. 定向搜索 | `historian_search` → `historian_read` | 已知关键词，找特定页面 |
+| B. 结构获取 | `historian_read` 多个路径 | 已知路径，批量取内容 |
+| C. 发现浏览 | `historian_map` → 扫描 → `historian_search` / `historian_read` | 不确定有什么，先扫地图 |
+| D. 时间线追溯 | `historian_map action=timeline days=N [path=前缀]` | "这台机器最近/上周改了什么"、G5 卡漂移排查 |
+
+### 检索纪律
+
+- 预过滤：先 `historian_search`，不要 fetch 全部
+- 2-3 页通常足够
+- 引用页面路径以便调用方重新获取
+- 大页（>5K tokens）提示并提供提取单节选项
+
+---
+
+## References: 何时读
+
+| 文件 | 何时读 |
+|------|--------|
+| `references/rules.md` | 每次写作前过一遍 SYN-1..20 规则 |
+| `references/genres.md` | Phase 1.5 选页型时、Phase 2 按骨架写作时 |
+| `references/wikijs-guide.md` | 用户问"中文页面在哪看"、遇到 API 错误、需要确认语法是否支持 |
+| `references/style.md` | 检查信息密度、双语写作惯例、禁止词汇 |
+| `references/adapting-your-own-wiki.md` | 换机器/换 wiki.js 实例接入史官；配 sections 白名单；翻译腿缺省行为；关 readingLoop/capture；发布前隐私门 |