dsh-compact-relay 0.5.1 → 0.5.3

package/lib/config.js

@@ -14,6 +14,7 @@ import {
   validateConfig,
 } from './core/config-schema.js';
 import { isPlainObject } from './core/object.js';
+import { normalizeFavoriteWords } from './core/favorite-score.js';
 
 // 兼容旧导入：其它模块/文档仍可从 config.js 拿默认配置与路径工具。
 export { CONFIG_FIELDS, DEFAULT_CONFIG, defaultDshHome, expandHome } from './core/config-schema.js';
@@ -136,6 +137,13 @@ export function resolveConfig(raw = {}) {
         ? expandHome(input.handoffDir)
         : DEFAULT_CONFIG.handoffDir,
     ),
+    // 0.5.3 P1-6：推荐收藏配置（词表规范化：去空白/去重/截长/限量）。
+    favorite: {
+      enabled: input.favorite?.enabled ?? DEFAULT_CONFIG.favorite.enabled,
+      level: input.favorite?.level ?? DEFAULT_CONFIG.favorite.level,
+      mustWords: normalizeFavoriteWords(input.favorite?.mustWords ?? DEFAULT_CONFIG.favorite.mustWords),
+      muteWords: normalizeFavoriteWords(input.favorite?.muteWords ?? DEFAULT_CONFIG.favorite.muteWords),
+    },
     colors: normalizeColors(colors),
     links: {
       tutorial: input.links?.tutorial ?? DEFAULT_CONFIG.links.tutorial,

package/lib/core/config-schema.js

@@ -62,8 +62,8 @@ export const CONFIG_FIELDS = Object.freeze([
   field(['thresholds', 'maxSummaries'], { label: '摘要份数上限', kind: 'positiveInt', default: 6, editable: true, view: true }),
   field(['contextWindowFallback'], { label: '兜底窗口', kind: 'positiveInt', default: 1_000_000 }),
   field(['retention', 'recentTailTokens'], { label: '保留近期原文', kind: 'nonNegativeInt', default: 40_000, editable: true, view: true }),
-  field(['summary', 'maxTokens'], { label: '摘要输出上限', kind: 'positiveInt', default: 8_192 }),
-  field(['handoff', 'maxTokens'], { label: '交接单输出上限', kind: 'positiveInt', default: 8_192 }),
+  field(['summary', 'maxTokens'], { label: '摘要输出上限', kind: 'positiveInt', default: 16_384 }),
+  field(['handoff', 'maxTokens'], { label: '交接单输出上限', kind: 'positiveInt', default: 16_384 }),
   field(['timeouts', 'llmMs'], { label: '模型调用超时', kind: 'positiveInt', default: 180_000 }),
   field(['dev', 'testRangeNodes'], { label: '测试取段条数', kind: 'positiveInt', default: 4 }),
   field(['handoffDir'], {
@@ -80,6 +80,20 @@ export const CONFIG_FIELDS = Object.freeze([
   field(['colors', 'base', 'pin'], { label: '锁定颜色', kind: 'color', default: '#C026D3', editable: true, view: true }),
   field(['colors', 'base', 'compact'], { label: '调整颜色', kind: 'color', default: '#C26A00', editable: true, view: true }),
   field(['colors', 'base', 'handoff'], { label: '上限颜色', kind: 'color', default: '#D92D20', editable: true, view: true }),
+  // 0.6：收藏星标点亮色（设计稿到位后改配置值即可，不改代码）。
+  field(['colors', 'base', 'favorite'], { label: '收藏颜色', kind: 'color', default: '#F5C542', editable: true, view: true }),
+  // 0.5.3 P1-6：推荐收藏（模型打分 → 星标「点亮」建议，绝不自动收藏）。
+  field(['favorite', 'enabled'], { label: '推荐收藏', kind: 'boolean', default: true, editable: true, view: true }),
+  field(['favorite', 'level'], {
+    label: '推荐档位',
+    kind: 'enum',
+    values: ['loose', 'standard', 'strict'],
+    default: 'standard',
+    editable: true,
+    view: true,
+  }),
+  field(['favorite', 'mustWords'], { label: '必亮词', kind: 'words', default: [], editable: true, view: true }),
+  field(['favorite', 'muteWords'], { label: '屏蔽词', kind: 'words', default: [], editable: true, view: true }),
   // 0.3.1：仓库已建（cfanzx/dsh-compact-relay），默认指向仓库内的教程与 Issues；
   // 用户仍可在设置文件里覆盖 links.tutorial / links.feedback。
   field(['links', 'tutorial'], { label: '使用教程链接', kind: 'urlOrEmpty', default: 'https://github.com/cfanzx/dsh-compact-relay/blob/main/TUTORIAL.md', view: true }),
@@ -229,6 +243,15 @@ export function validateFieldValue(item, value) {
       return typeof value === 'string' && value.trim().length > 0 ? null : '不能为空，必须是颜色值（如 #6F7680）';
     case 'path':
       return typeof value === 'string' && value.length > 0 ? null : '不能为空';
+    case 'words':
+      if (!Array.isArray(value)) return '必须是字符串数组（例如 ["结论","定案"]）';
+      if (value.length > 20) return '最多 20 个词';
+      for (const word of value) {
+        if (typeof word !== 'string') return '每个词都必须是字符串';
+        if ([...word.trim()].length === 0) return '不能有空词';
+        if ([...word.trim()].length > 12) return `单词最长 12 个字（${word.slice(0, 12)}…）`;
+      }
+      return null;
     case 'urlOrEmpty':
       if (typeof value !== 'string') return '必须是字符串';
       if (value.length > 0 && !/^https?:\/\//i.test(value)) return '必须是 http(s) 链接，或留空';

package/lib/core/errors.js

@@ -21,15 +21,21 @@ const MESSAGES = Object.freeze({
 });
 
 /**
- * 给一次动作失败打上稳定的 code。
+ * 给一次动作失败打上稳定的 code（可选 HTTP 状态码）。
+ *
+ * 0.5.3 P2-2：错误码不再一律 400 —— 未知会话 404、宿主缺接缝 503、内部错 500
+ * 由动作层显式标注（`statusCode`），adapters/http 只做映射，不重猜。
+ *
  * @param {string} code
  * @param {string} message
  * @param {unknown} [cause]
- * @returns {Error & {code: string}}
+ * @param {number} [statusCode] 建议的 HTTP 状态码（缺省由入口按 400/500 兜底）
+ * @returns {Error & {code: string, statusCode?: number}}
  */
-export function actionError(code, message, cause) {
+export function actionError(code, message, cause, statusCode) {
   const error = new Error(message, cause === undefined ? undefined : { cause });
   error.code = code;
+  if (Number.isInteger(statusCode)) error.statusCode = statusCode;
   return error;
 }
 

package/lib/core/favorite-score.js

@@ -0,0 +1,220 @@
+/**
+ * 推荐收藏 · 打分与判定（纯函数层）—— 2026-10-28 定稿。
+ *
+ * 位置：`AI 回复落地 → 异步问模型「这条值不值得收藏原文」→ 判定 → 客户端星标高亮`。
+ * 这里只做**不碰 IO 的那一半**：提示词、解析、档位阈值、筛选词过滤、最终判定。
+ * 模型调用在 `dsh/favorite-scorer.js`，事件钩子在 `dsh/favorite-watch.js`。
+ *
+ * 红线（定稿 §6）：推荐只决定「亮不亮」，绝不自动写收藏；真正的收藏仍由用户点星触发。
+ *
+ * 档位（实测数据见 `dcr-收藏-推荐收藏-验证-2026-10-28.md`）：
+ *   宽松 ≥60：每 3 条回复亮 1 次，准确率 71%
+ *   标准 ≥75：每 4 条亮 1 次，准确率 76%（默认）
+ *   严格 ≥85：每 7 条亮 1 次，准确率 89%
+ *
+ * 筛选词（定稿 §3）：
+ *   必亮词：出现就亮（跳过分数）；屏蔽词：出现就绝不亮；优先级 屏蔽 > 必亮 > 分数。
+ *   只做大小写无关的**子串包含**，不引正则——用户写不坏、可试算、可预期。
+ *
+ * 判定顺序：屏蔽词 → 必亮词 → 档位阈值。模型失败（score===null）→ 不亮（fail closed）。
+ */
+
+/** 三档阈值（分数 0-100）。 */
+export const FAVORITE_SCORE_LEVELS = Object.freeze({ loose: 60, standard: 75, strict: 85 });
+
+/** 默认档位（2026-10-28 小潇拍板）。 */
+export const FAVORITE_SCORE_DEFAULT_LEVEL = 'standard';
+
+/** 合法档位名。 */
+const LEVELS = Object.freeze(['loose', 'standard', 'strict']);
+
+/** 必亮词 / 屏蔽词各自上限。 */
+export const FAVORITE_WORDS_MAX = 20;
+
+/** 单个词最长字符数。 */
+export const FAVORITE_WORD_MAX_CHARS = 12;
+
+/** 单条消息送给模型的最大字符数（超长截断，末尾加省略号）。 */
+export const FAVORITE_SCORE_INPUT_MAX_CHARS = 3500;
+
+/** 短于这个长度的消息不参与推荐（没有可收藏的原文价值）。 */
+export const FAVORITE_SCORE_MIN_CHARS = 12;
+
+/** 解析失败/模型不可用时的占位分数（null 表示「不知道」，判定为不亮）。 */
+export const FAVORITE_SCORE_UNKNOWN = null;
+
+/**
+ * 档位 → 阈值；非法档位回落默认档。
+ * @param {string} [level]
+ * @returns {number}
+ */
+export function favoriteScoreThresholdOf(level) {
+  if (typeof level === 'string' && Object.hasOwn(FAVORITE_SCORE_LEVELS, level)) {
+    return FAVORITE_SCORE_LEVELS[level];
+  }
+  return FAVORITE_SCORE_LEVELS[FAVORITE_SCORE_DEFAULT_LEVEL];
+}
+
+/**
+ * 规范化档位名；非法值回落默认档。
+ * @param {unknown} level
+ * @returns {'loose'|'standard'|'strict'}
+ */
+export function normalizeFavoriteLevel(level) {
+  return typeof level === 'string' && LEVELS.includes(level) ? level : FAVORITE_SCORE_DEFAULT_LEVEL;
+}
+
+/**
+ * 规范化一组筛选词：去空白、去重（按小写比较）、截长、限量。
+ * 空串/非字符串一律丢弃；词内空白保留原样（用户可能写「测试 全绿」）。
+ * @param {unknown} words
+ * @returns {string[]}
+ */
+export function normalizeFavoriteWords(words) {
+  if (!Array.isArray(words)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const raw of words) {
+    if (typeof raw !== 'string') continue;
+    const word = raw.trim();
+    if (word.length === 0) continue;
+    const clipped = [...word].slice(0, FAVORITE_WORD_MAX_CHARS).join('');
+    const key = clipped.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(clipped);
+    if (out.length >= FAVORITE_WORDS_MAX) break;
+  }
+  return out;
+}
+
+/**
+ * 在文本里找第一个命中的词（大小写无关的子串匹配）。
+ * @param {string} text
+ * @param {string[]} words 规范化后的词表
+ * @returns {string|null} 命中的词；没命中返回 null
+ */
+export function matchFavoriteWord(text, words) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  if (!Array.isArray(words) || words.length === 0) return null;
+  const haystack = text.toLowerCase();
+  for (const word of words) {
+    if (typeof word !== 'string' || word.length === 0) continue;
+    if (haystack.includes(word.toLowerCase())) return word;
+  }
+  return null;
+}
+
+/**
+ * 送模型的系统提示词（与验证脚本 v3 逐字一致，唯一差别是要求 0-100 分）。
+ * 改这里等于改口径——`test/favorite-suggest.mjs` 锁了几个关键句，别顺手删。
+ * @returns {string}
+ */
+export function buildFavoriteScoreSystemPrompt() {
+  return (
+    '你帮用户判断：AI 的一条回复，值不值得『收藏原文』（以后可能想回看这条的原话）。\n\n' +
+    '判断标准（三类算）：\n' +
+    '- 结论：能/不能、可行/不可行、该做/不该做、问题在哪、定案；\n' +
+    '- 判断：方案取舍与理由、原因分析、优先级、对错判断、建议；\n' +
+    '- 纠偏：承认之前判断错了、指出根因、给出改进方向或下次注意。\n\n' +
+    '不算：主体是报进度（做完了/改完了/测试全绿/真机验证通过/发版了）、列清单（改了哪些文件/有哪些发现）、操作步骤、提问、寒暄、确认收到。\n\n' +
+    '给这条消息打一个 0-100 的分：\n' +
+    '90-100：就是一条关键结论/判断/纠偏，用户以后大概率想回看原话；\n' +
+    '70-89：有明确判断，但也掺了流水账，可收可不收；\n' +
+    '40-69：有点结论的味道，但主体不是判断；\n' +
+    '0-39：进度汇报/清单/步骤/寒暄，不该收。\n' +
+    '只回 JSON：{"score":0到100的整数,"reason":"不超过15字"}'
+  );
+}
+
+/**
+ * 裁到送模型的最大长度（按字符，不切坏 emoji）。
+ * @param {string} text
+ * @returns {string}
+ */
+export function clipForScore(text) {
+  if (typeof text !== 'string') return '';
+  const chars = [...text];
+  if (chars.length <= FAVORITE_SCORE_INPUT_MAX_CHARS) return text;
+  return `${chars.slice(0, FAVORITE_SCORE_INPUT_MAX_CHARS).join('')}…`;
+}
+
+/**
+ * 送模型的用户消息文本。
+ * @param {string} text
+ * @returns {string}
+ */
+export function buildFavoriteScoreUserText(text) {
+  return `消息原文：\n${clipForScore(text)}`;
+}
+
+/**
+ * 解析模型输出：剥 ```json 围栏、取第一个 JSON 对象、clamp 到 0-100。
+ * 解析不出来返回 null（调用方按「不亮」处理，不抛错）。
+ * @param {unknown} content
+ * @returns {{score:number, reason:string}|null}
+ */
+export function parseFavoriteScore(content) {
+  if (typeof content !== 'string') return null;
+  let text = content.trim();
+  if (text.startsWith('```')) {
+    text = text.replace(/^```[a-zA-Z]*\s*/u, '').replace(/```\s*$/u, '');
+  }
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== 'object') return null;
+  const rawScore = parsed.score;
+  const score = typeof rawScore === 'number' ? rawScore : Number.NaN;
+  if (!Number.isFinite(score)) return null;
+  const clamped = Math.max(0, Math.min(100, Math.round(score)));
+  const reason = typeof parsed.reason === 'string' ? parsed.reason.trim().slice(0, 40) : '';
+  return { score: clamped, reason };
+}
+
+/**
+ * 最终判定：这条 AI 回复要不要点亮收藏星标。
+ *
+ * @param {{ text?:string, score?:number|null, level?:string, mustWords?:unknown, muteWords?:unknown }} input
+ * @returns {{ suggest:boolean, score:number|null, reason:'mute-word'|'must-word'|'threshold'|'too-short'|'unknown-score', matched:string|null }}
+ */
+export function decideFavoriteSuggest({ text, score, level, mustWords, muteWords } = {}) {
+  const body = typeof text === 'string' ? text : '';
+  const words = {
+    must: normalizeFavoriteWords(mustWords),
+    mute: normalizeFavoriteWords(muteWords),
+  };
+  const unknown = { suggest: false, score: FAVORITE_SCORE_UNKNOWN, matched: null };
+
+  if ([...body.trim()].length < FAVORITE_SCORE_MIN_CHARS) {
+    return { ...unknown, reason: 'too-short' };
+  }
+
+  // 屏蔽词优先：命中就绝不亮（即使模型给高分）。
+  const muted = matchFavoriteWord(body, words.mute);
+  if (muted !== null) return { ...unknown, matched: muted, reason: 'mute-word' };
+
+  // 必亮词：出现就亮，跳过模型分数（模型失败也亮）。
+  const must = matchFavoriteWord(body, words.must);
+  if (must !== null) {
+    const knownScore = typeof score === 'number' && Number.isFinite(score) ? Math.round(score) : null;
+    return { suggest: true, score: knownScore, matched: must, reason: 'must-word' };
+  }
+
+  if (typeof score !== 'number' || !Number.isFinite(score)) {
+    return { ...unknown, reason: 'unknown-score' };
+  }
+  const threshold = favoriteScoreThresholdOf(level);
+  return {
+    suggest: score >= threshold,
+    score: Math.round(score),
+    matched: null,
+    reason: 'threshold',
+  };
+}

package/lib/core/favorites.js

@@ -0,0 +1,167 @@
+/**
+ * 收藏（favorite）—— 纯数据层：记录校验、集合计算、标题截取、摘要目录生成。
+ *
+ * 零 IO、零依赖（只复用 pin-anchors 的消息摘要），可裸跑单测。
+ * 记录存储走 dsh/favorites-file.js 的「一项工作一个文件」JSONL：追加式 add/remove，不写快照。
+ */
+
+import { messageSnippetOf } from './pin-anchors.js';
+
+/** 单条记录 schema 版本。 */
+export const FAVORITE_SCHEMA = 'dcr-favorite/v1';
+
+/** 单项目收藏上限（定稿：够用）。 */
+export const FAVORITE_MAX = 500;
+
+/** 摘要目录最多列几条（超了截断，不让摘要膨胀）。 */
+export const DIRECTORY_MAX = 20;
+
+const isSeq = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0;
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/**
+ * 读侧容错：形状不对 → null（调用方跳过该行，永不抛）。
+ * @param {unknown} raw
+ * @returns {{schema:string,op:'add'|'remove',sessionId:string,seq:number,at:number|null}|null}
+ */
+export function normalizeFavoriteRecord(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (raw.schema !== FAVORITE_SCHEMA) return null;
+  if (raw.op !== 'add' && raw.op !== 'remove') return null;
+  if (!isSeq(raw.seq)) return null;
+  const sessionId = nonEmpty(raw.sessionId);
+  if (sessionId === null) return null;
+  return {
+    schema: FAVORITE_SCHEMA,
+    op: raw.op,
+    sessionId,
+    seq: raw.seq,
+    at: typeof raw.at === 'number' && Number.isFinite(raw.at) ? raw.at : null,
+  };
+}
+
+/**
+ * JSONL 文本 → 记录数组（坏行跳过）。
+ * @param {string} text
+ * @returns {object[]}
+ */
+export function parseFavoriteLines(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue; // 半截写/手改 → 跳过
+    }
+    const record = normalizeFavoriteRecord(parsed);
+    if (record !== null) records.push(record);
+  }
+  return records;
+}
+
+/**
+ * 记录数组 → Map<sessionId, Set<seq>>（按时间顺序应用 add/remove）。
+ * @param {object[]} records
+ * @returns {Map<string, Set<number>>}
+ */
+export function applyFavoriteOps(records) {
+  const map = new Map();
+  if (!Array.isArray(records)) return map;
+  for (const record of records) {
+    const op = normalizeFavoriteRecord(record);
+    if (op === null) continue;
+    let set = map.get(op.sessionId);
+    if (set === undefined) {
+      set = new Set();
+      map.set(op.sessionId, set);
+    }
+    if (op.op === 'add') set.add(op.seq);
+    else set.delete(op.seq);
+  }
+  for (const [sessionId, set] of [...map]) {
+    if (set.size === 0) map.delete(sessionId);
+  }
+  return map;
+}
+
+/** 全部会话的收藏总数。 */
+export function countFavorites(map) {
+  let total = 0;
+  for (const set of map.values()) total += set.size;
+  return total;
+}
+
+/** 某会话的收藏 seq（升序数组）。 */
+export function favoriteSeqsOf(map, sessionId) {
+  const set = map instanceof Map && typeof sessionId === 'string' ? map.get(sessionId) : undefined;
+  return set === undefined ? [] : [...set].sort((a, b) => a - b);
+}
+
+/**
+ * 标题截取：40–60 字，不调模型。
+ * @param {object|undefined} event 消息事件
+ * @param {number} [max]
+ * @returns {string}
+ */
+export function buildFavoriteTitle(event, max = 60) {
+  const snippet = messageSnippetOf(event) || '';
+  const text = snippet.replace(/\s+/gu, ' ').trim();
+  if (text.length === 0) return '（无文本）';
+  return text.length > max ? `${text.slice(0, Math.max(1, max - 1))}…` : text;
+}
+
+/**
+ * 目录行（摘要与 /favorite list 共用）。
+ * @param {{index:number, role:string, title:string}[]} entries
+ * @param {number} [max]
+ * @returns {string[]}
+ */
+export function buildFavoriteDirectoryLines(entries, max = DIRECTORY_MAX) {
+  const list = Array.isArray(entries) ? entries.filter((entry) => entry !== null && typeof entry === 'object') : [];
+  const shown = list.slice(0, Math.max(1, max));
+  const lines = shown.map((entry) => `- 收藏 ${entry.index} · [${entry.role}] ${entry.title}`);
+  if (list.length > shown.length) lines.push(`- …等 ${list.length} 条，用 /favorite list 查看`);
+  return lines;
+}
+
+/**
+ * 把「收藏目录」作为独立文本块追加在摘要之后；没有目录原样返回。
+ * @param {{type:string,text:string}[]} summary
+ * @param {string[]} lines buildFavoriteDirectoryLines 的产物
+ * @returns {{type:string,text:string}[]}
+ */
+export function appendFavoriteDirectory(summary, lines) {
+  const blocks = Array.isArray(summary)
+    ? summary.filter((block) => block !== null && typeof block === 'object' && block.type === 'text')
+    : [];
+  if (!Array.isArray(lines) || lines.length === 0) return blocks;
+  const text = ['## 收藏（本段）', ...lines, '', '（以上原文未进摘要，按序号可查：/favorite <序号>）'].join('\n');
+  return [...blocks, { type: 'text', text }];
+}
+
+/**
+ * 推荐收藏（半自动）—— **接口占位，实现待接**。
+ *
+ * 定位：系统识别「值得留」的消息并**建议**，必须由用户点星/命令确认，绝不自动收藏。
+ * 预期实现：复用 lib/core/pin-suggest.js 的识别规则（关键决策 / 报错堆栈 / 明确要求别改），
+ * 把输出从「建议锁定」改成「建议收藏」。
+ *
+ * 约定（调用方已按此消费，改实现不用改调用方）：
+ * @param {{seq:number,type:string}[]} events 候选事件（通常是当前会话 surface 内消息）
+ * @param {{limit?:number}} [options]
+ * @returns {{seq:number,role:string,title:string,reason:string,confidence:'high'|'medium'|'low'}[]}
+ */
+export function suggestFavorites(events, { limit = 3 } = {}) {
+  if (!Array.isArray(events) || events.length === 0) return [];
+  const cap = Number.isInteger(limit) && limit > 0 ? limit : 3;
+  // 实现留白：接 pin-suggest 规则后在这里返回建议；
+  // 现在返回空数组 = 「没有推荐」，命令会明确提示「推荐收藏尚未接入」。
+  return events.slice(0, 0).slice(0, cap);
+}

package/lib/core/relay-record.js

@@ -0,0 +1,131 @@
+/**
+ * 接力链 record 的**唯一构造点**（0.5.2 S2）。
+ *
+ * 为什么要有这个模块：0.5.1 之前父记录在 `actions/handoff.js` 手写 13–14 个键、
+ * 子记录在 `dsh/sessions.js` 手写 9–10 个键 —— 两个写点各拼一份，加字段要改两处，
+ * 漏一处就是静默降级（读侧 `normalizeRelayRecord` 对缺失/非法字段一律当没有）。
+ * 现在「一条 record 长什么样」只有这一处实现，两个写点只负责传语义参数。
+ *
+ * ⚠️ **这是 record 的字节契约，不是普通的对象字面量，不许「统一美化」**：
+ *   1. 键的**插入顺序**就是 `JSON.stringify` 的顺序（会话日志是 JSONL）。父/子两套
+ *      顺序**故意不同**，都必须逐字节保留 —— `test/contract-golden.mjs` 锁住了顺序；
+ *   2. 父记录多写 0.3 旧字段 `parentSessionId` / `index`（canonical 是 `parentId` /
+ *      `ordinal`，新写入双写，旧记录仍按旧名可读）；
+ *   3. 父记录写 `planId`（可能为 **null**）；子记录**没有**这个键；
+ *   4. 父记录 `historyTitle` **条件写入**（改名没真的生效就不写这个键，不能记一个
+ *      不存在的标题）；子记录没有这个键；
+ *   5. 父/子 `path` 都是**条件写入**（`typeof path === 'string' && path.length > 0`）：
+ *      子记录在旧调用方/落盘失败时拿不到交接单，就不写键、不写空串；父记录的调用方
+ *      保证交接单已落盘（`path.join(handoffDir, handoffFileName(...))`，必然非空），
+ *      所以父记录实际总是带 path —— golden 里有断言；
+ *   6. 父/子都写 `titleSeq`，**即使为 null**（不是「省略 null」的统一策略：
+ *      0.4.x 记录没有这个键，0.5.0 起显式写 null 表示「拿不到宿主 eventSeq」）。
+ *
+ * 纯函数：不读文件/环境/时间，不 import 任何 `node:` 模块；`atIso` 由调用方按本地
+ * 时区口径算好传进来（core 不依赖 dsh 层），保证可在浏览器侧内联（build-client）。
+ */
+
+/** record 的两个角色（写点只有这两个：交接的父会话、新建的子会话）。 */
+export const RELAY_RECORD_ROLES = Object.freeze(['parent', 'child']);
+
+/**
+ * 按角色产出一条 relay record（唯一构造）。
+ *
+ * 两个角色共用的字段：`parentId` / `childId` / `ordinal` / `title` / `baseTitle` /
+ * `scheme` / `titleSeq` / `at` / `atIso`（`title` 是本次新会话标题）。
+ *
+ * @param {object} input
+ * @param {'parent'|'child'} input.role 父记录（旧会话日志）还是子记录（新会话日志）
+ * @param {string} input.parentId 父会话 id（写 `parentId`，parent 另写 `parentSessionId`）
+ * @param {string} input.childId 子会话 id
+ * @param {number} input.ordinal 链号（parent 另写 `index`）
+ * @param {string} input.title 本次新会话标题
+ * @param {string} input.baseTitle 链上原始标题（不带序号前缀）
+ * @param {'handoff-n'|'history-n'} input.scheme 本次链的命名方案
+ * @param {number|null} [input.titleSeq] 本次 rename 的宿主 eventSeq（拿不到就是 null）
+ * @param {string} [input.path] 交接单路径（非空字符串才写键）
+ * @param {string|null} [input.planId] 压缩计划 id（**仅 parent**；null 表示这次没压缩）
+ * @param {string} [input.historyTitle] 旧会话改名后的「历史 N」标题（**仅 parent**，且只在改名生效时传）
+ * @param {number} input.at 记录时间（epoch ms）
+ * @param {string} input.atIso 记录时间（本地 ISO，含时区偏移）
+ * @returns {object} 可直接交给 `engine.appendPluginRecord` 的 record
+ */
+export function relayRecordOfForm({
+  role,
+  parentId,
+  childId,
+  ordinal,
+  baseTitle,
+  title,
+  scheme,
+  titleSeq = null,
+  path,
+  planId,
+  historyTitle,
+  rootId,
+  at,
+  atIso,
+} = {}) {
+  if (role === 'parent') {
+    return {
+      parentId,
+      childId,
+      ordinal,
+      at,
+      atIso,
+      // 0.3 旧字段双写（旧记录只读兼容）；顺序与 0.5.1 手写写法逐字节一致。
+      parentSessionId: parentId,
+      index: ordinal,
+      ...(typeof path === 'string' && path.length > 0 ? { path } : {}),
+      planId: planId ?? null,
+      title,
+      baseTitle,
+      scheme,
+      titleSeq,
+      // 改名真的生效（renamed / already）时调用方才传 historyTitle；空串也当没有。
+      ...(typeof historyTitle === 'string' && historyTitle.length > 0 ? { historyTitle } : {}),
+      // 0.6：链根会话 id（收藏文件按链根定位）。
+      ...(typeof rootId === 'string' && rootId.length > 0 ? { rootId } : {}),
+    };
+  }
+  if (role === 'child') {
+    return {
+      parentId,
+      childId,
+      ordinal,
+      baseTitle,
+      title,
+      scheme,
+      titleSeq,
+      // 旧调用方/落盘失败拿不到交接单 → 不写这个键（不猜、不写空串）。
+      ...(typeof path === 'string' && path.length > 0 ? { path } : {}),
+      at,
+      atIso,
+    };
+  }
+  // 角色是代码常量，传错属于开发期错误（不是用户输入），直接抛。
+  throw new TypeError(`relayRecordOfForm: 未知 role「${String(role)}」（只认 ${RELAY_RECORD_ROLES.join(' / ')}）`);
+}
+
+/**
+ * 父记录（写在**旧会话**日志里；子会话建好、旧会话改名之后）。
+ *
+ * 多写 0.3 旧字段 `parentSessionId` / `index` 和 `planId`，可选 `historyTitle`。
+ * @param {Omit<Parameters<typeof relayRecordOfForm>[0], 'role'>} input
+ * @returns {object}
+ */
+export function parentRelayRecordOf(input = {}) {
+  return relayRecordOfForm({ ...input, role: 'parent' });
+}
+
+/**
+ * 子记录（写在**新会话**日志里；`followup` 之后、`flush` 之前）。
+ *
+ * 只写 canonical 字段 + `titleSeq` + 条件 `path`；不写 `parentSessionId` / `index` /
+ * `planId` / `historyTitle`（这些是父会话侧的旧字段/审计字段）。
+ * @param {Omit<Parameters<typeof relayRecordOfForm>[0], 'role'>} input
+ * @returns {object}
+ */
+export function childRelayRecordOf(input = {}) {
+  return relayRecordOfForm({ ...input, role: 'child' });
+}