@deepseek-ai/dsh-tool-ralph 0.1.1-rc.2 → 0.1.2-alpha.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.i18n.yaml +2 -2
- package/README.md +102 -16
- package/README.zh.md +115 -29
- package/lib/index.js +1 -1
- package/package.json +26 -25
package/README.i18n.yaml
CHANGED
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
|
3
3
|
# after editing either side, bring the other along and re-record with:
|
|
4
4
|
# pnpm run verify-translation-pairing --write packages/workflow/tool-ralph/README.md
|
|
5
|
-
README.md:
|
|
6
|
-
README.zh.md:
|
|
5
|
+
README.md: 882201a2e0b1b105f4e57e3b24d2360ff4870370
|
|
6
|
+
README.zh.md: edefe0ede50e2d5447d33d5b52d1f6b2f8ed3773
|
package/README.md
CHANGED
|
@@ -1,38 +1,107 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "The model-facing ralph tool: a fixed foreground fresh-agent loop toward one immutable objective, for users and maintainers choosing or configuring fresh-agent iteration."
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# @deepseek-ai/dsh-tool-ralph
|
|
2
7
|
|
|
3
8
|
English | [中文](README.zh.md)
|
|
4
9
|
|
|
5
|
-
|
|
10
|
+
## Summary
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
`dsh-tool-ralph` gives the model the `ralph` tool: a fixed foreground workflow that hands one immutable objective to a sequence of fresh child agents, each starting with no conversation seed and carrying only the previous bounded report. It is a specialized orchestration policy built on the workflow and subagent capabilities — no Ralph mode is added to the agent loop, and the same-session goal domain stays independent. The call returns when a worker reports completion or a concrete blocker, or at the round limit; completion and blockers are worker reports, not independent certification. Use it only when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution; ordinary long-running objectives belong to goal tools, and bounded delegation belongs to subagents or workflows.
|
|
8
13
|
|
|
9
|
-
|
|
14
|
+
## Table of Contents
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
- [Use this package](#use-this-package)
|
|
17
|
+
- [Understand the implementation](#understand-the-implementation)
|
|
18
|
+
- [Further Exploration](#further-exploration)
|
|
19
|
+
- [Model Experience](#model-experience)
|
|
20
|
+
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
|
|
21
|
+
- [Dev Note](#dev-note)
|
|
12
22
|
|
|
13
|
-
|
|
23
|
+
-----
|
|
14
24
|
|
|
15
|
-
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## Use this package
|
|
16
27
|
|
|
17
|
-
|
|
28
|
+
The `ralph` tool runs a fixed foreground loop: one fresh child per round works on the immutable objective in the shared workspace, and only a bounded structured report crosses rounds. Use it only when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. For ordinary long-running same-session work, use goal tools; for bounded delegation and fan-out, use plain subagents or the `workflow` tool.
|
|
18
29
|
|
|
19
|
-
|
|
30
|
+
### Calling the tool
|
|
31
|
+
|
|
32
|
+
The model submits `{ objective, maxRounds? }` and the call blocks until the whole run settles. The deployment config's `maxRounds` is both the default and a ceiling on a call override. The terminal result is `complete`, `blocked`, or `budget-limited`, carrying the last bounded report and the number of rounds started; an ordinary child failure returns an error naming the failed round and retaining the last successful handoff when one exists.
|
|
20
33
|
|
|
21
|
-
|
|
34
|
+
### What each round sees
|
|
22
35
|
|
|
23
|
-
|
|
36
|
+
Each child receives only the immutable objective, its current round and cap, a shared-workspace-as-authority instruction, and the previous structured handoff; parent conversation and prior child sessions are never seeded. The workspace is the long-term memory across rounds. Reports carry a status (`continue`, `complete`, or `blocked`), a non-empty summary, evidence, next steps, and blocker text; invalid or oversized reports fail the workflow instead of being truncated or mistaken for cap exhaustion.
|
|
24
37
|
|
|
25
|
-
|
|
38
|
+
### Config
|
|
26
39
|
|
|
27
|
-
|
|
|
40
|
+
| Field | Default | Meaning |
|
|
28
41
|
|---|---|---|
|
|
29
42
|
| `subagentProvider` | `spawn` | Fresh structured-output provider used for every round. |
|
|
30
43
|
| `maxRounds` | `256` | Default and deployment ceiling for one Ralph run. |
|
|
31
44
|
| `maxHandoffChars` | `16384` | Maximum serialized characters in one round report. |
|
|
32
45
|
| `maxResultChars` | `16384` | Maximum characters in the complete successful parent result. |
|
|
33
46
|
|
|
34
|
-
|
|
47
|
+
The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-ralph) is the exhaustive source for every accepted field. The configured provider must exist, support structured output, and report `inheritsParentContext: false`; a call against a provider that violates this fails loud before any round starts.
|
|
48
|
+
|
|
49
|
+
-----
|
|
50
|
+
|
|
51
|
+
<a id="understand-the-implementation"></a>
|
|
52
|
+
## Understand the implementation
|
|
53
|
+
|
|
54
|
+
<details>
|
|
55
|
+
<summary>Implementation internals — click to expand</summary>
|
|
56
|
+
|
|
57
|
+
This section explains the fixed-script design and the validation and lifecycle mechanics; observable behavior is fully covered in [Use this package](#use-this-package).
|
|
58
|
+
|
|
59
|
+
### Design concept
|
|
60
|
+
|
|
61
|
+
The loop is a deployment-owned fixed script: the model supplies data only and cannot alter the loop, provider route, schema, or handoff validation. The tool is an ordinary plugin over `ctx.workflowEngine` and `ctx.subagents` — no Ralph mode or fresh-agent loop is added to `agent-loop`, and the same-session goal domain stays independent. The [Ralph Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) owns the policy and deferred work.
|
|
62
|
+
|
|
63
|
+
### Fixed script and routing
|
|
64
|
+
|
|
65
|
+
The configured provider is carried as `WorkflowStartRequest.subagentProvider`, so the fixed script cannot inspect or change routing and the ordinary model-written `workflow` tool gains no provider selector. The resolved round cap is carried as `WorkflowStartRequest.maxTotalAgents`, coordinating the fixed loop with the engine's total-child backstop; the engine rejects a cap above its deployment ceiling before publishing a run.
|
|
66
|
+
|
|
67
|
+
### Report validation
|
|
68
|
+
|
|
69
|
+
Status-specific semantics and the serialized `maxHandoffChars` ceiling are validated inside the fixed workflow and again at the consumer boundary: a continuing report needs next steps and an empty blocker, a completion report needs evidence and no next steps, and a blocked report needs a concrete blocker. Invalid, missing, or oversized reports fail the workflow.
|
|
70
|
+
|
|
71
|
+
### Lifecycle and cancellation
|
|
72
|
+
|
|
73
|
+
The caller's agent is the parent of every fresh child, preserving cwd and lineage without copying its conversation. `exec.signal` enters the workflow engine and is also bridged to `run.cancel()` for implementation independence. The tool awaits `run.result` and calls `run.dispose()` in `finally`, so a cancelled parent step waits for the engine's bounded termination and child quiescence before returning.
|
|
74
|
+
|
|
75
|
+
### Render intent
|
|
35
76
|
|
|
77
|
+
The pending call is a `generic` card titled `ralph` with the immutable objective as its `rawInput`; the result keeps the generic card. Both presentation functions depend only on tool arguments and the settled tool envelope, and the completion and blocker labels state that a worker reported the outcome, not independent certification.
|
|
78
|
+
|
|
79
|
+
### Source map
|
|
80
|
+
|
|
81
|
+
| File | Role |
|
|
82
|
+
|---|---|
|
|
83
|
+
| [`src/index.ts`](src/index.ts) | Plugin entry: fixed script, provider routing, report validation, tool registration |
|
|
84
|
+
| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; workflow and subagent owners validate the runs and children it starts) |
|
|
85
|
+
|
|
86
|
+
</details>
|
|
87
|
+
|
|
88
|
+
-----
|
|
89
|
+
|
|
90
|
+
<a id="further-exploration"></a>
|
|
91
|
+
## Further Exploration
|
|
92
|
+
|
|
93
|
+
Read these pages when the tool-level contract is not enough. They move from the shared workflow model to the engine, the subagent seam, and the adjacent goal domain.
|
|
94
|
+
|
|
95
|
+
- [Workflow subsystem](../../../docs/subsystems/workflow.md) — the seam contract behind the fixed loop.
|
|
96
|
+
- [Workflow seam](../workflow/README.md) — the run and result vocabulary.
|
|
97
|
+
- [Worker-thread engine](../workflow-worker-thread/README.md) — the engine that executes the fixed script.
|
|
98
|
+
- [subagent seam](../../subagent/subagent/README.md) — the fresh-child provider contract.
|
|
99
|
+
- [Goal group](../../goal/goal/README.md) — same-session goal tools for ordinary long-running objectives.
|
|
100
|
+
- [Ralph tool Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) — the policy, provider requirements, and deferred work.
|
|
101
|
+
|
|
102
|
+
-----
|
|
103
|
+
|
|
104
|
+
<a id="model-experience"></a>
|
|
36
105
|
## Model Experience
|
|
37
106
|
|
|
38
107
|
### System prompt
|
|
@@ -44,7 +113,7 @@ Every parent request in this plugin's registration scope receives the fixed rout
|
|
|
44
113
|
##### Ralph guidance
|
|
45
114
|
|
|
46
115
|
```markdown
|
|
47
|
-
Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or
|
|
116
|
+
Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.
|
|
48
117
|
```
|
|
49
118
|
|
|
50
119
|
#### Token effect
|
|
@@ -85,9 +154,26 @@ Each fresh child has an independent request cache. The parent result appends aft
|
|
|
85
154
|
|
|
86
155
|
## Known Limitations and Deferred Work
|
|
87
156
|
|
|
88
|
-
|
|
157
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
These limits define what the tool does not yet support. They are current constraints, not a task backlog.
|
|
161
|
+
|
|
162
|
+
- **Completion is worker self-declaration** — there is no independent evaluator or verifier deciding whether the objective is complete; evaluator policy and evaluator-driven continuation are deferred.
|
|
89
163
|
- **Foreground only** — there is no job id, background collection, process-resume checkpoint, scheduler, or wall-clock start policy.
|
|
90
164
|
- **The workspace is the only cross-round long-term memory** — one bounded report is the explicit handoff, and uncommitted conversational reasoning disappears with each child.
|
|
91
|
-
- **One round is one fresh child** — there is no within-round fan-out, model
|
|
165
|
+
- **One round is one fresh child** — there is no within-round fan-out, model or provider switching, fork context, or model-call-selected provider.
|
|
92
166
|
- **Ordinary child failure is terminal for the run** — the fixed script reports the failed round and last successful handoff but does not retry; fatal workflow infrastructure failures can end before that state is returned.
|
|
93
167
|
- **Only round count bounds aggregate effort** — token, price, and elapsed-time budgets are deferred.
|
|
168
|
+
|
|
169
|
+
<a id="dev-note"></a>
|
|
170
|
+
### Dev Note
|
|
171
|
+
|
|
172
|
+
<details>
|
|
173
|
+
<summary>Working context for maintainers — click to expand</summary>
|
|
174
|
+
|
|
175
|
+
This Dev Note is working context for maintainers: open directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
|
|
176
|
+
|
|
177
|
+
Open directions: an independent evaluator with evaluator-driven continuation; within-round fan-out and provider selection; and token, price, and elapsed-time budgets beyond the round cap.
|
|
178
|
+
|
|
179
|
+
</details>
|
package/README.zh.md
CHANGED
|
@@ -1,50 +1,119 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "面向模型的 ralph 工具：面向一个不可变目标的固定前台全新 agent 循环，供选择或配置全新 agent 迭代的用户与维护者阅读。"
|
|
3
|
+
kind: "package-reference"
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# @deepseek-ai/dsh-tool-ralph
|
|
2
7
|
|
|
3
8
|
[English](README.md) | 中文
|
|
4
9
|
|
|
5
|
-
|
|
10
|
+
## 概述
|
|
11
|
+
|
|
12
|
+
`dsh-tool-ralph` 把 `ralph` 工具交给模型：一个固定的前台工作流，把一个不可变目标依次交给多个全新子 agent（智能体），每个子 agent 都没有对话种子，只携带上一份有界报告。它是构建在工作流与 subagent 能力之上的专用编排策略——不会向 agent loop 添加 Ralph 模式，同会话的 goal 领域也保持独立。调用在 worker 报告完成或具体阻塞、或达到 Round 上限时返回；完成与阻塞都是 worker 报告，不是独立认证。仅当直接用户明确要求 Ralph 循环或全新 agent 迭代执行时使用它；普通的长期同会话目标属于 goal 工具，有界委派属于 subagent 或工作流。
|
|
6
13
|
|
|
7
|
-
##
|
|
14
|
+
## 目录
|
|
8
15
|
|
|
9
|
-
|
|
16
|
+
- [使用本包](#use-this-package)
|
|
17
|
+
- [理解实现](#understand-the-implementation)
|
|
18
|
+
- [进一步探索](#further-exploration)
|
|
19
|
+
- [模型体验](#model-experience)
|
|
20
|
+
- [已知限制与延期工作](#known-limitations-and-deferred-work)
|
|
21
|
+
- [开发备注](#dev-note)
|
|
10
22
|
|
|
11
|
-
|
|
23
|
+
-----
|
|
12
24
|
|
|
13
|
-
|
|
25
|
+
<a id="use-this-package"></a>
|
|
26
|
+
## 使用本包
|
|
14
27
|
|
|
15
|
-
|
|
28
|
+
`ralph` 工具运行固定的前台循环：每个 Round 一个全新子 agent 在共享工作区中处理不可变目标，只有一份有界的结构化报告跨越 Round。仅当直接用户明确要求 Ralph 循环或全新 agent 迭代执行时使用它。普通的长期同会话工作请使用 goal 工具；有界委派与扇出请使用普通 subagent 或 `workflow` 工具。
|
|
16
29
|
|
|
17
|
-
|
|
30
|
+
### 调用工具
|
|
18
31
|
|
|
19
|
-
|
|
32
|
+
模型提交 `{ objective, maxRounds? }`，调用会阻塞到整个运行结算。部署配置中的 `maxRounds` 既是默认值，也是调用覆盖值的上限。终态结果为 `complete`、`blocked` 或 `budget-limited`，携带最后一份有界报告与已启动的 Round 数量；普通子 agent 失败会返回错误，其中标明失败的 Round，并在存在时保留上一次成功交接。
|
|
20
33
|
|
|
21
|
-
|
|
34
|
+
### 每个 Round 看到什么
|
|
22
35
|
|
|
23
|
-
|
|
36
|
+
每个子 agent 只接收不可变目标、当前 Round 及其上限、一条「共享工作区是权威状态」指令与上一份结构化交接；父级对话与先前子 agent 会话绝不会作为种子。工作区是跨 Round 的长期记忆。报告携带状态（`continue`、`complete` 或 `blocked`）、非空摘要、证据、后续步骤与阻塞文本；无效或过大的报告会使工作流失败，而不会被截断或误认为上限耗尽。
|
|
24
37
|
|
|
25
|
-
|
|
38
|
+
### 配置
|
|
26
39
|
|
|
27
|
-
|
|
|
40
|
+
| 字段 | 默认值 | 含义 |
|
|
28
41
|
|---|---|---|
|
|
29
42
|
| `subagentProvider` | `spawn` | 每个 Round 使用的全新结构化输出提供方。 |
|
|
30
43
|
| `maxRounds` | `256` | 一次 Ralph 运行的默认值和部署上限。 |
|
|
31
44
|
| `maxHandoffChars` | `16384` | 一份 Round 报告序列化后的最大字符数。 |
|
|
32
45
|
| `maxResultChars` | `16384` | 返回给父级的完整成功结果最大字符数。 |
|
|
33
46
|
|
|
34
|
-
|
|
47
|
+
生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-ralph)是每个受支持字段的穷尽式真源。配置的提供方必须存在、支持结构化输出，并报告 `inheritsParentContext: false`；针对违反此要求的提供方的调用会在任何 Round 开始前响亮失败。
|
|
48
|
+
|
|
49
|
+
-----
|
|
50
|
+
|
|
51
|
+
<a id="understand-the-implementation"></a>
|
|
52
|
+
## 理解实现
|
|
53
|
+
|
|
54
|
+
<details>
|
|
55
|
+
<summary>实现细节——点击展开</summary>
|
|
56
|
+
|
|
57
|
+
本节解释固定脚本设计以及校验与生命周期机制；可观察行为已在[使用本包](#use-this-package)中完整说明。
|
|
58
|
+
|
|
59
|
+
### 设计理念
|
|
60
|
+
|
|
61
|
+
循环是部署方拥有的固定脚本：模型只提供数据，无法改变循环、提供方路由、schema 或交接校验。该工具是基于 `ctx.workflowEngine` 与 `ctx.subagents` 的普通插件——不会向 `agent-loop` 添加 Ralph 模式或全新 agent loop，同会话的 goal 领域也保持独立。[Ralph Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md)拥有策略与暂缓事项。
|
|
62
|
+
|
|
63
|
+
### 固定脚本与路由
|
|
64
|
+
|
|
65
|
+
配置的提供方以 `WorkflowStartRequest.subagentProvider` 传递，因此固定脚本无法检查或更改路由，普通的模型编写 `workflow` 工具也不会因此获得提供方选择器。解析后的 Round 上限以 `WorkflowStartRequest.maxTotalAgents` 传递，使固定循环与引擎的子 agent 总数后备上限协同；上限超过引擎部署上限时，引擎会在发布运行前拒绝。
|
|
66
|
+
|
|
67
|
+
### 报告校验
|
|
68
|
+
|
|
69
|
+
特定状态的语义与序列化后的 `maxHandoffChars` 上限会在固定工作流内部及消费方边界各校验一次：继续报告需要后续步骤与空阻塞，完成报告需要证据且没有后续步骤，阻塞报告需要具体阻塞。无效、缺失或过大的报告会使工作流失败。
|
|
70
|
+
|
|
71
|
+
### 生命周期与取消
|
|
72
|
+
|
|
73
|
+
调用方 agent 是每个全新子 agent 的父级，因此会保留 cwd 与谱系，但不会复制其对话。`exec.signal` 进入工作流引擎，同时也桥接到 `run.cancel()`，以便不依赖具体实现。工具等待 `run.result` 并在 `finally` 中调用 `run.dispose()`，因此被取消的父级步骤会等到引擎完成有界终止且子 agent 完全停稳后才返回。
|
|
74
|
+
|
|
75
|
+
### 渲染意图
|
|
76
|
+
|
|
77
|
+
待处理调用使用 `generic` 卡片，标题为 `ralph`，不可变目标作为其 `rawInput`；结果继续使用 generic 卡片。两个呈现函数都只依赖工具参数与已结算的工具包络，完成与阻塞标签会说明结果由 worker 报告，而非独立认证。
|
|
35
78
|
|
|
79
|
+
### 源码地图
|
|
80
|
+
|
|
81
|
+
| 文件 | 职责 |
|
|
82
|
+
|---|---|
|
|
83
|
+
| [`src/index.ts`](src/index.ts) | 插件入口：固定脚本、提供方路由、报告校验、工具注册 |
|
|
84
|
+
| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；工作流与 subagent 归属方校验它启动的运行与子 agent） |
|
|
85
|
+
|
|
86
|
+
</details>
|
|
87
|
+
|
|
88
|
+
-----
|
|
89
|
+
|
|
90
|
+
<a id="further-exploration"></a>
|
|
91
|
+
## 进一步探索
|
|
92
|
+
|
|
93
|
+
当工具级契约不够用时阅读以下页面。它们从共享工作流模型逐步进入引擎、subagent seam 与相邻的 goal 领域。
|
|
94
|
+
|
|
95
|
+
- [工作流子系统](../../../docs/subsystems/workflow.zh.md)——固定循环背后的 seam 契约。
|
|
96
|
+
- [工作流 seam](../workflow/README.zh.md)——运行与结果词汇。
|
|
97
|
+
- [worker-thread 引擎](../workflow-worker-thread/README.zh.md)——执行固定脚本的引擎。
|
|
98
|
+
- [subagent seam](../../subagent/subagent/README.zh.md)——全新子 agent 的提供方契约。
|
|
99
|
+
- [goal 组](../../goal/goal/README.zh.md)——面向普通长期目标的同会话 goal 工具。
|
|
100
|
+
- [Ralph 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.zh.md)——策略、提供方要求与暂缓事项。
|
|
101
|
+
|
|
102
|
+
-----
|
|
103
|
+
|
|
104
|
+
<a id="model-experience"></a>
|
|
36
105
|
## 模型体验
|
|
37
106
|
|
|
38
107
|
### 系统提示词
|
|
39
108
|
|
|
40
|
-
####
|
|
109
|
+
#### 模型看到什么
|
|
41
110
|
|
|
42
|
-
|
|
111
|
+
在该插件的注册作用域内，每个父级请求都会收到下方固定的路由指导。
|
|
43
112
|
|
|
44
113
|
##### Ralph 指导
|
|
45
114
|
|
|
46
115
|
```markdown
|
|
47
|
-
Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or
|
|
116
|
+
Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.
|
|
48
117
|
```
|
|
49
118
|
|
|
50
119
|
#### Token 影响
|
|
@@ -53,13 +122,13 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
|
|
|
53
122
|
|
|
54
123
|
#### KV Cache 影响
|
|
55
124
|
|
|
56
|
-
|
|
125
|
+
只要插件作用域与指导文本不变，前缀就保持稳定。启用或 dispose（资源释放）可能会使从该提示词段起的缓存复用失效。
|
|
57
126
|
|
|
58
127
|
### 工具 schema
|
|
59
128
|
|
|
60
|
-
####
|
|
129
|
+
#### 模型看到什么
|
|
61
130
|
|
|
62
|
-
已生成的 [`ralph` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-ralph)公开一个必填 `objective`
|
|
131
|
+
已生成的 [`ralph` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-ralph) 公开一个必填 `objective` 字符串与一个可选 `maxRounds` 数字。提供方选择、交接大小、报告 schema、工作流脚本与编排行为均由部署侧控制，不在调用 schema 中。
|
|
63
132
|
|
|
64
133
|
#### Token 影响
|
|
65
134
|
|
|
@@ -67,13 +136,13 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
|
|
|
67
136
|
|
|
68
137
|
#### KV Cache 影响
|
|
69
138
|
|
|
70
|
-
|
|
139
|
+
只要定义与可见性不变，前缀就保持稳定。
|
|
71
140
|
|
|
72
141
|
### 子 agent 请求与父级结果
|
|
73
142
|
|
|
74
|
-
####
|
|
143
|
+
#### 模型看到什么
|
|
75
144
|
|
|
76
|
-
每个子 agent 都会看到独立的固定 Round
|
|
145
|
+
每个子 agent 都会看到独立的固定 Round 提示词与结构化输出捕获契约。父级只看到原始调用与一个终态结果，其中包含 worker 报告的状态、Round 数量与美化打印的最终报告；中间子 agent 消息与报告不会进入父级对话。普通子 agent 失败时改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
|
|
77
146
|
|
|
78
147
|
#### Token 影响
|
|
79
148
|
|
|
@@ -83,11 +152,28 @@ Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop o
|
|
|
83
152
|
|
|
84
153
|
每个全新子 agent 都有独立的请求缓存。父级结果追加在可复用请求前缀之后。
|
|
85
154
|
|
|
86
|
-
##
|
|
155
|
+
## 已知限制与延期工作
|
|
156
|
+
|
|
157
|
+
<a id="known-limitations-and-deferred-work"></a>
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
这些限制说明该工具尚未支持什么。它们是当前约束，不是任务积压。
|
|
161
|
+
|
|
162
|
+
- **完成由 worker 自行声明**——没有独立评估器或验证器判断目标是否完成；评估器策略与评估器驱动的延续均暂缓。
|
|
163
|
+
- **仅支持前台**——没有 job id、后台收集、进程恢复检查点、调度器或基于挂钟时间的启动策略。
|
|
164
|
+
- **工作区是唯一的跨 Round 长期记忆**——一份有界报告作为显式交接，每个子 agent 结束后，未提交的对话推理都会消失。
|
|
165
|
+
- **一个 Round 对应一个全新子 agent**——Round 内没有扇出、模型或提供方切换、fork 上下文或由模型调用选择的提供方。
|
|
166
|
+
- **普通子 agent 失败会终止运行**——固定脚本报告失败的 Round 与上一次成功交接，但不会重试；致命的工作流基础设施失败可能在该状态返回前结束。
|
|
167
|
+
- **聚合工作量仅受 Round 数量限制**——token、价格与耗时预算均暂缓。
|
|
168
|
+
|
|
169
|
+
<a id="dev-note"></a>
|
|
170
|
+
### 开发备注
|
|
171
|
+
|
|
172
|
+
<details>
|
|
173
|
+
<summary>维护者的工作上下文——点击展开</summary>
|
|
174
|
+
|
|
175
|
+
本开发备注是维护者的工作上下文：尚未决定的开放方向。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码与相关 Agent Note 为准。
|
|
176
|
+
|
|
177
|
+
开放方向：带评估器驱动延续的独立评估器；Round 内扇出与提供方选择；以及 Round 上限之外的 token、价格与耗时预算。
|
|
87
178
|
|
|
88
|
-
|
|
89
|
-
- **仅支持前台**：没有 job id、后台收集、进程恢复检查点、调度器或基于挂钟时间的启动策略。
|
|
90
|
-
- **工作区是唯一的跨 Round 长期记忆**：一份有界报告作为显式交接内容，每个子 agent 结束后，未提交的对话推理都会消失。
|
|
91
|
-
- **一个 Round 对应一个全新子 agent**：Round 内没有扇出、模型/提供方切换、fork 上下文或由模型调用选择的提供方。
|
|
92
|
-
- **普通子 agent 失败会终止运行**：固定脚本报告失败的 Round 和上一次成功交接，但不会重试；致命的工作流基础设施失败可能在该状态返回前结束。
|
|
93
|
-
- **聚合工作量仅受 Round 数量限制**：token、价格和耗时预算均暂缓处理。
|
|
179
|
+
</details>
|
package/lib/index.js
CHANGED
|
@@ -294,7 +294,7 @@ function apply(ctx, config) {
|
|
|
294
294
|
const resolved = resolveConfig(config);
|
|
295
295
|
ctx.systemPrompt.section({
|
|
296
296
|
name: "tool:ralph",
|
|
297
|
-
order:
|
|
297
|
+
order: ctx.systemPrompt.getSectionOrder("TOOL_RALPH"),
|
|
298
298
|
text: "Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out."
|
|
299
299
|
});
|
|
300
300
|
ctx.tools.register(defineTool({
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@deepseek-ai/dsh-tool-ralph",
|
|
3
3
|
"description": "Model-facing fresh-agent Ralph loop over the workflow and subagent seams",
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.2-alpha.2",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
7
7
|
},
|
|
@@ -32,33 +32,34 @@
|
|
|
32
32
|
],
|
|
33
33
|
"license": "MIT",
|
|
34
34
|
"peerDependencies": {
|
|
35
|
-
"@deepseek-ai/dsh-
|
|
36
|
-
"@deepseek-ai/dsh-llm": "^0.1.
|
|
37
|
-
"@deepseek-ai/dsh-system-prompt": "^0.1.
|
|
38
|
-
"@deepseek-ai/dsh-
|
|
39
|
-
"@deepseek-ai/dsh-
|
|
40
|
-
"@deepseek-ai/dsh-workflow": "^0.1.
|
|
41
|
-
"@deepseek-ai/
|
|
42
|
-
"@deepseek-ai/
|
|
35
|
+
"@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
|
|
36
|
+
"@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
|
|
37
|
+
"@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
|
|
38
|
+
"@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
|
|
39
|
+
"@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
|
|
40
|
+
"@deepseek-ai/dsh-workflow": "^0.1.2-alpha.2",
|
|
41
|
+
"@deepseek-ai/cordis": "^4.0.2",
|
|
42
|
+
"@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2"
|
|
43
43
|
},
|
|
44
44
|
"dependencies": {
|
|
45
|
-
"@deepseek-ai/schemastery": "^3.18.
|
|
45
|
+
"@deepseek-ai/schemastery": "^3.18.2"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|
|
48
|
-
"@deepseek-ai/cordis-plugin-loader": "^1.0.
|
|
49
|
-
"@deepseek-ai/dsh-agent": "^0.1.
|
|
50
|
-
"@deepseek-ai/dsh-agent-loop": "^0.1.
|
|
51
|
-
"@deepseek-ai/dsh-agent-loop-testkit": "^0.1.
|
|
52
|
-
"@deepseek-ai/dsh-invariants": "^0.1.
|
|
53
|
-
"@deepseek-ai/dsh-
|
|
54
|
-
"@deepseek-ai/dsh-
|
|
55
|
-
"@deepseek-ai/dsh-subagent": "^0.1.
|
|
56
|
-
"@deepseek-ai/dsh-subagent-spawn-in-process": "^0.1.
|
|
57
|
-
"@deepseek-ai/dsh-system-prompt": "^0.1.
|
|
58
|
-
"@deepseek-ai/dsh-tools": "^0.1.
|
|
59
|
-
"@deepseek-ai/dsh-workflow": "^0.1.
|
|
60
|
-
"@deepseek-ai/dsh-workflow-worker-thread": "^0.1.
|
|
61
|
-
"@deepseek-ai/
|
|
62
|
-
"@deepseek-ai/
|
|
48
|
+
"@deepseek-ai/cordis-plugin-loader": "^1.0.3",
|
|
49
|
+
"@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
|
|
50
|
+
"@deepseek-ai/dsh-agent-loop": "^0.1.2-alpha.2",
|
|
51
|
+
"@deepseek-ai/dsh-agent-loop-testkit": "^0.1.2-alpha.2",
|
|
52
|
+
"@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
|
|
53
|
+
"@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
|
|
54
|
+
"@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
|
|
55
|
+
"@deepseek-ai/dsh-subagent-in-process-driver": "^0.1.2-alpha.2",
|
|
56
|
+
"@deepseek-ai/dsh-subagent-spawn-in-process": "^0.1.2-alpha.2",
|
|
57
|
+
"@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
|
|
58
|
+
"@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
|
|
59
|
+
"@deepseek-ai/dsh-workflow": "^0.1.2-alpha.2",
|
|
60
|
+
"@deepseek-ai/dsh-workflow-worker-thread": "^0.1.2-alpha.2",
|
|
61
|
+
"@deepseek-ai/cordis": "^4.0.2",
|
|
62
|
+
"@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
|
|
63
|
+
"@deepseek-ai/dsh-llm": "^0.1.2-alpha.2"
|
|
63
64
|
}
|
|
64
65
|
}
|