@x-otto/cli 0.0.1-alpha.0

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

@@ -0,0 +1,125 @@
+/**
+ * episode.ts —— RFC-318 M2：episode 数据模型与解析规整。
+ *
+ * **episode ≠ lesson**：lesson 是陈述性知识（"这个坑要绕开"，RFC-036 已有管线），episode 是
+ * **程序性**知识——"这类任务是按什么顺序做成的"。两者数据面物理隔离（RFC-318 D1/D3），
+ * episode 只被归纳器离线消费，默认不进 prompt。
+ */
+
+/** 一条解决路径上的单步：工具名 + 一句话意图。 */
+export interface EpisodeStep {
+  /** 工具名。来自 `readTranscript` 投影保留的 `toolName`（M1 grill 定案的下游消费点）。 */
+  tool: string
+  /** 这一步在做什么（供 M4 生成 SKILL.md 时还原可读流程）。 */
+  intent: string
+}
+
+export interface Episode {
+  /**
+   * 任务签名——归一化的任务描述，M3 相似检测的一级匹配键。
+   * 要求"去掉具体标识符后仍能表达任务类型"（如"给某个包新增一个受控能力"而非"给
+   * plugin 包加 readTranscript"），否则同类任务永远聚不成簇。
+   */
+  taskSignature: string
+  /** 检索标签（小写）。 */
+  tags: string[]
+  /** 有序执行步骤——**这是 episode 的核心价值**，缺了它就退化成一条 lesson。 */
+  steps: EpisodeStep[]
+  /**
+   * 结果判定。只有 `success` 的轨迹值得归纳成 skill（Voyager 先例：技能入库前需验证成功）；
+   * `partial`/`failure` 仍然存档——M3 可用它们做反面信号，且丢弃会让"这条路走不通"的
+   * 知识永久流失。
+   */
+  outcome: 'success' | 'partial' | 'failure'
+  sessionId: string
+  /** 抽取时刻（epoch ms）。 */
+  at: number
+}
+
+/** 字段上限（R6 治理内建：创建即带约束，不等膨胀后补救）。 */
+export const MAX_SIGNATURE_CHARS = 200
+export const MAX_INTENT_CHARS = 120
+export const MAX_STEPS = 20
+export const MAX_TAGS = 5
+
+const OUTCOMES = new Set(['success', 'partial', 'failure'])
+
+function clamp(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max) : text
+}
+
+function normalizeSteps(raw: unknown): EpisodeStep[] {
+  if (!Array.isArray(raw)) return []
+  const steps: EpisodeStep[] = []
+  for (const item of raw) {
+    if (steps.length >= MAX_STEPS) break
+    const s = item as { tool?: unknown; intent?: unknown }
+    const tool = typeof s?.tool === 'string' ? s.tool.trim() : ''
+    if (!tool) continue // 无工具名的步骤对路径骨架无价值，丢弃
+    const intent = typeof s?.intent === 'string' ? s.intent.trim() : ''
+    steps.push({ tool: clamp(tool, MAX_INTENT_CHARS), intent: clamp(intent, MAX_INTENT_CHARS) })
+  }
+  return steps
+}
+
+function normalizeTags(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return []
+  const tags: string[] = []
+  for (const item of raw) {
+    if (tags.length >= MAX_TAGS) break
+    if (typeof item !== 'string') continue
+    const tag = item.trim().toLowerCase()
+    if (tag && !tags.includes(tag)) tags.push(tag)
+  }
+  return tags
+}
+
+/**
+ * 把模型输出解析成 `Episode`。
+ *
+ * **fail-closed（R4）**：非 JSON / 不是对象 / 显式 `null` / 缺关键字段 / 无有效步骤 →
+ * 一律返回 `null`，**绝不抛**。抽取是尽力而为的旁路观测，任何异常都不该冒泡成服务崩溃。
+ *
+ * 为什么"无有效步骤即丢弃"：没有执行路径的 episode 退化成一条描述性文本，对 M3 的路径
+ * 相似检测零贡献，只会占治理配额、稀释真实信号。
+ */
+export function parseEpisode(raw: string, sessionId: string, now: number): Episode | null {
+  let data: unknown
+  try {
+    data = JSON.parse(extractJsonBlock(raw))
+  } catch {
+    return null
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return null
+
+  const obj = data as Record<string, unknown>
+  const taskSignature = typeof obj['taskSignature'] === 'string' ? obj['taskSignature'].trim() : ''
+  if (!taskSignature) return null
+
+  const steps = normalizeSteps(obj['steps'])
+  if (steps.length === 0) return null
+
+  const outcomeRaw = typeof obj['outcome'] === 'string' ? obj['outcome'] : ''
+  const outcome = OUTCOMES.has(outcomeRaw) ? (outcomeRaw as Episode['outcome']) : 'partial'
+
+  return {
+    taskSignature: clamp(taskSignature, MAX_SIGNATURE_CHARS),
+    tags: normalizeTags(obj['tags']),
+    steps,
+    outcome,
+    sessionId,
+    at: now,
+  }
+}
+
+/**
+ * 从模型输出里取 JSON 主体——模型常把 JSON 包在 ```json 围栏里或前后加解释文字。
+ * 取第一个 `{` 到最后一个 `}`；不做更复杂的解析（失败自然落到 parse 的 fail-closed）。
+ */
+function extractJsonBlock(raw: string): string {
+  const trimmed = raw.trim()
+  const start = trimmed.indexOf('{')
+  const end = trimmed.lastIndexOf('}')
+  if (start === -1 || end === -1 || end <= start) return trimmed
+  return trimmed.slice(start, end + 1)
+}

package/dist/bundled-extensions/plugin-skill-inductor/src/extraction-prompt.ts

@@ -0,0 +1,97 @@
+/**
+ * extraction-prompt.ts —— RFC-318 M2：episode 抽取的策略面。
+ *
+ * **这个文件是"可被自迭代回路改进的策略"的落点**（RFC-318 §2 目标 5）：归纳质量不好时，
+ * 回路可以对本文件提改进 diff，走与人类相同的审查流水线。故 prompt 独立成文件而非内联
+ * 进 service——让"改策略"是一次小而清晰的 diff，不是在流程代码里找字符串。
+ *
+ * 设计要点（信噪比是本 RFC 最大风险，第一道闸在这里）——结构经 M2 审核后重排：
+ * 1. **放弃条件前置**：先列"什么时候输出 null"再给 JSON schema。原版把 schema 放前面，
+ *    会把模型强 prime 成"我要产出 JSON"，后置的 null 分支敌不过这个先入印象——闲聊型
+ *    会话会被硬凑成 episode（审核指出的高危项）。
+ * 2. **判据可操作**："worth remembering" 这类形容词在不同模型/温度下判定漂移很大，换成
+ *    可数的门槛（≥2 个工具步骤 + 有明确结局）。
+ * 3. **few-shot 优于指令**：给一正一反两个完整示例。让模型看见"该输出 null 的样子"，
+ *    比多写三行禁令有效得多。
+ * 4. **taskSignature 去具体化说清楚"替换什么"**：列出要泛化的标识符类别（包名/函数名/
+ *    文件路径/变量名），而不是只给一对 good/bad——单个例子容易被模型学成"换个词"。
+ */
+
+export const EPISODE_EXTRACTION_PROMPT = `You are a trajectory analyst for an AI coding assistant. Read the session transcript below and extract the reusable SOLUTION PATH — the ordered tool steps — of the task that was carried out, so that similar future tasks can follow the same route.
+
+## STEP 1 — Decide whether to extract anything at all
+
+Output exactly \`null\` (nothing else, no JSON) if ANY of these is true:
+
+1. No task was carried out — the session is chat, Q&A, explanation, or planning only.
+2. Fewer than 2 real tool calls appear in the transcript.
+3. The work is still in progress — no success, failure, or abandonment is visible yet.
+4. The path is trivial: a single lookup answered directly (e.g. read one file → answer), with no decision-making, no iteration, no repair.
+
+Be strict here. Most sessions deserve \`null\`. A wrong \`null\` costs nothing; a fabricated episode pollutes the skill library permanently.
+
+## STEP 2 — Only if none of the above applies, output ONE JSON object
+
+{
+  "taskSignature": string,   // The TASK TYPE, with every specific identifier generalized away.
+                             // Replace package names, file paths, function names, variable names,
+                             // and product names with their CATEGORY or ROLE.
+                             // It must describe a class of tasks, not this one instance.
+  "tags": string[],          // 1-5 lowercase keywords for retrieval
+  "steps": [                 // The real tool sequence, in order
+    { "tool": string,        // Tool name EXACTLY as it appears in the transcript — never invent one
+      "intent": string }     // One short phrase: what this step accomplished
+  ],
+  "outcome": "success" | "partial" | "failure"
+}
+
+Rules for steps:
+- Every step MUST correspond to a real tool call visible in the transcript. Do NOT invent, merge unrelated calls, or idealize the path into what "should" have been done.
+- Collapse trivial repetition: five consecutive reads of different files become one "read" step describing the group.
+- Drop abandoned detours that had no effect on the outcome.
+
+## Examples
+
+### Example A — a real task (extract)
+
+Transcript: user asks to add a rate limit to an API endpoint. Assistant greps for the middleware registry, reads the existing throttle helper, edits the route to apply it, runs the test suite, sees one failure, fixes the config, reruns — green.
+
+Output:
+{
+  "taskSignature": "apply an existing cross-cutting middleware to a specific API route and get the suite green",
+  "tags": ["api", "middleware", "config"],
+  "steps": [
+    { "tool": "grep", "intent": "locate where middleware is registered" },
+    { "tool": "read", "intent": "study the existing helper's interface" },
+    { "tool": "edit", "intent": "apply the middleware to the target route" },
+    { "tool": "bash", "intent": "run the test suite, one failure surfaced" },
+    { "tool": "edit", "intent": "correct the configuration value" },
+    { "tool": "bash", "intent": "rerun — all green" }
+  ],
+  "outcome": "success"
+}
+
+Note how the signature says "an existing cross-cutting middleware" and "a specific API route" instead of naming the rate limiter or the route — that is what makes it match future tasks of the same shape.
+
+### Example B — not a task (do not extract)
+
+Transcript: user asks how the caching layer works. Assistant reads two files and explains the design. No changes made.
+
+Output:
+null
+
+## Output format
+
+Output ONLY the JSON object, or the bare word \`null\`. No prose, no code fences, no explanation.`
+
+/** 把会话切片渲染成 transcript 文本。 */
+export function buildEpisodePrompt(
+  messages: readonly { role: string; text: string; toolName?: string }[],
+): string {
+  const lines = messages.map((m) => {
+    // 工具名单独标出——它是 steps[].tool 的唯一可信来源（模型不该从散文里猜工具名）。
+    const tag = m.toolName ? `${m.role}(${m.toolName})` : m.role
+    return `<${tag}>\n${m.text}\n</${tag}>`
+  })
+  return `${EPISODE_EXTRACTION_PROMPT}\n\n<transcript>\n${lines.join('\n')}\n</transcript>`
+}

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

@@ -0,0 +1,183 @@
+/**
+ * inductor-service.ts —— RFC-318 M2：归纳器 service 的主流程。
+ *
+ * 生命周期：宿主在会话空闲时经 `pool.notify` 推 `session.idle` 事件（RFC-318 D9），
+ * 本 service 据此读增量轨迹 → 抽 episode → 落 scoped storage。
+ *
+ * **fail-closed 且不阻塞（R4）**：全流程任何一步失败都只 warn 并返回。notify handler 抛出
+ * 异常会被 worker 上报为服务崩溃并触发退避重启——对"这次没抽出东西"这种常态而言，那是
+ * 完全错误的严重级别。
+ *
+ * **配额意识（R2）**：宿主侧对 `readTranscript`（每 notify 1 次）与 `complete`（每 notify
+ * 2 次）有硬配额。本 service 每次 notify 最多各调 1 次，天然在预算内——但绝不自造重试
+ * 循环去试探配额边界（那是把宿主强制当成可协商的）。
+ */
+
+import { parseEpisode } from './episode'
+import { buildEpisodePrompt } from './extraction-prompt'
+import { advanceCursor, appendEpisode, loadRecord, saveRecord } from './episode-store'
+import { detectCandidates } from './candidate-detector'
+import { loadCandidates, mergeCandidates, saveCandidates } from './candidate-store'
+
+import type { EpisodeStorage } from './episode-store'
+import type { CandidateStorage } from './candidate-store'
+import type { EpisodeRecord } from './episode-store'
+
+/**
+ * 少于这么多条新消息就不抽取——只推进游标。
+ * 对齐 RFC-036 `createMemoryAutoExtractHooks` 的 `minMessages: 6` 口径：太短的切片
+ * 抽不出有意义的路径，白烧一次模型调用。
+ *
+ * **这是缺省值**——宿主可经通知的 `options.minMessages` 覆盖（用户在 /preference 里调）。
+ * 插件读不到宿主 settings（隔离 worker，刻意不给这个能力），故走下发。
+ */
+export const MIN_MESSAGES_FOR_EXTRACTION = 6
+
+/** 阈值下限——低于 2 条消息无论如何抽不出路径，防止用户把它调成 0 后每次 idle 都烧模型。 */
+export const MIN_MESSAGES_FLOOR = 2
+
+/** 解析生效阈值：宿主下发优先，非法值（非数字/过小）回退缺省。 */
+export function resolveMinMessages(fromHost?: number): number {
+  if (typeof fromHost !== 'number' || !Number.isFinite(fromHost)) {
+    return MIN_MESSAGES_FOR_EXTRACTION
+  }
+  return Math.max(MIN_MESSAGES_FLOOR, Math.floor(fromHost))
+}
+
+/** 抽取调用的 token 上限——episode 是结构化短输出，比 lesson 抽取（2048）更省。 */
+export const EXTRACTION_MAX_TOKENS = 1_024
+
+/** service 运行所需的宿主能力（全部经 M1 的受控能力面注入，缺一即不工作）。 */
+export interface InductorHost {
+  readTranscript?: (input: { sessionId: string; sinceIndex?: number }) => Promise<{
+    messages: readonly { role: string; text: string; toolName?: string }[]
+    nextIndex: number
+  }>
+  complete?: (input: { prompt: string; maxTokens?: number }) => Promise<string>
+}
+
+export interface InductorDeps {
+  host?: InductorHost
+  /** episode 与 candidate 共用同一份 scoped storage（各占一条记录）。 */
+  storage?: EpisodeStorage & CandidateStorage
+  logger: { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
+  now?: () => number
+}
+
+export type InductionOutcome =
+  | 'missing-capability'
+  | 'in-flight'
+  | 'no-new-messages'
+  | 'too-short'
+  | 'no-episode'
+  | 'saved'
+  | 'error'
+
+/**
+ * 归纳器核心——与 service 生命周期解耦，便于单测直接驱动（注入假 host/storage）。
+ */
+export class SkillInductor {
+  /** 正在处理中的会话——同 session 的并发 notify 直接丢弃（下次 notify 会补上）。 */
+  private readonly inFlight = new Set<string>()
+
+  constructor(private readonly deps: InductorDeps) {}
+
+  private get now(): number {
+    return this.deps.now ? this.deps.now() : Date.now()
+  }
+
+  async onSessionIdle(sessionId: string, options?: { minMessages?: number }): Promise<InductionOutcome> {
+    const { host, storage, logger } = this.deps
+    // 能力自检：未授予时宿主注入的是 undefined（fail-closed 跨越 RPC 边界），不是会抛错的
+    // 假句柄——所以这里判存在性即可，不需要 try/catch 试探。
+    if (!host?.readTranscript || !host.complete || !storage) {
+      logger.warn(
+        'skill-inductor idle: required capabilities missing (needs session.read + llm.complete + storage), skipping',
+      )
+      return 'missing-capability'
+    }
+    if (this.inFlight.has(sessionId)) return 'in-flight'
+    this.inFlight.add(sessionId)
+    try {
+      return await this.run(
+        sessionId,
+        host.readTranscript,
+        host.complete,
+        storage,
+        resolveMinMessages(options?.minMessages),
+      )
+    } catch (err) {
+      // 兜底：任何未预期异常都收在这里，绝不冒泡到 notify handler（R4）。
+      logger.warn(`skill-inductor idle failed: ${err instanceof Error ? err.message : String(err)}`)
+      return 'error'
+    } finally {
+      this.inFlight.delete(sessionId)
+    }
+  }
+
+  private async run(
+    sessionId: string,
+    readTranscript: NonNullable<InductorHost['readTranscript']>,
+    complete: NonNullable<InductorHost['complete']>,
+    storage: EpisodeStorage & CandidateStorage,
+    minMessages: number,
+  ): Promise<InductionOutcome> {
+    const record = await loadRecord(storage)
+    const sinceIndex = record.cursor[sessionId] ?? 0
+
+    const { messages, nextIndex } = await readTranscript({ sessionId, sinceIndex })
+    if (messages.length === 0) {
+      // 游标仍要推进：nextIndex 可能因宿主侧的条数上限跳过了旧消息。
+      if (nextIndex !== sinceIndex) await saveRecord(storage, advanceCursor(record, sessionId, nextIndex))
+      return 'no-new-messages'
+    }
+    if (messages.length < minMessages) {
+      // **不推进游标**：切片太短是"还没攒够"，下次 notify 应该带上这些消息一起抽。
+      return 'too-short'
+    }
+
+    const raw = await complete({
+      prompt: buildEpisodePrompt(messages),
+      maxTokens: EXTRACTION_MAX_TOKENS,
+    })
+    const episode = parseEpisode(raw, sessionId, this.now)
+
+    // 抽不出 episode 也要推进游标——这一段已经判过"没有可归纳的路径"，重复抽只会
+    // 重复烧模型调用（信噪比与成本的直接权衡点）。
+    const advanced = advanceCursor(record, sessionId, nextIndex)
+    if (!episode) {
+      await saveRecord(storage, advanced)
+      return 'no-episode'
+    }
+    const withEpisode = appendEpisode(advanced, episode)
+    await saveRecord(storage, withEpisode)
+    this.deps.logger.info(`skill-inductor captured episode: ${episode.taskSignature}`)
+    // 只在真的新增了 episode 后才跑检测——没有新数据就不可能出新簇。
+    await this.refreshCandidates(storage, withEpisode)
+    return 'saved'
+  }
+
+  /**
+   * 重算候选并落盘（RFC-318 D-M3-5）。
+   *
+   * **失败静默**：这是 episode 抽取的下游附加动作，episode 已经安全落盘；检测出问题不该
+   * 反过来把主链路标记成失败（R4）。
+   */
+  private async refreshCandidates(
+    storage: EpisodeStorage & CandidateStorage,
+    record: EpisodeRecord,
+  ): Promise<void> {
+    try {
+      const detected = detectCandidates(record.items)
+      const existing = await loadCandidates(storage)
+      // 合并而非覆盖——既有候选的 dismissedAt 必须活下来（R9），否则每次抽取都会把
+      // 用户的拒绝抹掉，冷却形同虚设。
+      const items = mergeCandidates(existing.items, detected)
+      await saveCandidates(storage, { items })
+    } catch (err) {
+      this.deps.logger.warn(
+        `skill-inductor candidate detection failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * similarity.ts —— RFC-318 M3：episode 相似度（确定性，无 embedding）。
+ *
+ * **为什么不复用 core 的实现**：`@x-otto/memory` 里有同款 `jaccard`/`toWordSet`
+ * （operational-learning.ts:86,95），但它们未导出、且属 core 包——插件跑在独立编译产物 +
+ * 隔离 worker 里，不能依赖 core。故独立实现，**口径刻意对齐既有版本**（小写化、按非
+ * 字母数字切分、丢弃长度 ≤2 的词），避免同一概念在两处产生语义漂移。
+ *
+ * **为什么首版不用 embedding**（RFC-318 D4）：零新依赖、结果确定可复现（同样的 episode
+ * 集合永远聚出同样的簇——这是簇 id 稳定性的前提，见 candidate-detector），且 RFC-284 的
+ * 探针数据证明 Jaccard 在本仓这个数据规模上够用。召回不足再单独立项。
+ */
+
+import type { Episode } from './episode'
+
+/** taskSignature 相似度在总分里的权重（主信号）。 */
+export const SIGNATURE_WEIGHT = 0.8
+/** tags 交集在总分里的权重（修正信号）。 */
+export const TAG_WEIGHT = 0.2
+
+/**
+ * 文本 → 词集。丢弃长度 ≤2 的词：冠词/介词/短代码片段对主题判别几乎无贡献，
+ * 却会因为高频出现而抬高所有配对的分数（噪声地板）。
+ */
+export function toWordSet(text: string): Set<string> {
+  return new Set(
+    text
+      .toLowerCase()
+      .split(/[^\p{L}\p{N}]+/u)
+      .filter((w) => w.length > 2),
+  )
+}
+
+/** Jaccard 词集相似度 [0,1]。任一为空即 0（空集与任何集合"相似"是无意义的判定）。 */
+export function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 || b.size === 0) return 0
+  let intersection = 0
+  for (const w of a) {
+    if (b.has(w)) intersection++
+  }
+  return intersection / (a.size + b.size - intersection)
+}
+
+/**
+ * 两条 episode 的相似度 [0,1]——两级加权（RFC-318 D4）。
+ *
+ * 一级 `taskSignature` 词集 Jaccard 是主信号；二级 `tags` 交集只占 0.2：tags 由模型自由
+ * 生成、稳定性差（同类任务可能标 `plugin` 也可能标 `capability`），当主信号会引入噪音；
+ * 但它能救回"措辞完全不同、主题相同"的漏配，故保留小权重。
+ *
+ * **刻意不比对 steps 序列**：同一类任务的执行路径本就允许分支（那正是要归纳的东西），
+ * 拿它当聚簇条件会把同类任务拆散。steps 是簇成立后归纳 SKILL.md 的素材，不是聚簇依据。
+ */
+export function episodeSimilarity(a: Episode, b: Episode): number {
+  const signature = jaccard(toWordSet(a.taskSignature), toWordSet(b.taskSignature))
+  const tags = jaccard(new Set(a.tags), new Set(b.tags))
+  return SIGNATURE_WEIGHT * signature + TAG_WEIGHT * tags
+}