@mingmaple/dsh-handover 0.0.0-stage → 0.9.12

package/src/lib/charter.mjs

@@ -0,0 +1,28 @@
+/** Charter（规则正文）访问：只读，不改。 */
+import path from 'node:path';
+import { NL } from './text.mjs';
+
+const FENCE = String.fromCharCode(96, 96, 96);
+export const TITLE_KEY = "运行期省 token（通用约束";
+export const WATER_KEY = "上下文水位自查";
+
+export function charterPath(ws) {
+  return path.join(ws, '_Control_Center', 'rules', 'Workspace_Charter.md');
+}
+
+/**
+ * 从 §8.1.1.4 的 markdown 代码块现取「通用约束条」正文：
+ * 返回 { title, body }，无法获取返回 null。改正文不用改代码。
+ */
+export function canonicalBlock(text) {
+  const i = text.indexOf(FENCE + 'markdown');
+  if (i === -1) return null;
+  const rest = text.slice(i + FENCE.length + 8);
+  const j = rest.indexOf(FENCE);
+  if (j === -1) return null;
+  const lines = rest.slice(0, j).split(NL).map((l) => l.trim()).filter((l) => l !== '');
+  let idx = -1;
+  for (let k = 0; k < lines.length; k++) if (lines[k].indexOf('运行期按') !== -1) { idx = k; break; }
+  if (idx === -1) return null;
+  return { title: lines[idx], body: lines.slice(idx) };
+}

package/src/lib/config.mjs

@@ -0,0 +1,37 @@
+/** dsh-handover 配置：全部可被 profile patch 的 config 覆盖。 */
+export const DEFAULTS = {
+  workspaceRoot: '',            // 留空则从会话 cwd 推导（向上找 _Control_Center 目录）
+  warnRatio: 0.32,
+  handoverRatio: 0.35,
+  hardRatio: 0.85,
+  maxCompactions: 3,
+  autoResume: true,
+  sessionScanHours: 12,
+  handoverPath: '',        // 留空 = 按会话角色解析（全局 records/Global_Handover.md；项目 _Project_Meta/<项目>/Handover.md；杂项 _Misc/tasks/<任务>/Handover.md）。非空则强制该路径（演练用）
+  rolesPath: '',           // 留空 = ~/.dsh/storages/dsh-handover.roles.json
+  // 续跑提示：{n} {max} {handover} {role} 会被替换成真值；{handover} 是本会话自己的交接绝对路径。
+  // 只在助手登记压缩时选 resume=continue（默认）才投递；resume=wait 表示已收尾，不唤醒。
+  resumePrompt: '【dsh-handover 自动续跑·第 {n}/{max} 次压缩】压缩已完成，历史已被摘要替换。第一步：ho_handover(action=read) 取回本会话的交接（{handover}）；然后按 §2「下一步」继续（若 §2 已无待办，向用户一句话收尾并停止）。不要复述交接内容，不要重做已完成的事。完整流程：ho_charter(doc="runtime")。',
+  resumePromptUnknown: '【dsh-handover 自动续跑·第 {n}/{max} 次压缩】压缩已完成，历史已被摘要替换。本会话是普通会话，不参与交接；如需继续，请由全局会话为其指定角色。',
+  compactTimeoutMs: 120000,
+  compactAttempts: 3,
+  waitIdleMs: 180000,      // 等会话空闲的上限（超过就放弃并回告）
+  driftSlack: 3,           // Δ交接容忍轮数（超过即需刷交接）
+  wakeAuthority: 'on',     // 会话守卫硬拦：on / off（off＝连 peer_new 也不拦）
+  directPeer: 'on',        // 会话之间直接 peer_send：on 允许（不经全局转述）；off 退回「只能向全局报告」的旧口径
+  roleGating: 'on',        // 按角色裁剪工具与提示段：on / off（off＝所有会话都看得见全部工具）
+  reuseCheck: true,        // 建新会话前查在任会话水位（低于 warnRatio 拒绝）
+  prepackMinAgeMin: 90,    // 打包前要求会话静止分钟数
+  packFormat: 'auto',      // 归档格式：auto（有 7-Zip 用 7z，否则内置 tar.gz）、7z、tar
+  sevenZipPath: '',        // 留空则自动探测 C:\Program Files\7-Zip\7z.exe
+};
+
+export function resolveConfig(raw) {
+  const out = { ...DEFAULTS };
+  if (raw && typeof raw === "object") {
+    for (const k of Object.keys(DEFAULTS)) {
+      if (raw[k] !== undefined && raw[k] !== null) out[k] = raw[k];
+    }
+  }
+  return out;
+}

package/src/lib/consent.mjs

@@ -0,0 +1,84 @@
+/**
+ * 压缩授权：压缩会丢历史，所以「同意」必须由用户自己产生，AI 不能自己给自己批。
+ *
+ * 做法：唯一的授权入口是设置页上的一次点击（用户在场、只能是用户按），
+ * 授权一次有效 5 分钟、只对指定会话生效；`ho_checkpoint`、全局代排与调度器三处都校验它。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const CONSENT_TTL_MS = 5 * 60 * 1000;
+
+function consentPath() {
+  const home = process.env.USERPROFILE || process.env.HOME || os.homedir();
+  return path.join(home, '.dsh', 'storages', 'dsh-handover.consent.json');
+}
+
+function readAll() {
+  try {
+    const t = fs.readFileSync(consentPath(), 'utf8').replace(/^\uFEFF/, '');
+    const v = JSON.parse(t);
+    return v && typeof v === 'object' ? v : {};
+  } catch { return {}; }
+}
+
+function writeAll(v) {
+  const p = consentPath();
+  try { fs.mkdirSync(path.dirname(p), { recursive: true }); } catch { /* ignore */ }
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(v, null, 2), 'utf8');
+  fs.renameSync(tmp, p);
+}
+
+function stampNow() {
+  const d = new Date(Date.now() + 8 * 3600 * 1000);
+  const p = (n) => String(n).padStart(2, '0');
+  return d.getUTCFullYear() + '-' + p(d.getUTCMonth() + 1) + '-' + p(d.getUTCDate()) + ' ' + p(d.getUTCHours()) + ':' + p(d.getUTCMinutes()) + ' +0800';
+}
+
+/** 用户点了一次「允许该会话压缩一次」。 */
+export function grantConsent(sessionId, note) {
+  const sid = String(sessionId || '');
+  if (!sid) throw new Error('缺少会话 id');
+  const all = readAll();
+  const now = Date.now();
+  all[sid] = { at: now, until: now + CONSENT_TTL_MS, atText: stampNow(), note: String(note || '') };
+  writeAll(all);
+  return { sessionId: sid, until: new Date(all[sid].until).toISOString(), minutes: CONSENT_TTL_MS / 60000, atText: all[sid].atText };
+}
+
+/** 授权是否有效（每次读取时一并清除已过期者）。 */
+export function checkConsent(sessionId) {
+  const sid = String(sessionId || '');
+  if (!sid) return { ok: false, reason: '没有会话 id' };
+  const all = readAll();
+  const hit = all[sid];
+  const now = Date.now();
+  let dirty = false;
+  for (const k of Object.keys(all)) {
+    if (!all[k] || !all[k].until || all[k].until <= now) { delete all[k]; dirty = true; }
+  }
+  if (dirty) { try { writeAll(all); } catch { /* ignore */ } }
+  if (!hit || !hit.until || hit.until <= now) {
+    return { ok: false, reason: '用户还没有在设置页点「允许压缩」' };
+  }
+  return { ok: true, until: hit.until, leftMs: hit.until - now, atText: hit.atText || '' };
+}
+
+export function consumedConsent(sessionId) {
+  const all = readAll();
+  const sid = String(sessionId || '');
+  if (all[sid]) { delete all[sid]; try { writeAll(all); } catch { /* ignore */ } }
+}
+
+export function listConsent() {
+  const all = readAll();
+  const now = Date.now();
+  return Object.keys(all).map((sid) => ({
+    sessionId: sid,
+    leftMs: Math.max(0, (all[sid].until || 0) - now),
+    atText: all[sid].atText || '',
+    note: all[sid].note || '',
+  })).filter((r) => r.leftMs > 0);
+}

package/src/lib/drift.mjs

@@ -0,0 +1,65 @@
+/** 交接漂移（替代 handover_check.mjs）：Δ = 会话当前轮 − 交接写入轮；> slack 即需刷交接。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonDir, pick } from './text.mjs';
+import { projectOf, projCacheDir, isSubagent } from './sessions.mjs';
+import { findLog, decodeLog, turnStarts } from './zstd-log.mjs';
+
+export function computeDrift(opts) {
+  const ws = opts.ws;
+  const slack = opts.slack === undefined ? 3 : opts.slack;
+  const all = opts.all === true;
+  const cacheDir = opts.cacheDir || projCacheDir();
+  const rows = [];
+  const seen = new Map();
+  for (const f of readJsonDir(cacheDir)) {
+    const proj = projectOf(f.data).project;
+    if (!proj || proj === '-' || proj.indexOf('<') !== -1 || proj.indexOf('>') !== -1) continue;
+    if (!fs.existsSync(path.join(ws, 'Projects', proj))) continue;
+    const sid = f.name.replace('.json', '');
+    const turns = Number(pick(f.data, 'record', 'rows', 'sessionStats', 'val', 'turns') || 0);
+    rows.push({ sid, project: proj, turns, mtime: f.mtimeMs, kind: isSubagent(f.data) ? '子会话' : '平级' });
+  }
+  let picked;
+  if (all) picked = rows;
+  else {
+    for (const r of rows) {
+      const cur = seen.get(r.project);
+      if (!cur || r.mtime > cur.mtime) seen.set(r.project, r);
+    }
+    picked = Array.from(seen.values());
+  }
+  const out = [];
+  let fresh = 0, need = 0, unknown = 0;
+  for (const s of picked.slice().sort((a, b) => b.mtime - a.mtime)) {
+    const hand = path.join(ws, '_Project_Meta', s.project, 'Handover.md');
+    let hm = 0;
+    try { hm = fs.statSync(hand).mtimeMs; } catch { /* 没有交接 */ }
+    const log = findLog(s.sid, opts.logsRoot);
+    const recs = log ? decodeLog(log) : null;
+    let handoverTurn = null;
+    if (recs) {
+      for (const t of turnStarts(recs)) if (t.time <= hm) handoverTurn = t.turn;
+      if (handoverTurn === null) handoverTurn = 0;
+    }
+    let verdict = '', delta = null;
+    if (recs) {
+      delta = s.turns - (handoverTurn || 0);
+      verdict = delta <= slack ? '已最新' : '需刷交接';
+    } else {
+      delta = null;
+      verdict = hm && s.mtime <= hm ? '已最新（仅时间戳）' : '需人工确认';
+    }
+    if (verdict === '已最新' || verdict === '已最新（仅时间戳）') fresh++;
+    else if (verdict === '需刷交接') need++;
+    else unknown++;
+    out.push({ project: s.project, kind: s.kind, sid: s.sid, turns: s.turns, handoverTurn, delta, verdict });
+  }
+  return { rows: out, fresh, need, unknown, slack };
+}
+
+export function driftVerdict(res) {
+  return '判定：' + res.fresh + ' 个已最新、' + res.need + ' 个需刷交接' +
+    (res.unknown ? '、' + res.unknown + ' 个需人工确认' : '') +
+    (res.need || res.unknown ? '；先让需刷的会话写交接，再搬' : '；可以直接搬');
+}

package/src/lib/events.mjs

@@ -0,0 +1,89 @@
+/** 会话事件派生：已压缩次数与压缩锁状态。主数据源＝会话日志（eventsOf 在本运行时常常为空），事件数组只作兜底。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { findLog, decodeLog } from './zstd-log.mjs';
+import { projCacheDir } from './sessions.mjs';
+
+/** 取本会话事件数组；无法获取返回 []。 */
+export function eventsOf(exec) {
+  try {
+    const s = exec && exec.agent && exec.agent.session;
+    if (s && Array.isArray(s.events)) return s.events;
+  } catch { /* ignore */ }
+  return [];
+}
+
+/**
+ * 返回 { used, lock }：
+ *   used = compaction/summary 次数（= 已压缩次数）
+ *   lock = 'clean' | 'open'（有未闭合的 compaction/start，且晚于最近一次 session/end-seed）
+ */
+export function countCompactions(events) {
+  let used = 0;
+  let pendingStart = null;
+  let lastEndSeed = -1;
+  for (let i = 0; i < events.length; i++) {
+    const e = events[i];
+    const t = e && e.type;
+    if (t === 'session/end-seed') lastEndSeed = i;
+    else if (t === 'compaction/start') pendingStart = i;
+    else if (t === 'compaction/summary') used++;
+    else if (t === 'compaction/end') pendingStart = null;
+  }
+  const open = pendingStart !== null && pendingStart > lastEndSeed;
+  return { used, lock: open ? 'open' : 'clean' };
+}
+
+// 按 (sid, 日志 size+mtime) 缓存，避免每轮解几 MB 日志。
+const cache = new Map();
+
+/** 从会话日志读压缩状态：{ used, lock, lastSummaryMs, source }。读不到日志时退回事件数组。 */
+export function compactionStateOf(sessionId, exec) {
+  const fromEvents = () => {
+    const c = countCompactions(eventsOf(exec));
+    return { used: c.used, lock: c.lock, lastSummaryMs: null, source: 'events' };
+  };
+  const sid = sessionId ? String(sessionId) : '';
+  if (!sid) return fromEvents();
+  const file = findLog(sid);
+  if (!file) return fromEvents();
+  let st = null;
+  try { st = fs.statSync(file); } catch { return fromEvents(); }
+  const hit = cache.get(sid);
+  if (hit && hit.size === st.size && hit.mtimeMs === st.mtimeMs) return hit.value;
+  let recs = null;
+  try { recs = decodeLog(file); } catch { recs = null; }
+  if (!recs || !recs.length) return fromEvents();
+  const c = countCompactions(recs);
+  let last = null;
+  for (const r of recs) {
+    if (r && r.type === 'compaction/summary' && typeof r.time === 'number') last = last === null ? r.time : Math.max(last, r.time);
+  }
+  const value = { used: c.used, lock: c.lock, lastSummaryMs: last, source: 'log' };
+  cache.set(sid, { size: st.size, mtimeMs: st.mtimeMs, value });
+  return value;
+}
+
+/** 投影缓存里该会话文件的 mtimeMs（判断「压缩刚完成、缓存未刷新」用）。 */
+function projCacheMtimeOf(sessionId) {
+  const sid = sessionId ? String(sessionId) : '';
+  if (!sid) return null;
+  try {
+    const dir = projCacheDir();
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.json')) continue;
+      if (name.replace('.json', '') !== sid) continue;
+      return fs.statSync(path.join(dir, name)).mtimeMs;
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+/** 压缩后读数滞后提示：日志里已有 summary，但投影缓存比它旧 ⇒ 返回一句中文提示，否则空串。 */
+export function stalePressureNote(sessionId) {
+  const st = compactionStateOf(sessionId, null);
+  if (!st.lastSummaryMs) return '';
+  const m = projCacheMtimeOf(sessionId);
+  if (m === null || m >= st.lastSummaryMs) return '';
+  return '（压缩刚完成，投影缓存尚未刷新，水位读数滞后一轮；下一次请求后自动正常）';
+}

package/src/lib/extra-prompt.mjs

@@ -0,0 +1,41 @@
+/**
+ * 用户全局前置提示词：存在本机 ~/.dsh/storages/ 下。
+ * 与插件自身的会话约束无关：仅当用户显式开启且内容非空时注入全部会话；
+ * 关闭或留空时不注册提示段，不占用注入点位，避免与其他提示词插件冲突。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** 与官方 SECTION_ORDERS 对齐：FILE_REFERENCE=900，工具段从 1000 起。 */
+export const EXTRA_PROMPT_ORDER = 950;
+export const EXTRA_PROMPT_SECTION = 'dsh-handover:extra-prompt';
+const EXTRA_PROMPT_MAX = 20000;
+
+function storePath() {
+  return path.join(os.homedir(), '.dsh', 'storages', 'dsh-handover.extra-prompt.json');
+}
+
+/** 返回 { enabled, text }。旧文件只有 text 时，按「内容非空即开启」迁移。 */
+export function readExtraPrompt() {
+  try {
+    const j = JSON.parse(fs.readFileSync(storePath(), 'utf8'));
+    const text = typeof j.text === 'string' ? j.text : '';
+    const enabled = typeof j.enabled === 'boolean' ? j.enabled : text.trim() !== '';
+    return { enabled, text };
+  } catch {
+    return { enabled: false, text: '' };
+  }
+}
+
+/** 保存并返回 { enabled, text }；空内容一律视为关闭。 */
+export function writeExtraPrompt(text, enabled) {
+  const clean = String(text == null ? '' : text).trim();
+  if (clean.length > EXTRA_PROMPT_MAX) throw new Error('全局前置提示词过长（上限 ' + EXTRA_PROMPT_MAX + ' 字符）');
+  const on = enabled !== false && clean.length > 0;
+  const p = storePath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const body = { enabled: on, text: clean, updatedAt: new Date().toISOString() };
+  fs.writeFileSync(p, JSON.stringify(body, null, 2) + '\n', 'utf8');
+  return body;
+}

package/src/lib/facts.mjs

@@ -0,0 +1,70 @@
+/**
+ * 口径单一来源：水位阈值、压缩次数与提示段 token 预算。
+ * 运行期文本一律由本模块渲染；改数值只改 config.mjs 的默认值或本文件的预算表。
+ * 文档与测试引用同一组常量，避免同一事实多处各写一遍。
+ */
+import { DEFAULTS } from './config.mjs';
+
+/** 比例转百分比文本：0.32 → "32%"。 */
+function pctOf(ratio) {
+  const n = Math.round(Number(ratio) * 1000) / 10;
+  return (Number.isInteger(n) ? String(n) : n.toFixed(1)) + '%';
+}
+
+/** 水位与压缩口径：全部由配置推导。 */
+export function watermark(cfg) {
+  const c = cfg || DEFAULTS;
+  const warn = pctOf(c.warnRatio !== undefined ? c.warnRatio : DEFAULTS.warnRatio);
+  const handover = pctOf(c.handoverRatio !== undefined ? c.handoverRatio : DEFAULTS.handoverRatio);
+  const hard = pctOf(c.hardRatio !== undefined ? c.hardRatio : DEFAULTS.hardRatio);
+  const max = c.maxCompactions !== undefined ? c.maxCompactions : DEFAULTS.maxCompactions;
+  return { warn, handover, hard, max, warnValue: Math.round((c.warnRatio !== undefined ? c.warnRatio : DEFAULTS.warnRatio) * 100) };
+}
+
+/** 一句式交接规则（全局与项目提示段共用）。 */
+export function handoverRuleText(cfg) {
+  const w = watermark(cfg);
+  return '水位 ' + w.warn + ' 提醒，' + w.handover + ' 交接线，' + w.hard + ' 硬上限；至多压缩 '
+    + w.max + ' 次，第 ' + (w.max + 1) + ' 次换任。';
+}
+
+/** 设置页使用说明里的紧写形式。 */
+export function compactSummaryText(cfg) {
+  const w = watermark(cfg);
+  return w.warn + ' 提醒、' + w.handover + ' 交接线、' + w.hard + ' 硬上限；同一会话最多压缩 ' + w.max + ' 次';
+}
+
+/** 提示段与工具描述的加权 token 估算：CJK 与全角标点每字符 1 token，其余每 4 字符 1 token。 */
+export function estimateTokens(text) {
+  const s = String(text === null || text === undefined ? '' : text);
+  let wide = 0;
+  let narrow = 0;
+  for (const ch of s) {
+    const cp = ch.codePointAt(0);
+    if (isWide(cp)) wide += 1;
+    else narrow += 1;
+  }
+  return wide + Math.ceil(narrow / 4);
+}
+
+function isWide(cp) {
+  return (cp >= 0x2000 && cp <= 0x206f)   // 通用标点（破折号、省略号、弯引号）
+    || (cp >= 0x3000 && cp <= 0x303f)     // CJK 标点
+    || (cp >= 0x2e80 && cp <= 0x9fff)     // CJK 部首至统一汉字
+    || (cp >= 0xf900 && cp <= 0xfaff)     // 兼容汉字
+    || (cp >= 0xfe30 && cp <= 0xfe4f)     // CJK 兼容形式
+    || (cp >= 0xff00 && cp <= 0xffef);    // 全角字符
+}
+
+/**
+ * 上下文成本上限（加权 token）。
+ * 全局段按短工作区路径计；worst 档按真实长路径加迁移提示行计。
+ * 单条工具描述单独设限，避免每次请求的固定开销无界增长。
+ */
+export const TOKEN_BUDGET = {
+  globalTokens: 320,
+  globalWorstTokens: 360,
+  projectTokens: 300,
+  projectWorstTokens: 340,
+  toolDescTokens: 70,
+};

package/src/lib/gates.mjs

@@ -0,0 +1,148 @@
+/** 闸门：通用约束条同步复核与交接文档体检。 */
+import path from 'node:path';
+import { readUtf8, isFile, isDir } from './text.mjs';
+import fs from 'node:fs';
+import { charterPath, canonicalBlock, TITLE_KEY, WATER_KEY } from './charter.mjs';
+import { readProfile, listProfiles } from './profile.mjs';
+
+/**
+ * 读 Registry.md 的「形态」列 → { 项目名: 形态 }。
+ * 口径（Charter §1.6、§2.5）：只有 library 才受通用约束条闸门管；artifact、shortcut、product 属工程型，豁免。
+ * 缺该列或读不到 → 全部按 library 处理（向后兼容）。
+ */
+function registryForms(ws) {
+  const p = path.join(ws, '_Project_Meta', 'Registry.md');
+  if (!isFile(p)) return {};
+  let text = '';
+  try { text = readUtf8(p); } catch { return {}; }
+  const out = {};
+  let head = null;
+  for (const raw of text.split(/\r?\n/)) {
+    const s = raw.trim();
+    if (!s.startsWith('|')) continue;
+    const cells = s.replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+    if (!head) {
+      if (cells.indexOf('项目名') !== -1) head = cells;
+      continue;
+    }
+    if (head.indexOf('形态') === -1) return {};
+    if (cells.every((c) => /^[-:\s]*$/.test(c))) continue;
+    const iName = head.indexOf('项目名');
+    const iForm = head.indexOf('形态');
+    if (cells.length <= Math.max(iName, iForm)) continue;
+    out[cells[iName]] = cells[iForm].replace(/`/g, '').trim();
+  }
+  return out;
+}
+
+/** 工作区下所有「库型」项目库（带 RULES.md）：返回 [{ name, root }]；工程型按形态跳过。 */
+function libraryRoots(ws) {
+  const forms = registryForms(ws);
+  const projDir = path.join(ws, 'Projects');
+  const out = [];
+  let projects = [];
+  try { projects = fs.readdirSync(projDir); } catch { return out; }
+  for (const name of projects) {
+    const pdir = path.join(projDir, name);
+    if (!isDir(pdir)) continue;
+    const form = forms[name] || 'library';
+    if (form !== 'library') continue;
+    // 骨架档案可让项目决定是否启用 24 行约束条；未注册时按默认（启用）处理。
+    const pf = readProfile(ws, { role: 'project', project: name });
+    if (pf.exists && pf.profile.gate && pf.profile.gate.libraryBlock === false) continue;
+    let libs = [];
+    try { libs = fs.readdirSync(pdir); } catch { continue; }
+    for (const lib of libs) {
+      const root = path.join(pdir, lib);
+      if (!isDir(root)) continue;
+      if (isFile(path.join(root, 'RULES.md'))) out.push({ name, root });
+    }
+  }
+  return out;
+}
+
+/** 同步复核：返回 { libraries, total, missing, verdict, ok }。 */
+/** 插件内置的 Charter 骨架（dist/templates/Charter.skeleton.md）；工作区那份只是覆盖。 */
+function bundledCharter() {
+  try {
+    const p = new URL('../templates/Charter.skeleton.md', import.meta.url);
+    return fs.readFileSync(p, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+export function syncCheck(ws) {
+  const charter = charterPath(ws);
+  // 口径：**插件自带的这套默认规则才是本体**，工作区里的同名文件是「本地化覆盖」。
+  // 所以只有「连 _Control_Center 都没有」才算没接入工作区；有目录但没 Charter 时用内置那份继续跑。
+  const hasCenter = isDir(path.join(ws, '_Control_Center'));
+  let text = '';
+  let builtin = false;
+  if (isFile(charter)) {
+    text = readUtf8(charter);
+  } else if (hasCenter) {
+    text = bundledCharter();
+    builtin = true;
+  } else {
+    return {
+      error: '这个实例还没接入工作区：读不到 ' + charter,
+      path: charter,
+      ok: false,
+      noWorkspace: true,
+    };
+  }
+  const blk = canonicalBlock(text);
+  if (!blk || !blk.body || blk.body.length === 0) {
+    return { error: '无法获取 §8.1.1.4 的正文（结构可能变了）', path: charter, ok: false };
+  }
+  const rows = [];
+  let bad = 0;
+  for (const lib of libraryRoots(ws)) {
+    const rules = readUtf8(path.join(lib.root, 'RULES.md'));
+    const missing = blk.body.filter((l) => rules.indexOf(l) === -1);
+    const titleOk = rules.indexOf(TITLE_KEY) !== -1;
+    const waterOk = rules.indexOf(WATER_KEY) !== -1;
+    const ok = titleOk && missing.length === 0 && waterOk;
+    if (!ok) bad++;
+    rows.push({ name: lib.name, titleOk, waterOk, missing, total: blk.body.length, ok });
+  }
+  return {
+    libraries: rows,
+    profiles: listProfiles(ws),
+    total: rows.length,
+    bodyLines: blk.body.length,
+    builtin,
+    missing: bad,
+    ok: bad === 0,
+    verdict: bad === 0
+
+      ? "全部落位。"
+      : bad + ' 个库有缺 —— 向对应项目会话派发（由它自己写进本库 RULES.md，全局不得改项目库内文件）。',
+  };
+}
+
+export function renderSyncCheck(res) {
+  const out = [];
+  if (res.error) { out.push(res.error + '：' + res.path); return out; }
+  out.push('通用约束条同步复核  库数 ' + res.total + '  正文 ' + res.bodyLines + ' 行  来源 §8.1.1.4' + (res.builtin ? '（工作区没有 Workspace_Charter.md，用插件内置口径）' : ''));
+  for (const r of res.libraries) {
+    const flag = r.ok ? '通过' : '未通过';
+    out.push('  ' + r.name + '  标题 ' + (r.titleOk ? '通过' : '缺') + '  正文 ' + (r.total - r.missing.length) + '/' + r.total +
+      '  水位自查 ' + (r.waterOk ? '通过' : '缺') + '  ' + flag);
+    for (const m of r.missing.slice(0, 3)) out.push("        缺: " + m.slice(0, 70));
+  }
+  const ps = res.profiles || [];
+  if (ps.length) {
+    out.push('');
+    out.push('项目与杂项骨架');
+    for (const p of ps) {
+      const flag = p.exists ? (p.ok ? '通过' : '未通过') : '待注册';
+      const miss = p.missing && p.missing.length ? '  缺 ' + p.missing.join('、') : '';
+      out.push('  ' + p.name + '  ' + flag + '  类别 ' + p.kind + miss);
+    }
+  }
+  out.push('');
+  out.push('判定：' + res.verdict);
+  return out;
+}