opencode-wiki-historian 0.5.0 → 0.5.1

package/dist/maintain.d.ts

@@ -91,7 +91,7 @@ export interface MaintainReport {
             childPath: string;
         }[];
     };
-    readonly rootOrphans: readonly {
+    readonly flatRootPages: readonly {
         section: string;
         paths: readonly string[];
     }[];
@@ -114,7 +114,7 @@ export interface MaintainReport {
     }[];
     readonly freshness: FreshnessScan | null;
 }
-export declare const MAINTAIN_SCHEMA = "historian.maintain.v1";
+export declare const MAINTAIN_SCHEMA = "historian.maintain.v2";
 /** Trigram-Jaccard bar for calling two (different-path) titles near-duplicates. */
 export declare const DUP_TITLE_THRESHOLD = 0.75;
 export declare function buildMaintainReport(input: MaintainInput, opts?: MaintainOptions): Promise<MaintainReport>;

package/dist/maintain.js

@@ -17,7 +17,7 @@ import { classifyGenre } from './templates/genres.js';
 import { isInternalPath } from './tools/shared.js';
 import { normalize } from './migrate-score.js';
 // --- Constants --------------------------------------------------------------
-export const MAINTAIN_SCHEMA = 'historian.maintain.v1';
+export const MAINTAIN_SCHEMA = 'historian.maintain.v2';
 /** Trigram-Jaccard bar for calling two (different-path) titles near-duplicates. */
 export const DUP_TITLE_THRESHOLD = 0.75;
 const DAY_MS = 86_400_000;
@@ -58,8 +58,11 @@ function jaccard(a, b) {
 function cmpStr(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+// bold-merge deliberately leaves (重定向)/(redirect)-suffixed stubs beside their
+// live twins; clustering those pairs reports non-defects and buries true near-dupes.
+const STUB_TITLE_RE = /[（(]\s*(?:重定向|redirect)\s*[）)]\s*$/i;
 function findDuplicates(rows) {
-    const units = rows.map((r) => ({
+    const units = rows.filter((r) => !STUB_TITLE_RE.test(r.title)).map((r) => ({
         path: r.path,
         title: r.title,
         grams: titleGrams(normalize(r.title).toLowerCase()),
@@ -147,7 +150,7 @@ function singleChildDirs(paths) {
     }
     return out;
 }
-function rootOrphans(paths) {
+function flatRootPages(paths) {
     const bySection = new Map();
     for (const path of paths) {
         if (path.split('/').length !== 2)
@@ -270,7 +273,7 @@ export async function buildMaintainReport(input, opts = {}) {
         duplicates: { threshold: DUP_TITLE_THRESHOLD, clusters: findDuplicates(kept) },
         staleness: { topN, oldest: staleness(kept, now, topN) },
         diffusion: { singleChildDirs: singleChildDirs(paths) },
-        rootOrphans: rootOrphans(paths),
+        flatRootPages: flatRootPages(paths),
         tags: tagVocab(kept),
         redirects,
         sections: sectionDist(kept),
@@ -313,10 +316,10 @@ export function renderMaintainMarkdown(r) {
         L.push('  - none');
     for (const d of r.diffusion.singleChildDirs)
         L.push(`  - \`${d.dir}/\` holds only \`${d.childPath}\``);
-    L.push('- root-level orphans (depth-2 pages, no sub-shelf):');
-    if (r.rootOrphans.length === 0)
+    L.push('- flat root pages per section (depth-2 listing, shelving hint — NOT inbound analysis; true orphans = surface deep links.orphanPages):');
+    if (r.flatRootPages.length === 0)
         L.push('  - none');
-    for (const o of r.rootOrphans)
+    for (const o of r.flatRootPages)
         L.push(`  - \`${o.section}/\` (${fmt(o.paths.length)}): ${o.paths.map((p) => `\`${p}\``).join(', ')}`);
     L.push('', '## Tag vocabulary', '');
     if (!r.tags.available)

package/dist/surface.d.ts

@@ -13,6 +13,7 @@
  */
 import type { MaintainRow } from './maintain.js';
 import type { Locale } from './wiki/pages.read.js';
+import type { NavSnapshot } from './wiki/nav.js';
 export declare const SURFACE_SCHEMA: "historian.surface.v1";
 /** Minimal shape of a live `pages.list` row the surface diff needs. */
 export interface LiveRow {
@@ -26,6 +27,12 @@ export interface SurfaceInput {
     readonly generatedAt: string;
     readonly baseUrl: string;
     readonly liveInventory?: readonly LiveRow[];
+    /**
+     * Live primary nav. Issue #1's disease is sidebar exposure, so the check
+     * must read the real tree — omit/null reports `available: false` rather
+     * than falsely claiming a clean nav.
+     */
+    readonly nav?: NavSnapshot | null;
     readonly deep?: boolean;
     readonly readBody?: (path: string, locale: Locale) => Promise<string | null>;
 }
@@ -39,7 +46,18 @@ export interface SurfaceCoverage {
     readonly removedFromLive: number;
 }
 export interface SurfaceNav {
-    readonly machineSections: readonly string[];
+    readonly available: boolean;
+    readonly mode: string | null;
+    /** DYNAMIC/MIXED re-mirror the filesystem page tree into the sidebar — the exact Issue #1 relapse. */
+    readonly filesystemExposed: boolean;
+    /** Underscore-prefixed (machine-namespace) links explicitly mounted in the curated tree. */
+    readonly machineLinks: {
+        readonly locale: string;
+        readonly label: string;
+        readonly target: string;
+    }[];
+    /** Informational: underscore segments in the PAGE tree — by design (_meta/_evidence/_sandbox/_data). */
+    readonly machinePaths: readonly string[];
     readonly sectionLandingMissing: {
         readonly dir: string;
         readonly pagePaths: number;

package/dist/surface.js

@@ -16,6 +16,9 @@ import { lintBody } from './lint.js';
 import { classifyGenre } from './templates/genres.js';
 export const SURFACE_SCHEMA = 'historian.surface.v1';
 const MACHINE_SEG_RE = /^_/;
+// nav targets carry a leading slash and may pre-pend the locale segment
+// (/zh/_meta/x) — machine check runs on the first real path segment.
+const MACHINE_TARGET_RE = /^\/(?:(?:en|zh)\/)?_[^/]+/;
 const ROOT_EXEMPT = new Set(['home', 'wiki-index']);
 const visible = (r) => r.isPublished !== false && r.isPrivate !== true;
 const rowKey = (path, locale) => `${locale}\u0000${path}`;
@@ -23,15 +26,24 @@ function isFrontPath(path) {
     return !isInternalPath(path) && !path.startsWith('_sandbox/') && !path.startsWith('_data/');
 }
 // --- light tier ---------------------------------------------------------------
-function buildNav(rows, live) {
+function buildNav(rows, live, nav) {
     const paths = new Set();
     for (const r of rows)
         paths.add(r.path);
     for (const r of live ?? [])
         paths.add(r.path);
-    const machineSections = [...new Set([...paths].map((p) => p.split('/')[0]))]
+    const machinePaths = [...new Set([...paths].map((p) => p.split('/')[0]))]
         .filter((s) => MACHINE_SEG_RE.test(s))
         .sort();
+    const mode = nav?.mode ?? null;
+    const machineLinks = [];
+    for (const t of nav?.trees ?? []) {
+        for (const it of t.items) {
+            if (MACHINE_TARGET_RE.test(it.target)) {
+                machineLinks.push({ locale: t.locale, label: it.label, target: it.target });
+            }
+        }
+    }
     const perDir = new Map();
     for (const p of paths) {
         const seg = p.split('/');
@@ -43,7 +55,14 @@ function buildNav(rows, live) {
         .filter(([dir, n]) => n >= 2 && !paths.has(dir))
         .map(([dir, pagePaths]) => ({ dir, pagePaths }))
         .sort((a, b) => b.pagePaths - a.pagePaths || a.dir.localeCompare(b.dir));
-    return { machineSections, sectionLandingMissing };
+    return {
+        available: nav != null,
+        mode,
+        filesystemExposed: mode === 'DYNAMIC' || mode === 'MIXED',
+        machineLinks,
+        machinePaths,
+        sectionLandingMissing,
+    };
 }
 function buildCoverage(rows, live) {
     if (live === undefined)
@@ -269,7 +288,7 @@ export async function buildSurfaceReport(input) {
         generatedAt: input.generatedAt,
         deep: input.deep === true,
         coverage: buildCoverage(input.rows, input.liveInventory),
-        nav: buildNav(input.rows, input.liveInventory),
+        nav: buildNav(input.rows, input.liveInventory, input.nav),
         tagsEmpty: input.rows
             .filter((r) => isFrontPath(r.path) && (r.tags?.length ?? 0) === 0)
             .map((r) => ({ path: r.path, locale: r.locale }))
@@ -291,8 +310,21 @@ export function renderSurfaceMarkdown(r) {
         for (const m of cap(r.coverage.missingFromMap, 40))
             L.push(`  - \`${m.locale}/${m.path}\``);
     }
-    L.push('', '## 导航 Nav（动态侧栏镜像）', '');
-    L.push(`- 机器命名空间暴露 machineSections: ${r.nav.machineSections.map((s) => `\`${s}/\``).join(' ') || 'none'}`);
+    L.push('', '## 导航 Nav（真相 = 实时导航树，非页面树推断）', '');
+    if (!r.nav.available) {
+        L.push('- ⚠ 导航树不可读（nav.available=false）— 机器段暴露无法核验，请检查 token 的导航读取权限');
+    }
+    else {
+        L.push(`- mode: \`${r.nav.mode}\` · 文件系统暴露 filesystemExposed: ${r.nav.filesystemExposed ? '⚠ 是 — DYNAMIC/MIXED 会把页面树镜像回侧栏（Issue #1 复发）' : '否'}`);
+        if (r.nav.machineLinks.length > 0) {
+            L.push(`- ⚠ 导航树内机器段链接 machineLinks (${r.nav.machineLinks.length}):`);
+            for (const m of cap(r.nav.machineLinks, 20))
+                L.push(`  - [${m.locale}] ${m.label} → \`${m.target}\``);
+        }
+        else {
+            L.push(`- 导航树内机器段链接: none ✓（页面树存档段 ${r.nav.machinePaths.map((s) => `\`${s}/\``).join(' ') || '—'} 属设计内，仅备查）`);
+        }
+    }
     if (r.nav.sectionLandingMissing.length > 0) {
         L.push(`- 落地页缺失 sectionLandingMissing（面包屑 404 / 空目录页）:`);
         for (const s of r.nav.sectionLandingMissing)

package/dist/tools/local.js

@@ -12,6 +12,7 @@ import { buildMaintainReport, renderMaintainMarkdown } from '../maintain.js';
 import { buildSurfaceReport, renderSurfaceMarkdown } from '../surface.js';
 import { normalizeLocale, PathValidationError } from '../wiki/locale.js';
 import { listPages, readPage } from '../wiki/pages.read.js';
+import { readPrimaryNav } from '../wiki/nav.js';
 import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
 const s = tool.schema;
 const TRANSLATE_ARGS = {
@@ -102,17 +103,19 @@ async function runMaintain(deps, mapDeps, snapshot, deep) {
         }
         : undefined;
     const report = await buildMaintainReport({ rows, mapGeneratedAt: snapshot.generatedAt, mapStaleSeconds: snapshot.staleSeconds }, { deep, readBody });
+    const nav = await readPrimaryNav(client);
     const surface = await buildSurfaceReport({
         rows,
         generatedAt: report.generatedAt,
         baseUrl: deps.options.baseUrl,
         liveInventory,
+        nav,
         deep,
         readBody,
     });
     return {
         action: 'maintain',
-        schema: 'historian.maintain.v2',
+        schema: 'historian.maintain.v3',
         deep: report.deep,
         generatedAt: report.generatedAt,
         rowCount: report.rowCount,

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.5.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 行独立；maintain 同时返回 surface 接口面体检（信封 `historian.maintain.v2`） |
+| `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,21 +327,21 @@ historian_map action:'refresh'
 - **light 扫：每次批量写后必跑**——只基于地图行 + 每 locale 一次只读 `pages.list`（便宜，随批走）
 - **deep 扫：每周至多一次**——逐页读正文，跑新鲜度（缺「上次核实于」/ 复核过期）与 `> Redirect:` 存根计数（贵，克制用）
 
-light 扫在 maintain 行之外附带 **surface-light**：`coverage`（live 页面与地图不一致）、`nav`（`_*` 机器命名空间暴露于侧栏 / 章节缺落地页→面包屑 404）、`tagsEmpty`；deep 扫附带 **surface-deep**：正文级检测，逐页一次读取、双消费者共享缓存。
+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.machineSections`（surface） | `_*` 机器命名空间进侧栏 | 导航树手工策划，只挂主题章节 |
+| `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） | 存根无可点出口 / 死链 / 指存根 / 同页多锚点 | 修出口与目标；锚点收敛到规范页 |