docs(i18n): proofread README translations 181-186
This commit is contained in:
j-xiang
@@ -2,15 +2,15 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
workflow seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
|
||||
工作流 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` 兑现。
|
||||
`WorkflowService.start(request): WorkflowRun` 会同步完成足够多的校验，在运行创建前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
|
||||
|
||||
运行由持有方拥有。引擎插件卸载会阻止新的启动，但不会撤销已接受的运行。持有方必须在每条路径上调用 `dispose()`；dispose 会取消剩余工作，并在文档规定的期限内达到或放弃完全停稳。
|
||||
运行由持有方负责。引擎插件卸载会阻止新的启动，但不会撤销已接受的运行。持有方必须在每条路径上调用 `dispose()`；dispose（资源释放）会取消剩余工作，并在文档规定的期限内达到或放弃完全停稳。
|
||||
|
||||
`WorkflowStartRequest` 包含 `{ meta, script, args?, subagentProvider?, maxTotalAgents?, parent, signal? }`。`parent` 把每个子 agent（智能体）归属于调用 agent。`subagentProvider` 可以为该次运行的所有子 agent 指定路由，同时不向脚本公开提供方选择；省略时使用引擎配置的提供方。`maxTotalAgents` 可以为一次运行降低引擎的部署上限，同样对脚本不可见。实现会同步拒绝无效路由和限制。`meta` 与 `args` 是普通数据，不是脚本片段。
|
||||
|
||||
@@ -18,13 +18,13 @@ workflow seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的
|
||||
|
||||
## 事件
|
||||
|
||||
工作流事件只供观察。它们携带 `WorkflowRunInfo`（`id` 加 `meta`），而不是实时运行，因此监听器无法取得取消或 dispose（资源释放）权限。
|
||||
工作流事件只供观察。它们携带 `WorkflowRunInfo`（`id` 加 `meta`），而不是活动运行，因此监听器无法取得取消或 dispose 权限。
|
||||
|
||||
- `workflow/start` / `workflow/end` 为运行配对；
|
||||
- `workflow/phase` 和 `workflow/log` 公开脚本叙述；
|
||||
- `workflow/agent-start` / `workflow/agent-end` 按 `seq` 为每次子 agent 调用配对；异步提供方启动被拒绝的子 agent 不会发出其中任何一个事件。
|
||||
- `workflow/agent-start` / `workflow/agent-end` 按 `seq` 为每次子 agent 调用配对；提供方的异步启动调用被拒绝时，该子 agent 不会发出其中任何一个事件。
|
||||
|
||||
同进程事件 payload 是以不可变方式借用的值。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变执行。
|
||||
同进程事件 payload 是以不可变方式借用的值。每个监听器都独立隔离：同步抛出异常或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变执行。
|
||||
|
||||
## 失败纪律
|
||||
|
||||
@@ -33,10 +33,10 @@ workflow seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的
|
||||
- `SCRIPT_PARSE` / `META_INVALID`：工作流无法启动；
|
||||
- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎契约；
|
||||
- `AGENT_CAP` / `ITEM_CAP`：超过已配置的安全上限；
|
||||
- `AGENT_START`：提供方异步启动被拒绝；
|
||||
- `AGENT_START`：提供方的异步启动调用被拒绝；
|
||||
- `AGENT_RESULT`：已就绪子 agent 的结果因基础设施故障而拒绝；
|
||||
- `RESULT_UNSERIALIZABLE`：脚本/worker 值不是普通 JSON 数据；
|
||||
- `CANCELLED`：取消拥有该运行，待处理和未来的钩子都会拒绝。
|
||||
- `CANCELLED`：取消会接管该运行，待处理和未来的钩子都会拒绝。
|
||||
|
||||
子 agent 若以非完成的结束原因正常兑现，并不属于基础设施异常：`agent()` 返回 `null`，使脚本可以处理普通的子 agent 失败。
|
||||
|
||||
@@ -46,14 +46,14 @@ workflow seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
|
||||
不会直接导致 KV Cache 失效；请求前缀的任何变化均由上述消费方负责。
|
||||
|
||||
## 已知限制与延期工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **仅支持前台收集**：调用方拥有一个实时运行并等待它；后台启动/轮询、spill 句柄和分离收集均延期处理。
|
||||
- **没有日志记录或恢复**：脚本、子 agent 进度和中间值均不设检查点，因此进程重启后无法继续运行。
|
||||
- **仅支持前台收集**：调用方负责一个活动运行并等待它；后台启动／轮询、spill 句柄和分离收集均暂缓处理。
|
||||
- **没有日志化或恢复**：脚本、子 agent 进度和中间值均不设检查点，因此进程重启后无法继续运行。
|
||||
- **没有已保存或嵌套工作流**：该 seam 只启动调用方提供的脚本，工作流脚本不会收到用于递归编排的 `workflow()` 钩子。
|
||||
- **没有 token 预算词汇**：引擎会限制并发、条目和子 agent，但请求与结果都不会统计跨子 agent 的模型 token。
|
||||
- **运行由持有方拥有，不由服务跟踪**：卸载引擎不会发现独立的实时句柄；每个消费方都必须 dispose 自己启动的运行。
|
||||
- **运行由持有方负责，不由服务跟踪**：卸载引擎不会发现独立的活动句柄；每个消费方都必须 dispose 自己启动的运行。
|
||||
|
||||
延期的工作流接口见[动态工作流 Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
|
||||
暂缓实现的工作流接口见[动态工作流 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
|
||||
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
Workspace 系列拥有持久 workspace 概念：用户工作所在的目录，包含标题以及属于它的有序会话列表。设计记录：[领域 KV 存储 Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
|
||||
Workspace 系列负责持久 workspace 概念：用户工作所在的目录，包含标题以及属于它的有序会话列表。设计记录：[领域 KV 存储 Agent Note（agent 决策记录）](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)。
|
||||
|
||||
| 包 | 职责 | ctx 键 |
|
||||
|---|---|---|
|
||||
| `workspace/` | 位于存储领域形式之上的 `WorkspaceRegistry` 服务：按 realpath 唯一的路径、会话所有权计数、实体缓存 | `ctx.workspace` |
|
||||
| `workspace/` | 基于存储领域数据形式的 `WorkspaceRegistry` 服务：按 realpath 去重的路径、会话归属记账、实体缓存 | `ctx.workspace` |
|
||||
|
||||
所有权真相存在 workspace 记录的 `sessionIds`（有序）中，绝不从会话 cwd 派生；`attachSession` 会验证会话头的 cwd 解析到 workspace 路径，因此一个会话在结构上最多属于一个 workspace。删除 Workspace 只会移除该注册表记录及账本：目录、用户文件和会话日志都会保留，相关会话则进入 Ungrouped（参见[决策记录](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）。
|
||||
所有权信息以 workspace 记录中的 `sessionIds`（有序）为准，绝不从会话 cwd 派生；`attachSession` 会验证会话头的 cwd 解析到 workspace 路径，因此一个会话在结构上最多属于一个 workspace。删除 Workspace 只会移除该注册表记录及会话归属记录：目录、用户文件和会话日志都会保留，相关会话则进入 Ungrouped（参见[决策记录](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）。
|
||||
|
||||
@@ -4,21 +4,21 @@
|
||||
|
||||
DeepSeek Harness 的 Workspace 实体注册表（`ctx.workspace`）：通过领域数据形式存储持久 workspace 记录、稳定 workspace 顺序和按新到旧排列的候选会话索引。消费方看到 `Workspace` 接口；实体实现保持包（package）私有。
|
||||
|
||||
实体／存储理由见[领域 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；仅头部启动和 GUI 排序见 [Workspace UI 产品流 Agent Note](../../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
|
||||
实体／存储理由见[领域 Agent Note（agent 决策记录）](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)；仅使用头部的引导初始化和 GUI 排序见 [Workspace UI 产品流 Agent Note](../../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md)。
|
||||
|
||||
## 形状
|
||||
## 结构
|
||||
|
||||
- `ctx.workspace.create(path, title?)`：规范化 `path` 时使用 `fs.realpath`，拒绝不存在或非目录的路径，每个规范路径最多创建一条记录，并将新记录前置到持久 workspace 顺序。对同一路径重复调用会返回现有 workspace，且不改变其标题；不同路径不能创建重复标题。
|
||||
- `ctx.workspace.get(id)`/`list()`/`resolveByPath(path)`：由缓存提供的查找。`list()` 为同步操作，并遵循持久注册表顺序；`resolveByPath` 为异步操作，因为它应用同一 `realpath` 规范，并会拒绝缺失路径，而不是创建路径。
|
||||
- `ctx.workspace.delete(id)`：只移除 Workspace 注册记录、对应的持久顺序条目及会话账本。未知 id 返回 `false`，成功移除记录则返回 `true`。目录、用户文件、实时会话和持久化会话日志绝不受影响，因此相关会话会进入 Ungrouped。表写入失败时会恢复原顺序和此前发布的实体。
|
||||
- `ctx.workspace.get(id)`/`list()`/`resolveByPath(path)`：由缓存提供的查找。`list()` 为同步操作，并遵循持久注册表顺序；`resolveByPath` 为异步操作，因为它采用相同的 `realpath` 规范化方式，并会拒绝缺失路径，而不是创建路径。
|
||||
- `ctx.workspace.delete(id)`：只移除 Workspace 注册记录、对应的持久顺序条目及会话归属记录。未知 id 返回 `false`，成功移除记录则返回 `true`。目录、用户文件、活跃会话和持久化会话日志绝不受影响，因此相关会话会进入 Ungrouped。表写入失败时会恢复原顺序和此前发布的实体。
|
||||
- `Workspace.attachSession(id)`：对照 workspace 路径验证实时或已持久化的会话头 cwd，并将新 id 前置。未知会话、缺失／无法解析／非目录的 cwd 值和不匹配情况都会在不写入的前提下被拒绝。`detachSession` 只移除候选索引条目。
|
||||
- `ctx.workspace.touchSession(id)`：仅将已验证、已记账的会话移到最前。未分组或被过滤的会话为空操作，workspace 顺序绝不改变。
|
||||
- `Workspace.sessionIds`：按持久候选顺序提供同步 id 加规范 cwd 成员投影。缺失头部、无效 cwd 值和不匹配情况都被过滤；下一次 workspace 变更会剪除它们。如果同一存储介质将一个会话索引到两个 workspace 下、从两条记录声明同一路径，或偏离持久 workspace 顺序，启动会被拒绝。
|
||||
- `ctx.workspace.touchSession(id)`：仅将已验证、已记账的会话移到最前。未分组或被过滤的会话不会触发任何操作，workspace 顺序绝不改变。
|
||||
- `Workspace.sessionIds`：按持久候选顺序提供同步 id 加规范 cwd 成员投影。缺失头部、无效 cwd 值和不匹配情况都被过滤；下一次 workspace 变更会剪除它们。如果同一存储介质将一个会话索引到两个 workspace 下、用两条记录声明同一路径，或偏离持久 workspace 顺序，启动会被拒绝。
|
||||
- `Workspace.status()`：未缓存的目录检查，返回 `'ok' | 'missing-dir'`；目录缺失绝不会改动记录。
|
||||
|
||||
`storageDomain` 和 `sessionPersistence` 是启动必需依赖。对等服务不可用时，插件保持待处理，且不能提交空的已初始化标记。首次成功启动时，注册表调用 `SessionPersistence.list()`，仅使用头部 `id`、`cwd` 和 `createdAt` 对有效历史目录分组并持久化初始顺序；它绝不读取事件正文。已初始化标记最后写入，因此重启后可安全复用部分启动写入。后续仅有 cwd 的会话仍属于 Ungrouped。
|
||||
`storageDomain` 和 `sessionPersistence` 是启动必需依赖。任一依赖服务不可用时，插件保持待处理，且不能提交空的已初始化标记。首次成功启动时，注册表调用 `SessionPersistence.list()`，仅使用头部 `id`、`cwd` 和 `createdAt` 对有效历史目录分组并持久化初始顺序；它绝不读取事件正文。已初始化标记最后写入，因此重启后可安全复用引导初始化期间的部分写入。后续仅能通过 cwd 识别的会话仍属于 Ungrouped。
|
||||
|
||||
Create 与 delete 会在记录和顺序可能分叉之前，先持久化明确的待处理变更标记。启动时只补全被该标记证明的变更，随后清除标记；没有标记的顺序／表不一致仍属于来源不明的损坏，并会直接失败。删除后重新注册同一路径会生成新的 Workspace id，且不会自动重新接纳保留下来的 Session。
|
||||
创建和删除操作会在记录和顺序可能分叉之前，先持久化明确的待处理变更标记。启动时只补全该标记所指明的变更，随后清除标记；没有标记的顺序／表不一致仍属于来源不明的损坏，并会明确报错。删除后重新注册同一路径会生成新的 Workspace id，且不会自动重新接纳保留下来的会话。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -34,9 +34,9 @@ Create 与 delete 会在记录和顺序可能分叉之前，先持久化明确
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
与实时请求无关：此包绝不触及请求前缀，因此无法使提供方缓存复用失效。
|
||||
与实时请求无关：此包绝不触及请求前缀，因此不会使提供方缓存复用失效。
|
||||
|
||||
## 已知限制与延后工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- 会话删除与破坏性的文件夹移除是彼此独立且尚未提供的功能；删除 Workspace 注册记录绝不能替代二者（参见[决策记录](../../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)）。
|
||||
- 头部索引会在启动时刷新，也会在 attach 必须解析未缓存持久 id 时刷新；另一进程执行的删除或 cwd 破坏会在下次刷新或重启后被观测。
|
||||
- 头部索引会在启动时刷新，也会在 attach 必须解析未缓存持久 id 时刷新；另一进程执行的删除或造成的 cwd 损坏会在下次刷新或重启后被发现。
|
||||
|
||||
Reference in New Issue
Block a user