From b483d8fef24a808d20409d9518e3e9aa70deac3b Mon Sep 17 00:00:00 2001 From: _Kerman Date: Tue, 28 Jul 2026 10:28:25 +0800 Subject: [PATCH] docs: sync compaction inspection contracts --- docs/core-data-structures/compaction.i18n.yaml | 4 ++-- docs/core-data-structures/compaction.md | 6 ++++-- docs/core-data-structures/compaction.zh.md | 6 ++++-- docs/persistence-catalog.md | 8 ++++++-- packages/cordis/tool-cordis/src/api-catalog.ts | 2 +- 5 files changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/core-data-structures/compaction.i18n.yaml b/docs/core-data-structures/compaction.i18n.yaml index 94b6bd4c5d..09dedca673 100644 --- a/docs/core-data-structures/compaction.i18n.yaml +++ b/docs/core-data-structures/compaction.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/core-data-structures/compaction.md -compaction.md: 3ba5edd96c509e064ac7033b175b7ddd3c972452 -compaction.zh.md: d082b0d0545802500278e96ca41a273bce275f53 +compaction.md: d3db21fb84cb82a4ba3bb8c16731b0e9f04c160a +compaction.zh.md: e96fff729b7a2d6375e6b471ee343a59f0f75a07 diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md index 3ba5edd96c..d3db21fb84 100644 --- a/docs/core-data-structures/compaction.md +++ b/docs/core-data-structures/compaction.md @@ -13,7 +13,7 @@ Compaction extends [`SessionEventMap`](session.md) with three event types via de | Event | Payload | Role | |---|---|---| | `compact/start` | `{ turn }` | acquires the log-recorded lock | -| `compact/summary` | `{ summary, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens? }` | provenance: the summary blocks, the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note) | +| `compact/summary` | `{ summary, rawOutput?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance: the safe summary projection, optional complete provider output and usage, the shadowed surface-boundary pair (`start`/`end` seqs — a position span, not a numeric interval), the shadowed seqs in surface order, the estimated token count, and the summarize call's envelope (`provider`, `model`, plus its generation cap when one applied) — logged so the one-shot request is reconstructable from log + code (the reconstructability Agent Note) | | `compact/end` | `{ turn, error? }` | releases the lock (`error` set when summarization threw) | The lock brackets the **whole** operation: `compact/start` is appended first, then summarization, the `compact/summary` provenance record, and the `user/message` replacement all land, and only then `compact/end`. Releasing the lock last turns a crash mid-operation into a detectable orphaned lock (a `compact/start` with no matching `compact/end`) rather than a `compact/end` that falsely claims compaction finished. @@ -22,7 +22,7 @@ These variants are merged inside a `declare module '@deepseek-ai/dsh-session'` b ## `CompactionResult` -What a successful compaction returns to its caller: the bookkeeping-event seqs, raw summary, shadowed range and seqs, and estimated token count. +What a successful compaction returns to its caller: the bookkeeping-event seqs, safe summary projection, optional complete provider output, shadowed range and seqs, and estimated token count. ```ts type-equiv /** Result of a successful compaction operation. */ @@ -35,6 +35,8 @@ interface CompactionResult { endSeq: number /** The summary content blocks produced by the backend. */ summary: ContentBlock[] + /** Complete provider output before the backend's safe summary projection. */ + rawOutput?: ContentBlock[] /** * The surface-boundary pair that was shadowed: the seqs of the first * (`start`) and last (`end`) surface nodes of the replaced range. A diff --git a/docs/core-data-structures/compaction.zh.md b/docs/core-data-structures/compaction.zh.md index d082b0d054..e96fff729b 100644 --- a/docs/core-data-structures/compaction.zh.md +++ b/docs/core-data-structures/compaction.zh.md @@ -13,7 +13,7 @@ | 事件 | 载荷 | 作用 | |---|---|---| | `compact/start` | `{ turn }` | 获取日志记录的锁 | -| `compact/summary` | `{ summary, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens? }` | provenance：摘要块、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note） | +| `compact/summary` | `{ summary, rawOutput?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | provenance：安全摘要投影、可选的完整 provider 输出与 usage、被遮蔽的 surface 边界对（`start`/`end` seq——位置跨度，而非数值区间）、按 surface 顺序排列的被遮蔽 seq、估算 token 数，以及摘要调用的 envelope（`provider`、`model`，若有生成上限则还包括该上限）——写入日志后，该一次性请求可由日志 + 代码重建（见可重建性 Agent Note） | | `compact/end` | `{ turn, error? }` | 释放锁（摘要调用抛出异常时设置 `error`） | 锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。 @@ -22,7 +22,7 @@ ## `CompactionResult` -成功压缩向调用方返回：记账事件 seq、原始摘要、被遮蔽的范围与 seq，以及估算 token 数。 +成功压缩向调用方返回：记账事件 seq、安全摘要投影、可选的完整 provider 输出、被遮蔽的范围与 seq，以及估算 token 数。 ```ts type-equiv /** Result of a successful compaction operation. */ @@ -35,6 +35,8 @@ interface CompactionResult { endSeq: number /** The summary content blocks produced by the backend. */ summary: ContentBlock[] + /** Complete provider output before the backend's safe summary projection. */ + rawOutput?: ContentBlock[] /** * The surface-boundary pair that was shadowed: the seqs of the first * (`start`) and last (`end`) surface nodes of the replaced range. A diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index f4d7357572..8dec7dbc19 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -177,7 +177,7 @@ Source: [`packages/core/session/src/types.ts:222`](../packages/core/session/src/ 'compact/end': { turn: number; error?: string } ``` -Source: [`packages/compact/compact/src/types.ts:40`](../packages/compact/compact/src/types.ts) +Source: [`packages/compact/compact/src/types.ts:44`](../packages/compact/compact/src/types.ts) #### `compact/start` — log-only @@ -199,6 +199,8 @@ Source: [`packages/compact/compact/src/types.ts:15`](../packages/compact/compact */ 'compact/summary': { summary: ContentBlock[] + /** Complete provider output before the backend's safe summary projection. */ + rawOutput?: ContentBlock[] shadowedRange: { start: number; end: number } shadowedSeqs: number[] shadowedTokenCount: number @@ -213,10 +215,12 @@ Source: [`packages/compact/compact/src/types.ts:15`](../packages/compact/compact model: string /** The generation cap the summarize call sent, when one applied. */ maxTokens?: number + /** Provider-reported token usage for the summarization request, when emitted. */ + usage?: TokenUsage } ``` -Types: [ContentBlock](core-data-structures/core.md) +Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md) Source: [`packages/compact/compact/src/types.ts:22`](../packages/compact/compact/src/types.ts) diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index e3f81aa527..b9c6bd305b 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -1539,7 +1539,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'CompactionResult', - declaration: 'export interface CompactionResult {\n startSeq: number;\n summarySeq: number;\n endSeq: number;\n summary: ContentBlock[];\n shadowedRange: {\n start: number;\n end: number;\n };\n shadowedSeqs: number[];\n shadowedTokenCount: number;\n}', + declaration: 'export interface CompactionResult {\n startSeq: number;\n summarySeq: number;\n endSeq: number;\n summary: ContentBlock[];\n rawOutput?: ContentBlock[];\n shadowedRange: {\n start: number;\n end: number;\n };\n shadowedSeqs: number[];\n shadowedTokenCount: number;\n}', }, { name: 'CompactionTrigger',