ppxans-harness 2.6.0 → 3.2.1

package/src/utils/text.js

@@ -1,16 +1,16 @@
-// src/utils/text.js - 零依赖文本工具 (token 估算等, 供 agent/llm 等共用)
-// 单一实现, 避免 agent 与 llm 各自维护一份 token 估算导致口径漂移。
-
-// 估算 token 数: 中文字符约 1 字 ≈ 0.6 token, 1 token ≈ 4 字符; 统一按字符数 /1.6 估。
-export function estimateTokens(s) {
-  return Math.ceil(String(s || "").length / 1.6);
-}
-
-// 按 token 预算截断字符串: 保留头部信息 (供 persona/角色设定等需保留 key 信息的场景),
-// 超预算时在尾部标注截断来源与总量。与 estimateTokens 同口径 (字符/1.6)。
-export function truncateByTokens(s, budget) {
-  const str = String(s || "");
-  const maxLen = Math.floor(budget * 1.6);
-  if (str.length <= maxLen) return str;
-  return str.slice(0, maxLen) + `\n...[persona 已按预算截断, 共 ${str.length} 字符]...`;
+// src/utils/text.js - 零依赖文本工具 (token 估算等, 供 agent/llm 等共用)
+// 单一实现, 避免 agent 与 llm 各自维护一份 token 估算导致口径漂移。
+
+// 估算 token 数: 中文字符约 1 字 ≈ 0.6 token, 1 token ≈ 4 字符; 统一按字符数 /1.6 估。
+export function estimateTokens(s) {
+  return Math.ceil(String(s || "").length / 1.6);
+}
+
+// 按 token 预算截断字符串: 保留头部信息 (供 persona/角色设定等需保留 key 信息的场景),
+// 超预算时在尾部标注截断来源与总量。与 estimateTokens 同口径 (字符/1.6)。
+export function truncateByTokens(s, budget) {
+  const str = String(s || "");
+  const maxLen = Math.floor(budget * 1.6);
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen) + `\n...[persona 已按预算截断, 共 ${str.length} 字符]...`;
 }

package/src/utils/trace.js

@@ -1,153 +1,153 @@
-// src/utils/trace.js - 结构化可观测轨迹 (Harness 第四层)
-// 记录每次工具调用的完整轨迹: 工具/参数/结果摘要/耗时/成败
-// 写 JSONL 到 data/logs/traces/YYYY-MM-DD.jsonl, 供事后复盘"哪一步坏了"
-// v1.0.8: args/result 落盘前 PII 脱敏 (凭证不写日志); read(day) 支持按指定日期读取
-// P0 (2026-09-15): 事件源不变量 (model-visible = logged) ——
-//   turn/step 边界事件落同一 JSONL + verifyReplay() 重放校验 (配对完整性/顺序性)。
-//   对齐 dsh "会话日志是模型可见内容的唯一事实源" 思想, 用皮皮虾自有结构增量实现。
-import fs from "node:fs";
-import path from "node:path";
-import { ensureDir, logicalDay } from "./store.js";
-import { scrubPII } from "./pii.js";
-
-const MAX_TRACE_BODY = 2000;   // 单条结果保留上限, 防爆文件
-
-// 事件类型常量 (turn/step 边界)
-export const EVT = {
-  TURN_START: "turn/start",
-  TURN_END: "turn/end",
-  STEP_START: "step/start",
-  STEP_END: "step/end",
-  TOOL: "tool/call",
-};
-
-export class Traces {
-  constructor(dataDir) {
-    this.dir = path.join(dataDir, "logs", "traces");
-    ensureDir(this.dir);
-    this.sessionId = "s_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
-    this.count = 0;
-  }
-
-  _file(day = logicalDay()) { return path.join(this.dir, `${day}.jsonl`); }
-
-  // 记录一次工具调用轨迹
-  record({ tool, args, result, ok, durationMs, error }) {
-    const entry = this._entry({ evt: EVT.TOOL, tool, args, result, ok, durationMs, error });
-    fs.appendFileSync(this._file(), JSON.stringify(entry) + "\n", "utf8");
-    return entry;
-  }
-
-  // ---- P0: turn/step 边界事件 (事件源事实) ----
-  recordTurnStart({ sessionId, reason } = {}) {
-    return this._append({ evt: EVT.TURN_START, tsIso: new Date().toISOString(), reason: reason || "user", sessionId: sessionId || this.sessionId });
-  }
-  recordTurnEnd({ ok = true, rounds = 0, reason } = {}) {
-    return this._append({ evt: EVT.TURN_END, ok: !!ok, rounds, reason: reason || null });
-  }
-  recordStepStart({ round = 0, context } = {}) {
-    // context 快照 = 该 step 模型看到的上下文投影摘要 (验证 model-visible = logged)
-    const safe = context ? scrubPII(JSON.stringify(context)).cleaned : null;
-    return this._append({ evt: EVT.STEP_START, round, context: safe ? this._truncate(safe) : null });
-  }
-  recordStepEnd({ round = 0, ok = true, tool = null, error } = {}) {
-    return this._append({ evt: EVT.STEP_END, round, ok: !!ok, tool: tool || null, error: error || null });
-  }
-
-  _append(extra) {
-    this.count += 1;
-    const entry = { ...this._base(), ...extra };
-    fs.appendFileSync(this._file(), JSON.stringify(entry) + "\n", "utf8");
-    return entry;
-  }
-
-  _base() {
-    return { ts: new Date().toISOString(), sessionId: this.sessionId, seq: this.count };
-  }
-
-  _entry({ evt, tool, args, result, ok, durationMs, error }) {
-    const safeArgs = scrubPII(JSON.stringify(args ?? {})).cleaned;
-    const safeResult = scrubPII(String(result ?? "")).cleaned;
-    return {
-      ...this._base(),
-      evt: evt || EVT.TOOL,
-      tool,
-      args: this._truncate(safeArgs),
-      result: this._truncate(safeResult),
-      ok: !!ok,
-      durationMs: Math.round(durationMs || 0),
-      error: error || null,
-    };
-  }
-
-  _truncate(s) {
-    const str = String(s ?? "");
-    return str.length > MAX_TRACE_BODY ? str.slice(0, MAX_TRACE_BODY) + "…" : str;
-  }
-
-  // ---- P0: 事件源不变量断言 (model-visible = logged) ----
-  // 重放校验: 1) 每行可解析  2) turn/step 配对完整 (start 必有 end, 嵌套合法)  3) step round 递增无重复
-  // 返回 { ok, total, errors: [] }。任何不变量破坏 → ok=false + 具体错误行, 供自愈/测试定位。
-  verifyReplay(day = logicalDay()) {
-    const lines = this.readRaw(day);
-    const errors = [];
-    const turnStack = [];
-    const stepRounds = new Set();
-    let total = 0;
-    for (let i = 0; i < lines.length; i++) {
-      let e;
-      try { e = JSON.parse(lines[i]); } catch (err) { errors.push({ line: i + 1, kind: "parse", detail: err.message }); continue; }
-      total++;
-      if (!e || !e.evt) { errors.push({ line: i + 1, kind: "no-evt" }); continue; }
-      if (e.evt === EVT.TURN_START) turnStack.push(i);
-      else if (e.evt === EVT.TURN_END) {
-        if (!turnStack.length) errors.push({ line: i + 1, kind: "turn-end-orphan" });
-        else turnStack.pop();
-      } else if (e.evt === EVT.STEP_START) {
-        const r = Number(e.round);
-        if (stepRounds.has(r)) errors.push({ line: i + 1, kind: "step-round-duplicate", detail: `round=${r}` });
-        stepRounds.add(r);
-      }
-    }
-    if (turnStack.length) errors.push({ kind: "turn-unclosed", detail: `剩余 ${turnStack.length} 个未闭合 turn` });
-    return { ok: errors.length === 0, total, errors };
-  }
-
-  // 读原始行 (verifyReplay 用, 不跳过坏行)
-  readRaw(day = logicalDay()) {
-    const file = this._file(day);
-    if (!fs.existsSync(file)) return [];
-    return fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
-  }
-
-  // 读取某天轨迹 (最近 N 条); day 缺省 = 今天
-  read(day, limit = 100) {
-    const file = this._file(day);
-    if (!fs.existsSync(file)) return [];
-    return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-limit)
-      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
-  }
-
-  // 统计: 失败率/平均耗时/慢工具
-  stats(day) {
-    const all = this.read(day, 10000);
-    if (!all.length) return { count: 0, failed: 0, failRate: "0%", slowTools: [] };
-    const failed = all.filter((t) => !t.ok);
-    const byTool = {};
-    for (const t of all) {
-      (byTool[t.tool] = byTool[t.tool] || { calls: 0, fails: 0, totalMs: 0 });
-      byTool[t.tool].calls++;
-      if (!t.ok) byTool[t.tool].fails++;
-      byTool[t.tool].totalMs += t.durationMs;
-    }
-    const slow = Object.entries(byTool)
-      .map(([tool, v]) => ({ tool, ...v, avgMs: Math.round(v.totalMs / v.calls) }))
-      .sort((a, b) => b.avgMs - a.avgMs).slice(0, 5);
-    return {
-      count: all.length,
-      failed: failed.length,
-      failRate: all.length ? (failed.length / all.length * 100).toFixed(1) + "%" : "0%",
-      slowTools: slow,
-    };
-  }
-}
+// src/utils/trace.js - 结构化可观测轨迹 (Harness 第四层)
+// 记录每次工具调用的完整轨迹: 工具/参数/结果摘要/耗时/成败
+// 写 JSONL 到 data/logs/traces/YYYY-MM-DD.jsonl, 供事后复盘"哪一步坏了"
+// v1.0.8: args/result 落盘前 PII 脱敏 (凭证不写日志); read(day) 支持按指定日期读取
+// P0 (2026-09-15): 事件源不变量 (model-visible = logged) ——
+//   turn/step 边界事件落同一 JSONL + verifyReplay() 重放校验 (配对完整性/顺序性)。
+//   对齐 dsh "会话日志是模型可见内容的唯一事实源" 思想, 用皮皮虾自有结构增量实现。
+import fs from "node:fs";
+import path from "node:path";
+import { logsDir, logicalDay } from "./store.js";
+import { shortId } from "./id.js";
+import { scrubPII } from "./pii.js";
+
+const MAX_TRACE_BODY = 2000;   // 单条结果保留上限, 防爆文件
+
+// 事件类型常量 (turn/step 边界)
+export const EVT = {
+  TURN_START: "turn/start",
+  TURN_END: "turn/end",
+  STEP_START: "step/start",
+  STEP_END: "step/end",
+  TOOL: "tool/call",
+};
+
+export class Traces {
+  constructor(dataDir) {
+    this.dir = logsDir(dataDir); // 与 core/trace.js 同一目录 (logs/traces)
+    this.sessionId = shortId("s_", 6);
+    this.count = 0;
+  }
+
+  _file(day = logicalDay()) { return path.join(this.dir, `${day}.jsonl`); }
+
+  // 记录一次工具调用轨迹
+  record({ tool, args, result, ok, durationMs, error }) {
+    const entry = this._entry({ evt: EVT.TOOL, tool, args, result, ok, durationMs, error });
+    fs.appendFileSync(this._file(), JSON.stringify(entry) + "\n", "utf8");
+    return entry;
+  }
+
+  // ---- P0: turn/step 边界事件 (事件源事实) ----
+  recordTurnStart({ sessionId, reason } = {}) {
+    return this._append({ evt: EVT.TURN_START, tsIso: new Date().toISOString(), reason: reason || "user", sessionId: sessionId || this.sessionId });
+  }
+  recordTurnEnd({ ok = true, rounds = 0, reason } = {}) {
+    return this._append({ evt: EVT.TURN_END, ok: !!ok, rounds, reason: reason || null });
+  }
+  recordStepStart({ round = 0, context } = {}) {
+    // context 快照 = 该 step 模型看到的上下文投影摘要 (验证 model-visible = logged)
+    const safe = context ? scrubPII(JSON.stringify(context)).cleaned : null;
+    return this._append({ evt: EVT.STEP_START, round, context: safe ? this._truncate(safe) : null });
+  }
+  recordStepEnd({ round = 0, ok = true, tool = null, error } = {}) {
+    return this._append({ evt: EVT.STEP_END, round, ok: !!ok, tool: tool || null, error: error || null });
+  }
+
+  _append(extra) {
+    this.count += 1;
+    const entry = { ...this._base(), ...extra };
+    fs.appendFileSync(this._file(), JSON.stringify(entry) + "\n", "utf8");
+    return entry;
+  }
+
+  _base() {
+    return { ts: new Date().toISOString(), sessionId: this.sessionId, seq: this.count };
+  }
+
+  _entry({ evt, tool, args, result, ok, durationMs, error }) {
+    const safeArgs = scrubPII(JSON.stringify(args ?? {})).cleaned;
+    const safeResult = scrubPII(String(result ?? "")).cleaned;
+    return {
+      ...this._base(),
+      evt: evt || EVT.TOOL,
+      tool,
+      args: this._truncate(safeArgs),
+      result: this._truncate(safeResult),
+      ok: !!ok,
+      durationMs: Math.round(durationMs || 0),
+      error: error || null,
+    };
+  }
+
+  _truncate(s) {
+    const str = String(s ?? "");
+    return str.length > MAX_TRACE_BODY ? str.slice(0, MAX_TRACE_BODY) + "…" : str;
+  }
+
+  // ---- P0: 事件源不变量断言 (model-visible = logged) ----
+  // 重放校验: 1) 每行可解析  2) turn/step 配对完整 (start 必有 end, 嵌套合法)  3) step round 递增无重复
+  // 返回 { ok, total, errors: [] }。任何不变量破坏 → ok=false + 具体错误行, 供自愈/测试定位。
+  verifyReplay(day = logicalDay()) {
+    const lines = this.readRaw(day);
+    const errors = [];
+    const turnStack = [];
+    const stepRounds = new Set();
+    let total = 0;
+    for (let i = 0; i < lines.length; i++) {
+      let e;
+      try { e = JSON.parse(lines[i]); } catch (err) { errors.push({ line: i + 1, kind: "parse", detail: err.message }); continue; }
+      total++;
+      if (!e || !e.evt) { errors.push({ line: i + 1, kind: "no-evt" }); continue; }
+      if (e.evt === EVT.TURN_START) turnStack.push(i);
+      else if (e.evt === EVT.TURN_END) {
+        if (!turnStack.length) errors.push({ line: i + 1, kind: "turn-end-orphan" });
+        else turnStack.pop();
+      } else if (e.evt === EVT.STEP_START) {
+        const r = Number(e.round);
+        if (stepRounds.has(r)) errors.push({ line: i + 1, kind: "step-round-duplicate", detail: `round=${r}` });
+        stepRounds.add(r);
+      }
+    }
+    if (turnStack.length) errors.push({ kind: "turn-unclosed", detail: `剩余 ${turnStack.length} 个未闭合 turn` });
+    return { ok: errors.length === 0, total, errors };
+  }
+
+  // 读原始行 (verifyReplay 用, 不跳过坏行)
+  readRaw(day = logicalDay()) {
+    const file = this._file(day);
+    if (!fs.existsSync(file)) return [];
+    return fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+  }
+
+  // 读取某天轨迹 (最近 N 条); day 缺省 = 今天
+  read(day, limit = 100) {
+    const file = this._file(day);
+    if (!fs.existsSync(file)) return [];
+    return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-limit)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  }
+
+  // 统计: 失败率/平均耗时/慢工具
+  stats(day) {
+    const all = this.read(day, 10000);
+    if (!all.length) return { count: 0, failed: 0, failRate: "0%", slowTools: [] };
+    const failed = all.filter((t) => !t.ok);
+    const byTool = {};
+    for (const t of all) {
+      (byTool[t.tool] = byTool[t.tool] || { calls: 0, fails: 0, totalMs: 0 });
+      byTool[t.tool].calls++;
+      if (!t.ok) byTool[t.tool].fails++;
+      byTool[t.tool].totalMs += t.durationMs;
+    }
+    const slow = Object.entries(byTool)
+      .map(([tool, v]) => ({ tool, ...v, avgMs: Math.round(v.totalMs / v.calls) }))
+      .sort((a, b) => b.avgMs - a.avgMs).slice(0, 5);
+    return {
+      count: all.length,
+      failed: failed.length,
+      failRate: all.length ? (failed.length / all.length * 100).toFixed(1) + "%" : "0%",
+      slowTools: slow,
+    };
+  }
+}

package/src/utils/wal.js

@@ -0,0 +1,39 @@
+// src/utils/wal.js - 追加式变更日志 (Write-Ahead Log) 轻量实现
+// 用途: 记忆数据的高频增量落盘。每次变更 append 一行事件到 <file>.wal (单行 JSON, 原子追加),
+//       达到阈值或显式 flush 时全量 compact 到主文件 + 清空 WAL。
+// 崩溃安全: 主文件 = 最后一次 flush 快照, WAL = 快照后的增量; 启动时重放 WAL 恢复。
+// 重放幂等: 事件按 id upsert/remove, 重复应用无害 (flush 后崩溃最多重放已落盘变更)。
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "./store.js";
+import { debug } from "../utils/logger.js";
+
+export function walFileOf(file) {
+  return file + ".wal";
+}
+
+// 追加一条事件 (JSON 行)。appendFileSync 单行追加在正常写入下原子; 失败抛错由调用方降级 (内存态仍正确, 下次 flush 补齐)。
+export function appendWal(walFile, evt) {
+  ensureDir(path.dirname(walFile));
+  fs.appendFileSync(walFile, JSON.stringify(evt) + "\n", "utf8");
+}
+
+// 读 WAL: 逐行解析; 尾部半行 (崩溃中断写入) 静默丢弃; 返回事件数组
+export function readWal(walFile) {
+  if (!fs.existsSync(walFile)) return [];
+  let raw;
+  try { raw = fs.readFileSync(walFile, "utf8"); } catch { return []; }
+  if (!raw) return [];
+  const events = [];
+  for (const line of raw.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try { events.push(JSON.parse(t)); } catch { break; } // 半行丢弃, 后面的已不可信
+  }
+  return events;
+}
+
+// 清空 WAL (compact 成功后调用; 与 append 同一锁内执行, 防丢事件)
+export function truncateWal(walFile) {
+  try { fs.rmSync(walFile, { force: true }); } catch (e) { debug(`[utils/wal] 已忽略异常: ${e && e.message ? e.message : e}`); }
+}

package/src/utils/winutf8.js

@@ -1,15 +1,16 @@
-// src/utils/winutf8.js - Windows 控制台 UTF-8 引导：强制 chcp 65001 + stdout/stderr 用 utf8
-// 根治 PowerShell/GBK 控制台把 Node UTF-8 输出解成乱码（鐨尰铏?/鑳藉姏... 那种）
-import { execSync } from "node:child_process";
-
-export function ensureUTF8Console() {
-  if (process.platform !== "win32") return;
-  try {
-    // 改当前控制台活动代码页为 UTF-8（仅当是真实终端时；stdout 非 TTY 时跳过，避免写日志管道报错）
-    if (process.stdout?.isTTY) {
-      execSync("chcp 65001", { stdio: "ignore", windowsHide: true });
-    }
-  } catch { /* 非交互/无控制台，忽略 */ }
-  try { process.stdout.setDefaultEncoding?.("utf8"); } catch {}
-  try { process.stderr.setDefaultEncoding?.("utf8"); } catch {}
-}
+// src/utils/winutf8.js - Windows 控制台 UTF-8 引导：强制 chcp 65001 + stdout/stderr 用 utf8
+// 根治 PowerShell/GBK 控制台把 Node UTF-8 输出解成乱码（鐨尰铏?/鑳藉姏... 那种）
+import { execSync } from "node:child_process";
+import { debug } from "../utils/logger.js";
+
+export function ensureUTF8Console() {
+  if (process.platform !== "win32") return;
+  try {
+    // 改当前控制台活动代码页为 UTF-8（仅当是真实终端时；stdout 非 TTY 时跳过，避免写日志管道报错）
+    if (process.stdout?.isTTY) {
+      execSync("chcp 65001", { stdio: "ignore", windowsHide: true });
+    }
+  } catch { /* 非交互/无控制台，忽略 */ }
+  try { process.stdout.setDefaultEncoding?.("utf8"); } catch (e) { debug(`[utils/winutf8] 已忽略异常: ${e && e.message ? e.message : e}`); }
+  try { process.stderr.setDefaultEncoding?.("utf8"); } catch (e) { debug(`[utils/winutf8] 已忽略异常: ${e && e.message ? e.message : e}`); }
+}

package/src/wiki/index.js

@@ -0,0 +1,170 @@
+// src/wiki/index.js - 代码库 Wiki 生成器 (2026-10-02 吸收 ZCode Wiki 机制)
+// 对齐 ZCode repo-wiki 三要素:
+//   1. 每个结论绑定源码位置 (file:line)
+//   2. Mermaid 架构/依赖图
+//   3. 敏感文件排除 (文件名含 token/secret/credential/password 等一律不读不引)
+// 零依赖, 复用 repomap 的扫描与符号索引 (defRecords 已含 file/line/sig)。
+import fs from "node:fs";
+import path from "node:path";
+import { scanRepo, extractSymbols, DEFAULT_IGNORE } from "../repomap/index.js";
+import { debug } from "../utils/logger.js";
+
+// 敏感文件名模式 (ZCode Wiki 同款语义): 命中即从 wiki 中排除, 不读不引
+export const SENSITIVE_PATTERNS = [
+  /token/i, /secret/i, /credential/i, /password/i, /passwd/i,
+  /api[-_]?key/i, /\.pem$/i, /\.key$/i, /private[-_]?key/i,
+];
+
+export function isSensitiveFile(rel) {
+  return SENSITIVE_PATTERNS.some((p) => p.test(path.basename(rel)));
+}
+
+// 解析一个 js/ts 文件的内部 import 依赖 (相对路径 → 仓库内文件)
+function internalImports(content, rel, root) {
+  const out = [];
+  const re = /(?:from\s+|require\(\s*|import\s*\(\s*)["']([^"']+)["']/g;
+  let m;
+  while ((m = re.exec(content))) {
+    const spec = m[1];
+    if (!spec.startsWith(".")) continue; // 只看相对依赖 (内部模块图)
+    try {
+      let abs = path.resolve(path.dirname(path.join(root, rel)), spec);
+      // 补扩展名 (ESM 无扩展名约定)
+      const tries = ["", ".js", ".mjs", ".cjs", ".ts", "/index.js", "/index.ts"];
+      const hit = tries.map((t) => abs + t).find((p) => {
+        try { return fs.statSync(p).isFile(); } catch { return false; }
+      });
+      if (!hit) continue;
+      const relTo = path.relative(root, hit).split(path.sep).join("/");
+      if (relTo && relTo !== rel && !relTo.startsWith("..")) out.push(relTo);
+    } catch { /* 解析失败跳过 */ }
+  }
+  return [...new Set(out)];
+}
+
+// 生成 wiki 文本
+export function generateWiki(root, opts = {}) {
+  const { topPerFile = 5, maxNodes = 40 } = opts;
+  const scan = scanRepo(root, { ignore: [...DEFAULT_IGNORE, "test", "tests", "__tests__"] });
+
+  // 敏感文件过滤
+  const files = scan.files.filter((f) => !isSensitiveFile(f.rel));
+  const skippedSensitive = scan.files.length - files.length;
+
+  // 文件 → 定义列表 (来自 defRecords: name → [{file,line,sig,kind}])
+  const defsByFile = new Map(); // rel -> [{name, line, sig, kind}]
+  for (const [name, recs] of scan.defRecords) {
+    for (const r of recs) {
+      if (!defsByFile.has(r.file)) defsByFile.set(r.file, []);
+      defsByFile.get(r.file).push({ name, line: r.line, sig: r.sig, kind: r.kind });
+    }
+  }
+
+  // 内部 import 边 (只读非敏感的 js/ts 文件)
+  const edges = new Set();
+  const nodeSet = new Set();
+  for (const f of files) {
+    if (!/\.(js|mjs|cjs|ts)$/.test(f.ext)) continue;
+    let content;
+    try { content = fs.readFileSync(path.join(root, f.rel), "utf8"); } catch { continue; }
+    for (const to of internalImports(content, f.rel, root)) {
+      if (isSensitiveFile(to)) continue; // 敏感文件不进图
+      edges.add(`${f.rel} -> ${to}`);
+      nodeSet.add(f.rel);
+      nodeSet.add(to);
+    }
+  }
+
+  // 渲染
+  const L = [];
+  const short = (p) => p.replace(/^src\//, "s/").replace(/\.(js|mjs|cjs|ts)$/, "").replace(/[^A-Za-z0-9_]/g, "_");
+  L.push(`# ${path.basename(path.resolve(root))} · 代码库 Wiki`);
+  L.push("");
+  L.push(`> 由皮皮虾自动生成 (ZCode repo-wiki 机制对齐)。每个结论绑定源码位置 (file:line); 敏感文件 (token/secret/credential/password 等) 已排除 ${skippedSensitive} 个。`);
+  L.push("");
+  L.push(`**规模**: 文件 ${files.length} · 定义 ${[...defsByFile.values()].reduce((s, d) => s + d.length, 0)} · 内部依赖边 ${edges.size}`);
+  L.push("");
+
+  // 按目录分组, 每文件列 top 定义 (按引用数排序: 用 refCounts)
+  const byDir = new Map();
+  for (const f of files) {
+    const dir = f.dir;
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(f);
+  }
+  for (const dir of [...byDir.keys()].sort()) {
+    L.push(`## ${dir === "." ? "(根目录)" : dir}`);
+    L.push("");
+    for (const f of byDir.get(dir).sort((a, b) => a.rel.localeCompare(b.rel))) {
+      const defs = (defsByFile.get(f.rel) || [])
+        // 噪音过滤 (ZCode wiki 语义: 文档骨架而非全文键值): md 只留一二级标题, json 不进正文
+        .filter((d) => {
+          if (d.kind === ".json") return false;
+          if (d.kind === ".md" && !/^#{1,2} /.test(d.sig || "")) return false;
+          return true;
+        })
+        // 定义类型分级: function/class 是骨架, 裸 const 赋值是噪音 → 降级
+        .map((d) => ({ ...d, tier: /^(export\s+)?(async\s+)?(function|class)\b/.test(d.sig || "") ? 0
+          : /^(export\s+)?(const|let)\s+\w+\s*=\s*(async\s*)?(\(|function|[A-Za-z])/.test(d.sig || "") ? 1 : 2 }))
+        .sort((a, b) => (a.tier - b.tier) || ((scan.refCounts.get(b.name) || 0) - (scan.refCounts.get(a.name) || 0)))
+        .slice(0, topPerFile);
+      if (!defs.length) continue;
+      L.push(`### \`${f.rel}\``);
+      L.push("");
+      for (const d of defs) {
+        L.push(`- \`${d.sig || d.name}\` — ${f.rel}:${d.line}`);
+      }
+      L.push("");
+    }
+  }
+
+  // mermaid 依赖图 (节点数限幅)
+  if (nodeSet.size) {
+    const nodes = [...nodeSet].slice(0, maxNodes);
+    const nset = new Set(nodes);
+    L.push(`## 模块依赖图 (top ${nodes.length})`);
+    L.push("");
+    L.push("```mermaid");
+    L.push("graph LR");
+    for (const e of edges) {
+      const [from, to] = e.split(" -> ");
+      if (nset.has(from) && nset.has(to)) {
+        L.push(`  ${short(from)} --> ${short(to)}`);
+      }
+    }
+    L.push("```");
+    L.push("");
+  }
+
+  return {
+    text: L.join("\n"),
+    stats: {
+      files: files.length,
+      defs: [...defsByFile.values()].reduce((s, d) => s + d.length, 0),
+      edges: edges.size,
+    },
+    sensitiveSkipped: skippedSensitive,
+    // ZCode 语义: 代码变化后 wiki 自动标记陈旧 — stale = 源码里最新的 mtime 晚于 wiki 文件
+    stale: null, // 由调用方填充 (需要 wiki 文件路径对比)
+  };
+}
+
+// 陈旧检测: wikiOutPath 不存在 = 从未生成 (stale); 任一源码文件 mtime 更新 = 陈旧
+// 返回 { stale: boolean, reason }
+export function checkStaleness(wikiOutPath, root) {
+  try {
+    const wikiMtime = fs.statSync(wikiOutPath).mtimeMs;
+    const scan = scanRepo(root, {});
+    let newest = 0;
+    for (const f of scan.files) {
+      try {
+        const m = fs.statSync(path.join(root, f.rel)).mtimeMs;
+        if (m > newest) newest = m;
+      } catch (e) { debug(`[wiki/index] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    }
+    if (newest > wikiMtime) return { stale: true, reason: "源码在 wiki 生成后有变更" };
+    return { stale: false, reason: "wiki 与源码同步" };
+  } catch {
+    return { stale: true, reason: "wiki 尚未生成" };
+  }
+}