docs: translate remaining READMEs

packages/workflow/workflow/README.i18n.yaml

@@ -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
+README.md: 9d01cfd3d2504d6b5af5a1af6cba735a4abb5795
+README.zh.md: 85dc6bb1897678f72eb715514ab85cad7f7b9589

packages/workflow/workflow/README.md

@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-workflow
 
+English | [中文](README.zh.md)
+
 The workflow seam (`ctx.workflows`) executes a model-written orchestration script that can fan out subagents. The seam defines the script, run, result, error, and event contracts; an engine decides how to isolate and execute the script.
 
 `@deepseek-ai/dsh-workflow-workerthread` is the current engine and `@deepseek-ai/dsh-tool-workflow` is the model-facing consumer. A future process or sandbox engine can replace the implementation without changing the tool.

packages/workflow/workflow/README.zh.md

@@ -0,0 +1,59 @@
+# @deepseek-ai/dsh-workflow
+
+[English](README.md) | 中文
+
+workflow seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
+
+`@deepseek-ai/dsh-workflow-workerthread` 是当前引擎，`@deepseek-ai/dsh-tool-workflow` 是面向模型的消费方。未来的进程或沙箱引擎可以替换实现，而无需更改工具。
+
+## 服务与运行契约
+
+`WorkflowService.start(request): WorkflowRun` 会同步完成足够多的校验，在运行存在前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
+
+运行由持有方拥有。引擎插件卸载会阻止新的启动，但不会撤销已接受的运行。持有方必须在每条路径上调用 `dispose()`；dispose 会取消剩余工作，并在文档规定的期限内达到或放弃完全停稳。
+
+`WorkflowStartRequest` 包含 `{ meta, script, args?, subagentProvider?, maxTotalAgents?, parent, signal? }`。`parent` 把每个子 agent（智能体）归属于调用 agent。`subagentProvider` 可以为该次运行的所有子 agent 指定路由，同时不向脚本公开提供方选择；省略时使用引擎配置的提供方。`maxTotalAgents` 可以为一次运行降低引擎的部署上限，同样对脚本不可见。实现会同步拒绝无效路由和限制。`meta` 与 `args` 是普通数据，不是脚本片段。
+
+`WorkflowRun` 公开 `{ id, meta, result, cancel(reason?), dispose() }`。`WorkflowResult` 包含 `{ value, stopReason, error?, agentsStarted }`；`value` 是普通 JSON 数据或 `null`。
+
+## 事件
+
+工作流事件只供观察。它们携带 `WorkflowRunInfo`（`id` 加 `meta`），而不是实时运行，因此监听器无法取得取消或 dispose（资源释放）权限。
+
+- `workflow/start` / `workflow/end` 为运行配对；
+- `workflow/phase` 和 `workflow/log` 公开脚本叙述；
+- `workflow/agent-start` / `workflow/agent-end` 按 `seq` 为每次子 agent 调用配对；异步提供方启动被拒绝的子 agent 不会发出其中任何一个事件。
+
+同进程事件 payload 是以不可变方式借用的值。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变执行。
+
+## 失败纪律
+
+`WorkflowError` 携带一个代码和 `fatal` 标志。致命错误总会逸出 `parallel()` 和 `pipeline()`，而不会变成普通的逐项 `null`：
+
+- `SCRIPT_PARSE` / `META_INVALID`：工作流无法启动；
+- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎契约；
+- `AGENT_CAP` / `ITEM_CAP`：超过已配置的安全上限；
+- `AGENT_START`：提供方异步启动被拒绝；
+- `AGENT_RESULT`：已就绪子 agent 的结果因基础设施故障而拒绝；
+- `RESULT_UNSERIALIZABLE`：脚本/worker 值不是普通 JSON 数据；
+- `CANCELLED`：取消拥有该运行，待处理和未来的钩子都会拒绝。
+
+子 agent 若以非完成的结束原因正常兑现，并不属于基础设施异常：`agent()` 返回 `null`，使脚本可以处理普通的子 agent 失败。
+
+## 模型体验
+
+通过 `dsh-tool-workflow` 和工作流引擎间接产生影响；两者创建子 agent 请求，并返回保留在父级的工具结果。
+
+#### KV Cache 影响
+
+不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
+
+## 已知限制与延期工作
+
+- **仅支持前台收集**：调用方拥有一个实时运行并等待它；后台启动/轮询、spill 句柄和分离收集均延期处理。
+- **没有日志记录或恢复**：脚本、子 agent 进度和中间值均不设检查点，因此进程重启后无法继续运行。
+- **没有已保存或嵌套工作流**：该 seam 只启动调用方提供的脚本，工作流脚本不会收到用于递归编排的 `workflow()` 钩子。
+- **没有 token 预算词汇**：引擎会限制并发、条目和子 agent，但请求与结果都不会统计跨子 agent 的模型 token。
+- **运行由持有方拥有，不由服务跟踪**：卸载引擎不会发现独立的实时句柄；每个消费方都必须 dispose 自己启动的运行。
+
+延期的工作流接口见[动态工作流 Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。