compressed-context 0.1.0 → 0.2.0

package/src/compression/normalize.ts

@@ -1,114 +1,114 @@
-import { Schema } from "effect"
-
-import type { SummaryFormat } from "../shared/settings.ts"
-import { toBabelSummary } from "./babel.ts"
-import { toMarkdownSummary } from "./markdown.ts"
-import { SummaryFields, type Summary } from "./schema.ts"
-
-/** 输入：任意模型字段；输出：字符串数组；预期：字符串包成单元素数组，其他丢弃。 */
-export function stringArray(value: unknown): string[] {
-  if (Array.isArray(value)) {
-    return value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
-  }
-  if (typeof value === "string" && value.trim().length > 0) return [value]
-  return []
-}
-
-/**
- * 输入：模型返回的原始 JSON 对象。
- * 输出：补齐缺失可选字段后的对象。
- * 预期：真实模型常漏 progress/files 或把数组写成字符串；只补空值，不编造内容。
- */
-export function normalizeSummary(value: unknown): unknown {
-  if (typeof value !== "object" || value === null) return value
-  const record = value as Record<string, unknown>
-  const goal = typeof record["goal"] === "string" ? record["goal"] : ""
-  const title = (
-    typeof record["title"] === "string" && record["title"].trim().length > 0
-      ? record["title"]
-      : goal.trim() || "untitled"
-  ).slice(0, 80)
-  const progress =
-    typeof record["progress"] === "object" && record["progress"] !== null
-      ? (record["progress"] as Record<string, unknown>)
-      : {}
-  return {
-    ...record,
-    title,
-    goal,
-    constraints: stringArray(record["constraints"]),
-    decisions: stringArray(record["decisions"]),
-    progress: {
-      completed: stringArray(progress["completed"]),
-      active: stringArray(progress["active"]),
-      blocked: stringArray(progress["blocked"]),
-    },
-    open_items: stringArray(record["open_items"]),
-    files: stringArray(record["files"]),
-    facts: stringArray(record["facts"]),
-  }
-}
-
-/** 输入：模型返回的 Markdown 载体；输出：正文；预期：支持 string / markdown / text / summary。 */
-function markdownText(value: unknown): string | undefined {
-  if (typeof value === "string") return value
-  if (typeof value !== "object" || value === null) return undefined
-  const record = value as Record<string, unknown>
-  for (const key of ["markdown", "text", "summary", "content"]) {
-    const text = record[key]
-    if (typeof text === "string") return text
-  }
-  return undefined
-}
-
-/** 输入：模型返回的 Markdown 载体；输出：可选标题。 */
-function markdownTitle(value: unknown): string | undefined {
-  if (typeof value !== "object" || value === null) return undefined
-  const record = value as Record<string, unknown>
-  const title = record["title"] ?? record["topic"]
-  return typeof title === "string" ? title : undefined
-}
-
-/** 输入：Babel 载体；输出：正文文本和可选 title/goal。 */
-function babelParts(
-  value: unknown,
-): { readonly text: string; readonly title?: string; readonly goal?: string } | undefined {
-  if (typeof value === "string") return { text: value }
-  if (typeof value !== "object" || value === null) return undefined
-  const record = value as Record<string, unknown>
-  for (const key of ["babel", "markdown", "text", "summary", "content"]) {
-    const text = record[key]
-    if (typeof text !== "string") continue
-    const title = typeof record["title"] === "string" ? record["title"] : undefined
-    const goal = typeof record["goal"] === "string" ? record["goal"] : undefined
-    return {
-      text,
-      ...(title === undefined ? {} : { title }),
-      ...(goal === undefined ? {} : { goal }),
-    }
-  }
-  return undefined
-}
-
-/**
- * 输入：模型返回的原始值 + 摘要格式。
- * 输出：规范摘要；形状不合法时返回 undefined。
- * 预期：Markdown 直接保留原文；JSON 先补齐可选字段再由 SummaryFields 解码。
- */
-export function toSummary(value: unknown, format: SummaryFormat = "markdown"): Summary | undefined {
-  if (format === "babel") {
-    const parts = babelParts(value)
-    if (parts === undefined) return undefined
-    return toBabelSummary(parts.text, parts.title, parts.goal)
-  }
-  if (format === "markdown") {
-    const text = markdownText(value)
-    if (text !== undefined) return toMarkdownSummary(text, markdownTitle(value))
-    // Markdown 模式下仍收到 JSON 字段时回退到结构化解析，避免工具调用直接失败。
-  }
-  try {
-    return Schema.decodeUnknownSync(SummaryFields)(normalizeSummary(value))
-  } catch {
-    return undefined
-  }
-}
+import { Schema } from "effect"
+
+import type { SummaryFormat } from "../shared/settings.ts"
+import { toBabelSummary } from "./babel.ts"
+import { toMarkdownSummary } from "./markdown.ts"
+import { SummaryFields, type Summary } from "./schema.ts"
+
+/** 输入：任意模型字段；输出：字符串数组；预期：字符串包成单元素数组，其他丢弃。 */
+export function stringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+  }
+  if (typeof value === "string" && value.trim().length > 0) return [value]
+  return []
+}
+
+/**
+ * 输入：模型返回的原始 JSON 对象。
+ * 输出：补齐缺失可选字段后的对象。
+ * 预期：真实模型常漏 progress/files 或把数组写成字符串；只补空值，不编造内容。
+ */
+export function normalizeSummary(value: unknown): unknown {
+  if (typeof value !== "object" || value === null) return value
+  const record = value as Record<string, unknown>
+  const goal = typeof record["goal"] === "string" ? record["goal"] : ""
+  const title = (
+    typeof record["title"] === "string" && record["title"].trim().length > 0
+      ? record["title"]
+      : goal.trim() || "untitled"
+  ).slice(0, 80)
+  const progress =
+    typeof record["progress"] === "object" && record["progress"] !== null
+      ? (record["progress"] as Record<string, unknown>)
+      : {}
+  return {
+    ...record,
+    title,
+    goal,
+    constraints: stringArray(record["constraints"]),
+    decisions: stringArray(record["decisions"]),
+    progress: {
+      completed: stringArray(progress["completed"]),
+      active: stringArray(progress["active"]),
+      blocked: stringArray(progress["blocked"]),
+    },
+    open_items: stringArray(record["open_items"]),
+    files: stringArray(record["files"]),
+    facts: stringArray(record["facts"]),
+  }
+}
+
+/** 输入：模型返回的 Markdown 载体；输出：正文；预期：支持 string / markdown / text / summary。 */
+function markdownText(value: unknown): string | undefined {
+  if (typeof value === "string") return value
+  if (typeof value !== "object" || value === null) return undefined
+  const record = value as Record<string, unknown>
+  for (const key of ["markdown", "text", "summary", "content"]) {
+    const text = record[key]
+    if (typeof text === "string") return text
+  }
+  return undefined
+}
+
+/** 输入：模型返回的 Markdown 载体；输出：可选标题。 */
+function markdownTitle(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const record = value as Record<string, unknown>
+  const title = record["title"] ?? record["topic"]
+  return typeof title === "string" ? title : undefined
+}
+
+/** 输入：Babel 载体；输出：正文文本和可选 title/goal。 */
+function babelParts(
+  value: unknown,
+): { readonly text: string; readonly title?: string; readonly goal?: string } | undefined {
+  if (typeof value === "string") return { text: value }
+  if (typeof value !== "object" || value === null) return undefined
+  const record = value as Record<string, unknown>
+  for (const key of ["babel", "markdown", "text", "summary", "content"]) {
+    const text = record[key]
+    if (typeof text !== "string") continue
+    const title = typeof record["title"] === "string" ? record["title"] : undefined
+    const goal = typeof record["goal"] === "string" ? record["goal"] : undefined
+    return {
+      text,
+      ...(title === undefined ? {} : { title }),
+      ...(goal === undefined ? {} : { goal }),
+    }
+  }
+  return undefined
+}
+
+/**
+ * 输入：模型返回的原始值 + 摘要格式。
+ * 输出：规范摘要；形状不合法时返回 undefined。
+ * 预期：Markdown 直接保留原文；JSON 先补齐可选字段再由 SummaryFields 解码。
+ */
+export function toSummary(value: unknown, format: SummaryFormat = "markdown"): Summary | undefined {
+  if (format === "babel") {
+    const parts = babelParts(value)
+    if (parts === undefined) return undefined
+    return toBabelSummary(parts.text, parts.title, parts.goal)
+  }
+  if (format === "markdown") {
+    const text = markdownText(value)
+    if (text !== undefined) return toMarkdownSummary(text, markdownTitle(value))
+    // Markdown 模式下仍收到 JSON 字段时回退到结构化解析，避免工具调用直接失败。
+  }
+  try {
+    return Schema.decodeUnknownSync(SummaryFields)(normalizeSummary(value))
+  } catch {
+    return undefined
+  }
+}

package/src/compression/render.ts

@@ -1,70 +1,70 @@
-import type { Block } from "./state.ts"
-import type { Summary } from "./schema.ts"
-import { summaryBody, summaryTitle } from "./summary.ts"
-import { formatTimestamp } from "../shared/format.ts"
-import { countText } from "../shared/tokens.ts"
-
-/** 输入：块 id；输出：块头标记；预期：用于渲染和对账。 */
-export function blockMarker(id: string): string {
-  return `[Compressed conversation section #${id}]`
-}
-
-/** 块头附加信息开关；默认都不显示，避免多占 token。 */
-export interface RenderOptions {
-  readonly showTimeline?: boolean
-  readonly showBlockTokens?: boolean
-}
-
-/** 输入：结构化字段；输出：Markdown 摘要正文。 */
-export function renderSummary(summary: Summary): string {
-  return summaryBody(summary)
-}
-
-/**
- * 输入：一个块 + 可选渲染开关。
- * 输出：带块头、层级/合并关系、可选时间与 token 估算的完整文本。
- * 预期：marker 前缀保持原样，对账逻辑只依赖 `blockMarker(id)`。
- */
-export function renderBlock(block: Block, options: RenderOptions = {}): string {
-  const body = renderSummary(block.summary)
-  const meta: string[] = [`T${block.tier.toString()}`]
-  if (block.sourceBlockIds !== undefined && block.sourceBlockIds.length > 0) {
-    meta.push(`merged ${block.sourceBlockIds.map((id) => `#${id}`).join(" + ")}`)
-  }
-  if (options.showBlockTokens === true) {
-    meta.push(`≈${countText(body).toString()} tok`)
-  }
-  if (options.showTimeline === true) {
-    meta.push(formatTimestamp(block.at))
-  }
-  const title = summaryTitle(block.summary).trim()
-  const header = `${blockMarker(block.id)} [${meta.join(" · ")}]${title ? ` ${title}` : ""}`
-  return `${header}\n\n${body}`
-}
-
-/**
- * 输入：已落盘块 + 可选 pending 块 + 渲染开关。
- * 输出：active 顶层块，按 order 排序。
- * 预期：被任何块 sourceBlockIds 引用的块不显示；合并块占据第一个源块的位置。
- */
-export function activeBlocks(blocks: readonly Block[], pending?: Block): readonly Block[] {
-  const all = pending === undefined ? blocks : [...blocks, pending]
-  const consumed = new Set<string>()
-  for (const block of all) {
-    for (const sourceId of block.sourceBlockIds ?? []) consumed.add(sourceId)
-  }
-  return all
-    .filter((block) => !consumed.has(block.id))
-    .sort((a, b) => a.order - b.order || a.at - b.at || a.id.localeCompare(b.id))
-}
-
-/** 输入：块 + 可选 pending + 渲染开关；输出：拼接后的 checkpoint 文本。 */
-export function renderAll(
-  blocks: readonly Block[],
-  pending?: Block,
-  options: RenderOptions = {},
-): string {
-  return activeBlocks(blocks, pending)
-    .map((block) => renderBlock(block, options))
-    .join("\n\n")
-}
+import type { Block } from "./state.ts"
+import type { Summary } from "./schema.ts"
+import { summaryBody, summaryTitle } from "./summary.ts"
+import { formatTimestamp } from "../shared/format.ts"
+import { countText } from "../shared/tokens.ts"
+
+/** 输入：块 id；输出：块头标记；预期：用于渲染和对账。 */
+export function blockMarker(id: string): string {
+  return `[Compressed conversation section #${id}]`
+}
+
+/** 块头附加信息开关；默认都不显示，避免多占 token。 */
+export interface RenderOptions {
+  readonly showTimeline?: boolean
+  readonly showBlockTokens?: boolean
+}
+
+/** 输入：结构化字段；输出：Markdown 摘要正文。 */
+export function renderSummary(summary: Summary): string {
+  return summaryBody(summary)
+}
+
+/**
+ * 输入：一个块 + 可选渲染开关。
+ * 输出：带块头、层级/合并关系、可选时间与 token 估算的完整文本。
+ * 预期：marker 前缀保持原样，对账逻辑只依赖 `blockMarker(id)`。
+ */
+export function renderBlock(block: Block, options: RenderOptions = {}): string {
+  const body = renderSummary(block.summary)
+  const meta: string[] = [`T${block.tier.toString()}`]
+  if (block.sourceBlockIds !== undefined && block.sourceBlockIds.length > 0) {
+    meta.push(`merged ${block.sourceBlockIds.map((id) => `#${id}`).join(" + ")}`)
+  }
+  if (options.showBlockTokens === true) {
+    meta.push(`≈${countText(body).toString()} tok`)
+  }
+  if (options.showTimeline === true) {
+    meta.push(formatTimestamp(block.at))
+  }
+  const title = summaryTitle(block.summary).trim()
+  const header = `${blockMarker(block.id)} [${meta.join(" · ")}]${title ? ` ${title}` : ""}`
+  return `${header}\n\n${body}`
+}
+
+/**
+ * 输入：已落盘块 + 可选 pending 块 + 渲染开关。
+ * 输出：active 顶层块，按 order 排序。
+ * 预期：被任何块 sourceBlockIds 引用的块不显示；合并块占据第一个源块的位置。
+ */
+export function activeBlocks(blocks: readonly Block[], pending?: Block): readonly Block[] {
+  const all = pending === undefined ? blocks : [...blocks, pending]
+  const consumed = new Set<string>()
+  for (const block of all) {
+    for (const sourceId of block.sourceBlockIds ?? []) consumed.add(sourceId)
+  }
+  return all
+    .filter((block) => !consumed.has(block.id))
+    .sort((a, b) => a.order - b.order || a.at - b.at || a.id.localeCompare(b.id))
+}
+
+/** 输入：块 + 可选 pending + 渲染开关；输出：拼接后的 checkpoint 文本。 */
+export function renderAll(
+  blocks: readonly Block[],
+  pending?: Block,
+  options: RenderOptions = {},
+): string {
+  return activeBlocks(blocks, pending)
+    .map((block) => renderBlock(block, options))
+    .join("\n\n")
+}

package/src/compression/schema.ts

@@ -1,84 +1,131 @@
-import { Schema } from "effect"
-
-/**
- * 摘要的规范 JSON 形状：写入存储、渲染、校验都用这一份，所有字段必填。
- *
- * 模型侧输入用 SummaryInput：JSON 模式只要求 goal，Markdown 模式要求 markdown；
- * 进入内部前由 normalize 补齐，避免逼模型编造内容。
- */
-export const SummaryFields = Schema.Struct({
-  title: Schema.String,
-  goal: Schema.String,
-  constraints: Schema.Array(Schema.String),
-  decisions: Schema.Array(Schema.String),
-  progress: Schema.Struct({
-    completed: Schema.Array(Schema.String),
-    active: Schema.Array(Schema.String),
-    blocked: Schema.Array(Schema.String),
-  }),
-  open_items: Schema.Array(Schema.String),
-  files: Schema.Array(Schema.String),
-  facts: Schema.Array(Schema.String),
-})
-
-export type SummaryFields = Schema.Schema.Type<typeof SummaryFields>
-
-/** Markdown 摘要：正文是唯一权威内容，title 只是派生元数据。 */
-export interface MarkdownSummary {
-  readonly format: "markdown"
-  readonly title: string
-  readonly text: string
-}
-
-/**
- * Babel 摘要：正文是模型间高密度文本，title/goal 从首行 `T=...|G=...` 解析。
- * text 保留首行，方便 T2/T3 合并时继续看到目标。
- */
-export interface BabelSummary {
-  readonly format: "babel"
-  readonly title: string
-  readonly goal: string
-  readonly text: string
-}
-
-/** 块摘要：JSON 保持原形状，Markdown/Babel 用 format 标记；旧 JSON 块天然兼容。 */
-export type Summary = SummaryFields | MarkdownSummary | BabelSummary
-
-/** 输入：任意摘要；输出：是否 Markdown 摘要。 */
-export function isMarkdownSummary(summary: Summary): summary is MarkdownSummary {
-  return "format" in summary && summary.format === "markdown"
-}
-
-/** 输入：任意摘要；输出：是否 Babel 摘要。 */
-export function isBabelSummary(summary: Summary): summary is BabelSummary {
-  return "format" in summary && summary.format === "babel"
-}
-
-/**
- * 模型侧摘要输入：JSON 字段都可选，Markdown 用 markdown 字段。
- *
- * 预期：JSON 模式在归一化时要求 goal；Markdown 模式要求 markdown。
- */
-export const SummaryInput = Schema.Struct({
-  format: Schema.optional(
-    Schema.Union([Schema.Literal("json"), Schema.Literal("markdown"), Schema.Literal("babel")]),
-  ),
-  markdown: Schema.optional(Schema.String),
-  babel: Schema.optional(Schema.String),
-  title: Schema.optional(Schema.String),
-  goal: Schema.optional(Schema.String),
-  constraints: Schema.optional(Schema.Array(Schema.String)),
-  decisions: Schema.optional(Schema.Array(Schema.String)),
-  progress: Schema.optional(
-    Schema.Struct({
-      completed: Schema.optional(Schema.Array(Schema.String)),
-      active: Schema.optional(Schema.Array(Schema.String)),
-      blocked: Schema.optional(Schema.Array(Schema.String)),
-    }),
-  ),
-  open_items: Schema.optional(Schema.Array(Schema.String)),
-  files: Schema.optional(Schema.Array(Schema.String)),
-  facts: Schema.optional(Schema.Array(Schema.String)),
-})
-
-export type SummaryInput = Schema.Schema.Type<typeof SummaryInput>
+import { Schema } from "effect"
+
+import type { SummaryFormat } from "../shared/settings.ts"
+
+/**
+ * 摘要的规范 JSON 形状：写入存储、渲染、校验都用这一份，所有字段必填。
+ *
+ * 模型侧输入用 SummaryInput：JSON 模式只要求 goal，Markdown 模式要求 markdown；
+ * 进入内部前由 normalize 补齐，避免逼模型编造内容。
+ */
+export const SummaryFields = Schema.Struct({
+  title: Schema.String,
+  goal: Schema.String,
+  constraints: Schema.Array(Schema.String),
+  decisions: Schema.Array(Schema.String),
+  progress: Schema.Struct({
+    completed: Schema.Array(Schema.String),
+    active: Schema.Array(Schema.String),
+    blocked: Schema.Array(Schema.String),
+  }),
+  open_items: Schema.Array(Schema.String),
+  files: Schema.Array(Schema.String),
+  facts: Schema.Array(Schema.String),
+})
+
+export type SummaryFields = Schema.Schema.Type<typeof SummaryFields>
+
+/** Markdown 摘要：正文是唯一权威内容，title 只是派生元数据。 */
+export interface MarkdownSummary {
+  readonly format: "markdown"
+  readonly title: string
+  readonly text: string
+}
+
+/**
+ * Babel 摘要：正文是模型间高密度文本，title/goal 从首行 `T=...|G=...` 解析。
+ * text 保留首行，方便 T2/T3 合并时继续看到目标。
+ */
+export interface BabelSummary {
+  readonly format: "babel"
+  readonly title: string
+  readonly goal: string
+  readonly text: string
+}
+
+/** 块摘要：JSON 保持原形状，Markdown/Babel 用 format 标记；旧 JSON 块天然兼容。 */
+export type Summary = SummaryFields | MarkdownSummary | BabelSummary
+
+/** 输入：任意摘要；输出：是否 Markdown 摘要。 */
+export function isMarkdownSummary(summary: Summary): summary is MarkdownSummary {
+  return "format" in summary && summary.format === "markdown"
+}
+
+/** 输入：任意摘要；输出：是否 Babel 摘要。 */
+export function isBabelSummary(summary: Summary): summary is BabelSummary {
+  return "format" in summary && summary.format === "babel"
+}
+
+/**
+ * 模型侧摘要输入：JSON 字段都可选，Markdown 用 markdown 字段。
+ *
+ * 预期：JSON 模式在归一化时要求 goal；Markdown 模式要求 markdown。
+ */
+export const SummaryInput = Schema.Struct({
+  format: Schema.optional(
+    Schema.Union([Schema.Literal("json"), Schema.Literal("markdown"), Schema.Literal("babel")]),
+  ),
+  markdown: Schema.optional(Schema.String),
+  babel: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  goal: Schema.optional(Schema.String),
+  constraints: Schema.optional(Schema.Array(Schema.String)),
+  decisions: Schema.optional(Schema.Array(Schema.String)),
+  progress: Schema.optional(
+    Schema.Struct({
+      completed: Schema.optional(Schema.Array(Schema.String)),
+      active: Schema.optional(Schema.Array(Schema.String)),
+      blocked: Schema.optional(Schema.Array(Schema.String)),
+    }),
+  ),
+  open_items: Schema.optional(Schema.Array(Schema.String)),
+  files: Schema.optional(Schema.Array(Schema.String)),
+  facts: Schema.optional(Schema.Array(Schema.String)),
+})
+
+export type SummaryInput = Schema.Schema.Type<typeof SummaryInput>
+
+/**
+ * JSON 模式的模型输入：goal 必填，其余可选。
+ *
+ * 与 SummaryInput 的差别只有 goal：JSON 模式没有 goal 就没有内容可写。
+ */
+export const JsonSummaryInput = Schema.Struct({
+  goal: Schema.String,
+  title: Schema.optional(Schema.String),
+  constraints: Schema.optional(Schema.Array(Schema.String)),
+  decisions: Schema.optional(Schema.Array(Schema.String)),
+  progress: Schema.optional(
+    Schema.Struct({
+      completed: Schema.optional(Schema.Array(Schema.String)),
+      active: Schema.optional(Schema.Array(Schema.String)),
+      blocked: Schema.optional(Schema.Array(Schema.String)),
+    }),
+  ),
+  open_items: Schema.optional(Schema.Array(Schema.String)),
+  files: Schema.optional(Schema.Array(Schema.String)),
+  facts: Schema.optional(Schema.Array(Schema.String)),
+})
+
+/** Markdown 模式的模型输入：正文必填；title 可选，传了就省掉从首行提取。 */
+export const MarkdownSummaryInput = Schema.Struct({
+  markdown: Schema.String,
+  title: Schema.optional(Schema.String),
+})
+
+/** Babel 模式的模型输入：正文必填；title 可选，目标从首行 `G=` 解析。 */
+export const BabelSummaryInput = Schema.Struct({
+  babel: Schema.String,
+  title: Schema.optional(Schema.String),
+})
+
+/**
+ * 输入：摘要格式。
+ * 输出：该格式的模型输入 schema，只保留这个格式用得上的字段。
+ * 预期：切换格式后工具参数真的收窄，模型不会按旧习惯传别的字段。
+ */
+export function summaryInputFor(format: SummaryFormat) {
+  if (format === "markdown") return MarkdownSummaryInput
+  if (format === "babel") return BabelSummaryInput
+  return JsonSummaryInput
+}