@mingmaple/dsh-handover 0.0.0-stage → 0.9.6

package/src/lib/config.mjs

@@ -0,0 +1,36 @@
+/** 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,
+  libraries: [],
+  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} 是本会话自己的交接绝对路径。
+  resumePrompt: '【dsh-handover 自动续跑·第 {n}/{max} 次压缩】压缩已完成，历史已被摘要替换。第一步：ho_handover(action=read) 取回本会话的交接（{handover}）；然后按 §2「下一步」继续。不要复述交接内容，不要重做已完成的事。完整流程：ho_charter(doc="runtime")。',
+  resumePromptUnknown: '【dsh-handover 自动续跑·第 {n}/{max} 次压缩】压缩已完成，历史已被摘要替换。本会话是普通会话，不参与交接；如需继续，请由全局会话为其指定角色。',
+  compactTimeoutMs: 120000,
+  compactAttempts: 3,
+  waitIdleMs: 180000,      // 等会话空闲的上限（超过就放弃并回告）
+  driftSlack: 3,           // Δ交接容忍轮数（超过即需刷交接）
+  wakeAuthority: 'on',     // 唤醒权硬拦：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;
+}

package/src/lib/guide.mjs

@@ -0,0 +1,99 @@
+/**
+ * 设置页「使用说明」的内容：面向人，不面向模型。
+ * 数据放宿主侧，客户端只负责渲染——改文案不用动客户端 bundle。
+ * 行文用标准书面语：不用口语化的示例句，示例一律写成可以直接提的要求。
+ * 水位与工具数由 facts.mjs、names.mjs 推导，不在这里重复写死。
+ */
+import { compactSummaryText, watermark } from './facts.mjs';
+import { ALL_TOOL_NAMES } from './names.mjs';
+
+/** 首次安装、尚未接入工作区时的下一步（设置页与工具输出共用同一份）。 */
+export const SETUP_STEPS = [
+  '准备一个长期存在的目录作为工作区的上级目录，不要选临时目录或下载目录。',
+  '在本页下方的输入框中粘贴该目录的绝对路径，点击「建立全局文件体系」：插件会在其中创建 _Workspace 目录，并铺好 _Control_Center、Projects 等整套结构。',
+  '点击「注册为工作区」完成注册；也可以把页面上显示的绝对路径复制下来，粘贴到 DSH 的新建工作区窗口。',
+  '新建一个标题含「全局」的会话。下一轮起，本插件会把该目录接入闸门、交接体检与会话水位三项。',
+];
+
+export function buildGuide(cfg) {
+  const w = watermark(cfg);
+  const compact = compactSummaryText(cfg);
+  const toolCount = ALL_TOOL_NAMES.length;
+  return {
+  intro: [
+    '本插件的全部功能都在对话中调用：不必记命令，也不必操作菜单，用中文说明要做的事，全局会话会选择相应的工具执行。',
+    '工具与提示按会话角色载入：全局会话可见全部 ' + toolCount + ' 个工具，项目与杂项会话只载入自己需要的几个，普通会话不载入插件工具，也不注入提示段。角色在下方「会话角色」中指定。',
+    '本页除首次安装、全局前置提示词与会话角色外均为只读；需要最新读数时，点击右上角的「刷新」。',
+  ],
+  situations: [
+    { when: '作业开始与结束', say: '先出一份起始简报', what: '汇总上下文水位、通用约束条闸门、会话清点与阶段建议（ho_brief）' },
+    { when: '查阅规则', say: '把 Charter 第 7.2.3 节取出来', what: '按节返回规则正文，避免整篇读取（ho_charter；完整流程用 doc="runtime"）' },
+    { when: '交接与压缩续跑', say: '先把交接文档写好，再压缩并继续', what: '写自己角色的交接、体检、登记压缩，回合结束后自动压缩并自动续跑（ho_handover、ho_checkpoint）' },
+    { when: '接近上下文上限', say: '查一下本会话的上下文水位', what: compact + '（ho_phase）' },
+    { when: '换任', say: '建立下一代全局会话', what: '建会话、唤醒并投递启动提示词；在任会话水位低于 ' + w.warn + ' 时拒绝新建（ho_sessions action=new）' },
+    { when: '会话角色', say: '把 Demo1 设成项目角色，并让它整理自己的文件', what: '写角色表、当场收窄该会话的工具与提示、投递一次性整理指令（ho_sessions action=role / 本页会话角色）' },
+    { when: '通知项目会话', say: '通知 Demo 更新交接文档', what: '投递一条消息；会消耗目标会话一整轮 token，应尽量少用（peer_send）' },
+    { when: '全局前置提示词', say: '把这段设为全局前置提示词', what: '保存到本机；仅在你开启且内容非空时注入全部会话，关闭或留空时不注册提示段' },
+    { when: '项目骨架', say: '注册 Demo 的骨架', what: '读取、注册、校验项目或杂项的骨架档案；由该项目会话自己写文件并注册（ho_profile）' },
+    { when: '查看会话', say: '列出当前活跃的会话', what: '水位、运行状态、活跃或沉默、在任或前任（ho_sessions）' },
+    { when: '打包迁移', say: '把 Demo 打包成迁移包', what: '收集文件、逐文件 sha256、7z、自检、绝对路径体检（ho_pack action=pack）' },
+    { when: '在新机器恢复', say: '预演这次恢复', what: '校验、列出覆盖清单、备份、写入；默认仅预演（ho_pack action=restore）' },
+    { when: '删除会话', say: '把这个会话归档', what: '官方仅提供归档；需要再次唤醒时须先解归档（ho_sessions action=archive、unarchive）' },
+    { when: '建立工作区', say: '把这个目录注册为工作区', what: '注册已存在的目录；删除只删注册，目录与会话日志均保留（ho_workspace）' },
+    { when: '首次安装', say: '把某个目录建成全局根目录', what: '在该目录下建立整套全局文件体系，并注册为工作区（ho_init）' },
+    { when: '自检', say: '检查插件当前状态', what: '服务可解析性、压缩调度器、压缩计数、本会话角色与工具集（ho_diag）' },
+  ],
+  groups: [
+    {
+      title: '只读工具（不消耗任何会话的 token）',
+      tools: [
+        ['ho_brief', '起始与收束的单条命令：水位、闸门、会话清点与阶段建议'],
+        ['ho_gate', '通用约束条闸门（按库型判定）与交接文档体检'],
+        ['ho_sessions', '会话清点；也用于设定角色、建会话、出提示词、归档'],
+        ['ho_phase', '本会话阶段：水位、已压缩次数、锁状态、建议动作'],
+        ['ho_charter', '按节返回规则正文；doc="runtime" 取完整流程手册'],
+        ['ho_drift', '交接漂移体检：Δ 为当前轮与交接轮之差，大于 3 需刷新'],
+        ['ho_diag', '插件自检：服务、调度器、压缩计数、角色判定与工具集'],
+        ['ho_tokens', '会话 token 体检：轮数、步数、每步 token、最贵的单条返回'],
+      ],
+    },
+    {
+      title: '写工具（会改动文件；均带备份或预演）',
+      tools: [
+        ['ho_handover', '读写、追加、归档本会话自己的交接（写前备份、写后按角色体检）'],
+        ['ho_checkpoint', '写交接、登记压缩，回合结束后自动压缩并自动续跑'],
+        ['ho_snapshot', '库快照：逐字节复制、sha256 清单、来源说明'],
+        ['ho_changelog', '按固定表格追加一行台账'],
+        ['ho_pack', 'action：check 前置闸门、pack 打包、verify 校验、restore 恢复（默认预演）'],
+        ['ho_workspace', '工作区列表、创建、删除；删除只删注册'],
+        ['ho_init', '首次安装：在指定目录下建立整套全局文件体系，可顺带注册工作区'],
+        ['ho_profile', '项目或杂项骨架：读取、注册、校验、取预设'],
+      ],
+    },
+    {
+      title: '平级会话工具',
+      tools: [
+        ['peer_list', '会话清点，只读投影缓存，不激活任何会话'],
+        ['peer_status', '单会话详情：水位、运行状态、轮数、步数、工作目录'],
+        ['peer_send', '向指定会话投递一条消息，是唯一会消耗对方 token 的动作'],
+        ['peer_new', '新建平级会话，可指定工作区与标题'],
+        ['peer_rename', '只改显示标题，不唤醒目标会话'],
+        ['peer_peek', '查看指定会话近期的对话，会消耗本会话 token'],
+      ],
+    },
+  ],
+  rules: [
+    '交接线：上下文水位达到 ' + w.warn + ' 时提醒，达到 ' + w.handover + ' 时写交接并压缩，' + w.hard + ' 为硬上限；同一会话最多压缩 ' + w.max + ' 次，第四段改用新建会话。',
+    '压缩不可逆：历史会被摘要替换，因此必须先写出合格的交接文档；体检未通过时，插件拒绝安排压缩。',
+    '交接文件按角色分离：全局写 _Control_Center/records/Global_Handover.md，项目写 _Project_Meta/<项目>/Handover.md，杂项写 _Misc/tasks/<任务>/Handover.md，互不串用。',
+    '会话本身不迁移：跨机器、跨平台的连续性依托交接文档。',
+    '全局前置提示词属于用户内容，不是插件约束；关闭或留空时不占用注入点位，可与其它提示词插件并存。',
+    '项目与杂项的骨架由各自会话注册；构建型、动画型等项目不必套用插件类项目的文档集。',
+    '迁移只搬运文件与清单，不改写文件内容：包内写死的绝对路径会以清单形式报出，由用户或项目会话自行修改；库内引用一律使用相对路径。',
+    '插件本体为公开件，不含任何用户项目、会话或账号数据；用户数据与角色表都保存在本机。',
+  ],
+  };
+}
+
+/** 默认配置下的说明文本；设置页按实际配置调用 buildGuide。 */
+const GUIDE = buildGuide();