@mingmaple/dsh-handover 0.0.0-stage → 0.9.12

package/src/tools/ho_phase.mjs

@@ -0,0 +1,37 @@
+/** ho_phase —— 本会话阶段：水位 / 已压缩次数 / 锁状态 / 建议动作（纯只读，不压缩）。 */
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL } from '../lib/text.mjs';
+import { decide } from '../lib/phase.mjs';
+
+export function pmPhaseTool(env) {
+  return {
+    name: nameOf('phase'),
+    description:
+      '本会话阶段：水位、已压缩次数、锁状态、建议动作。只读。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        simulateRatio: { type: 'number', description: '演练用：用这个比例替代真实水位（0-1），不写任何状态' },
+      },
+    },
+    output: textOutput(),
+    async execute(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) : ''));
+      const usedText = count.used + '/' + (env.cfg.maxCompactions) + ' 次';
+      out.push('压缩      ' + usedText + (count.note ? '  ' + count.note : ''));
+      out.push('锁        ' + lock);
+      out.push('建议      ' + adv.action + ' —— ' + adv.reason);
+      return { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_profile.mjs

@@ -0,0 +1,105 @@
+/** ho_profile —— 项目与杂项的骨架档案：读、注册、校验、取预设。 */
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL } from '../lib/text.mjs';
+import { presets, readProfile, writeProfile, validateProfile, profilePathFor, PROFILE_KINDS } from '../lib/profile.mjs';
+import { assertProjectName, assertTaskName } from '../lib/role.mjs';
+import { stampTz } from '../lib/brief.mjs';
+
+function targetOf(env, info, args, exec) {
+  if (info && (info.role === 'project' || info.role === 'misc')) {
+    const own = info.role === 'project' ? String(info.project || '') : String(info.task || '');
+    const given = String(args.project || args.task || '').trim();
+    // 项目会话只处理自己的骨架；传了别的名字就明确报错，而不是静默忽略入参（实测踩过）。
+    if (given && given !== own) {
+      throw new Error('本会话是' + (info.role === 'project' ? '项目「' + own + '」' : '杂项「' + own + '」')
+        + '，只能读写自己的骨架；要看「' + given + '」请由全局会话执行 ho_profile。');
+    }
+    return { role: info.role, project: info.project || '', task: info.task || '', self: true };
+  }
+  if (info && info.role === 'global') {
+    if (args.project) return { role: 'project', project: assertProjectName(String(args.project)), task: '', self: false };
+    if (args.task) return { role: 'misc', project: '', task: assertTaskName(String(args.task)), self: false };
+    throw new Error('全局会话使用 ho_profile 时须给 project 或 task');
+  }
+  throw new Error('普通会话不参与骨架注册');
+}
+
+function scopeOf(t) {
+  return t.role === 'project' ? '项目「' + t.project + '」' : '杂项任务「' + t.task + '」';
+}
+
+export function pmProfileTool(env) {
+  return {
+    name: nameOf('profile'),
+    description: '项目或杂项骨架：读取、注册、校验、取预设。只写本角色的 _Project_Meta 或 _Misc 目录。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ['read', 'register', 'validate', 'presets'], description: '缺省 read' },
+        project: { type: 'string', description: '全局会话读取或校验时的项目名' },
+        task: { type: 'string', description: '全局会话读取或校验时的任务名' },
+        kind: { type: 'string', enum: PROFILE_KINDS, description: 'presets 时取指定预设；缺省返回全部' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const action = typeof args.action === 'string' && args.action ? args.action : 'read';
+      const ws = env.resolveWs(exec);
+      if (!ws) throw new Error('没有工作区根');
+      if (action === 'presets') {
+        const all = presets();
+        const one = args.kind && all[args.kind] ? { [args.kind]: all[args.kind] } : all;
+        return { text: JSON.stringify(one, null, 2) };
+      }
+      const info = env.roleOf(exec);
+      const t = targetOf(env, info, args, exec);
+      const scope = { role: t.role, project: t.project, task: t.task };
+      const p = profilePathFor(ws, scope);
+      const r = readProfile(ws, scope);
+      if (action === 'read') {
+        const v = validateProfile(ws, scope, r.profile);
+        const out = [
+          '骨架：' + scopeOf(t) + '（' + (r.exists ? '已注册' : '未注册，按默认骨架运行') + '）',
+          '文件：' + (p || '（无）'),
+        ];
+        out.push(JSON.stringify(r.profile, null, 2));
+        out.push('校验：' + (v.ok ? '通过' : '未通过') + (v.missing.length ? '；缺 ' + v.missing.join('、') : ''));
+        if (r.errors.length) out.push('结构错误：' + r.errors.join('；'));
+        return { text: out.join(NL) };
+      }
+      if (action === 'validate') {
+        const v = validateProfile(ws, scope, r.profile);
+        const out = [
+          '骨架校验：' + scopeOf(t),
+          '文件：' + (p || '（无）'),
+          '结论：' + (v.ok ? '通过' : '未通过'),
+        ];
+        if (v.missing.length) out.push('缺：' + v.missing.join('、'));
+        if (r.errors.length || v.errors.length) out.push('结构错误：' + r.errors.concat(v.errors).join('；'));
+        return { text: out.join(NL) };
+      }
+      if (action === 'register') {
+        if (!t.self) throw new Error('注册须由该项目或杂项会话本人执行');
+        if (!r.exists) throw new Error('未找到骨架文件：' + p + '。先通读本库并写入该文件，再执行注册。');
+        if (r.errors.length) throw new Error('骨架结构不合法：' + r.errors.join('；'));
+        const saved = writeProfile(ws, scope, r.profile);
+        const v = validateProfile(ws, scope, saved.profile);
+        const sid = env.selfId(exec);
+        if (sid && typeof env.writeRole === 'function') {
+          try { env.writeRole(sid, { profileAt: stampTz(Date.now()), profileKind: saved.profile.kind }); } catch { /* 角色表写失败不影响注册 */ }
+        }
+        const out = [
+          '已注册骨架：' + scopeOf(t),
+          '文件：' + saved.path,
+          '类别：' + saved.profile.kind + '；约束条校验：' + (saved.profile.gate.libraryBlock ? '启用' : '不启用'),
+        ];
+        if (v.missing.length) out.push('尚缺：' + v.missing.join('、') + '（补齐后 ho_profile(action=validate) 复核）');
+        else out.push('校验：通过');
+        return { text: out.join(NL) };
+      }
+      throw new Error('未知 action：' + action);
+    },
+  };
+}

package/src/tools/ho_sessions.mjs

@@ -0,0 +1,115 @@
+/** ho_sessions —— 会话清点；action 分流：role 设置角色、new 建会话、prompt 出提示词、archive/unarchive 归档。 */
+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';
+import { sessionNew, sessionPrompt, sessionArchive, sessionUnarchive, sessionOrder, sessionPlace } from '../lib/session-ops.mjs';
+import { readRoles, resolveRole, ROLE_LABEL, sessionMeta } from '../lib/role.mjs';
+import { watermark } from '../lib/facts.mjs';
+
+function list(env, args, exec) {
+  const warn = typeof args.warn === "number" ? args.warn : watermark(env.cfg).warnValue;
+  const limit = typeof args.limit === "number" ? args.limit : 40;
+  const scan = scanSessions({
+    dir: env.cacheDir(),
+    meId: env.selfId(exec),
+    meCwd: env.selfCwd(exec),
+    warn,
+    silentHours: env.cfg.sessionScanHours,
+    projectsOnly: args.include_subagents !== true,
+  });
+  const store = readRoles(env.cfg);
+  const roleOf = (r) => {
+    const meta = sessionMeta(r.sid);
+    return resolveRole({ cfg: env.cfg, roles: store, sessionId: r.sid, cwd: meta.cwd, firstPrompt: meta.firstPrompt, subagent: meta.subagent, title: r.project });
+  };
+  const out = [];
+  out.push("活跃 / 沉默线：最后活动 " + stamp(scan.cutoffMs) + " 之后算活跃（" + scan.silentHours + " 小时；Charter 7.2.3）");
+  for (const r of scan.rows.slice(0, limit)) {
+    const pct = r.pct === null ? "水位 ?" : "水位 " + r.pct.toFixed(1) + "%";
+    const lab = r.mtime >= scan.cutoffMs ? "活跃" : "沉默";
+    const flag = r.pct !== null && r.pct >= warn ? "  【进预警区】" : "";
+    const info = roleOf(r);
+    out.push(r.kind + " " + r.sid + "  " + r.project + "  " + pct + "  " + r.state + "  角色 " + (ROLE_LABEL[info.role] || info.role) + "  最后活动 " + stamp(r.mtime) + "  【" + lab + "】" + flag);
+  }
+  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 + " 个会话（沉默项目全部＋前任）");
+  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("、"));
+  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) {
+    const bad = gate.libraries.filter((l) => !l.ok).map((l) => l.name + "(缺 " + l.missing.length + " 行)");
+    out.push("通用约束条闸门（Charter §7.2.3「闸门」）：**未过** —— " + bad.join("、"));
+    out.push("判定：通用约束条有库缺，交接前必须补齐（Charter §7.2.3 闸门）");
+    return out.join(NL);
+  } else out.push("通用约束条闸门（Charter §7.2.3「闸门」）：" + gate.total + "/" + gate.total + " 已落位");
+  const verdict = scan.hot.length
+    ? "判定：" + scan.hot.length + " 个会话已进预警区（>=" + warn + "%），按 Charter 7.2.3 先收齐交接再换会话"
+    : scan.unknown.length
+      ? "判定：" + scan.unknown.length + " 个会话水位无法读取，需人工判断"
+      : "判定：没有会话进入预警区（>=" + warn + "%），可以继续";
+  out.push(verdict);
+  return out.join(NL);
+}
+
+export function pmSessionsTool(env) {
+  return {
+    name: nameOf('sessions'),
+    description: '会话清点与调度；action=role 设置角色、new 建会话、order 下指令（交接、压缩）、place 移入工作区、prompt 出提示词、archive/unarchive 归档。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ['list', 'role', 'new', 'order', 'place', 'prompt', 'archive', 'unarchive'], description: '缺省 list' },
+        order: { type: 'string', enum: ['handover', 'compact'], description: 'order 的动作：handover 让它写交接再换任；compact 给它排压缩（先要有合格交接）' },
+        resume: { type: 'string', enum: ['continue', 'wait'], description: 'order=compact 时的去向：缺省 wait（交接后收尾，压缩后不唤醒）；continue 表示压缩后按交接继续' },
+        include_subagents: { type: 'boolean', description: 'list 时含子会话' },
+        limit: { type: 'number', description: 'list 行数（默认 40）' },
+        warn: { type: 'number', description: 'list 预警阈值（默认 ' + watermark(env.cfg).warn + '）' },
+        session_id: { type: 'string', description: 'role/order/place/archive/unarchive 的目标会话' },
+        role: { type: 'string', enum: ['global', 'project', 'misc', 'plain'], description: 'role 要设成的角色；new 时也据此登记接任者角色' },
+        project: { type: 'string', description: '项目名（role=project 必填；new 时为换任项目）' },
+        task: { type: 'string', description: '任务名（role=misc 必填）' },
+        notify: { type: 'boolean', description: 'role 时投整理指令（默认 true，会唤醒它一轮）' },
+        title: { type: 'string', description: 'new 的标题；prompt 用于推断代际' },
+        workspace: { type: 'string', description: 'new 必填：目标工作区的 id、标题或路径；new 时不给也能按 project 自动匹配同名工作区' },
+        cwd: { type: 'string', description: 'new 的工作目录，必须是某个已注册工作区的根（与 workspace 二选一）' },
+        message: { type: 'string', description: 'new 的启动提示词；不给则自动生成' },
+        force: { type: 'boolean', description: 'new 越过 <' + watermark(env.cfg).warn + ' 复用判据；order=compact 越过 120 秒去抖；archive 允许停掉在跑的' },
+        kind: { type: 'string', enum: ['global', 'project', 'misc', 'migration'], description: 'prompt 的类型；new 时用作角色候选' },
+        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；否则只报错、不做任何事' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const action = typeof args.action === 'string' && args.action ? args.action : 'list';
+      if (action === 'list') return { text: list(env, args, exec) };
+      if (action === 'new') return { text: await sessionNew(env, args, exec) };
+      if (action === 'order') return { text: await sessionOrder(env, args) };
+      if (action === 'place') return { text: await sessionPlace(env, args) };
+      if (action === 'prompt') return { text: sessionPrompt(env, args, exec) };
+      if (action === 'archive') return { text: await sessionArchive(env, args, exec) };
+      if (action === 'unarchive') return { text: await sessionUnarchive(env, args) };
+      if (action === 'role') {
+        if (typeof env.applyRole !== 'function') throw new Error('宿主侧没有装配 applyRole');
+        const r = await env.applyRole({ sessionId: args.session_id, role: args.role, project: args.project, task: args.task, wake: args.notify !== false });
+        const out = [];
+        out.push(r.ok ? '已设定角色：' + (ROLE_LABEL[r.role] || r.role) : '设定失败：' + r.error);
+        if (r.ok) {
+          out.push('  存活会话当场生效：' + (r.live ? '是（工具集与提示段已换）' : '否（下次开轮时生效）'));
+          out.push('  整理指令：' + (r.delivered ? '已投递（会唤醒它一轮）' : (r.error ? '投递失败：' + r.error : '未投递')));
+        }
+        return { text: out.join(NL) };
+      }
+      throw new Error('未知 action：' + action);
+    },
+  };
+}

package/src/tools/ho_snapshot.mjs

@@ -0,0 +1,104 @@
+/** ho_snapshot —— 库快照：逐字节复制 + sha256 清单 + PROVENANCE（Charter §4.4）。 */
+import fs from 'node:fs';
+import { nameOf } from '../lib/names.mjs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { textOutput } from '../lib/output.mjs';
+import { NL, isDir } from '../lib/text.mjs';
+import { assertProjectName } from '../lib/role.mjs';
+
+const SKIP_DIRS = ['__pycache__', '.git', 'node_modules', '.obsidian'];
+const SKIP_FILES = ['.DS_Store', 'Thumbs.db'];
+
+function stamp() {
+  const d = new Date();
+  const p = (n) => (n < 10 ? '0' + n : '' + n);
+  return d.getFullYear() + p(d.getMonth() + 1) + p(d.getDate()) + '-' + p(d.getHours()) + p(d.getMinutes());
+}
+
+function walk(root, rel, rows) {
+  for (const name of fs.readdirSync(path.join(root, rel))) {
+    const full = path.join(root, rel, name);
+    const st = fs.statSync(full);
+    const r = rel ? rel + '/' + name : name;
+    if (st.isDirectory()) {
+      if (SKIP_DIRS.indexOf(name) !== -1) continue;
+      walk(root, r, rows);
+    } else if (st.isFile()) {
+      if (SKIP_FILES.indexOf(name) !== -1) continue;
+      if (name.endsWith('.pyc')) continue;
+      rows.push({ rel: r, size: st.size });
+    }
+  }
+  return rows;
+}
+
+export function pmSnapshotTool(env) {
+  return {
+    name: nameOf('snapshot'),
+    description:
+      '库快照：逐字节复制、sha256 清单、来源说明。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['project'],
+      properties: {
+        project: { type: 'string', description: '项目名（Projects/<项目>/ 下）' },
+        tag: { type: 'string', description: '标签，默认 行为检查' },
+        dry_run: { type: 'boolean', description: '只统计不落盘' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const ws = env.resolveWs(exec);
+      const project = assertProjectName(typeof args.project === 'string' ? args.project.trim() : '');
+      if (!project) throw new Error('project 不能为空（写项目名，如 Demo）');
+      const projDir = path.join(ws, 'Projects', project);
+      if (!isDir(projDir)) throw new Error('找不到项目：' + projDir);
+      let lib = null;
+      for (const name of fs.readdirSync(projDir)) {
+        const p = path.join(projDir, name);
+        if (isDir(p) && fs.existsSync(path.join(p, 'RULES.md'))) { lib = p; break; }
+      }
+      if (!lib) throw new Error('该项目下没有带 RULES.md 的库根：' + projDir);
+      const rows = walk(lib, '', []);
+      const total = rows.reduce((a, b) => a + b.size, 0);
+      const out = [];
+      out.push('源库 ' + lib);
+      out.push('文件 ' + rows.length + ' 个，共 ' + (total / 1048576).toFixed(2) + ' MB');
+      if (args.dry_run) { out.push('dry_run：不落盘。'); return { text: out.join(NL) }; }
+      const tag = args.tag || '行为检查';
+      const dest = path.join(ws, '_Temp', 'Checks', args.project + '_' + tag + '_' + stamp());
+      if (fs.existsSync(dest)) throw new Error('目标已存在，不覆盖：' + dest);
+      const libDest = path.join(dest, 'lib');
+      fs.mkdirSync(libDest, { recursive: true });
+      const manifest = ['# 源库: ' + lib, '# 文件: ' + rows.length + '  字节: ' + total];
+      let drift = 0;
+      for (const r of rows) {
+        const src = path.join(lib, r.rel);
+        const dst = path.join(libDest, r.rel);
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        fs.copyFileSync(src, dst);
+        const h1 = crypto.createHash('sha256').update(fs.readFileSync(src)).digest('hex');
+        const h2 = crypto.createHash('sha256').update(fs.readFileSync(dst)).digest('hex');
+        if (h1 !== h2) drift++;
+        manifest.push(r.rel + String.fromCharCode(9) + r.size + String.fromCharCode(9) + h1);
+      }
+      fs.writeFileSync(path.join(dest, 'MANIFEST.tsv'), manifest.join(NL), 'utf8');
+      const prov = [
+        '# PROVENANCE',
+        '- 源库: ' + lib,
+        '- 生成时间: ' + new Date().toISOString(),
+        '- 发起会话: ' + (env.selfId(exec) || '?'),
+        '- 文件数/字节: ' + rows.length + ' / ' + total,
+        '- 排除: __pycache__ .git node_modules .obsidian *.pyc .DS_Store Thumbs.db',
+        '- 校验: 逐文件 sha256 比对，drift=' + drift,
+        '- 含个人数据，不得外发、不得进 _Archives',
+      ].join(NL);
+      fs.writeFileSync(path.join(dest, 'PROVENANCE.md'), prov, 'utf8');
+      out.push('已落盘 ' + dest);
+      out.push('校验 drift=' + drift + (drift === 0 ? '（逐文件一致）' : '（**不一致，判失败**）'));
+      return { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_tokens.mjs

@@ -0,0 +1,57 @@
+/** ho_tokens —— token 体检（替代 token_probe/token_survey 的常用判据）。 */
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL, pick } from '../lib/text.mjs';
+import { findLog, decodeLog, turnStarts } from '../lib/zstd-log.mjs';
+
+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 };
+}
+
+export function pmTokensTool(env) {
+  return {
+    name: nameOf('tokens'),
+    description:
+      '会话 token 体检：轮数、步数、每步 token、最贵单条返回。只读。',
+    parameters: {
+      type: 'object', additionalProperties: false, required: ['sessions'],
+      properties: { sessions: { type: 'array', items: { type: 'string' }, description: '会话 id 列表' } },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const out = [];
+      const list = Array.isArray(args.sessions) ? args.sessions.filter((s) => typeof s === 'string' && s.trim() !== '') : [];
+      if (!list.length) throw new Error('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 { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_workspace.mjs

@@ -0,0 +1,217 @@
+/** ho_workspace —— 工作区生命周期：list / create / delete（官方 workspaceRegistry）＋ 全局根目录搬迁。 */
+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 { probeMove, startMove, moveStatus, cleanupOld, stageSwitch, repairLink, stageRetarget } from '../lib/mover.mjs';
+import { currentRoot } from '../lib/api.mjs';
+
+const BAD = '不能删除「全局」工作区（那是管理会话的家）。';
+
+function gb(n) {
+  const v = Number(n) || 0;
+  if (v >= 1024 * 1024 * 1024) return (v / (1024 * 1024 * 1024)).toFixed(2) + ' GB';
+  if (v >= 1024 * 1024) return (v / (1024 * 1024)).toFixed(1) + ' MB';
+  if (v >= 1024) return (v / 1024).toFixed(1) + ' KB';
+  return v + ' B';
+}
+
+function renderProbe(p) {
+  const out = [];
+  out.push('搬迁预检：' + (p.ok ? '通过' : '不通过'));
+  out.push('  源  ' + p.src + (p.srcIsLink ? '（已是链接，指向 ' + p.linkTarget + '）' : ''));
+  out.push('  复制源  ' + p.copyFrom);
+  out.push('  目标  ' + p.dst);
+  out.push('  总大小  ' + p.files + ' 文件 · ' + gb(p.bytes) + '（' + p.dirs + ' 子目录）');
+  if (p.freeBytes !== null && p.freeBytes !== undefined) out.push('  目标盘可用  ' + gb(p.freeBytes));
+  for (const w of p.warnings || []) out.push('  注意：' + w);
+  for (const x of p.problems || []) out.push('  未通过：' + x);
+  if (p.ok) out.push('提示：复制完会生成切换脚本；切换那一步需要**完全退出 DSH** 再跑（源目录被占用）。');
+  return out.join(NL);
+}
+
+export function pmWorkspaceTool(env) {
+  return {
+    name: nameOf('workspace'),
+    description:
+      '工作区 list、create、delete；move-* 搬整个全局根目录（探针、执行、状态、清旧副本）。删除只删注册。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['action'],
+      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',
+        },
+        path: { type: 'string', description: 'create 用：目录绝对路径；默认要求已存在，ensure=true 时自动创建' },
+        title: { type: 'string', description: 'create 用：显示标题' },
+        ensure: { type: 'boolean', description: 'create 用：目录不存在时自动创建（默认 false，不替你建目录）' },
+        workspace: { type: 'string', description: 'delete 用：工作区 id、标题、路径' },
+        to: { type: 'string', description: 'move 用：新根绝对路径（父目录可自动建）' },
+        confirm: { type: 'boolean', description: 'move-cleanup 用：true 才真的删旧副本' },
+      },
+    },
+    output: textOutput(),
+    async execute(args) {
+      const reg = env.registry();
+      const action = String(args.action || '');
+      const out = [];
+
+      if (action === 'list') {
+        if (reg && typeof reg.list === 'function') {
+          let list = [];
+          try { list = reg.list() || []; } catch { list = []; }
+          if (list.length) {
+            out.push('工作区（官方注册表，' + list.length + ' 个）');
+            for (const w of list) {
+              const n = w && w.sessionIds && typeof w.sessionIds.length === 'number' ? w.sessionIds.length : '?';
+              out.push('  ' + String(w.id) + '  ' + String(w.title || '-') + '  ' + String(w.path || '-') + '  会话 ' + n);
+            }
+            return { text: out.join(NL) };
+          }
+        }
+        const rows = workspaceRows();
+        out.push('工作区（退化：读 workspace.json，' + rows.length + ' 个）');
+        for (const r of rows) out.push('  ' + r.id + '  ' + r.title + '  ' + r.path + '  会话 ' + r.sessions);
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'create') {
+        if (!reg || typeof reg.create !== 'function') throw new Error('workspaceRegistry.create 不可用');
+        const p = String(args.path || '').trim();
+        if (!p) throw new Error('create 需要 path（目录绝对路径）');
+        let st = null;
+        try { st = fs.statSync(p); } catch { st = null; }
+        if ((!st || !st.isDirectory()) && args.ensure === true) {
+          try { fs.mkdirSync(p, { recursive: true }); st = fs.statSync(p); } catch (e) { throw new Error('建目录失败：' + p + '（' + String(e && e.message ? e.message : e) + '）'); }
+        }
+        if (!st || !st.isDirectory()) throw new Error('目录不存在或不是目录：' + p + '（默认不替你建目录；要建请传 ensure=true，或先手工建好）');
+        const title = String(args.title || '').trim() || p.split(/[\\/]/).filter(Boolean).pop() || p;
+        let w = null;
+        try { w = await reg.create(p, title); } catch (e) { throw new Error('建工作区失败：' + String(e && e.message ? e.message : e)); }
+        out.push('已注册工作区 ' + String(w && w.id ? w.id : '?') + '  ' + String(w && w.title ? w.title : title));
+        out.push('路径 ' + String(w && w.path ? w.path : p));
+        out.push('同一路径重复调用返回原记录、不改标题；新登记的工作区排在列表最前。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'delete') {
+        if (!reg || typeof reg.delete !== 'function') throw new Error('workspaceRegistry.delete 不可用');
+        const key = String(args.workspace || '').trim();
+        if (!key) throw new Error('delete 需要 workspace（id、标题、路径）');
+        let list = [];
+        try { list = reg.list() || []; } catch { list = []; }
+        const norm = (s) => String(s || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+        const hit = list.find((w) => String(w.id) === key || w.title === key || norm(w.path) === norm(key));
+        if (!hit) throw new Error('找不到工作区：' + key);
+        if (String(hit.title || '').indexOf('全局') !== -1) throw new Error(BAD);
+        const ok = await reg.delete(hit.id);
+        out.push((ok ? '已删除工作区注册 ' : '该工作区不存在（无操作）') + String(hit.id) + '  ' + String(hit.title || '-'));
+        out.push('注意：只删注册；目录与全部会话日志都保留在原处。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'move-probe' || action === 'move') {
+        const src = currentRoot(env);
+        if (!src) throw new Error('未找到全局根（工作区未接入）');
+        const to = String(args.to || '').trim();
+        if (!to) throw new Error(action === 'move' ? 'move 需要 to（新根绝对路径）' : 'move-probe 需要 to（新根绝对路径）');
+        if (action === 'move-probe') {
+          const p = await probeMove({ src, to });
+          return { text: renderProbe(p) };
+        }
+        const p = await probeMove({ src, to });
+        if (!p.ok) return { text: renderProbe(p) + NL + '未开始复制。' };
+        const r = await startMove({ src, to });
+        if (!r.ok) {
+          out.push('复制完成但**校验有差异**，未生成切换脚本。');
+          out.push('  文件 源 ' + r.report.files + ' / 目标 ' + r.report.copies);
+          out.push('  缺失 ' + r.report.missingCount + ' 条' + (r.report.missing.length ? '：' + r.report.missing.join('、') : ''));
+          out.push('  多出 ' + r.report.extraCount + ' 条' + (r.report.extra.length ? '：' + r.report.extra.join('、') : ''));
+          out.push('处置：清空目标目录后重跑，或先停掉在写文件的会话。');
+          return { text: out.join(NL) };
+        }
+        out.push('复制并校验通过：' + r.report.files + ' 文件 · ' + gb(r.report.bytes));
+        out.push('  sha256 清单摘要 ' + r.report.digest);
+        out.push('  目标  ' + r.marker.dst);
+        out.push('  切换助手  ' + r.marker.script.helper);
+        out.push('  手工启动器（Windows、POSIX）  ' + r.marker.script.cmd + ' 、 ' + r.marker.script.sh);
+        out.push('');
+        out.push('下一步（三条，顺序不能换）：');
+        out.push('  ① 完全退出 DSH（源目录被占用，改名会失败）');
+        out.push('  ② 执行 ho_workspace(action="move-switch") 派后台助手（推荐）；助手会等待 DSH 退出后自动完成');
+        out.push('  ③ 重新启动 DSH；确认无误后在设置页点「删除旧副本」');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'move-switch') {
+        const r = stageSwitch({ relaunch: args.relaunch === true });
+        if (r.already) { out.push('已经是切换态（旧路径就是 junction），无需再切。'); return { text: out.join(NL) }; }
+        out.push('已派出后台切换助手（pid ' + r.pid + '）。');
+        out.push('  它会在你**完全退出 DSH** 后自动完成：旧目录改名、原位建 junction、校验指向' + (r.relaunch ? '，然后重新启动 DSH' : '') + '。');
+        out.push('  日志：' + r.log);
+        out.push('  提醒：从现在起不要改这个工作区里的文件（改动只会落在还活着的旧目录上）。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'move-status') {
+        const st = moveStatus();   // 以标记里的源路径为准：修改登记后当前根已是新位置，拿它比对会误报
+        const label = { none: '没有搬迁记录', verified: '已复制校验通过，等待切换', switched: '已切换（旧路径是 junction）', 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) + '…');
+        if (st.retarget) {
+          if (st.retarget.needed) {
+            out.push('  DSH 登记仍指着旧路径：' + st.retarget.total + ' 处');
+            for (const f of st.retarget.files) out.push('    ' + f.path + '  ×' + f.count);
+            out.push('  修改登记：ho_workspace(action="move-retarget")（退出 DSH 后由助手改写，先备份）');
+          } else {
+            out.push('  DSH 登记已在新位置（无需修改登记）');
+          }
+        }
+        if (st.olds && st.olds.length) {
+          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('  没有旧副本残留');
+        }
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'move-retarget') {
+        const r = stageRetarget();
+        if (r.already) { out.push('DSH 登记已在新位置，无需修改登记。'); return { text: out.join(NL) }; }
+        if (!r.ok) { out.push('派助手失败：' + r.error); out.push('  手工执行：' + (r.script && r.script.helper)); return { text: out.join(NL) }; }
+        out.push('已派出登记修改登记助手（pid ' + r.pid + '）。');
+        out.push('  它会在你完全退出 DSH 后改写这些登记（每份先备份）：');
+        for (const f of (r.plan.files || [])) if (f.count) out.push('    ' + f.path + '  ×' + f.count);
+        out.push('  只改登记文本，不动任何数据文件；日志：' + (r.script && r.script.log));
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'move-repair') {
+        const r = repairLink();
+        if (r.already) { out.push('原路径已是指向新根的链接，无需重建。'); return { text: out.join(NL) }; }
+        out.push('已重建链接：' + r.src + ' → ' + r.dst + '（' + r.kind + '）');
+        out.push('  说明：只建链接，未改动任何文件。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'move-cleanup') {
+        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);
+        if (r.bytes) out.push('  释放 ' + gb(r.bytes));
+        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');
+    },
+  };
+}