diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index 9a3accc299..c0cd08d5b7 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.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/persistence-catalog.md -persistence-catalog.md: ee210f58bdf633dad75894131e649eff45158453 -persistence-catalog.zh.md: 10fd5874529228a87baed64f4bfd5ac8743f5e62 +persistence-catalog.md: 3011a1ec612f0e77925793e07ab07a567eb78b40 +persistence-catalog.zh.md: c1ca737cf0e1eba772b14dd00c93121b25e1339c diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index ee210f58bd..3011a1ec61 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -477,7 +477,7 @@ Source: [`packages/compaction/compaction/src/types.ts:34`](../packages/compactio 'deliverables/presented': { turn: number; callId: ToolCallId; files: PresentedFile[] } ``` -Types: [ToolCallId](subsystems/core.md) +Types: [PresentedFile](subsystems/deliverables.md) · [ToolCallId](subsystems/core.md) Source: [`packages/deliverables/tool-present/src/types.ts:15`](../packages/deliverables/tool-present/src/types.ts) @@ -1252,6 +1252,8 @@ Source: [`packages/web/web-search-deepseek/src/provider.ts:82`](../packages/web/ 'workspace/changes': WorkspaceChangesData ``` +Types: [WorkspaceChangesData](subsystems/deliverables.md) + Source: [`packages/deliverables/workspace-changes/src/types.ts:36`](../packages/deliverables/workspace-changes/src/types.ts) ## Resolved persistence types diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index 10fd587452..c1ca737cf0 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -479,7 +479,7 @@ export type SessionEvent = { 'deliverables/presented': { turn: number; callId: ToolCallId; files: PresentedFile[] } ``` -类型：[ToolCallId](subsystems/core.zh.md) +类型：[PresentedFile](subsystems/deliverables.zh.md) · [ToolCallId](subsystems/core.zh.md) 来源：[`packages/deliverables/tool-present/src/types.ts:15`](../packages/deliverables/tool-present/src/types.ts) @@ -1254,6 +1254,8 @@ export type SessionEvent = { 'workspace/changes': WorkspaceChangesData ``` +类型：[WorkspaceChangesData](subsystems/deliverables.zh.md) + 来源：[`packages/deliverables/workspace-changes/src/types.ts:36`](../packages/deliverables/workspace-changes/src/types.ts) ## 已解析的持久化类型 diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml index 4605553c60..080eff9a15 100644 --- a/docs/subsystems/README.i18n.yaml +++ b/docs/subsystems/README.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/subsystems/README.md -README.md: 88b2c85c2a02c98c57c3dd9075cec7d7dcd5ea9f -README.zh.md: 5527ff47c951594a99d01498548f17e726c2c095 +README.md: de98afec0af29a068fe4dc939802f479373240d5 +README.zh.md: 362398a368737c8ac34001a6133976ab5a376034 diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md index 88b2c85c2a..de98afec0a 100644 --- a/docs/subsystems/README.md +++ b/docs/subsystems/README.md @@ -14,6 +14,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures | [goal.md](goal.md) | persisted goal identity, lifecycle snapshots, activation, change records, and round attribution | | [schedule.md](schedule.md) | Session-local reminder records, durable transitions, active views, and ordinary-conversation delivery | | [todo.md](todo.md) | the todo package's whole-list item type, durable event ownership, projection, and open-turn invariant | +| [deliverables.md](deliverables.md) | what a turn hands to the user: `PresentedFile` deliveries from `present` and the `WorkspaceChangesData` summary of changed files from git snapshots | | [commands.md](commands.md) | the human-command registry service: definitions, adapter discovery, direct invocation, results, and parsing views | | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnEndReason`, `deriveMessages()`, execution enclosure, and standalone events | | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, the JSONL provider, `session/flush`, crash recovery, `SessionHeader` | diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md index 5527ff47c9..362398a368 100644 --- a/docs/subsystems/README.zh.md +++ b/docs/subsystems/README.zh.md @@ -14,6 +14,7 @@ | [goal.md](goal.zh.md) | 持久 goal 标识、生命周期快照、激活、变更记录与 Round 归属 | | [schedule.md](schedule.zh.md) | 仅限会话内的提醒记录、持久转换、活动视图与普通对话交付 | | [todo.md](todo.zh.md) | todo 包的整列表条目类型、持久事件所有权、投影和未结束轮次不变式 | +| [deliverables.md](deliverables.zh.md) | 一轮交给用户的东西：`present` 声明的 `PresentedFile` 交付，以及由 git 快照得出的 `WorkspaceChangesData` 改动摘要 | | [commands.md](commands.zh.md) | 人类命令注册表服务：定义、适配器发现、直接调用、结果与解析视图 | | [session.md](session.zh.md) | 完整的 `SessionEventMap` 变体目录、`TurnEndReason`、`deriveMessages()`、执行封闭与独立事件 | | [persistence.md](persistence.zh.md) | 持久性 seam：`SessionPersistence`、JSONL 提供方、`session/flush`、崩溃恢复、`SessionHeader` | diff --git a/docs/subsystems/deliverables.i18n.yaml b/docs/subsystems/deliverables.i18n.yaml new file mode 100644 index 0000000000..9975a4c5d3 --- /dev/null +++ b/docs/subsystems/deliverables.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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/subsystems/deliverables.md +deliverables.md: f8e2b34d0f57537a8cc2e97331f1bf04525ddb4e +deliverables.zh.md: da8d7a93d282ab4a0bd02f5e5eadcd4a0f75703b diff --git a/docs/subsystems/deliverables.md b/docs/subsystems/deliverables.md new file mode 100644 index 0000000000..f8e2b34d0f --- /dev/null +++ b/docs/subsystems/deliverables.md @@ -0,0 +1,61 @@ +# Deliverables + +English | [中文](deliverables.zh.md) + +What a turn hands to the user, recorded as two log-only Session events owned by the [deliverables package group](../../packages/deliverables/README.md): the files the model declared through the `present` tool, and the files the turn changed, summarized from git working-tree snapshots taken at turn start and turn end. Only clients read the events; the Web [deliverables plugin](../../packages/client/ui-deliverables/README.md) renders both at the end of the turn. Tool behavior, snapshot mechanics, and configuration are on the package READMEs for [`tool-present`](../../packages/deliverables/tool-present/README.md) and [`workspace-changes`](../../packages/deliverables/workspace-changes/README.md). + +Sources: [`packages/deliverables/tool-present/src/types.ts`](../../packages/deliverables/tool-present/src/types.ts), [`packages/deliverables/workspace-changes/src/types.ts`](../../packages/deliverables/workspace-changes/src/types.ts) + +## `PresentedFile` — one declared delivery + +```ts type-equiv +/** A declared filesystem file whose current contents remain at its source path. */ +interface PresentedFile { + /** Original absolute path or path relative to the Session working directory. */ + path: string + /** Optional description supplied by the model. */ + description?: string +} +``` + +## `WorkspaceChangedFile` — one changed file + +```ts type-equiv +/** One file changed during a turn, with line counts from git or from the recorded file-tool hunks. */ +interface WorkspaceChangedFile { + /** Path relative to the Session working directory, or an absolute Host path outside it. */ + path: string + /** + * Sort key and label: the relative path inside the working directory, a + * `../` path for repository files above it, a `~` path under the home + * directory, otherwise the absolute path. Always slash-separated. + */ + display: string + /** Lines added; zero for a binary file. */ + added: number + /** Lines deleted; zero for a binary file. */ + deleted: number + /** Present when git reported the file as binary. */ + binary?: true +} +``` + +## `WorkspaceChangesData` — one turn's change summary + +```ts type-equiv +/** Files changed during one top-level turn. */ +interface WorkspaceChangesData { + /** The turn whose file changes this summary describes. */ + turn: number + /** Changed files in `display` order, capped at the plugin's `maxFiles`. */ + files: WorkspaceChangedFile[] + /** Complete changed-file count, including files omitted by the cap. */ + total: number + /** Git tree object ids of the turn-start and turn-end working-tree snapshots. */ + snapshot: { before: string; after: string } +} +``` + +## Durable events + +`tool-present` declaration-merges `deliverables/presented: { turn; callId; files: PresentedFile[] }` into `SessionEventMap`, appended once per successful final `present` result. `workspace-changes` merges `workspace/changes: WorkspaceChangesData`, appended when a top-level turn stops; a later event for the same turn replaces the earlier one, so a client keeps only the latest. The generated [persistence catalog](../persistence-catalog.md#deliverablespresented--log-only) records both declaration sites. Neither event reaches the model. diff --git a/docs/subsystems/deliverables.zh.md b/docs/subsystems/deliverables.zh.md new file mode 100644 index 0000000000..da8d7a93d2 --- /dev/null +++ b/docs/subsystems/deliverables.zh.md @@ -0,0 +1,61 @@ +# 产出物 + +[English](deliverables.md) | 中文 + +记录一轮交给用户的东西，由 [deliverables 包组](../../packages/deliverables/README.zh.md)拥有的两个只写日志的 Session 事件承载：模型通过 `present` 工具声明的文件，以及这一轮改动的文件，后者由轮开始和轮结束时的 git 工作树快照对比得出。事件只由客户端读取，Web [产出物插件](../../packages/client/ui-deliverables/README.zh.md)在轮末渲染两者。工具行为、快照机制和配置见 [`tool-present`](../../packages/deliverables/tool-present/README.zh.md) 与 [`workspace-changes`](../../packages/deliverables/workspace-changes/README.zh.md) 的包 README。 + +源码：[`packages/deliverables/tool-present/src/types.ts`](../../packages/deliverables/tool-present/src/types.ts)、[`packages/deliverables/workspace-changes/src/types.ts`](../../packages/deliverables/workspace-changes/src/types.ts) + +## `PresentedFile`：一条声明的交付 + +```ts type-equiv +/** A declared filesystem file whose current contents remain at its source path. */ +interface PresentedFile { + /** Original absolute path or path relative to the Session working directory. */ + path: string + /** Optional description supplied by the model. */ + description?: string +} +``` + +## `WorkspaceChangedFile`：一个改动的文件 + +```ts type-equiv +/** One file changed during a turn, with line counts from git or from the recorded file-tool hunks. */ +interface WorkspaceChangedFile { + /** Path relative to the Session working directory, or an absolute Host path outside it. */ + path: string + /** + * Sort key and label: the relative path inside the working directory, a + * `../` path for repository files above it, a `~` path under the home + * directory, otherwise the absolute path. Always slash-separated. + */ + display: string + /** Lines added; zero for a binary file. */ + added: number + /** Lines deleted; zero for a binary file. */ + deleted: number + /** Present when git reported the file as binary. */ + binary?: true +} +``` + +## `WorkspaceChangesData`：一轮的改动摘要 + +```ts type-equiv +/** Files changed during one top-level turn. */ +interface WorkspaceChangesData { + /** The turn whose file changes this summary describes. */ + turn: number + /** Changed files in `display` order, capped at the plugin's `maxFiles`. */ + files: WorkspaceChangedFile[] + /** Complete changed-file count, including files omitted by the cap. */ + total: number + /** Git tree object ids of the turn-start and turn-end working-tree snapshots. */ + snapshot: { before: string; after: string } +} +``` + +## 持久事件 + +`tool-present` 通过声明合并把 `deliverables/presented: { turn; callId; files: PresentedFile[] }` 加入 `SessionEventMap`，每次 `present` 的最终结果成功时追加一条。`workspace-changes` 合并 `workspace/changes: WorkspaceChangesData`，在顶层轮停止时追加；同一轮后来的事件替代先前的，客户端只保留最新一条。生成的[持久化目录](../persistence-catalog.zh.md#deliverablespresented--log-only)记录了两处声明位置。两个事件都不会进入模型请求。 diff --git a/packages/deliverables/README.i18n.yaml b/packages/deliverables/README.i18n.yaml index a0fbfda878..c5873b1ab9 100644 --- a/packages/deliverables/README.i18n.yaml +++ b/packages/deliverables/README.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 packages/deliverables/README.md -README.md: 4295e15981c2e01465de301edf1f1182aa21b88a -README.zh.md: 37eab8dc0d16a188aeb85be03b4572a70a28cb49 +README.md: ff2980f8cd190281010fcce3cd5c8a27f7d4213d +README.zh.md: c9bf60f3e765214608ed4d1d1fc25b1a2115460e diff --git a/packages/deliverables/README.md b/packages/deliverables/README.md index 4295e15981..ff2980f8cd 100644 --- a/packages/deliverables/README.md +++ b/packages/deliverables/README.md @@ -32,6 +32,7 @@ The deliverables family records what a turn hands to the user as durable Session ## Related documentation +- [Deliverables subsystem](../../docs/subsystems/deliverables.md) — the `PresentedFile` and `WorkspaceChangesData` vocabulary and the two durable events. - [Web deliverables](../client/ui-deliverables/README.md) — the turn-tail cards and file mentions that render these events. - [Present declares workspace source files](../../.agents/notes/implemented/feature/2026-09-08-present-workspace-source-files.md) — the delivery decision. - [Turn changed-files card](../../.agents/notes/implemented/feature/2026-09-11-turn-changed-files-card.md) — the snapshot design and coverage rules. diff --git a/packages/deliverables/README.zh.md b/packages/deliverables/README.zh.md index 37eab8dc0d..c9bf60f3e7 100644 --- a/packages/deliverables/README.zh.md +++ b/packages/deliverables/README.zh.md @@ -32,6 +32,7 @@ deliverables 系列把一轮交给用户的内容记录为只有客户端读取 ## 相关文档 +- [产出物子系统](../../docs/subsystems/deliverables.zh.md)——`PresentedFile` 与 `WorkspaceChangesData` 的词汇和两个持久事件。 - [Web 产出物](../client/ui-deliverables/README.zh.md)——渲染这些事件的轮尾卡片与文件提及。 - [present 声明工作区源文件](../../.agents/notes/implemented/feature/2026-09-08-present-workspace-source-files.zh.md)——交付决策。 - [本轮改动文件卡片](../../.agents/notes/implemented/feature/2026-09-11-turn-changed-files-card.zh.md)——快照设计与覆盖规则。 diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts index 7f0be31113..23c72f13d1 100644 --- a/scripts/gen-persistence-catalog.ts +++ b/scripts/gen-persistence-catalog.ts @@ -40,6 +40,8 @@ const LINK_MAP: Record = { StreamChunk: 'subsystems/llm-streaming.md', TokenUsage: 'subsystems/llm-streaming.md', TodoItem: 'subsystems/todo.md', + PresentedFile: 'subsystems/deliverables.md', + WorkspaceChangesData: 'subsystems/deliverables.md', TurnTrigger: 'subsystems/session.md', TurnEndReason: 'subsystems/session.md', SessionTitleEventData: 'subsystems/session-title.md', diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 6b0d56a403..3bbabf8097 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -2161,6 +2161,21 @@ "doc": "docs/subsystems/mcp.md", "symbol": "McpResourceProvider", "source": "packages/mcp/mcp-resources/src/index.ts" + }, + { + "doc": "docs/subsystems/deliverables.md", + "symbol": "PresentedFile", + "source": "packages/deliverables/tool-present/src/types.ts" + }, + { + "doc": "docs/subsystems/deliverables.md", + "symbol": "WorkspaceChangedFile", + "source": "packages/deliverables/workspace-changes/src/types.ts" + }, + { + "doc": "docs/subsystems/deliverables.md", + "symbol": "WorkspaceChangesData", + "source": "packages/deliverables/workspace-changes/src/types.ts" } ] }