@mingmaple/dsh-handover 0.9.14 → 1.0.0

package/src/tools/ho_checkpoint.mjs

@@ -2,33 +2,34 @@
 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 { readHandover, rewriteHandover } 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';
+import { markSkipNext } from '../lib/reminder.mjs';
 
 export function pmCheckpointTool(env) {
   return {
     name: nameOf('checkpoint'),
     description:
-      '写交接、登记压缩；回合结束后自动压缩。resume=continue（默认）压缩后续跑；resume=wait 表示任务已收尾，压缩后不唤醒。',
+      '写交接、登记压缩；回合结束后自动压缩。resume=continue（缺省）表示压缩后续跑；resume=wait 表示任务已收尾，压缩后不唤醒。',
     parameters: {
       type: 'object',
       additionalProperties: false,
       properties: {
         handover_text: { type: 'string', description: '要写入的交接正文；不给则要求磁盘上已有合格交接' },
         handover_path: { type: 'string', description: '覆盖交接路径（演练用）' },
-        resume: { type: 'string', enum: ['continue', 'wait'], description: '压缩后的去向：continue（默认）按交接 §2 继续；wait 表示本轮任务已收尾，压缩后不唤醒，等用户派新任务' },
-        at_risk: { type: 'boolean', description: '当前处在关键步骤：为 true 时，水位在提醒线～交接线之间只提醒、不压缩（过交接线仍会压）' },
+        resume: { type: 'string', enum: ['continue', 'wait'], description: '压缩后的去向：continue（缺省）按交接 §2 继续；wait 表示本轮任务已收尾，压缩后不唤醒，等待当前用户派新任务' },
+        at_risk: { type: 'boolean', description: '当前处在关键步骤：为 true 时，水位在提醒线与交接线之间只提醒、不压缩（过交接线仍压缩）' },
         force: { type: 'boolean', description: '忽略关键步骤判定，直接排压缩' },
-        confirm: { type: 'boolean', description: '判定为「可压缩」后须经用户同意才传 true；还需用户在设置页点「允许压缩」（5 分钟一次性授权），否则不排压缩' },
+        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，无法调度压缩");
+      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' }
@@ -37,7 +38,7 @@ export function pmCheckpointTool(env) {
         return { text: [
           '没有可用的交接路径：' + (target && target.reason ? target.reason : '未知'),
           '先指定角色（设置页的 dsh-handover 中「会话角色」），或显式传 handover_path="<交接文件绝对路径>"。',
-          '压缩会丢历史，没有合格交接就不排压缩。',
+          '压缩会丢失历史；没有合格交接，不排压缩。',
         ].join(NL) };
       }
       const file = target.path;
@@ -46,55 +47,56 @@ export function pmCheckpointTool(env) {
       const self = env.selfPct(meId);
       const ratio = self === null ? null : self / 100;
       const out = [];
+      const ratioText = ratio === null ? '读不到' : (Math.round(ratio * 1000) / 10).toFixed(1) + '%';
       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。");
+        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 复查；若长时间不动，说明上次压缩崩在中间。");
+        out.push("处置：等当前压缩结束后用 ho_status 复查；若长时间无变化，说明上次压缩中途失败。");
         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") 建新会话。');
+        out.push('下一步：按固定流程写交接。① ho_handover(action="read") 读旧交接；② action="archive" 归档；③ 读模板 _Control_Center/templates/Handover.md；④ action="new" 新建空白写入。之后由全局 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）。");
+      if (args.at_risk === true && args.force !== true && ratio !== null && ratio < (env.cfg.hardRatio || 0.85)) {
+        out.push("已暂缓（关键步骤）：水位 " + ratioText + "，先完成当前小步骤再压缩；到阶段边界再调用一次 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。");
+        out.push("水位未到可压缩线（" + ratioText + "）：不压缩。");
+        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)；不同意就保持原样。');
+        out.push('水位 ' + ratioText + '，已压缩 ' + count.used + '/' + env.cfg.maxCompactions + '。');
+        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);
+        wrote = rewriteHandover(ws, file, args.handover_text, { kind: target.kind, info });
+        out.push("交接已写入 " + file + "（" + wrote.bytes + " B）· 角色 " + info.role);
+        if (wrote.archived) out.push("旧交接已归档 " + wrote.archived.dest + "（sha256 一致）");
         out.push("体检 " + wrote.verdict + (wrote.reasons.length ? "：" : " · 结构齐备"));
         for (const r of wrote.reasons) out.push("  - " + r);
         if (wrote.verdict !== "通过") {
-          out.push("体检不通过 ⇒ 不排压缩（先补结构，压缩后就没机会改了）。");
+          out.push("体检未通过，不排压缩（先补齐结构；压缩后无法再改）。");
           return { text: out.join(NL) };
         }
       } else {
         const cur = readHandover(file);
         if (cur.text === null || cur.text.trim() === "") {
           out.push("没有交接正文，磁盘上也没有：" + file);
-          out.push("拒绝压缩 —— 压缩会丢历史，必须先有交接。");
+          out.push("拒绝压缩：压缩会丢失历史，必须先有交接。");
           return { text: out.join(NL) };
         }
         out.push("沿用磁盘上已有交接：" + file);
@@ -104,28 +106,30 @@ export function pmCheckpointTool(env) {
       // 会话自行判断水位与询问用户，用户点授权后自行排压缩，不必上报全局。
       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 自行填写——惟有用户在设置页当面点击的那一次，方视为同意。');
+        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) + '% —— 属于提前压缩，会白付一次摘要调用，且本轮前缀缓存失效。');
+        out.push('成本提示：当前水位 ' + (Math.round(ratio * 1000) / 10) + '% 低于可压缩线 ' + Math.round(handoverRatio * 100) + '%，属提前压缩，会多付一次摘要调用，且本轮前缀缓存失效。');
       }
       consumedConsent(meId);
+      // 压缩后第一轮的水位读数是压缩前的旧投影，跳过那一轮提醒判定，免得用虚高读数用掉一次性提醒。
+      markSkipNext(meId);
       const n = count.used + 1;
       const resume = args.resume === 'wait' ? 'wait' : 'continue';
       env.schedule(meId, n, { resume });
-      out.push('用户已授权（' + cs.atText + ' 点击，剩 ' + Math.round(cs.leftMs / 1000) + ' 秒）。');
-      out.push("已登记压缩（第 " + n + "/" + env.cfg.maxCompactions + " 次）。本回合结束后执行。");
+      out.push('当前用户已授权（' + cs.atText + ' 点击，剩余 ' + Math.round(cs.leftMs / 1000) + ' 秒）。');
+      out.push("已登记压缩（第 " + n + "/" + env.cfg.maxCompactions + " 次），本回合结束后执行。");
       if (resume === 'wait') {
-        out.push("去向：wait —— 压缩完成后不会唤醒本会话，等你派新任务。");
+        out.push("去向：wait —— 压缩完成后不唤醒本会话，等待当前用户派新任务。");
       } else {
-        out.push("去向：continue —— 压缩完成后自动收到续跑消息；若 60 秒内没有续跑消息，用 ho_phase 看状态。");
+        out.push("去向：continue —— 压缩完成后自动收到续跑消息；若 60 秒内未收到续跑消息，用 ho_status 查看状态。");
       }
-      out.push("压缩期间不要结束会话。");
+      out.push("压缩期间不得结束会话。");
       return { text: out.join(NL) };
     },
   };

package/src/tools/ho_docmap.mjs

@@ -0,0 +1,239 @@
+/**
+ * ho_docmap —— 体系注册与文档定位（1.0）。
+ *
+ * 动作：read 读、write 写、check 校验路径、plan 读写与归档行动计划。
+ * 写入范围由会话已登记的角色决定：全局只写总注册，项目只写本项目注册，杂项只写本任务注册。
+ * 写入者必须是在任会话（以 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, registryRelPath, registryAbsPath, readRegistry, readGlobalRegistry,
+  validateEntries, checkRegistries, writeRegistry, syncGlobalRefs,
+  planRelPath, readPlan, writePlan, archivePlan, pointRegistryToPlan,
+  GLOBAL_REGISTRY_REL, REGISTRY_NAME,
+} from '../lib/system.mjs';
+import { taskNameOk } from '../lib/role.mjs';
+
+export const ACTIONS = ['read', 'write', 'check', 'plan'];
+
+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 '（空：不注入正文）';
+  return entries.map((e) => '- ' + e.path + (e.about ? ' —— ' + e.about : '') + (e.when ? '（' + e.when + '）' : '')).join(NL);
+}
+
+function targetInfoFor(info, task) {
+  if (info && info.role === 'global') {
+    const t = String(task || '').trim();
+    if (!t) return null;
+    if (!taskNameOk(t)) throw new Error('任务名不合法（当目录名用）：' + t);
+    return { role: 'global-task', task: t };
+  }
+  return info;
+}
+
+function nodePath(ws, ...parts) {
+  return path.join(String(ws || ''), ...parts);
+}
+
+export function pmDocmapTool(env) {
+  return {
+    name: nameOf('docmap'),
+    description:
+      '体系注册与文档定位：read 读、write 写（逐条校验路径存在）、check 校验、plan 读写并归档行动计划；全局总注册只列路径，全局任务用 task 读写自身注册与计划。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ACTIONS, description: '缺省 read' },
+        entries: {
+          type: 'array',
+          description: 'write：整份替换。每项 { path: 工作区相对路径, about: 用途, when: 读取时机, section: structure|files }；section 缺省 files',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['path', 'about'],
+            properties: {
+              path: { type: 'string', description: '工作区相对路径，必须存在' },
+              about: { type: 'string', description: '用途，一句话' },
+              when: { type: 'string', description: '读取时机（可选）' },
+              section: { type: 'string', enum: ['structure', 'files'], description: '目录结构或规范文件（缺省 files）' },
+            },
+          },
+        },
+        mode: { type: 'string', enum: ['read', 'write', 'archive'], description: 'action=plan 时的动作，缺省 read' },
+        text: { type: 'string', description: 'action=plan、mode=write 时的行动计划正文' },
+        task: { 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 label = lineageLabel(info);
+      const meId = String(env.selfId(exec) || '');
+
+      if (action === 'read') {
+        const taskName = String(args.task || '').trim();
+        if (lin.kind === 'global' && taskName) {
+          const target = targetInfoFor(info, taskName);
+          const reg = readRegistry(ws, target);
+          const rel = registryRelPath(target);
+          const out = ['体系注册（' + lineageLabel(target) + '）  ' + rel];
+          out.push(reg.exists ? '状态  已设置，目录 ' + reg.data.structure.length + ' 条、规范 ' + reg.data.files.length + ' 条' : '状态  未设置');
+          if (reg.data.plan) out.push('计划  ' + reg.data.plan);
+          if (reg.data.structure.length) out.push('', '目录结构：', entriesText(reg.data.structure));
+          if (reg.data.files.length) out.push('', '规范文件：', entriesText(reg.data.files));
+          return { text: out.join(NL) };
+        }
+        if (lin.kind === 'global') {
+          const g = readGlobalRegistry(ws);
+          const out = ['体系注册（全局）  ' + GLOBAL_REGISTRY_REL, g.rows.length ? '任务 ' + g.rows.length + ' 个' : '暂无任务注册'];
+          for (const r of g.rows) out.push('  ' + r.kind + '「' + r.task + '」  ' + r.path);
+          return { text: out.join(NL) };
+        }
+        const reg = readRegistry(ws, info);
+        const rel = registryRelPath(info);
+        const out = ['体系注册（' + label + '）  ' + rel];
+        out.push(reg.exists ? '状态  已设置，目录 ' + reg.data.structure.length + ' 条、规范 ' + reg.data.files.length + ' 条' : '状态  未设置（空注册只注入一句提示）');
+        if (reg.data.plan) out.push('计划  ' + reg.data.plan);
+        if (reg.data.structure.length) out.push('', '目录结构：', entriesText(reg.data.structure));
+        if (reg.data.files.length) out.push('', '规范文件：', entriesText(reg.data.files));
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'check') {
+        const res = lin.kind === 'global' ? checkRegistries(ws) : checkRegistries(ws, info);
+        const out = ['体系注册体检  ' + (lin.kind === 'global' ? '全部任务' : label)];
+        if (!res.rows.length) out.push('  尚无任何任务注册（空注册不注入正文，属正常）');
+        for (const r of res.rows) {
+          out.push('  ' + r.label + '  ' + r.rel + '  ' + (r.exists ? r.entries + ' 条' : '未设置') + '  ' + (r.bad.length ? '失效 ' + r.bad.length + ' 条' : '路径全部存在'));
+          for (const b of r.bad.slice(0, 5)) out.push('        失效：' + b.path + ' —— ' + b.problem);
+        }
+        out.push(res.missing ? '判定：' + res.missing + ' 条路径失效，由该类别在任会话用 ho_docmap(action="write") 更新。' : '判定：路径全部存在。');
+        return { text: out.join(NL) };
+      }
+
+      if (action === 'plan') {
+        const mode = typeof args.mode === 'string' && args.mode ? args.mode : 'read';
+        let target = null;
+        try { target = targetInfoFor(info, args.task); } catch (e) { throw e; }
+        if (!target) throw new Error('全局会话读写计划时须给 task（任务名）');
+        const rel = planRelPath(ws, target);
+        if (!rel) throw new Error('没有可用的计划路径：角色未定');
+        if (mode === 'read') {
+          const p = readPlan(ws, target);
+          if (!p.exists) return { text: '计划未建立：' + rel + NL + '层二任务应先写行动计划，模板见 _Control_Center/templates/Plan.skeleton.md。' };
+          if (p.error) throw new Error(p.error);
+          return { text: p.text };
+        }
+        if (mode === 'archive') {
+          const archived = archivePlan(ws, target);
+          return { text: archived ? '旧计划已归档：' + archived : '没有可归档的旧计划：' + rel };
+        }
+        const text = String(args.text || '');
+        if (!text.trim()) throw new Error('mode=write 需要 text（行动计划正文）');
+        const r = writePlan(ws, target, text);
+        let pointed = false;
+        try { pointed = pointRegistryToPlan(ws, target); } catch { pointed = false; }
+        let refreshed = false;
+        try { refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+        const out = ['已写入计划 ' + r.rel + '（' + r.bytes + ' B）' + (r.archived ? '；旧计划已归档 ' + r.archived : '；无旧计划')];
+        out.push(pointed ? '注册已指向该计划。' : '本任务尚无体系注册，写入注册后再指向计划。');
+        out.push(refreshed ? '提示段已重装。' : '提示段未能当场重装：下一轮或重启后生效。');
+        return { text: out.join(NL) };
+      }
+
+      // action=write
+      const holder = holderOf(ws, lin);
+      if (!holder.current) {
+        throw new Error('名册里没有「' + (holder.key || label) + '」的在任记录：以在任记录为写入依据，先完成名称注册（ho_office action="register"）');
+      }
+      if (!meId || String(holder.current.sessionId || '') !== meId) {
+        throw new Error('只有在任会话可以写：本条登记的在任会话为 ' + (holder.current.name || '?') + '（' + holder.current.sessionId + '），本会话为只读');
+      }
+
+      if (lin.kind === 'global' && !String(args.task || '').trim()) {
+        const g = syncGlobalRefs(ws);
+        let refreshed = false;
+        try { refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+        const out = ['已按磁盘任务重建全局总注册 ' + GLOBAL_REGISTRY_REL + '（' + g.rows.length + ' 个任务）'];
+        for (const r of g.rows) out.push('  ' + r.kind + '「' + r.task + '」  ' + r.path);
+        out.push(refreshed ? '提示段已重装：下一轮即注入引用清单。' : '提示段未能当场重装：重启 DSH 或让会话重建后生效。');
+        return { text: out.join(NL) };
+      }
+
+      // 全局任务：由全局会话直接维护该任务的体系注册。
+      const writeInfo = lin.kind === 'global'
+        ? targetInfoFor(info, String(args.task || '').trim())
+        : info;
+      if (!writeInfo) throw new Error('全局会话写任务注册时需要 task（任务名）');
+      const list = Array.isArray(args.entries) ? args.entries : null;
+      if (!list) throw new Error('write 需要 entries 数组（每项 path、about、when、section）');
+      const structure = [];
+      const files = [];
+      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();
+        const section = e.section === 'structure' ? 'structure' : 'files';
+        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 + ' 里不能换行');
+        }
+        (section === 'structure' ? structure : files).push({ path: p, about, when });
+      }
+      const bad = validateEntries(ws, structure.concat(files));
+      if (bad.length) {
+        const lines = ['未写入：下列路径不存在或不合法，逐条修正后重试。'];
+        for (const b of bad) lines.push('  - ' + b.path + '：' + b.problem);
+        lines.push('路径一律写工作区相对路径（例：Projects/<项目>/README.md）。');
+        throw new Error(lines.join(NL));
+      }
+      const cur = readRegistry(ws, writeInfo);
+      const plan = cur.data.plan || '';
+      if (plan) {
+        const problem = validateEntries(ws, [{ path: plan }]);
+        if (problem.length) throw new Error('注册里的计划路径已失效：' + plan + NL + '先修正计划（ho_docmap action="plan"）或删除该行。');
+      }
+      const r = writeRegistry(ws, writeInfo, { structure, files, plan });
+      if (lin.kind === 'global') syncGlobalRefs(ws);
+      let refreshed = false;
+      try { refreshed = env.refreshPromptFor(meId) === true; } catch { refreshed = false; }
+      const out = [];
+      out.push('已写入 ' + registryRelPath(writeInfo) + '（目录 ' + structure.length + ' 条、规范 ' + files.length + ' 条）'
+        + (r.backup ? '；原文件备份为 ' + path.basename(r.backup) : ''));
+      out.push(refreshed ? '提示段已重装：下一轮即按新注册注入。' : '提示段未能当场重装：重启 DSH 或让会话重建后生效。');
+      out.push('只给路径与用途；不设字数上限，但过长的用途会挤占提示段。');
+      return { text: out.join(NL) };
+    },
+  };
+}

package/src/tools/ho_gate.mjs

@@ -4,8 +4,9 @@ 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 { legacyInfo } from '../lib/legacy.mjs';
 import { SETUP_STEPS } from '../lib/guide.mjs';
 
 function lintAllProjects(ws) {
@@ -26,12 +27,12 @@ export function pmGateTool(env) {
   return {
     name: nameOf('gate'),
     description:
-      '通用约束条闸门（按库型判定）＋交接文档体检。只读。',
+      '通用约束条闸门（按库型判定）、交接文档体检与体系注册路径检查。只读。',
     parameters: {
       type: 'object',
       additionalProperties: false,
       properties: {
-        scope: { type: 'string', enum: ['all', 'global', 'project'], description: '默认 all' },
+        scope: { type: 'string', enum: ['all', 'global', 'project'], description: '缺省 all' },
         project: { type: 'string', description: 'scope=project 时的项目名' },
       },
     },
@@ -47,15 +48,20 @@ export function pmGateTool(env) {
         const g = syncCheck(ws);
         if (g.noWorkspace) {
           out.push('通用约束条闸门：未接入工作区（' + g.path + '）');
-          out.push('把工作区接入就好，一共四步：');
+          out.push('接入工作区共 4 步：');
           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));
+        out.push(renderDocmapCheck(docmapReport(ws)).join(NL));
+        try {
+          const legacy = legacyInfo(ws);
+          if (legacy.exists) out.push('旧文档定位待迁移：' + legacy.dir + '（ho_workspace action="migrate"）');
+        } catch { /* 旧目录检查失败不影响闸门 */ }
       } else if (scope === "project") {
         const name = args.project;
-        if (!name) throw new Error("scope=project 时必须给 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));
       }

package/src/tools/ho_handover.mjs

@@ -1,21 +1,19 @@
-/** ho_handover —— 读/写/追加/归档**本会话自己的**交接（路径按角色解析；写前备份、写后按角色体检）。 */
+/** 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, archiveStamp, archiveFileName } from '../lib/handover-io.mjs';
-import { archiveDirFor } from '../lib/role.mjs';
+import { readHandover, writeHandover, rewriteHandover, archiveHandover } from '../lib/handover-io.mjs';
+import { assertTaskName } from '../lib/role.mjs';
 
 function noPath(input) {
   const reason = input && input.reason ? input.reason : '未知原因';
   return [
     '没有可用的交接路径：' + reason,
-    '两条处置：',
-    '  ① 在设置页的 dsh-handover 中「会话角色」给本会话指定角色（项目角色要填项目名）；',
+    '处置：',
+    '  ① 在设置页的 dsh-handover 中「会话角色」给本会话指定角色（项目角色须填项目名）；',
     '  ② 临时显式传 path="<交接文件绝对路径>"。',
-    '（插件不再默认读全局交接——那是以前会串角色的老行为。）',
+    '（插件不再默认读全局交接：旧版行为会导致角色串用。）',
   ].join(NL);
 }
 
@@ -23,58 +21,86 @@ export function pmHandoverTool(env) {
   return {
     name: nameOf('handover'),
     description:
-      '读写、追加、归档本会话自己的交接；写前备份、写后按角色体检。',
+      '读写、新建、追加、归档交接；整篇重写用 new（先归档旧交接，再新建空白文件写入）；项目与杂项会话读写自己的交接，全局会话可用 task 指向某个全局任务。写后按角色体检。',
     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 忽略）' },
+        action: { type: 'string', enum: ['read', 'new', 'write', 'append', 'archive'], description: 'read | new（整篇重写：归档旧交接后新建空白写入）| write（仅首次创建）| append | archive' },
+        text: { type: 'string', description: 'new/write/append 时的正文（read/archive 忽略）' },
         path: { type: 'string', description: '覆盖默认路径（演练或强制指定时用）' },
+        task: { type: 'string', description: '全局会话读写某个全局任务的交接：_Control_Center/tasks/<任务>/Handover.md' },
       },
     },
     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);
+      const taskName = String(args.task || '').trim();
+      let target = null;
+      if (taskName) {
+        if (info.role !== 'global') throw new Error('task 参数只对全局会话开放');
+        assertTaskName(taskName);
+        target = {
+          path: path.join(ws, '_Control_Center', 'tasks', taskName, 'Handover.md'),
+          kind: 'project', role: 'global-task', task: taskName,
+        };
+      } else {
+        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) };
+      const archiveOpts = taskName
+        ? {
+            info: { role: 'misc', task: taskName },
+            archiveDir: path.join(ws, '_Archives', '_Global', 'tasks', taskName, 'Handover'),
+          }
+        : { kind: target.kind, info };
+      const snapOpts = taskName
+        ? { kind: target.kind, info: { role: 'misc', task: taskName }, snapshotDir: path.join(ws, '_Temp', '_Global', 'tasks', taskName, 'Snapshots') }
+        : { kind: target.kind, info };
 
       if (args.action === "read") {
         const r = readHandover(target.path);
-        if (r.text === null) return { text: "交接文档不存在：" + target.path + NL + "（第一次写用 action=write 或 action=append）" };
+        if (r.text === null) return { text: "交接文档不存在：" + target.path + NL + "（首次创建用 action=write；整篇重写用 action=new）" };
         return { text: r.text };
       }
       if (args.action === "archive") {
-        const src = readHandover(target.path);
-        if (src.text === null) throw new Error("要归档的交接不存在：" + target.path);
-        const stampText = archiveStamp(new Date());
-        const dir = archiveDirFor(ws, info);
-        fs.mkdirSync(dir, { recursive: true });
-        // 命名按 Handover_Rules §4.2：<原文件名>_<YYYYMMDD_HHMMSS>.md；同一秒重复归档加 -2、-3。
-        let dest = path.join(dir, archiveFileName(target.path, stampText));
-        for (let n = 2; fs.existsSync(dest) && n < 100; n++) {
-          dest = path.join(dir, archiveFileName(target.path, stampText + "-" + n));
-        }
-        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");
+        if (!readHandover(target.path).text) throw new Error("要归档的交接不存在：" + target.path);
+        const a = archiveHandover(ws, target.path, archiveOpts);
+        return { text: "已归档 " + a.dest + "（" + a.bytes + " B）" + NL + "sha256 一致 " + a.sha256.slice(0, 16) + "…" };
+      }
+      if (args.action === "new") {
+        if (typeof args.text !== "string" || args.text.trim() === "") throw new Error("new 需要 text");
+        const res = rewriteHandover(ws, target.path, args.text, Object.assign({}, snapOpts, archiveOpts));
         const out = [];
-        out.push("已归档 " + dest + "（" + fs.statSync(dest).size + " B）");
-        out.push("sha256 " + (a === b ? "一致 " + a.slice(0, 16) + "…" : "**不一致，归档失败**"));
+        out.push(res.archived
+          ? (res.archived.reused
+            ? "已归档（复用内容相同的副本）" + res.archived.dest + "（" + res.archived.bytes + " B）"
+            : "已归档 " + res.archived.dest + "（" + res.archived.bytes + " B，sha256 一致）")
+          : "原交接不存在，直接新建（无需归档）");
+        out.push("已新建 " + res.path + "（" + res.bytes + " B）· 角色 " + (taskName ? 'global-task' : info.role) + (taskName ? " · 任务「" + taskName + "」" : ""));
+        out.push("体检 " + res.verdict + (res.reasons.length ? "" : " · 结构齐备"));
+        for (const r of res.reasons) out.push("  - " + r);
+        if (res.verdict !== "通过") out.push("提示：修正后重跑 action=new（将再次归档当前文件）。");
         return { text: out.join(NL) };
       }
       if (args.action !== "write" && args.action !== "append") {
-        throw new Error("未知 action：" + String(args.action) + "（只能是 read | write | append | archive）");
+        throw new Error("未知 action：" + String(args.action) + "（只能是 read | new | write | append | archive）");
+      }
+      if (typeof args.text !== "string" || args.text.trim() === "") throw new Error(args.action + " 需要 text");
+      if (args.action === "write" && readHandover(target.path).text) {
+        throw new Error(
+          "交接已存在，不能用 write 改写：" + target.path + NL
+          + "整篇重写按固定流程：① ho_handover(action=\"read\") 读旧交接；② ho_handover(action=\"archive\") 归档；③ 读模板 _Control_Center/templates/Handover.md；④ ho_handover(action=\"new\", text=…) 新建空白写入。",
+        );
       }
-      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 res = writeHandover(ws, target.path, args.text, args.action, snapOpts);
       const out = [];
-      out.push("已写入 " + res.path + "（" + res.bytes + " B）· 角色 " + info.role + (target.kind !== 'global' ? "（" + (info.project || info.task) + "）" : ""));
+      const scope = taskName ? '全局任务「' + taskName + '」' : (target.kind !== 'global' ? '（' + (info.project || info.task) + '）' : '');
+      out.push("已写入 " + res.path + "（" + res.bytes + " B）· 角色 " + (taskName ? 'global-task' : info.role) + scope);
       out.push("备份 " + (res.backup || "（原文件不存在，无需备份）"));
       out.push("体检 " + res.verdict + (res.reasons.length ? "" : " · 结构齐备"));
       for (const r of res.reasons) out.push("  - " + r);