@mingmaple/dsh-handover 0.9.14 → 1.0.0

package/src/lib/global-task.mjs

@@ -0,0 +1,69 @@
+/**
+ * 全局任务库：`_Control_Center/tasks/<任务>/`。
+ * 全局可同时承担多个任务，每个任务有独立交接、体系注册与计划；任务可整体独立为项目或杂项会话。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { NL, readUtf8, isFile, isDir } from './text.mjs';
+import { assertTaskName } from './role.mjs';
+import { renderRegistry, syncGlobalRefs } from './system.mjs';
+
+const HANDOVER = [
+  '# 交接（全局任务）',
+  '',
+  '## 1. 正在做的事',
+  '',
+  '未开始；由全局会话在任务启动时补写。',
+  '',
+  '## 2. 下一步',
+  '',
+  '- 待定。',
+  '',
+].join(NL);
+
+function copyIf(src, dst) {
+  if (!isFile(src) || fs.existsSync(dst)) return false;
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+  fs.copyFileSync(src, dst);
+  return true;
+}
+
+/**
+ * 建立全局任务库：目录、交接、体系注册、规则与模板副本；随后重建全局总注册。
+ * @returns {{ dir: string, created: string[] }}
+ */
+export function createGlobalTask(ws, task) {
+  const name = String(task || '').trim();
+  assertTaskName(name);
+  const dir = path.join(String(ws || ''), '_Control_Center', 'tasks', name);
+  if (isDir(dir) && fs.readdirSync(dir).length) throw new Error('全局任务已存在且非空：' + dir);
+  fs.mkdirSync(path.join(dir, '_archive'), { recursive: true });
+  const created = [];
+  const files = [
+    ['Handover.md', HANDOVER],
+    ['System.md', renderRegistry({ role: 'global-task', task: name }, { structure: [], files: [], plan: '' })],
+  ];
+  for (const [rel, body] of files) {
+    const dst = path.join(dir, rel);
+    if (fs.existsSync(dst)) continue;
+    fs.writeFileSync(dst, body, 'utf8');
+    created.push(rel);
+  }
+  // 暂任规范与交接规范随任务库独立，避免暂任方跨库读取全局规则。
+  const rules = path.join(String(ws || ''), '_Control_Center', 'rules');
+  for (const rel of ['Delegation_Rules.md', 'Handover_Rules.md']) {
+    if (copyIf(path.join(rules, rel), path.join(dir, rel))) created.push(rel);
+  }
+  const tpl = path.join(String(ws || ''), '_Control_Center', 'templates');
+  for (const rel of ['Plan.skeleton.md', 'System.skeleton.md']) {
+    if (copyIf(path.join(tpl, rel), path.join(dir, rel))) created.push(rel);
+  }
+  syncGlobalRefs(ws);
+  return { dir, created };
+}
+
+/** 读全局任务交接正文（不存在返回空串）。 */
+export function readTaskHandover(ws, task) {
+  const file = path.join(String(ws || ''), '_Control_Center', 'tasks', String(task || ''), 'Handover.md');
+  try { return readUtf8(file); } catch { return ''; }
+}

package/src/lib/guide.mjs

@@ -1,7 +1,7 @@
 /**
- * 设置页「使用说明」的内容：面向人，不面向模型。
+ * 设置页「使用说明」与「工具明细」的内容：面向人，不面向模型。
  * 数据放宿主侧，客户端只负责渲染——改文案不用动客户端 bundle。
- * 行文用标准书面语：不用口语化的示例句，示例一律写成可以直接提的要求。
+ * 行文用标准书面语：示例一律写成可以直接提出的要求。
  * 水位与工具数由 facts.mjs、names.mjs 推导，不在这里重复写死。
  */
 import { compactSummaryText, watermark } from './facts.mjs';
@@ -9,11 +9,11 @@ import { ALL_TOOL_NAMES } from './names.mjs';
 
 /** 首次安装、尚未接入工作区时的下一步（设置页与工具输出共用同一份）。 */
 export const SETUP_STEPS = [
-  '准备一个长期存在的目录作为全局根的上级目录，不要选临时目录或下载目录。',
-  '在本页下方的输入框中粘贴该目录的绝对路径，点「一键部署」：插件会在其中建立 _Workspace 与整套结构，注册为「全局」工作区，并新建一个「全局」会话。',
-  '在左侧「全局」工作区中打开新会话即可开始。若只想先铺文件，可点「仅建立文件体系」，之后再注册工作区。',
-  '工作区已接入但还没有全局会话时，本页会单独出现「全局会话」卡片，可随时补建。',
-  '新建项目或杂项会话时，应当指明目标工作区；找不到工作区时，插件会把已注册的工作区列出来，不会静默落到别处。',
+  '准备一个长期保留的目录，作为全局根的上级目录；不得选用临时目录或下载目录。',
+  '在本页下方的输入框中填写该目录的绝对路径，再点击「一键部署」。插件将在其中建立 _Workspace 与整套结构，注册为「全局」工作区，并新建一个「全局」会话。',
+  '在左侧「全局」工作区中打开新会话，即可开始。若只需先建立文件体系，可点击「仅建立文件体系」，之后再注册工作区。',
+  '工作区已接入但尚无全局会话时，本页会单独显示「全局会话」卡片，可随时补建。',
+  '新建项目或杂项会话时，应指明目标工作区；找不到工作区时，插件会列出已注册的工作区，不会静默落到其他位置。',
 ];
 
 export function buildGuide(cfg) {
@@ -21,84 +21,80 @@ export function buildGuide(cfg) {
   const compact = compactSummaryText(cfg);
   const toolCount = ALL_TOOL_NAMES.length;
   return {
-  intro: [
-    '本插件的全部功能都在对话中调用：不必记命令，也不必操作菜单，用中文说明要做的事，全局会话会选择相应的工具执行。',
-    '工具与提示按会话角色载入：全局会话可见全部 ' + toolCount + ' 个工具，项目与杂项会话只载入自己需要的几个，普通会话不载入插件工具，也不注入提示段。角色在下方「会话角色」中指定。',
-    '本页除首次安装、全局前置提示词与会话角色外均为只读；需要最新读数时，点击右上角的「刷新」。',
-  ],
-  situations: [
-    { when: '首次安装', say: '部署全局文件体系', what: '本页「一键部署」可一次完成三件事：建文件体系、注册「全局」工作区、建「全局」会话' },
-    { when: '作业开始与结束', say: '先出一份起始简报', what: '汇总上下文水位、通用约束条闸门、会话清点与阶段建议（ho_brief）' },
-    { when: '查阅规则', say: '把 Charter 第 7.2.3 节取出来', what: '按节返回规则正文，避免整篇读取（ho_charter；完整流程用 doc="runtime"）' },
-    { when: '交接与压缩续跑', say: '先把交接文档写好，再压缩并继续', what: '写自己角色的交接、体检、登记压缩，并由助手选择压缩后去向：继续工作时用 resume=continue，任务已收尾时用 resume=wait（压缩后不唤醒）（ho_handover、ho_checkpoint）' },
-    { when: '接近上下文上限', say: '查一下本会话的上下文水位', what: compact + '（ho_phase）' },
-    { when: '换任', say: '让在任会话自己完成换任', what: '用户先发送 /allow-succeed 授权，在任会话随后校验交接、建接任会话并登记在任（ho_succeed）；全局仍可用 ho_sessions action=new 手动新建会话' },
-    { when: '会话角色', say: '把 Demo1 设成项目角色，并让它整理自己的文件', what: '写角色表、当场收窄该会话的工具与提示、投递一次性整理指令（ho_sessions action=role / 本页会话角色）' },
-    { when: '通知项目会话', say: '通知 Demo 更新交接文档', what: '投递一条消息；会话之间可直接对话，不必经全局转述；会消耗目标会话一整轮 token，应尽量少用（peer_send）' },
-    { when: '全局前置提示词', say: '把这段设为全局前置提示词', what: '保存到本机；仅在你开启且内容非空时注入全部会话，关闭或留空时不注册提示段' },
-    { when: '项目骨架', say: '注册 Demo 的骨架', what: '读取、注册、校验项目或杂项的骨架档案；由该项目会话自己写文件并注册（ho_profile）' },
-    { when: '查看会话', say: '列出当前活跃的会话', what: '水位、运行状态、活跃或沉默、在任或前任（ho_sessions）' },
-    { when: '打包迁移', say: '把 Demo 打包成迁移包', what: '收集文件、逐文件 sha256、7z、自检、绝对路径体检（ho_pack action=pack）' },
-    { when: '在新机器恢复', say: '预演这次恢复', what: '校验、列出覆盖清单、备份、写入；默认仅预演（ho_pack action=restore）' },
-    { when: '删除会话', say: '把这个会话归档', what: '官方仅提供归档；需要再次唤醒时须先解归档（ho_sessions action=archive、unarchive）' },
-    { when: '建立工作区', say: '把这个目录注册为工作区', what: '注册已存在的目录；删除只删注册，目录与会话日志均保留（ho_workspace）' },
-    { when: '首次安装', say: '把某个目录建成全局根目录', what: '在该目录下建立整套全局文件体系，并注册为工作区（ho_init）' },
-    { when: '自检', say: '检查插件当前状态', what: '服务可解析性、压缩调度器、压缩计数、本会话角色与工具集（ho_diag）' },
-    { when: '查在任', say: '现在 Mingent 是谁在任', what: '按全局、项目、杂项查现任会话的名字与会话 id（ho_office）；不起会话也可用命令行 node scripts/office.mjs 同名查询' },
-  ],
-  groups: [
-    {
-      title: '只读工具（不消耗任何会话的 token）',
-      tools: [
-        ['ho_brief', '起始与收束的单条命令：水位、闸门、会话清点与阶段建议'],
-        ['ho_gate', '通用约束条闸门（按库型判定）与交接文档体检'],
-        ['ho_sessions', '会话清点；也用于设定角色、建会话、出提示词、归档'],
-        ['ho_phase', '本会话阶段：水位、已压缩次数、锁状态、建议动作'],
-        ['ho_charter', '按节返回规则正文；doc="runtime" 取完整流程手册'],
-        ['ho_drift', '交接漂移体检：Δ 为当前轮与交接轮之差，大于 3 需刷新'],
-        ['ho_diag', '插件自检：服务、调度器、压缩计数、角色判定与工具集'],
-        ['ho_tokens', '会话 token 体检：轮数、步数、每步 token、最贵的单条返回'],
-        ['ho_office', '在任登记表：查全局、项目、杂项现在由哪个会话在任（名字与会话 id）'],
-      ],
-    },
-    {
-      title: '写工具（会改动文件；均带备份或预演）',
-      tools: [
-        ['ho_handover', '读写、追加、归档本会话自己的交接（写前备份、写后按角色体检）'],
-        ['ho_checkpoint', '写交接、登记压缩，回合结束后自动压缩并自动续跑'],
-        ['ho_snapshot', '库快照：逐字节复制、sha256 清单、来源说明'],
-        ['ho_changelog', '按固定表格追加一行台账'],
-        ['ho_pack', 'action：check 前置闸门、pack 打包、verify 校验、restore 恢复（默认预演）'],
-        ['ho_workspace', '工作区列表、创建、删除；删除只删注册'],
-        ['ho_init', '首次安装：在指定目录下建立整套全局文件体系，可顺带注册工作区'],
-        ['ho_profile', '项目或杂项骨架：读取、注册、校验、取预设'],
-        ['ho_succeed', '换任自服务：在任会话经用户授权后自行校验交接、建接任会话并登记在任'],
-      ],
-    },
-    {
-      title: '平级会话工具',
-      tools: [
-        ['peer_list', '会话清点，只读投影缓存，不激活任何会话'],
-        ['peer_status', '单会话详情：水位、运行状态、轮数、步数、工作目录'],
-        ['peer_send', '向指定会话投递一条消息，是唯一会消耗对方 token 的动作'],
-        ['peer_new', '新建平级会话，可指定工作区与标题'],
-        ['peer_rename', '只改显示标题，不唤醒目标会话'],
-        ['peer_peek', '查看指定会话近期的对话，会消耗本会话 token'],
-      ],
-    },
-  ],
-  rules: [
-    '交接线：上下文水位达到 ' + w.warn + ' 时提醒，达到 ' + w.handover + ' 时写交接并压缩，' + w.hard + ' 为硬上限；同一会话最多压缩 ' + w.max + ' 次，第四段改用新建会话。',
-    '压缩不可逆：历史会被摘要替换，因此必须先写出合格的交接文档；体检未通过时，插件拒绝安排压缩。',
-    '会话之间可直接 peer_send 对话，不必经全局转述；默认沉默仍适用：只在到交接线且已写交接、需用户决定、发现全局口径有误时发一条，任务完成不向全局报告。',
-    '压缩后的去向由助手在登记时选择：任务未完成用 continue 续跑，任务已收尾用 wait 静默收尾，等用户派新任务。',
-    '交接文件按角色分离：全局写 _Control_Center/records/Global_Handover.md，项目写 _Project_Meta/<项目>/Handover.md，杂项写 _Misc/tasks/<任务>/Handover.md，互不串用。',
-    '会话本身不迁移：跨机器、跨平台的连续性依托交接文档。',
-    '全局前置提示词属于用户内容，不是插件约束；关闭或留空时不占用注入点位，可与其它提示词插件并存。',
-    '项目与杂项的骨架由各自会话注册；构建型、动画型等项目不必套用插件类项目的文档集。',
-    '迁移只搬运文件与清单，不改写文件内容：包内写死的绝对路径会以清单形式报出，由用户或项目会话自行修改；库内引用一律使用相对路径。',
-    '插件本体为公开件，不含任何用户项目、会话或账号数据；用户数据与角色表都保存在本机。',
-  ],
+    intro: [
+      '插件功能主要在会话中调用：用中文说明要做的事，全局会话会选择相应工具执行，不必记命令；设置页另提供授权、迁移与会话角色等操作入口。',
+      '工具与提示按会话角色载入：全局会话可见全部 ' + toolCount + ' 个工具，项目与杂项会话仅载入所需的部分工具，普通会话不载入插件工具，也不注入提示段。角色在下方「会话角色」中指定。',
+      '本页除首次安装、全局前置提示词与会话角色外均为只读；需要最新读数时，点击右上角的「刷新」。',
+    ],
+    situations: [
+      { when: '首次安装', say: '部署全局文件体系', what: '本页「一键部署」一次完成 3 步：建立文件体系、注册「全局」工作区、建立「全局」会话' },
+      { when: '作业开始与结束', say: '先出一份起始简报', what: '汇总上下文水位、通用约束条闸门、会话清点、交接漂移与阶段建议（ho_status view=brief）' },
+      { when: '查阅规则', say: '取出 Charter 第 7.2.3 节', what: '按节返回规则正文，避免整篇读取；插件用法用 doc="runtime"（ho_charter）' },
+      { when: '交接与压缩续跑', say: '写好交接文档后压缩并继续', what: '按固定流程重写交接（读旧交接、归档、读模板、新建写入），体检后登记压缩；未完成用 resume=continue 续跑，已收尾用 resume=wait（ho_handover、ho_checkpoint）' },
+      { when: '上下文到 35% 或 50%', say: '查询本会话的上下文水位', what: compact + '；2 条线各后台提醒一次，不生成用户消息（ho_status view=phase）' },
+      { when: '换任', say: '让在任会话自己完成换任', what: '先由当前用户授权：聊天框发送 /allow-succeed，或在设置页「授权」卡点击「授权换任」；在任会话随后校验交接、建立接任会话并登记在任（ho_succeed）' },
+      { when: '会话角色', say: '把 Demo1 设为项目角色', what: '写角色表，当场收窄该会话的工具与提示，并投递首轮指令以建立体系；项目与杂项互转默认先快照再移动，也可选择直接建（ho_sessions action=role）' },
+      { when: '通知会话', say: '通知 Demo 更新交接文档', what: '投递一条消息；会话之间可直接通信，不必经全局转述；该动作会消耗目标会话一整轮 token，应尽量少用（peer action=send）' },
+      { when: '多会话协作', say: '把这三件事分给三个会话并收结果', what: '先逐个 send 派任务，再用 collect 列出要等待的会话；先完成者先返回，同时完成者一并返回。被派方完成即结束回合，不发送确认或进度消息（peer action=collect）' },
+      { when: '全局前置提示词', say: '将这段设为全局前置提示词', what: '在本页保存到本机；仅在开启且内容非空时注入全部会话，关闭或留空时不注册提示段' },
+      { when: '项目骨架', say: '注册 Demo 的骨架', what: '读取、注册、校验项目或杂项的骨架档案；档案文件由该项目会话自己写（ho_profile）' },
+      { when: '体系注册', say: '把本项目的体系注册写进提示段', what: '每个任务一份体系注册，写目录结构、规范文件与计划；全局总注册只列各任务体系文件路径；写入后热更新（ho_docmap action=write）' },
+      { when: '行动计划', say: '为这个任务建立行动计划', what: '写任务根 PLAN.md；旧计划先归档且不再读取；压缩或换任后按「先交接、再计划、后执行」阅读（ho_docmap action=plan）' },
+      { when: '暂任交出与归还', say: '把本任务交给另一个会话', what: '先刷新交接，再按任务库内 Delegation_Rules.md 把提示词写入 Delegation_Prompt.md；归还时刷新交接，并在交接中写明暂任者（ho_handover）' },
+      { when: '查看会话', say: '列出当前会话', what: '水位、运行状态、活跃或沉默、角色与最后活动，并给出本轮通知名单（ho_sessions）' },
+      { when: '打包迁移', say: '把 Demo 打包成迁移包', what: '收集文件、逐文件 sha256、7z（无 7-Zip 时用内置 tar.gz）、自检与绝对路径体检（ho_backup action=pack）' },
+      { when: '在新机器恢复', say: '预演这次恢复', what: '校验、列出覆盖清单、备份后写入；默认仅预演（ho_backup action=restore）' },
+      { when: '归档会话', say: '把这个会话归档', what: 'DSH 只提供归档；再次唤醒须先解归档（ho_sessions action=archive、unarchive）' },
+      { when: '建立工作区', say: '把这个目录注册为工作区', what: 'init 在指定目录下建立整套全局文件体系；list、create、delete 管理注册，删除只删注册（ho_workspace）' },
+      { when: '旧体系迁移', say: '把旧文档定位并入体系注册', what: '迁移模块读取旧 docmap，并入各任务体系注册，并把旧目录归档；旧目录不删除（ho_workspace action=migrate）' },
+      { when: '自检', say: '检查插件当前状态', what: '服务可用性、压缩调度器与压缩计数、本会话角色与工具集、水位与迁移状态（ho_status view=diag）' },
+      { when: '查在任', say: '现在 Demo1 由谁在任', what: '按全局、项目、杂项查询现任会话的名字与会话 id（ho_office）；也可用命令行 node scripts/office.mjs 查询' },
+      { when: '写作规范', say: '按写作规范检查这份文档', what: '执行 _Control_Center/standards/写作规范/README.md 的 W 条款；插件自带的语体门禁扫描 README、docs、templates 与 src' },
+    ],
+    groups: [
+      {
+        title: '只读工具（不消耗任何会话 token）',
+        tools: [
+          ['ho_status', '会话状态：view=phase 水位与建议（默认）、brief 起始简报、diag 插件自检、drift 交接漂移、tokens token 体检'],
+          ['ho_gate', '通用约束条闸门（按库型判定）＋交接文档体检＋体系注册路径检查'],
+          ['ho_sessions', '会话清点与通知名单；也用于设定角色、身份互转、建会话、出提示词、归档'],
+          ['ho_charter', '按节返回规则正文；doc="runtime" 取完整插件手册'],
+          ['ho_office', '在任登记表：查在任；action=register 用于会话首次注册自己的名字'],
+          ['ho_docmap', '体系注册与文档定位：read、write、check；action=plan 读写计划并归档旧计划'],
+        ],
+      },
+      {
+        title: '写工具（会改动文件；均带备份或预演）',
+        tools: [
+          ['ho_handover', '读写、新建、追加、归档本会话自己的交接；整篇重写用 new 先归档旧交接再新建写入，写后按角色体检'],
+          ['ho_checkpoint', '写交接、登记压缩；回合结束后压缩，并按 resume 决定是否续跑'],
+          ['ho_changelog', '按固定表格追加一行台账'],
+          ['ho_backup', 'action：snapshot 库快照、check 前置闸门、pack 打包、verify 校验、restore 恢复（默认预演）'],
+          ['ho_workspace', 'init 首次建体系；scaffold 补齐；migrate 旧体系迁移；list、create、delete 工作区；move-* 迁移全局根目录'],
+          ['ho_profile', '项目或杂项骨架：读取、注册、校验、取预设'],
+          ['ho_succeed', '换任自服务：在任会话经当前用户授权后自行校验交接、建接任会话并登记在任'],
+        ],
+      },
+      {
+        title: '平级会话工具',
+        tools: [
+          ['peer', 'action：list 会话一览、status 单会话详情、send 投消息（wait=true 同轮等回复）、wait 等单个回复、collect 收集先完成的最终回复、peek 读近期会话历史、rename 改标题、new 新建'],
+        ],
+      },
+    ],
+    rules: [
+      '水位 ' + w.remind + ' 与 ' + w.remind2 + ' 各提醒一次（工具结果末尾追加）；' + w.handover + ' 后可压缩，' + w.hard + ' 为硬上限；同一会话最多压缩 ' + w.max + ' 次，第 ' + (w.max + 1) + ' 次换任。',
+      '压缩不可逆：历史会被摘要替换，因此必须先写出合格的交接文档；体检未通过时，插件拒绝安排压缩。',
+      '压缩或换任后按「先读交接、再读计划、后执行」恢复；没有计划则跳过第二步。',
+      '会话之间可直接用 peer（action=send）通信，不必经全局转述；默认沉默仍适用：仅在到交接线、需当前用户决定、发现全局口径有误时发送一条。',
+      '当前用户授权（压缩或换任）写入后，目标会话的提示段会立刻多一行提示与到期时刻；授权过期或使用后自动消失，不留占位。',
+      '交接文件按角色分离：全局写 _Control_Center/records/Global_Handover.md，项目写 _Project_Meta/<项目>/Handover.md，杂项写 _Misc/tasks/<任务>/Handover.md，互不串用。',
+      '体系注册按任务独立：项目在 _Project_Meta/<项目>/System.md，杂项在 _Misc/tasks/<任务>/System.md，全局任务在 _Control_Center/tasks/<任务>/System.md；全局总注册 _Control_Center/records/systems.md 只列路径。',
+      '身份在项目与杂项之间互转时，先按归档规范打整库快照，再移动；用户也可选择直接建，沿用同一模板体系。',
+      '会话本身不迁移：跨机器、跨平台的连续性依托交接文档。',
+      '全局前置提示词属于用户内容，不是插件约束；关闭或留空时不占用注入点位。',
+      '插件本体为公开件，不含任何用户项目、会话或账号数据；用户数据与角色表都保存在本机。',
+    ],
   };
 }
 

package/src/lib/handover-io.mjs

@@ -1,9 +1,10 @@
-/** 交接文档读写：原子写 + 写前备份 + 写后体检（判据复用 lib/lint.mjs）。路径按会话角色解析。 */
+/** 交接文档读写：原子写 + 写前备份 + 存档（整篇重写先归档）+ 写后体检（判据复用 lib/lint.mjs）。路径按会话角色解析。 */
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { readUtf8 } from './text.mjs';
 import { lintGlobal, lintProject } from './lint.mjs';
-import { snapshotDirFor } from './role.mjs';
+import { snapshotDirFor, archiveDirFor } from './role.mjs';
 
 function stamp() {
   const d = new Date();
@@ -11,6 +12,10 @@ function stamp() {
   return d.getFullYear() + p(d.getMonth() + 1) + p(d.getDate()) + "-" + p(d.getHours()) + p(d.getMinutes()) + p(d.getSeconds());
 }
 
+function sha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
 /** 读交接：{ path, text }；文件不存在返回 text: null。 */
 export function readHandover(file) {
   try { return { path: file, text: readUtf8(file) }; }
@@ -30,26 +35,51 @@ export function archiveStamp(d) {
 /**
  * 归档文件名：`<原文件名>_<YYYYMMDD_HHMMSS>.md`。
  * 「原文件名」取源文件主名（不含扩展名）：全局 `Global_Handover_…`、项目与杂项 `Handover_…`；
- * 不加链标识——归档目录本身已按链隔离（规范 §4.1）。
+ * 不加链标识——归档目录本身已按链隔离（规范 §5）。
  */
 export function archiveFileName(file, stampText) {
   const base = String(file || "").split(/[\\/]/).pop().replace(/\.md$/i, "");
   return base + "_" + String(stampText) + ".md";
 }
 
+/**
+ * 归档交接：复制到规范位置并校验 sha256；同名不覆盖，同一秒追加 `-2`、`-3`。
+ * @param {object} [opts] { info?: 角色信息, kind?: 'global'|'project'|'misc', archiveDir?: 强制指定目录 }
+ * @returns {{ dest, bytes, sha256 }}
+ */
+export function archiveHandover(ws, file, opts) {
+  const o = opts || {};
+  const info = o.info || { role: o.kind === 'project' ? 'project' : o.kind === 'misc' ? 'misc' : 'global' };
+  const dir = o.archiveDir || archiveDirFor(ws, info);
+  fs.mkdirSync(dir, { recursive: true });
+  const stampText = archiveStamp(new Date());
+  let dest = path.join(dir, archiveFileName(file, stampText));
+  for (let n = 2; fs.existsSync(dest) && n < 100; n++) dest = path.join(dir, archiveFileName(file, stampText + "-" + n));
+  if (fs.existsSync(dest)) throw new Error("归档目标已存在，不覆盖：" + dest);
+  fs.copyFileSync(file, dest);
+  const a = sha256(file);
+  const b = sha256(dest);
+  if (a !== b) {
+    try { fs.rmSync(dest, { force: true }); } catch { /* 删不掉就留着，报错已说明路径 */ }
+    throw new Error("归档校验失败：sha256 不一致，未写入新交接：" + dest);
+  }
+  return { dest, bytes: fs.statSync(dest).size, sha256: b };
+}
+
 /**
  * 写交接：先把旧文件复制到 <作用域>/Snapshots/pm-handover-<stamp>/，再原子替换，最后按角色体检。
- * @param {object} [opts] { info?: 角色信息（决定体检判据与备份目录）, kind?: 'global'|'project'|'misc' }
+ * `opts.noBackup` 为 true 时跳过备份（整篇重写已先归档）。
+ * @param {object} [opts] { info?: 角色信息（决定体检判据与备份目录）, kind?: 'global'|'project'|'misc', noBackup?: boolean }
  * @returns {{ path, backup, verdict, reasons, bytes }}
  */
 export function writeHandover(ws, file, text, mode, opts) {
   const o = opts || {};
   const info = o.info || { role: o.kind === 'project' ? 'project' : o.kind === 'misc' ? 'misc' : 'global' };
   let dir = null;
-  try { dir = snapshotDirFor(ws, info); } catch { dir = path.join(ws, '_Temp', '_Global', 'Snapshots'); }
+  try { dir = o.snapshotDir || snapshotDirFor(ws, info); } catch { dir = path.join(ws, '_Temp', '_Global', 'Snapshots'); }
   let backup = null;
   try {
-    if (fs.existsSync(file)) {
+    if (!o.noBackup && fs.existsSync(file)) {
       const bdir = path.join(dir, "pm-handover-" + stamp());
       fs.mkdirSync(bdir, { recursive: true });
       backup = path.join(bdir, path.basename(file));
@@ -67,3 +97,36 @@ export function writeHandover(ws, file, text, mode, opts) {
     : lintGlobal(file);
   return { path: file, backup, verdict: res.verdict, reasons: res.reasons, bytes: Buffer.byteLength(body, "utf8") };
 }
+
+function findSameArchive(dir, sha) {
+  try {
+    for (const name of fs.readdirSync(dir)) {
+      if (!/\.md$/i.test(name)) continue;
+      const p = path.join(dir, name);
+      try { if (sha256(p) === sha) return p; } catch { /* 读不到就跳过 */ }
+    }
+  } catch { /* 目录不存在时按未归档处理 */ }
+  return null;
+}
+
+/**
+ * 整篇重写：先归档旧交接（文件存在时），再新建空白文件写入，最后体检。
+ * 固定流程的落点：读旧交接由调用方完成，归档与新建由本函数一次做完。
+ * 归档幂等：归档目录里已有内容相同的副本时复用，不重复复制。
+ * @returns 同 writeHandover，另加 archived: { dest, bytes, sha256, reused } | null
+ */
+export function rewriteHandover(ws, file, text, opts) {
+  const o = opts || {};
+  let archived = null;
+  if (fs.existsSync(file)) {
+    const info = o.info || { role: o.kind === 'project' ? 'project' : o.kind === 'misc' ? 'misc' : 'global' };
+    const dir = o.archiveDir || archiveDirFor(ws, info);
+    const sha = sha256(file);
+    const same = findSameArchive(dir, sha);
+    archived = same
+      ? { dest: same, bytes: fs.statSync(same).size, sha256: sha, reused: true }
+      : Object.assign(archiveHandover(ws, file, o), { reused: false });
+  }
+  const res = writeHandover(ws, file, text, "write", Object.assign({}, o, { noBackup: true }));
+  return Object.assign({}, res, { archived });
+}