docs(deliverables): add the subsystem page the package-group gate requires

The deliverables group README links a subsystems page that carries the PresentedFile, WorkspaceChangedFile, and WorkspaceChangesData declarations and names the two log-only events; the persistence catalog links the payload types to it.
2026-09-14 14:16:59 +08:00
1 parent dce58eaf4e
commit 722008aeeb
@@ -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
@@ -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
@@ -479,7 +479,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
 '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<T extends SessionEventType = SessionEventType> = {
 'workspace/changes': WorkspaceChangesData
 ```

+类型：[WorkspaceChangesData](subsystems/deliverables.zh.md)
+
 来源：[`packages/deliverables/workspace-changes/src/types.ts:36`](../packages/deliverables/workspace-changes/src/types.ts)

 ## 已解析的持久化类型
@@ -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
@@ -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` |
@@ -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` |
@@ -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
@@ -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.
@@ -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)记录了两处声明位置。两个事件都不会进入模型请求。
@@ -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
@@ -32,6 +32,7 @@ The deliverables family records what a turn hands to the user as durable Session
 <a id="related-documentation"></a>
 ## 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.
@@ -32,6 +32,7 @@ deliverables 系列把一轮交给用户的内容记录为只有客户端读取
 <a id="related-documentation"></a>
 ## 相关文档

+- [产出物子系统](../../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)——快照设计与覆盖规则。
@@ -40,6 +40,8 @@ const LINK_MAP: Record<string, string> = {
  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',
@@ -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"
    }
  ]
 }