Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync compaction inspection contracts

Browse Source
This commit is contained in:
_Kerman
2026-07-28 10:28:25 +08:00
parent 92081094ae
commit b483d8fef2
5 changed files with 17 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/core-data-structures/compaction.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/core-data-structures/compaction.md # pnpm run verify-translation-pairing --write docs/core-data-structures/compaction.md
compaction.md: 3ba5edd96c509e064ac7033b175b7ddd3c972452 compaction.md: d3db21fb84cb82a4ba3bb8c16731b0e9f04c160a
compaction.zh.md: d082b0d0545802500278e96ca41a273bce275f53 compaction.zh.md: e96fff729b7a2d6375e6b471ee343a59f0f75a07

6
docs/core-data-structures/compaction.md
View File

@@ -13,7 +13,7 @@ Compaction extends [`SessionEventMap`](session.md) with three event types via de
| Event | Payload | Role | | Event | Payload | Role |
|---|---|---| |---|---|---|
| `compact/start` | `{ turn }` | acquires the log-recorded lock | | `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) | | `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. 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` ## `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 ```ts type-equiv
/** Result of a successful compaction operation. */ /** Result of a successful compaction operation. */
@@ -35,6 +35,8 @@ interface CompactionResult {
endSeq: number endSeq: number
/** The summary content blocks produced by the backend. */ /** The summary content blocks produced by the backend. */
summary: ContentBlock[] 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 * The surface-boundary pair that was shadowed: the seqs of the first
* (`start`) and last (`end`) surface nodes of the replaced range. A * (`start`) and last (`end`) surface nodes of the replaced range. A

6
docs/core-data-structures/compaction.zh.md
View File

@@ -13,7 +13,7 @@
| 事件 | 载荷 | 作用 | | 事件 | 载荷 | 作用 |
|---|---|---| |---|---|---|
| `compact/start` | `{ turn }` | 获取日志记录的锁 | | `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/end` | `{ turn, error? }` | 释放锁（摘要调用抛出异常时设置 `error`） |
锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。 锁括住**整个**操作：先追加 `compact/start`，然后执行摘要生成、写入 `compact/summary` 来源记录与 `user/message` 替换，最后才追加 `compact/end`。最后释放锁意味着操作中途崩溃会表现为可检测的遗留锁（有 `compact/start` 而无匹配的 `compact/end`），而非一个虚假声称压缩已完成的 `compact/end`。
@@ -22,7 +22,7 @@
## `CompactionResult` ## `CompactionResult`
成功压缩向调用方返回：记账事件 seq、原始摘要、被遮蔽的范围与 seq，以及估算 token 数。 成功压缩向调用方返回：记账事件 seq、安全摘要投影、可选的完整 provider 输出、被遮蔽的范围与 seq，以及估算 token 数。
```ts type-equiv ```ts type-equiv
/** Result of a successful compaction operation. */ /** Result of a successful compaction operation. */
@@ -35,6 +35,8 @@ interface CompactionResult {
endSeq: number endSeq: number
/** The summary content blocks produced by the backend. */ /** The summary content blocks produced by the backend. */
summary: ContentBlock[] 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 * The surface-boundary pair that was shadowed: the seqs of the first
* (`start`) and last (`end`) surface nodes of the replaced range. A * (`start`) and last (`end`) surface nodes of the replaced range. A

8
docs/persistence-catalog.md
View File

@@ -177,7 +177,7 @@ Source: [`packages/core/session/src/types.ts:222`](../packages/core/session/src/
'compact/end': { turn: number; error?: string } '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 #### `compact/start` — log-only
@@ -199,6 +199,8 @@ Source: [`packages/compact/compact/src/types.ts:15`](../packages/compact/compact
*/ */
'compact/summary': { 'compact/summary': {
summary: ContentBlock[] summary: ContentBlock[]
/** Complete provider output before the backend's safe summary projection. */
rawOutput?: ContentBlock[]
shadowedRange: { start: number; end: number } shadowedRange: { start: number; end: number }
shadowedSeqs: number[] shadowedSeqs: number[]
shadowedTokenCount: number shadowedTokenCount: number
@@ -213,10 +215,12 @@ Source: [`packages/compact/compact/src/types.ts:15`](../packages/compact/compact
model: string model: string
/** The generation cap the summarize call sent, when one applied. */ /** The generation cap the summarize call sent, when one applied. */
maxTokens?: number 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) Source: [`packages/compact/compact/src/types.ts:22`](../packages/compact/compact/src/types.ts)

2
packages/cordis/tool-cordis/src/api-catalog.ts
View File

@@ -1539,7 +1539,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
}, },
{ {
name: 'CompactionResult', 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', name: 'CompactionTrigger',