@mingmaple/dsh-handover 0.9.14 → 0.9.22

package/src/tools/ho_docmap.mjs

@@ -0,0 +1,153 @@
+/**
+ * ho_docmap —— 本会话的文档定位 map（只指路，不规定读多少）。
+ *
+ * 写入范围由会话已登记的角色决定，不接受传入项目名或任务名：全局只写 global.md，
+ * 项目只写 project-<本项目>.md，杂项只写 misc-<本任务>.md。
+ * 写入者必须是在任会话（以 Office.json 为准）；已交出的旧会话只读。
+ * 不设字数上限；写盘前逐条校验路径存在，缺项整条拒绝并列出。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL } from '../lib/text.mjs';
+import { loadOffice, lineageKeyOf } from '../lib/office.mjs';
+import {
+  lineageOf, lineageLabel, docmapRelPath, docmapAbsPath, readDocmap,
+  renderDocmap, validateEntries,
+} from '../lib/docmap.mjs';
+
+export const ACTIONS = ['read', 'write', 'check'];
+
+function ownLineage(env, exec) {
+  let info = null;
+  try { info = env.roleOf(exec); } catch { info = null; }
+  const lin = lineageOf(info);
+  return { info, lin };
+}
+
+function holderOf(ws, lin) {
+  try {
+    const store = loadOffice(ws);
+    const key = lineageKeyOf(lin.kind, lin.project, lin.task);
+    const row = store.lineages ? store.lineages[key] : null;
+    return { key, current: row && row.current ? row.current : null };
+  } catch {
+    return { key: '', current: null };
+  }
+}
+
+function entriesText(entries) {
+  if (!entries.length) return '（空 map：不注入提示段）';
+  return entries.map((e) => '- ' + e.path + (e.about ? ' —— ' + e.about : '') + (e.when ? '（' + e.when + '）' : '')).join(NL);
+}
+
+export function pmDocmapTool(env) {
+  return {
+    name: nameOf('docmap'),
+    description:
+      '本会话的文档定位：action=read 读、write 写（逐条校验路径存在）、check 查自己的 map；只指路，不规定读多少。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ACTIONS, description: '缺省 read' },
+        entries: {
+          type: 'array',
+          description: 'write：整份替换。每项 { path: 工作区相对路径, about: 一句话介绍, when: 何时读 }',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['path', 'about'],
+            properties: {
+              path: { type: 'string', description: '工作区相对路径，必须存在' },
+              about: { type: 'string', description: '一句话介绍' },
+              when: { type: 'string', description: '什么时候该读（可选，建议写）' },
+            },
+          },
+        },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const ws = env.resolveWs(exec);
+      const { info, lin } = ownLineage(env, exec);
+      if (!lin) throw new Error('本会话没有角色：文档定位只对全局、项目、杂项会话开放');
+      const action = typeof args.action === 'string' && args.action ? args.action : 'read';
+      if (ACTIONS.indexOf(action) === -1) throw new Error('action 只能是 ' + ACTIONS.join(' | ') + '（收到 ' + String(action) + '）');
+      const rel = docmapRelPath(info);
+      const abs = docmapAbsPath(ws, info);
+      const label = lineageLabel(info);
+
+      if (action === 'read') {
+        const map = readDocmap(ws, info);
+        const out = [];
+        out.push('文档定位（' + label + '）  ' + rel);
+        out.push(map.exists ? '状态  已设置，' + map.entries.length + ' 条' : '状态  未设置（空 map 不注入提示段）');
+        if (map.entries.length) out.push('', entriesText(map.entries));
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'check') {
+        const map = readDocmap(ws, info);
+        const bad = validateEntries(ws, map.entries);
+        const out = [];
+        out.push('文档定位体检（' + label + '）  ' + rel);
+        out.push(map.exists ? '条目 ' + map.entries.length + ' 条' : '未设置（空 map 不注入）');
+        for (const b of bad) out.push('  失效：' + b.path + ' —— ' + b.problem);
+        out.push(bad.length ? '判定：' + bad.length + ' 条失效，请更新 map。' : '判定：路径全部存在。');
+        return { text: out.join(NL) };
+      }
+
+      // action=write
+      const holder = holderOf(ws, lin);
+      const meId = String(env.selfId(exec) || '');
+      if (!holder.current) {
+        throw new Error('登记表里没有「' + (holder.key || label) + '」的在任记录：以在任记录为写入依据，先由全局完成登记');
+      }
+      if (!meId || String(holder.current.sessionId || '') !== meId) {
+        throw new Error('只有在任会话可以写：本条登记的在任会话为 ' + (holder.current.name || '?') + '（' + holder.current.sessionId + '），本会话为只读');
+      }
+      const list = Array.isArray(args.entries) ? args.entries : null;
+      if (!list) throw new Error('write 需要 entries 数组（每项 path、about、when）');
+      const entries = [];
+      for (const raw of list) {
+        const e = raw || {};
+        const p = String(e.path === undefined || e.path === null ? '' : e.path).trim();
+        const about = String(e.about === undefined || e.about === null ? '' : e.about).trim();
+        const when = String(e.when === undefined || e.when === null ? '' : e.when).trim();
+        if (!p) throw new Error('entries 里有空路径');
+        for (const [field, val] of [['path', p], ['about', about], ['when', when]]) {
+          if (val.indexOf('|') !== -1) throw new Error(field + ' 里不能出现竖线「|」（表格分隔符）：' + val);
+          if (val.indexOf(String.fromCharCode(10)) !== -1) throw new Error(field + ' 里不能换行');
+        }
+        entries.push({ path: p, about, when });
+      }
+      const bad = validateEntries(ws, entries);
+      if (bad.length) {
+        const lines = ['未写入：下列路径不存在或不合法，逐条修正后重试。'];
+        for (const b of bad) lines.push('  - ' + b.path + '：' + b.problem);
+        lines.push('路径一律写工作区相对路径（例：Projects/<项目>/SKILL.md）。');
+        throw new Error(lines.join(NL));
+      }
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      let backup = '';
+      if (fs.existsSync(abs)) {
+        backup = abs + '.bak';
+        try { fs.copyFileSync(abs, backup); } catch { backup = ''; }
+      }
+      const body = renderDocmap(info, entries);
+      const tmp = abs + '.tmp-' + process.pid;
+      fs.writeFileSync(tmp, body, 'utf8');
+      fs.renameSync(tmp, abs);
+      let refreshed = false;
+      try { if (typeof env.refreshPromptFor === 'function') refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+      const out = [];
+      out.push('已写入 ' + rel + '（' + entries.length + ' 条）' + (backup ? '；原文件备份为 ' + path.basename(backup) : ''));
+      out.push(refreshed ? '提示段已重装：下一轮即按新 map 注入。' : '提示段未能在本进程重装：重启 DSH 或让会话重建后生效。');
+      out.push('建议精炼：每条一句介绍、一句时机即可；不设字数上限，但太长的介绍会挤占提示段。');
+      if (!entries.length) out.push('空 map：不注入提示段（相当于撤销）。');
+      return { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_gate.mjs

@@ -4,7 +4,7 @@ import { nameOf } from '../lib/names.mjs';
 import fs from 'node:fs';
 import { textOutput } from '../lib/output.mjs';
 import { NL } from '../lib/text.mjs';
-import { syncCheck, renderSyncCheck } from '../lib/gates.mjs';
+import { syncCheck, renderSyncCheck, docmapReport, renderDocmapCheck } from '../lib/gates.mjs';
 import { lintGlobal, lintProject, renderLintGlobal, renderLintProject } from '../lib/lint.mjs';
 import { SETUP_STEPS } from '../lib/guide.mjs';
 
@@ -53,6 +53,7 @@ export function pmGateTool(env) {
         }
         out.push(renderSyncCheck(g).join(NL));
         out.push(renderLintProject(null, lintAllProjects(ws)).join(NL));
+        out.push(renderDocmapCheck(docmapReport(ws)).join(NL));
       } else if (scope === "project") {
         const name = args.project;
         if (!name) throw new Error("scope=project 时必须给 project 参数");

package/src/tools/ho_office.mjs

@@ -13,7 +13,7 @@ export function pmOfficeTool(env) {
       type: 'object',
       additionalProperties: false,
       properties: {
-        query: { type: 'string', description: '要查的名字，如「全局」「全局3」「Mingent」「抢名额脚本」；多个用空格或逗号分隔；留空＝列出全部在任' },
+        query: { type: 'string', description: '要查的名字，如「全局」「全局3」「Demo1」「示例任务」；多个用空格或逗号分隔；留空＝列出全部在任' },
         json: { type: 'boolean', description: 'true 时输出机器可读 JSON（供脚本解析）' },
       },
     },

package/src/tools/ho_sessions.mjs

@@ -2,7 +2,6 @@
 import { textOutput } from '../lib/output.mjs';
 import { nameOf } from '../lib/names.mjs';
 import { NL } from '../lib/text.mjs';
-import path from 'node:path';
 import { scanSessions } from '../lib/sessions.mjs';
 import { syncCheck } from '../lib/gates.mjs';
 import { stamp } from '../lib/brief.mjs';
@@ -37,9 +36,9 @@ function list(env, args, exec) {
   }
   const notifProjects = new Set(scan.notify.map((r) => r.project));
   const skipProjects = new Set(scan.skip.map((r) => r.project));
-  out.push("通知判定：活跃项目 " + notifProjects.size + " 个，需要通知 " + scan.notify.length + " 个会话（仅各项目在任）/ 沉默项目 " + skipProjects.size + " 个，跳过 " + scan.skip.length + " 个会话（沉默项目全部＋前任）");
+  out.push("通知判定：活跃项目 " + notifProjects.size + " 个，需要通知 " + scan.notify.length + " 个会话（仅各项目在任）/ 沉默项目 " + skipProjects.size + " 个，跳过 " + scan.skip.length + " 个会话（沉默项目全部＋已交出的旧会话）");
   for (const r of scan.notify) out.push("  要通知【在任】" + r.project + "(" + r.sid + ")  最后活动 " + stamp(r.mtime));
-  if (scan.skip.length) out.push("  跳过（沉默项目，含其前任）：" + scan.skip.map((x) => x.project + "(" + x.sid.slice(-8) + ")").join("、"));
+  if (scan.skip.length) out.push("  跳过（沉默项目，含其已交出的旧会话）：" + scan.skip.map((x) => x.project + "(" + x.sid.slice(-8) + ")").join("、"));
   const gate = syncCheck(env.resolveWs(exec));
   if (gate.error) out.push("通用约束条闸门（Charter §7.2.3）：读不到 §8.1.1.4 正文 —— 请人工核 " + gate.path);
   else if (!gate.ok) {
@@ -85,7 +84,7 @@ export function pmSessionsTool(env) {
         sessionId: { type: 'string', description: 'prompt：新会话自己的 id' },
         globalSessionId: { type: 'string', description: 'prompt：现任全局 id' },
         extra: { type: 'string', description: 'prompt 附加一句；order 时作为「全局附加」拼进指令' },
-        confirm: { type: 'boolean', description: 'new、order 需要用户明确同意后传 true；否则只报错、不做任何事' },
+        confirm: { type: 'boolean', description: 'new、order 需要当前用户明确同意后传 true；否则只报错、不做任何事' },
       },
     },
     output: textOutput(),

package/src/tools/ho_status.mjs

@@ -0,0 +1,246 @@
+/**
+ * ho_status —— 会话状态：一个入口，按 view 分流。
+ *   phase（默认）：水位、压缩次数、锁、建议动作
+ *   brief：水位、闸门、会话清点、交接漂移、阶段建议
+ *   diag：服务可解析性、调度器、初始化错误、角色与工具集
+ *   drift：交接漂移体检
+ *   tokens：按会话 id 统计轮数、步数、每步 token
+ * 全部只读；原 ho_phase、ho_brief、ho_diag、ho_drift、ho_tokens 合并于此。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL, pick } from '../lib/text.mjs';
+import { syncCheck } from '../lib/gates.mjs';
+import { scanSessions, readSelfPressure } from '../lib/sessions.mjs';
+import { composeBrief } from '../lib/brief.mjs';
+import { decide } from '../lib/phase.mjs';
+import { computeDrift, driftVerdict } from '../lib/drift.mjs';
+import { watermark } from '../lib/facts.mjs';
+import { eventsOf, countCompactions } from '../lib/events.mjs';
+import { findLog, decodeLog, turnStarts } from '../lib/zstd-log.mjs';
+import { activeConsentsFor, formatConsentLine } from '../lib/consent.mjs';
+
+export const VIEWS = ['phase', 'brief', 'diag', 'drift', 'tokens'];
+
+function analyzeLog(records) {
+  const turns = turnStarts(records).length;
+  let steps = 0, outTok = 0, maxResult = 0, toolResults = 0;
+  const perTurn = new Map();
+  for (const r of records) {
+    if (!r || !r.type) continue;
+    if (r.type === 'step/start') {
+      steps++;
+      const t = pick(r, 'data', 'turn');
+      if (typeof t === 'number') perTurn.set(t, (perTurn.get(t) || 0) + 1);
+    } else if (r.type === 'assistant/message') {
+      const u = pick(r, 'data', 'usage');
+      if (u && typeof u.outputTokens === 'number') outTok += u.outputTokens;
+    } else if (r.type === 'tool/result') {
+      toolResults++;
+      try { const len = JSON.stringify(pick(r, 'data') || '').length; if (len > maxResult) maxResult = len; } catch { /* ignore */ }
+    }
+  }
+  const heavyTurns = Array.from(perTurn.values()).filter((n) => n > 20).length;
+  return { turns, steps, outTok, maxResult, toolResults, heavyTurns, perStep: steps ? Math.round(outTok / steps) : 0 };
+}
+
+/** 授权状态行：压缩与换任各一句，未授权写「无授权」。 */
+function consentLine(meId) {
+  try { return formatConsentLine(activeConsentsFor(meId)); } catch { return ''; }
+}
+
+function phaseText(env, args, exec) {
+  const meId = env.selfId(exec);
+  const real = env.selfPct(meId);
+  const ratio = typeof args.simulateRatio === 'number' ? args.simulateRatio : (real === null ? null : real / 100);
+  const count = env.compactionCount(exec);
+  const lock = env.lockState(exec);
+  const adv = decide({ ratio, compactionsUsed: count.used, cfg: env.cfg, lockState: lock });
+  const out = [];
+  out.push('会话      ' + (meId || '未知'));
+  out.push('水位      ' + (ratio === null ? '读不到' : (Math.round(ratio * 1000) / 10).toFixed(1) + '%')
+    + (typeof args.simulateRatio === 'number' ? '  （演练模拟值）' : '')
+    + (typeof env.staleNote === 'function' ? env.staleNote(exec) : ''));
+  out.push('压缩      ' + count.used + '/' + env.cfg.maxCompactions + ' 次' + (count.note ? '  ' + count.note : ''));
+  out.push('锁        ' + lock);
+  out.push('建议      ' + adv.action + ' —— ' + adv.reason);
+  const c = consentLine(meId);
+  if (c) out.push('授权      ' + c);
+  return out;
+}
+
+function briefText(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const w = watermark(env.cfg);
+  const warn = typeof args.threshold === 'number' ? args.threshold : w.warnValue;
+  const gate = syncCheck(ws);
+  const meId = env.selfId(exec);
+  const self = readSelfPressure(env.cacheDir(), meId);
+  const scan = scanSessions({
+    dir: env.cacheDir(),
+    meId,
+    meCwd: env.selfCwd(exec),
+    warn,
+    silentHours: env.cfg.sessionScanHours,
+  });
+  const drift = computeDrift({ ws, cacheDir: env.cacheDir(), slack: env.cfg.driftSlack, all: false });
+  const ratio = self.used === null || self.win === null ? null : self.used / self.win;
+  const adv = decide({ ratio, compactionsUsed: 0, cfg: env.cfg, lockState: 'unknown' });
+  const selfPct = self.used === null || self.win === null ? null : (self.used / self.win) * 100;
+  const ok = gate.ok && (selfPct === null || selfPct < warn);
+  const lines = composeBrief({
+    cfg: env.cfg,
+    selfUsed: self.used,
+    selfWin: self.win,
+    gate,
+    scan,
+    drift,
+    advice: { text: adv.action + ' —— ' + adv.reason },
+    ok,
+  });
+  const c = consentLine(meId);
+  if (c) lines.push('授权   ' + c);
+  return lines;
+}
+
+function diagText(env, state, exec) {
+  const out = [];
+  const meId = env.selfId(exec);
+  out.push('会话      ' + (meId || '?'));
+  if (typeof env.version === 'function') out.push('版本      ' + env.version());
+  out.push('调度器    ' + (state.schedulerReady() ? '就绪' : '未就绪' + (state.schedulerError() ? '：' + state.schedulerError() : '（稍后重试或重启）')));
+  if (typeof env.injectList === 'function') out.push('inject    ' + env.injectList().join(' / '));
+  if (typeof env.initErrors === 'function') {
+    const errs = env.initErrors();
+    out.push('初始化    ' + (errs.length ? '有 ' + errs.length + ' 处失败：' + errs.join('；') : '无错误'));
+  }
+  if (typeof env.probeServices === 'function') {
+    const svc = env.probeServices();
+    out.push('服务      ' + Object.keys(svc).map((k) => k + '=' + (svc[k] ? '可用' : '—')).join('  '));
+  }
+  if (typeof env.guardLast === 'function') {
+    const g = env.guardLast();
+    out.push('通信判定  ' + (g
+      ? (g.allow ? '放行' : '拦截') + ' · 依据 ' + g.source + (g.title ? ' · 标题 ' + g.title : '') + ' · 会话 ' + g.sid
+      : '本进程还没有 peer（action="send"、"new"）调用'));
+  }
+  if (typeof env.probeAgentScope === 'function') {
+    const a = env.probeAgentScope(exec);
+    const show = ['compaction', 'compactNow', 'tokenMeter', 'sessions', 'llm', 'agents']
+      .map((k) => k + '=' + (a[k] ? '可用' : '—')).join('  ');
+    out.push('会话作用域 ' + (a.ctx ? show : '无法获取 exec.agent.ctx'));
+  }
+  const st = typeof env.compactionState === 'function'
+    ? env.compactionState(exec)
+    : (() => { const c = countCompactions(eventsOf(exec)); return { used: c.used, lock: c.lock, source: 'events' }; })();
+  out.push('压缩      ' + st.used + '/' + env.cfg.maxCompactions + ' 次；锁 ' + st.lock + '；来源 ' + st.source);
+  const pct = env.selfPct(meId);
+  out.push('水位      ' + (pct === null ? '读不到' : pct.toFixed(1) + '%') + (typeof env.staleNote === 'function' ? env.staleNote(exec) : ''));
+  const ws = env.resolveWs(exec);
+  let wsOk = false;
+  try { wsOk = fs.existsSync(path.join(ws, '_Control_Center')); } catch { wsOk = false; }
+  if (typeof env.roleOf === 'function') {
+    try {
+      const info = env.roleOf(exec);
+      const ts = typeof env.toolsetOf === 'function' ? env.toolsetOf(info.role) : null;
+      out.push('角色      ' + info.role + (info.project ? '（项目 ' + info.project + '）' : info.task ? '（任务 ' + info.task + '）' : '') + ' · 依据 ' + info.source + (ts ? ' · 可见工具 ' + ts.allow.length + '/' + (ts.allow.length + ts.deny.length) : ''));
+      if (typeof env.roleState === 'function') {
+        const rs = env.roleState();
+        const cnt = typeof rs.count === 'number' ? ' · 已装配 ' + rs.count + ' 个会话' : '';
+        out.push('角色装配  ' + (rs.mode || '未知') + cnt + (rs.last ? ' · 最近：' + rs.last.sid + ' → ' + rs.last.role + '（' + rs.last.at + '）' : ''));
+      }
+    } catch (e) {
+      out.push('角色      判定失败：' + (e && e.message ? e.message : e));
+    }
+  }
+  out.push('工作区    ' + ws + (wsOk
+    ? '  已接入'
+    : '  — 未接入（未找到 _Control_Center）：让当前用户走设置页「首次安装」，或本会话直接 ho_workspace(action="init", parent="<目录>", register=true)'));
+  try {
+    const mv = typeof env.moveInfo === 'function' ? env.moveInfo() : null;
+    if (mv) out.push('迁移      ' + mv.phase + ' · ' + mv.src + (mv.dst ? '  →  ' + mv.dst : ''));
+  } catch { /* ignore */ }
+  out.push('配置      warn=' + env.cfg.warnRatio + ' handover=' + env.cfg.handoverRatio + ' hard=' + env.cfg.hardRatio + ' max=' + env.cfg.maxCompactions);
+  if (typeof env.handoverFor === 'function') {
+    try {
+      const hp = env.handoverFor(exec);
+      out.push('交接路径  ' + (hp && hp.path ? hp.path + '（' + hp.kind + '）' : '无 —— ' + ((hp && hp.reason) || '角色未定')));
+    } catch (e) {
+      out.push('交接路径  解析失败：' + (e && e.message ? e.message : e));
+    }
+  } else {
+    out.push('交接路径  ' + (env.cfg.handoverPath || '（按角色解析）'));
+  }
+  return out;
+}
+
+function driftText(env, args, exec) {
+  const ws = env.resolveWs(exec);
+  const res = computeDrift({
+    ws,
+    cacheDir: env.cacheDir(),
+    slack: typeof args.slack === 'number' ? args.slack : env.cfg.driftSlack,
+    all: args.all === true,
+  });
+  const out = [];
+  out.push('交接匹配检查（跟着交接走；冗余 ' + res.slack + ' 轮）  工作区根 ' + ws);
+  out.push('  项目  会话类型 会话  当前轮  交接轮  Δ  判定');
+  for (const r of res.rows) {
+    const cells = [r.project, r.kind, r.sid.slice(-8), String(r.turns), r.handoverTurn === null ? '?' : String(r.handoverTurn), r.delta === null ? '?' : String(r.delta), r.verdict];
+    out.push('  ' + cells.join('  '));
+  }
+  if (!res.rows.length) out.push('  读不到任何项目会话（Projects/ 下对应库不存在时属正常）');
+  out.push(driftVerdict(res));
+  return out;
+}
+
+function tokensText(args) {
+  const out = [];
+  const list = Array.isArray(args.sessions) ? args.sessions.filter((s) => typeof s === 'string' && s.trim() !== '') : [];
+  if (!list.length) throw new Error('view=tokens 时 sessions 不能为空（给会话 id 数组）');
+  out.push('会话 轮 步 输出tok 每步tok 最贵返回 超20步轮 判定');
+  for (const sid of list) {
+    const full = sid.indexOf('session-') === 0 ? sid : 'session-' + sid;
+    const log = findLog(full);
+    if (!log) { out.push(sid + '  ERR 日志找不到'); continue; }
+    const recs = decodeLog(log);
+    if (!recs) { out.push(sid + '  ERR 日志解不出'); continue; }
+    const m = analyzeLog(recs);
+    const verdict = m.perStep > 2000 ? '偏贵（每步 >2k）' : m.heavyTurns > 0 ? '有超 20 步的轮' : '正常';
+    out.push([sid.slice(-8), m.turns, m.steps, m.outTok, m.perStep, Math.round(m.maxResult / 1024) + 'KB', m.heavyTurns, verdict].join('  '));
+  }
+  return out;
+}
+
+export function pmStatusTool(env, state) {
+  const w = watermark(env.cfg);
+  return {
+    name: nameOf('status'),
+    description:
+      '会话状态（只读）：view=phase 水位与建议（默认）、brief 起始简报、diag 插件自检、drift 交接漂移、tokens token 体检。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        view: { type: 'string', enum: VIEWS, description: '缺省 phase' },
+        threshold: { type: 'number', description: 'view=brief：预警阈值百分比（默认 ' + w.warnValue + '）' },
+        simulateRatio: { type: 'number', description: 'view=phase：演练用比例替代真实水位（0-1），不写任何状态' },
+        sessions: { type: 'array', items: { type: 'string' }, description: 'view=tokens：会话 id 列表' },
+        slack: { type: 'number', description: 'view=drift：容忍轮数（默认 3）' },
+        all: { type: 'boolean', description: 'view=drift：列全部会话，而不只是每个项目的在任会话' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const view = typeof args.view === 'string' && args.view ? args.view : 'phase';
+      if (VIEWS.indexOf(view) === -1) throw new Error('view 只能是 ' + VIEWS.join(' | ') + '（收到 ' + String(view) + '）');
+      if (view === 'phase') return { text: phaseText(env, args, exec).join(NL) };
+      if (view === 'brief') return { text: briefText(env, args, exec).join(NL) };
+      if (view === 'diag') return { text: diagText(env, state, exec).join(NL) };
+      if (view === 'drift') return { text: driftText(env, args, exec).join(NL) };
+      return { text: tokensText(args).join(NL) };
+    },
+  };
+}

package/src/tools/ho_succeed.mjs

@@ -7,7 +7,7 @@ export function pmSucceedTool(env) {
   return {
     name: nameOf('succeed'),
     description:
-      '换任：校验本会话交接，建接任会话并登记在任；须用户先授权（/allow-succeed）。',
+      '换任：校验本会话交接，建接任会话并登记在任；须当前用户先授权（/allow-succeed）。',
     parameters: {
       type: 'object',
       additionalProperties: false,

package/src/tools/ho_workspace.mjs

@@ -1,10 +1,11 @@
-/** ho_workspace —— 工作区生命周期：list / create / delete（官方 workspaceRegistry）＋ 全局根目录搬迁。 */
+/** ho_workspace —— 工作区生命周期：list / create / delete / init（首次建体系）＋ 全局根目录迁移。 */
 import fs from 'node:fs';
 import { nameOf } from '../lib/names.mjs';
 import path from 'node:path';
 import { textOutput } from '../lib/output.mjs';
 import { NL } from '../lib/text.mjs';
 import { workspaceRows } from '../lib/registry.mjs';
+import { createGlobalWorkspace, ensureScaffold } from '../lib/scaffold.mjs';
 import { probeMove, startMove, moveStatus, cleanupOld, stageSwitch, repairLink, stageRetarget } from '../lib/mover.mjs';
 import { currentRoot } from '../lib/api.mjs';
 
@@ -20,7 +21,7 @@ function gb(n) {
 
 function renderProbe(p) {
   const out = [];
-  out.push('搬迁预检：' + (p.ok ? '通过' : '不通过'));
+  out.push('迁移预检：' + (p.ok ? '通过' : '不通过'));
   out.push('  源  ' + p.src + (p.srcIsLink ? '（已是链接，指向 ' + p.linkTarget + '）' : ''));
   out.push('  复制源  ' + p.copyFrom);
   out.push('  目标  ' + p.dst);
@@ -36,7 +37,7 @@ export function pmWorkspaceTool(env) {
   return {
     name: nameOf('workspace'),
     description:
-      '工作区 list、create、delete；move-* 搬整个全局根目录（探针、执行、状态、清旧副本）。删除只删注册。',
+      '工作区：init 首次建全局体系、scaffold 补齐缺失目录与说明、list、create、delete、move-* 搬整个全局根目录。删除只删注册。',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -44,15 +45,18 @@ export function pmWorkspaceTool(env) {
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'create', 'delete', 'move-probe', 'move', 'move-switch', 'move-status', 'move-retarget', 'move-repair', 'move-cleanup'],
-          description: 'list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup',
+          enum: ['init', 'scaffold', 'list', 'create', 'delete', 'move-probe', 'move', 'move-switch', 'move-status', 'move-retarget', 'move-repair', 'move-cleanup'],
+          description: 'init / scaffold / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup',
         },
+        parent: { type: 'string', description: 'init 用：目标父目录绝对路径（不存在会创建）；全局根建在它里面' },
+        name: { type: 'string', description: 'init 用：全局根目录名，默认 _Workspace' },
+        register: { type: 'boolean', description: 'init 用：建好后顺带注册为工作区（默认 false）' },
         path: { type: 'string', description: 'create 用：目录绝对路径；默认要求已存在，ensure=true 时自动创建' },
-        title: { type: 'string', description: 'create 用：显示标题' },
+        title: { type: 'string', description: 'create、init 用：工作区显示标题（init 默认「全局」）' },
         ensure: { type: 'boolean', description: 'create 用：目录不存在时自动创建（默认 false，不替你建目录）' },
         workspace: { type: 'string', description: 'delete 用：工作区 id、标题、路径' },
         to: { type: 'string', description: 'move 用：新根绝对路径（父目录可自动建）' },
-        confirm: { type: 'boolean', description: 'move-cleanup 用：true 才真的删旧副本' },
+        confirm: { type: 'boolean', description: 'move-cleanup 用：true 才真的删旧备份' },
       },
     },
     output: textOutput(),
@@ -61,6 +65,74 @@ export function pmWorkspaceTool(env) {
       const action = String(args.action || '');
       const out = [];
 
+      if (action === 'init') {
+        const parent = String(args.parent || '').trim();
+        if (!parent) throw new Error('action="init" 需要 parent（目标父目录绝对路径）');
+        const r = createGlobalWorkspace(parent, { name: args.name });
+        if (!r.ok) {
+          out.push('未建立：' + r.error);
+          if (r.root) out.push('目标：' + r.root);
+          out.push('');
+          out.push('用法：ho_workspace(action="init", parent="<已存在的目录绝对路径>")。插件只新建、不覆盖。');
+          return { text: out.join(NL) };
+        }
+        out.push('已建立全局文件体系：' + r.root);
+        out.push('  目录 ' + r.created.length + ' 个：' + r.created.slice(0, 5).join('、') + (r.created.length > 5 ? ' 等' : ''));
+        out.push('  文件 ' + r.written.length + ' 个：' + (r.written.length ? r.written.join('、') : '（都已存在，未覆盖）'));
+        if (r.existed) out.push('  目标目录原为空目录，直接使用。');
+        if (r.createdParent) out.push('  父目录原本不存在，已创建。');
+        if (r.skipped.length) out.push('  跳过（已存在、未覆盖）：' + r.skipped.join('、'));
+        let registered = null;
+        if (args.register === true) {
+          if (!reg || typeof reg.create !== 'function') {
+            out.push('');
+            out.push('注册未完成：workspaceRegistry 不可用。请把下面这个路径粘进 DSH 的新建工作区窗口：');
+            out.push('  ' + r.root);
+            return { text: out.join(NL) };
+          }
+          const title = String(args.title || '').trim() || '全局';
+          try {
+            const w = await reg.create(r.root, title);
+            registered = w;
+            out.push('');
+            out.push('已注册工作区：' + title + '（' + String(w && w.id ? w.id : '?') + '）');
+          } catch (e) {
+            out.push('');
+            out.push('注册失败：' + String(e && e.message ? e.message : e));
+            out.push('可把下面这个路径粘进 DSH 的新建工作区窗口：');
+            out.push('  ' + r.root);
+            return { text: out.join(NL) };
+          }
+        }
+        out.push('');
+        out.push('下一步：');
+        if (!registered) {
+          out.push('  1. 注册为工作区：ho_workspace(action="create", path="' + r.root + '", title="全局")，或把该路径粘进 DSH 的新建工作区窗口；');
+          out.push('  2. 新建一个标题含「全局」的会话，闸门、交接体检、会话水位即接入。');
+        } else {
+          out.push('  新建一个标题含「全局」的会话，闸门、交接体检、会话水位即接入。');
+        }
+        out.push('（也可以在设置页的 dsh-handover 中完成「首次安装」，效果相同。）');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'scaffold') {
+        const root = currentRoot(env);
+        if (!root) throw new Error('未找到全局根（工作区未接入）');
+        const r = ensureScaffold(root);
+        if (!r.ok) {
+          out.push('未补齐：' + r.error);
+          out.push('根目录：' + root);
+          return { text: out.join(NL) };
+        }
+        out.push('已核对文件体系：' + root);
+        out.push('  新建目录 ' + r.created.length + ' 个：' + (r.created.length ? r.created.join('、') : '（无缺失）'));
+        out.push('  新建文件 ' + r.written.length + ' 个：' + (r.written.length ? r.written.join('、') : '（无缺失）'));
+        out.push('  已存在未覆盖 ' + r.skipped.length + ' 个' + (r.skipped.length ? '：' + r.skipped.join('、') : ''));
+        out.push('只新建、不覆盖、不删：已有文件的内容一字未改。');
+        return { text: out.join(NL) };
+      }
+
       if (action === 'list') {
         if (reg && typeof reg.list === 'function') {
           let list = [];
@@ -144,7 +216,7 @@ export function pmWorkspaceTool(env) {
         out.push('下一步（三条，顺序不能换）：');
         out.push('  ① 完全退出 DSH（源目录被占用，改名会失败）');
         out.push('  ② 执行 ho_workspace(action="move-switch") 派后台助手（推荐）；助手会等待 DSH 退出后自动完成');
-        out.push('  ③ 重新启动 DSH；确认无误后在设置页点「删除旧副本」');
+        out.push('  ③ 重新启动 DSH；确认无误后可在设置页删除旧备份');
         return { text: out.join(NL) };
       }
 
@@ -160,8 +232,8 @@ export function pmWorkspaceTool(env) {
 
       if (action === 'move-status') {
         const st = moveStatus();   // 以标记里的源路径为准：修改登记后当前根已是新位置，拿它比对会误报
-        const label = { none: '没有搬迁记录', verified: '已复制校验通过，等待切换', switched: '已切换（旧路径是 junction）', partial: '复制有差异，未生成脚本' };
-        out.push('搬迁状态：' + (label[st.phase] || st.phase));
+        const label = { none: '没有迁移记录', verified: '已复制并校验通过，待切换', switched: '已切换（原路径为链接）', partial: '复制有差异，未生成脚本' };
+        out.push('迁移状态：' + (label[st.phase] || st.phase));
         out.push('  源  ' + st.src + (st.linkTarget ? '（→ ' + st.linkTarget + '）' : ''));
         if (st.dst) out.push('  目标  ' + st.dst);
         if (st.marker && st.marker.files) out.push('  清单  ' + st.marker.files + ' 文件 · ' + (st.marker.digest || '').slice(0, 16) + '…');
@@ -175,10 +247,10 @@ export function pmWorkspaceTool(env) {
           }
         }
         if (st.olds && st.olds.length) {
-          for (const o of st.olds) out.push('  旧副本  ' + o.path + '  ' + gb(o.bytes));
+          for (const o of st.olds) out.push('  旧备份  ' + o.path + '  ' + gb(o.bytes));
           out.push('  删除：ho_workspace(action="move-cleanup", confirm=true)');
         } else if (st.phase === 'switched') {
-          out.push('  没有旧副本残留');
+          out.push('  没有旧备份');
         }
         return { text: out.join(NL) };
       }
@@ -203,7 +275,7 @@ export function pmWorkspaceTool(env) {
       }
 
       if (action === 'move-cleanup') {
-        if (args.confirm !== true) throw new Error('move-cleanup 需要 confirm=true（会真删旧副本目录）');
+        if (args.confirm !== true) throw new Error('move-cleanup 需要 confirm=true（会真删旧备份目录）');
         const r = await cleanupOld({ confirm: true });
         out.push(r.note);
         for (const p of r.removed) out.push('  已删 ' + p);
@@ -211,7 +283,7 @@ export function pmWorkspaceTool(env) {
         return { text: out.join(NL) };
       }
 
-      throw new Error('action 只能是 list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup');
+      throw new Error('action 只能是 init / scaffold / list / create / delete / move-probe / move / move-switch / move-status / move-retarget / move-repair / move-cleanup');
     },
   };
 }