From 5f67b99e72b9a35e0b8f35f5c92141f0acadcb38 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Thu, 23 Jul 2026 13:53:14 +0800 Subject: [PATCH] docs(i18n): align Turn and Step terminology --- docs/defensive-patterns.i18n.yaml | 2 +- docs/defensive-patterns.zh.md | 4 ++-- docs/glossary.i18n.yaml | 2 +- docs/glossary.zh.md | 8 ++++---- docs/i18n/terminology.md | 4 ++-- docs/testing.i18n.yaml | 2 +- docs/testing.zh.md | 4 ++-- 7 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/defensive-patterns.i18n.yaml b/docs/defensive-patterns.i18n.yaml index b39cad3e24..39db53200c 100644 --- a/docs/defensive-patterns.i18n.yaml +++ b/docs/defensive-patterns.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write defensive-patterns.md: 349b916df6f7544300dacd578acf42668d9436ac -defensive-patterns.zh.md: 19565f54595195a52d1b49ff487294945171ae2d +defensive-patterns.zh.md: 7c99290854e2bbdb4237853717f175d096ec79d9 diff --git a/docs/defensive-patterns.zh.md b/docs/defensive-patterns.zh.md index 19565f5459..7c99290854 100644 --- a/docs/defensive-patterns.zh.md +++ b/docs/defensive-patterns.zh.md @@ -10,11 +10,11 @@ ## 跨 seam 契约两侧都要遵守 -当一个接口文档记录了两种合法的信号方式时——例如适配器可以通过从 `stream()` 抛出异常来报告失败，也可以通过以 `finish {kind:'error'|'aborted'}` 分片结束流来报告——消费方必须同时处理两种路径，而不是只处理第一个实现恰好使用的那种。依赖库的适配器可能无法在流中途抛出异常，只能走带内路径；如果 agent loop（智能体循环）只捕获抛出的异常，就会把提供方的 401 错误变成一个正常完成的轮次。请在类型定义处记录契约；通过真实消费方测试每个分支。 +当一个接口文档记录了两种合法的信号方式时——例如适配器可以通过从 `stream()` 抛出异常来报告失败，也可以通过以 `finish {kind:'error'|'aborted'}` 分片结束流来报告——消费方必须同时处理两种路径，而不是只处理第一个实现恰好使用的那种。依赖库的适配器可能无法在流中途抛出异常，只能走带内路径；如果 agent loop（智能体循环）只捕获抛出的异常，就会把提供方的 401 错误变成一个正常完成的 Turn（轮次）。请在类型定义处记录契约；通过真实消费方测试每个分支。 ## 异步状态不是同步状态 -`agent.send()` 不会在返回前翻转状态；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿基于一个刚刚请求的状态来控制流程——应以实际触发的事件/promise（`agent/status`、`task.done`）驱动生命周期，并观察状态转换（先看到 `running` 再看到 `idle`），而不是把状态当作单次发送的结果：多个排队发送会在同一个 `running` 区间内连续运行多个轮次，而取消或资源释放可能丢弃尚未启动的项。这条守则是双向的：如果等待的转换永远不会发生（EOF 时没有提交过任何工作 → 永远不会进入 `running`），等待就会挂起——请显式处理「无需等待」的分支。 +`agent.send()` 不会在返回前翻转状态；后台任务的完成与 Turn 边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿基于一个刚刚请求的状态来控制流程——应以实际触发的事件/promise（`agent/status`、`task.done`）驱动生命周期，并观察状态转换（先看到 `running` 再看到 `idle`），而不是把状态当作单次发送的结果：多个排队发送会在同一个 `running` 区间内连续运行多个 Turn，而取消或资源释放可能丢弃尚未启动的项。这条守则是双向的：如果等待的转换永远不会发生（EOF 时没有提交过任何工作 → 永远不会进入 `running`），等待就会挂起——请显式处理「无需等待」的分支。 ## Dispose 必须达到静止，而不仅仅是请求停止 diff --git a/docs/glossary.i18n.yaml b/docs/glossary.i18n.yaml index 9724877d71..9ccbe4467d 100644 --- a/docs/glossary.i18n.yaml +++ b/docs/glossary.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write glossary.md: c1931c0e0c630d05f5bd4fc3f30720f858f1175e -glossary.zh.md: 951abebc162e2456211437fcd5b27dd57783e9b6 +glossary.zh.md: bd44efa1222bde5a4281cbb005543fa3cc6691b4 diff --git a/docs/glossary.zh.md b/docs/glossary.zh.md index 951abebc16..bd44efa122 100644 --- a/docs/glossary.zh.md +++ b/docs/glossary.zh.md @@ -21,7 +21,7 @@ FIXME(glossary-completeness): 首次发布前扩充本术语表，使其覆盖 S ## 目标 - **目标**：附着在现有会话上的单个持久完成目标，带有按修订号演进的 `active` / `paused` / `blocked` / `complete` 阶段和 Goal Round 上限；`blocked` 保留策略代码与说明。目标是一种状态，不是调度器，也不是一段独立对话；会话日志仍是其真源。 -- **Goal Round**：为当前目标接纳的一次续行周期。同会话驱动器将 Goal Round 具体化为一个来源为目标的[轮次](#turn)，其中包含一个或多个步骤；同一会话中无关的人类轮次不消耗 Goal Round 上限。 +- **Goal Round**：为当前目标接纳的一次续行周期。同会话驱动器将 Goal Round 具体化为一个来源为目标的 [Turn（轮次）](#turn)，其中包含一个或多个 Step（步骤）；同一会话中无关的人类 Turn 不消耗 Goal Round 上限。 - **目标激活**：续行消费方接纳下一个 Goal Round 的进程本地权限。激活态为 `armed` 或 `disarmed`；它有意不参与持久回放，因此恢复和 fork 后，必须由人类随后通过 `/goal` 或模型工具授权恢复变更，自动工作才可开始。 ## 人类命令 @@ -32,9 +32,9 @@ FIXME(glossary-completeness): 首次发布前扩充本术语表，使其覆盖 S ## 循环层级 -- **轮次**：会话中一次对已接纳输入的排空过程，在模型及其工具停止工作或终止策略介入后结束。 -- **步骤**：一次模型请求，以及由模型响应引发的工具执行；一个轮次包含一个或多个步骤。 -- **Round**：承载一个轮次的外层策略迭代，例如一个 [Goal Round](#goal-round) 或一次使用全新 agent 的 Ralph 尝试。Round 计数器归该策略所有，并不统计会话中的每个轮次。 +- **Turn**：会话中一次对已接纳输入的排空过程，在模型及其工具停止工作或终止策略介入后结束。 +- **Step**：一次模型请求，以及由模型响应引发的工具执行；一个 Turn 包含一个或多个 Step。 +- **Round**：承载一个 Turn 的外层策略迭代，例如一个 [Goal Round](#goal-round) 或一次使用全新 agent 的 Ralph 尝试。Round 计数器归该策略所有，并不统计会话中的每个 Turn。 ## Ralph diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md index 287fbbc572..b0b44f24cc 100644 --- a/docs/i18n/terminology.md +++ b/docs/i18n/terminology.md @@ -58,11 +58,13 @@ | seam | seam | | | 与 `extension point` 是不同概念；根据具体语境，可译为`服务边界`或`可替换点` | | skill | skill | skill（技能） | | | | spawn | spawn | | | | +| Step | Step | Step（步骤） | | 领域层级术语；普通流程或操作步骤不在此列，按中文语境翻译。 | | steering | steering | steering（中途引导） | | | | task id | task id | | 任务 id | 保留英文 | | subagent | subagent | | | | | thinking | thinking | | | API 字段保留英文；描述模型模式时译为`思考` | | transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 | +| Turn | Turn | Turn（轮次） | | 领域层级术语；普通非领域用法（如轮流、转向或往返）按中文语境翻译。 | | waterfall | waterfall | waterfall（瀑布式事件） | | | | wheel | wheel 包 | | | Python 打包格式 | | worktree | worktree | | | git 工作区概念 | @@ -164,7 +166,6 @@ | spine | 主干 | | | | | staged | 暂存 | | | 沿用 git 官方中文翻译 | | stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` | -| step | 步骤 | | | | | stream | 流 | | | | | streaming | 流式输出 | | | | | structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） | @@ -176,7 +177,6 @@ | tool result | 工具结果 | | | | | tool schema | 工具 schema | | | | | toolkit | 工具包 | | | | -| turn | 轮次 | | | | | VFS | VFS | 虚拟文件系统（VFS） | | | | typecheck | 类型检查 | | | | | vocabulary | 词汇 | | | | diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml index 89e63f7fef..f94a618dc6 100644 --- a/docs/testing.i18n.yaml +++ b/docs/testing.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write testing.md: 5a18397ba2431a4c4f2595d32d9de6fe3ddeb6f4 -testing.zh.md: 19ee4aa6abffc13c35b1933e2af0ed38eef5c7e6 +testing.zh.md: d9f1fca745b0f545f0b1904a2d3029649568d18d diff --git a/docs/testing.zh.md b/docs/testing.zh.md index 19ee4aa6ab..d9f1fca745 100644 --- a/docs/testing.zh.md +++ b/docs/testing.zh.md @@ -13,13 +13,13 @@ ## 带密钥策略：推理在这里很便宜 -我们是 DeepSeek，不要吝惜真实 API 测试。无密钥测试只能证明底层通路；只有带密钥运行才能证明 agent（智能体）能对接真实模型正常工作。覆盖文件写入提示词、包含多个轮次的对话、工具使用和流中取消。价值最高的是**冒烟测试**：启动真实示例、发送一条提示词，并检查外部世界；它们能捕获「单元测试全绿、产品却坏了」这一类 mock 无法发现的问题（[事故复盘 0001](postmortem/0001-acp-default-export-drops-inject.md)）。自动跳过让无密钥 CI 和无密钥贡献者不受阻塞；它不是成本信号。每个示例都提供无密钥和带密钥冒烟测试（[examples/AGENTS.md](../examples/AGENTS.md)）。 +我们是 DeepSeek，不要吝惜真实 API 测试。无密钥测试只能证明底层通路；只有带密钥运行才能证明 agent（智能体）能对接真实模型正常工作。覆盖文件写入提示词、包含多个 Turn（轮次）的对话、工具使用和流中取消。价值最高的是**冒烟测试**：启动真实示例、发送一条提示词，并检查外部世界；它们能捕获「单元测试全绿、产品却坏了」这一类 mock 无法发现的问题（[事故复盘 0001](postmortem/0001-acp-default-export-drops-inject.md)）。自动跳过让无密钥 CI 和无密钥贡献者不受阻塞；它不是成本信号。每个示例都提供无密钥和带密钥冒烟测试（[examples/AGENTS.md](../examples/AGENTS.md)）。 ## 优先使用真实实现而非 mock 只 mock 开销高或不确定的边界（LLM（大语言模型）适配器、网络、时钟）；下游一切保持真实。手写替身只能证明桥接层在搬运字节，不能证明交付的工具行为符合断言。桥接工具调用测试将脚本化 mock 模型与真实工具和执行器配合使用：`makeBridgeHarness({ withBash: true })` 接入 `dsh-bash-local` 与 `dsh-tool-bash`，然后运行 `echo`。 -恢复测试按步骤区分分片前与分片后的失败，并证明失败分片不会派生出消息或工具副作用。覆盖耗尽、取消、策略组合、持久化、状态、协议计数、会关闭传输的空闲超时，以及交付的 Loader 组合。 +恢复测试按 Step（步骤）区分分片前与分片后的失败，并证明失败分片不会派生出消息或工具副作用。覆盖耗尽、取消、策略组合、持久化、状态、协议计数、会关闭传输的空闲超时，以及交付的 Loader 组合。 ## 验证外部世界，而非自我报告