dsh-compact-relay 0.5.2 → 0.5.4

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

@@ -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

@@ -62,6 +62,7 @@ export function relayRecordOfForm({
   path,
   planId,
   historyTitle,
+  rootId,
   at,
   atIso,
 } = {}) {
@@ -83,6 +84,8 @@ export function relayRecordOfForm({
       titleSeq,
       // 改名真的生效（renamed / already）时调用方才传 historyTitle；空串也当没有。
       ...(typeof historyTitle === 'string' && historyTitle.length > 0 ? { historyTitle } : {}),
+      // 0.6：链根会话 id（收藏文件按链根定位）。
+      ...(typeof rootId === 'string' && rootId.length > 0 ? { rootId } : {}),
     };
   }
   if (role === 'child') {

package/lib/dsh/favorite-scorer.js

@@ -0,0 +1,91 @@
+/**
+ * 推荐收藏 · 模型打分调用（0.5.3 P1-6）。
+ *
+ * 位置：`dsh/favorite-watch.js` 在助手消息落地后异步调这里，只判**最后一条**回复。
+ * 口径（2026-10-28 验证脚本 v3 定稿）：flash 档、关思考、temperature 0、只回 JSON 分数。
+ *
+ * 红线：这里只返回分数，**绝不写收藏**；失败一律返回 null（调用方按「不亮」处理，
+ * 不抛错、不重试——推荐只是锦上添花，不能因为模型抖动影响主流程）。
+ *
+ * 与摘要/交接的区别：那两个任务失败要让用户知道（有明确错误码）；推荐失败是静默降级，
+ * 所以不套 model-task 的重试/预算循环，只借 callStream 的超时与取消。
+ */
+import { buildFavoriteScoreSystemPrompt, buildFavoriteScoreUserText, parseFavoriteScore } from '../core/favorite-score.js';
+import { callStream } from './llm-call.js';
+import { routeOf } from './route.js';
+
+/** 打分输出极短，给 160 token 足够（提示词要求只回一个 JSON）。 */
+export const FAVORITE_SCORE_MAX_TOKENS = 160;
+
+/** 单条打分超时；超过就不亮（比主对话慢太多就失去「即时提示」的意义）。 */
+export const FAVORITE_SCORE_TIMEOUT_MS = 8_000;
+
+/**
+ * 从 BlockAssembler 里取纯文本（只拼 text block；忽略 reason/tool）。
+ * @param {object} assembler
+ * @returns {string}
+ */
+function textOfAssembler(assembler) {
+  if (assembler === null || typeof assembler !== 'object') return '';
+  const blocks = typeof assembler.blocks === 'function' ? assembler.blocks() : [];
+  if (!Array.isArray(blocks)) return '';
+  const parts = [];
+  for (const block of blocks) {
+    if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
+      parts.push(block.text);
+    }
+  }
+  return parts.join('\n').trim();
+}
+
+/**
+ * 给一条助手回复打分（0-100）。任何失败返回 null（不亮），不抛错。
+ *
+ * @param {{ctx:object, engine:object, log?:object}} deps
+ * @param {{agent?:object, text?:string}} input
+ * @returns {Promise<{score:number, reason:string, provider:string, model:string}|null>}
+ */
+export async function scoreFavoriteMessage(deps, { agent, text } = {}) {
+  const body = typeof text === 'string' ? text.trim() : '';
+  if (body.length === 0) return null;
+  const session = agent !== null && typeof agent === 'object' ? agent.session : undefined;
+  if (session === undefined || session === null) return null;
+  const target = routeOf(deps.ctx, session, agent);
+  if (target === null) return null;
+
+  const options = {
+    provider: target.provider,
+    model: target.model,
+    reasoningEffort: 'off',
+    temperature: 0,
+    maxTokens: FAVORITE_SCORE_MAX_TOKENS,
+    messages: [
+      { role: 'system', content: [{ type: 'text', text: buildFavoriteScoreSystemPrompt() }] },
+      { role: 'user', content: [{ type: 'text', text: buildFavoriteScoreUserText(body) }] },
+    ],
+  };
+
+  let assembler;
+  try {
+    assembler = await callStream({
+      ctx: deps.ctx,
+      engine: deps.engine,
+      options,
+      timeoutMs: FAVORITE_SCORE_TIMEOUT_MS,
+      label: '推荐收藏打分',
+      retry: false,
+    });
+  } catch (error) {
+    deps.log?.warn?.(`推荐收藏打分失败（忽略，不亮）：${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+
+  const parsed = parseFavoriteScore(textOfAssembler(assembler));
+  if (parsed === null) {
+    deps.log?.warn?.('推荐收藏打分：模型输出解析失败（忽略，不亮）');
+    return null;
+  }
+  return { score: parsed.score, reason: parsed.reason, provider: target.provider, model: target.model };
+}
+
+export default scoreFavoriteMessage;