dsh-subagent-profile 0.3.4 → 0.5.0

package/lib/core/evolution-advice.mjs

@@ -1,13 +1,16 @@
 // lib/core/evolution-advice.mjs — evolution:advice 派发优化建议链（从 evolution-summary.mjs
 // 拆出以守文件行门）：suggestAdvice（纯函数四条件 + 升/降轴硬规则）、readSummaries /
-// refreshSummaries / computeAdvice / buildAdviceText（生产聚合触发与注入文本）。
+// refreshSummaries / computeAdvice / renderAdviceText（人类面板数据源）。
 // 聚合本体（computeSummaries/writeSummaries）仍驻 evolution-summary.mjs；本模块只读
 // 台账并调度聚合，绝无写回台账路径。fail-soft 纪律与 evolution-summary 同源。
+// 本轮起模型侧注入已下架（index.mjs 的 evolution:advice section 恒空）：本链只为
+// 人类面板（建议卡/提醒中心/审计行）服务，不再生成模型可见文本。
 //
 // 依赖方向：本模块 → evolution-summary.mjs（单向，无环）。
 
 import { existsSync, readFileSync, statSync } from 'node:fs';
-import { computeSummaries, parseDispatchRecords, writeSummaries, confidenceLevel } from './evolution-summary.mjs';
+import { computeSummaries, parseDispatchRecords, writeSummaries, confidenceLevel, profileKeyOf } from './evolution-summary.mjs';
+import { loadWithMigration } from './evolution-persistence.mjs';
 
 // --- 派发优化建议（suggestAdvice）-----------------------------------------------
 // 从单条 L1 聚合（l1Entry）产出「一项确定性建议」或 null。四条件齐备才产出：
@@ -17,6 +20,8 @@ import { computeSummaries, parseDispatchRecords, writeSummaries, confidenceLevel
 //   （平）。阈值 successThreshold / confidenceMinLevel / cooldownMs 为建议初值，
 //   待实测后校准。
 const CONFIDENCE_RANK = { low: 0, medium: 1, high: 2 };
+// 置信度级别中文映射（面板文本人话化，与客户端 ZH.confidenceZh 同口径）。
+const CONFIDENCE_ZH = { low: '低', medium: '中等', high: '高' };
 
 function hasCapabilityAxis(profileKey) {
   return /(^|\|)(preset|provider|model|persona|toolFilter):/.test(String(profileKey ?? ''));
@@ -50,7 +55,7 @@ function performanceText(entry) {
   const perf = entry?.perf ?? {};
   const parts = [
     `过去 ${entry?.deployments_total ?? 0} 次：完成 ${outcome.completed ?? 0}、失败 ${outcome.failed ?? 0}、终止 ${outcome.killed ?? 0}`,
-    `加权成功分 ${entry?.score?.weighted_success ?? 0}`,
+    `近期表现分 ${entry?.score?.weighted_success ?? 0}`,
   ];
   if (perf.avg_elapsed_ms !== null && perf.avg_elapsed_ms !== undefined) parts.push(`平均耗时 ${perf.avg_elapsed_ms}ms`);
   if (perf.avg_output_len !== null && perf.avg_output_len !== undefined) parts.push(`平均输出 ${perf.avg_output_len} 字符`);
@@ -63,9 +68,71 @@ function directionFor(profileKey, capability, budget) {
   return '平';
 }
 
+// --- 建议对象与理由（确定性人话）-----------------------------------------------
+// objectText：建议直接带对象（模型改用更低档 / 去掉自定义人格……），按最保守改变
+// 取一段（自定义人格/工具过滤先、模型次之、预设最后——与候选生成降档的保守序一致）；
+// 升预算方向读 L2 预算轴存在性给「推理强度上调一档 / maxTokens 上调」。
+// reasonText：理由一句话，从身份键段 + 聚合计数推导（同输入恒同输出，不含任何
+// 配置原文）。
+
+function adviceKeySegments(profileKey) {
+  const parsed = { preset: false, model: false, persona: false, toolFilter: false };
+  for (const part of String(profileKey ?? '').split('|')) {
+    if (part.startsWith('preset:')) parsed.preset = true;
+    else if (part.startsWith('model:')) parsed.model = true;
+    else if (part === 'persona:1') parsed.persona = true;
+    else if (part === 'toolFilter:1') parsed.toolFilter = true;
+  }
+  return parsed;
+}
+
+function downObjectText(segments) {
+  if (segments.persona) return '去掉自定义人格';
+  if (segments.toolFilter) return '移除工具过滤';
+  if (segments.model) return '模型改用更低档';
+  if (segments.preset) return '预设改用更低档';
+  return '能力配置降级';
+}
+
+function budgetObjectText(profileKey, l2) {
+  const source = l2 !== null && typeof l2 === 'object' ? l2 : {};
+  let hasEffort = false;
+  let hasTokens = false;
+  for (const axisKey of Object.keys(source)) {
+    if (typeof axisKey !== 'string') continue;
+    if (axisKey.startsWith(`${profileKey}:reasoningEffort:`)) hasEffort = true;
+    else if (axisKey.startsWith(`${profileKey}:maxTokens:`)) hasTokens = true;
+  }
+  if (hasEffort) return '推理强度上调一档';
+  if (hasTokens) return 'maxTokens 上调';
+  return '预算上调';
+}
+
+function downReasonText(segments, entry) {
+  const n = Number.isFinite(entry?.confidence?.n) ? entry.confidence.n : (entry?.deployments_total ?? 0);
+  const killed = Number.isFinite(entry?.outcome?.killed) ? entry.outcome.killed : 0;
+  if (segments.persona) {
+    return killed > 0
+      ? `带自定义人格的派发 ${n} 次里 ${killed} 次被终止，去掉后可复用父会话统一提示`
+      : '去掉自定义人格后，子 Agent 复用父会话统一提示，配置更简单';
+  }
+  if (segments.toolFilter) return '移除工具过滤后，子 Agent 的工具面回到父会话范围，配置更简单';
+  if (segments.model) return '同类任务改用更低档模型，成本通常更低';
+  if (segments.preset) return '相邻低档预设能力相近，成本通常更低';
+  return `近期表现低于预期（近期表现分 ${entry?.score?.weighted_success ?? 0}），降低能力配置是更稳妥的方向`;
+}
+
+function upReasonText(profileKey, l2) {
+  const text = budgetObjectText(profileKey, l2);
+  if (text === '推理强度上调一档') return '推理强度上调一档可提升复杂任务完成质量';
+  if (text === 'maxTokens 上调') return 'token 上限上调后可减少中途截断';
+  return '预算上调后可提升复杂任务完成质量';
+}
+
 export function suggestAdvice({
   l1Entry,
   profileKey = '',
+  l2 = null,
   minN = 3,
   cooldownMs = 600000,
   now = Date.now(),
@@ -90,35 +157,31 @@ export function suggestAdvice({
   const axes = entry.axes !== null && typeof entry.axes === 'object' ? entry.axes : null;
   const capability = axes !== null && typeof axes.capability === 'boolean' ? axes.capability : hasCapabilityAxis(key);
   const budget = axes !== null && typeof axes.budget === 'boolean' ? axes.budget : hasBudgetAxis(key);
+  const suggestion = directionFor(key, capability, budget);
+  const segments = adviceKeySegments(key);
 
   return {
     profileKey: key,
     performanceText: performanceText(entry),
-    suggestion: directionFor(key, capability, budget),
+    suggestion,
+    // 建议对象与理由：确定性人话，同输入恒同输出；面板渲染「建议：…」与「理由：…」。
+    objectText: suggestion === '降' ? downObjectText(segments) : suggestion === '升' ? budgetObjectText(key, l2) : '',
+    reasonText: suggestion === '降' ? downReasonText(segments, entry) : suggestion === '升' ? upReasonText(key, l2) : '',
     confidence: level,
     cooldownUntil: now + cooldownMs,
   };
 }
 
-// --- 派发优化建议（evolution:advice 注入段，默认关）----------------------------
+// --- 派发优化建议（面板侧；模型侧注入下架，注入段恒空）-------------------
 
-// 读 summaries.json（存在才读；损坏/形状不符 → null，fail-soft）。
-// 版本化：只接受 v:1；未知/超前版本 fail-soft 跳过（v1 无前驱，迁移表空）。
-export function readSummaries(file, logger) {
-  try {
-    if (!existsSync(file)) return null;
-    const parsed = JSON.parse(readFileSync(file, 'utf8'));
-    if (parsed === null || typeof parsed !== 'object' || parsed.l1 === null || typeof parsed.l1 !== 'object') return null;
-    if (parsed.v !== 1) {
-      if (logger !== undefined && typeof logger.warn === 'function') {
-        logger.warn(`[dsh-subagent-profile] summaries.json 版本 ${String(parsed.v)} 未知，跳过该资产（fail-soft）`);
-      }
-      return null;
-    }
-    return parsed;
-  } catch {
-    return null;
-  }
+// 读 summaries.json（存在才读）。版本化经通用持久化机制：v 低于当前版本时内存
+// 前向迁移后原子写回；损坏/形状不符/未知或超前版本 fail-soft 返回 null，并告警
+// + onLoss（迁移丢失计数）。l1 形状校验保留（读端数据契约）。
+export function readSummaries(file, logger, opts = {}) {
+  const data = loadWithMigration(file, 'summaries', { logger, onLoss: opts.onLoss });
+  if (data === null) return null;
+  if (data.l1 === null || typeof data.l1 !== 'object') return null;
+  return data;
 }
 
 // 生产聚合触发点（T1 修复）：读 dispatch.jsonl → parseDispatchRecords → computeSummaries
@@ -152,14 +215,15 @@ function summariesStale(dispatchFile, summariesFile) {
   }
 }
 
-// 注入段文本：全局聚合摘要 + 各 profile 一条确定性建议（人类读、非指令）。
+// 面板侧文本：全局聚合摘要 + 各 profile 一条确定性建议（人类读、非指令；
+// 只供人类面板渲染，不再进模型侧注入段）。
 export function renderAdviceText(advice, global) {
   const direction = (value) => (value === '升' ? '可上调预算' : value === '降' ? '建议降级' : '维持现状');
   const lines = advice.map((a) => {
     const untilText = Number.isFinite(a.cooldownUntil)
       ? `（冷却至 ${new Date(a.cooldownUntil).toLocaleTimeString('zh-CN', { hour12: false })}）`
       : '';
-    return `- ${a.profileKey}：${a.performanceText}；${direction(a.suggestion)}（置信度 ${a.confidence}）${untilText}`;
+    return `- ${a.profileKey}：${a.performanceText}；${direction(a.suggestion)}（置信度 ${CONFIDENCE_ZH[a.confidence] ?? a.confidence}）${untilText}`;
   });
   const total = global.completed + global.failed + global.killed;
   return `以下为过去派发的只读统计与确定性建议（仅供人类参考，不改变派发行为）：\n` +
@@ -168,8 +232,9 @@ export function renderAdviceText(advice, global) {
 
 // 建议产出后把各 profile 的新 cooldown.until_ts 写回 summaries.json（原子写、
 // fail-soft）。写前重读磁盘再合并：并发注入各自基于最新磁盘态写回，把互相覆盖
-// 窗口压到最小（残余竞态：读-写间隙，彻底解决需进程内锁，成本不值）。
-function writeBackCooldowns(file, data, produced, logger) {
+// 窗口压到最小（残余竞态：读-写间隙，彻底解决需进程内锁，成本不值）。回滚冷却
+// 注入（suggestion-rollback 后同键冷却）复用同一写入口。
+export function writeBackCooldowns(file, data, produced, logger) {
   const fresh = readSummaries(file, logger);
   const base = fresh !== null && typeof fresh === 'object' ? fresh : data;
   const l1 = { ...(base.l1 ?? {}) };
@@ -183,15 +248,31 @@ function writeBackCooldowns(file, data, produced, logger) {
   }
 }
 
-// 结构化建议（读+算，不写回 cooldown、不渲染文本）：供注入段与只读面板共用。
-export function computeAdvice({ summariesFile, dispatchFile, whitelist, logger }) {
+// 滞后防振荡 streak 写回 summaries.json（原子写、fail-soft）：与 cooldown 同口径
+// 重读磁盘再合并；写入失败只 warn，内存计数仍驱动本轮生成。
+export function writeBackStreaks(summariesFile, streaks, logger) {
+  const fresh = readSummaries(summariesFile, logger);
+  if (fresh === null || typeof fresh !== 'object') return;
+  const l1 = { ...(fresh.l1 ?? {}) };
+  for (const streak of streaks) {
+    const group = l1[streak.profileKey];
+    l1[streak.profileKey] = { ...group, streak: { axis: streak.axis, direction: streak.direction, count: streak.count, last_ts: streak.last_ts } };
+  }
+  const res = writeSummaries(summariesFile, { l1, l2: fresh.l2 ?? {} });
+  if (res.persisted !== true) {
+    logger.warn(`[dsh-subagent-profile] evolution:advice streak 写回失败：${res.error ?? '未知错误'}`);
+  }
+}
+
+// 结构化建议（读+算，不写回 cooldown、不渲染文本）：供人类面板与只读展示共用。
+export function computeAdvice({ summariesFile, dispatchFile, whitelist, logger, onLoss }) {
   if (dispatchFile !== undefined && summariesStale(dispatchFile, summariesFile)) refreshSummaries({ dispatchFile, summariesFile, logger });
-  let data = readSummaries(summariesFile, logger);
+  let data = readSummaries(summariesFile, logger, { onLoss });
   // summaries.json 存在但不可读（损坏/版本不符）→ fail-soft 重建（幂等可复算），
   // 损坏资产不阻断建议产出；台账缺失时维持空建议（refreshSummaries 的 no-ledger 语义）。
   if (data === null && dispatchFile !== undefined && existsSync(summariesFile)) {
     refreshSummaries({ dispatchFile, summariesFile, logger });
-    data = readSummaries(summariesFile, logger);
+    data = readSummaries(summariesFile, logger, { onLoss });
   }
   if (data === null) return { advice: [], global: { completed: 0, failed: 0, killed: 0, total: 0 }, produced: [], summaries: null };
   const l1 = data.l1 ?? {};
@@ -205,7 +286,7 @@ export function computeAdvice({ summariesFile, dispatchFile, whitelist, logger }
     global.completed += group.outcome?.completed ?? 0;
     global.failed += group.outcome?.failed ?? 0;
     global.killed += group.outcome?.killed ?? 0;
-    const suggestion = suggestAdvice({ l1Entry: group, profileKey });
+    const suggestion = suggestAdvice({ l1Entry: group, profileKey, l2: data.l2 });
     if (suggestion === null) continue;
     // 只对实际产出的建议键校验候选（N 不足不产出建议的组不要求 system-trust）。
     assertSystemCandidate(whitelist, presetFromKey(profileKey));
@@ -215,10 +296,49 @@ export function computeAdvice({ summariesFile, dispatchFile, whitelist, logger }
   return { advice, global: { ...global, total: global.completed + global.failed + global.killed }, produced, summaries: data };
 }
 
-// 派发优化建议段文本生成：computeAdvice → 写回 cooldown（防每请求重复注入）→ 渲染；空建议返回空串。
-export function buildAdviceText({ summariesFile, dispatchFile, whitelist, logger }) {
-  const { advice, global, produced, summaries } = computeAdvice({ summariesFile, dispatchFile, whitelist, logger });
+// 面板侧建议文本生成：computeAdvice → 写回 cooldown（防每请求重复注入）→ 渲染；空建议返回空串。
+// 仅供人类面板（/list 建议区）调用；模型侧注入段已下架（index.mjs 恒空）。
+export function buildAdviceText({ summariesFile, dispatchFile, whitelist, logger, onLoss }) {
+  const { advice, global, produced, summaries } = computeAdvice({ summariesFile, dispatchFile, whitelist, logger, onLoss });
   if (advice.length === 0) return '';
   writeBackCooldowns(summariesFile, summaries, produced, logger);
   return renderAdviceText(advice, global);
 }
+
+// --- 近期派发明细（面板折叠表数据源）------------------------------------------
+// 从派发台账读行，用「行生效配置 → profileKeyOf（与聚合层同口径）」匹配各建议键，
+// 取最近 limit 条（按 ts 倒序）。只取渲染所需字段（时间/会话/子 Agent/结果/耗时/模式），
+// 不含任何原文。台账缺失/读失败/无匹配 → 空表（fail-soft，面板显示 0 次）。
+export function recentDispatchDetails(dispatchFile, profileKeys, { limit = 5 } = {}) {
+  const out = {};
+  const wanted = new Set(Array.isArray(profileKeys) ? profileKeys.filter((key) => typeof key === 'string') : []);
+  if (typeof dispatchFile !== 'string' || !existsSync(dispatchFile) || wanted.size === 0) return out;
+  let lines;
+  try {
+    lines = readFileSync(dispatchFile, 'utf8').split('\n');
+  } catch {
+    return out;
+  }
+  const { records } = parseDispatchRecords(lines);
+  const byKey = new Map();
+  for (const record of records) {
+    if (record === null || typeof record !== 'object') continue;
+    const key = profileKeyOf(record.effective);
+    if (!wanted.has(key)) continue;
+    const rows = byKey.get(key) ?? [];
+    rows.push({
+      ts: typeof record.ts === 'number' ? record.ts : null,
+      sessionId: typeof record.session_id === 'string' ? record.session_id : null,
+      childId: typeof record.child_id === 'string' ? record.child_id : null,
+      mode: typeof record.mode === 'string' ? record.mode : '',
+      outcome: record.outcome !== null && typeof record.outcome === 'object' && typeof record.outcome.status === 'string' ? record.outcome.status : '',
+      elapsedMs: record.outcome !== null && typeof record.outcome === 'object' && Number.isFinite(record.outcome.elapsed_ms) ? record.outcome.elapsed_ms : null,
+    });
+    byKey.set(key, rows);
+  }
+  for (const [key, rows] of byKey) {
+    rows.sort((a, b) => (b.ts ?? 0) - (a.ts ?? 0));
+    out[key] = rows.slice(0, limit);
+  }
+  return out;
+}

package/lib/core/evolution-assets.mjs

@@ -0,0 +1,167 @@
+// lib/core/evolution-assets.mjs — 进化候选资产域（subagent-evolution/assets/）。
+// 与 drafts-store 隔离：drafts 是「存为方案」通道（source='human'/'dispatch'，无
+// 生命周期）；evolution 资产带五态生命周期（draft/proposed/applied/expired/
+// rolled_back）与治理审计，本域只落进化候选。资产文件与索引各自原子写
+// （tmp+rename），损坏/缺失 fail-soft；写失败 warn + 通知治理审计钩子（不抛）。
+// 状态流转（本域职责内）：draft →（apply 确认后由装配层驱动）→ proposed；
+// 过期判定与换代由装配层驱动（先比对数据变化再转 expired 并留审计）；
+// applied/rolled_back 供金丝雀判定与回滚流转。
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const ASSETS_VERSION = 1;
+const ASSET_STATES = new Set(['draft', 'proposed', 'applied', 'expired', 'rolled_back']);
+const UNRESOLVED_STATES = new Set(['draft', 'proposed']);
+const ID_PATTERN = /^[A-Za-z0-9-]{1,64}$/;
+
+// 原子写（tmp+rename）：崩溃不产生截断文件；失败 fail-soft 清理 tmp + warn +
+// 治理审计钩子。返回 {persisted, error?} 由调用方按 fail-soft 处理。
+function atomicWrite(file, payload, logger, onGovernanceFailure) {
+  const tmp = `${file}.tmp`;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+    renameSync(tmp, file);
+    return { persisted: true };
+  } catch (error) {
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    if (logger !== undefined && typeof logger.warn === 'function') {
+      logger.warn(`[dsh-subagent-profile] evolution assets: 资产写入失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    onGovernanceFailure();
+    return { persisted: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// 读索引（assets.index.json）；缺失/损坏/形状不符回退空索引并 warn。
+function loadIndex(file, logger) {
+  if (!existsSync(file)) return { v: ASSETS_VERSION, assets: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (parsed !== null && typeof parsed === 'object' && parsed.v === ASSETS_VERSION && Array.isArray(parsed.assets)) {
+      return { v: ASSETS_VERSION, assets: parsed.assets.filter((e) => e !== null && typeof e === 'object' && typeof e.id === 'string') };
+    }
+  } catch { /* fail-soft 从零 */ }
+  if (logger !== undefined && typeof logger.warn === 'function') {
+    logger.warn('[dsh-subagent-profile] evolution assets: 索引文件形状不符或损坏，按空索引处理');
+  }
+  return { v: ASSETS_VERSION, assets: [] };
+}
+
+// 读单个资产文件；缺失/损坏/状态非法返回 null（fail-soft，索引条目调用方跳过）。
+function loadAssetFile(file) {
+  if (!existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (parsed !== null && typeof parsed === 'object' && parsed.v === ASSETS_VERSION
+      && typeof parsed.id === 'string' && ASSET_STATES.has(parsed.state)) {
+      return parsed;
+    }
+  } catch { /* fail-soft */ }
+  return null;
+}
+
+// 资产 id 白名单校验（文件名直接由 id 拼接，防路径穿越）。
+function safeAssetId(id) {
+  return typeof id === 'string' && ID_PATTERN.test(id) ? id : null;
+}
+
+// 索引条目 → 完整资产（读文件合并；文件缺失/损坏返回 null 由调用方跳过）。
+function readAsset(state, entry) {
+  const asset = loadAssetFile(join(state.dir, `${entry.id}.json`));
+  if (asset === null) return null;
+  return { ...asset, index: entry };
+}
+
+// 过期判定与换代由装配层（evolution-engine）驱动：候选过期后需先比对数据变化
+// 再决定是否转 expired 并留审计，本域不再按时间盲扫 draft。此函数保留为稳定
+// 接口（list/get 的读前钩子），恒返回 0、不改任何资产。
+function sweepExpiredAssets() {
+  return 0;
+}
+
+// 状态流转：资产文件先行（合并 patch + 状态 + updatedAt），成功后同步索引。
+function transitionAsset(state, id, nextState, patch) {
+  const safe = safeAssetId(id);
+  if (safe === null) return { persisted: false, error: '资产 id 非法' };
+  const entry = state.index.assets.find((e) => e.id === safe);
+  if (entry === undefined) return { persisted: false, error: '资产不存在' };
+  if (!ASSET_STATES.has(nextState)) return { persisted: false, error: '资产状态非法' };
+  const asset = loadAssetFile(join(state.dir, safe + '.json'));
+  if (asset === null) return { persisted: false, error: '资产文件缺失或损坏' };
+  const next = { ...asset, ...patch, state: nextState, updatedAt: Date.now() };
+  const persisted = state.persistAsset(next);
+  if (persisted.persisted) {
+    entry.state = nextState;
+    entry.updatedAt = next.updatedAt;
+    // 索引镜像有效期（换代判定按索引条目读 expiry，patch 后必须同步）。
+    entry.expiry = typeof next.expiry === 'number' ? next.expiry : null;
+    state.persistIndex();
+  }
+  return persisted;
+}
+
+// 新资产落盘：校验 → 写资产文件 → 追加索引条目 → 写索引（文件先行，索引为清单
+// 事实源；索引写失败仅告警，内存态继续驱动本进程）。
+function addAsset(state, asset) {
+  if (asset === null || typeof asset !== 'object') return { persisted: false, error: '资产必须是对象' };
+  const safe = safeAssetId(asset.id);
+  if (safe === null || asset.state === undefined || !ASSET_STATES.has(asset.state)) {
+    return { persisted: false, error: '资产 id 或状态非法' };
+  }
+  if (state.index.assets.some((e) => e.id === safe)) return { persisted: false, error: '资产 id 已存在' };
+  const persisted = state.persistAsset(asset);
+  if (!persisted.persisted) return persisted;
+  state.index.assets.push({
+    id: asset.id,
+    source: typeof asset.source === 'string' ? asset.source : 'evolution',
+    profileKey: typeof asset.profile_key === 'string' ? asset.profile_key : '',
+    state: asset.state,
+    axis: asset.axis,
+    direction: asset.direction,
+    expiry: typeof asset.expiry === 'number' ? asset.expiry : null,
+    createdAt: asset.createdAt,
+    updatedAt: asset.updatedAt,
+  });
+  const indexPersisted = state.persistIndex();
+  return indexPersisted.persisted ? { persisted: true, id: asset.id } : { persisted: false, error: indexPersisted.error };
+}
+
+// 按 id 读资产（清扫过期草稿后）；id 非法或不存在返回 undefined。
+function getAsset(state, id) {
+  sweepExpiredAssets(state);
+  const safe = safeAssetId(id);
+  if (safe === null) return undefined;
+  const entry = state.index.assets.find((e) => e.id === safe);
+  if (entry === undefined) return undefined;
+  return readAsset(state, entry) ?? undefined;
+}
+
+export function createEvolutionAssets({ dshHome, logger, onGovernanceFailure = () => {} } = {}) {
+  const dir = join(dshHome, 'subagent-evolution', 'assets');
+  const indexFile = join(dir, 'assets.index.json');
+  const state = {
+    dir,
+    index: loadIndex(indexFile, logger),
+    persistIndex: () => atomicWrite(indexFile, state.index, logger, onGovernanceFailure),
+    persistAsset: (asset) => atomicWrite(join(dir, `${asset.id}.json`), asset, logger, onGovernanceFailure),
+  };
+  return {
+    list() {
+      sweepExpiredAssets(state);
+      return state.index.assets.map((entry) => readAsset(state, entry)).filter((a) => a !== null);
+    },
+    get: (id) => getAsset(state, id),
+    add: (asset) => addAsset(state, asset),
+    transition: (id, nextState, patch) => transitionAsset(state, id, nextState, patch),
+    // 同身份键是否仍有未处置（draft/proposed）资产——生成去重与观察期隔离判据。
+    hasUnresolved: (profileKey) => state.index.assets.some((e) => e.profileKey === profileKey && UNRESOLVED_STATES.has(e.state)),
+    findUnresolved: (profileKey) => state.index.assets
+      .filter((e) => e.profileKey === profileKey && UNRESOLVED_STATES.has(e.state))
+      .map((e) => ({ ...e })),
+    countBySource: (source) => state.index.assets.filter((e) => e.source === source).length,
+    ids: () => state.index.assets.map((e) => e.id),
+    sweepExpired: (now) => sweepExpiredAssets(state, now),
+  };
+}