docs(i18n): standardize contract terminology
This commit is contained in:
xjt
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/workflow/README.md
|
||||
README.md: 7b19cfd37f9b6870825d5e0761aed92908206b3a
|
||||
README.zh.md: 8460e22347a6c24b84f12f641479edb78bf1ed1e
|
||||
README.zh.md: 33b3f26780da1bf4efcd78242b2cfb212cef4c22
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# workflow/：动态工作流能力族
|
||||
# workflow/：动态工作流能力家族
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
@@ -11,6 +11,6 @@
|
||||
| [`tool-workflow/`](tool-workflow/README.md) | 向模型公开通用工作流执行 | 注册到 `ctx.tools` |
|
||||
| [`tool-ralph/`](tool-ralph/README.md) | 公开使用全新 agent（智能体）的固定 Ralph 工作流 | 注册到 `ctx.tools` |
|
||||
|
||||
worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) 和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) 决策。
|
||||
worker thread 将工作流执行与宿主事件循环隔离，但不构成安全边界。参见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)和 [Ralph 工具](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)决策。
|
||||
|
||||
子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见 [动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
|
||||
子系统参考——启动请求、`WorkflowMeta`、结果、实时运行、`workflow/*` 事件——见 [docs/subsystems/workflow.md](../../docs/subsystems/workflow.md)；决策见[动态工作流](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)与 [Ralph 消费方](../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) Agent Note。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/workflow/tool-ralph/README.md
|
||||
README.md: daf242364d1093cff30cd1dc95823e1ecb89a9c7
|
||||
README.zh.md: c855c6b5f42728f67935208b44601b379364aa7f
|
||||
README.zh.md: 92c3256188d9b4c38a292ba7697f702dc46db737
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
面向模型的 `ralph` 工具运行固定的前台工作流，把一个不可变目标依次交给多个全新子 agent（智能体）。它展示如何把专用编排策略实现为基于 [`ctx.workflows`](../workflow/README.md) 和 [`ctx.subagents`](../../subagent/subagent/README.md) 的普通插件：不会向 `agent-loop` 添加 Ralph 模式或全新 agent loop（智能体循环），同会话的[目标领域](../../goal/goal/README.md)也保持独立。策略和暂缓事项由 [Ralph Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)负责。
|
||||
|
||||
## 契约
|
||||
## 约定
|
||||
|
||||
`ralph({ objective, maxRounds? })` 会等待整个运行完成。部署配置中的 `maxRounds` 既是默认值，也是调用覆盖值的上限。每个 Ralph Round 通过 `subagentProvider` 启动一个子 agent；该提供方必须存在、支持结构化输出，并报告 `inheritsParentContext: false`。已配置的提供方以 `WorkflowStartRequest.subagentProvider` 传递，使固定脚本无法检查或更改路由，普通的模型编写 `workflow` 工具也不会因此获得提供方选择器。解析后的 Round 上限还会作为 `WorkflowStartRequest.maxTotalAgents` 传递，使固定循环与引擎的子 agent 总数后备上限协同；Ralph 上限超过引擎部署上限时，引擎会在发布运行前拒绝。
|
||||
|
||||
@@ -73,7 +73,7 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
每个子 agent 都会看到独立的固定 Round 提示词和结构化输出捕获契约。父级只看到原始调用和一个终态结果，其中包含 worker 报告的状态、Round 数量及经过美化打印的最终报告；中间子 agent 消息和报告不会进入父级对话。普通子 agent 失败时会改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
|
||||
每个子 agent 都会看到独立的固定 Round 提示词和结构化输出捕获约定。父级只看到原始调用和一个终态结果，其中包含 worker 报告的状态、Round 数量及经过美化打印的最终报告；中间子 agent 消息和报告不会进入父级对话。普通子 agent 失败时会改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/workflow/tool-workflow/README.md
|
||||
README.md: 5afa68764bfe339377954f8912b6f9b795435be1
|
||||
README.zh.md: 9af11811c9a91562983dcd865a0cb1a626cdac3c
|
||||
README.zh.md: 7f18c6f54332e11ea54a927ef2d7b723c2601c05
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
## 模型看到的内容
|
||||
|
||||
工具有三个参数：`meta`（必需的身份数据：`name`、`description` 和可选的进度注解）、`script`（必需的纯 JavaScript 脚本体，不含 `export const meta` 语句；工具描述包含完整的编写契约）以及 `args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态）。插件还会贡献一个 `tool:<toolName>` 系统提示词段，其中包含使用策略：只有用户明确要求工作流／大型编排时才使用该工具；一两项委派优先使用普通 subagent 调用。这遵循工具指导随工具插件交付、绝不放入部署 persona 的约定。
|
||||
工具有三个参数：`meta`（必需的身份数据：`name`、`description` 和可选的进度注解）、`script`（必需的纯 JavaScript 脚本体，不含 `export const meta` 语句；工具描述包含完整的编写约定）以及 `args`（可选 JSON 对象，作为全局变量 `args` 向脚本公开；裸列表应包装到字段中，使协议 schema 如实表达形态）。插件还会贡献一个 `tool:<toolName>` 系统提示词段，其中包含使用策略：只有用户明确要求工作流／大型编排时才使用该工具；一两项委派优先使用普通 subagent 调用。这遵循工具指导随工具插件交付、绝不放入部署 persona 的约定。
|
||||
|
||||
## 生命周期
|
||||
|
||||
@@ -49,7 +49,7 @@ Use the <toolName> tool ONLY when the user explicitly asks for a workflow or for
|
||||
|
||||
#### 模型看到的内容
|
||||
|
||||
工具可见时，已生成的默认 [`workflow` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-workflow) 包含完整的 JavaScript 钩子与元数据契约；`toolName` 可以重命名该定义，模型会提交脚本、元数据和可选 args。
|
||||
工具可见时，已生成的默认 [`workflow` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-workflow) 包含完整的 JavaScript 钩子与元数据约定；`toolName` 可以重命名该定义，模型会提交脚本、元数据和可选 args。
|
||||
|
||||
#### Token 影响
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/workflow/workflow-workerthread/README.md
|
||||
README.md: 9da420bdd67ac5b0a4bfffa312c6fe7b2dabf8f5
|
||||
README.zh.md: caba1cf5284c1586fe17e00ed4115ff12e3e4ae9
|
||||
README.zh.md: dbed654508bf38bd369247c411d3e8d3a1a749a5
|
||||
|
||||
@@ -21,7 +21,7 @@ worker 仍提供实用的隔离：
|
||||
|
||||
真正的不可信脚本沙箱需要在同一工作流 seam 背后采用不同引擎。
|
||||
|
||||
## 脚本契约
|
||||
## 脚本约定
|
||||
|
||||
工作流的 `meta` 是宿主提供的数据，而不是待求值的脚本文本。引擎会校验必需的 `name` 和 `description`、拒绝未知字段，并在返回运行前检查脚本正文能否解析。
|
||||
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/workflow/workflow/README.md
|
||||
README.md: 0de661423206cc71eb4669bc8ddb2419202bcb4a
|
||||
README.zh.md: da11b59aa285ea8f4e0e8c18ceab8922d706491a
|
||||
README.zh.md: 62abd00c013d054f4111a2db2ce72c58d3514087
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
工作流 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` 兑现。
|
||||
|
||||
@@ -31,7 +31,7 @@
|
||||
`WorkflowError` 携带一个代码和 `fatal` 标志。致命错误总会逸出 `parallel()` 和 `pipeline()`，而不会变成普通的逐项 `null`：
|
||||
|
||||
- `SCRIPT_PARSE` / `META_INVALID`：工作流无法启动；
|
||||
- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎契约；
|
||||
- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎约定；
|
||||
- `AGENT_CAP` / `ITEM_CAP`：超过已配置的安全上限；
|
||||
- `AGENT_START`：提供方的异步启动调用被拒绝；
|
||||
- `AGENT_RESULT`：已发布子 agent 的结果因基础设施故障而被拒绝；
|
||||
|
||||
Reference in New Issue
Block a user