@mingmaple/dsh-handover 0.0.0-stage → 0.9.12

package/src/lib/guide.mjs

@@ -0,0 +1,103 @@
+/**
+ * 设置页「使用说明」的内容：面向人，不面向模型。
+ * 数据放宿主侧，客户端只负责渲染——改文案不用动客户端 bundle。
+ * 行文用标准书面语：不用口语化的示例句，示例一律写成可以直接提的要求。
+ * 水位与工具数由 facts.mjs、names.mjs 推导，不在这里重复写死。
+ */
+import { compactSummaryText, watermark } from './facts.mjs';
+import { ALL_TOOL_NAMES } from './names.mjs';
+
+/** 首次安装、尚未接入工作区时的下一步（设置页与工具输出共用同一份）。 */
+export const SETUP_STEPS = [
+  '准备一个长期存在的目录作为全局根的上级目录，不要选临时目录或下载目录。',
+  '在本页下方的输入框中粘贴该目录的绝对路径，点「一键部署」：插件会在其中建立 _Workspace 与整套结构，注册为「全局」工作区，并新建一个「全局」会话。',
+  '在左侧「全局」工作区中打开新会话即可开始。若只想先铺文件，可点「仅建立文件体系」，之后再注册工作区。',
+  '工作区已接入但还没有全局会话时，本页会单独出现「全局会话」卡片，可随时补建。',
+  '新建项目或杂项会话时，应当指明目标工作区；找不到工作区时，插件会把已注册的工作区列出来，不会静默落到别处。',
+];
+
+export function buildGuide(cfg) {
+  const w = watermark(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: '建会话、唤醒并投递启动提示词；在任会话水位低于 ' + w.warn + ' 时拒绝新建（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）' },
+  ],
+  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、最贵的单条返回'],
+      ],
+    },
+    {
+      title: '写工具（会改动文件；均带备份或预演）',
+      tools: [
+        ['ho_handover', '读写、追加、归档本会话自己的交接（写前备份、写后按角色体检）'],
+        ['ho_checkpoint', '写交接、登记压缩，回合结束后自动压缩并自动续跑'],
+        ['ho_snapshot', '库快照：逐字节复制、sha256 清单、来源说明'],
+        ['ho_changelog', '按固定表格追加一行台账'],
+        ['ho_pack', 'action：check 前置闸门、pack 打包、verify 校验、restore 恢复（默认预演）'],
+        ['ho_workspace', '工作区列表、创建、删除；删除只删注册'],
+        ['ho_init', '首次安装：在指定目录下建立整套全局文件体系，可顺带注册工作区'],
+        ['ho_profile', '项目或杂项骨架：读取、注册、校验、取预设'],
+      ],
+    },
+    {
+      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，互不串用。',
+    '会话本身不迁移：跨机器、跨平台的连续性依托交接文档。',
+    '全局前置提示词属于用户内容，不是插件约束；关闭或留空时不占用注入点位，可与其它提示词插件并存。',
+    '项目与杂项的骨架由各自会话注册；构建型、动画型等项目不必套用插件类项目的文档集。',
+    '迁移只搬运文件与清单，不改写文件内容：包内写死的绝对路径会以清单形式报出，由用户或项目会话自行修改；库内引用一律使用相对路径。',
+    '插件本体为公开件，不含任何用户项目、会话或账号数据；用户数据与角色表都保存在本机。',
+  ],
+  };
+}
+
+/** 默认配置下的说明文本；设置页按实际配置调用 buildGuide。 */
+const GUIDE = buildGuide();

package/src/lib/handover-io.mjs

@@ -0,0 +1,69 @@
+/** 交接文档读写：原子写 + 写前备份 + 写后体检（判据复用 lib/lint.mjs）。路径按会话角色解析。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readUtf8 } from './text.mjs';
+import { lintGlobal, lintProject } from './lint.mjs';
+import { snapshotDirFor } from './role.mjs';
+
+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()) + p(d.getSeconds());
+}
+
+/** 读交接：{ path, text }；文件不存在返回 text: null。 */
+export function readHandover(file) {
+  try { return { path: file, text: readUtf8(file) }; }
+  catch { return { path: file, text: null }; }
+}
+
+/**
+ * 归档时间戳：`YYYYMMDD_HHMMSS`（到秒）。
+ * 规范要求时间戳取归档那一刻；只到分钟会在同一分钟内归档两份时撞名，故到秒。
+ */
+export function archiveStamp(d) {
+  const x = d || new Date();
+  const p = (n) => (n < 10 ? "0" + n : "" + n);
+  return x.getFullYear() + p(x.getMonth() + 1) + p(x.getDate()) + "_" + p(x.getHours()) + p(x.getMinutes()) + p(x.getSeconds());
+}
+
+/**
+ * 归档文件名：`<原文件名>_<YYYYMMDD_HHMMSS>.md`。
+ * 「原文件名」取源文件主名（不含扩展名）：全局 `Global_Handover_…`、项目与杂项 `Handover_…`；
+ * 不加链标识——归档目录本身已按链隔离（规范 §4.1）。
+ */
+export function archiveFileName(file, stampText) {
+  const base = String(file || "").split(/[\\/]/).pop().replace(/\.md$/i, "");
+  return base + "_" + String(stampText) + ".md";
+}
+
+/**
+ * 写交接：先把旧文件复制到 <作用域>/Snapshots/pm-handover-<stamp>/，再原子替换，最后按角色体检。
+ * @param {object} [opts] { info?: 角色信息（决定体检判据与备份目录）, kind?: 'global'|'project'|'misc' }
+ * @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'); }
+  let backup = null;
+  try {
+    if (fs.existsSync(file)) {
+      const bdir = path.join(dir, "pm-handover-" + stamp());
+      fs.mkdirSync(bdir, { recursive: true });
+      backup = path.join(bdir, path.basename(file));
+      fs.copyFileSync(file, backup);
+    }
+  } catch (e) { throw new Error("备份失败，已中止写入：" + e.message); }
+  const body = mode === "append" && fs.existsSync(file) ? readUtf8(file) + String.fromCharCode(10) + text : text;
+  const parent = path.dirname(file);
+  fs.mkdirSync(parent, { recursive: true });
+  const tmp = file + ".tmp-" + stamp();
+  fs.writeFileSync(tmp, body, "utf8");
+  fs.renameSync(tmp, file);
+  const res = (o.kind === 'project' || o.kind === 'misc' || info.role === 'project' || info.role === 'misc')
+    ? lintProject(file)
+    : lintGlobal(file);
+  return { path: file, backup, verdict: res.verdict, reasons: res.reasons, bytes: Buffer.byteLength(body, "utf8") };
+}

package/src/lib/lint.mjs

@@ -0,0 +1,152 @@
+/** 交接文档体检：项目交接与全局交接。 */
+import { readUtf8, sectionLines, isFile } from './text.mjs';
+import { statSync } from 'node:fs';
+
+const TICK = String.fromCharCode(96);
+const ACCEPTABLE = [
+  '<工作区根>', '<项目名>', '<YYYY-MM-DD>', '<绝对路径>', '<版本号>',
+  '<YYYYMMDD_HHMMSS>', '<日期>', '<过去日期>', '<任务短名>', '<N>', '<M>', '<id>', '<新 id>',
+];
+
+/** 去掉行内代码段，避免把示例里的占位符当残留。 */
+function stripCodeSpans(text) {
+  let out = "";
+  let inCode = false;
+  for (const ch of text) {
+    if (ch === TICK) { inCode = !inCode; continue; }
+    if (!inCode) out += ch;
+  }
+  return out;
+}
+
+function firstPlaceholder(text) {
+  const src = stripCodeSpans(text);
+  for (let i = 0; i < src.length; i++) {
+    if (src[i] !== '<') continue;
+    const j = src.indexOf('>', i + 1);
+    if (j === -1) break;
+    if (j - i > 41) continue;
+    const token = src.slice(i, j + 1);
+    if (token.indexOf(String.fromCharCode(10)) !== -1) continue;
+    if (ACCEPTABLE.indexOf(token) !== -1) continue;
+    return token;
+  }
+  return null;
+}
+
+const GLOBAL_SECTIONS = [
+  '0. 身份与寻址',
+  '1. 正在做的事',
+  '2. 下一步',
+  '3. 待用户决定',
+  '4. 用户要求逐条落位',
+  '5. 坑点与禁区',
+  '6. 关键路径',
+  '7. 会话 id 对照',
+];
+
+const GLOBAL_FIELDS = [
+  '会话类型', '本任', '链内代数', '接任', '本文件', '冲突以谁为准', '修订',
+];
+
+function hasHeading(lines, sec) {
+  return lines.some((l) => l.startsWith('## ') && l.indexOf(sec) !== -1);
+}
+
+function tableRows(lines) {
+  return lines.filter((l) => l.trim().startsWith('|') && l.indexOf('---') === -1);
+}
+
+function bulletRows(lines) {
+  return lines.filter((l) => l.trim().startsWith('-') || l.trim().startsWith('*'));
+}
+
+/** 全局交接体检：{ verdict, reasons }。 */
+export function lintGlobal(file) {
+  if (!isFile(file)) return { verdict: "读不到", reasons: ["文件不存在：" + file] };
+  let text = "";
+  try { text = readUtf8(file); } catch (e) { return { verdict: "读不到", reasons: ["读取失败：" + e.message] }; }
+  const lines = text.split(String.fromCharCode(10));
+  const bad = [];
+  // §3 标题有新旧两种写法，旧的「等用户拍板」也按通过处理。
+  const SEC_ALIAS = { '3. 待用户决定': ['3. 等用户拍板'] }; // 语体豁免：旧文档标题原文，只作兼容匹配
+  for (const sec of GLOBAL_SECTIONS) {
+    const alt = SEC_ALIAS[sec] || [];
+    if (!hasHeading(lines, sec) && !alt.some((a) => hasHeading(lines, a))) bad.push("缺一节：## " + sec);
+  }
+  const zero = sectionLines(text, '身份与寻址');
+  if (!zero) bad.push('缺 ## 0. 身份与寻址');
+  else {
+    const zt = zero.join(String.fromCharCode(10));
+    for (const f of GLOBAL_FIELDS) if (zt.indexOf("| " + f + " |") === -1 && zt.indexOf("|" + f + "|") === -1) bad.push("§0 缺字段：" + f);
+  }
+  const chainLine = lines.find((l) => l.indexOf('链内代数') !== -1);
+  if (!chainLine) bad.push('§0 缺「链内代数」行');
+  else {
+    const hasDi = chainLine.indexOf('第') !== -1 && chainLine.indexOf('代') !== -1;
+    if (!hasDi) bad.push('链内代数不是「第 N 代」格式：' + chainLine.slice(0, 60));
+  }
+  const s2 = sectionLines(text, '下一步');
+  if (!s2) bad.push('缺 ## 2. 下一步');
+  else if (tableRows(s2).length <= 1 && bulletRows(s2).length === 0) bad.push('§2 没列出任何条目');
+  const s7 = sectionLines(text, '会话 id 对照');
+  if (!s7) bad.push('缺 ## 7. 会话 id 对照');
+  else {
+    if (!s7.some((l) => l.trim().startsWith('|') && l.indexOf('session-') !== -1)) bad.push('§7 没有一行带 session id');
+    if (s7.some((l) => l.indexOf('待回填') !== -1)) bad.push('§7 还有「待回填」');
+  }
+  const ph = firstPlaceholder(text);
+  if (ph) bad.push("残留模板占位符：" + ph);
+  return { verdict: bad.length === 0 ? "通过" : "不合格", reasons: bad };
+}
+
+/** 项目交接体检：{ verdict, reasons }，verdict ∈ 通过/不合格/缺节/读不到。 */
+export function lintProject(file) {
+  if (!isFile(file)) return { verdict: "不合格", reasons: ["缺 Handover.md：" + file] };
+  let text = "";
+  try { text = readUtf8(file); } catch (e) { return { verdict: "读不到", reasons: ["读取失败：" + e.message] }; }
+  const bad = [];
+  const gap = [];
+  const body = sectionLines(text, '正在做的事');
+  if (!body) gap.push("缺 ## 1. 正在做的事 一节（2026-10-12 起的强制项，本项目还没补）");
+  else {
+    const core = body.filter((l) => l.trim() !== '' && !l.trim().startsWith('>'));
+    if (core.length === 0) bad.push("正在做的事 是空节（或只有引用块说明），没写实质内容");
+    else if (core.join('').trim().length < 30) bad.push('正在做的事 内容过短，像是应付');
+  }
+  const nxt = sectionLines(text, '下一步') || sectionLines(text, '待办');
+  if (!nxt) bad.push("缺「下一步待办」一节");
+  else if (tableRows(nxt).length <= 1 && bulletRows(nxt).length === 0) bad.push("「下一步待办」没列出任何条目");
+  const ph = firstPlaceholder(text);
+  if (ph) bad.push("残留模板占位符：" + ph);
+  if (bad.length) return { verdict: "不合格", reasons: bad };
+  if (gap.length) return { verdict: "缺节", reasons: gap };
+  return { verdict: "通过", reasons: [] };
+}
+
+export function renderLintGlobal(file, res) {
+  const out = [];
+  out.push("交接文档体检（全局）  " + file);
+  let size = "?";
+  try { size = String(statSync(file).size); } catch { /* ignore */ }
+  out.push("  Global_Handover.md  " + res.verdict + "  " + size + " B");
+  for (const r of res.reasons) out.push("             - " + r);
+  out.push("判定：" + (res.verdict === "通过" ? "结构齐备" : "不合格（" + res.reasons.length + " 项）"));
+  return out;
+}
+
+export function renderLintProject(name, rows) {
+  const list = Array.isArray(rows) ? rows : [{ name, file: "", res: rows }];
+  const out = [];
+  out.push("交接文档体检  项目 " + (name || "全部"));
+  let fails = 0;
+  let gaps = 0;
+  for (const it of list) {
+    out.push("  " + it.name + "  " + it.res.verdict);
+    for (const r of it.res.reasons) out.push("             - " + r);
+    if (it.res.verdict === "不合格") fails++;
+    else if (it.res.verdict === "缺节") gaps++;
+  }
+  out.push("判定：" + list.length + " 个项目 —— 不合格 " + fails + " 个（要改）、缺节 " + gaps + " 个（新规范未铺开，属正常）");
+  return out;
+}

package/src/lib/manual.mjs

@@ -0,0 +1,124 @@
+/**
+ * 逐角色的系统提示段与一次性引导。
+ * 职责边界：本文件只写会话定位、写入范围、交接路径、水位与换任、向全局汇报。
+ * 其他行为约束（不虚构、最小改动、文风等）不属于本插件，由用户按需通过「全局前置提示词」注入。
+ * 文字一律标准书面语；代码里不用反引号拼提示词。
+ */
+import { handoverPathFor, scopeLabel } from './role.mjs';
+import { handoverRuleText, watermark } from './facts.mjs';
+
+const NL = String.fromCharCode(10);
+
+/** 完整流程的指针句（三档角色共用）。 */
+const RUNTIME_POINTER = '规则细节按节取：ho_charter(doc="runtime", section=…)。';
+
+/** 全局会话的常驻段：五节骨架（身份、权限、节奏、交接、按需取用）。 */
+export function globalManual(opts) {
+  const o = opts || {};
+  const lines = [
+    'dsh-handover 运行期（全局）',
+    '',
+    '一、身份',
+    '本会话为「全局」管理会话：协调会话、维护规则与交接。',
+    '',
+    '二、权限',
+    '可写 _Control_Center、_Project_Meta 与项目结构本身；Projects 与各项目库内文件只读，不得代改写；项目内作业不代办。',
+    '新建会话与设定角色仅属全局；会话之间可直接 peer_send，不必经全局转述；换任须经用户同意。',
+    '',
+    '三、节奏',
+    handoverRuleText(o.cfg),
+    '压缩须用户点「压缩授权」，随后写交接并 ho_checkpoint(confirm=true)；任务未完成时压缩后续跑，已收尾时传 resume=wait 不再唤醒；confirm 仅表意图，插件只认那次点击。关键步骤传 at_risk=true 暂缓。',
+    '',
+    '四、交接',
+    '全局交接：_Control_Center/records/Global_Handover.md（ho_handover 默认）。',
+    '',
+    '五、按需取用',
+    RUNTIME_POINTER,
+  ];
+  const mv = moveLine(o);
+  if (mv) lines.push(mv);
+  return lines.join(NL);
+}
+
+/** 项目与杂项会话的提示段：只写本角色自己的写入范围、交接与水位。 */
+export function scopedManual(info, opts) {
+  const o = opts || {};
+  const hp = handoverPathFor(o.ws, info);
+  const label = scopeLabel(info);
+  const lines = [
+    'dsh-handover 运行期（' + label + '）',
+    info.role === 'project'
+      ? '只可写本库与元数据目录，不得写 _Control_Center 及其他项目。'
+      : '只可写本任务目录与元数据目录，不得写 _Control_Center、Projects 及其他任务。',
+    info.role === 'project'
+      ? '库根：Projects/' + info.project + '/；元数据：_Project_Meta/' + info.project + '/。'
+      : '任务目录：_Misc/tasks/' + info.task + '/。',
+    info.role === 'project'
+      ? '骨架：_Project_Meta/' + info.project + '/project.profile.json；未注册时先通读本库并 ho_profile(action=register)。'
+      : '骨架：_Misc/tasks/' + info.task + '/task.profile.json；未注册时先通读本任务并 ho_profile(action=register)。',
+    info.role === 'project'
+      ? '临时与归档：_Temp/' + info.project + '/{Snapshots,Scratch}、_Archives/' + info.project + '/。'
+      : '临时与归档：_Temp/_Misc/' + info.task + '/Snapshots/、_Archives/_Misc/' + info.task + '/。',
+    hp.path
+      ? '交接：' + hp.path + '（ho_handover 默认）。'
+      : '交接路径未解析（缺角色或项目名），请先在设置页设定角色。',
+    handoverRuleText(o.cfg) + '压缩须用户点「压缩授权」，再自行 ho_checkpoint(confirm=true)；收尾时传 resume=wait 不再唤醒。',
+    '会话间可直接 peer_send，不必经全局转述；默认沉默：只在水位 ' + watermark(o.cfg).warn + ' 已写交接、需用户决定、口径有误时向全局报告；任务完成不报全局。',
+    RUNTIME_POINTER,
+  ];
+  const mv = moveLine(o);
+  if (mv) lines.push(mv);
+  return lines.join(NL);
+}
+
+/** 迁移提示行（只有真的搬过才出现）。 */
+function moveLine(opts) {
+  const mv = opts && opts.move;
+  if (!mv || mv.phase !== 'switched') return '';
+  return '已迁移至 ' + (mv.dst || '?') + '；' + (mv.src || '?') + ' 现为链接，勿再手工迁移。';
+}
+
+export function manualFor(info, opts) {
+  const role = info && info.role ? info.role : 'plain';
+  if (role === 'global') return globalManual(opts);
+  if (role === 'project' || role === 'misc') return scopedManual(info, opts);
+  return '';
+}
+
+/** 「整理所属文件」一次性指令：设定项目或杂项角色后投递，唤醒它自己做。 */
+export function organizeMessageFor(info, opts) {
+  const o = opts || {};
+  const role = info && info.role ? info.role : 'plain';
+  if (role === 'plain') return '';
+  const head = '【dsh-handover 角色设定】本会话已被设定为「' + scopeLabel(info) + '」。请按下列结构核对自身文件：缺失的目录予以建立，位置不当的文件予以归位；既有文件就地保留，不得删除或修改内容。';
+  if (role === 'project') {
+    const p = info.project;
+    return [
+      head,
+      '先通读本库，判断本项目的大体骨架：代码与文档主体、必需文件、临时与归档位置。构建型、动画型等项目不必套用插件类项目的文档集。',
+      '把结论写入 _Project_Meta/' + p + '/project.profile.json；字段格式见 ho_profile(action=presets)。',
+      '写入后调用 ho_profile(action=register) 校验并登记；返回缺失项时按清单补齐。',
+      '约束：仅可改动本库与 _Project_Meta/' + p + '/；不得改动 _Control_Center 及其他项目；移动较大文件前先执行 ho_snapshot。可用工具：ho_snapshot、ho_handover、ho_phase、ho_checkpoint、ho_profile、peer_send。',
+      '完成后以一句话向用户说明「注册了哪些骨架项、仍缺哪些」，无需每轮回执。',
+    ].join(NL);
+  }
+  if (role === 'misc') {
+    const t = info.task;
+    return [
+      head,
+      '先通读本任务目录，判断本任务的骨架：工作文件、规则文件、交接、快照与归档位置。',
+      '把结论写入 _Misc/tasks/' + t + '/task.profile.json；字段格式见 ho_profile(action=presets)。',
+      '写入后调用 ho_profile(action=register) 校验并登记。',
+      '约束：仅可改动 _Misc/tasks/' + t + '/、_Temp/_Misc/' + t + '/、_Archives/_Misc/' + t + '/；_Control_Center、Projects 与其他任务不得触碰。工具：ho_snapshot、ho_handover、ho_phase、ho_checkpoint、ho_profile、peer_send。',
+      '完成后以一句话说明改动即可。',
+    ].join(NL);
+  }
+  return [
+    head,
+    '- _Control_Center/{records,rules,user,templates,tools} — 交接、规则、写作规范、模板、脚本。',
+    '- _Project_Meta/Registry.md 与各项目元数据目录。',
+    '- Projects/、_Misc/tasks/、_Archives/、_Temp/ — 只维护结构，不代写项目库内文件。',
+    '约束：项目库内文件由该项目会话自行整理；骨架由项目自己注册，缺则派发，不代写。',
+    '完成后以一句话汇报即可。',
+  ].join(NL);
+}