@mingmaple/dsh-handover 0.0.0-stage → 0.9.6

package/src/lib/profile.mjs

@@ -0,0 +1,204 @@
+/**
+ * 项目与杂项的骨架档案：由本会话自行判断、写入、注册；插件只校验与引用。
+ * 项目：_Project_Meta/<项目>/project.profile.json
+ * 杂项：_Misc/tasks/<任务>/task.profile.json
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isFile } from './text.mjs';
+
+const PROFILE_SCHEMA = 1;
+export const PROFILE_KINDS = ['application', 'animation', 'library', 'general'];
+const PROJECT_FILE = 'project.profile.json';
+const TASK_FILE = 'task.profile.json';
+
+const PRESETS = {
+  application: {
+    kind: 'application',
+    required: ['README.md', 'src'],
+    optional: ['SKILL.md', 'CHANGELOG.md'],
+    docs: ['docs/'],
+    gate: { libraryBlock: false },
+    notes: '构建型项目：不要求插件类项目的文档集。',
+  },
+  animation: {
+    kind: 'animation',
+    required: ['README.md'],
+    optional: ['src', 'public', 'assets'],
+    docs: [],
+    gate: { libraryBlock: false },
+    notes: '动画与视频项目：不要求代码库式的目录与文档。',
+  },
+  library: {
+    kind: 'library',
+    required: ['README.md', 'RULES.md'],
+    optional: ['docs/', 'SKILL.md'],
+    docs: ['docs/'],
+    gate: { libraryBlock: true },
+    notes: '库型项目：启用 24 行通用约束条校验。',
+  },
+  general: {
+    kind: 'general',
+    required: [],
+    optional: [],
+    docs: [],
+    gate: { libraryBlock: false },
+    notes: '通用骨架：只保留最小约束。',
+  },
+};
+
+export function presets() {
+  return JSON.parse(JSON.stringify(PRESETS));
+}
+
+export function profilePathFor(ws, info) {
+  if (!ws || !info) return null;
+  if (info.role === 'project' && info.project) return path.join(ws, '_Project_Meta', info.project, PROJECT_FILE);
+  if (info.role === 'misc' && info.task) return path.join(ws, '_Misc', 'tasks', info.task, TASK_FILE);
+  return null;
+}
+
+/** 未注册时的默认骨架：沿用现有目录约定，24 行约束条默认启用（向后兼容）。 */
+function defaultProfile(info) {
+  const base = {
+    schema: PROFILE_SCHEMA,
+    kind: 'general',
+    root: '',
+    required: [],
+    optional: [],
+    docs: [],
+    meta: [],
+    gate: { libraryBlock: true },
+    handover: { extraSections: [] },
+    notes: '未注册：按默认骨架运行。',
+  };
+  if (info && info.role === 'project' && info.project) {
+    base.root = 'Projects/' + info.project;
+    base.required = [];
+    base.optional = ['SKILL.md'];
+    base.meta = [];
+    base.notes = '未注册：按默认骨架运行，请由本项目会话补注册。';
+  } else if (info && info.role === 'misc' && info.task) {
+    base.root = '_Misc/tasks/' + info.task;
+    base.required = [];
+    base.notes = '未注册：按默认骨架运行，请由本任务会话补注册。';
+  }
+  return base;
+}
+
+function cleanList(v, field, errors) {
+  if (v === undefined) 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, '/');
+    if (!s) continue;
+    if (path.isAbsolute(s) || /^[A-Za-z]:/.test(s) || s.split('/').indexOf('..') !== -1) {
+      errors.push(field + ' 不得使用绝对路径或 ..：' + s);
+      continue;
+    }
+    if (out.indexOf(s) === -1) out.push(s);
+  }
+  return out;
+}
+
+/** 规范化并校验结构；返回 { profile, errors }。路径越界与类型错误进 errors。 */
+export function normalizeProfile(raw, info) {
+  const errors = [];
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const kind = PROFILE_KINDS.indexOf(String(src.kind || '')) !== -1 ? String(src.kind) : 'general';
+  const rootDefault = info && info.role === 'project' && info.project
+    ? 'Projects/' + info.project
+    : (info && info.role === 'misc' && info.task ? '_Misc/tasks/' + info.task : '');
+  const root = String(src.root || rootDefault).trim().replace(/\\/g, '/');
+  if (path.isAbsolute(root) || /^[A-Za-z]:/.test(root) || root.split('/').indexOf('..') !== -1) {
+    errors.push('root 不得使用绝对路径或 ..');
+  }
+  const profile = {
+    schema: PROFILE_SCHEMA,
+    kind,
+    root,
+    required: cleanList(src.required, 'required', errors),
+    optional: cleanList(src.optional, 'optional', errors),
+    docs: cleanList(src.docs, 'docs', errors),
+    meta: cleanList(src.meta, 'meta', errors),
+    gate: { libraryBlock: !!(src.gate && src.gate.libraryBlock === true) },
+    handover: { extraSections: cleanList(src.handover && src.handover.extraSections, 'handover.extraSections', errors) },
+    notes: String(src.notes == null ? '' : src.notes).trim(),
+  };
+  return { profile, errors };
+}
+
+export function readProfile(ws, info) {
+  const p = profilePathFor(ws, info);
+  if (!p) return { exists: false, path: null, profile: defaultProfile(info), errors: [] };
+  if (!isFile(p)) return { exists: false, path: p, profile: defaultProfile(info), errors: [] };
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const r = normalizeProfile(raw, info);
+    return { exists: true, path: p, profile: r.profile, errors: r.errors };
+  } catch (e) {
+    return { exists: true, path: p, profile: defaultProfile(info), errors: ['读或解析失败：' + (e && e.message ? e.message : String(e))] };
+  }
+}
+
+export function writeProfile(ws, info, raw) {
+  const p = profilePathFor(ws, info);
+  if (!p) throw new Error('当前角色没有骨架路径（须为项目或杂项）');
+  const r = normalizeProfile(raw, info);
+  if (r.errors.length) throw new Error('骨架结构不合法：' + r.errors.join('；'));
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  if (isFile(p)) fs.copyFileSync(p, p + '.bak');
+  fs.writeFileSync(p, JSON.stringify(r.profile, null, 2) + String.fromCharCode(10), 'utf8');
+  return { path: p, profile: r.profile };
+}
+
+/** 校验：结构错误与必需项缺失分开报；docs 与 optional 不强制存在。 */
+export function validateProfile(ws, info, profile) {
+  const p = profile || readProfile(ws, info).profile;
+  const errors = [];
+  const missing = [];
+  const root = path.join(ws, p.root || '');
+  for (const rel of p.required || []) {
+    const f = path.join(root, rel);
+    if (!fs.existsSync(f)) missing.push(rel);
+  }
+  const metaRoot = info && info.role === 'project' && info.project
+    ? path.join(ws, '_Project_Meta', info.project)
+    : (info && info.role === 'misc' && info.task ? path.join(ws, '_Misc', 'tasks', info.task) : null);
+  // meta 条目相对档案目录（_Project_Meta/<项目>/ 或 _Misc/tasks/<任务>/），不是库内路径；
+  // 报缺时给全路径，避免被读成库内或某个 _meta/ 子目录。
+  const metaLabel = info && info.role === 'project' && info.project
+    ? '_Project_Meta/' + info.project + '/'
+    : (info && info.task ? '_Misc/tasks/' + info.task + '/' : '');
+  if (metaRoot) {
+    for (const rel of p.meta || []) {
+      if (!fs.existsSync(path.join(metaRoot, rel))) missing.push(metaLabel + rel);
+    }
+  }
+  return { ok: errors.length === 0 && missing.length === 0, errors, missing };
+}
+
+/** 已注册骨架清单（读文件，不写）：项目与杂项各一组。 */
+export function listProfiles(ws) {
+  const out = [];
+  const scan = (dir, role, nameKey) => {
+    let names = [];
+    try { names = fs.readdirSync(dir); } catch { return; }
+    for (const name of names) {
+      const d = path.join(dir, name);
+      try { if (!fs.statSync(d).isDirectory()) continue; } catch { continue; }
+      const file = path.join(d, role === 'project' ? PROJECT_FILE : TASK_FILE);
+      const info = { role, project: role === 'project' ? name : '', task: role === 'misc' ? name : '' };
+      const r = readProfile(ws, info);
+      const v = validateProfile(ws, info, r.profile);
+      out.push({
+        role, name, path: file, exists: r.exists,
+        kind: r.profile.kind, ok: v.ok, missing: v.missing, errors: r.errors.concat(v.errors),
+      });
+    }
+  };
+  scan(path.join(ws, '_Project_Meta'), 'project');
+  scan(path.join(ws, '_Misc', 'tasks'), 'misc');
+  return out;
+}

package/src/lib/registry.mjs

@@ -0,0 +1,53 @@
+/** 工作区与会话生命周期：只走 DSH 官方服务（workspaceRegistry），读不到就明确报错，不自己改注册表文件。 */
+import os from 'node:os';
+import path from 'node:path';
+import { readUtf8 } from './text.mjs';
+
+function workspaceJsonPath() {
+  return path.join(os.homedir(), '.dsh', 'storages', 'workspace.json');
+}
+
+/** 读 workspace.json 的 workspaces 表（只读；读不到返回空表）。 */
+function readWorkspaceTable() {
+  try {
+    const data = JSON.parse(readUtf8(workspaceJsonPath()));
+    return (data && data.tables && data.tables.workspaces) || {};
+  } catch { return {}; }
+}
+
+/** 官方服务：ctx.workspaceRegistry（session-controller 就是这么用的）；无法获取返回 null。 */
+export function resolveRegistry(ctx) {
+  let v = null;
+  try { v = ctx.workspaceRegistry || null; } catch { /* ignore */ }
+  if (!v) { try { v = typeof ctx.get === 'function' ? ctx.get('workspaceRegistry') : null; } catch { /* ignore */ } }
+  return v || null;
+}
+
+/** 「全局」工作区里的会话 id 集合（判定会话是否属于全局）。 */
+export function globalWorkspaceSessionIds() {
+  const out = [];
+  const tables = readWorkspaceTable();
+  for (const id of Object.keys(tables)) {
+    const w = tables[id] || {};
+    const title = typeof w.title === 'string' ? w.title : '';
+    if (title.indexOf('全局') === -1) continue;
+    for (const sid of (Array.isArray(w.sessionIds) ? w.sessionIds : [])) {
+      if (out.indexOf(sid) === -1) out.push(sid);
+    }
+  }
+  return out;
+}
+
+/** 工作区表投影：id / 标题 / 路径 / 会话数，供 ho_workspace list 用。 */
+export function workspaceRows() {
+  const tables = readWorkspaceTable();
+  return Object.keys(tables).map((id) => {
+    const w = tables[id] || {};
+    return {
+      id,
+      title: typeof w.title === 'string' ? w.title : '-',
+      path: typeof w.path === 'string' ? w.path : '-',
+      sessions: Array.isArray(w.sessionIds) ? w.sessionIds.length : 0,
+    };
+  });
+}

package/src/lib/retarget-helper.tmpl

@@ -0,0 +1,46 @@
+// dsh-handover 登记改址助手（由插件生成，勿手改）
+// 只改 DSH 的登记文件（workspace.json、聊天集成的归属表），不动任何数据文件。
+import fs from 'node:fs';
+
+const LOG = %%LOG%%;
+const WAIT_PID = Number(process.argv[2] || 0) || 0;
+const FROM = %%FROM%%;
+const TO = %%TO%%;
+const FILES = %%FILES%%;
+
+function log(m) {
+  try { fs.appendFileSync(LOG, new Date().toISOString() + '  ' + m + '\n', 'utf8'); } catch { /* ignore */ }
+  try { console.log(m); } catch { /* ignore */ }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function alive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === 'EPERM'; }
+}
+const esc = (p) => JSON.stringify(String(p)).slice(1, -1);
+
+(async () => {
+  log('== 登记改址助手 ==  pid=' + process.pid);
+  if (WAIT_PID) {
+    log('等待 DSH 退出（最多 30 分钟）…');
+    for (let i = 0; i < 900; i++) { if (!alive(WAIT_PID)) break; await sleep(2000); }
+    if (alive(WAIT_PID)) { log('[中止] 等 DSH 退出超时，未做任何改动'); process.exit(1); }
+    await sleep(1500);
+    log('DSH 已退出，开始改址');
+  }
+  const from = esc(FROM);
+  const to = esc(TO);
+  let changed = 0;
+  for (const p of FILES) {
+    let text = '';
+    try { text = fs.readFileSync(p, 'utf8'); } catch { log('跳过（读不到）：' + p); continue; }
+    const n = text.split(from).length - 1;
+    if (!n) { log('无需改：' + p); continue; }
+    const bak = p + '.bak-' + new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
+    try { fs.copyFileSync(p, bak); } catch { log('跳过（备份失败）：' + p); continue; }
+    try { fs.writeFileSync(p, text.split(from).join(to), 'utf8'); } catch (e) { log('跳过（写入失败）：' + p + ' :: ' + e.message); continue; }
+    changed += n;
+    log('已改 ' + n + ' 处：' + p + '   备份 ' + bak);
+  }
+  log(changed ? ('完成：共改 ' + changed + ' 处登记，重启 DSH 后工作区即在新位置。') : '无需改动。');
+})();

package/src/lib/role.mjs

@@ -0,0 +1,217 @@
+/**
+ * 会话角色：判定、逐角色交接路径、工具集与文案。角色表是本机状态（不进仓库、不进迁移包）。
+ * 判定顺序：角色表 → 全局标题 → 全局工作区 → 子会话（默认普通）→ cwd（Projects/<名> 或 _Misc/tasks/<任务>）→ 首条提示 → 普通。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonDir, pick } 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 { 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);
+
+/** 角色 → 可见工具（其余一律 deny）。改这张表就是改成本结构。 */
+const ROLE_TOOLS = {
+  global: ALL_TOOL_NAMES.slice(),
+  project: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('gate'), nameOf('snapshot'), nameOf('profile'), peerNameOf('send'), peerNameOf('status')],
+  misc: [nameOf('phase'), nameOf('handover'), nameOf('checkpoint'), nameOf('charter'), nameOf('snapshot'), nameOf('profile'), peerNameOf('send'), peerNameOf('status'), peerNameOf('new')],
+  plain: [],
+};
+
+export function toolsetFor(role) {
+  const allow = ROLE_TOOLS[role] || ROLE_TOOLS.plain;
+  const deny = ALL_TOOL_NAMES.filter((n) => allow.indexOf(n) === -1);
+  return { allow: allow.slice(), deny };
+}
+
+// ---------------------------------------------------------------- 角色表（本机状态）
+
+export function rolesPath(cfg) {
+  try {
+    if (cfg && cfg.rolesPath) return String(cfg.rolesPath);
+  } catch { /* ignore */ }
+  return path.join(os.homedir(), '.dsh', 'storages', 'dsh-handover.roles.json');
+}
+
+export function readRoles(cfg) {
+  try {
+    const j = JSON.parse(fs.readFileSync(rolesPath(cfg), 'utf8'));
+    const sessions = j && typeof j.sessions === 'object' && j.sessions ? j.sessions : {};
+    return { version: 1, sessions };
+  } catch {
+    return { version: 1, sessions: {} };
+  }
+}
+
+function writeRolesFile(cfg, data) {
+  const file = rolesPath(cfg);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + String.fromCharCode(10), 'utf8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/** 写入/更新一条角色；返回写入后的条目。 */
+export function writeRole(cfg, sessionId, patch) {
+  const sid = String(sessionId || '');
+  if (!sid) throw new Error('缺会话 id');
+  const data = readRoles(cfg);
+  const prev = data.sessions[sid] || {};
+  const next = Object.assign({}, prev, patch || {});
+  next.setAt = stampTz(Date.now());
+  // 角色变了就重新引导一次；只是改项目名也重引导，因为路径变了。
+  if (prev.role !== next.role || prev.project !== next.project || prev.task !== next.task) delete next.bootstrappedAt;
+  data.sessions[sid] = next;
+  writeRolesFile(cfg, data);
+  return next;
+}
+
+export function bootstrappedAt(cfg, sessionId) {
+  const cur = readRoles(cfg).sessions[String(sessionId || '')];
+  return cur && cur.bootstrappedAt ? String(cur.bootstrappedAt) : '';
+}
+
+// ---------------------------------------------------------------- 判定
+
+/** 从投影缓存读会话的 cwd 与首条提示（读不到返回空串）。 */
+export function sessionMeta(sessionId) {
+  const sid = String(sessionId || '');
+  if (!sid) return { cwd: '', firstPrompt: '', subagent: false };
+  for (const f of readJsonDir(projCacheDir())) {
+    if (f.name.replace('.json', '') !== sid) continue;
+    return {
+      cwd: String(pick(f.data, 'record', 'identity', 'cwd') || ''),
+      firstPrompt: String(pick(f.data, 'record', 'rows', 'titleInput', 'val', 'first', 'text') || ''),
+      subagent: isSubagent(f.data),
+    };
+  }
+  return { cwd: '', firstPrompt: '', subagent: false };
+}
+
+function parts(p) {
+  return String(p || '').replace(/\\/g, '/').split('/').filter(Boolean);
+}
+
+/** cwd 落在 Projects/<名>/ 或 _Misc/tasks/<任务>/ 里就据此判定。 */
+function roleFromPath(cwd) {
+  const seg = parts(cwd);
+  for (let i = 0; i < seg.length; i++) {
+    if (seg[i] === 'Projects' && seg[i + 1] && seg[i + 1] !== '_Project_Meta') {
+      return { role: 'project', project: seg[i + 1], task: '' };
+    }
+    if (seg[i] === '_Misc' && seg[i + 1] === 'tasks' && seg[i + 2]) {
+      return { role: 'misc', project: '', task: seg[i + 2] };
+    }
+    if (seg[i] === '_Project_Meta' && seg[i + 1]) {
+      return { role: 'project', project: seg[i + 1], task: '' };
+    }
+  }
+  return null;
+}
+
+/** 首条提示里能解析出 Projects/<名>/ 或「<名>」项目 就算项目会话。 */
+function roleFromPrompt(text) {
+  const t = String(text || '').replace(/\\/g, '/');   // Windows 路径也能解析
+  const i = t.indexOf('Projects/');
+  if (i !== -1) {
+    const rest = t.slice(i + 'Projects/'.length);
+    let name = '';
+    for (const ch of rest) {
+      if (ch === '/' || ch === ' ' || ch === String.fromCharCode(9) || ch === String.fromCharCode(10) || ch === String.fromCharCode(13)) break;
+      name += ch;
+    }
+    if (name) return { role: 'project', project: name, task: '' };
+  }
+  const q = t.indexOf(String.fromCharCode(12300));
+  if (q !== -1) {
+    const rest = t.slice(q + 1);
+    const j = rest.indexOf(String.fromCharCode(12301) + '项目');
+    if (j > 0) return { role: 'project', project: rest.slice(0, j), task: '' };
+  }
+  return null;
+}
+
+/**
+ * 判定一个会话的角色。
+ * @param {{ cfg?: object, sessionId?: string, title?: string, cwd?: string, firstPrompt?: string, roles?: object }} opts
+ */
+export function resolveRole(opts) {
+  const o = opts || {};
+  const sid = String(o.sessionId || '');
+  const store = o.roles || readRoles(o.cfg);
+  const hit = sid ? store.sessions[sid] : null;
+  if (hit) {
+    const role = String(hit.role || '');
+    if (ROLES.indexOf(role) !== -1) {
+      return { role, project: String(hit.project || ''), task: String(hit.task || ''), source: 'store', sessionId: sid };
+    }
+    // 旧角色表的 unknown 是兜底态，按新口径并入普通。
+    if (role === 'unknown') {
+      return { role: 'plain', project: String(hit.project || ''), task: String(hit.task || ''), source: 'store', sessionId: sid };
+    }
+  }
+  const title = String(o.title || '');
+  if (title.indexOf('全局') !== -1) return { role: 'global', project: '', task: '', source: 'title', sessionId: sid };
+  try {
+    if (sid && globalWorkspaceSessionIds().indexOf(sid) !== -1) {
+      return { role: 'global', project: '', task: '', source: 'workspace', sessionId: sid };
+    }
+  } catch { /* 读不到工作区表就继续往下判 */ }
+  // 子会话默认按普通处理，不再按 cwd 注入项目段；项目中显式指定角色的子会话仍以角色表为准。
+  if (o.subagent === true) return { role: 'plain', project: '', task: '', source: 'subagent', sessionId: sid };
+  const byPath = roleFromPath(o.cwd);
+  if (byPath) return Object.assign(byPath, { source: 'cwd', sessionId: sid });
+  const byPrompt = roleFromPrompt(o.firstPrompt);
+  if (byPrompt) return Object.assign(byPrompt, { source: 'prompt', sessionId: sid });
+  return { role: 'plain', project: '', task: '', source: 'none', sessionId: sid };
+}
+
+// ---------------------------------------------------------------- 路径
+
+/**
+ * 逐角色交接路径。
+ * @returns {{ path: string|null, kind: string|null, scope: string, role: string, reason?: string }}
+ */
+export function handoverPathFor(ws, info) {
+  const role = info && info.role ? info.role : 'plain';
+  if (!ws) return { path: null, kind: null, scope: '', role, reason: '没有工作区根' };
+  if (role === 'global') {
+    return { path: path.join(ws, '_Control_Center', 'records', 'Global_Handover.md'), kind: 'global', scope: '_Global', role };
+  }
+  if (role === 'project') {
+    const project = String(info.project || '');
+    if (!project) return { path: null, kind: null, scope: '', role, reason: '项目名缺失' };
+    return { path: path.join(ws, '_Project_Meta', project, 'Handover.md'), kind: 'project', scope: project, role, project };
+  }
+  if (role === 'misc') {
+    const task = String(info.task || '');
+    if (!task) return { path: null, kind: null, scope: '', role, reason: '任务名缺失' };
+    return { path: path.join(ws, '_Misc', 'tasks', task, 'Handover.md'), kind: 'misc', scope: path.join('_Misc', task), role, task };
+  }
+  if (role === 'plain') return { path: null, kind: null, scope: '', role, reason: '普通会话不参与交接' };
+  return { path: null, kind: null, scope: '', role, reason: '本会话未设定角色' };
+}
+
+export function snapshotDirFor(ws, info) {
+  const t = handoverPathFor(ws, info);
+  return path.join(ws, '_Temp', t.scope || '_Global', 'Snapshots');
+}
+
+export function archiveDirFor(ws, info) {
+  const t = handoverPathFor(ws, info);
+  return path.join(ws, '_Archives', t.scope || '_Global', 'Handover');
+}
+
+export function scopeLabel(info) {
+  const role = info && info.role ? info.role : 'plain';
+  if (role === 'project') return '项目「' + (info.project || '?') + '」';
+  if (role === 'misc') return '杂项任务「' + (info.task || '?') + '」';
+  return ROLE_LABEL[role] || role;
+}

package/src/lib/rpc-carrier.mjs

@@ -0,0 +1,65 @@
+/**
+ * DSH 认证的 /api 载体（客户端设置页取数/下指令的**主通道**）。
+ *
+ * 为什么不用裸 fetch：本机 GUI 服务器对非浏览器策略的请求直接 403「Browser access is disabled」，
+ * 而 DSH 的 /api 载体自带浏览器鉴权与 Host/Origin 信任，dsh-im 的设置页正是走这条。
+ * 契约（与 DSH 内置管理 RPC 一致）：
+ *   入：POST /api/dsh-handover  body={type:'client-request', rpcId, method:'dsh-handover', payload:{method, payload}}
+ *   出：{type:'server-response', rpcId, result:{ok:true,value} | {ok:false,error:{code,message,details}}}
+ * 旧宿主没有 connection 服务时静默跳过，HTTP 路由继续兜底。
+ */
+const CARRIER_PATH = '/api/dsh-handover';
+const CARRIER_METHOD = 'dsh-handover';
+
+export function registerRpcCarrier(ctx, api, log) {
+  const say = typeof log === 'function' ? log : () => {};
+  let inner;
+  try {
+    inner = (cc) => {
+      const conn = cc && cc.connection ? cc.connection : null;
+      const reg = conn && conn.fetch && typeof conn.fetch.register === 'function' ? conn.fetch : null;
+      if (!reg) { say('载体：connection.fetch.register 不可用，退回 HTTP 路由'); return; }
+      let dispose = null;
+      try {
+        dispose = reg.register.call(reg, {
+          path: CARRIER_PATH,
+          methods: ['POST'],
+          requestBody: 'buffered',
+          async fetch(request) {
+            if (request.method !== 'POST') return new Response('method not allowed', { status: 405 });
+            let msg = null;
+            try { msg = await request.json(); } catch { return new Response('body is not JSON', { status: 400 }); }
+            const rpcId = msg && typeof msg.rpcId === 'string' ? msg.rpcId : 'invalid-request';
+            const call = msg && msg.payload;
+            const sane = msg && msg.type === 'client-request' && msg.method === CARRIER_METHOD
+              && call && typeof call.method === 'string' && Object.prototype.hasOwnProperty.call(call, 'payload');
+            if (!sane) {
+              return Response.json({ type: 'server-response', rpcId, result: { ok: false, error: { code: 'bad-request', message: '信封不合法', details: {} } } });
+            }
+            let r;
+            try { r = await api.call(call.method, call.payload); }
+            catch (e) { r = { ok: false, error: { code: 'failed', message: String(e && e.message ? e.message : e), details: {} } }; }
+            say('载体 ' + call.method + (r.ok ? ' ok' : (' 失败：' + String((r.error && r.error.message) || ''))));
+            return Response.json({ type: 'server-response', rpcId, result: r });
+          },
+        });
+        say('载体：已注册 ' + CARRIER_PATH);
+      } catch (e) {
+        say('载体注册失败：' + String(e && e.message ? e.message : e));
+        return;
+      }
+      try {
+        if (typeof cc.effect === 'function') cc.effect(() => dispose, 'dsh-handover: /api 载体');
+      } catch { /* ignore */ }
+    };
+  } catch (e) {
+    say('载体装配失败：' + String(e && e.message ? e.message : e));
+    return;
+  }
+  try {
+    if (typeof ctx.inject === 'function') ctx.inject(['connection'], inner);
+    else say('载体：宿主不支持 ctx.inject，退回 HTTP 路由');
+  } catch (e) {
+    say('载体装配失败：' + String(e && e.message ? e.message : e));
+  }
+}