@mingmaple/dsh-handover 0.0.0-stage → 0.9.6

package/src/lib/status.mjs

@@ -0,0 +1,171 @@
+/**
+ * 设置页用的状态快照（只读）：插件自身状态 ＋ 闸门 ＋ 交接体检 ＋ 会话水位 ＋ 最近一次守卫判定。
+ * 全部读本地文件，不唤醒任何会话、不花任何会话的 token。
+ * 任何一段出错都只让该段带 error 字段，不让整页 500。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDir } from './text.mjs';
+import { syncCheck } from './gates.mjs';
+import { lintGlobal, lintProject } from './lint.mjs';
+import { scanSessions } from './sessions.mjs';
+import { routeWorkspace, hasCenter } from './workspace.mjs';
+import { stampTz } from './brief.mjs';
+import { buildGuide, SETUP_STEPS } from './guide.mjs';
+import { readRoles, resolveRole, ROLE_LABEL, sessionMeta } from './role.mjs';
+import { listConsent } from './consent.mjs';
+import { listProfiles } from './profile.mjs';
+
+function guard(fn, fallback) {
+  try { return fn(); } catch (e) { return { ...fallback, error: String(e && e.message ? e.message : e) }; }
+}
+
+/** 项目交接体检：_Project_Meta/<项目>/Handover.md。 */
+function lintProjects(ws) {
+  const out = [];
+  let dirs = [];
+  try { dirs = fs.readdirSync(path.join(ws, '_Project_Meta')).sort(); } catch { return out; }
+  for (const name of dirs) {
+    const dir = path.join(ws, '_Project_Meta', name);
+    try { if (!isDir(dir)) continue; } catch { continue; }
+    const r = lintProject(path.join(dir, 'Handover.md'));
+    out.push({ name, verdict: r.verdict, reasons: Array.isArray(r.reasons) ? r.reasons.slice(0, 5) : [] });
+  }
+  return out;
+}
+
+export function buildStatus(env, extra) {
+  const info = extra || {};
+  const ws = routeWorkspace(env);
+  const found = hasCenter(ws);
+  const warn = Math.round((env.cfg.warnRatio || 0.32) * 100);
+  const out = {
+    generatedAt: stampTz(Date.now()),
+    plugin: {
+      name: info.name || '@mingmaple/dsh-handover',
+      version: info.version || '?',
+      tools: typeof info.tools === 'number' ? info.tools : 0,
+      inject: guard(() => env.injectList(), []),
+      initErrors: guard(() => env.initErrors(), []),
+      scheduler: info.scheduler || '未知',
+    },
+    workspace: { root: ws, found },
+    ratios: guard(() => ({
+      warn: Math.round((env.cfg.warnRatio !== undefined ? env.cfg.warnRatio : 0.32) * 100),
+      handover: Math.round((env.cfg.handoverRatio !== undefined ? env.cfg.handoverRatio : 0.35) * 100),
+      hard: Math.round((env.cfg.hardRatio !== undefined ? env.cfg.hardRatio : 0.85) * 100),
+    }), { warn: 32, handover: 35, hard: 85 }),
+    guardLast: guard(() => env.guardLast(), null),
+    extraPrompt: guard(() => (typeof env.extraPrompt === 'function' ? env.extraPrompt() : ''), ''),
+    extraPromptEnabled: guard(() => (typeof env.extraPromptEnabled === 'function' ? env.extraPromptEnabled() : false), false),
+    extraPromptOrder: 950,
+    roles: guard(() => {
+      const store = readRoles(env.cfg);
+      const map = {};
+      for (const sid of Object.keys(store.sessions)) {
+        const e = store.sessions[sid] || {};
+        map[sid] = { role: String(e.role || ''), project: String(e.project || ''), task: String(e.task || ''), setAt: String(e.setAt || ''), bootstrappedAt: String(e.bootstrappedAt || '') };
+      }
+      return map;
+    }, {}),
+    consent: guard(() => listConsent(), []),
+    profiles: guard(() => listProfiles(ws), []),
+    guide: guard(() => buildGuide(env.cfg), { intro: [], situations: [], groups: [], rules: [] }),
+    gate: null,
+    handover: null,
+    sessions: null,
+    notes: [],
+  };
+
+  if (!found) {
+    out.notes.push('未找到 _Control_Center：这个实例还没接入工作区。可在插件 config 里写 workspaceRoot。');
+    out.notes.push('插件本身已加载：工具与设置页不依赖工作区，只有闸门、交接、会话三段需要工作区。');
+    out.setup = { steps: SETUP_STEPS };
+    return out;
+  }
+
+  out.gate = guard(() => {
+    const g = syncCheck(ws);
+    return {
+      ok: !!g.ok,
+      error: g.error || '',
+      verdict: g.verdict || '',
+      total: g.total || 0,
+      bodyLines: g.bodyLines || 0,
+      libraries: (g.libraries || []).map((r) => ({
+        name: r.name, ok: !!r.ok, titleOk: !!r.titleOk, waterOk: !!r.waterOk,
+        missing: r.missing ? r.missing.length : 0, lines: r.total || 0,
+      })),
+    };
+  }, { ok: false, libraries: [] });
+
+  out.handover = guard(() => {
+    const g = lintGlobal(path.join(ws, '_Control_Center', 'records', 'Global_Handover.md'));
+    const projects = lintProjects(ws);
+    return {
+      global: { verdict: g.verdict, reasons: Array.isArray(g.reasons) ? g.reasons.slice(0, 5) : [] },
+      projects,
+      fail: projects.filter((p) => p.verdict === '不合格').length,
+    };
+  }, { global: { verdict: '读不到', reasons: [] }, projects: [], fail: 0 });
+
+  out.sessions = guard(() => {
+    const scan = scanSessions({
+      dir: env.cacheDir(),
+      meId: null,
+      meCwd: null,
+      warn,
+      silentHours: env.cfg.sessionScanHours,
+      projectsOnly: true,
+    });
+    const store = readRoles(env.cfg);
+    const roleOf = (sid, cwd, firstPrompt, title) => {
+      const meta = sessionMeta(sid);
+      return resolveRole({ cfg: env.cfg, roles: store, sessionId: sid, cwd, firstPrompt, subagent: meta.subagent, title });
+    };
+    const wide = scanSessions({
+      dir: env.cacheDir(), meId: null, meCwd: null, warn, silentHours: env.cfg.sessionScanHours, projectsOnly: false,
+    });
+    const all = wide.rows.filter((r) => r.kind === '平级').map((r) => {
+      const meta = sessionMeta(r.sid);
+      const info = roleOf(r.sid, meta.cwd, meta.firstPrompt, r.project);
+      return {
+        sid: r.sid,
+        title: r.project === '-' ? '' : r.project,
+        role: info.role,
+        roleLabel: ROLE_LABEL[info.role] || info.role,
+        source: info.source,
+        project: info.project,
+        task: info.task,
+        pct: r.pct,
+        state: r.state,
+        active: r.mtime >= scan.cutoffMs,
+        seen: stampTz(r.mtime),
+      };
+    });
+    return {
+      rows: scan.rows.slice(0, 60).map((r) => {
+        const meta = sessionMeta(r.sid);
+        const info = roleOf(r.sid, meta.cwd, meta.firstPrompt, r.project);
+        return {
+          sid: r.sid, project: r.project, pct: r.pct, state: r.state,
+          role: info.role, roleLabel: ROLE_LABEL[info.role] || info.role,
+          active: r.mtime >= scan.cutoffMs, seen: stampTz(r.mtime),
+        };
+      }),
+      all,
+      notify: scan.notify.map((r) => ({ sid: r.sid, project: r.project })),
+      hot: scan.hot.length,
+      unknown: scan.unknown.length,
+      cutoff: stampTz(scan.cutoffMs),
+      silentHours: scan.silentHours,
+      verdict: scan.hot.length
+        ? scan.hot.length + ' 个会话已进预警区（不低于 ' + warn + '%），应先收齐交接，再换会话'
+        : '没有会话进入预警区。',
+    };
+  }, { rows: [], notify: [], hot: 0, unknown: 0 });
+
+  if (out.gate && !out.gate.ok && !out.gate.error) out.notes.push('通用约束条闸门未过：向对应项目会话派发，全局不代写项目库内文件。');
+  if (out.handover && out.handover.fail) out.notes.push(out.handover.fail + ' 个项目交接体检不合格，交接前必须先补。');
+  return out;
+}

package/src/lib/text.mjs

@@ -0,0 +1,74 @@
+/** 文本/文件小工具：无第三方依赖，全部同步 IO（工具调用内使用）。 */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const NL = String.fromCharCode(10);
+
+export function readUtf8(p) {
+  return fs.readFileSync(p, 'utf8');
+}
+
+export function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+export function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * 读目录下全部 *.json，返回 [{ name, path, data, mtimeMs }]，读不动的跳过。
+ *
+ * 投影缓存里有几百个文件、几十 MB，单次读取约 0.2 秒；按会话逐条判定角色时会反复调用。
+ * 因此加一层 1.5 秒的进程内缓存：同一轮状态计算只解析一次，跨轮仍是新数据。
+ */
+const JSON_DIR_TTL_MS = 1500;
+const jsonDirCache = new Map();
+
+export function readJsonDir(dir) {
+  const key = String(dir);
+  const now = Date.now();
+  const hit = jsonDirCache.get(key);
+  if (hit && now - hit.at < JSON_DIR_TTL_MS) return hit.items;
+  const out = [];
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return out; }
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const p = path.join(dir, name);
+    try {
+      const st = fs.statSync(p);
+      if (!st.isFile()) continue;
+      out.push({ name, path: p, data: JSON.parse(fs.readFileSync(p, 'utf8')), mtimeMs: st.mtimeMs });
+    } catch { /* 跳过坏文件 */ }
+  }
+  jsonDirCache.set(key, { at: Date.now(), items: out });
+  return out;
+}
+
+/** 安全按路径取值，无法获取返回 null。 */
+export function pick(node) {
+  let cur = node;
+  for (let i = 1; i < arguments.length; i++) {
+    const k = arguments[i];
+    if (cur === null || typeof cur !== "object" || !(k in cur)) return null;
+    cur = cur[k];
+  }
+  return cur === undefined ? null : cur;
+}
+
+/** 按标题行切节：返回标题匹配 name 的整段（到下一个 ## 为止）；找不到返回 null。 */
+export function sectionLines(text, name) {
+  const lines = text.split(NL);
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith('## ') && lines[i].indexOf(name) !== -1) {
+      const out = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].startsWith('## ')) break;
+        out.push(lines[j]);
+      }
+      return out;
+    }
+  }
+  return null;
+}

package/src/lib/webroute.mjs

@@ -0,0 +1,130 @@
+/**
+ * 设置页数据的**旧通道**：GET /dsh-handover/status.json、POST /setup /register /extra-prompt /role。
+ *
+ * 主通道是 DSH 认证的 /api 载体（见 rpc-carrier.mjs）：本机 GUI 服务器对裸请求一律返回 403。
+ * 这里保留给没有 connection 服务的宿主与 CLI 作兜底，实现统一委托 api.mjs，避免两套逻辑漂移。
+ */
+import { createApi } from './api.mjs';
+
+const ROUTE = '/dsh-handover';
+const MAX_BODY = 64 * 1024;
+
+/** 读 JSON 请求体；出错返回 { error }。 */
+function readJson(req) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+    let size = 0;
+    const chunks = [];
+    try {
+      req.on('data', (c) => {
+        size += c.length;
+        if (size > MAX_BODY) { finish({ error: '请求体过大' }); try { req.destroy(); } catch { /* ignore */ } return; }
+        chunks.push(c);
+      });
+      req.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8').trim();
+        if (!text) { finish({ value: {} }); return; }
+        try { finish({ value: JSON.parse(text) }); } catch { finish({ error: '请求体不是合法 JSON' }); }
+      });
+      req.on('error', () => finish({ error: '读取请求体失败' }));
+    } catch {
+      finish({ error: '读取请求体失败' });
+    }
+  });
+}
+
+function sendJson(res, code, obj) {
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(JSON.stringify(obj));
+}
+
+function msgOf(e) { return String(e && e.message ? e.message : e); }
+
+export function registerStatusRoute(ctx, env, info, apiIn) {
+  const install = (wctx) => {
+    try {
+      const webServer = wctx && wctx.webServer;
+      if (!webServer || typeof webServer.register !== 'function') {
+        env.log('状态路由：webServer 不可用，跳过设置页 HTTP 兜底（主通道是 /api 载体）');
+        return;
+      }
+      const api = apiIn || createApi(env, info);
+
+      /** 旧通道出口：把统一信封翻成 { ok, ...value }（页面两种通道都能吃）。 */
+      const reply = (res, r) => {
+        if (!r || r.ok !== true) {
+          const err = (r && r.error) || {};
+          const out = { ok: false, error: String(err.message || '失败') };
+          if (err.details && typeof err.details === 'object') Object.assign(out, err.details);
+          sendJson(res, (r && r.http) || 400, out);
+          return;
+        }
+        const v = r.value && typeof r.value === 'object' ? r.value : { value: r.value };
+        sendJson(res, 200, Object.assign({ ok: true }, v));
+      };
+
+      const readBody = async (req, res) => {
+        const body = await readJson(req);
+        if (body.error) { sendJson(res, 400, { ok: false, error: body.error }); return null; }
+        return body.value || {};
+      };
+
+      const dispose = webServer.register({
+        kind: 'prefix',
+        path: ROUTE,
+        handler: async (req, res) => {
+          try {
+            const pathname = String((req && req.url) || '').split('?')[0];
+            const method = String((req && req.method) || 'GET').toUpperCase();
+            const tail = pathname.slice(ROUTE.length);
+            env.log('HTTP ' + method + ' ' + pathname);
+
+            if (tail === '/status.json') {
+              if (method !== 'GET' && method !== 'HEAD') {
+                res.writeHead(405, { allow: 'GET, HEAD' });
+                res.end();
+                return;
+              }
+              const r = await api.call('status', {});
+              if (r.ok !== true) { sendJson(res, r.http || 500, { error: String((r.error && r.error.message) || '失败') }); return; }
+              const body = JSON.stringify(r.value);
+              res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+              res.end(method === 'HEAD' ? undefined : body);
+              return;
+            }
+
+            if (tail === '/setup' || tail === '/register' || tail === '/extra-prompt' || tail === '/role') {
+              if (method !== 'POST') { res.writeHead(405, { allow: 'POST' }); res.end(); return; }
+              const input = await readBody(req, res);
+              if (input === null) return;
+              const name = tail.slice(1);
+              const r = await api.call(name, input);
+              if (name === 'setup') {
+                env.log('首次安装向导：' + (r.ok ? '已建 ' + String((r.value && r.value.root) || '') : '失败 ' + String((r.error && r.error.message) || '')));
+              }
+              if (name === 'extra-prompt') {
+                env.log('全局前置提示词：' + (r.ok ? (String((r.value && r.value.chars) || 0) + ' 字符') : '失败'));
+              }
+              reply(res, r);
+              return;
+            }
+
+            res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+            res.end('404');
+          } catch (e) {
+            try { sendJson(res, 500, { error: msgOf(e) }); } catch { /* 已结束 */ }
+          }
+        },
+      });
+      if (typeof wctx.effect === 'function') wctx.effect(() => dispose, 'dsh-handover: 设置页路由');
+    } catch (e) {
+      env.log('状态路由注册失败：' + msgOf(e));
+    }
+  };
+  try {
+    if (typeof ctx.inject === 'function') ctx.inject(['webServer'], install);
+  } catch (e) {
+    env.log('状态路由装配失败：' + msgOf(e));
+  }
+}

package/src/lib/workspace.mjs

@@ -0,0 +1,23 @@
+/** 工作区解析：路由侧（设置页，没有 exec）与工具侧共用一套判定。 */
+import path from 'node:path';
+import { isDir } from './text.mjs';
+import { workspaceRows } from './registry.mjs';
+
+export function hasCenter(p) {
+  if (!p || p === '-') return false;
+  try { return isDir(path.join(p, '_Control_Center')); } catch { return false; }
+}
+
+/**
+ * 没有 exec 时的兜底：配置 workspaceRoot → 标题含「全局」且带 _Control_Center 的工作区
+ * → 任一带 _Control_Center 的工作区 → 进程 cwd。
+ */
+export function routeWorkspace(env) {
+  try { if (env && env.cfg && env.cfg.workspaceRoot) return env.cfg.workspaceRoot; } catch { /* ignore */ }
+  let rows = [];
+  try { rows = workspaceRows(); } catch { rows = []; }
+  const list = Array.isArray(rows) ? rows : [];
+  for (const r of list) if (String(r.title).indexOf('全局') !== -1 && hasCenter(r.path)) return r.path;
+  for (const r of list) if (hasCenter(r.path)) return r.path;
+  try { return process.cwd(); } catch { return ''; }
+}

package/src/lib/zstd-log.mjs

@@ -0,0 +1,65 @@
+/** DSH 会话日志：定位 + 多帧 zstd 解码（与 handover_check.mjs 同一做法）。 */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+
+export function logsRoot() {
+  return path.join(os.homedir(), '.dsh', 'sessions');
+}
+
+/** 在 ~/.dsh/sessions 下找 <sid>/session.v4.jsonl.zstd（深度 ≤3）。 */
+export function findLog(sid, root) {
+  let hit = null;
+  const base = root || logsRoot();
+  const walk = (dir, depth) => {
+    if (hit || depth > 3) return;
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (!e.isDirectory()) continue;
+      const p = path.join(dir, e.name);
+      if (e.name === sid) {
+        const f = path.join(p, 'session.v4.jsonl.zstd');
+        if (fs.existsSync(f)) { hit = f; return; }
+      }
+      walk(p, depth + 1);
+    }
+  };
+  walk(base, 0);
+  return hit;
+}
+
+/** 解码多帧 zstd 日志，返回事件数组（坏帧跳过）。 */
+export function decodeLog(file) {
+  let buf;
+  try { buf = fs.readFileSync(file); } catch { return null; }
+  const starts = [];
+  let i = 0;
+  while (true) { const j = buf.indexOf(MAGIC, i); if (j < 0) break; starts.push(j); i = j + 4; }
+  if (!starts.length) return null;
+  starts.push(buf.length);
+  let text = "";
+  for (let k = 0; k < starts.length - 1; k++) {
+    try { text += zlib.zstdDecompressSync(buf.subarray(starts[k], starts[k + 1])).toString("utf8"); } catch { /* 坏帧 */ }
+  }
+  const out = [];
+  for (const line of text.split(String.fromCharCode(10))) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* 非 JSON 行 */ }
+  }
+  return out;
+}
+
+/** 取 turn/start 事件的时间戳序列（按时间排序）。 */
+export function turnStarts(records) {
+  const starts = [];
+  for (const r of records) {
+    if (!r || r.type !== "turn/start") continue;
+    const turn = r.data && typeof r.data.turn === "number" ? r.data.turn : null;
+    if (turn !== null && typeof r.time === "number") starts.push({ turn, time: r.time });
+  }
+  return starts.sort((a, b) => a.time - b.time);
+}

package/src/selftest.mjs

@@ -0,0 +1,84 @@
+/**
+ * 脱离 DSH 的自测台：用假 env 直接跑工具 execute，打印只读结果，供人工比对；不参与发布门禁。
+ * 用法：node selftest.mjs [--ws <工作区根>] [--session <session id>] [--tool brief|gate|sessions|phase|charter|all]
+ */
+import { resolveConfig } from './lib/config.mjs';
+import { projCacheDir, pressurePct } from './lib/sessions.mjs';
+import { readJsonDir, isDir } from './lib/text.mjs';
+import { pmBriefTool } from './tools/ho_brief.mjs';
+import { pmGateTool } from './tools/ho_gate.mjs';
+import { pmSessionsTool } from './tools/ho_sessions.mjs';
+import { pmPhaseTool } from './tools/ho_phase.mjs';
+import { pmCharterTool } from './tools/ho_charter.mjs';
+import path from 'node:path';
+
+const argv = process.argv.slice(2);
+function argOf(flag, dflt) {
+  const i = argv.indexOf(flag);
+  return i !== -1 && argv[i + 1] ? argv[i + 1] : dflt;
+}
+
+/** 从 cwd 向上找带 _Control_Center 的目录；找不到就用 cwd（公开仓库里不写死任何本机路径）。 */
+function autoWs() {
+  let cur = process.cwd();
+  for (let i = 0; i < 8 && cur; i++) {
+    if (isDir(path.join(cur, "_Control_Center"))) return cur;
+    const up = path.dirname(cur);
+    if (up === cur) break;
+    cur = up;
+  }
+  return process.cwd();
+}
+
+const ws = argOf("--ws", autoWs());
+const selfId = argOf("--session", "");
+const only = argOf("--tool", "all");
+
+const cfg = resolveConfig({ workspaceRoot: ws });
+const env = {
+  cfg,
+  cacheDir: () => projCacheDir(),
+  resolveWs: () => cfg.workspaceRoot,
+  selfId: () => (selfId || null),
+  selfCwd: () => null,
+  selfPct(id) {
+    if (!id) return null;
+    const target = id.indexOf('session-') === 0 ? id : 'session-' + id;
+    for (const f of readJsonDir(projCacheDir())) {
+      const stem = f.name.replace('.json', '');
+      if (stem === target || stem === id) return pressurePct(f.data);
+    }
+    return null;
+  },
+  compactionCount: () => ({ used: null, note: '（批 B 接入事件计数）' }),
+  lockState: () => 'unknown',
+};
+
+const exec = null;
+const cases = [
+  { t: pmBriefTool(env), a: {}, flag: "brief" },
+  { t: pmGateTool(env), a: { scope: "all" }, flag: "gate" },
+  { t: pmSessionsTool(env), a: {}, flag: "sessions" },
+  { t: pmPhaseTool(env), a: {}, flag: "phase" },
+  { t: pmCharterTool(env), a: { doc: "charter", section: "8.1.1.4", maxLines: 30 }, flag: "charter" },
+];
+
+let failed = 0;
+for (const c of cases) {
+  if (only !== "all" && only !== c.flag) continue;
+  const bar = "==== ho_" + c.flag + " ====";
+  console.log(bar);
+  try {
+    const out = await c.t.execute(c.a, exec);
+    console.log(out.text);
+  } catch (e) {
+    failed++;
+    console.log("FAILED: " + (e && e.message ? e.message : String(e)));
+    if (e && e.stack) console.log(e.stack.split(String.fromCharCode(10)).slice(0, 4).join(String.fromCharCode(10)));
+  }
+  console.log("");
+}
+if (failed) {
+  console.log("自测失败 " + failed + " 项");
+  process.exitCode = 1;
+}

package/src/templates/Changelog.skeleton.md

@@ -0,0 +1,10 @@
+# Global Handover Changelog（全局交接变更日志）
+
+> 追加式历史日志。每次改动 _Control_Center 的全局规则、结构或 Global_Handover.md 本身时，追加一行。
+> 由插件 ho_changelog 按格式追加（新行插在最新一行之前）。
+
+## 变更记录
+
+| 日期 | 变更 | 执行者 |
+|---|---|---|
+| 2026-10-24 | 由 dsh-handover 首次安装向导生成工作区骨架 | setup |

package/src/templates/Charter.skeleton.md

@@ -0,0 +1,53 @@
+# Workspace Charter（骨架）
+
+> 本文件由 dsh-handover 首次安装向导生成，只含跑起来所需的最小内容；按需继续写。
+> 铁律：§8.1.1.4 那 24 行是唯一正文来源，任何项目库的 RULES.md 都要逐字复制它（外加一行「上下文水位自查」）。改这里就必须同步改所有库。
+
+## 8. 工程约束
+
+### 8.1.1.4 项目侧通用约束条（可直接粘贴；改这里就要重新同步所有项目）
+
+> 同步方式＝把下面代码块的内容逐行复制进 `Projects/<项目名>/<库名>/RULES.md`，再加一行「上下文水位自查」。
+
+```markdown
+**运行期省 token（通用约束；项目无关，全部在役项目共用这一份正文；数值按 27 个退役会话跨项目实测定）**
+
+运行期按**步数**花钱：实测成本 ≈ **步数 × 每步约 1.7k token**（四分位 1.3k–2.0k，最高 3.3k），
+与项目类型、会话角色无关。⇒ 唯一可伸缩的杠杆是**步数**。
+
+1. **单轮工具调用 ≤ 20 步**。实测正常轮的中位数只有 **7 步**；>20 步的轮占 15%，却是账单主体。
+   超了就停：先把「建一小段 → 跑一次 → 看一眼」固化成一条不变量，再继续。
+2. **同一动作在本会话第 3 次出现，就固化成 `_Scripts/` 下的命令**，之后只许调参调用、不许现场重写。
+   （实测：近似重复动作只占 1.8%，但出现过单个动作重复 11 次的实例 —— 这条是抓长尾。）
+3. **一条命令验多个假设**，不要一步一问。
+4. **脚本输出要「读一次就能决定下一步」**，不要打印全量清单。
+   （实测：平均每个会话有 12.6 条 >4 KB 的工具返回，最大 54 KB。它的代价不在被重复读 —— 339 条里
+   近似重复 0 条 —— 而在此后**每一步都要把它重读一遍**。）
+5. **任务开始用 `todo_write` 列出计划**，让用户看得见总步数与进度。
+6. **跨版本对比 / 一次性实验先隔离运行根**：把待跑的脚本与数据**整体复制到库根之外的独立副本**再跑
+   （系统临时目录即可）。判据＝**这个脚本的库根会解析到哪**；只要可能落到真库或归档目录，就先复制。
+7. **构建期可以铺张**（反复试错），不必为省 token 牺牲效率。
+8. **不可逆动作的最小充分核验**：不要求「重查一遍」，只要求动手前能回答四问 —— **目标**（动谁）、**范围**（动多少）、
+   **时效**（依据是否本会话内 / 无后续写入 / 无并发）、**逃生**（错了能否恢复）。四问都能从上下文回答 ⇒ 直接做，依据一句；
+   **缺哪项只补哪项**；**逃生＝不可恢复**才升级为全量清单 ＋ 备份 ＋ 试运行 ＋ 用户确认。
+   **本会话内用户亲口说的、或你自己刚跑出来的**信息**计入**核验，不得重复核验。判不准时先给拟做动作与依据、
+   指出缺口，再问是否补查 —— 不要用「我不猜，先检查」开场。
+9. **防步数失控三条（电脑侧 A/B 实测；第 1 条约束的补丁）**。实测：单轮 ≤20 步**两版都落到 33–36 步**，说明「超了就停」是事后话 ⇒ 改成事前拦：
+   ① **动手前写步数预算**（"这活我打算 ≤N 步"）；**实测热轮的两大块**＝读规则/长文（一次读完、别反复翻同义文件）＋同一动作重复（先固化再跑），先压这两块。
+   ② **同一命令在一处重复调用，就把「路径与参数」硬化** —— 输出路径**一律绝对路径**（实测反面：`--out` 用相对路径，4 张产物落进库根）；默认参数写成脚本常量，别每次重猜（实测反面：同一参数误用默认值，4 张返工）。
+   ③ **隔离胜过小心删** —— 长循环/批处理先落临时目录再做，事后无需清理（隔离运行根是第 6 条，这里补「默认就这么干」）；`job_output` 同一 job **轮询 ≤2 次**，等就等，不要反复看。
+   本条**不要求**改计步口径：探针取的是日志事实，你自数的「轮/步」跟它对不上时，**以日志为准**，也别为了好看改自己的计数。
+```
+
+## 9. 上下文水位自查
+
+每个项目库的 `RULES.md` 必须含一行「上下文水位自查」（说明该库会话在多少水位时写交接、多少时换任）。
+闸门（ho_gate）会逐库检查：标题行在、24 行正文一行不缺、水位自查在。缺任何一项，该库判红。
+
+## 10. 工作区约定
+
+- 全局交接：`_Control_Center/records/Global_Handover.md`（ho_handover 读写，写前自动备份）
+- 台账：`_Control_Center/records/Global_Changelog.md`（ho_changelog 按格式追加）
+- 会话提示词模板：`_Control_Center/templates/Prompt_Templates.md`（ho_sessions 的 action=prompt 渲染）
+- 项目库：`Projects/<项目名>/<库名>/`，每库一份 `RULES.md`；项目交接在 `_Project_Meta/<项目名>/Handover.md`
+- 杂项：`_Misc/tasks/<任务短名>/`；归档 `_Archives/`；临时与快照 `_Temp/`

package/src/templates/Handover.global.skeleton.md

@@ -0,0 +1,56 @@
+# 全局 交接文档
+
+> 本文件由 **dsh-handover 首次安装向导**生成。§7 里那行 session id 是**占位**——第一个全局会话接手时把它换成本机真实的 id。
+
+## 0. 身份与寻址
+
+| 项 | 值 |
+|---|---|
+| 会话类型 | 全局 |
+| 本任 | 待第一个全局会话接手 |
+| 链内代数 | 第 1 代（本机序号，接手时核对） |
+| 接任 | 无（首任） |
+| 上级、报告对象 | 用户 |
+| 本文件 | _Control_Center/records/Global_Handover.md |
+| 冲突以谁为准 | rules/Workspace_Charter.md |
+| 修订 | 首次安装向导生成 |
+
+## 1. 正在做的事
+
+| 项 | 现状 |
+|---|---|
+| 初始化 | 工作区骨架已生成；等第一个标题含「全局」的会话接手 |
+
+## 2. 下一步
+
+| # | 动作 | 落点 | 完成判据 |
+|---|---|---|---|
+| 1 | 全局会话接手：核闸门、把 §0 身份信息填实 | 本文件 §0 | ho_gate 三项全绿 |
+| 2 | 按需新建项目库 | Projects/ | 各库 RULES.md 24/24 ＋ 上下文水位自查 |
+
+## 3. 待用户决定
+
+（暂无）
+
+## 4. 用户要求逐条落位
+
+| # | 用户原话要点 | 状态 | 落在哪 |
+|---|---|---|---|
+| 1 | 安装插件并在指定目录建好全局根 | 已落地 | 本文件 |
+
+## 5. 坑点与禁区
+
+- 禁区：改 §8.1.1.4 那 24 行正文会让所有项目库对不上——要改就同步改全部库。
+
+## 6. 关键路径
+
+- 交接：_Control_Center/records/Global_Handover.md
+- 规则：_Control_Center/rules/Workspace_Charter.md
+- 台账：_Control_Center/records/Global_Changelog.md
+- 提示词模板：_Control_Center/templates/Prompt_Templates.md
+
+## 7. 会话 id 对照
+
+| 角色 | session id | 状态 |
+|---|---|---|
+| 全局 | session-00000000-0000-0000-0000-000000000000 | 占位：接手时换成本机真实的全局会话 id |