compressed-context 0.1.0 → 0.2.0

package/src/compression/events.ts

@@ -1,275 +1,275 @@
-import type { Plugin } from "@opencode/plugin"
-
-import { cacheHistoryKey } from "../shared/cache.ts"
-import { forEachScannedEntry } from "../shared/scan.ts"
-import { clearActiveSummary } from "./active-summary-cache.ts"
-import { recordCacheHistory } from "./cache-history.ts"
-import { deleteSessionTempFiles } from "./decompress.ts"
-import { markSessionDeleted } from "./deleted-sessions.ts"
-import { blockMarker } from "./render.ts"
-import { deleteTranscriptsForSession } from "./transcript-store.ts"
-import {
-  STATE_PREFIX,
-  commitPending,
-  dropPending,
-  loadState,
-  parseState,
-  retryPending,
-  saveState,
-  stateKey,
-  type State,
-} from "./state.ts"
-
-/** 输入：服务端上下文 + sessionID + 块 id；输出：最新 compaction 是否包含该块。 */
-export async function hasBlockInLatestCompaction(
-  ctx: Plugin.Context,
-  sessionID: string,
-  blockId: string,
-): Promise<boolean> {
-  try {
-    const messages = await ctx.session.context({ sessionID })
-    const latest = messages.find((message) => message.type === "compaction" && message.status === "completed")
-    if (latest === undefined) return false
-    return latest.summary.includes(blockMarker(blockId))
-  } catch {
-    return false
-  }
-}
-
-/** 输入：状态；输出：pending 对账后的状态。 */
-async function reconcile(ctx: Plugin.Context, sessionID: string, state: State): Promise<State> {
-  if (!state.pending) return state
-  const found = await hasBlockInLatestCompaction(ctx, sessionID, state.pending.id)
-  return found ? commitPending(state) : dropPending(state, "pending compaction not found after restart")
-}
-
-export type CompactionEventType = "ended" | "failed"
-
-/** 摘要链仍超预算且没有任何合法合并候选时的终止提示。 */
-export const TERMINAL_MESSAGE =
-  "compression cannot reduce this context further: start a new session or use native compaction"
-
-/**
- * 输入：服务端上下文 + 事件类型 + sessionID + 事件自带错误（仅 failed 有）。
- * 输出：无。
- * 预期：只有最新 checkpoint 包含 pending marker 才转正；失败时保留 phase 让下一次请求重试，
- *       达到 MAX_COMPRESSION_ATTEMPTS 后清除 phase，记录真实原因。
- *       事件 error 优先于 state.lastError——钩子没跑过的失败（如 OpenCode 在钩子前判定
- *       「无可压缩内容」）state 里没有任何错误记录，只能从事件拿真实原因。
- */
-export async function handleCompactionEvent(
-  ctx: Plugin.Context,
-  type: CompactionEventType,
-  sessionID: string,
-  eventError?: string,
-): Promise<void> {
-  const state = await loadState(ctx.storage, sessionID)
-  if (type === "ended") {
-    if (!state.pending) {
-      await saveState(ctx.storage, sessionID, { ...state, attempts: 0 })
-      return
-    }
-    // 事件可能晚到：只有最新 checkpoint 确实包含这个 pending 才转正，
-    // 否则它属于下一层 compaction，留给下一次 ended。
-    if (await hasBlockInLatestCompaction(ctx, sessionID, state.pending.id)) {
-      await saveState(ctx.storage, sessionID, commitPending(state))
-    }
-    return
-  }
-
-  const detail = eventError ?? state.lastError ?? "compaction failed"
-  // 钩子从未运行的失败（state 里没有任何本层错误记录）且已排下一层 phase：
-  // 典型是历史里只剩 checkpoint，OpenCode 在钩子前就判定无可压缩内容。
-  // 这不是本层失败，保留 phase 等下一次带真实消息的压缩，不计 attempts。
-  if (eventError !== undefined && state.lastError === undefined && state.phase !== undefined) {
-    await saveState(ctx.storage, sessionID, { ...state, attempts: 0 })
-    return
-  }
-  // 本层失败：保留 phase，下一次请求由 auto 重新入队；达到上限后 retryPending 会清掉 phase。
-  if (state.phase !== undefined) {
-    await saveState(ctx.storage, sessionID, retryPending(state, detail))
-    return
-  }
-  // T1 没有下一层可重试：丢弃 pending，记录真实原因。
-  await saveState(ctx.storage, sessionID, dropPending(state, detail))
-}
-
-export interface SessionEventOptions {
-  readonly onSessionIdle?: (sessionID: string) => void
-  readonly onSessionDeleted?: (sessionID: string) => void
-  readonly onStepEnded?: (input: {
-    readonly sessionID: string
-    readonly messageID: string
-    readonly tokens: {
-      readonly input: number
-      readonly output: number
-      readonly reasoning: number
-      readonly cache: { readonly read: number; readonly write: number }
-    }
-  }) => void | Promise<void>
-}
-
-/**
- * 输入：插件上下文 + sessionID。
- * 输出：无。
- * 预期：先打墓碑阻止迟到写入，再删 state、cache history、transcript 与临时文件。
- */
-export async function forgetSession(ctx: Plugin.Context, sessionID: string): Promise<void> {
-  markSessionDeleted(sessionID)
-  clearActiveSummary(sessionID)
-  deleteSessionTempFiles(sessionID)
-  try {
-    await Promise.all([
-      ctx.storage.remove(stateKey(sessionID)),
-      ctx.storage.remove(cacheHistoryKey(sessionID)),
-      deleteTranscriptsForSession(ctx.storage, sessionID),
-    ])
-  } catch {
-    // best effort：删不掉也不影响当前进程
-  }
-}
-
-/** 输入：事件里未校验的 tokens 字段；输出：规范化后的 usage，形状不对时 undefined。 */
-function readStepTokens(raw: unknown): {
-  input: number
-  output: number
-  reasoning: number
-  cache: { read: number; write: number }
-} | undefined {
-  if (typeof raw !== "object" || raw === null) return undefined
-  const record = raw as Record<string, unknown>
-  const input = record["input"]
-  if (typeof input !== "number" || !Number.isFinite(input)) return undefined
-  const finite = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) ? value : 0)
-  const cache =
-    typeof record["cache"] === "object" && record["cache"] !== null
-      ? (record["cache"] as Record<string, unknown>)
-      : {}
-  return {
-    input,
-    output: finite(record["output"]),
-    reasoning: finite(record["reasoning"]),
-    cache: { read: finite(cache["read"]), write: finite(cache["write"]) },
-  }
-}
-
-/**
- * 输入：插件上下文 + 可选清理回调。
- * 输出：订阅会话事件并返回取消函数。
- * 预期：compaction 成功/失败对账 pending；usage.updated/idle 补写缓存历史；
- *       idle 清理内存；deleted 清理内存与 storage。
- */
-export function startSessionEvents(
-  ctx: Plugin.Context,
-  options: SessionEventOptions = {},
-): () => void {
-  const controller = new AbortController()
-  void (async () => {
-    try {
-      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
-        switch (event.type) {
-          case "session.step.ended": {
-            const data = event.data as {
-              sessionID: string
-              assistantMessageID?: string
-              tokens?: unknown
-            }
-            const tokens = readStepTokens(data.tokens)
-            if (tokens !== undefined && options.onStepEnded !== undefined) {
-              await options.onStepEnded({
-                sessionID: data.sessionID,
-                messageID: data.assistantMessageID ?? "",
-                tokens,
-              })
-            }
-            break
-          }
-          case "session.compaction.ended":
-          case "session.compaction.failed": {
-            const type: CompactionEventType =
-              event.type === "session.compaction.ended" ? "ended" : "failed"
-            const failure =
-              event.type === "session.compaction.failed"
-                ? ((event.data as { error?: { message?: string } }).error?.message ?? "compaction failed")
-                : undefined
-            await handleCompactionEvent(ctx, type, event.data.sessionID, failure)
-            break
-          }
-          case "session.usage.updated":
-          case "session.idle":
-            // session.idle 在新版本里已标记 deprecated，usage.updated 每个 step 都会发；
-            // 两个都接，谁先到都能补写（按 messageID 去重）。
-            await recordCacheHistory(ctx, event.data.sessionID)
-            if (event.type === "session.idle") options.onSessionIdle?.(event.data.sessionID)
-            break
-          case "session.deleted":
-            await forgetSession(ctx, event.data.sessionID)
-            options.onSessionDeleted?.(event.data.sessionID)
-            break
-        }
-      }
-    } catch {
-      // aborted or disconnected；下一次事件或启动对账会补上
-    }
-  })()
-  return () => {
-    controller.abort()
-  }
-}
-
-/** 输入：任意错误；输出：是否明确的“会话不存在”。 */
-function isSessionMissing(error: unknown): boolean {
-  if (typeof error !== "object" || error === null) {
-    return /not found|404/i.test(String(error))
-  }
-  const record = error as Record<string, unknown>
-  const status = record["status"] ?? record["statusCode"] ?? record["code"]
-  if (status === 404 || status === "404" || status === "not_found") return true
-  const message = typeof record["message"] === "string" ? record["message"] : ""
-  return /not found|404/i.test(message)
-}
-
-/**
- * 输入：服务端上下文 + 每个 state 条目的处理函数。
- * 输出：无。
- * 预期：按 100 条一页顺序遍历所有 state key；空 sessionID 跳过，处理函数串行 await。
- */
-async function forEachStateEntry(
-  ctx: Plugin.Context,
-  visit: (sessionID: string, value: unknown) => Promise<void>,
-): Promise<void> {
-  await forEachScannedEntry(ctx.storage, STATE_PREFIX, async (entry) => {
-    const sessionID = entry.key.slice(STATE_PREFIX.length)
-    if (sessionID.length === 0) return
-    await visit(sessionID, entry.value)
-  })
-}
-
-/**
- * 输入：服务端上下文。
- * 输出：无。
- * 预期：启动时只清理“明确不存在”会话的孤儿 state；瞬时错误不删数据。
- */
-async function cleanupOrphanStates(ctx: Plugin.Context): Promise<void> {
-  await forEachStateEntry(ctx, async (sessionID) => {
-    try {
-      await ctx.session.get({ sessionID })
-    } catch (error) {
-      if (isSessionMissing(error)) await forgetSession(ctx, sessionID)
-    }
-  })
-}
-
-/** 输入：服务端上下文；输出：无；预期：启动时对账所有 pending 状态并清理孤儿。 */
-export async function reconcileAll(ctx: Plugin.Context): Promise<void> {
-  try {
-    await cleanupOrphanStates(ctx)
-    await forEachStateEntry(ctx, async (sessionID, value) => {
-      const state = parseState(value)
-      if (!state.pending) return
-      await saveState(ctx.storage, sessionID, await reconcile(ctx, sessionID, state))
-    })
-  } catch {
-    // best effort
-  }
-}
+import type { Plugin } from "@opencode/plugin"
+
+import { cacheHistoryKey } from "../shared/cache.ts"
+import { forEachScannedEntry } from "../shared/scan.ts"
+import { clearActiveSummary } from "./active-summary-cache.ts"
+import { recordCacheHistory } from "./cache-history.ts"
+import { deleteSessionTempFiles } from "./decompress.ts"
+import { markSessionDeleted } from "./deleted-sessions.ts"
+import { blockMarker } from "./render.ts"
+import { deleteTranscriptsForSession } from "./transcript-store.ts"
+import {
+  STATE_PREFIX,
+  commitPending,
+  dropPending,
+  loadState,
+  parseState,
+  retryPending,
+  saveState,
+  stateKey,
+  type State,
+} from "./state.ts"
+
+/** 输入：服务端上下文 + sessionID + 块 id；输出：最新 compaction 是否包含该块。 */
+export async function hasBlockInLatestCompaction(
+  ctx: Plugin.Context,
+  sessionID: string,
+  blockId: string,
+): Promise<boolean> {
+  try {
+    const messages = await ctx.session.context({ sessionID })
+    const latest = messages.find((message) => message.type === "compaction" && message.status === "completed")
+    if (latest === undefined) return false
+    return latest.summary.includes(blockMarker(blockId))
+  } catch {
+    return false
+  }
+}
+
+/** 输入：状态；输出：pending 对账后的状态。 */
+async function reconcile(ctx: Plugin.Context, sessionID: string, state: State): Promise<State> {
+  if (!state.pending) return state
+  const found = await hasBlockInLatestCompaction(ctx, sessionID, state.pending.id)
+  return found ? commitPending(state) : dropPending(state, "pending compaction not found after restart")
+}
+
+export type CompactionEventType = "ended" | "failed"
+
+/** 摘要链仍超预算且没有任何合法合并候选时的终止提示。 */
+export const TERMINAL_MESSAGE =
+  "compression cannot reduce this context further: start a new session or use native compaction"
+
+/**
+ * 输入：服务端上下文 + 事件类型 + sessionID + 事件自带错误（仅 failed 有）。
+ * 输出：无。
+ * 预期：只有最新 checkpoint 包含 pending marker 才转正；失败时保留 phase 让下一次请求重试，
+ *       达到 MAX_COMPRESSION_ATTEMPTS 后清除 phase，记录真实原因。
+ *       事件 error 优先于 state.lastError——钩子没跑过的失败（如 OpenCode 在钩子前判定
+ *       「无可压缩内容」）state 里没有任何错误记录，只能从事件拿真实原因。
+ */
+export async function handleCompactionEvent(
+  ctx: Plugin.Context,
+  type: CompactionEventType,
+  sessionID: string,
+  eventError?: string,
+): Promise<void> {
+  const state = await loadState(ctx.storage, sessionID)
+  if (type === "ended") {
+    if (!state.pending) {
+      await saveState(ctx.storage, sessionID, { ...state, attempts: 0 })
+      return
+    }
+    // 事件可能晚到：只有最新 checkpoint 确实包含这个 pending 才转正，
+    // 否则它属于下一层 compaction，留给下一次 ended。
+    if (await hasBlockInLatestCompaction(ctx, sessionID, state.pending.id)) {
+      await saveState(ctx.storage, sessionID, commitPending(state))
+    }
+    return
+  }
+
+  const detail = eventError ?? state.lastError ?? "compaction failed"
+  // 钩子从未运行的失败（state 里没有任何本层错误记录）且已排下一层 phase：
+  // 典型是历史里只剩 checkpoint，OpenCode 在钩子前就判定无可压缩内容。
+  // 这不是本层失败，保留 phase 等下一次带真实消息的压缩，不计 attempts。
+  if (eventError !== undefined && state.lastError === undefined && state.phase !== undefined) {
+    await saveState(ctx.storage, sessionID, { ...state, attempts: 0 })
+    return
+  }
+  // 本层失败：保留 phase，下一次请求由 auto 重新入队；达到上限后 retryPending 会清掉 phase。
+  if (state.phase !== undefined) {
+    await saveState(ctx.storage, sessionID, retryPending(state, detail))
+    return
+  }
+  // T1 没有下一层可重试：丢弃 pending，记录真实原因。
+  await saveState(ctx.storage, sessionID, dropPending(state, detail))
+}
+
+export interface SessionEventOptions {
+  readonly onSessionIdle?: (sessionID: string) => void
+  readonly onSessionDeleted?: (sessionID: string) => void
+  readonly onStepEnded?: (input: {
+    readonly sessionID: string
+    readonly messageID: string
+    readonly tokens: {
+      readonly input: number
+      readonly output: number
+      readonly reasoning: number
+      readonly cache: { readonly read: number; readonly write: number }
+    }
+  }) => void | Promise<void>
+}
+
+/**
+ * 输入：插件上下文 + sessionID。
+ * 输出：无。
+ * 预期：先打墓碑阻止迟到写入，再删 state、cache history、transcript 与临时文件。
+ */
+export async function forgetSession(ctx: Plugin.Context, sessionID: string): Promise<void> {
+  markSessionDeleted(sessionID)
+  clearActiveSummary(sessionID)
+  deleteSessionTempFiles(sessionID)
+  try {
+    await Promise.all([
+      ctx.storage.remove(stateKey(sessionID)),
+      ctx.storage.remove(cacheHistoryKey(sessionID)),
+      deleteTranscriptsForSession(ctx.storage, sessionID),
+    ])
+  } catch {
+    // best effort：删不掉也不影响当前进程
+  }
+}
+
+/** 输入：事件里未校验的 tokens 字段；输出：规范化后的 usage，形状不对时 undefined。 */
+function readStepTokens(raw: unknown): {
+  input: number
+  output: number
+  reasoning: number
+  cache: { read: number; write: number }
+} | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined
+  const record = raw as Record<string, unknown>
+  const input = record["input"]
+  if (typeof input !== "number" || !Number.isFinite(input)) return undefined
+  const finite = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) ? value : 0)
+  const cache =
+    typeof record["cache"] === "object" && record["cache"] !== null
+      ? (record["cache"] as Record<string, unknown>)
+      : {}
+  return {
+    input,
+    output: finite(record["output"]),
+    reasoning: finite(record["reasoning"]),
+    cache: { read: finite(cache["read"]), write: finite(cache["write"]) },
+  }
+}
+
+/**
+ * 输入：插件上下文 + 可选清理回调。
+ * 输出：订阅会话事件并返回取消函数。
+ * 预期：compaction 成功/失败对账 pending；usage.updated/idle 补写缓存历史；
+ *       idle 清理内存；deleted 清理内存与 storage。
+ */
+export function startSessionEvents(
+  ctx: Plugin.Context,
+  options: SessionEventOptions = {},
+): () => void {
+  const controller = new AbortController()
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        switch (event.type) {
+          case "session.step.ended": {
+            const data = event.data as {
+              sessionID: string
+              assistantMessageID?: string
+              tokens?: unknown
+            }
+            const tokens = readStepTokens(data.tokens)
+            if (tokens !== undefined && options.onStepEnded !== undefined) {
+              await options.onStepEnded({
+                sessionID: data.sessionID,
+                messageID: data.assistantMessageID ?? "",
+                tokens,
+              })
+            }
+            break
+          }
+          case "session.compaction.ended":
+          case "session.compaction.failed": {
+            const type: CompactionEventType =
+              event.type === "session.compaction.ended" ? "ended" : "failed"
+            const failure =
+              event.type === "session.compaction.failed"
+                ? ((event.data as { error?: { message?: string } }).error?.message ?? "compaction failed")
+                : undefined
+            await handleCompactionEvent(ctx, type, event.data.sessionID, failure)
+            break
+          }
+          case "session.usage.updated":
+          case "session.idle":
+            // session.idle 在新版本里已标记 deprecated，usage.updated 每个 step 都会发；
+            // 两个都接，谁先到都能补写（按 messageID 去重）。
+            await recordCacheHistory(ctx, event.data.sessionID)
+            if (event.type === "session.idle") options.onSessionIdle?.(event.data.sessionID)
+            break
+          case "session.deleted":
+            await forgetSession(ctx, event.data.sessionID)
+            options.onSessionDeleted?.(event.data.sessionID)
+            break
+        }
+      }
+    } catch {
+      // aborted or disconnected；下一次事件或启动对账会补上
+    }
+  })()
+  return () => {
+    controller.abort()
+  }
+}
+
+/** 输入：任意错误；输出：是否明确的“会话不存在”。 */
+function isSessionMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) {
+    return /not found|404/i.test(String(error))
+  }
+  const record = error as Record<string, unknown>
+  const status = record["status"] ?? record["statusCode"] ?? record["code"]
+  if (status === 404 || status === "404" || status === "not_found") return true
+  const message = typeof record["message"] === "string" ? record["message"] : ""
+  return /not found|404/i.test(message)
+}
+
+/**
+ * 输入：服务端上下文 + 每个 state 条目的处理函数。
+ * 输出：无。
+ * 预期：按 100 条一页顺序遍历所有 state key；空 sessionID 跳过，处理函数串行 await。
+ */
+async function forEachStateEntry(
+  ctx: Plugin.Context,
+  visit: (sessionID: string, value: unknown) => Promise<void>,
+): Promise<void> {
+  await forEachScannedEntry(ctx.storage, STATE_PREFIX, async (entry) => {
+    const sessionID = entry.key.slice(STATE_PREFIX.length)
+    if (sessionID.length === 0) return
+    await visit(sessionID, entry.value)
+  })
+}
+
+/**
+ * 输入：服务端上下文。
+ * 输出：无。
+ * 预期：启动时只清理“明确不存在”会话的孤儿 state；瞬时错误不删数据。
+ */
+async function cleanupOrphanStates(ctx: Plugin.Context): Promise<void> {
+  await forEachStateEntry(ctx, async (sessionID) => {
+    try {
+      await ctx.session.get({ sessionID })
+    } catch (error) {
+      if (isSessionMissing(error)) await forgetSession(ctx, sessionID)
+    }
+  })
+}
+
+/** 输入：服务端上下文；输出：无；预期：启动时对账所有 pending 状态并清理孤儿。 */
+export async function reconcileAll(ctx: Plugin.Context): Promise<void> {
+  try {
+    await cleanupOrphanStates(ctx)
+    await forEachStateEntry(ctx, async (sessionID, value) => {
+      const state = parseState(value)
+      if (!state.pending) return
+      await saveState(ctx.storage, sessionID, await reconcile(ctx, sessionID, state))
+    })
+  } catch {
+    // best effort
+  }
+}

package/src/compression/markdown.ts

@@ -1,53 +1,53 @@
-import type { MarkdownSummary } from "./schema.ts"
-
-const HEADING_RE = /^#{1,6}\s+(.+)$/m
-const BULLET_RE = /^[\u2022\-*]\s+/
-
-/** 输入：文本 + 上限；输出：截断后的文本。 */
-function clamp(text: string, max: number): string {
-  return text.length <= max ? text : text.slice(0, max).trimEnd()
-}
-
-/**
- * 输入：Markdown 正文。
- * 输出：块标题；预期：第一个标题 > 第一个非空行 > untitled，去 bullet，最多 60 字符。
- */
-export function deriveMarkdownTitle(text: string): string {
-  const heading = HEADING_RE.exec(text)
-  const source = heading !== null ? heading[1] ?? "" : (text.split("\n").find((line) => line.trim().length > 0) ?? "")
-  const cleaned = source.trim().replace(BULLET_RE, "")
-  return cleaned.length === 0 ? "untitled" : clamp(cleaned, 60)
-}
-
-/**
- * 输入：Markdown 正文。
- * 输出：用于候选描述的短目标；预期：标题后的第一个非空非标题行，最多 160 字符。
- */
-export function markdownGoal(text: string): string {
-  const lines = text.split("\n").map((line) => line.trim())
-  const headingIndex = lines.findIndex((line) => HEADING_RE.test(line))
-  const start = headingIndex >= 0 ? headingIndex + 1 : 0
-  const first = lines.slice(start).find((line) => line.length > 0 && !HEADING_RE.test(line))
-  const cleaned = (first ?? deriveMarkdownTitle(text)).replace(BULLET_RE, "")
-  return clamp(cleaned, 160)
-}
-
-/** 输入：文本；输出：去掉 markdown 代码围栏后的正文。 */
-function cleanMarkdown(text: string): string {
-  return text
-    .trim()
-    .replace(/^```(?:markdown|md)?\s*/i, "")
-    .replace(/\s*```$/, "")
-    .trim()
-}
-
-/** 输入：Markdown 正文 + 可选标题；输出：规范 Markdown 摘要。 */
-export function toMarkdownSummary(text: string, title?: string): MarkdownSummary {
-  const body = cleanMarkdown(text)
-  const explicit = title?.trim() ?? ""
-  return {
-    format: "markdown",
-    title: explicit.length > 0 ? clamp(explicit, 80) : deriveMarkdownTitle(body),
-    text: body,
-  }
-}
+import type { MarkdownSummary } from "./schema.ts"
+
+const HEADING_RE = /^#{1,6}\s+(.+)$/m
+const BULLET_RE = /^[\u2022\-*]\s+/
+
+/** 输入：文本 + 上限；输出：截断后的文本。 */
+function clamp(text: string, max: number): string {
+  return text.length <= max ? text : text.slice(0, max).trimEnd()
+}
+
+/**
+ * 输入：Markdown 正文。
+ * 输出：块标题；预期：第一个标题 > 第一个非空行 > untitled，去 bullet，最多 60 字符。
+ */
+export function deriveMarkdownTitle(text: string): string {
+  const heading = HEADING_RE.exec(text)
+  const source = heading !== null ? heading[1] ?? "" : (text.split("\n").find((line) => line.trim().length > 0) ?? "")
+  const cleaned = source.trim().replace(BULLET_RE, "")
+  return cleaned.length === 0 ? "untitled" : clamp(cleaned, 60)
+}
+
+/**
+ * 输入：Markdown 正文。
+ * 输出：用于候选描述的短目标；预期：标题后的第一个非空非标题行，最多 160 字符。
+ */
+export function markdownGoal(text: string): string {
+  const lines = text.split("\n").map((line) => line.trim())
+  const headingIndex = lines.findIndex((line) => HEADING_RE.test(line))
+  const start = headingIndex >= 0 ? headingIndex + 1 : 0
+  const first = lines.slice(start).find((line) => line.length > 0 && !HEADING_RE.test(line))
+  const cleaned = (first ?? deriveMarkdownTitle(text)).replace(BULLET_RE, "")
+  return clamp(cleaned, 160)
+}
+
+/** 输入：文本；输出：去掉 markdown 代码围栏后的正文。 */
+function cleanMarkdown(text: string): string {
+  return text
+    .trim()
+    .replace(/^```(?:markdown|md)?\s*/i, "")
+    .replace(/\s*```$/, "")
+    .trim()
+}
+
+/** 输入：Markdown 正文 + 可选标题；输出：规范 Markdown 摘要。 */
+export function toMarkdownSummary(text: string, title?: string): MarkdownSummary {
+  const body = cleanMarkdown(text)
+  const explicit = title?.trim() ?? ""
+  return {
+    format: "markdown",
+    title: explicit.length > 0 ? clamp(explicit, 80) : deriveMarkdownTitle(body),
+    text: body,
+  }
+}