@mingmaple/dsh-handover 0.0.0-stage → 0.9.6

package/src/lib/handover-io.mjs

@@ -0,0 +1,49 @@
+/** 交接文档读写：原子写 + 写前备份 + 写后体检（判据复用 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 }; }
+}
+
+/**
+ * 写交接：先把旧文件复制到 <作用域>/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)，轮末自动压缩并续跑；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)。',
+    '与全局通信仅用 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);
+}