@mingmaple/dsh-handover 0.9.14 → 1.0.0

package/src/lib/pack-ops.mjs

@@ -1,6 +1,6 @@
 /**
  * 打包、校验、预演、恢复的实现（原 ho_pack / ho_pack_verify / ho_pack_restore / ho_pack_precheck 的代码搬到这里）。
- * 对外只经 ho_pack(action=…) 暴露，少 3 份 schema 的固定开销。
+ * 对外只经 ho_backup(action=…) 暴露：四份旧入口合为一份 schema，省下三份的固定开销。
  * 共同口径：只报告绝对路径、不改写文件内容；恢复默认预演、覆盖前备份、从不删除目标文件。
  */
 import fs from 'node:fs';
@@ -26,7 +26,7 @@ function chooseFormat(args, cfg) {
   const want = String((args && args.format) || (cfg && cfg.packFormat) || 'auto').toLowerCase();
   if (want === '7z') {
     const bin = sevenZipBin(cfg && cfg.sevenZipPath);
-    if (!bin) throw new Error('指定了 format=7z，但本机没有 7-Zip。去掉 format 用 auto，或写 format="tar" 用内置归档器。');
+    if (!bin) throw new Error('指定 format=7z，但本机无 7-Zip。可省略 format 改用 auto，或写 format="tar" 使用内置归档器。');
     return { fmt: '7z', bin };
   }
   if (want === 'tar' || want === 'targz' || want === 'tar.gz') return { fmt: 'tar', bin: '' };
@@ -48,11 +48,11 @@ function unpack(packPath, dir) {
   }
   if (fmt === '7z') {
     const bin = sevenZipBin('');
-    if (!bin) return { code: -1, out: '这个包是 7z 格式，但本机没有 7-Zip；装一个 7-Zip，或改用 tar.gz 包。' };
+    if (!bin) return { code: -1, out: '该包为 7z 格式，但本机无 7-Zip；请安装 7-Zip，或改用 tar.gz 包。' };
     fs.mkdirSync(dir, { recursive: true });
     return run7zSafe(bin, packPath, dir);
   }
-  return { code: -1, out: '认不出包格式（既不是 7z 魔数也不是 gzip）：' + packPath };
+  return { code: -1, out: '无法识别包格式（既非 7z 魔数，也非 gzip）：' + packPath };
 }
 
 /** 包内路径必须相对且不越界：拒绝绝对路径、盘符、..（防止恢复时写到目标目录之外）。 */
@@ -121,7 +121,7 @@ export function packCheck(env, args, exec) {
       const live = scan.rows.filter((r) => r.project === item);
       if (live.length) {
         const best = live.slice().sort((a, b) => b.mtime - a.mtime)[0];
-        if (best.state === 'running') why.push('会话 ' + best.sid + ' 正在跑');
+        if (best.state === 'running') why.push('会话 ' + best.sid + ' 正在运行');
         if (now - best.mtime < minAge) why.push('最后活动距今 ' + Math.round((now - best.mtime) / 60000) + ' 分钟 < ' + Math.round(minAge / 60000));
       }
       const hand = path.join(ws, '_Project_Meta', item, 'Handover.md');
@@ -170,7 +170,7 @@ export function packNow(env, args, exec) {
   if (!entries.length) throw new Error('没有可打包的文件：' + roots.map((r) => r[0]).join('、'));
   const total = entries.reduce((a, b) => a + b.bytes, 0);
   const out = [];
-  out.push('目标 ' + kind + (name ? ':' + name : '') + ' → ' + entries.length + ' 个文件 / ' + (total / 1048576).toFixed(2) + ' MB');
+  out.push('目标 ' + kind + (name ? ':' + name : '') + '，' + entries.length + ' 个文件 / ' + (total / 1048576).toFixed(2) + ' MB');
   if (args.dry_run) {
     for (const e of entries.slice(0, 20)) out.push('  ' + e.rel + '  ' + e.bytes + ' B');
     const pre = scanAbsoluteRefs(ws, entries.map((e) => e.rel));
@@ -205,7 +205,7 @@ export function packNow(env, args, exec) {
   fs.writeFileSync(path.join(stagingRoot, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
   fs.writeFileSync(path.join(stagingRoot, 'CHECKSUMS.sha256'), files.map((f) => f.sha256 + '  ' + f.path).join(NL) + NL, 'utf8');
   const absLines = renderAbsoluteRefs(abs, { title: '绝对路径体检（包内）', max: 200 });
-  const md = ['# 迁移包（最简版）', '', '- 目标: ' + kind + (name ? ':' + name : ''), '- 生成: ' + manifest.createdAt, '- 文件: ' + files.length + ' 个 / ' + total + ' B', '- 说明: ' + (args.note || '（无）'), '', ...absLines, '', '## 跨平台注意', '', '- **库内引用一律相对路径**：本包里有 ' + abs.totalHits + ' 处写死的绝对路径，插件**只报告、不改写**文件内容——迁移后需由人或项目会话自己改。', '- 源平台 ' + manifest.sourcePlatform + '；换行 CRLF ' + abs.crlf + ' 个 / LF ' + abs.lf + ' 个' + (abs.nonUtf8.length ? '；非 UTF-8 ' + abs.nonUtf8.length + ' 个' : '') + '。', '- 目标机若是别的系统（Windows ↔ macOS/Linux）：盘符、路径分隔符、大小写敏感性、换行、编码都要项目会话自己核一遍。', '', '## 目标环境前置（先做这两件，再做恢复）', '', '1. 安装 dsh-handover 插件（否则本工具不存在）；', '2. 打开本包随附的交接文件（_Project_Meta/<项目名>/Handover.md 或全局 _Control_Center/records/Global_Handover.md），按它恢复状态。', '', '## 恢复', '', 'ho_pack(action="restore", pack="<本包绝对路径>", dry_run=true)   # 先预演，再加 apply=true', '', '> 会话本身**不迁移**：连续性只靠交接文档。'].join(NL);
+  const md = ['# 迁移包（最简版）', '', '- 目标: ' + kind + (name ? ':' + name : ''), '- 生成: ' + manifest.createdAt, '- 文件: ' + files.length + ' 个 / ' + total + ' B', '- 说明: ' + (args.note || '（无）'), '', ...absLines, '', '## 跨平台注意', '', '- **库内引用一律相对路径**：本包内有 ' + abs.totalHits + ' 处写死的绝对路径，插件只报告、不改写文件内容，迁移后须由人工或项目会话修改。', '- 源平台 ' + manifest.sourcePlatform + '；换行 CRLF ' + abs.crlf + ' 个 / LF ' + abs.lf + ' 个' + (abs.nonUtf8.length ? '；非 UTF-8 ' + abs.nonUtf8.length + ' 个' : '') + '。', '- 目标机若为其他系统（Windows ↔ macOS/Linux）：盘符、路径分隔符、大小写敏感性、换行与编码均须项目会话自行核对。', '', '## 目标环境前置（先完成这两项，再执行恢复）', '', '1. 安装 dsh-handover 插件（否则本工具不存在）；', '2. 打开本包随附的交接文件（_Project_Meta/<项目名>/Handover.md 或全局 _Control_Center/records/Global_Handover.md），按其中内容恢复状态。', '', '## 恢复', '', 'ho_backup(action="restore", pack="<本包绝对路径>", dry_run=true)   # 先预演，再加 apply=true', '', '> 会话本身不迁移：连续性只依托交接文档。'].join(NL);
   fs.writeFileSync(path.join(stagingRoot, 'MIGRATION.md'), md, 'utf8');
   const outDir = args.out || path.join(ws, '_Archives', '_Global', 'Backups');
   fs.mkdirSync(outDir, { recursive: true });
@@ -263,7 +263,7 @@ export function packVerify(env, args, exec) {
   out.push('文件 ' + manifest.files.length + ' 个；一致 ' + same.length + ' / 漂移 ' + drift.length + ' / 缺失 ' + missing.length);
   for (const p of drift.slice(0, 10)) out.push('  漂移：' + p);
   for (const p of missing.slice(0, 10)) out.push('  缺失：' + p);
-  out.push(drift.length === 0 && missing.length === 0 ? '判定：包内即现版，可直接用' : '判定：**包已作废**（盘上已变），必须重打');
+  out.push(drift.length === 0 && missing.length === 0 ? '判定：包内即现版，可直接使用' : '判定：包已作废（磁盘内容已变更），须重新打包');
   return out.join(NL);
 }
 
@@ -323,10 +323,10 @@ export function packRestore(env, args, exec) {
   out.push('包 ' + packPath + '，目标 ' + target);
   out.push('文件 ' + manifest.files.length + ' 个；新增 ' + adds.length + ' / 覆盖 ' + overwrites.length);
   for (const p of overwrites.slice(0, 10)) out.push('  覆盖：' + p);
-  if (crossPlatform) out.push('注意：源平台 ' + manifest.sourcePlatform + ' ≠ 本机 ' + process.platform + '：路径分隔符、盘符、大小写、换行、编码都需要项目会话自己核一遍。');
+  if (crossPlatform) out.push('注意：源平台 ' + manifest.sourcePlatform + ' ≠ 本机 ' + process.platform + '；路径分隔符、盘符、大小写、换行与编码均须项目会话自行核对。');
   out.push(...renderAbsoluteRefs(abs, { title: '绝对路径体检（恢复前）', max: 20 }));
-  if (abs.totalHits) out.push('  ⇒ 这些位置插件**不会**改；迁移后由人或项目会话按新机器改，库内引用统一用相对路径。');
-  if (!apply) out.push('**预演**：未写入任何文件。确认无误后用 apply=true 再调一次。');
+  if (abs.totalHits) out.push('  上述位置插件不作改动；迁移后由人工或项目会话按新机器修改，库内引用统一使用相对路径。');
+  if (!apply) out.push('预演：未写入任何文件。确认无误后以 apply=true 再次调用。');
   else out.push('已写入；被覆盖的旧文件备份在 ' + backupDir);
   return out.join(NL);
 }

package/src/lib/pathkey.mjs

@@ -0,0 +1,24 @@
+/**
+ * 路径等价键：跨平台比较同一路径时用。
+ * Windows 与 macOS 的默认文件系统不区分大小写，Linux 区分；因此只在 win32 与 darwin 上折叠大小写。
+ * 反斜杠一律折成正斜杠，去掉末尾分隔符，便于比较用户输入与登记表里的路径。
+ * `platform` 可显式传入，便于按平台写单元测试。
+ */
+import path from 'node:path';
+
+/** 返回用于比较的路径键。 */
+export function pathKey(p, platform) {
+  const plat = platform || process.platform;
+  const norm = String(p || '').replace(/\\/g, '/').replace(/\/+$/, '');
+  return (plat === 'win32' || plat === 'darwin') ? norm.toLowerCase() : norm;
+}
+
+/** 两个路径是否指向同一位置（按当前或指定平台判定）。 */
+export function samePath(a, b, platform) {
+  return pathKey(a, platform) === pathKey(b, platform);
+}
+
+/** 把工作区相对路径（'/' 分隔）转成本机路径。 */
+export function relToAbs(root, rel) {
+  return path.join(root, String(rel).split('/').join(path.sep));
+}

package/src/lib/peer.mjs

@@ -3,7 +3,7 @@
  * 数据源与 peer-link 完全一致，不引入任何第三方依赖：
  *   ~/.dsh/storages/session_projcache/sessions/<session id>.json   水位 / 运行状态 / 项目名
  *   ~/.dsh/storages/workspace.json                                  工作区 id / 标题 / 路径
- *   ~/.dsh/sessions/<slug>/<session id>/session.v4.jsonl.zstd       会话日志（peer_peek 用）
+ *   ~/.dsh/sessions/<slug>/<session id>/session.v4.jsonl.zstd       会话日志（peer 的 peek 动作用）
  * 平级会话的判据：投影缓存里 **没有** record.rows.subagent.identity（子会话才有）。
  */
 import fs from 'node:fs';
@@ -159,7 +159,7 @@ export function stamp(ms) {
   return p(d.getMonth() + 1) + '-' + p(d.getDate()) + ' ' + p(d.getHours()) + ':' + p(d.getMinutes());
 }
 
-/** 一行式摘要（给 peer_list 用）。 */
+/** 一行式摘要（给 peer 的 list 动作用）。 */
 export function rowLine(sessionId, cache, fallback) {
   const pct = cache === null ? null : pressurePct(cache);
   const state = isBusy(cache) === true ? 'running' : fallback === undefined ? 'idle' : fallback;
@@ -171,14 +171,14 @@ export function rowLine(sessionId, cache, fallback) {
 
 /**
  * 会话清单：controller.list 的结果按 origin 过滤。
- * 冷会话在这一步就会被服务端从持久化里恢复成可寻址的行，所以 peer_list 本身不花 token。
+ * 冷会话在这一步就会被服务端从持久化里恢复成可寻址的行，所以 peer（action="list"）本身不花 token。
  */
 export async function sessionRows(controller, includeSubagents) {
   const value = await controller.list({}, new AbortController().signal);
   return value.items.filter((row) => includeSubagents === true || row.origin !== 'subagent');
 }
 
-// ---------------------------------------------------------------- 会话日志（peer_peek）
+// ---------------------------------------------------------------- 会话日志（peer 的 peek 动作）
 
 /** 解 zstd **多帧**日志并按行解析成事件数组；本 Node 构建没有 zstd 时返回 null。 */
 export function decodeSessionLog(file) {

package/src/lib/phase.mjs

@@ -3,34 +3,29 @@
 /**
  * @param {{ratio:number|null, compactionsUsed:number, cfg:object, lockState:string}} input
  * @returns {{action:string, reason:string}}
- *   action ∈ continue | pause | checkpoint | new_session | force_compact | blocked | unknown
+ *   action ∈ continue | checkpoint | force_compact | new_session | blocked | unknown
  */
 export function decide(input) {
   const cfg = input.cfg || {};
-  const warn = cfg.warnRatio === undefined ? 0.32 : cfg.warnRatio;
   const handover = cfg.handoverRatio === undefined ? 0.35 : cfg.handoverRatio;
   const hard = cfg.hardRatio === undefined ? 0.85 : cfg.hardRatio;
   const maxComp = cfg.maxCompactions === undefined ? 3 : cfg.maxCompactions;
   const used = typeof input.compactionsUsed === 'number' ? input.compactionsUsed : 0;
   if (input.lockState === 'orphaned') {
-    return { action: 'blocked', reason: '检测到未闭合的压缩锁（compaction/start 无配对 end）：先处理再排新压缩' };
+    return { action: 'blocked', reason: '检测到未闭合的压缩锁（compaction/start 无配对 end）：先处理压缩锁，再排新压缩' };
   }
   // 额度用尽优先于水位判定：3 次压满后再压不是「水位没到」，而是该换任了。
-  // 放在水位判定之前，force 也就绕不过去（force 只在水位分支里放行）。
   if (used >= maxComp) {
-    return { action: 'new_session', reason: '已压缩 ' + used + '/' + maxComp + ' 次：压缩额度用尽，应写交接并建新会话' };
+    return { action: 'new_session', reason: '已压缩 ' + used + '/' + maxComp + ' 次：压缩额度用尽，应写交接并新建会话' };
   }
   if (input.ratio === null || input.ratio === undefined) {
-    return { action: 'unknown', reason: '水位读不到：人工判断，不要盲目压缩' };
+    return { action: 'unknown', reason: '水位读不到：需人工判断，不得盲目压缩' };
   }
   if (input.ratio >= hard) {
-    return { action: 'force_compact', reason: '已到硬顶（' + Math.round(hard * 100) + '%）：强制压缩，哪怕任务中途' };
+    return { action: 'force_compact', reason: '已到硬顶（' + Math.round(hard * 100) + '%）：应强制压缩，任务中途亦同' };
   }
   if (input.ratio >= handover) {
-    return { action: 'checkpoint', reason: '过交接线（' + Math.round(handover * 100) + '%）：写交接，随后压缩，再读交接续跑' };
+    return { action: 'checkpoint', reason: '已过可压缩线（' + Math.round(handover * 100) + '%）：先刷新交接，再登记压缩' };
   }
-  if (input.ratio >= warn) {
-    return { action: 'pause', reason: '过提醒线（' + Math.round(warn * 100) + '%）：建议在阶段完成处调 ho_checkpoint（关键步骤返回 pause）' };
-  }
-  return { action: 'continue', reason: '水位正常' };
-}
+  return { action: 'continue', reason: '水位可继续；提前压缩仅在助手建议，或当前用户主动要求并授权时进行' };
+}

package/src/lib/profile.mjs

@@ -88,7 +88,7 @@ function defaultProfile(info) {
 
 function cleanList(v, field, errors) {
   if (v === undefined) return [];
-  if (!Array.isArray(v)) { errors.push(field + ' 必须是数组'); return []; }
+  if (!Array.isArray(v)) { errors.push(field + ' 须为数组'); return []; }
   const out = [];
   for (const x of v) {
     const s = String(x == null ? '' : x).trim().replace(/\\/g, '/');

package/src/lib/reminder.mjs

@@ -0,0 +1,110 @@
+/**
+ * 一次性后台提醒（1.0）：35% 与 50% 各投一次。
+ *
+ * 投递方式（用户定）：尾注入（Tail-end Injection）。插件工具返回结果时，把提醒贴在结果的末尾，
+ * 模型在下一步立刻读到；不改系统提示词（避免改写前缀缓存）、不拆回合、不另起消息、不打断工具。
+ * 不往会话日志写任何事件：宿主对 developer/message 有「必须匹配已打开的轮与步」的强校验，
+ * 写事件会把会话写成 SessionFormatError（已实测发生过）。
+ *
+ * 两处风险：
+ *   1) 压缩刚完成时投影缓存还是压缩前的旧水位，跳过恢复后的第一次判定。
+ *   2) 模型整轮不调用插件工具时没有注入点；此时它可自行用 ho_status 读水位。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readSessionPressurePct } from './sessions.mjs';
+
+export function remindersPath() {
+  return path.join(os.homedir(), '.dsh', 'storages', 'dsh-handover.reminders.json');
+}
+
+export function readReminderState() {
+  try {
+    const v = JSON.parse(fs.readFileSync(remindersPath(), 'utf8').replace(/^\uFEFF/, ''));
+    const sessions = v && typeof v.sessions === 'object' && v.sessions ? v.sessions : {};
+    return { version: 1, sessions };
+  } catch {
+    return { version: 1, sessions: {} };
+  }
+}
+
+function writeReminderState(state) {
+  const file = remindersPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + String.fromCharCode(10), 'utf8');
+  fs.renameSync(tmp, file);
+}
+
+/** 35% 提醒文本。 */
+export function remindText35() {
+  return '当前上下文约占窗口 35%。先把正在做的任务收束到可暂停的位置。'
+    + '随后判断剩余流程总量：较少则继续完成；较多则做完当前小步骤后停止，'
+    + '向当前用户确认是否继续，或写出剩余流程的行动计划、刷新交接，再压缩或换任。'
+    + '判定标准：完成全部剩余流程后，上下文占用不超过 45%。本条为一次性后台提醒。';
+}
+
+/** 50% 提醒文本。 */
+export function remindText50() {
+  return '当前上下文约占窗口 50%。先把正在做的任务收束到可暂停的位置。'
+    + '随后判断剩余流程总量：较少则继续完成；较多则做完当前小步骤后停止，'
+    + '向当前用户确认是否继续，或写出剩余流程的行动计划、刷新交接，再压缩或换任。'
+    + '判定标准：完成全部剩余流程后，上下文占用不超过 55%。本条为一次性后台提醒。';
+}
+
+/**
+ * 判定一次：水位到线且该线未提醒过时写状态并返回提醒正文。
+ * 只应由「工具返回结果」这条路径调用：那时模型正好在等下一次装配。
+ * @param {{ remindRatio?: number, remind2Ratio?: number }} cfg
+ * @param {string} sid 会话 id
+ * @returns {string} 提醒正文；不需要投时为空串
+ */
+export function checkReminder(cfg, sid) {
+  const id = String(sid || '');
+  if (!id) return '';
+  const state = readReminderState();
+  const rec = state.sessions[id] || {};
+  // 压缩刚完成后的那次判定：投影缓存可能还是压缩前的旧水位，跳过。
+  if (rec.skipNext) {
+    rec.skipNext = false;
+    state.sessions[id] = rec;
+    try { writeReminderState(state); } catch { /* 写盘失败不阻断工具 */ }
+    return '';
+  }
+  const pct = readSessionPressurePct(id);
+  if (pct === null || pct === undefined) return '';
+  const r1 = (cfg && cfg.remindRatio !== undefined ? cfg.remindRatio : 0.35) * 100;
+  const r2 = (cfg && cfg.remind2Ratio !== undefined ? cfg.remind2Ratio : 0.5) * 100;
+  const parts = [];
+  let changed = false;
+  if (pct >= r1 && !rec.r35) { rec.r35 = true; changed = true; parts.push(remindText35()); }
+  if (pct >= r2 && !rec.r50) { rec.r50 = true; changed = true; parts.push(remindText50()); }
+  if (!changed) return '';
+  state.sessions[id] = rec;
+  try { writeReminderState(state); } catch { /* 写盘失败不阻断工具 */ }
+  return parts.join(String.fromCharCode(10, 10));
+}
+
+/**
+ * 工具结果末尾的提醒尾巴：命中阈值时返回要 append 的文本，否则空串。
+ * 形如 `[System Note: …]`，紧贴工具结果，模型下一步立刻读到。
+ * @param {{ remindRatio?: number, remind2Ratio?: number }} cfg
+ * @param {string} sid 会话 id
+ */
+export function reminderTailNote(cfg, sid) {
+  const text = checkReminder(cfg, sid);
+  if (!text) return '';
+  return '[System Note: ' + text + ']';
+}
+
+/** 记一次「压缩后跳过下一轮判定」；由 ho_checkpoint 在登记压缩时写入。 */
+export function markSkipNext(sid) {
+  const id = String(sid || '');
+  if (!id) return;
+  const state = readReminderState();
+  const rec = state.sessions[id] || {};
+  rec.skipNext = true;
+  state.sessions[id] = rec;
+  try { writeReminderState(state); } catch { /* 写盘失败只影响一次判定 */ }
+}

package/src/lib/role.mjs

@@ -8,19 +8,22 @@ import path from 'node:path';
 import { readJsonDir, pick, isSafeName, assertSafeName } from './text.mjs';
 import { projCacheDir, isSubagent } from './sessions.mjs';
 import { globalWorkspaceSessionIds } from './registry.mjs';
-import { TOOL_NAMES, PEER_NAMES, nameOf, peerNameOf } from './names.mjs';
+import { TOOL_NAMES, PEER_NAME, nameOf } from './names.mjs';
 import { stampTz } from './brief.mjs';
 
 export const ROLES = ['global', 'project', 'misc', 'plain'];
 export const ROLE_LABEL = { global: '全局', project: '项目', misc: '杂项', plain: '普通' };
 
-export const ALL_TOOL_NAMES = TOOL_NAMES.concat(PEER_NAMES);
+export const ALL_TOOL_NAMES = TOOL_NAMES.concat([PEER_NAME]);
 
-/** 角色 → 可见工具（其余一律 deny）。改这张表就是改成本结构。 */
+/**
+ * 角色 → 可见工具（其余一律 deny）。改这张表就是改成本结构。
+ * 合并后一个工具内含多个动作，动作级权限在工具内部再判一次（见 tools/peer.mjs）。
+ */
 const ROLE_TOOLS = {
   global: ALL_TOOL_NAMES.slice(),
-  project: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('gate'), nameOf('snapshot'), nameOf('profile'), nameOf('office'), nameOf('succeed'), peerNameOf('send'), peerNameOf('status')],
-  misc: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('snapshot'), nameOf('profile'), nameOf('office'), nameOf('succeed'), peerNameOf('send'), peerNameOf('status'), peerNameOf('new')],
+  project: [nameOf('status'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('gate'), nameOf('backup'), nameOf('profile'), nameOf('office'), nameOf('succeed'), nameOf('docmap'), PEER_NAME],
+  misc: [nameOf('status'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('backup'), nameOf('profile'), nameOf('office'), nameOf('succeed'), nameOf('docmap'), PEER_NAME],
   plain: [],
 };
 
@@ -61,7 +64,7 @@ function writeRolesFile(cfg, data) {
 /** 写入/更新一条角色；返回写入后的条目。 */
 export function writeRole(cfg, sessionId, patch) {
   const sid = String(sessionId || '');
-  if (!sid) throw new Error('缺会话 id');
+  if (!sid) throw new Error('缺少会话 id');
   const data = readRoles(cfg);
   const prev = data.sessions[sid] || {};
   const next = Object.assign({}, prev, patch || {});

package/src/lib/scaffold.mjs

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { pathKey } from './pathkey.mjs';
 
 /** 插件自带的模板目录（dist/templates 或 src/templates）。 */
 const TPL = new URL('../templates/', import.meta.url);
@@ -20,8 +21,10 @@ const DEFAULT_ROOT_NAME = '_Workspace';
 const DIRS = [
   '_Control_Center/records',
   '_Control_Center/rules',
+  '_Control_Center/standards',
   '_Control_Center/templates',
   '_Control_Center/tools',
+  '_Control_Center/tasks',
   '_Control_Center/user',
   'Projects',
   '_Project_Meta',
@@ -33,35 +36,90 @@ const DIRS = [
 const FILES = [
   ['_Control_Center/records/Global_Handover.md', 'Handover.global.skeleton.md'],
   ['_Control_Center/records/Global_Changelog.md', 'Changelog.skeleton.md'],
+  // 全局总注册：只列各任务体系文件的路径；由 ho_docmap 或 scaffold 维护。
+  ['_Control_Center/records/systems.md', 'Systems.global.skeleton.md'],
   ['_Control_Center/rules/Workspace_Charter.md', 'Charter.skeleton.md'],
   ['_Control_Center/templates/Prompt_Templates.md', 'Prompt_Templates.md'],
+  ['_Control_Center/templates/Handover.md', 'Handover.template.md'],
+  ['_Control_Center/templates/Plan.skeleton.md', 'Plan.skeleton.md'],
+  ['_Control_Center/templates/System.skeleton.md', 'System.skeleton.md'],
+  // 通用规范：一条规范一个子目录，各角色会话都可读，只有全局写。
+  ['_Control_Center/standards/README.md', 'standards/README.md'],
+  ['_Control_Center/standards/写作规范/README.md', 'standards/写作规范/README.md'],
+  ['_Control_Center/standards/写作规范/依据_论文.md', 'standards/写作规范/依据_论文.md'],
   // 规则类：工作区没有这份时，ho_charter 会退回同名内置版本；这里先铺一份可改的默认口径。
   ['_Control_Center/rules/Handover_Rules.md', 'rules/Handover_Rules.md'],
   ['_Control_Center/rules/Migration_Rules.md', 'rules/Migration_Rules.md'],
   ['_Control_Center/rules/Misc_Task_Standard.md', 'rules/Misc_Task_Standard.md'],
+  ['_Control_Center/rules/Delegation_Rules.md', 'rules/Delegation_Rules.md'],
   ['_Control_Center/user/Writing_Rules.md', 'rules/Writing_Rules.md'],
 ];
 
 /** 规整用户粘贴的路径：去掉引号/尾分隔符、展开 ~、解析成绝对路径。 */
 function normalizeParent(input) {
   let s = String(input || '').trim();
-  if (!s) return { error: '先粘贴一个目录（父目录，全局根会建在它里面）' };
+  if (!s) return { error: '请先填写目录（父目录，全局根建于其中）' };
   s = s.replace(/^["']+|["']+$/g, '').trim();
-  if (!s) return { error: '先粘贴一个目录' };
+  if (!s) return { error: '请先填写目录' };
   if (s === '~') s = os.homedir();
   else if (s.startsWith('~/') || s.startsWith('~\\')) s = path.join(os.homedir(), s.slice(2));
   const abs = path.resolve(s);
   let st = null;
   try { st = fs.statSync(abs); } catch { st = null; }
-  if (st && !st.isDirectory()) return { error: '这不是一个目录：' + abs, path: abs };
+  if (st && !st.isDirectory()) return { error: '该路径不是目录：' + abs, path: abs };
   // 目标父目录不存在就建：允许直接指定尚不存在的路径。
   if (!st) {
     try { fs.mkdirSync(abs, { recursive: true }); }
-    catch (e) { return { error: '建不出这个目录：' + abs + '（' + String(e && e.message ? e.message : e) + '）', path: abs }; }
+    catch (e) { return { error: '无法创建该目录：' + abs + '（' + String(e && e.message ? e.message : e) + '）', path: abs }; }
   }
   return { parent: abs, createdParent: !st };
 }
 
+/**
+ * 在既有的全局根上补齐缺失的目录与说明文件：只新建，不覆盖，不删任何东西。
+ * 用途：插件新增了目录（例如通用规范库）后，已部署的工作区靠它一次补齐。
+ */
+export function ensureScaffold(root) {
+  const abs = String(root || '');
+  let st = null;
+  try { st = fs.statSync(abs); } catch { st = null; }
+  if (!st || !st.isDirectory()) return { ok: false, error: '全局根不存在或不是目录：' + (abs || '（空）') };
+
+  const created = [];
+  const written = [];
+  const skipped = [];
+  const missingTemplates = [];
+  for (const d of DIRS) {
+    const p = path.join(abs, d.split('/').join(path.sep));
+    if (!fs.existsSync(p)) created.push(d);
+    try {
+      fs.mkdirSync(p, { recursive: true });
+    } catch (e) {
+      return { ok: false, error: '建目录失败：' + d + '（' + String(e && e.message ? e.message : e) + '）', created, written, skipped };
+    }
+  }
+  for (const [rel, tpl] of FILES) {
+    const dst = path.join(abs, rel.split('/').join(path.sep));
+    if (fs.existsSync(dst)) { skipped.push(rel); continue; }
+    let body = '';
+    try {
+      body = template(tpl);
+    } catch {
+      // 内置模板缺失时不写空文件，登记后由调用方报出，避免静默留下半套体系。
+      missingTemplates.push(rel);
+      continue;
+    }
+    try {
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.writeFileSync(dst, body, 'utf8');
+      written.push(rel);
+    } catch (e) {
+      return { ok: false, error: '写文件失败（' + rel + '）：' + (e && e.message ? e.message : e), created, written, skipped, missingTemplates };
+    }
+  }
+  return { ok: true, created, written, skipped, missingTemplates };
+}
+
 /**
  * 建全局根。
  * @param parentInput 用户在设置页粘贴的路径
@@ -74,9 +132,9 @@ export function createGlobalWorkspace(parentInput, opts) {
 
   const name = (opts && typeof opts.name === 'string' && opts.name.trim()) || DEFAULT_ROOT_NAME;
   if (name.indexOf('/') !== -1 || name.indexOf('\\') !== -1 || name === '.' || name === '..') {
-    return { ok: false, error: '根目录名不能带路径分隔符：' + name };
+    return { ok: false, error: '根目录名不得含路径分隔符：' + name };
   }
-  const sameName = path.basename(t.parent).toLowerCase() === name.toLowerCase();
+  const sameName = pathKey(path.basename(t.parent)) === pathKey(name);
   const root = sameName ? t.parent : path.join(t.parent, name);
 
   let existed = false;
@@ -89,30 +147,14 @@ export function createGlobalWorkspace(parentInput, opts) {
     existed = true;
   }
 
-  const created = [];
   try {
     fs.mkdirSync(root, { recursive: true });
-    for (const d of DIRS) {
-      const p = path.join(root, d.split('/').join(path.sep));
-      fs.mkdirSync(p, { recursive: true });
-      created.push(d);
-    }
   } catch (e) {
     return { ok: false, root, error: '建目录失败：' + (e && e.message ? e.message : e) };
   }
 
-  const written = [];
-  const skipped = [];
-  for (const [rel, tpl] of FILES) {
-    const dst = path.join(root, rel.split('/').join(path.sep));
-    if (fs.existsSync(dst)) { skipped.push(rel); continue; }
-    try {
-      fs.writeFileSync(dst, template(tpl), 'utf8');
-      written.push(rel);
-    } catch (e) {
-      return { ok: false, root, created, written, error: '写文件失败（' + rel + '）：' + (e && e.message ? e.message : e) };
-    }
-  }
-
-  return { ok: true, root, existed, created, written, skipped };
+  // 铺目录与说明文件走同一套清单：init 与 scaffold 两处不得各写一份。
+  const sc = ensureScaffold(root);
+  if (!sc.ok) return { ok: false, root, created: sc.created, written: sc.written, error: sc.error };
+  return { ok: true, root, existed, created: sc.created, written: sc.written, skipped: sc.skipped };
 }

package/src/lib/schedule.mjs

@@ -28,7 +28,6 @@ export function createScheduler(deps) {
   const timers = new Map();
   let disposed = false;
 
-  // 用全局定时器：cordis 的 ctx.setTimeout 绑定调用方 fiber，工具调用返回后可能被一并释放
   // 用全局定时器：cordis 的 ctx.setTimeout 绑定调用方 fiber，工具调用返回后可能被一并释放。
   function later(fn, ms) {
     return setTimeout(fn, ms);
@@ -72,9 +71,9 @@ export function createScheduler(deps) {
 
   async function compactOnce(sessionId) {
     const agent = agentOf(sessionId);
-    if (!agent) throw new Error("agent 不在内存中（会话可能已休眠）");
+    if (!agent) throw new Error("会话不在内存中（可能已休眠）");
     const compaction = compactionOf(agent);
-    if (!compaction || typeof compaction.compactNow !== "function") throw new Error("compaction.compactNow 不可用（profile 级与会话作用域都没取到）");
+    if (!compaction || typeof compaction.compactNow !== "function") throw new Error("compaction.compactNow 不可用（profile 级与会话作用域均未取到）");
     const ac = new AbortController();
     const timer = later(() => ac.abort(new Error("timeout")), cfg.compactTimeoutMs || 120000);
     try {
@@ -129,7 +128,7 @@ export function createScheduler(deps) {
     if (!agent) { fail(sessionId, "会话不在内存，无法压缩"); return; }
     if (agent.status === "running") {
       const idle = await waitIdle(agent, cfg.waitIdleMs || 180000);
-      if (!idle) { fail(sessionId, "等了 " + Math.round((cfg.waitIdleMs || 180000) / 1000) + " 秒会话仍未空闲"); return; }
+      if (!idle) { fail(sessionId, "等待 " + Math.round((cfg.waitIdleMs || 180000) / 1000) + " 秒后，会话仍未空闲"); return; }
     }
     try {
       const result = await compactOnce(sessionId);
@@ -158,7 +157,7 @@ export function createScheduler(deps) {
     } catch (e) {
       const code = e && e.code;
       if (code === "busy") {
-        if (Date.now() - job.startedAt > (cfg.waitIdleMs || 180000)) { fail(sessionId, "压缩一直 busy（有别的压缩或排队工作）"); return; }
+        if (Date.now() - job.startedAt > (cfg.waitIdleMs || 180000)) { fail(sessionId, "压缩持续处于 busy 状态（存在其他压缩或排队工作）"); return; }
         retryLater(sessionId, 800);
         return;
       }
@@ -182,7 +181,7 @@ export function createScheduler(deps) {
     pending.delete(sessionId);
     note("checkpoint failed " + sessionId + ": " + msg);
     try {
-      promptSelf(sessionId, "【dsh-handover】压缩未执行：" + msg + "。历史没有被压缩，交接已就绪；请把这条消息原样告诉用户，不要自行重试压缩。").catch(() => {});
+      promptSelf(sessionId, "【dsh-handover】压缩未执行：" + msg + "。历史未被压缩，交接已就绪。请将本条消息原样告知当前用户，不得自行重试压缩。").catch(() => {});
     } catch { /* ignore */ }
   }
 

package/src/lib/session-create.mjs

@@ -16,7 +16,7 @@ export async function newSessionIn(env, opts) {
   }
   const workspaceId = String(o.workspaceId || '');
   const cwd = String(o.cwd || '');
-  if (!workspaceId && !cwd) return { error: '建会话要么给 workspaceId，要么给 cwd' };
+  if (!workspaceId && !cwd) return { error: '建会话须给出 workspaceId 或 cwd' };
   let created = null;
   try {
     created = workspaceId ? await controller.create({ workspaceId }) : await controller.create({ cwd });
@@ -24,10 +24,10 @@ export async function newSessionIn(env, opts) {
     return { error: '建会话失败：' + String(e && e.message ? e.message : e) };
   }
   const sessionId = String((created && created.sessionId) || '');
-  if (!sessionId) return { error: 'create 没有返回 sessionId' };
+  if (!sessionId) return { error: 'create 未返回 sessionId' };
   const title = String(o.title || '');
   if (title) {
-    try { if (typeof controller.rename === 'function') await controller.rename({ sessionId, title }); } catch { /* 改名失败可事后 peer_rename */ }
+    try { if (typeof controller.rename === 'function') await controller.rename({ sessionId, title }); } catch { /* 改名失败可事后用 peer（action="rename"） */ }
   }
   const role = String(o.role || '');
   if (role && role !== 'plain' && typeof env.writeRole === 'function') {