@mingmaple/dsh-handover 0.0.0-stage → 0.9.6

package/src/tools/ho_checkpoint.mjs

@@ -0,0 +1,125 @@
+/** ho_checkpoint —— 写交接 + 登记压缩；压缩由调度器在轮次结束后执行（交接路径按角色）。 */
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL } from '../lib/text.mjs';
+import { readHandover, writeHandover } from '../lib/handover-io.mjs';
+import { eventsOf, countCompactions } from '../lib/events.mjs';
+import { decide } from '../lib/phase.mjs';
+import { checkConsent, consumedConsent } from '../lib/consent.mjs';
+
+export function pmCheckpointTool(env) {
+  return {
+    name: nameOf('checkpoint'),
+    description:
+      '写交接、登记压缩；回合结束后自动压缩并续跑。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        handover_text: { type: 'string', description: '要写入的交接正文；不给则要求磁盘上已有合格交接' },
+        handover_path: { type: 'string', description: '覆盖交接路径（演练用）' },
+        at_risk: { type: 'boolean', description: '当前处在关键步骤：为 true 时，水位在提醒线～交接线之间只提醒、不压缩（过交接线仍会压）' },
+        force: { type: 'boolean', description: '忽略关键步骤判定，直接排压缩' },
+        confirm: { type: 'boolean', description: '判定为「可压缩」后须经用户同意才传 true；还需用户在设置页点「允许压缩」（5 分钟一次性授权），否则不排压缩' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const ws = env.resolveWs(exec);
+      const meId = env.selfId(exec);
+      if (!meId) throw new Error("拿不到本会话 id，无法调度压缩");
+      const info = env.roleOf(exec);
+      const target = args.handover_path
+        ? { path: args.handover_path, kind: info.role === 'project' ? 'project' : info.role === 'misc' ? 'misc' : 'global' }
+        : env.handoverFor(exec);
+      if (!target || !target.path) {
+        return { text: [
+          '没有可用的交接路径：' + (target && target.reason ? target.reason : '未知'),
+          '先指定角色（设置页的 dsh-handover 中「会话角色」），或显式传 handover_path="<交接文件绝对路径>"。',
+          '压缩会丢历史，没有合格交接就不排压缩。',
+        ].join(NL) };
+      }
+      const file = target.path;
+      const st = typeof env.compactionState === "function" ? env.compactionState(exec) : null;
+      const count = st ? { used: st.used, lock: st.lock } : countCompactions(eventsOf(exec));
+      const self = env.selfPct(meId);
+      const ratio = self === null ? null : self / 100;
+      const out = [];
+      const recentSec = st && st.lastSummaryMs ? (Date.now() - st.lastSummaryMs) / 1000 : null;
+      if (recentSec !== null && recentSec < 120 && args.force !== true) {
+        out.push("拒绝排压缩：" + Math.round(recentSec) + " 秒前刚完成一次压缩（日志里有 compaction/summary），避免重复排程。");
+        out.push("等一轮让投影缓存刷新；确实要再压一次请加 force=true。");
+        return { text: out.join(NL) };
+      }
+      if (count.lock === "open") {
+        out.push("拒绝排压缩：检测到未闭合的压缩锁（compaction/start 无配对 end）。");
+        out.push("处理：等当前压缩结束后用 ho_phase 复查；若长时间不动，说明上次压缩崩在中间。");
+        return { text: out.join(NL) };
+      }
+      const adv = decide({ ratio, compactionsUsed: count.used, cfg: env.cfg, lockState: count.lock });
+      if (adv.action === "new_session") {
+        out.push("不建议压缩：" + adv.reason);
+        out.push('下一步：用 ho_handover(action=write) 写交接，再由全局 ho_sessions(action="new") 建新会话。');
+        return { text: out.join(NL) };
+      }
+      if (adv.action === "pause" && args.at_risk === true && args.force !== true) {
+        out.push("已暂停（关键步骤）：" + adv.reason);
+        out.push("到阶段边界再调一次 ho_checkpoint（不带 at_risk 或带 force）。");
+        return { text: out.join(NL) };
+      }
+      if (adv.action === "continue" && args.force !== true) {
+        out.push("水位未到线（" + (ratio === null ? "读不到" : (Math.round(ratio * 1000) / 10).toFixed(1) + "%") + "）：不压。");
+        out.push("需要强制演练可加 force=true。");
+        return { text: out.join(NL) };
+      }
+      // 判断逻辑不动；只有判定可以压缩之后，才停下来问用户。
+      if (args.confirm !== true) {
+        out.push('判定：可以压缩（' + adv.reason + '）。');
+        out.push('水位 ' + (ratio === null ? '读不到' : (Math.round(ratio * 1000) / 10).toFixed(1) + '%') + '，已压缩 ' + count.used + '/3。');
+        out.push('压缩会丢历史并自动续跑 —— 先问用户「要压缩吗？」，回答同意后再调 ho_checkpoint(confirm=true)；不同意就保持原样。');
+        return { text: out.join(NL) };
+      }
+      let wrote = null;
+      if (typeof args.handover_text === "string" && args.handover_text.trim() !== "") {
+        wrote = writeHandover(ws, file, args.handover_text, "write", { kind: target.kind, info });
+        out.push("交接已写入 " + file + "（" + wrote.bytes + " B，备份：" + (wrote.backup || "无") + "）· 角色 " + info.role);
+        out.push("体检 " + wrote.verdict + (wrote.reasons.length ? "：" : " · 结构齐备"));
+        for (const r of wrote.reasons) out.push("  - " + r);
+        if (wrote.verdict !== "通过") {
+          out.push("体检不通过 ⇒ 不排压缩（先补结构，压缩后就没机会改了）。");
+          return { text: out.join(NL) };
+        }
+      } else {
+        const cur = readHandover(file);
+        if (cur.text === null || cur.text.trim() === "") {
+          out.push("没有交接正文，磁盘上也没有：" + file);
+          out.push("拒绝压缩 —— 压缩会丢历史，必须先有交接。");
+          return { text: out.join(NL) };
+        }
+        out.push("沿用磁盘上已有交接：" + file);
+      }
+      // 严格闸门：confirm=true 只表示意图，是否同意以用户点过授权为准。
+      // 任何角色（全局、项目、杂项）都靠同一条判据：用户是否在设置页点过授权。
+      // 会话自行判断水位与询问用户，用户点授权后自行排压缩，不必上报全局。
+      const cs = checkConsent(meId);
+      if (!cs.ok) {
+        out.push('交接已写好，但**没有排压缩**：' + cs.reason + '。');
+        out.push('授权方式（任选其一）：① 在聊天框发送 /allow-compact（最快，仅授权本会话）；② 在设置页的 dsh-handover 中点击「压缩授权」一次。授权有效期 5 分钟，其后须再调用 ho_checkpoint(confirm=true)。');
+        out.push('如此设限的原因：压缩会丢弃历史，而参数由 AI 自行填写——惟有用户在设置页当面点击的那一次，方视为同意。');
+        return { text: out.join(NL) };
+      }
+      // 成本提示：低于交接线强行压缩会白付一次摘要，且本轮前缀缓存失效。
+      const handoverRatio = (env.cfg && env.cfg.handoverRatio) || 0.35;
+      if (ratio !== null && ratio < handoverRatio) {
+        out.push('注意成本：当前水位 ' + (Math.round(ratio * 1000) / 10) + '% 低于交接线 ' + Math.round(handoverRatio * 100) + '% —— 属于提前压缩，会白付一次摘要调用，且本轮前缀缓存失效。');
+      }
+      consumedConsent(meId);
+      const n = count.used + 1;
+      env.schedule(meId, n);
+      out.push('用户已授权（' + cs.atText + ' 点击，剩 ' + Math.round(cs.leftMs / 1000) + ' 秒）。');
+      out.push("已登记压缩（第 " + n + "/" + env.cfg.maxCompactions + " 次）。本回合结束后执行，完成后会自动收到续跑消息。");
+      out.push("压缩期间不要结束会话；如果 60 秒内没有续跑消息，用 ho_phase 看状态。");
+      return { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_diag.mjs

@@ -0,0 +1,85 @@
+/** ho_diag —— 诊断：服务是否可解析、调度器是否就绪、配置是否如预期。不写任何东西。 */
+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 { eventsOf, countCompactions } from '../lib/events.mjs';
+
+export function pmDiagTool(env, state) {
+  return {
+    name: nameOf('diag'),
+    description:
+      '插件自检：服务、调度器、压缩计数、工作区是否接入。只读。',
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    output: textOutput(),
+    async execute(args, exec) {
+      const out = [];
+      const meId = env.selfId(exec);
+      out.push("会话      " + (meId || "?"));
+      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_send、peer_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);
+      out.push("水位      " + (env.selfPct(meId) === null ? "读不到" : env.selfPct(meId).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();
+            out.push("角色收窄  " + (rs.gating || "未触发") + (rs.last ? " · 最近：" + rs.last.sid + " → " + rs.last.role + "（" + rs.last.at + "）" : ""));
+            if (rs.bootstrap) out.push("一次性引导 " + rs.bootstrap);
+          }
+        } catch (e) {
+          out.push("角色      判定失败：" + (e && e.message ? e.message : e));
+        }
+      }
+      out.push("工作区    " + ws + (wsOk
+        ? "  已接入"
+        : "  — 未接入（未找到 _Control_Center）：让用户走设置页「首次安装」，或本会话直接 ho_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 { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_drift.mjs

@@ -0,0 +1,41 @@
+/** ho_drift —— 交接漂移体检（替代 handover_check.mjs）。 */
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL } from '../lib/text.mjs';
+import { computeDrift, driftVerdict } from '../lib/drift.mjs';
+
+export function pmDriftTool(env) {
+  return {
+    name: nameOf('drift'),
+    description:
+      '交接漂移体检：Δ＝当前轮−交接轮，超过容忍轮数（默认 3）需刷新交接。只读。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        slack: { type: 'number', description: '容忍轮数（默认 3）' },
+        all: { type: 'boolean', description: '列全部会话，而不只是每个项目的在任会话' },
+      },
+    },
+    output: textOutput(),
+    async execute(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 { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_gate.mjs

@@ -0,0 +1,69 @@
+/** ho_gate —— 通用约束条闸门 + 交接文档体检。 */
+import path from 'node:path';
+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 { lintGlobal, lintProject, renderLintGlobal, renderLintProject } from '../lib/lint.mjs';
+import { SETUP_STEPS } from '../lib/guide.mjs';
+
+function lintAllProjects(ws) {
+  const meta = path.join(ws, "_Project_Meta");
+  const rows = [];
+  let dirs = [];
+  try { dirs = fs.readdirSync(meta).sort(); } catch { return rows; }
+  for (const name of dirs) {
+    const dir = path.join(meta, name);
+    try { if (!fs.statSync(dir).isDirectory()) continue; } catch { continue; }
+    const f = path.join(dir, "Handover.md");
+    rows.push({ name, file: f, res: lintProject(f) });
+  }
+  return rows;
+}
+
+export function pmGateTool(env) {
+  return {
+    name: nameOf('gate'),
+    description:
+      '通用约束条闸门（按库型判定）＋交接文档体检。只读。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        scope: { type: 'string', enum: ['all', 'global', 'project'], description: '默认 all' },
+        project: { type: 'string', description: 'scope=project 时的项目名' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const ws = env.resolveWs(exec);
+      const scope = args.scope || "all";
+      if (scope !== "all" && scope !== "global" && scope !== "project") {
+        throw new Error("scope 只能是 all | global | project（收到 " + String(scope) + "）");
+      }
+      const out = [];
+      if (scope === "all") {
+        const g = syncCheck(ws);
+        if (g.noWorkspace) {
+          out.push('通用约束条闸门：未接入工作区（' + g.path + '）');
+          out.push('把工作区接入就好，一共四步：');
+          SETUP_STEPS.forEach((s, i) => out.push('  ' + (i + 1) + '. ' + s));
+          return { text: out.join(NL) };
+        }
+        out.push(renderSyncCheck(g).join(NL));
+        out.push(renderLintProject(null, lintAllProjects(ws)).join(NL));
+      } else if (scope === "project") {
+        const name = args.project;
+        if (!name) throw new Error("scope=project 时必须给 project 参数");
+        const f = path.join(ws, "_Project_Meta", name, "Handover.md");
+        out.push(renderLintProject(name, [{ name, file: f, res: lintProject(f) }]).join(NL));
+      }
+      if (scope === "all" || scope === "global") {
+        const p = path.join(ws, "_Control_Center", "records", "Global_Handover.md");
+        out.push(renderLintGlobal(p, lintGlobal(p)).join(NL));
+      }
+      return { text: out.join(NL + NL) };
+    },
+  };
+}

package/src/tools/ho_handover.mjs

@@ -0,0 +1,83 @@
+/** ho_handover —— 读/写/追加/归档**本会话自己的**交接（路径按角色解析；写前备份、写后按角色体检）。 */
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { NL } from '../lib/text.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readHandover, writeHandover } from '../lib/handover-io.mjs';
+import { archiveDirFor } from '../lib/role.mjs';
+
+function noPath(input) {
+  const reason = input && input.reason ? input.reason : '未知原因';
+  return [
+    '没有可用的交接路径：' + reason,
+    '两条处置：',
+    '  ① 在设置页的 dsh-handover 中「会话角色」给本会话指定角色（项目角色要填项目名）；',
+    '  ② 临时显式传 path="<交接文件绝对路径>"。',
+    '（插件不再默认读全局交接——那是以前会串角色的老行为。）',
+  ].join(NL);
+}
+
+export function pmHandoverTool(env) {
+  return {
+    name: nameOf('handover'),
+    description:
+      '读写、追加、归档本会话自己的交接；写前备份、写后按角色体检。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['action'],
+      properties: {
+        action: { type: 'string', enum: ['read', 'write', 'append', 'archive'], description: 'read | write | append | archive' },
+        text: { type: 'string', description: 'write/append 时的正文（read/archive 忽略）' },
+        path: { type: 'string', description: '覆盖默认路径（演练或强制指定时用）' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const ws = env.resolveWs(exec);
+      const info = env.roleOf(exec);
+      const target = args.path
+        ? { path: args.path, kind: info.role === 'project' ? 'project' : info.role === 'misc' ? 'misc' : 'global', role: info.role, project: info.project, task: info.task }
+        : env.handoverFor(exec);
+      if (!target || !target.path) return { text: noPath(target) };
+
+      if (args.action === "read") {
+        const r = readHandover(target.path);
+        if (r.text === null) return { text: "交接文档不存在：" + target.path + NL + "（第一次写用 action=write 或 action=append）" };
+        return { text: r.text };
+      }
+      if (args.action === "archive") {
+        const src = readHandover(target.path);
+        if (src.text === null) throw new Error("要归档的交接不存在：" + target.path);
+        const d = new Date();
+        const p = (n) => (n < 10 ? "0" + n : "" + n);
+        const stampText = d.getFullYear() + p(d.getMonth() + 1) + p(d.getDate()) + "_" + p(d.getHours()) + p(d.getMinutes());
+        const dir = archiveDirFor(ws, info);
+        fs.mkdirSync(dir, { recursive: true });
+        const base = info.role === 'project' ? (info.project + '_Handover_') : info.role === 'misc' ? ((info.task || 'task') + '_Handover_') : 'Global_Handover_';
+        const dest = path.join(dir, base + stampText + ".md");
+        if (fs.existsSync(dest)) throw new Error("归档目标已存在，不覆盖：" + dest);
+        fs.copyFileSync(target.path, dest);
+        const a = crypto.createHash("sha256").update(fs.readFileSync(target.path)).digest("hex");
+        const b = crypto.createHash("sha256").update(fs.readFileSync(dest)).digest("hex");
+        const out = [];
+        out.push("已归档 " + dest + "（" + fs.statSync(dest).size + " B）");
+        out.push("sha256 " + (a === b ? "一致 " + a.slice(0, 16) + "…" : "**不一致，归档失败**"));
+        return { text: out.join(NL) };
+      }
+      if (args.action !== "write" && args.action !== "append") {
+        throw new Error("未知 action：" + String(args.action) + "（只能是 read | write | append | archive）");
+      }
+      if (typeof args.text !== "string" || args.text.trim() === "") throw new Error("write/append 需要 text");
+      const res = writeHandover(ws, target.path, args.text, args.action === "append" ? "append" : "write", { kind: target.kind, info });
+      const out = [];
+      out.push("已写入 " + res.path + "（" + res.bytes + " B）· 角色 " + info.role + (target.kind !== 'global' ? "（" + (info.project || info.task) + "）" : ""));
+      out.push("备份 " + (res.backup || "（原文件不存在，无需备份）"));
+      out.push("体检 " + res.verdict + (res.reasons.length ? "" : " · 结构齐备"));
+      for (const r of res.reasons) out.push("  - " + r);
+      return { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_init.mjs

@@ -0,0 +1,82 @@
+/**
+ * ho_init —— 首次安装：在用户给的目录里建「全局文件体系」，可选顺带注册为工作区。
+ * 与设置页的「首次安装向导」同一套实现（lib/scaffold.mjs），因此两条路径行为一致。
+ */
+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 { createGlobalWorkspace } from '../lib/scaffold.mjs';
+
+export function pmInitTool(env) {
+  return {
+    name: nameOf('init'),
+    description:
+      '首次安装：在指定目录（不存在会创建）下建全局文件体系（根为 <目录>/_Workspace），可顺带注册工作区。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['parent'],
+      properties: {
+        parent: { type: 'string', description: '目标父目录绝对路径（不存在会创建）；全局根建在它里面' },
+        name: { type: 'string', description: '全局根目录名，默认 _Workspace' },
+        register: { type: 'boolean', description: '建好后顺带注册为工作区（默认 false）' },
+        title: { type: 'string', description: 'register 时的工作区标题，默认「全局」' },
+      },
+    },
+    output: textOutput(),
+    async execute(args) {
+      const r = createGlobalWorkspace(args.parent, { name: args.name });
+      const out = [];
+      if (!r.ok) {
+        out.push('未建立：' + r.error);
+        if (r.root) out.push('目标：' + r.root);
+        out.push('');
+        out.push('用法：ho_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) {
+        const reg = env.registry();
+        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) };
+    },
+  };
+}

package/src/tools/ho_pack.mjs

@@ -0,0 +1,38 @@
+/** ho_pack —— 打包族：action=check（前置闸门）、pack（打包）、verify（校包）、restore（默认预演）。 */
+import { textOutput } from '../lib/output.mjs';
+import { nameOf } from '../lib/names.mjs';
+import { packCheck, packNow, packVerify, packRestore } from '../lib/pack-ops.mjs';
+
+export function pmPackTool(env) {
+  return {
+    name: nameOf('pack'),
+    description: '迁移包四合一：check 前置闸门、pack 打包、verify 校包、restore 恢复（默认预演）。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ['check', 'pack', 'verify', 'restore'], description: '缺省 pack' },
+        kind: { type: 'string', enum: ['project', 'task', 'global'], description: 'pack 的目标类型' },
+        name: { type: 'string', description: 'pack 的项目名、任务名' },
+        out: { type: 'string', description: 'pack 的输出目录' },
+        note: { type: 'string', description: 'pack 写进 MIGRATION.md 的说明' },
+        items: { type: 'array', items: { type: 'string' }, description: 'check 检查的项目名（global 表示全局）' },
+        min_age_min: { type: 'number', description: 'check 要求静止分钟（默认 90）' },
+        pack: { type: 'string', description: 'verify/restore 的包路径' },
+        target: { type: 'string', description: 'restore 的目标根（默认当前）' },
+        apply: { type: 'boolean', description: 'restore 时 true 才写入' },
+        dry_run: { type: 'boolean', description: 'pack 只列清单；restore 只预演' },
+        format: { type: 'string', enum: ['auto', '7z', 'tar'], description: 'pack 的归档格式：auto＝有 7-Zip 用 7z，否则内置 tar.gz（默认）' },
+      },
+    },
+    output: textOutput(),
+    async execute(args, exec) {
+      const action = typeof args.action === 'string' && args.action ? args.action : 'pack';
+      if (action === 'check') return { text: packCheck(env, args, exec) };
+      if (action === 'verify') return { text: packVerify(env, args, exec) };
+      if (action === 'restore') return { text: packRestore(env, args, exec) };
+      if (action !== 'pack') throw new Error('未知 action：' + action + '（check、pack、verify、restore）');
+      return { text: packNow(env, args, exec) };
+    },
+  };
+}

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) };
+    },
+  };
+}