From bb59526598b9ed7d0396f693bd3b0d0c5f6814b7 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Wed, 5 Aug 2026 17:23:52 +0800 Subject: [PATCH] docs(core): document ContextFormed as the discriminated union it became The rebase carried the simple-interface block from the base branch, while this branch turned ContextFormed into a per-form discriminated union; ContextSnapshotSection gets its own block so the page stays self-contained. --- ...26-08-05-context-form-vocabulary.i18n.yaml | 4 +- docs/core-data-structures/core.i18n.yaml | 4 +- docs/core-data-structures/core.md | 37 +++++++++++++++++-- docs/core-data-structures/core.zh.md | 37 +++++++++++++++++-- scripts/type-equiv.manifest.json | 5 +++ 5 files changed, 77 insertions(+), 10 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml index 5e34c894bf..2f64f89d4f 100644 --- a/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.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 .agents/notes/implemented/feature/2026-08-05-context-form-vocabulary.md -2026-08-05-context-form-vocabulary.md: e41e04fad01db57f16f2e593c9b1da3a97aa5263 -2026-08-05-context-form-vocabulary.zh.md: d2c1e99f4a4b8d7488c2fd485d492abc9a4430f6 +2026-08-05-context-form-vocabulary.md: 506fbd0ec9eff25c2369a2c127c5149efd1cd96e +2026-08-05-context-form-vocabulary.zh.md: d2f92d0734e33e4cbf3ef97e5138b625ef6205b4 diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index a75e6c6f80..cfb05d8a21 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.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/core.md -core.md: a3017060c318da6f5c8a02c0c0ddc5ffd1695fd6 -core.zh.md: ceefc0800b8f318472192880a3e383150a7fe5cc +core.md: 5da68943e0f481a7dee9a8bda4b5fdf43e285a66 +core.zh.md: 30b5ea0d2fe1a9049ea3e7b1a86cf8cee445e96d diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index b3f033a69a..5da68943e0 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -202,12 +202,43 @@ type ContextForm = ``` ```ts type-equiv -/** Optional producer-declared {@link ContextForm}, mixed into the source shapes that carry one. */ -interface ContextFormed { - readonly form?: ContextForm +/** One named contribution to a `snapshot`-form context, in assembly order. */ +interface ContextSnapshotSection { + /** The contributing subsystem's name. */ + readonly name: string + /** That contribution's model-facing text, exactly as assembled. */ + readonly text: string } ``` +```ts type-equiv +/** + * Producer-declared {@link ContextForm} and the fields that form requires, + * mixed into the source shapes that carry one. + * + * Discriminated by `form` so a producer cannot declare a shape without the + * facts that shape is presented from: a `notice` must record its one-line + * account, a `snapshot` its sections. Omitting `form` stays valid — an + * undeclared context is the documented default. + */ +type ContextFormed = + | { readonly form?: never } + | { readonly form: 'instructions' } + | { readonly form: 'catalog' } + | { + readonly form: 'snapshot' + /** The named contributions this snapshot assembled, in order. */ + readonly sections: readonly ContextSnapshotSection[] + } + | { + readonly form: 'notice' + /** One-line account of what happened, shown without expanding the row. */ + readonly summary: string + } + | { readonly form: 'relay' } + | { readonly form: 'recall' } +``` + ## Streaming Adapters emit a raw **chunk** protocol; the loop logs the chunks (replay fidelity) while feeding the same chunks through a `BlockAssembler` to rebuild blocks and messages. `StreamChunk` is a closed discriminated union over `type` — `block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`. diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index 3f4e83a192..30b5ea0d2f 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -208,12 +208,43 @@ type ContextForm = ``` ```ts type-equiv -/** Optional producer-declared {@link ContextForm}, mixed into the source shapes that carry one. */ -interface ContextFormed { - readonly form?: ContextForm +/** One named contribution to a `snapshot`-form context, in assembly order. */ +interface ContextSnapshotSection { + /** The contributing subsystem's name. */ + readonly name: string + /** That contribution's model-facing text, exactly as assembled. */ + readonly text: string } ``` +```ts type-equiv +/** + * Producer-declared {@link ContextForm} and the fields that form requires, + * mixed into the source shapes that carry one. + * + * Discriminated by `form` so a producer cannot declare a shape without the + * facts that shape is presented from: a `notice` must record its one-line + * account, a `snapshot` its sections. Omitting `form` stays valid — an + * undeclared context is the documented default. + */ +type ContextFormed = + | { readonly form?: never } + | { readonly form: 'instructions' } + | { readonly form: 'catalog' } + | { + readonly form: 'snapshot' + /** The named contributions this snapshot assembled, in order. */ + readonly sections: readonly ContextSnapshotSection[] + } + | { + readonly form: 'notice' + /** One-line account of what happened, shown without expanding the row. */ + readonly summary: string + } + | { readonly form: 'relay' } + | { readonly form: 'recall' } +``` + ## 流式输出 适配器发出原始**分片**协议；循环记录分片（回放保真度），同时将同一批分片送入 `BlockAssembler` 以重建块和消息。`StreamChunk` 是基于 `type` 的封闭判别联合——`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`。 diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index fb30d78d8c..2e42a9f5d0 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -31,6 +31,11 @@ "symbol": "ContextForm", "source": "packages/llm/llm/src/message.ts" }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ContextSnapshotSection", + "source": "packages/llm/llm/src/message.ts" + }, { "doc": "docs/core-data-structures/core.md", "symbol": "ContextFormed",