@x-otto/cli 0.0.1-alpha.0

package/dist/bundled-extensions/plugin-skill-inductor/plugin.ts

@@ -0,0 +1,77 @@
+/**
+ * plugin.ts —— plugin-skill-inductor 插件入口（RFC-318 M2）。
+ *
+ * otto 的第一个 `services` 型内部插件：常驻 worker，靠宿主推来的 `session.idle` 通知
+ * 干活（RFC-318 D9），而不是自持定时器轮询——轮询既拿不到 sessionId、也会在空闲期
+ * 无谓烧 CPU。
+ *
+ * **为什么归纳器是插件而不是 core 纯库**（RFC-318 D1，用户 grill 定调）：归纳策略本身
+ * （抽取 prompt、阈值）要能被自迭代回路自己升级——插件形态使"改进归纳器"与"改进任何
+ * 其他能力"走同一条提案→diff→审查→热加载流水线。core 纯库做不到热替换。
+ *
+ * **高危能力零豁免（R1）**：service / session.read / llm.complete 都要用户逐项 grant，本插件
+ * 不因"内置"而绕过信任门。user.notify/storage 仍按各自既有风险分层处理。
+ */
+import { definePlugin } from '@x-otto/plugin'
+
+import { SkillInductor } from './src/inductor-service'
+import { runCandidateDigest } from './src/candidate-digest'
+
+import type { PluginServiceContext, PluginServiceNotification } from '@x-otto/plugin'
+
+export default definePlugin(() => ({
+  services: [
+    {
+      id: 'inductor',
+      /**
+       * RFC-327 M4：候选摘要的定时报告。
+       *
+       * 这是 otto 第一条真实的"自迭代定时回路"——宿主 core schedule 到点 →
+       * `schedule.tick` 投递到本隔离 worker → 只读自己的候选存储 → 有值得处理的事时
+       * 经 `host.notify` 提示用户查看候选。常驻 service 不持有可验证的会话交互目标，故不得
+       * 调用 `host.ask`（RFC-350 fail-closed）；cron 解析/持久化/崩溃恢复全归 core（R4），
+       * 本插件拿不到 timer handle。
+       *
+       * 每 4 小时一次：低频足以避免噪音，又能在用户结束一段工作后的合理窗口内提醒。
+       * 没有新候选时**完全静默**（见 candidate-digest 的"静默是常态"）。
+       */
+      schedules: [{ key: 'candidate-digest', cron: '0 */4 * * *', name: '技能候选摘要' }],
+      start(ctx: PluginServiceContext) {
+        const inductor = new SkillInductor({
+          host: ctx.host,
+          storage: ctx.storage,
+          logger: ctx.logger,
+        })
+        // onNotify 是 M1 新增的被动接收面（无需能力声明——真正的数据面是 readTranscript）。
+        // 宿主未提供时（旧版本 otto）静默降级为"不工作"，而不是崩溃。
+        ctx.onNotify?.((n: PluginServiceNotification) => {
+          // RFC-327 M4：定时到点 → 候选摘要（只读 + 可能通知，不产生工作）。
+          if (n.type === 'schedule.tick') {
+            if (!ctx.storage) return
+            return runCandidateDigest(
+              { storage: ctx.storage, notify: ctx.host?.notify, logger: ctx.logger },
+              { scheduleId: n.scheduleId, occurrenceId: n.occurrenceId },
+            )
+              .then(() => undefined)
+              .catch(() => undefined) // 同下：报告失败不该被记成服务崩溃
+          }
+          if (n.type !== 'session.idle') return
+          // handler 内部已全程 fail-closed；返回 Promise 让 worker 侧能 await 完成，
+          // 避免服务停机时截断进行中的抽取。
+          // `.catch` 是防御纵深：`onSessionIdle` 的同步前段（能力自检里的 logger 调用）
+          // 若抛错会绕过其内部 try/catch，冒泡成 unhandled rejection——那会被 worker 记成
+          // 服务崩溃并触发退避重启，对"这次没抽出东西"是完全错误的严重级别。
+          return inductor
+            .onSessionIdle(n.sessionId, n.options)
+            .then(() => undefined)
+            .catch(() => undefined)
+        })
+        ctx.logger.info('skill-inductor service started')
+      },
+      stop() {
+        // 无外部连接/定时器需要收敛——in-flight 的抽取由 worker 停机窗口自然完成或被截断，
+        // 截断的代价只是"下次 notify 重抽一段"，无状态损坏（游标只在成功保存后推进）。
+      },
+    },
+  ],
+}))

package/dist/bundled-extensions/plugin-skill-inductor/src/candidate-detector.ts

@@ -0,0 +1,210 @@
+/**
+ * candidate-detector.ts —— RFC-318 M3：把 episode 聚成"同类任务重复出现"的候选。
+ *
+ * 这是技能回路的判别环节：**什么时候值得打断用户，问"要不要把这套流程固化成 skill"**。
+ * 门槛太低会变成骚扰（RFC-318 §8 列为最大风险之一），太高则回路永远不触发。首版取
+ * "最近 50 条里同类成功轨迹出现 ≥3 次"。
+ */
+
+import { createHash } from 'node:crypto'
+
+import { episodeSimilarity } from './similarity'
+
+import type { Episode } from './episode'
+
+/** 只看最近这么多条 episode——更早的路径可能已因代码演进失效。 */
+export const DETECT_WINDOW = 50
+/**
+ * 并簇阈值（`episodeSimilarity` 的加权分）。
+ *
+ * **0.25 是量出来的，不是拍的**。RFC 草案里写的 0.5 在施工时被实测推翻：拿三组真实纹理
+ * 的同义改写签名（插件能力/flaky 测试/provider 注册各 3 条）算全部配对分数——
+ *
+ *   同类对：min 0.285 / avg 0.496 / max 0.755
+ *   跨类对：max 0.160（avg 0.041）
+ *
+ * 分离度很好，但 0.5 正好切在**同类分布的中间**，近一半真实同类对会被判为不相似而漏配
+ * （连通分量能救回一部分，但 min 0.285 那种远低于 0.5 的仍会丢）。取 0.25：低于同类下界
+ * 0.285、高于跨类上界 0.160，中间留 0.125 的安全带。
+ *
+ * 词集 Jaccard 的分数天然偏低——同义改写会换掉一半实词（"fix…that fails under
+ * concurrency" vs "repair…under concurrent execution"），交并比自然掉到 0.3 附近。用
+ * 直觉里的"相似度该有 0.7"来定阈值是错的。
+ */
+export const SIMILARITY_THRESHOLD = 0.25
+/** 成簇门槛——少于这么多条同类不算"重复出现"，不产候选。 */
+export const MIN_CLUSTER_SIZE = 3
+
+/** 候选（M4a 宿主薄读取器的消费对象；字段即 grill 简报可展示的元信息面）。 */
+export interface SkillCandidate {
+  /** 稳定簇 id（见 `clusterIdOf` —— 关系到 R9 冷却能否生效）。 */
+  id: string
+  /** 代表性任务签名：取簇内最长者（信息量最大）。 */
+  taskSignature: string
+  tags: string[]
+  /** 簇成员会话 id（用户追溯入口）。 */
+  sessionIds: string[]
+  size: number
+  firstAt: number
+  lastAt: number
+  /** 用户拒绝时刻（R9 冷却）。检测器不产生此字段，由 store 合并时保留。 */
+  dismissedAt?: number
+  /** RFC-349 Should-2：候选被采纳为 skill 的时刻（用户在 grill 里选"记录"后由宿主回填）。
+   * 与 `dismissedAt` 对称——后者是"用户不要"，前者是"用户要了"。 */
+  appliedAt?: number
+  /** RFC-349 Should-2：该候选产出的 skill 被注入到 prompt 的次数（宿主侧追踪）。
+   * 0 = 已生成但从未被使用（可能噪声 skill）；高值 = 高价值 skill。 */
+  usageCount?: number
+}
+
+export interface DetectOptions {
+  window?: number
+  threshold?: number
+  minClusterSize?: number
+}
+
+/**
+ * 簇 id —— **必须在簇成长时保持不变**，否则已被用户拒绝的候选会因为多了一个成员而
+ * 换个 id"复活"，直接绕过 R9 的 14 天冷却，变成反复骚扰。
+ *
+ * 故 id 只由**最早 `MIN_CLUSTER_SIZE` 个成员**的 sessionId 派生：簇一旦成立，这三个成员
+ * 就不再变化（后来的只会追加在后面），id 就此固定。
+ * 用内容哈希或全量成员哈希都会随成长而变——那正是要避免的。
+ *
+ * **已知残余风险（审核记录，灰度期观察）**：episode 集合有 200 条 FIFO 上限，若某个任务
+ * 类型极高频、把最早的簇成员挤出集合，种子随之变化 → id 变 → 该簇的 dismissedAt 查不到，
+ * 冷却丢失、会被重新问一次。触发条件苛刻（需该类型持续活跃到撑满整个集合），且后果是
+ * "多问一次"而非数据损坏，故首版接受。若灰度观测到，改用"签名 + 最早成员集"的复合键。
+ */
+export function clusterIdOf(members: readonly Episode[], minClusterSize: number): string {
+  const seed = [...members]
+    .sort((a, b) => a.at - b.at)
+    .slice(0, minClusterSize)
+    .map((e) => e.sessionId)
+    .join('|')
+  return `cand_${createHash('sha256').update(seed).digest('hex').slice(0, 12)}`
+}
+
+/**
+ * 检测候选。纯函数：同样的输入永远得到同样的输出（簇 id 稳定性的前提）。
+ *
+ * **只聚 `outcome === 'success'`**：失败/半成功的轨迹不该被归纳成"最佳路径"（Voyager
+ * 先例：技能入库前需验证成功）。它们仍留在 episode store——"这条路走不通"也是知识，
+ * 只是不进候选。
+ *
+ * **聚簇 = 相似图的连通分量**（union-find），不是贪心单遍。
+ *
+ * 贪心（按时间倒序、与已有簇比较后并入）的问题是**结果依赖遍历顺序**：当三条同类 episode
+ * 中存在一条"两两相似度参差"的（A~B、A~C 达阈值但 B~C 不达），先遇到谁决定了它们是聚成
+ * 一簇还是碎成两簇——同一批数据换个到达顺序就得到不同的簇，而簇 id 由成员派生，簇不稳定
+ * 意味着 id 不稳定，R9 冷却直接失效。连通分量没有这个问题：任意两条达阈值即连边，簇是边的
+ * 传递闭包，与遍历顺序无关。
+ *
+ * （施工记录：这个缺陷是在阈值还是草案值 0.5 时被一组真实签名暴露的——A~B=0.66、A~C=0.61、
+ * B~C=0.43，倒序遍历把簇切成 2+1、候选凭空消失。阈值后来标定到 0.25，那组具体数字已不再
+ * 触发问题，但顺序敏感性是算法固有的，与阈值取值无关，故变更保留。）
+ *
+ * 代价是链式漂移（A~B、B~C 达阈值但 A 与 C 不像时三者仍同簇）。对"同类任务"这个语义可接受：
+ * 签名已是去具体化的任务类型描述，链式相似基本意味着确实同类；而顺序敏感会直接丢候选，
+ * 危害大得多。灰度期若观测到误聚率偏高，再考虑加簇内 pair 最小相似度校验。
+ */
+export function detectCandidates(
+  episodes: readonly Episode[],
+  options: DetectOptions = {},
+): SkillCandidate[] {
+  const window = options.window ?? DETECT_WINDOW
+  const threshold = options.threshold ?? SIMILARITY_THRESHOLD
+  const minClusterSize = options.minClusterSize ?? MIN_CLUSTER_SIZE
+
+  // 先按时间取最近 window 条（窗口语义按时间，不按输入顺序）。
+  // `isUsable` 逐条剔除脏数据而不是让整批检测失败：store 里的 items 是 `as Episode[]`
+  // 断言出来的（loadRecord 不做运行时逐字段校验），一条坏记录若能掀翻整轮检测，就会
+  // 让**所有**候选停止更新——fail-closed 没错，但颗粒度必须是单条而非整批。
+  const recent = [...episodes]
+    .filter((e) => isUsable(e) && e.outcome === 'success')
+    .sort((a, b) => a.at - b.at)
+    .slice(-window)
+
+  return groupByConnectivity(recent, threshold)
+    .filter((c) => c.length >= minClusterSize)
+    .map((members) => toCandidate(members, minClusterSize))
+}
+
+/**
+ * 单条 episode 是否可参与聚簇。
+ *
+ * 防的是持久化里的脏数据（手改文件、旧版本格式、写入截断）：`at` 为 NaN 会让排序行为
+ * 不确定并把 `firstAt`/`lastAt` 污染成 NaN 传给 M4a 展示；`tags` 非数组会让 `new Set()`
+ * 得到意外结果；空签名则根本无法参与相似度判定（词集为空，恒为 0 分）。
+ */
+function isUsable(e: Episode): boolean {
+  return (
+    typeof e?.at === 'number' &&
+    Number.isFinite(e.at) &&
+    typeof e.taskSignature === 'string' &&
+    e.taskSignature.trim().length > 0 &&
+    typeof e.sessionId === 'string' &&
+    Array.isArray(e.tags)
+  )
+}
+
+/** 相似图的连通分量（union-find）。O(n²) 比较——n ≤ window（默认 50），可忽略。 */
+function groupByConnectivity(episodes: readonly Episode[], threshold: number): Episode[][] {
+  const parent = episodes.map((_, i) => i)
+  const find = (i: number): number => {
+    let root = i
+    while (parent[root] !== root) root = parent[root] as number
+    // 路径压缩
+    let cur = i
+    while (parent[cur] !== root) {
+      const next = parent[cur] as number
+      parent[cur] = root
+      cur = next
+    }
+    return root
+  }
+  const union = (a: number, b: number): void => {
+    const ra = find(a)
+    const rb = find(b)
+    if (ra !== rb) parent[Math.max(ra, rb)] = Math.min(ra, rb)
+  }
+
+  for (let i = 0; i < episodes.length; i++) {
+    for (let j = i + 1; j < episodes.length; j++) {
+      const a = episodes[i] as Episode
+      const b = episodes[j] as Episode
+      if (episodeSimilarity(a, b) >= threshold) union(i, j)
+    }
+  }
+
+  const groups = new Map<number, Episode[]>()
+  for (let i = 0; i < episodes.length; i++) {
+    const root = find(i)
+    const bucket = groups.get(root)
+    if (bucket) bucket.push(episodes[i] as Episode)
+    else groups.set(root, [episodes[i] as Episode])
+  }
+  return [...groups.values()]
+}
+
+function toCandidate(members: readonly Episode[], minClusterSize: number): SkillCandidate {
+  const byTime = [...members].sort((a, b) => a.at - b.at)
+  // 代表签名取最长者：簇内各条措辞不同，最长的通常保留了最多的任务特征。
+  const representative = [...members].sort(
+    (a, b) => b.taskSignature.length - a.taskSignature.length,
+  )[0] as Episode
+  // 标签取并集（去重，保持首次出现顺序）——单条 episode 的 tags 可能不全。
+  const tags: string[] = []
+  for (const m of byTime) {
+    for (const t of m.tags) if (!tags.includes(t)) tags.push(t)
+  }
+  return {
+    id: clusterIdOf(members, minClusterSize),
+    taskSignature: representative.taskSignature,
+    tags,
+    sessionIds: [...new Set(byTime.map((m) => m.sessionId))],
+    size: members.length,
+    firstAt: (byTime[0] as Episode).at,
+    lastAt: (byTime[byTime.length - 1] as Episode).at,
+  }
+}

package/dist/bundled-extensions/plugin-skill-inductor/src/candidate-digest.ts

@@ -0,0 +1,146 @@
+import { loadCandidates, type CandidateStorage } from './candidate-store'
+
+import type { SkillCandidate } from './candidate-detector'
+
+/**
+ * RFC-327 M4：候选摘要报告器——第一个把「timer → 只读计算 → 用户可见状态」串起来的真实消费者。
+ *
+ * 它存在的意义不是"再加一个功能"，而是**证明 D1-D4/RFC-344 的能力面真的能串成回路**：
+ *   host schedule 到点 → `schedule.tick` 投递到隔离 worker → service 读自己的 scoped
+ *   storage 做纯计算 → 经 `host.notify` 提示用户处理候选；常驻 service 没有可信外部
+ *   InteractionTarget，不能调用 `host.ask`。
+ *
+ * 设计约束（全部来自 RFC-327/RFC-344 的既有规则，非本模块新增）：
+ * - **不触发抽取/模型/工作**：tick 是"看一眼候选并询问/提醒"，不是"干活"；要产生工作仍须
+ *   走 capability-gated `startJob`（本报告器刻意不用）。
+ * - **默认只读**：常规路径只读候选并通知，不在后台将候选标记为用户已处理。
+ * - **静默是常态**：没有新候选就什么都不发。定时任务最容易变成噪音源，故默认沉默。
+ * - **幂等**：以 `{scheduleId, occurrenceId}` 去重（at-least-once 投递下重投不重复通知）。
+ */
+
+/** 已报告过的候选 id + 最近一次 occurrence，持久化在 service 自己的 scoped storage。 */
+export const DIGEST_STATE_ID = 'candidate-digest-state'
+
+export interface DigestState {
+  /** 已经通知过用户的候选 id——避免同一个候选每小时提醒一次。 */
+  reportedIds: string[]
+  /** 最近处理过的 occurrence（幂等键，防 at-least-once 重投重复通知）。 */
+  lastOccurrenceId?: string
+}
+
+/** 候选被视为"值得报告"的最小簇规模——低于此值信噪比太差。 */
+export const DIGEST_MIN_CLUSTER_SIZE = 3
+
+/** 单次通知最多列举的候选数（正文长度受宿主 500 字符上限约束）。 */
+const DIGEST_MAX_LISTED = 3
+
+/** 报告器状态的读写面（与 CandidateStorage 同构，便于共用 ctx.storage）。 */
+export type DigestStorage = CandidateStorage
+
+export async function loadDigestState(storage: DigestStorage): Promise<DigestState> {
+  try {
+    const raw = await storage.load(DIGEST_STATE_ID)
+    if (!raw) return { reportedIds: [] }
+    const reportedIds = Array.isArray(raw['reportedIds']) ? (raw['reportedIds'] as string[]) : []
+    const lastOccurrenceId =
+      typeof raw['lastOccurrenceId'] === 'string' ? (raw['lastOccurrenceId'] as string) : undefined
+    return lastOccurrenceId ? { reportedIds, lastOccurrenceId } : { reportedIds }
+  } catch {
+    // 坏存储不崩服务（同 candidate-store 的 R4 纪律）——退化为"什么都没报告过"，
+    // 最坏后果是重复通知一次，不是丢数据。
+    return { reportedIds: [] }
+  }
+}
+
+/**
+ * 挑出值得报告的候选：规模达标、未被用户拒绝、且此前没报告过。
+ *
+ * `dismissedAt` 的候选被永久排除——用户已经说过"不要"，定时提醒再把它翻出来是骚扰
+ * （R9 冷却语义在报告面的延伸）。
+ */
+export function selectReportable(
+  candidates: readonly SkillCandidate[],
+  reportedIds: readonly string[],
+): SkillCandidate[] {
+  const reported = new Set(reportedIds)
+  return candidates
+    .filter((c) => c.size >= DIGEST_MIN_CLUSTER_SIZE && c.dismissedAt === undefined && !reported.has(c.id))
+    .sort((a, b) => b.size - a.size)
+}
+
+/** 组装通知正文——纯文本、有界；宿主还会再做一次控制字符剥离与截断。 */
+export function formatDigestMessage(reportable: readonly SkillCandidate[]): string {
+  const listed = reportable.slice(0, DIGEST_MAX_LISTED)
+  const lines = listed.map((c) => `· ${c.taskSignature}（重复 ${c.size} 次）`)
+  const more = reportable.length - listed.length
+  const tail = more > 0 ? ` 等 ${reportable.length} 项` : ''
+  return `发现可沉淀为技能的重复任务${tail}：\n${lines.join('\n')}`
+}
+
+
+export interface DigestDeps {
+  storage: DigestStorage
+  /** 宿主注入的通知能力；未授予 `user.notify` 时为 undefined（fail-closed）。 */
+  notify?: (input: { level: 'info' | 'warning' | 'error'; code: string; message: string }) => Promise<void>
+  logger: { info: (msg: string) => void; warn: (msg: string) => void }
+}
+
+export type DigestOutcome =
+  | 'notified'
+  | 'nothing-to-report'
+  | 'duplicate-occurrence'
+  | 'missing-capability'
+
+/**
+ * 处理一次 `schedule.tick`：读候选 → 挑出值得说的 → 通知 → 记账。
+ *
+ * 返回值供测试与诊断使用；服务侧不据此分支（tick 是尽力而为的旁路信号）。
+ */
+export async function runCandidateDigest(
+  deps: DigestDeps,
+  tick: { scheduleId: string; occurrenceId: string },
+): Promise<DigestOutcome> {
+  const { storage, notify, logger } = deps
+  if (!notify) {
+    // 未授予 user.notify——静默跳过而非报错：能力缺失是配置事实，不是运行故障。
+    return 'missing-capability'
+  }
+
+  const state = await loadDigestState(storage)
+
+  // 幂等：at-least-once 投递下同一 occurrence 可能重投，重复处理会让用户收到两次相同通知。
+  if (state.lastOccurrenceId === tick.occurrenceId) return 'duplicate-occurrence'
+
+  const { items } = await loadCandidates(storage)
+  const reportable = selectReportable(items, state.reportedIds)
+
+  // 静默是常态：没有新候选就什么都不做（连状态都不必写，除了 occurrence 记账）。
+  if (reportable.length === 0) {
+    await saveDigestState(storage, { ...state, lastOccurrenceId: tick.occurrenceId })
+    return 'nothing-to-report'
+  }
+
+  await notify!({
+    level: 'info',
+    code: 'skill-inductor.candidates-ready',
+    message: formatDigestMessage(reportable),
+  })
+  logger.info(`skill-inductor digest: notified ${reportable.length} candidate(s)`)
+
+  await saveDigestState(storage, {
+    // 只记录**已报告**的 id——被过滤掉的（规模不够/已拒绝）不入账，
+    // 否则它们将来长大或被恢复时会因"报告过"而永不再提醒。
+    reportedIds: [...state.reportedIds, ...reportable.map((c) => c.id)],
+    lastOccurrenceId: tick.occurrenceId,
+  })
+  return 'notified'
+}
+
+async function saveDigestState(storage: DigestStorage, state: DigestState): Promise<void> {
+  try {
+    await storage.save(DIGEST_STATE_ID, { ...state })
+  } catch {
+    // 写失败只影响幂等精度（下次可能重复通知一条），不影响正确性——不上抛以免
+    // 让一次记账失败被 worker 记成服务崩溃。
+  }
+}

package/dist/bundled-extensions/plugin-skill-inductor/src/candidate-store.ts

@@ -0,0 +1,87 @@
+/**
+ * candidate-store.ts —— RFC-318 M3：候选的持久化、合并与冷却。
+ *
+ * 与 episode 记录分开存（独立记录 id）：两者读写节奏不同——episode 每次抽取都写，
+ * candidates 只在成簇时写；合并成一条会放大写冲突面，也让 M4a 的宿主读取器被迫读入
+ * 全部 episode 才能拿到候选。
+ */
+
+import type { SkillCandidate } from './candidate-detector'
+
+/** storage 记录 id。 */
+export const CANDIDATE_RECORD_ID = 'candidates'
+
+/** 候选集合上限（R6 治理内建）——超出 FIFO 丢弃最旧的。 */
+export const MAX_CANDIDATES = 50
+
+export interface CandidateStorage {
+  save(id: string, data: Record<string, unknown>): Promise<void>
+  load(id: string): Promise<Record<string, unknown> | null>
+}
+
+export interface CandidateRecord {
+  items: SkillCandidate[]
+}
+
+/** 读取候选记录。脏数据/异常一律退化为空（R4：坏存储不崩服务）。 */
+export async function loadCandidates(storage: CandidateStorage): Promise<CandidateRecord> {
+  let raw: Record<string, unknown> | null
+  try {
+    raw = await storage.load(CANDIDATE_RECORD_ID)
+  } catch {
+    return { items: [] }
+  }
+  if (!raw) return { items: [] }
+  const items = Array.isArray(raw['items']) ? (raw['items'] as SkillCandidate[]) : []
+  return { items }
+}
+
+/**
+ * 把新检测出的候选并入既有集合。
+ *
+ * **核心不变式（R9）**：既有候选的 `dismissedAt` **必须保留**。新一轮检测总会重新产出
+ * 同一个簇（id 稳定），若直接覆盖就等于每次抽取都把用户的拒绝抹掉——冷却形同虚设。
+ * 其余字段（size/lastAt/sessionIds/tags）用新值：簇在成长，这些本就该更新。
+ */
+export function mergeCandidates(
+  existing: readonly SkillCandidate[],
+  detected: readonly SkillCandidate[],
+): SkillCandidate[] {
+  const preservedFieldsById = new Map<string, { dismissedAt?: number; appliedAt?: number; usageCount?: number }>()
+  for (const c of existing) {
+    const preserved: { dismissedAt?: number; appliedAt?: number; usageCount?: number } = {}
+    if (typeof c.dismissedAt === 'number') preserved.dismissedAt = c.dismissedAt
+    if (typeof c.appliedAt === 'number') preserved.appliedAt = c.appliedAt
+    if (typeof c.usageCount === 'number') preserved.usageCount = c.usageCount
+    if (Object.keys(preserved).length > 0) preservedFieldsById.set(c.id, preserved)
+  }
+
+  const merged: SkillCandidate[] = []
+  const detectedIds = new Set<string>()
+  for (const c of detected) {
+    detectedIds.add(c.id)
+    const preserved = preservedFieldsById.get(c.id)
+    merged.push(preserved ? { ...c, ...preserved } : c)
+  }
+  // 保留本轮没再检出的既有候选（窗口滑动会让老簇暂时落选，但用户的拒绝记录不该随之
+  // 消失——否则老簇重新进窗口时又会被当成全新候选来问）。
+  for (const c of existing) {
+    if (!detectedIds.has(c.id)) merged.push(c)
+  }
+
+  const overflow = merged.length - MAX_CANDIDATES
+  return overflow > 0 ? merged.slice(overflow) : merged
+}
+
+/** 落盘。失败静默（R4）——下次抽取会重算重写。 */
+export async function saveCandidates(
+  storage: CandidateStorage,
+  record: CandidateRecord,
+): Promise<boolean> {
+  try {
+    await storage.save(CANDIDATE_RECORD_ID, { items: record.items })
+    return true
+  } catch {
+    return false
+  }
+}

package/dist/bundled-extensions/plugin-skill-inductor/src/episode-store.ts

@@ -0,0 +1,122 @@
+/**
+ * episode-store.ts —— RFC-318 M2：episode 持久化与治理。
+ *
+ * **治理内建（R6）**：上限 + FIFO 淘汰从第一天就在，而不是等集合膨胀后补救——RFC-284
+ * 的直接教训（lesson 集合无界增长到 154 条 / 每轮 49k tokens 才回头做淘汰治理）。
+ *
+ * **不直接碰文件系统**：只经 `PluginScopedStorageShape` 契约。service worker 的写面已被
+ * execArgv 收窄到自己的 plugin-state 目录（R7），绕过契约自己 `fs.writeFile` 既违反
+ * 隔离语义、也会在写面外直接失败。
+ */
+
+import type { Episode } from './episode'
+
+/** storage 记录 id（单条记录承载全部 episode + 游标）。 */
+export const EPISODE_RECORD_ID = 'episodes'
+
+/** episode 集合上限——超出即 FIFO 丢弃最旧的。 */
+export const MAX_EPISODES = 200
+
+/**
+ * 游标表上限（审核发现的第二个无界增长点）。
+ *
+ * 每个见过的会话都会留下一条游标，只增不减——长期运行会攒出数千条目。上限设 500：
+ * 远大于任何真实的"仍在活跃"会话数，被淘汰的必然是早已结束的老会话，代价仅是"万一
+ * 它复活，重抽一小段轨迹"（无数据损坏，且立刻被 MIN_MESSAGES 门挡住多数情况）。
+ *
+ * 为什么不做"按会话是否存活清理"：插件侧没有会话生命周期视图（宿主也没给这个能力，
+ * 也不该给——那是能力面的扩张）。纯本地的容量上限是这里唯一诚实的治理手段。
+ */
+export const MAX_CURSORS = 500
+
+/** 存储契约的最小结构（只依赖用到的两个方法，不绑定完整 SDK 类型）。 */
+export interface EpisodeStorage {
+  save(id: string, data: Record<string, unknown>): Promise<void>
+  load(id: string): Promise<Record<string, unknown> | null>
+}
+
+export interface EpisodeRecord {
+  items: Episode[]
+  /**
+   * 每个会话下次该从哪个消息下标继续读（避免重复抽取同一段）。
+   *
+   * **有界（R6）**：见 `MAX_CURSORS`——按插入顺序 FIFO 淘汰。JS 对象保持字符串键的插入
+   * 顺序，故"最先记录的会话"就是最旧的。
+   */
+  cursor: Record<string, number>
+}
+
+function emptyRecord(): EpisodeRecord {
+  return { items: [], cursor: {} }
+}
+
+/**
+ * 读取记录。**任何异常/脏数据都退化为空记录**（R4）——存储损坏不该让服务崩溃，
+ * 大不了从头攒。
+ */
+export async function loadRecord(storage: EpisodeStorage): Promise<EpisodeRecord> {
+  let raw: Record<string, unknown> | null
+  try {
+    raw = await storage.load(EPISODE_RECORD_ID)
+  } catch {
+    return emptyRecord()
+  }
+  if (!raw) return emptyRecord()
+  const items = Array.isArray(raw['items']) ? (raw['items'] as Episode[]) : []
+  const cursorRaw = raw['cursor']
+  const cursor: Record<string, number> = {}
+  if (cursorRaw && typeof cursorRaw === 'object' && !Array.isArray(cursorRaw)) {
+    for (const [k, v] of Object.entries(cursorRaw as Record<string, unknown>)) {
+      if (typeof v === 'number' && Number.isFinite(v) && v >= 0) cursor[k] = v
+    }
+  }
+  return { items, cursor }
+}
+
+/**
+ * 追加一条 episode 并应用治理上限。纯函数（不落盘）——便于单测直接验治理语义。
+ *
+ * FIFO 而非 LRU：episode 的价值随时间衰减（老的执行路径可能已因代码演进失效），
+ * 且"最近做过的同类任务"正是 M3 想聚的簇——按时间保留天然对齐检测窗口。
+ */
+export function appendEpisode(record: EpisodeRecord, episode: Episode): EpisodeRecord {
+  const items = [...record.items, episode]
+  const overflow = items.length - MAX_EPISODES
+  return {
+    items: overflow > 0 ? items.slice(overflow) : items,
+    cursor: record.cursor,
+  }
+}
+
+/**
+ * 更新某会话的读取游标，并应用游标表上限（FIFO）。
+ *
+ * 更新既有会话时**先删后插**，使其回到插入序末尾——否则一个长期活跃的会话会因为"最早
+ * 被记录"而在扩容淘汰时被误删，导致它反复重抽（正好淘汰掉最不该淘汰的那个）。
+ */
+export function advanceCursor(
+  record: EpisodeRecord,
+  sessionId: string,
+  nextIndex: number,
+): EpisodeRecord {
+  const cursor: Record<string, number> = { ...record.cursor }
+  delete cursor[sessionId]
+  cursor[sessionId] = nextIndex
+
+  const keys = Object.keys(cursor)
+  if (keys.length > MAX_CURSORS) {
+    for (const stale of keys.slice(0, keys.length - MAX_CURSORS)) delete cursor[stale]
+  }
+  return { items: record.items, cursor }
+}
+
+/** 落盘。失败静默（R4）——调用方已在内存里推进了状态，下次 notify 会重试。 */
+export async function saveRecord(storage: EpisodeStorage, record: EpisodeRecord): Promise<boolean> {
+  try {
+    // storage.save 只接受对象，故 items 数组包在记录对象里（契约约束，非设计偏好）。
+    await storage.save(EPISODE_RECORD_ID, { items: record.items, cursor: record.cursor })
+    return true
+  } catch {
+    return false
+  }
+}