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

docs(i18n): proofread README translations 141-160

Browse Source
This commit is contained in:
j-xiang
2026-07-29 15:29:38 +08:00
parent 57b01e68d3
commit a37097846b
20 changed files with 146 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/support/llm-replay/README.zh.md
+18 -18
View File
@@ -2,21 +2,21 @@
[English](README.md) | 中文
用于无密钥快照测试的回放 LLM 插件。它从已记录的**会话 JSONL** fixture 重建模型流，使测试可以在无 API 密钥的情况下使用固定模型 transcript 启动真实 agent。配置 `providers` 后，它会注册仅回放适配器，其目录可供测试模型发现的场景使用；没有 `providers` 时，它会安装不需要发现的测试所用 catch-all `llm/stream` waterfall。
用于无密钥快照测试的大语言模型（LLM）回放插件。它根据已记录的**会话 JSONL** fixture（测试前置数据）重建模型流，使测试无需 API 密钥即可针对固定的模型 transcript（文本记录）启动真实 agent（智能体）。配置 `providers` 后，它会注册仅用于回放的适配器，其模型目录可供测试模型发现功能的场景使用；未配置 `providers` 时，它会安装无需模型发现功能的测试所用 catch-all `llm/stream` waterfall（瀑布式事件）。
其消费方是 ACP、headless `stream-json` 和 TUI 快照套件，以及 web 浏览器 e2e lane。Loader 驱动套件使用此插件替换真实 LLM 适配器；web lane 直接安装它，以保留拆卸消费句柄。将派生和回放逻辑保留在此处，可使其受 `packages/*/src` 上每文件 100% 覆盖率门禁约束。
其消费方包括 ACP（Agent Client Protocol）、headless `stream-json` 和 TUI 快照套件，以及 Web 浏览器 e2e 流水线。Loader 驱动的套件使用此插件替代真实 LLM 适配器；Web 流水线直接安装它，以保留清理阶段的消费检查句柄。将派生和回放逻辑放在此处，可使其受 `packages/*/src` 的逐文件 100% 覆盖率门禁约束。
## Fixture 的工作方式
## fixture 的工作方式
Fixture 就是持久化会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件携带每个 `StreamChunk`，因此按 `(turn, step)` 对其分组可重建每次 `stream()` 调用的分片序列（每个 loop 步骤一次模型调用）。因此，录制操作是「运行一次真实 agent 并收集 `.jsonl`」，由快照 harness 完成；该插件不执行录制。Fixture 的 `request/header` 内容可能被 token 化为 `{{system}}`/`{{tools}}`（harness 在一个场景中固定该内容，并擦除其余场景）；回放对此并不关心，因为派生只读取 `assistant/chunk` 事件和第 0 行会话 header。
fixture 就是持久化的会话日志（`<scenario>/session.jsonl`）。其 `assistant/chunk` 事件包含每个 `StreamChunk`，因此按 `(turn, step)` 分组即可重建每次 `stream()` 调用的分片序列（每个循环步骤调用一次模型）。因此，录制就是“运行一次真实 agent 并收集 `.jsonl`”，由快照 harness 完成；该插件本身不录制。fixture 的 `request/header` 内容可能被标记化为 `{{system}}`/`{{tools}}`（harness 会在一个场景中固定该内容，并清除其余场景中的内容）；回放不受影响，因为派生过程只读取 `assistant/chunk` 事件和第 0 行的会话 header。
有两种失败 mode 无法仅从 `assistant/chunk` 重建：在任何分片前纯抛出（例如 HTTP 401，日志只包含 `turn/end {error}` 而没有分片），以及 cancel/hang（是时序，而非分片内容）。需要这些的场景提供可选 sidecar（`<scenario>/replay.override.json`），它要么替换派生脚本（裸 `ReplayEntry[]`），要么增补派生脚本（`{ patches: [{ at, entry }] }`：保留全部由 JSONL 派生的调用，仅在点名的调用索引处换入，索引从 0 计；`at` 等于派生长度时为追加，正是注入的瞬态抛出之后那次重试尝试所占的槽位）。Patch 索引必须互不重复。覆写文档、每个 patch 与每个条目，以及每个分片的判别字段都会在文件加载时接受校验。`hang` 条目可以指定 `readyFile`；在其前缀分片到达 loop 后、等待取消前，回放会写入该空标记，使外部驱动器可以在不观察展示更新的情况下确定性取消。
有两种失败模式无法仅根据 `assistant/chunk` 重建：在产生任何分片前直接抛出异常（例如 HTTP 401，此时日志只有 `turn/end {error}` 而没有分片），以及取消或挂起（差异在时序，而非分片内容）。需要这些行为的场景可提供伴随文件（`<scenario>/replay.override.json`）：它可以替换派生脚本（裸 `ReplayEntry[]`），也可以增补派生脚本（`{ patches: [{ at, entry }] }`：保留所有从 JSONL 派生的调用，只替换指定的从 0 开始计数的调用索引；当 `at` 等于派生长度时，则在注入瞬态异常后的重试位置追加一次调用）。补丁索引不得重复。文件加载时会校验覆写文档、每个补丁和条目，以及每个分片的判别标签。`hang` 条目可以指定 `readyFile`；当前缀分片到达循环后、开始等待取消前，回放会写入这个空标记，使外部驱动程序无需观察展示层更新即可确定性地取消。
## 嵌套 agent：每会话键控
父 agent 委托给进程内 subagent 的场景会记录多个日志：父级（`session.jsonl`）和每个子级各一个（`session.1.jsonl`等）。每个 agent 在同一上下文中作为自己的 `Session` 运行，因此回放必须为每个 agent 提供自己的脚本。
父 agent 委托给进程内 subagent（子 agent）的场景会记录多个日志：父会话使用 `session.jsonl`，每个子会话各使用一个日志（`session.1.jsonl` 等）。每个 agent 都在同一上下文中作为独立的 `Session` 运行，因此回放必须为每个 agent 提供各自的脚本。
回放按调用会话 id 为每次调用建键（由 agent loop 标记的 `GenerateOptions.sessionId`）。实时会话 id 在每次运行中都是新的随机值，绝不等于已记录值，因此实时会话通过**首次调用顺序** 绑定到已记录脚本：脚本按 header `createdAt` 排序（父级在前，因为它必须先进行流式输出才能委托）；第一个进行任何调用的实时会话领取第一个脚本，下一个新会话领取下一个，以此类推。然后，每个会话推进自己的游标。没有 `sessionId` 的调用是绑定到主脚本的单一匿名会话，因此单会话场景与以前完全相同。实时会话数超过已记录脚本数时快速失败。
回放根据发起调用的会话 id 为每次调用建立键（`GenerateOptions.sessionId` 由 agent loop 写入）。实时会话 id 每次运行时都会重新随机生成，绝不会等于记录中的 id，因此实时会话按**首次调用顺序**绑定到已记录脚本：脚本按 header 中的 `createdAt` 排序（父会话在前，因为它必须先开始流式输出才能委托）；第一个发起调用的实时会话取得第一个脚本，下一个新会话取得下一个脚本，以此类推。此后每个会话分别推进自己的游标。没有 `sessionId` 的调用视为一个绑定主脚本的匿名会话，因此单会话场景的行为与以前完全相同。不同实时会话的数量超过已记录脚本数时会明确报错。
## 配置
@@ -24,9 +24,9 @@ Fixture 就是持久化会话日志（`<scenario>/session.jsonl`）。其 `assis
|---|---|---|---|
| `file` | string | `$DSH_SNAPSHOT_FILE` | 主（父）`session.jsonl` fixture 的路径。必需（配置或 env）。 |
| `overrideFile` | string | `$DSH_SNAPSHOT_OVERRIDE` | 主会话的可选 `ReplayOverrideDoc` sidecar：裸 `ReplayEntry[]` 替换其派生脚本，`{ patches }` 则按调用索引增补该脚本。 |
| `childFiles` | string[] | `$DSH_SNAPSHOT_CHILD_FILES` (path-delimited) | 嵌套场景中已记录的 subagent 子会话日志；单会话场景为空。 |
| `childFiles` | string[] | `$DSH_SNAPSHOT_CHILD_FILES`（以路径分隔符分隔） | 嵌套场景中已记录的 subagent 子会话日志；单会话场景为空。 |
| `providers` | `ReplayProviderConfig[]` | 无 | 可选的仅回放提供方和模型目录。每个提供方可以设置 `retryPolicy`，每个模型可以发布 `contextWindow`；已配置路由通过回放适配器分派，绝不执行提供方 I/O。 |
| `paceMs` | number | 无（突发） | 可选的每分片毫秒延迟，使下游传输（例如真实浏览器观察的 web SSE mux）看到真正的增量传递。它只是仿真开关，测试不得依赖它保证正确性。值必须是非负整数；pace 等待期间中止会迅速取消流。 |
| `paceMs` | number | 无（突发） | 可选的每分片毫秒延迟，使下游传输（例如真实浏览器观察到的 Web SSE（Server-Sent Events）多路复用器）看到真正的增量传递。它只是仿真开关，测试不得依赖它保证正确性。值必须是非负整数；pace 等待期间中止会迅速取消流。 |
```yaml
- id: llm-replay
@@ -52,10 +52,10 @@ Fixture 就是持久化会话日志（`<scenario>/session.jsonl`）。其 `assis
## 导出项
- `installLlmReplay(ctx, config)`：安装已配置回放适配器或 catch-all `llm/stream` 监听器；返回 `ReplayHandle`（包含用于 HMR 安全的 `dispose()`，以及 `assertConsumed()` 拆卸检查；后者确保每个已记录脚本都绑定到实时会话，且每个已绑定游标都已耗尽，从而将场景静默驱动的模型调用少于记录数转换为明确诊断）。在测试中使用它，可以不通过 Loader 或 env var 驱动回放。
- `loadSessionScripts(config)`：解析场景的有序 `SessionScript[]` （主级 + 子级），准备按首次调用顺序绑定到实时会话。
- `loadReplayScript(config)`：只解析主会话的 `ReplayEntry[]` （如果存在则使用经校验的 sidecar 替换或 patch，否则从 JSONL 派生；fixture 缺失时快速失败）。
- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)`：将已记录会话日志转换为脚本并读取其 header `id`/`createdAt` 的纯辅助工具。派生分组必须以 `finish` 分片结束；没有该分片的分组是已抛出 `stream()` 的指纹，必须改用 override sidecar 表达。
- `installLlmReplay(ctx, config)`：安装已配置回放适配器或 catch-all `llm/stream` 监听器；返回 `ReplayHandle`（包含用于保证 HMR（热模块替换）安全的 `dispose()`，以及清理阶段执行的 `assertConsumed()` 检查；后者确保每个已记录脚本都绑定到实时会话，且每个已绑定游标都已耗尽，从而将场景静默驱动的模型调用少于记录数转换为明确诊断）。在测试中使用它，可以不通过 Loader 或 env var 驱动回放。
- `loadSessionScripts(config)`：解析场景的有序的 `SessionScript[]`（主会话 + 子会话），准备按首次调用顺序绑定到实时会话。
- `loadReplayScript(config)`：只解析主会话的 `ReplayEntry[]`（如果伴随文件存在，则使用经校验的替换或补丁；否则从 JSONL 派生；fixture 缺失时明确报错）。
- `deriveReplayScript(events)` / `parseSessionLog(text)` / `parseSessionHeader(text)`：将已记录会话日志转换为脚本并读取其 header `id`/`createdAt` 的纯辅助工具。派生分组必须以 `finish` 分片结束；没有该分片的分组是 `stream()` 抛出异常的指纹，必须改用 override sidecar 表达。
- 类型 `ReplayEntry` / `ReplayOverrideDoc` / `ReplayOverridePatch` / `SessionScript` / `ReplayConfig` / `ReplayProviderConfig` / `ReplayModelConfig` / `ReplayHandle` / `Config`。
## 插件导出形态
@@ -66,11 +66,11 @@ Fixture 就是持久化会话日志（`<scenario>/session.jsonl`）。其 `assis
无。该无密钥测试适配器不向提供方模型发送请求，只将已记录 assistant 分片回放到测试 loop 中。
#### KV 缓存影响
#### KV Cache 影响
无；该包既不组装也不发送提供方请求。
无；该包（package）既不组装也不发送提供方请求。
## 已知限制与待完成工作
## 已知限制与暂缓事项
- **首次调用顺序脚本绑定假设串行委托**：并发运行同级 subagent 的 cut（或运行中落地的压缩摘要调用）会非确定性地将实时会话绑定到已记录脚本；在这种场景出现前暂不实现更强的键控（`XXX(concurrent-subagents)`）。
- **只有生产分片的调用可派生**：纯分片前抛出或 cancel/hang 场景需要 `replay.override.json` sidecar。替换和 patch 两种形式都只影响主会话；子会话脚本仍从各自日志派生。
- **首次调用顺序脚本绑定假设串行委托**：并发运行同级 subagent 的 cut（或运行中发生的上下文压缩（context compaction）摘要调用）会非确定性地将实时会话绑定到已记录脚本；在这种场景出现前暂不实现更强的键控（`XXX(concurrent-subagents)`）。
- **只有会产生分片的调用才能派生**：在产生分片前直接抛出异常或取消/挂起的场景需要 `replay.override.json` 伴随文件。替换和补丁两种形式都只影响主会话；子会话脚本仍从各自日志派生。