opencode-wiki-historian 0.4.0 → 0.5.1

package/dist/tools/shared.js

@@ -11,6 +11,7 @@
 import { assertLocalePair, PathValidationError } from '../wiki/locale.js';
 import { scoreChecklist } from '../migrate-score.js';
 import { selfReviewChecklist } from '../templates/genres.js';
+import { lintBody, publishGateViolations } from '../lint.js';
 /** Engine deps for one operation; client resolved lazily at use time. */
 export function pageDeps(deps) {
     return { client: deps.getClient(), options: deps.options, translate: deps.translate };
@@ -83,6 +84,8 @@ function hintFor(errorKind) {
             return 'The wiki endpoint is unreachable or misconfigured — check baseUrl and network.';
         case 'GraphQLError':
             return 'The wiki answered a GraphQL error — check the path/locale arguments.';
+        case 'PublishGateError':
+            return '消除 TODO/空节并把状态置 Active，或保留 状态:draft 待自检通过后发布；重定向存根正文必须带可点击的 [链接](目标URL)。';
         default:
             return 'Inspect the message and retry.';
     }
@@ -304,3 +307,23 @@ export function sectionRefusalJson(path, allowedSections) {
     const violation = sectionGuard(path, allowedSections);
     return violation === null ? null : errEnvelope(new ConfigError(violation));
 }
+// --- publish gate (V6.1, HANDOFF #5.1 / #6.1) --------------------------------
+export class PublishGateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PublishGateError';
+    }
+}
+/** Hard gate on front-tier writes: refuses the two shapes that shipped real
+ *  incidents — a page claiming Active with TODO markers or empty skeleton
+ *  sections, and a redirect stub whose body carries no clickable exit.
+ *  `_sandbox/*` and internal namespaces are exempt; 状态:draft stays the
+ *  sanctioned work-in-progress escape hatch. Null = proceed. */
+export function publishGateRefusalJson(content, locale, path, baseUrl) {
+    if (path.startsWith('_sandbox/') || isInternalPath(path))
+        return null;
+    const violations = publishGateViolations(lintBody(content, { locale, baseUrl }));
+    if (violations.length === 0)
+        return null;
+    return errEnvelope(new PublishGateError(`publish-gate: ${violations.join('; ')} on '${path}' (${locale})`));
+}

package/dist/tools/write.js

@@ -7,7 +7,7 @@
 import { tool } from '@opencode-ai/plugin';
 import { appendSection, createPage, updatePage, PageNotFoundError } from '../wiki/pages.js';
 import { readPage } from '../wiki/pages.read.js';
-import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
+import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, publishGateRefusalJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
 const s = tool.schema;
 const UPDATE_ARGS = {
     path: s.string(),
@@ -33,6 +33,11 @@ export function makeUpdateTool(deps) {
                 if (page === null) {
                     return errEnvelope(new PageNotFoundError(`page '${args.path}' (${args.locale}) does not exist`));
                 }
+                if (args.content !== undefined) {
+                    const gate = publishGateRefusalJson(args.content, args.locale, page.path, deps.options.baseUrl);
+                    if (gate !== null)
+                        return gate;
+                }
                 const result = await updatePage(pageDeps(deps), page.id, {
                     title: args.title,
                     content: args.content,

package/dist/wiki/nav.d.ts

@@ -0,0 +1,21 @@
+import { type GqlClient } from './client.js';
+export interface NavItem {
+    readonly label: string;
+    readonly targetType: string;
+    readonly target: string;
+}
+export interface NavTree {
+    readonly locale: string;
+    readonly items: readonly NavItem[];
+}
+export interface NavSnapshot {
+    readonly mode: string;
+    readonly trees: readonly NavTree[];
+}
+/** Shape-tolerant parse: unknown/nullish shapes degrade to '' entries; a
+ *  payload without `navigation` is not-a-nav (null), letting the caller mark
+ *  the check unavailable instead of claiming "clean". */
+export declare function parseNav(raw: unknown): NavSnapshot | null;
+/** Never throws: an unreadable nav (older server, token without navigation
+ *  read) returns null so the scan degrades to "unavailable", not failure. */
+export declare function readPrimaryNav(client: GqlClient): Promise<NavSnapshot | null>;

package/dist/wiki/nav.js

@@ -0,0 +1,43 @@
+// Live navigation reader (v0.5.1). Issue #1's actual disease was the SIDEBAR
+// mirroring the filesystem (DYNAMIC/MIXED exposing _meta/_evidence/_sandbox),
+// not the existence of machine-namespace pages — those are by design. So the
+// detector reads the real primary nav (mode + curated flat trees) instead of
+// inferring exposure from the page tree.
+//
+// Shape note: this wiki.js generation REJECTS `children` on NavigationItem
+// (HTTP 400, re-probed 2026-09-08) — flat `items` are the whole truth.
+import { gql } from './client.js';
+const NAV_QUERY = '{ navigation { config { mode } tree { locale items { label targetType target } } } }';
+/** Shape-tolerant parse: unknown/nullish shapes degrade to '' entries; a
+ *  payload without `navigation` is not-a-nav (null), letting the caller mark
+ *  the check unavailable instead of claiming "clean". */
+export function parseNav(raw) {
+    const nav = raw?.navigation;
+    if (nav === undefined || nav === null)
+        return null;
+    const trees = [];
+    for (const t of Array.isArray(nav.tree) ? nav.tree : []) {
+        const row = t;
+        const items = [];
+        for (const i of Array.isArray(row?.items) ? row.items : []) {
+            const it = i;
+            items.push({
+                label: typeof it?.label === 'string' ? it.label : '',
+                targetType: typeof it?.targetType === 'string' ? it.targetType : '',
+                target: typeof it?.target === 'string' ? it.target : '',
+            });
+        }
+        trees.push({ locale: typeof row?.locale === 'string' ? row.locale : '', items });
+    }
+    return { mode: typeof nav.config?.mode === 'string' ? nav.config.mode : '', trees };
+}
+/** Never throws: an unreadable nav (older server, token without navigation
+ *  read) returns null so the scan degrades to "unavailable", not failure. */
+export async function readPrimaryNav(client) {
+    try {
+        return parseNav(await gql(client, NAV_QUERY, {}));
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-wiki-historian",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "opencode plugin that manages a wiki.js knowledge base with bilingual pages, genre templates, and migration tooling.",
   "type": "module",
   "license": "MIT",

package/skills/historian/SKILL.md

@@ -200,7 +200,7 @@ G5 现状卡的硬约束：状态块是机读单行（`Active` / `Superseded-by:
 | `historian_translate_snippet` | 翻译片段 | `text`, `from`(en/zh), `to`(en/zh) |
 | `historian_search` | 搜索页面 | `query`, `kind`(title/content), `tags?`(1-5 个), `tagsMode?`(all 缺省/any) |
 | `historian_read` | 读取页面 | `path`, `locale` |
-| `historian_map` | 页面地图/时间线/维护扫描 | `action`(show/refresh/timeline/maintain)；maintain 可选 `deep`（缺省 false=light 扫）；timeline 可选 `days`（近 N 天）与 `path`（前缀过滤）；输出人读 markdown + 机读 JSON，zh/en 行独立 |
+| `historian_map` | 页面地图/时间线/维护扫描 | `action`(show/refresh/timeline/maintain)；maintain 可选 `deep`（缺省 false=light 扫）；timeline 可选 `days`（近 N 天）与 `path`（前缀过滤）；输出人读 markdown + 机读 JSON，zh/en 行独立；maintain 同时返回 surface 接口面体检（信封 `historian.maintain.v3`） |
 | `historian_migrate` | 迁移页面到规范 | `path`, `genre?`, `apply`(false/true) |
 | `historian_delete` | 删除页面 | `path`, `locale`, `confirm`(必须 "yes") |
 | `historian_move` | 移动页面 | `path`, `locale`, `newPath`, `newLocale?`, `confirm`(必须 "yes") |
@@ -327,17 +327,29 @@ historian_map action:'refresh'
 - **light 扫：每次批量写后必跑**——只基于地图行 + 每 locale 一次只读 `pages.list`（便宜，随批走）
 - **deep 扫：每周至多一次**——逐页读正文，跑新鲜度（缺「上次核实于」/ 复核过期）与 `> Redirect:` 存根计数（贵，克制用）
 
+light 扫在 maintain 行之外附带 **surface-light**：`coverage`（live 页面与地图不一致）、`nav`（侧栏真相=实时导航树：mode 非 STATIC 即把页面树镜像回侧栏 / 树内挂 `_` 段链接 / 章节缺落地页→面包屑 404）、`tagsEmpty`；deep 扫附带 **surface-deep**：正文级检测，逐页一次读取、双消费者共享缓存。
+
 报告行 → 处置映射表：
 
 | 报告行 | 含义 | 处置 |
 |--------|------|------|
 | `missingTwinPaths` | 双语孪生缺口 | 补孪生：翻译腿建 zh（或 en）页，走翻译失败处理 |
-| `duplicates.clusters` | 近重复标题簇（trigram-Jaccard 阈值） | bold-merge 流程：选最完整页为权威（bold），其余走 supersede 或 Redirect 存根 |
+| `duplicates.clusters` | 近重复标题簇（trigram-Jaccard 阈值；「（重定向）」存根不参与聚类） | bold-merge 流程：选最完整页为权威（bold），其余走 supersede 或 Redirect 存根 |
 | `staleness.oldest` | 最陈旧页 | mark/refresh：G5 卡重新核实或标记 stale，不静默覆盖 |
-| `rootOrphans` / `diffusion.singleChildDirs` | 顶级孤儿 / 独子目录 | 归架：并入正确章节、建章节索引，或按冻结协议做 Redirect 存根 |
+| `flatRootPages` / `diffusion.singleChildDirs` | 章节根平铺页清单（归架提示，非入链判定）/ 独子目录 | 归架：并入正确章节、建章节索引，或按冻结协议做 Redirect 存根；真孤儿看 surface deep 的 `orphanPages` |
 | `tags.vocabulary` | 标签漂移 | 词表映射：近义标签收敛到主词，`historian_page_update` 批量改 |
 | `redirects.stubs`（deep） | 重定向存根清单 | 核对目标存在、入链已改写；死链存根即修 |
 | `freshness`（deep） | 缺核实戳 / reviewBy 过期 | 回 G5 卡补核；到期页列入下周复核 |
+| `coverage.missingFromMap`（surface） | 新页/迁移未进地图 | `action:'refresh'` 后重扫 |
+| `nav.filesystemExposed` / `nav.machineLinks`（surface） | 侧栏被 DYNAMIC/MIXED 镜像出页面树 / 导航树里挂了 `_` 段链接 | 导航树手工策划只挂主题章节，mode 固定 STATIC；`nav.available=false` 时先修 token 导航读权限再下结论 |
+| `nav.sectionLandingMissing`（surface） | 章节缺落地页（面包屑 404） | 建章节总览页并链入 wiki-index |
+| `unfinished`（surface deep） | Active 页含 TODO/空节/导言空 | 补全或降回 draft |
+| `stubs` / `links.broken` / `toStubs` / `sameTargetStacks`（deep） | 存根无可点出口 / 死链 / 指存根 / 同页多锚点 | 修出口与目标；锚点收敛到规范页 |
+| `orphanPages` / `indexMissing`（deep） | 无入链 / 未入索引 | 归架：从相关页与 wiki-index 补链 |
+| `roleDivergence`（deep） | 同题页 en/zh 一存根一活页 | 双侧收敛到同一权威页 |
+| `twinParity`（deep） | 孪生正文分叉（长度/节结构） | 重译或重排落后的孪生腿 |
+| `zhEnglishDominant`（deep） | zh 页英文为主（违反中文为主） | 按 zh-first 政策重写 |
+| `ledgerClaims`（deep） | 事实密集页缺「上次核实于」戳 | 逐条对机器核实后补戳，或标 stale |
 
 ### 闸门回路 (gate)：reading loop + sections guard
 
@@ -350,6 +362,14 @@ historian_map action:'refresh'
 - 注入语义为**单块追加**：advisory 拼接到 system 提示的最后一个块（`\n\n` 分隔），system 为空数组时才新建块——绝不产生第二条 system 消息。严格 OpenAI 兼容后端（如 vLLM）会以 `System message must be at the beginning.` 拒绝多 system 请求，单块追加从根上规避此坑。
 - 幂等去重：同一请求的任一 system 块已含 `historian_search` 字样则跳过注入。
 
+#### 发布闸门 publish gate（写入硬拒，v0.5.0）
+
+`historian_page_create` 与带 `content` 的 `historian_page_update` 在**任何写入前**硬检正文，违例即零写入拒绝（`errorKind: PublishGateError`）：
+
+- **R1 存根须有出口**：`> Redirect:` 开头的正文必须含 ≥1 条可点击链接；纯行内代码路径不算出口
+- **R2 Active 不许半成品**：状态行为 `Active` 且正文含 TODO/TBD/占位注释或空节 → 拒绝；未完稿保持 `draft`——G1-G6 骨架状态行缺省即 `draft`，翻 Active 就是过闸动作
+- 豁免：`_sandbox/**` 与内部层（`_meta/`、`_evidence/`）；`append` 不过闸（增量语义），由 deep 扫描兜底
+
 #### sections guard（路径闸门）
 
 写入路径首段受插件选项 `sections` 白名单强制（配置后不在白名单的前缀被拒）。豁免段恒可写：`home`、`wiki-index`、`_sandbox`、`_data`、`_meta`、`_evidence`——机构记忆不能反锁落地的着陆页与机器命名空间。`tier:"evidence"` 的页面不校验（证据层是原材料归宿）。白名单为空的部署不做前缀限制，实际权限由 wiki.js token 的 page rules 决定。