@mingmaple/dsh-handover 0.0.0-stage → 0.9.6

package/scripts/build.mjs

@@ -0,0 +1,58 @@
+/**
+ * 构建：把 src/ 打成一个可直接安装的 bundle 包（dist/）。
+ * 用法：node scripts/build.mjs [--out <目录>]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repo = path.resolve(here, "..");
+const rootPkg = JSON.parse(fs.readFileSync(path.join(repo, "package.json"), "utf8"));
+
+const argIdx = process.argv.indexOf("--out");
+const dist = argIdx !== -1 && process.argv[argIdx + 1]
+  ? path.resolve(process.argv[argIdx + 1])
+  : path.join(repo, "dist");
+
+function rmrf(p) { if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true }); }
+function copyDir(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const name of fs.readdirSync(from)) {
+    const s = path.join(from, name);
+    const d = path.join(to, name);
+    if (fs.statSync(s).isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+rmrf(dist);
+fs.mkdirSync(dist, { recursive: true });
+copyDir(path.join(repo, "src", "lib"), path.join(dist, "lib"));
+copyDir(path.join(repo, "src", "tools"), path.join(dist, "tools"));
+fs.copyFileSync(path.join(repo, "src", "index.mjs"), path.join(dist, "index.mjs"));
+fs.copyFileSync(path.join(repo, "src", "cordis.patch.yml"), path.join(dist, "cordis.patch.yml"));
+// 浏览器半（设置页）：必须是已构建好的 __ModuleLoader__ 注册脚本，宿主按 exports["./client"] 取用。
+fs.copyFileSync(path.join(repo, "src", "client.js"), path.join(dist, "client.js"));
+// 首次安装向导用的模板（Charter 骨架、交接骨架、台账骨架、提示词模板）。
+copyDir(path.join(repo, "src", "templates"), path.join(dist, "templates"));
+
+const distPkg = {
+  name: rootPkg.name,
+  version: rootPkg.version,
+  private: true,
+  type: "module",
+  description: rootPkg.description,
+  license: rootPkg.license,
+  exports: { ".": "./index.mjs", "./client": "./client.js" },
+  dsh: {
+    bundle: { patch: "./cordis.patch.yml" },
+    client: rootPkg.dsh && rootPkg.dsh.client ? rootPkg.dsh.client : { platform: "web" },
+  },
+};
+fs.writeFileSync(path.join(dist, "package.json"), JSON.stringify(distPkg, null, 2) + "\n");
+
+let files = 0;
+walk(dist);
+function walk(p) { for (const n of fs.readdirSync(p)) { const q = path.join(p, n); if (fs.statSync(q).isDirectory()) walk(q); else files++; } }
+console.log("built " + rootPkg.name + "@" + rootPkg.version + " -> " + dist + " (" + files + " files)");

package/scripts/check-docs.mjs

@@ -0,0 +1,74 @@
+/**
+ * 文档校验：工具名集合、旧数与旧术语、内部链接、版本、语体。
+ * 只读，不做任何改写。退出码 0 表示全部通过。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ALL_TOOL_NAMES } from '../src/lib/names.mjs';
+import { listFiles, scanFiles } from './lib/register.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+const readme = path.join(root, 'README.md');
+const files = [readme]
+  .concat(listFiles(path.join(root, 'docs'), ['.md']))
+  .filter((f) => fs.existsSync(f));
+const problems = [];
+
+// 1. README 长度（对外首页承载全部说明，上限放宽）
+const readmeLines = fs.readFileSync(readme, 'utf8').split(/\r?\n/).length;
+if (readmeLines > 200) problems.push('README 应不超过 200 行（当前 ' + readmeLines + ' 行）');
+
+// 2. 旧数与旧术语
+const FORBIDDEN = ['21 个工具', '27 个工具', '未分类', '追加系统提示词', '4,028', '4.6 KB', '每库 24 行', 'CHANGELOG'];
+for (const file of files) {
+  const text = fs.readFileSync(file, 'utf8');
+  for (const w of FORBIDDEN) {
+    if (text.indexOf(w) !== -1) problems.push(path.relative(root, file) + ' 仍含旧表述「' + w + '」');
+  }
+}
+
+// 3. 工具名：文档里出现的 ho_* 与 peer_* 必须在 names.mjs 中
+for (const file of files) {
+  const text = fs.readFileSync(file, 'utf8');
+  const hits = text.match(/\b(?:ho|peer)_[a-z_]+\b/g) || [];
+  for (const name of hits) {
+    if (ALL_TOOL_NAMES.indexOf(name) === -1) problems.push(path.relative(root, file) + ' 出现未定义工具名「' + name + '」');
+  }
+}
+
+// 4. 内部链接可达
+for (const file of files) {
+  const text = fs.readFileSync(file, 'utf8');
+  const re = /\[[^\]]*\]\(([^)\s]+)\)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const target = m[1];
+    if (/^(https?:|mailto:|#)/.test(target)) continue;
+    const clean = target.split('#')[0];
+    const abs = path.resolve(path.dirname(file), clean);
+    if (!fs.existsSync(abs)) problems.push(path.relative(root, file) + ' 的链接不可达「' + target + '」');
+  }
+}
+
+// 5. 版本：README 的「当前版本」与 package.json 一致
+const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+const readmeText = fs.readFileSync(readme, 'utf8');
+const ver = readmeText.match(/当前版本\s*([0-9]+\.[0-9]+\.[0-9]+)/);
+if (!ver) problems.push('README 缺少「当前版本 X.Y.Z」一行');
+else if (ver[1] !== pkg.version) problems.push('版本不一致：package.json 为 ' + pkg.version + '，README 为 ' + ver[1]);
+
+// 6. 语体
+const hits = scanFiles(files, { ui: false });
+for (const h of hits) {
+  problems.push(path.relative(root, h.file) + ':' + h.line + ' ' + h.rules.join('、'));
+}
+
+if (problems.length) {
+  console.log('CHECK-DOCS FAIL ' + problems.length + ' 项：');
+  for (const p of problems) console.log('  - ' + p);
+  process.exitCode = 1;
+} else {
+  console.log('CHECK-DOCS OK（' + files.length + ' 份文档，工具名 ' + ALL_TOOL_NAMES.length + ' 个）');
+}

package/scripts/e2e-migration.mjs

@@ -0,0 +1,127 @@
+/**
+ * 迁移与恢复的端到端自测（不碰真库）：造一个假工作区 → 打包 → 校验 → 改一个字节看失效 → 预演恢复 → 真恢复 → 再恢复一次看备份。
+ * 用法：node scripts/e2e-migration.mjs [--dist <dist 目录>]
+ * 依赖：7-Zip（自动探测 C:\\Program Files\\7-Zip\\7z.exe）。
+ * 全程在系统临时目录里做，结束即删。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repo = path.resolve(here, '..');
+const argIdx = process.argv.indexOf('--dist');
+const dist = argIdx !== -1 ? path.resolve(process.argv[argIdx + 1]) : path.join(repo, 'dist');
+
+const imp = (rel) => import(pathToFileURL(path.join(dist, rel)).href);
+const { pmPackTool } = await imp('tools/ho_pack.mjs');
+const { resolveConfig } = await imp('lib/config.mjs');
+
+const fails = [];
+const ok = (cond, msg, extra) => { if (!cond) fails.push(msg + (extra ? ' → ' + extra : '')); else console.log('  通过 ' + msg); };
+
+const SB = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-handover-e2e-'));
+const WS = path.join(SB, 'ws');
+const OUT = path.join(SB, 'out');
+const TGT = path.join(SB, 'target');
+const ABS_LINE = '缓存目录写死成了 ' + 'D:' + path.sep + 'Work' + path.sep + 'cache（迁移时须改）';
+
+function w(rel, text) {
+  const p = path.join(WS, rel.split('/').join(path.sep));
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, text, 'utf8');
+}
+
+w('_Control_Center/records/Global_Handover.md', '# 全局 交接\n\n## 0. 身份与寻址\n\n| 链内代数 | 第 1 代 |\n\n## 2. 下一步\n\n| # | 动作 |\n|---|---|\n| 1 | 试跑 |\n\n## 7. 会话 id 对照\n\n| 角色 | id |\n|---|---|\n| 全局 | session-00000000-0000-0000-0000-000000000000 |\n');
+w('_Project_Meta/Demo/Handover.md', '# Demo 交接\n\n## 1. 正在做的事\n\n这是一个用于端到端自测的假项目库，内容足够长以满足体检的最短要求。\n\n## 2. 下一步待办\n\n- 改绝对路径\n');
+w('_Control_Center/rules/Note.md', '# 备注\n\n' + ABS_LINE + '\n');
+w('_Control_Center/rules/clean.md', '# 干净的相对引用\n\n见 ../records/Global_Handover.md\n');
+
+const cfg = resolveConfig({ workspaceRoot: WS });
+const env = {
+  cfg,
+  resolveWs: () => WS,
+  log: () => { },
+  cacheDir: () => path.join(SB, 'nocache'),   // 沙箱里没有投影缓存 ⇒ check 只看交接
+  selfId: () => null,
+  selfCwd: () => null,
+};
+const packTool = pmPackTool(env);
+/** action 分流：pack／verify／restore 都走同一个工具（合并口径）。 */
+const run = (args) => packTool.execute(args, null);
+
+console.log('（沙箱）' + SB);
+
+// 0. 前置闸门：action=check
+const r0 = await run({ action: 'check', items: ['global', 'Demo'], min_age_min: 0 });
+ok(/判定：/.test(r0.text), 'action=check 应给出判定', r0.text.split('\n').pop());
+
+// 1. 打包
+const r1 = await run({ action: 'pack', kind: 'global', out: OUT, note: 'e2e' });
+ok(/已打包/.test(r1.text), '打包成功');
+ok(/绝对路径体检：\d+ 处/.test(r1.text), '打包输出报出绝对路径处数', r1.text.split('\n').pop());
+const packs = fs.readdirSync(OUT).filter((n) => n.endsWith('.7z'));
+ok(packs.length === 1, '只出一个包', packs.join(','));
+const packPath = path.join(OUT, packs[0]);
+
+// 2. 包内清单与说明
+const x1 = path.join(SB, 'x1');
+fs.mkdirSync(x1, { recursive: true });
+const { execFileSync } = await import('node:child_process');
+const sevenZip = ['C:/Program Files/7-Zip/7z.exe', 'C:/Program Files (x86)/7-Zip/7z.exe'].find((p) => fs.existsSync(p));
+if (!sevenZip) { console.log('SKIP：本机没有 7-Zip，跳过解包核对'); }
+else {
+  execFileSync(sevenZip, ['x', '-y', '-o' + x1, packPath], { stdio: 'ignore' });
+  const mf = JSON.parse(fs.readFileSync(path.join(x1, 'manifest.json'), 'utf8'));
+  ok(mf.absoluteRefs && mf.absoluteRefs.totalHits >= 1, 'manifest 记录了绝对路径命中', JSON.stringify(mf.absoluteRefs && { totalHits: mf.absoluteRefs.totalHits, files: mf.absoluteRefs.files }));
+  ok(typeof mf.sourcePlatform === 'string' && /\+\d{4}$/.test(mf.createdAtLocal || ''), 'manifest 带源平台与带偏移的时间');
+  const md = fs.readFileSync(path.join(x1, 'MIGRATION.md'), 'utf8');
+  ok(md.indexOf('绝对路径体检') !== -1, 'MIGRATION.md 有「绝对路径体检」段');
+  ok(md.indexOf('跨平台注意') !== -1, 'MIGRATION.md 有「跨平台注意」段');
+  ok(md.indexOf('库内引用一律相对路径') !== -1, 'MIGRATION.md 写明相对路径口径');
+}
+
+// 3. 校验通过
+const r2 = await run({ action: 'verify', pack: packPath });
+ok(/漂移 0/.test(r2.text) && /缺失 0/.test(r2.text), 'pack_verify 判定与盘上一致（漂移 0 / 缺失 0）', r2.text.split('\n')[1]);
+
+// 4. 改盘上文件 → 校验应报不一致
+w('_Control_Center/rules/Note.md', '# 备注\n\n改过了\n');
+const r3 = await run({ action: 'verify', pack: packPath });
+ok(/不一致|缺失|作废/.test(r3.text), '盘上改了之后 verify 报出不一致', r3.text.split('\n').slice(0, 2).join(' / '));
+
+// 5. 预演恢复：不写任何文件
+const r4 = await run({ action: 'restore', pack: packPath, target: TGT });
+ok(/预演/.test(r4.text), '默认只预演');
+const tgtExists = fs.existsSync(TGT);
+ok(tgtExists === false, '预演没有创建目标目录', String(tgtExists));
+ok(/绝对路径体检（恢复前）/.test(r4.text), '恢复前复检已输出');
+
+// 6. 真恢复
+const r5 = await run({ action: 'restore', pack: packPath, target: TGT, apply: true });
+ok(/已写入/.test(r5.text), 'apply=true 写入成功');
+ok(fs.existsSync(path.join(TGT, '_Control_Center', 'records', 'Global_Handover.md')), '目标目录出现交接文件');
+ok(fs.readFileSync(path.join(TGT, '_Control_Center', 'rules', 'Note.md'), 'utf8').indexOf('改过了') === -1, '写回的是包内版本（不是盘上被改过的版本）');
+
+// 7. 再恢复一次 → 覆盖并备份
+const r6 = await run({ action: 'restore', pack: packPath, target: TGT, apply: true });
+ok(/覆盖/.test(r6.text), '第二次恢复报出覆盖');
+const snap = path.join(WS, '_Temp', '_Global', 'Snapshots');
+const baks = fs.existsSync(snap) ? fs.readdirSync(snap) : [];
+ok(baks.length >= 1, '覆盖前备份目录已建立', baks.join(','));
+
+// 8. 不删除目标文件：放一个包外的文件，恢复后仍在
+const keep = path.join(TGT, 'keep.txt');
+fs.writeFileSync(keep, 'keep', 'utf8');
+await run({ action: 'restore', pack: packPath, target: TGT, apply: true });
+ok(fs.existsSync(keep), '恢复不删除目标处原有文件');
+
+fs.rmSync(SB, { recursive: true, force: true });
+console.log('');
+if (fails.length) {
+  console.log('E2E FAIL ' + fails.length + ' 项：');
+  for (const f of fails) console.log('  - ' + f);
+  process.exit(1);
+}
+console.log('E2E OK（迁移与恢复端到端全过）');

package/scripts/lib/register.mjs

@@ -0,0 +1,103 @@
+/**
+ * 用户可见文案的语体扫描：词表、符号与时间格式。
+ * 词表只收「脱离上下文即不可解」与「书面语中不出现」两类；新增豁免须在注释里写明理由。
+ * 抽取器只取含中文的字符串字面量（跳过注释行），因此工具 description 与错误消息同样覆盖。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 命中即违规：口语、俚语、生造缩略。 */
+const BAD_WORDS = [
+  '搞定', '弄好', '弄成', '取不到', '装好', '重启过', '接上', '没找到',
+  '拍板', '干活', '收工', '开工', '顺手', '回头', '一眼', '一趟',
+  '跑一遍', '走一遍', '接着干', '咱们', '咋', '啥', '差不多', '算了',
+  '懒得', '省得', '别忘', '别再', '点单', '找活', '白花',
+  '整理并设', '改址', '体量', '忙闲', '抠', '跑一轮',
+];
+
+/** 符号与格式类规则；source 用于定位，test 返回是否命中。 */
+const SYMBOL_RULES = [
+  { id: '感叹号', test: (s) => /[!！]/.test(s) },
+  { id: '图形结论符号', test: (s) => /[✅❌⚠✗]/.test(s) },
+  { id: '全角斜杠', test: (s) => s.indexOf('／') !== -1 },
+  { id: '半角箭头', test: (s) => s.indexOf('->') !== -1 || s.indexOf('=>') !== -1 },
+  { id: '中文中的半角括号', test: (s) => /[\u4e00-\u9fff][(]/.test(s) },
+];
+
+/** 只对界面文件生效的规则：箭头连接句子。 */
+const UI_RULES = [
+  { id: '箭头连接句子', test: (s) => /[→←]/.test(s) },
+];
+
+/** 时间缺时区：2026-11-07 18:50 这类写法。 */
+const TIME_RULE = { id: '时间缺时区', test: (s) => /\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}(?!\s*[+-]\d{4})/.test(s) };
+
+const CJK = /[\u3400-\u9fff]/;
+
+/** 从源码或文档里抽用户可见的中文字符串。返回 [{ line, text }]。 */
+function extractStrings(file) {
+  const src = fs.readFileSync(file, 'utf8');
+  const out = [];
+  const ext = path.extname(file).toLowerCase();
+  if (ext === '.md') {
+    let fence = false;
+    src.split(/\r?\n/).forEach((line, i) => {
+      const t = line.trim();
+      if (t.startsWith('```')) { fence = !fence; return; }
+      if (fence || !CJK.test(t)) return;
+      out.push({ line: i + 1, text: t });
+    });
+    return out;
+  }
+  let offset = 0;
+  src.split(/\r?\n/).forEach((line, i) => {
+    const t = line.trim();
+    offset = i + 1;
+    if (t.startsWith('//') || t.startsWith('*') || t.startsWith('/*') || t.indexOf('语体豁免') !== -1) return;
+    // 单双引号与反引号里的单行字符串；转义引号不参与抽取。
+    const re = /'([^'\\]|\\.)*'|"([^"\\]|\\.)*"|`([^`\\]|\\.)*`/g;
+    let m;
+    while ((m = re.exec(line)) !== null) {
+      const lit = m[0];
+      if (!CJK.test(lit) && !/[✅❌⚠✗]/.test(lit)) continue;
+      out.push({ line: offset, text: lit });
+    }
+  });
+  return out;
+}
+
+/** 扫描一组文件：{ file, line, text, rules }。 */
+export function scanFiles(files, opts) {
+  const o = opts || {};
+  const rules = SYMBOL_RULES.concat(o.ui ? UI_RULES : []).concat([TIME_RULE]);
+  const hits = [];
+  for (const file of files) {
+    const strings = extractStrings(file);
+    for (const s of strings) {
+      const found = [];
+      for (const w of BAD_WORDS) if (s.text.indexOf(w) !== -1) found.push('口语词「' + w + '」');
+      for (const r of rules) if (r.test(s.text)) found.push(r.id);
+      if (found.length) hits.push({ file, line: s.line, text: s.text, rules: found });
+    }
+  }
+  return hits;
+}
+
+/** 列出目录下的指定扩展名文件。 */
+export function listFiles(dir, exts, opts) {
+  const out = [];
+  const stack = [dir];
+  const skip = (opts && opts.skip) || [];
+  while (stack.length) {
+    const cur = stack.pop();
+    for (const name of fs.readdirSync(cur)) {
+      const p = path.join(cur, name);
+      const st = fs.statSync(p);
+      if (st.isDirectory()) {
+        if (skip.some((s) => p.indexOf(s) !== -1)) continue;
+        stack.push(p);
+      } else if (exts.indexOf(path.extname(name).toLowerCase()) !== -1) out.push(p);
+    }
+  }
+  return out.sort();
+}