From 6865b861d8de7426d5ece1a460eac97e6d64ab94 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Fri, 24 Jul 2026 18:32:31 +0800 Subject: [PATCH] docs(site): preserve translated core fragment ids --- docs/core-data-structures/core.i18n.yaml | 2 +- docs/core-data-structures/core.zh.md | 6 ++++++ docs/core-data-structures/session.i18n.yaml | 2 +- docs/core-data-structures/session.zh.md | 4 ++++ 4 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/core-data-structures/core.i18n.yaml b/docs/core-data-structures/core.i18n.yaml index 4cf6d47d23..b352fc37b4 100644 --- a/docs/core-data-structures/core.i18n.yaml +++ b/docs/core-data-structures/core.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write core.md: b0aa719974c5e5839027a6f958ce08259053da76 -core.zh.md: 12bb477686ad37cce2e98319b8d75ffefc50bbb9 +core.zh.md: 157fcfb0409fdb63ea50186802a682b5fc476ffc diff --git a/docs/core-data-structures/core.zh.md b/docs/core-data-structures/core.zh.md index 12bb477686..157fcfb040 100644 --- a/docs/core-data-structures/core.zh.md +++ b/docs/core-data-structures/core.zh.md @@ -45,6 +45,8 @@ harness 是一个微内核：一个极小的核心加上众多插件。大多数 > 这些页面上的类型声明及其 JSDoc 与源码等价，并由 `pnpm run verify-type-equiv` 检查漂移（见 [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)）。普通块保留完整声明；`public-api` 块保留去除实现体的公开 class 声明。Cordis 服务使用生成的[服务目录](../cordis-catalog/services.md)。 + + ## `…Map → derived-union` 模式 harness 中几乎所有可扩展的和类型都遵循同一形状：一个以判别标签为键的接口（`…Map`），联合类型由 `keyof` 派生。插件通过**声明合并**添加变体——无需修改拥有该类型的包（package）。 @@ -79,6 +81,8 @@ declare module '@deepseek-ai/dsh-llm' { 消费方最常 `switch` 的两个大型判别联合类型是：**`StreamChunk`**（流式协议）和 **`SessionEvent`**（日志条目）。按仓库约定，对标签做 `switch`——不要链式 `if`——这样每个分支都能窄化类型，拼错的标签会编译失败。 + + ## 品牌化 ID 跨越包边界的 ID 都经过**品牌化**——结构上是字符串，但在类型层面不可互换（不能把 `SessionId` 传给需要 `CallId` 的位置）。每种类型通过各自的工厂构造；比较、日志记录和 JSON 行为与普通字符串相同。 @@ -359,6 +363,8 @@ type SessionEvent = { 十四种事件变体（`turn/start`、`turn/end`、`step/start`、`step/end`、`user/message`、`prompt/blocked`、`context/message`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`steering/message`、`todo/write`、`request/header`）、`deriveMessages()` 投影规则、`TurnTrigger`/`TurnEndReason` 原因以及轮次封闭不变量都在 **[session.md](session.md)** 中。日志如何持久化——`SessionPersistence` seam、JSONL/SQLite 后端、`session/flush` 检查点、崩溃恢复与 `SessionHeader`——则在 **[persistence.md](persistence.md)** 中。 + + ## Agent 句柄 `Agent` 是每个插件（UI、钩子、orchestrator）面向编程的 surface。具体实现为 dsh-agent-loop 包内部细节；循环外没有任何组件依赖它。 diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml index ba86de4263..b173cb3506 100644 --- a/docs/core-data-structures/session.i18n.yaml +++ b/docs/core-data-structures/session.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write session.md: b342e1c5c3bff030d67c61a6f1daa0c8167182c1 -session.zh.md: 4f539155a1a035a3fb9807c6990ab10b72c7a421 +session.zh.md: 9d221c9bfd7b3e8e60bd964fc0a55b439057e2c6 diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md index 4f539155a1..9d221c9bfd 100644 --- a/docs/core-data-structures/session.zh.md +++ b/docs/core-data-structures/session.zh.md @@ -158,6 +158,8 @@ interface TodoItem { } ``` + + ### 请求头事件：`request/header` 请求信封（即 `EpochHeader`：调用配置 + 渲染后的系统提示词 + 已组装的工具 schema + 会话前缀）会作为会话状态写入日志，因此每个对话请求都是日志的纯函数（见可重建性 Agent Note）。带有 reason `'initial'` 或 `'resume'` 的完整 `request/header` 快照记录每个 agent loop 实例的边界；之后请求发生变化时，系统会以 reason `'change'` 记录另一份完整快照。`foldRequestHeader(events)` 通过选择最新快照重建请求头。该事件不是 `SurfaceEventType`，不产生 LLM 消息。 @@ -501,6 +503,8 @@ interface TurnTriggerMap { } ``` + + ## 轮次的结束原因：`TurnEndReasonMap` `aborted` 有意作为一种粗粒度的持久结果：它只记录取消中断了实时轮次，不记录是哪个运行时调用方发起取消。仅属于运行时的调用方词汇由 [`AgentCancelCause`](core.md#the-agent-handle) 定义；未来若有审计需求，应新增独立的控制请求事件，而非让终止结果承载这一信息。