@xiangyixie/dsh-superagent 0.14.3 → 0.14.5

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/CHANGELOG.md CHANGED
@@ -8,6 +8,65 @@ along with the next code release. A doc-only version leaves `lib/` and `bin/`
8
8
  byte-identical to the version before it, and the pinned install line in the
9
9
  README is updated to the version being released.
10
10
 
11
+ ## 0.14.5 — 2026-11-16
12
+
13
+ 这次只做一件事:把插件自己占的地方变小,能力一个不少。
14
+
15
+ ### 变化
16
+
17
+ - **常驻开销降了 77%。** 每次请求都会带上插件的工具说明和一句引导语,这部分
18
+ 从约 4,923 token 降到约 1,139 token(同一宿主、同一模型实测)。工具描述不再
19
+ 写长篇使用手册,只留"什么时候该用它";详细说明放到工具真正被调用时返回。
20
+ - **常用工具直接可见,冷门能力按需展开。** 默认只声明 8 个常用工具:起 run、
21
+ 查状态、列表、取消、恢复、追加指令、回答提问,以及 `superagent_help`。长期
22
+ 目标、定时任务、实时插话、跨 run 笔记、模板、审计这 6 个不常用工具不会一
23
+ 直占着上下文;需要时先调一次 `superagent_help`,它们在下一步自动出现在工具
24
+ 列表里,会话按需记住这个状态。
25
+ - **引导语每个会话只出现一次。** 以前每个 turn 都会再塞一份,长会话里越来越
26
+ 占地方;现在只在会话开始时注入一次,内容也缩短了。
27
+
28
+ ### 对使用者的影响
29
+
30
+ - 工具名、参数、行为都没有变;已经在用的工作流照常跑。
31
+ - 需要定时任务、长期目标这类能力时,模型会自己先调 `superagent_help`,不需要
32
+ 你额外提示;展开后用法与之前一致。
33
+ - 新增回归测试钉住"一次请求固定带上的工具定义 + 引导语"的上限,超了测试就
34
+ 失败,避免以后又把开销涨回去。
35
+
36
+ ## 0.14.4 — 2026-11-16
37
+
38
+ This release gives a goal a life longer than one run, and fixes a check that
39
+ could not see a file that was already on disk.
40
+
41
+ ### Added
42
+
43
+ - **Long-term goals.** `superagent_goal` takes one goal and splits it into
44
+ ordered phases; each phase is still an ordinary run, so planning, parallel
45
+ subtasks, budgets, attention items, reports and resume keep working the way
46
+ they already did. Phases run in dependency order, retry within a budget, and
47
+ survive a host restart: a phase already finished is not planned again, and a
48
+ goal picks up from where the disk says it stopped. When a phase runs out of
49
+ budget, keeps failing without progress, or its worker and the machine check
50
+ disagree about the result, the goal stops and asks the person to decide —
51
+ `superagent_status` shows both sides of the evidence and the options (accept,
52
+ retry, stop) instead of guessing. The design is in `docs/LONG-GOAL.md`, now
53
+ shipped with the package.
54
+ - The plugin mounts thirteen tools; the new one is listed in the README.
55
+
56
+ ### Fixed
57
+
58
+ - **A deliverable that is on disk is no longer reported as missing.** In goal
59
+ mode the deliverable check resolved declared paths against the directory the
60
+ host was launched from, while the worker wrote into the goal's workspace. The
61
+ file existed, the check looked elsewhere, and the subtask failed with
62
+ `declared deliverable missing` — then retried with a fresh worker until the
63
+ attempts ran out. The check now uses the same base directory as the goal's
64
+ own acceptance step. Relative and absolute declarations, either separator,
65
+ and a different case on Windows all name the same file, and an absolute path
66
+ outside the workspace is still refused. A write that becomes visible only
67
+ just after the check starts is re-read inside a bounded 150 ms window; a file
68
+ that is never written still fails as missing.
69
+
11
70
  ## 0.14.3 — 2026-11-15
12
71
 
13
72
  The release is about the three things a run could not answer for itself: which
package/README.en.md CHANGED
@@ -27,7 +27,7 @@ filesystem; this is not a sandbox.
27
27
  in the environment:
28
28
 
29
29
  ```bash
30
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
30
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.5
31
31
  ```
32
32
 
33
33
  Then ask the session for a run — a real call, not a sketch:
@@ -40,8 +40,8 @@ covers the path from an empty machine, including the reason not to install npm's
40
40
  unrelated `dsh` package by name.
41
41
 
42
42
  It adds no in-host UI (the workspace panel and the conversation console are
43
- loopback pages) and patches no host code: the twelve `superagent_*` tools are the
44
- surface, plus six optional operator utilities (a terminal panel, an HTML report,
43
+ loopback pages) and patches no host code: the fourteen `superagent_*` tools are the
44
+ surface (eight declared by default, six more expanded on demand), plus six optional operator utilities (a terminal panel, an HTML report,
45
45
  an install doctor, a run archive, git sync, and the workspace panel) that read the
46
46
  same run files. Browser and desktop control is a separate layer: with
47
47
  `runtime.enabled` set, fourteen more tools are registered, and with the default
@@ -80,7 +80,7 @@ your `PATH`, use `npx @deepseek-ai/dsh@0.2.2-rc.1` instead.
80
80
 
81
81
  ```bash
82
82
  # 1. install the plugin into a profile (web, headless, ... whatever you run)
83
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
83
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.5
84
84
 
85
85
  # 2. confirm the bundle row exists in the merged config
86
86
  dsh --profile web --dump-config
@@ -101,8 +101,8 @@ The desktop app's **Add plugin** dialog accepts the same three forms:
101
101
 
102
102
  | Dialog input | Value | What it does |
103
103
  | --- | --- | --- |
104
- | Package name | `@xiangyixie/dsh-superagent@0.14.3` | Installs from npm. Name the version (see below). |
105
- | GitHub repository | `https://github.com/LittleChenLiya/dsh-superagent` | Installs from the repository. Add `#v0.14.3` if you need a fixed release. |
104
+ | Package name | `@xiangyixie/dsh-superagent@0.14.5` | Installs from npm. Name the version (see below). |
105
+ | GitHub repository | `https://github.com/LittleChenLiya/dsh-superagent` | Installs from the repository. Add `#v0.14.5` if you need a fixed release. |
106
106
  | Local directory | `file:/absolute/path/to/dsh-superagent` | Copies the checkout. Re-add after changing the source. |
107
107
 
108
108
  Upgrading is remove-then-add, not in-place: remove the old copy
@@ -271,7 +271,7 @@ Row config in `<profile>/cordis.patch.yml`:
271
271
  | `controlPort` | off | Loopback port for the embedding surface; `0` picks a free one. See [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md). |
272
272
  | `workspaceIsolation` | `false` | Give every worker its own git worktree so parallel workers cannot overwrite each other. See [Per-worker workspace isolation](#per-worker-workspace-isolation). |
273
273
  | `workspaceRoot` | session directory (see `workspaceBase`) | Repository the workers are isolated in when `workspaceIsolation` is on. Must be a git working tree with at least one commit. |
274
- | `workspaceBase` | `session` | What isolation is based on. `session` uses the current session's directory (or the repository root git resolves from it) and honours `workspaceRoot` only when it names the same directory; `config` restores the old behaviour of always using `workspaceRoot`. A mismatch prints `workspace warning` in status and in the log instead of silently isolating in another project. |
274
+ | `workspaceBase` | `session` | What isolation is based on. `session` uses the current session's directory (or the repository root git resolves from it) and honours `workspaceRoot` only when it names the same directory; `config` restores the old behaviour of always using `workspaceRoot`. A mismatch prints `workspace warning` in status and in the log instead of silently isolating in another project. |
275
275
  | `workbenchPort` | off | Loopback port for the local workspace panel; `0` picks a free one. The panel reads and edits files itself, without a host API. |
276
276
  | `workbenchRoot` | `process.cwd()` | Directory the panel may browse and edit. Every path outside it is refused. |
277
277
  | `consolePort` | off | Loopback port for the conversation console; `0` picks a free one. Requires the host `sessionController` service. |
@@ -823,7 +823,7 @@ lookup, one edit, one command, one short piece of writing — does not need a ru
823
823
  (project rules), `profile` (user preferences), or the run scope. `search`
824
824
  ranks notes against `query` (the current goal works well) and/or exact `tags`,
825
825
  so a relevant old note is found instead of only the newest ones; notes can
826
- carry `tags` when set. The tool is additive: the eleven other tools keep their
826
+ carry `tags` when set. The tool is additive: the twelve other tools keep their
827
827
  arguments and output.
828
828
  - `superagent_template(action, id?, params?, template?, limit?)` lists, shows,
829
829
  expands, saves, or deletes a workflow template: a fixed goal skeleton with
@@ -841,6 +841,18 @@ lookup, one edit, one command, one short piece of writing — does not need a ru
841
841
  goal (or an expanded template), a clock, and its own limits; it survives a host
842
842
  restart and starts runs nobody asked for. Nothing is armed until a plan exists.
843
843
  See [Scheduled runs](#scheduled-runs).
844
+ - `superagent_goal(action, goal_id?, goal?, phases?, cwd?, budget?, phase_budget?,
845
+ max_parallel_phases?, max_attempts_per_phase?, auto_resume?, decision_id?, answer?,
846
+ note?, limit?)` turns one natural-language goal into dependent phases, each phase
847
+ an ordinary run, advancing up to `max_parallel_phases` at once and surviving a host
848
+ restart. `create` decomposes with one direct run when `phases` is omitted;
849
+ `status`/`list` report phase state, run ids, usage, and open decisions; `answer`
850
+ settles phase-exhausted, verification-conflict, and stalled decisions;
851
+ `pause`/`resume`/`cancel` govern the whole goal. A phase budget is clamped to what
852
+ the goal has left, and the goal budget sums every phase, retry, and decompose run.
853
+ It extends the run engine rather than replacing it: planner, dependency graph,
854
+ budgets, attention, persistence, and resume are the same code. See
855
+ [docs/LONG-GOAL.md](docs/LONG-GOAL.md).
844
856
  - `superagent_audit(run_id?, subtask_id?, kind?, decision?, result?, target?,
845
857
  since?, until?, limit?, order?, format?, out_path?)` reads the audit trail, or
846
858
  exports the matching events as one JSONL or CSV file. See
@@ -1294,7 +1306,7 @@ records the command plus a zero-external-reference audit.
1294
1306
  does. It reads only: no install, no mount, no edit to the profile. One block per
1295
1307
  check — imported files against the `files` whitelist, declared files against
1296
1308
  what is on disk, the installed copy against the published tarball for its
1297
- version, the profile's bundle registration, and the twelve registered tools — each
1309
+ version, the profile's bundle registration, and the fourteen registered tools — each
1298
1310
  failure followed by the command that fixes it.
1299
1311
 
1300
1312
  ```bash
@@ -1778,7 +1790,7 @@ appears to "hang" until the ignored-abort child returns.
1778
1790
 
1779
1791
  | What you see | What it means | What to do |
1780
1792
  | --- | --- | --- |
1781
- | `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.3` and read the host log for `[dsh-superagent]` lines. |
1793
+ | `superagent_*` tools do not exist | The bundle row is not mounted, or the host refused to load the plugin. | Run `--dump-config` and check for the `@xiangyixie/dsh-superagent` block; reinstall with `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.5` and read the host log for `[dsh-superagent]` lines. |
1782
1794
  | `Cannot find module .../lib/control.js` (or `watch.js` / `report.js` / `wizard.js`), or `[dsh-superagent] dsh-superagent failed to load because a file it imports is missing: ...` in the host log | The copy in that profile is incomplete — an `add` that was interrupted leaves a partial extraction. From 0.14.3 the entry point names the missing file itself. The published package is not the cause: every version ships all thirty-four `lib/` files. | Delete the plugin's directory under the profile's `node_modules` (scoped `@xiangyixie/dsh-superagent`, or unscoped `dsh-superagent` from an older tarball install) and run the same `add` command again, with the version number. Do not copy files in by hand. |
1783
1795
  | `[error] the model provider rejected the API key` | The key env var is missing in the process that started the host. | Export `DEEPSEEK_API_KEY` (the default route) or the variable your route names, then restart `dsh`. |
1784
1796
  | `MISSING_CREDENTIAL ... no API key for provider route "..."` | The profile's route has no credential in the environment. | Set the env var named for that route and restart. The error line names the route, so use that, not this page. |
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
 
11
11
  **以下情况不要用它**:一次模型调用就能答完的时候——那样你只是在为 planner 和 aggregator 额外付钱。必须在一轮之内结束的工作、中间需要人工审批的步骤、需要嵌套委派的任务(子 agent 深度上限为 1)、以及想要宿主内嵌面板的人,也不适合;下文那个可选的工作区面板是回环地址上的网页,不是宿主 UI。子 agent 运行时用的是宿主的凭据和文件系统,这里不是沙箱。
12
12
 
13
- 它不添加宿主内 UI(工作区面板和对话控制台都是回环页面),也不修改宿主代码:对外的接口就是十二个 `superagent_*` 工具,另外还有六个可选的运维工具(终端面板、HTML 报告、安装自检、run 归档、git 同步、工作区面板),它们读的是同一批 run 文件。浏览器与桌面控制是独立的一层:设置 `runtime.enabled` 后会再注册十四个工具;默认值是 `false`,此时这些工具一个都不存在。
13
+ 它不添加宿主内 UI(工作区面板和对话控制台都是回环页面),也不修改宿主代码:对外的接口就是十四个 `superagent_*` 工具(默认只声明其中 8 个,其余 6 个按需展开),另外还有六个可选的运维工具(终端面板、HTML 报告、安装自检、run 归档、git 同步、工作区面板),它们读的是同一批 run 文件。浏览器与桌面控制是独立的一层:设置 `runtime.enabled` 后会再注册十四个工具;默认值是 `false`,此时这些工具一个都不存在。
14
14
 
15
15
  个人项目,与 DeepSeek 及 harness 维护方无关。MIT 许可,© 2026 Admire (LittleChenLiya);详见[许可证](#许可证)。
16
16
 
@@ -18,14 +18,14 @@
18
18
 
19
19
  三种安装方式,`dsh plugin add` 和桌面应用的 **Add plugin** 对话框都接受:
20
20
 
21
- - **npm 包名**:`@xiangyixie/dsh-superagent@0.14.3`,从 npm 安装。请写明版本号,原因见下文。
22
- - **GitHub 仓库**:`https://github.com/LittleChenLiya/dsh-superagent`,从仓库安装。需要固定版本时加 `#v0.14.3`。
21
+ - **npm 包名**:`@xiangyixie/dsh-superagent@0.14.5`,从 npm 安装。请写明版本号,原因见下文。
22
+ - **GitHub 仓库**:`https://github.com/LittleChenLiya/dsh-superagent`,从仓库安装。需要固定版本时加 `#v0.14.5`。
23
23
  - **本地目录**:`file:/absolute/path/to/dsh-superagent`,拷贝本地 checkout。改过源码之后要重新 add 一次。
24
24
 
25
25
  最常用的一条命令:
26
26
 
27
27
  ```bash
28
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
28
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.5
29
29
  ```
30
30
 
31
31
  ### 从插件索引安装(可选)
@@ -85,7 +85,7 @@ npx @deepseek-ai/dsh@0.2.2-rc.1 --version
85
85
 
86
86
  ```bash
87
87
  # 1. install the plugin into a profile (web, headless, ... whatever you run)
88
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
88
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.5
89
89
 
90
90
  # 2. confirm the bundle row exists in the merged config
91
91
  dsh --profile web --dump-config
@@ -95,8 +95,8 @@ dsh --profile web --dump-config
95
95
 
96
96
  | 对话框中的栏目 | 填写值 | 作用 |
97
97
  | --- | --- | --- |
98
- | 包名(Package name) | `@xiangyixie/dsh-superagent@0.14.3` | 从 npm 安装。要写明版本号(见上文)。 |
99
- | GitHub 仓库(GitHub repository) | `https://github.com/LittleChenLiya/dsh-superagent` | 从仓库安装。需要固定版本时加 `#v0.14.3`。 |
98
+ | 包名(Package name) | `@xiangyixie/dsh-superagent@0.14.5` | 从 npm 安装。要写明版本号(见上文)。 |
99
+ | GitHub 仓库(GitHub repository) | `https://github.com/LittleChenLiya/dsh-superagent` | 从仓库安装。需要固定版本时加 `#v0.14.5`。 |
100
100
  | 本地目录(Local directory) | `file:/absolute/path/to/dsh-superagent` | 拷贝本地 checkout。改过源码后需重新 add 一次。 |
101
101
 
102
102
  安装的三种形式和升级方式见上文的[安装](#安装)一节。查一下 dump 里有没有下面这一段。如果没有,说明插件装了但没挂载,任何 `superagent_*` 工具都不会存在:
@@ -493,8 +493,11 @@ cost: ¥0.0952 + $0.0248 (estimate; all models priced)
493
493
 
494
494
  ## 工具
495
495
 
496
- 如果目标有两个及以上可独立交付的产物,或含“先做 A 才能做 B”的前置依赖,就用 `superagent_start`,不要用宿主自带的 `subagent` 自己编排:只有 run 会留下计划、并行时序和一份合并报告。顶层会话的第一步会收到一条同样意思的简短提示,子会话不会重复收到。单一动作(一次查询、一次编辑、一条命令、一段短文本)不必起 run,直接做。
496
+ 如果目标有两个及以上可独立交付的产物,或含“先做 A 才能做 B”的前置依赖,就用 `superagent_start`,不要用宿主自带的 `subagent` 自己编排:只有 run 会留下计划、并行时序和一份合并报告。每个会话开始时只会收到一次同样意思的简短提示(不再每个 turn 重复),子会话不会收到。单一动作(一次查询、一次编辑、一条命令、一段短文本)不必起 run,直接做。
497
497
 
498
+ 默认只声明 8 个常用工具(`superagent_start` / `status` / `list` / `cancel` / `resume` / `followup` / `answer` / `help`),这样每次请求固定带的工具说明很小。长期目标、定时任务、实时插话、跨 run 笔记、模板、审计这 6 个工具按需展开:先调用一次 `superagent_help`,它们会在下一步自动出现在工具列表里,本会话之后一直可用。
499
+
500
+ - `superagent_help()` 列出另外 6 个按需工具以及各自适用的场景,并为本会话展开它们。需要定时、长期目标、记忆、模板、审计或实时插话时先调用它。
498
501
  - `superagent_start(goal, mode?, queue?, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
499
502
  启动一次 run 并立刻返回 run id。`mode: "direct"` 让一个 worker 直接跑这个 goal,不要 planner 也不要 aggregator,并把该 worker 的回复原样作为报告返回——适合一次自成一体的查询、修改、检索或短写作,不适合可以并行拆开的目标。默认的 `mode: "planned"` 走完整的 planner → worker → 合并报告流程。计划中的子任务可以声明 `dependsOn` 另一个子任务:依赖方会等它,并在自己的 prompt 里拿到它的报告,而彼此独立的子任务仍然并行。依赖成环会在任何工作开始前否掉整个计划,依赖一个计划从未声明的任务则以原因跳过。两种模式产出相同的 run 记录、配额、deadline、取消和用量记账。`goal_mode: true` 增加一步验收,并在失败的轮次重新规划;见 [Goal 模式](#goal-模式)。
500
503
  `queue: true` 让 `maxActiveRuns` 占满时的启动改为等空位而不是失败:它返回 `status: "queued"` 以及
@@ -526,6 +529,15 @@ cost: ¥0.0952 + $0.0248 (estimate; all models priced)
526
529
  - `superagent_schedule(action, id?, name?, goal?, template_id?, params?, cron?,
527
530
  every_minutes?, timezone?, miss_policy?, goal_mode?, acceptance?, max_rounds?,
528
531
  max_wall_clock_minutes?, no_progress_rounds?, budget?, human_priority?)` 创建、列出、暂停、恢复、删除或立即运行一个定时计划。计划保存一个 goal(或展开后的模板)、一个时钟和它自己的限额;它能跨宿主重启存活,并启动没人手动发起的 run。没有计划之前不会武装任何东西。见[定时运行](#定时运行)。
532
+ - `superagent_goal(action, goal_id?, goal?, phases?, cwd?, budget?, phase_budget?,
533
+ max_parallel_phases?, max_attempts_per_phase?, auto_resume?, decision_id?, answer?,
534
+ note?, limit?)` 把一个自然语言目标拆成有依赖关系的阶段,每个阶段是一个普通 run,按
535
+ `max_parallel_phases` 并行推进,跨宿主重启不丢。`create` 在没给 `phases` 时先用一次
536
+ direct run 拆阶段;`status`/`list` 给出阶段状态、run id、用量和待决策项;`answer` 结算
537
+ 阶段耗尽、验收证据冲突和停滞决策;`pause`/`resume`/`cancel` 管住整个目标。阶段预算收紧到
538
+ 目标剩余额度,目标预算合计所有阶段、重试和拆阶段 run。它扩展而不是替换 run:
539
+ planner、子任务依赖图、预算、attention、持久化和 resume 还是同一套,见
540
+ [docs/LONG-GOAL.md](docs/LONG-GOAL.md)。
529
541
  - `superagent_audit(run_id?, subtask_id?, kind?, decision?, result?, target?,
530
542
  since?, until?, limit?, order?, format?, out_path?)` 读审计轨迹,或把匹配的事件导出成一个 JSONL 或 CSV 文件。见
531
543
  [权限与审计](#权限与审计)。
@@ -1140,7 +1152,7 @@ SHA-256)。`--format html` 把同样的内容写成一个自包含
1140
1152
 
1141
1153
  | 你看到的 | 含义 | 怎么办 |
1142
1154
  | --- | --- | --- |
1143
- | `superagent_*` 工具不存在 | bundle 行没挂上,或者宿主拒绝加载插件。 | 跑 `--dump-config` 查 `@xiangyixie/dsh-superagent` 块;用 `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.3` 重装,并在宿主日志里找 `[dsh-superagent]` 行。 |
1155
+ | `superagent_*` 工具不存在 | bundle 行没挂上,或者宿主拒绝加载插件。 | 跑 `--dump-config` 查 `@xiangyixie/dsh-superagent` 块;用 `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.5` 重装,并在宿主日志里找 `[dsh-superagent]` 行。 |
1144
1156
  | `Cannot find module .../lib/control.js`(或 `watch.js` / `report.js` / `wizard.js`),或宿主日志里的 `[dsh-superagent] dsh-superagent failed to load because a file it imports is missing: ...` | 那个 profile 里的副本不完整——被中断的 `add` 会留下残缺的解包结果。0.14.3 起的入口会直接点名缺哪个文件。已发布的包不是原因:每个版本都带全部三十四个 `lib/` 文件。 | 删掉 profile 的 `node_modules` 下该插件的目录(带 scope 的 `@xiangyixie/dsh-superagent`,或旧 tarball 安装留下的无 scope 的 `dsh-superagent`),再用同一条 `add` 命令重装,并带上版本号。不要手工拷贝文件进去。 |
1145
1157
  | `[error] the model provider rejected the API key` | 启动宿主的那个进程里缺 key 环境变量。 | 导出 `DEEPSEEK_API_KEY`(默认路由)或你那条路由声明的变量,然后重启 `dsh`。 |
1146
1158
  | `MISSING_CREDENTIAL ... no API key for provider route "..."` | profile 的路由在环境里没有凭据。 | 设置该路由对应的环境变量并重启。错误行里写了路由名,以它为准,不要照本文。 |
package/README.zh.md CHANGED
@@ -10,7 +10,7 @@
10
10
 
11
11
  **以下情况不要用它**:一次模型调用就能答完的时候——那样你只是在为 planner 和 aggregator 额外付钱。必须在一轮之内结束的工作、中间需要人工审批的步骤、需要嵌套委派的任务(子 agent 深度上限为 1)、以及想要宿主内嵌面板的人,也不适合;下文那个可选的工作区面板是回环地址上的网页,不是宿主 UI。子 agent 运行时用的是宿主的凭据和文件系统,这里不是沙箱。
12
12
 
13
- 它不添加宿主内 UI(工作区面板和对话控制台都是回环页面),也不修改宿主代码:对外的接口就是十二个 `superagent_*` 工具,另外还有六个可选的运维工具(终端面板、HTML 报告、安装自检、run 归档、git 同步、工作区面板),它们读的是同一批 run 文件。浏览器与桌面控制是独立的一层:设置 `runtime.enabled` 后会再注册十四个工具;默认值是 `false`,此时这些工具一个都不存在。
13
+ 它不添加宿主内 UI(工作区面板和对话控制台都是回环页面),也不修改宿主代码:对外的接口就是十四个 `superagent_*` 工具(默认只声明其中 8 个,其余 6 个按需展开),另外还有六个可选的运维工具(终端面板、HTML 报告、安装自检、run 归档、git 同步、工作区面板),它们读的是同一批 run 文件。浏览器与桌面控制是独立的一层:设置 `runtime.enabled` 后会再注册十四个工具;默认值是 `false`,此时这些工具一个都不存在。
14
14
 
15
15
  个人项目,与 DeepSeek 及 harness 维护方无关。MIT 许可,© 2026 Admire (LittleChenLiya);详见[许可证](#许可证)。
16
16
 
@@ -18,14 +18,14 @@
18
18
 
19
19
  三种安装方式,`dsh plugin add` 和桌面应用的 **Add plugin** 对话框都接受:
20
20
 
21
- - **npm 包名**:`@xiangyixie/dsh-superagent@0.14.3`,从 npm 安装。请写明版本号,原因见下文。
22
- - **GitHub 仓库**:`https://github.com/LittleChenLiya/dsh-superagent`,从仓库安装。需要固定版本时加 `#v0.14.3`。
21
+ - **npm 包名**:`@xiangyixie/dsh-superagent@0.14.5`,从 npm 安装。请写明版本号,原因见下文。
22
+ - **GitHub 仓库**:`https://github.com/LittleChenLiya/dsh-superagent`,从仓库安装。需要固定版本时加 `#v0.14.5`。
23
23
  - **本地目录**:`file:/absolute/path/to/dsh-superagent`,拷贝本地 checkout。改过源码之后要重新 add 一次。
24
24
 
25
25
  最常用的一条命令:
26
26
 
27
27
  ```bash
28
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
28
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.5
29
29
  ```
30
30
 
31
31
  ### 从插件索引安装(可选)
@@ -85,7 +85,7 @@ npx @deepseek-ai/dsh@0.2.2-rc.1 --version
85
85
 
86
86
  ```bash
87
87
  # 1. install the plugin into a profile (web, headless, ... whatever you run)
88
- dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.3
88
+ dsh plugin --profile web add @xiangyixie/dsh-superagent@0.14.5
89
89
 
90
90
  # 2. confirm the bundle row exists in the merged config
91
91
  dsh --profile web --dump-config
@@ -95,8 +95,8 @@ dsh --profile web --dump-config
95
95
 
96
96
  | 对话框中的栏目 | 填写值 | 作用 |
97
97
  | --- | --- | --- |
98
- | 包名(Package name) | `@xiangyixie/dsh-superagent@0.14.3` | 从 npm 安装。要写明版本号(见上文)。 |
99
- | GitHub 仓库(GitHub repository) | `https://github.com/LittleChenLiya/dsh-superagent` | 从仓库安装。需要固定版本时加 `#v0.14.3`。 |
98
+ | 包名(Package name) | `@xiangyixie/dsh-superagent@0.14.5` | 从 npm 安装。要写明版本号(见上文)。 |
99
+ | GitHub 仓库(GitHub repository) | `https://github.com/LittleChenLiya/dsh-superagent` | 从仓库安装。需要固定版本时加 `#v0.14.5`。 |
100
100
  | 本地目录(Local directory) | `file:/absolute/path/to/dsh-superagent` | 拷贝本地 checkout。改过源码后需重新 add 一次。 |
101
101
 
102
102
  安装的三种形式和升级方式见上文的[安装](#安装)一节。查一下 dump 里有没有下面这一段。如果没有,说明插件装了但没挂载,任何 `superagent_*` 工具都不会存在:
@@ -209,7 +209,7 @@ report:
209
209
  | `controlPort` | 关 | 嵌入接口的回环端口;`0` 让系统挑一个空闲端口。见 [docs/embedding.md](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/embedding.md)。 |
210
210
  | `workspaceIsolation` | `false` | 给每个 worker 一个自己的 git worktree,避免并行 worker 互相覆盖。见[按 worker 隔离工作区](#按-worker-隔离工作区)。 |
211
211
  | `workspaceRoot` | 会话目录(见 `workspaceBase`) | `workspaceIsolation` 打开时,worker 在其中被隔离的仓库。必须是至少有一次提交的 git 工作树。 |
212
- | `workspaceBase` | `session` | 隔离的基准目录。`session` 用当前会话的目录(或 git 从它解析出的仓库根),`workspaceRoot` 只有指向同一目录时才生效;`config` 恢复旧行为,始终使用 `workspaceRoot`。两者不一致时 status 打印 `workspace warning`,并在日志里说明,不会静默改用另一个项目。 |
212
+ | `workspaceBase` | `session` | 隔离的基准目录。`session` 用当前会话的目录(或 git 从它解析出的仓库根),`workspaceRoot` 只有指向同一目录时才生效;`config` 恢复旧行为,始终使用 `workspaceRoot`。两者不一致时 status 打印 `workspace warning`,并在日志里说明,不会静默改用另一个项目。 |
213
213
  | `workbenchPort` | 关 | 本地工作区面板的回环端口;`0` 让系统挑一个空闲端口。面板自己读写文件,不经过宿主 API。 |
214
214
  | `workbenchRoot` | `process.cwd()` | 面板可以浏览和编辑的目录。它之外的任何路径都会被拒绝。 |
215
215
  | `consolePort` | 关 | 对话控制台的回环端口;`0` 让系统挑一个空闲端口。需要宿主的 `sessionController` 服务。 |
@@ -493,8 +493,11 @@ cost: ¥0.0952 + $0.0248 (estimate; all models priced)
493
493
 
494
494
  ## 工具
495
495
 
496
- 如果目标有两个及以上可独立交付的产物,或含“先做 A 才能做 B”的前置依赖,就用 `superagent_start`,不要用宿主自带的 `subagent` 自己编排:只有 run 会留下计划、并行时序和一份合并报告。顶层会话的第一步会收到一条同样意思的简短提示,子会话不会重复收到。单一动作(一次查询、一次编辑、一条命令、一段短文本)不必起 run,直接做。
496
+ 如果目标有两个及以上可独立交付的产物,或含“先做 A 才能做 B”的前置依赖,就用 `superagent_start`,不要用宿主自带的 `subagent` 自己编排:只有 run 会留下计划、并行时序和一份合并报告。每个会话开始时只会收到一次同样意思的简短提示(不再每个 turn 重复),子会话不会收到。单一动作(一次查询、一次编辑、一条命令、一段短文本)不必起 run,直接做。
497
497
 
498
+ 默认只声明 8 个常用工具(`superagent_start` / `status` / `list` / `cancel` / `resume` / `followup` / `answer` / `help`),这样每次请求固定带的工具说明很小。长期目标、定时任务、实时插话、跨 run 笔记、模板、审计这 6 个工具按需展开:先调用一次 `superagent_help`,它们会在下一步自动出现在工具列表里,本会话之后一直可用。
499
+
500
+ - `superagent_help()` 列出另外 6 个按需工具以及各自适用的场景,并为本会话展开它们。需要定时、长期目标、记忆、模板、审计或实时插话时先调用它。
498
501
  - `superagent_start(goal, mode?, queue?, max_subtasks?, max_parallel?, deadline_minutes?, allow_duplicate?, wait_seconds?)`
499
502
  启动一次 run 并立刻返回 run id。`mode: "direct"` 让一个 worker 直接跑这个 goal,不要 planner 也不要 aggregator,并把该 worker 的回复原样作为报告返回——适合一次自成一体的查询、修改、检索或短写作,不适合可以并行拆开的目标。默认的 `mode: "planned"` 走完整的 planner → worker → 合并报告流程。计划中的子任务可以声明 `dependsOn` 另一个子任务:依赖方会等它,并在自己的 prompt 里拿到它的报告,而彼此独立的子任务仍然并行。依赖成环会在任何工作开始前否掉整个计划,依赖一个计划从未声明的任务则以原因跳过。两种模式产出相同的 run 记录、配额、deadline、取消和用量记账。`goal_mode: true` 增加一步验收,并在失败的轮次重新规划;见 [Goal 模式](#goal-模式)。
500
503
  `queue: true` 让 `maxActiveRuns` 占满时的启动改为等空位而不是失败:它返回 `status: "queued"` 以及
@@ -521,11 +524,20 @@ cost: ¥0.0952 + $0.0248 (estimate; all models priced)
521
524
  - `superagent_memory(action, key?, kind?, text?, scope?, query?, tags?, limit?)`
522
525
  列出、搜索、添加、更正或遗忘笔记本里的笔记。`set` 一个已存在的 key 会取代旧的;`forget` 撤回它。`scope` 指向 `rules`
523
526
  (项目规则)、`profile`(用户偏好),或 run scope。`search`
524
- 按 `query`(当前 goal 效果不错)和/或精确 `tags` 给笔记排序,于是相关的老笔记能被找到,而不只是最新的几条;笔记在设置时可以携带 `tags`。这个工具是增量的:另外十一个工具的参数和输出都不变。
527
+ 按 `query`(当前 goal 效果不错)和/或精确 `tags` 给笔记排序,于是相关的老笔记能被找到,而不只是最新的几条;笔记在设置时可以携带 `tags`。这个工具是增量的:另外十二个工具的参数和输出都不变。
525
528
  - `superagent_template(action, id?, params?, template?, limit?)` 列出、展示、展开、保存或删除一个工作流模板:一个固定的 goal 骨架,带必需参数、适用场景和不适用场景。`expand` 返回一个普通 goal 字符串,`superagent_start` 会像对待手打的 goal 一样规划它;缺失或为空的参数会按名字被拒绝,而不是取默认值。模板不能设置限额、预算、模式或覆盖项,所以用模板永远不会扩大 run 的权限。内置 id 只读;自定义模板放在状态目录的模板目录下,那里的失败会被记录,但不会让 run 工具失效。
526
529
  - `superagent_schedule(action, id?, name?, goal?, template_id?, params?, cron?,
527
530
  every_minutes?, timezone?, miss_policy?, goal_mode?, acceptance?, max_rounds?,
528
531
  max_wall_clock_minutes?, no_progress_rounds?, budget?, human_priority?)` 创建、列出、暂停、恢复、删除或立即运行一个定时计划。计划保存一个 goal(或展开后的模板)、一个时钟和它自己的限额;它能跨宿主重启存活,并启动没人手动发起的 run。没有计划之前不会武装任何东西。见[定时运行](#定时运行)。
532
+ - `superagent_goal(action, goal_id?, goal?, phases?, cwd?, budget?, phase_budget?,
533
+ max_parallel_phases?, max_attempts_per_phase?, auto_resume?, decision_id?, answer?,
534
+ note?, limit?)` 把一个自然语言目标拆成有依赖关系的阶段,每个阶段是一个普通 run,按
535
+ `max_parallel_phases` 并行推进,跨宿主重启不丢。`create` 在没给 `phases` 时先用一次
536
+ direct run 拆阶段;`status`/`list` 给出阶段状态、run id、用量和待决策项;`answer` 结算
537
+ 阶段耗尽、验收证据冲突和停滞决策;`pause`/`resume`/`cancel` 管住整个目标。阶段预算收紧到
538
+ 目标剩余额度,目标预算合计所有阶段、重试和拆阶段 run。它扩展而不是替换 run:
539
+ planner、子任务依赖图、预算、attention、持久化和 resume 还是同一套,见
540
+ [docs/LONG-GOAL.md](docs/LONG-GOAL.md)。
529
541
  - `superagent_audit(run_id?, subtask_id?, kind?, decision?, result?, target?,
530
542
  since?, until?, limit?, order?, format?, out_path?)` 读审计轨迹,或把匹配的事件导出成一个 JSONL 或 CSV 文件。见
531
543
  [权限与审计](#权限与审计)。
@@ -793,7 +805,7 @@ worker 的重试链和它占 run 墙钟的比例列在结果旁边,所以一
793
805
  [docs/e2e/transcripts/report-cli.log](https://github.com/LittleChenLiya/dsh-superagent/blob/main/docs/e2e/transcripts/report-cli.log)
794
806
  记录了命令本身,以及一次零外部引用的审计。
795
807
 
796
- **`doctor`** 在宿主之前回答"装是装上了,为什么什么都不工作?"。它只读:不安装、不挂载、不修改 profile。每项检查一个块——导入的文件对 `files` 白名单、声明的文件对磁盘实况、已安装副本对同版本已发布的 tarball、profile 的 bundle 注册,以及注册的十二个工具——每个失败后面跟着能修好它的命令。
808
+ **`doctor`** 在宿主之前回答"装是装上了,为什么什么都不工作?"。它只读:不安装、不挂载、不修改 profile。每项检查一个块——导入的文件对 `files` 白名单、声明的文件对磁盘实况、已安装副本对同版本已发布的 tarball、profile 的 bundle 注册,以及注册的十三个工具——每个失败后面跟着能修好它的命令。
797
809
 
798
810
  ```bash
799
811
  PKG="${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@xiangyixie/dsh-superagent"
@@ -911,8 +923,8 @@ curl -s -H "Authorization: Bearer $TOKEN" "$URL/runs"
911
923
  事件流)都返回 `401`,而每个带非回环
912
924
  `Host` 头的请求返回 `403`。
913
925
 
914
- 第一次使用时,页面上的「首次使用向导」按顺序走:检查环境 → 验证 API key(真的请求端点,通过了才写任何东西)→ 预览并保存 profile patch → 在一个临时目录里跑一次真实的 trial run。每次保存前会留一份可回滚的 patch 备份(保留最近 10 次),密钥只交给宿主的凭据存储,patch 里只留引用;向导只改它自己那两个条目(`llm-pi-ai`、`agent-default-model`),其余行和注释原样不动。宿主没有提供向导接口时,按钮会说明本宿主不支持,而不是弹一个填了也没用的表单。
915
-
926
+ 第一次使用时,页面上的「首次使用向导」按顺序走:检查环境 → 验证 API key(真的请求端点,通过了才写任何东西)→ 预览并保存 profile patch → 在一个临时目录里跑一次真实的 trial run。每次保存前会留一份可回滚的 patch 备份(保留最近 10 次),密钥只交给宿主的凭据存储,patch 里只留引用;向导只改它自己那两个条目(`llm-pi-ai`、`agent-default-model`),其余行和注释原样不动。宿主没有提供向导接口时,按钮会说明本宿主不支持,而不是弹一个填了也没用的表单。
927
+
916
928
  如果宿主没有挂载 `sessionController`(例如没有 web session API 的无头 profile),页面会说明这一点并拒绝创建会话。它**不会**假装成一个聊天。控制台在一个进程里也只保留一个活跃
917
929
  对话;"新对话"会创建一个新的 Host Session,旧的保持原样。以宿主 `pendingInput` 形式出现的审批提示会显示在
918
930
  状态行里,但不会由这个页面回答;只有 run 的 attention 问题会被回答。
@@ -1140,7 +1152,7 @@ SHA-256)。`--format html` 把同样的内容写成一个自包含
1140
1152
 
1141
1153
  | 你看到的 | 含义 | 怎么办 |
1142
1154
  | --- | --- | --- |
1143
- | `superagent_*` 工具不存在 | bundle 行没挂上,或者宿主拒绝加载插件。 | 跑 `--dump-config` 查 `@xiangyixie/dsh-superagent` 块;用 `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.3` 重装,并在宿主日志里找 `[dsh-superagent]` 行。 |
1155
+ | `superagent_*` 工具不存在 | bundle 行没挂上,或者宿主拒绝加载插件。 | 跑 `--dump-config` 查 `@xiangyixie/dsh-superagent` 块;用 `dsh plugin --profile <p> add @xiangyixie/dsh-superagent@0.14.5` 重装,并在宿主日志里找 `[dsh-superagent]` 行。 |
1144
1156
  | `Cannot find module .../lib/control.js`(或 `watch.js` / `report.js` / `wizard.js`),或宿主日志里的 `[dsh-superagent] dsh-superagent failed to load because a file it imports is missing: ...` | 那个 profile 里的副本不完整——被中断的 `add` 会留下残缺的解包结果。0.14.3 起的入口会直接点名缺哪个文件。已发布的包不是原因:每个版本都带全部三十四个 `lib/` 文件。 | 删掉 profile 的 `node_modules` 下该插件的目录(带 scope 的 `@xiangyixie/dsh-superagent`,或旧 tarball 安装留下的无 scope 的 `dsh-superagent`),再用同一条 `add` 命令重装,并带上版本号。不要手工拷贝文件进去。 |
1145
1157
  | `[error] the model provider rejected the API key` | 启动宿主的那个进程里缺 key 环境变量。 | 导出 `DEEPSEEK_API_KEY`(默认路由)或你那条路由声明的变量,然后重启 `dsh`。 |
1146
1158
  | `MISSING_CREDENTIAL ... no API key for provider route "..."` | profile 的路由在环境里没有凭据。 | 设置该路由对应的环境变量并重启。错误行里写了路由名,以它为准,不要照本文。 |
package/bin/doctor.js CHANGED
@@ -15,7 +15,7 @@ Check that this copy of dsh-superagent can actually run:
15
15
  - every file the code imports is shipped by package.json "files" and exists
16
16
  - the installed copy matches the version package.json claims
17
17
  - the installed files match the published tarball (skipped when offline)
18
- - the DSH profile mounts the bundle patch and the twelve tools are registered
18
+ - the DSH profile mounts the bundle patch and the thirteen tools are registered
19
19
  - the running Node satisfies "engines"
20
20
 
21
21
  Nothing is installed or modified; the only network access is one public
@@ -0,0 +1,223 @@
1
+ # 长期目标(Long Goal)
2
+
3
+ 一个自然语言目标拆成多个阶段,每个阶段交给一组新的 agent 跨多轮推进;同一时刻可以有多组 agent 并行;宿主重启后从上次未完成的阶段继续,而不是从零重来。
4
+
5
+ 本文是设计与边界说明。实现见 `lib/long-goal.js`,测试见 `test/long-goal.test.mjs`。
6
+
7
+ ## 1. 与现有概念的关系
8
+
9
+ | 现有概念 | 关系 | 为什么不是替换 |
10
+ | --- | --- | --- |
11
+ | run | 长期目标的一个阶段执行一次 = 一个普通 run(每次重试也是一个新 run) | run 已经拥有 planner、依赖图、并行 worker、预算、用量、报告、审计、恢复与看板卡片。重写等于把这些再实现一遍,并让 0.14.3 的路径失去回归保护。 |
12
+ | 任务线(run 的 subtasks) | 阶段内部的并行任务线仍由 run 的 planner 生成,依赖、写冲突和并行上限沿用现有实现 | 长期目标不重新定义“任务”,只负责“哪些阶段可以同时开始、什么时候进入下一阶段”。 |
13
+ | 看板 | 阶段 run 照常出现在看板上;run 的 goal 文本带「长期目标 / 阶段 n/N」前缀,卡片可以直接分辨归属;目标级进度由 `superagent_goal status` 输出 | 不新增第二套看板数据源。看板读 run,goal 读 run 的阶段状态,只有一个事实来源。 |
14
+ | 收件箱 | 阶段 run worker 的提问仍走原有 attention / `superagent_answer`;阶段重试耗尽、停滞这类“目标级”问题走 `superagent_goal answer`,并通过 owner 会话的 followup 送达 | 收件箱已经能处理 run 级问题,目标级问题只需要一个新的路由 id,不需要新的消息系统。 |
15
+ | goal mode(0.14.3) | 阶段内部开 goal mode:一轮不达标就带着失败证据再来一轮,直到验收成立或硬停 | goal mode 是“同一阶段内的多轮”,长期目标是“多阶段之间的推进”。两者组合,而不是二选一。 |
16
+ | 定时计划(schedule) | 不使用。定时计划解决“按时间重复跑”,长期目标解决“一个目标跑到完成” | 把长期目标塞进 schedule 会让计划、窗口、补跑语义混在一起。 |
17
+
18
+ 结论:**扩展,不替换**。新增一个薄的目标层(阶段图 + 目标预算 + 跨阶段恢复),阶段执行完全复用 run。
19
+
20
+ ## 2. 数据结构
21
+
22
+ 长期目标是 `$DSH_HOME/state/superagent/goals/<goalId>.json` 里的一个 JSON 记录,原子写入(临时文件 + rename,Windows 上 EPERM 重试)。阶段 run 仍是 `runs/<runId>.json`,是任务级细节的唯一事实来源。
23
+
24
+ ```jsonc
25
+ {
26
+ "id": "g-20261116T101500-4f2a",
27
+ "schemaVersion": 1,
28
+ "goal": "把 dsh-superagent 推进到 1.0:范围、实现、发布验证三个阶段",
29
+ "status": "planning | running | paused | needs-decision | stalled | completed | partial | failed | cancelled | budget-stopped",
30
+ "createdAt": "…", "updatedAt": "…", "startedAt": "…", "finishedAt": null,
31
+ "ownerSessionId": "session-…", // 阶段 run 的 parent,重启后据此恢复
32
+ "cwd": "D:\\work\\plugin-1.0", // 阶段验收命令的工作目录
33
+ "autoResume": true, // 宿主重启后自动接着跑
34
+ "maxParallelPhases": 2, // 同时推进的阶段数
35
+ "maxAttemptsPerPhase": 2, // 一个阶段最多执行几次(含首次)
36
+ "maxRoundsPerPhase": 3, // 阶段 run 内 goal mode 的轮数
37
+ "noProgressRounds": 2, // 阶段 run 内连续同条件失败几轮算停滞
38
+ "phaseBudget": { "maxModelCalls": 40, "maxTokens": 800000 }, // 每次阶段 run 的上限
39
+ "budget": { "maxModelCalls": 120, "maxTokens": 3000000 }, // 整个目标的上限;null = 不额外限制
40
+ "maxWallClockMinutes": 1440,
41
+ "stallAfterMinutes": 180, // 没有阶段完成多久算目标级停滞
42
+ "phases": [{
43
+ "id": "p1",
44
+ "title": "1.0 范围",
45
+ "objective": "盘点现状,写出 1.0 的范围、非目标与验收清单",
46
+ "dependsOn": [],
47
+ "acceptance": [ // 至少一条;check 省略时由验收模型判断
48
+ { "id": "a1", "text": "docs/ROADMAP-1.0.md 存在且包含验收清单", "check": { "type": "file", "path": "docs/ROADMAP-1.0.md" } }
49
+ ],
50
+ "status": "pending | ready | running | verifying | completed | failed | skipped | cancelled | needs-decision",
51
+ "attempts": 0,
52
+ "runIds": [], // 每次尝试的 run;最后一个就是当前/最近一次
53
+ "currentRunId": null,
54
+ "resumeRunId": null, // 宿主重启后要恢复的原 run
55
+ "deliverables": [], // 可选,用于报告汇总
56
+ "lastOutcome": { "runStatus": null, "error": null, "failed": [], "changed": null },
57
+ "startedAt": null, "finishedAt": null
58
+ }],
59
+ "decomposeRunId": null, // 自动拆阶段用的 run
60
+ "decomposeAttempts": 0,
61
+ "decisions": [{
62
+ "id": "d1", "kind": "phase-exhausted | verification-conflict | stalled | worker-question",
63
+ "phaseId": "p2",
64
+ "question": "p2 连续两次失败,是否换一种做法重试?",
65
+ "options": ["retry", "skip", "stop"],
66
+ "reason": "…",
67
+ "answer": null, "answeredAt": null, "createdAt": "…"
68
+ }],
69
+ "decisionSeq": 0,
70
+ "usage": { "modelCalls": 0, "tokens": 0 }, // 所有阶段 run + 拆阶段 run 的合计
71
+ "events": [{ "at": "…", "type": "phase.completed", "phaseId": "p1", "detail": "…" }],
72
+ "progressAt": "…", // 最近一次阶段状态前进的时间
73
+ "noProgressAttempts": 0, // 自 progressAt 起失败的阶段尝试数
74
+ "stoppedReason": null,
75
+ "recovery": { "at": "…", "reason": "host-restart", "phases": ["p2"] }
76
+ }
77
+ ```
78
+
79
+ 约束:
80
+
81
+ - 阶段数 1–8;id 必须唯一;`dependsOn` 只能引用已存在的阶段;出现环直接拒绝创建,不落盘半成品。
82
+ - 每个阶段至少一条验收条件。用户没写时补一条由验收模型判断的条件(“该阶段目标已经达成,且报告给出可核对证据”)。
83
+ - 所有上限只收紧不放大:阶段预算再大也不能超过目标剩余预算。
84
+
85
+ ## 3. 状态机
86
+
87
+ ### 3.1 目标
88
+
89
+ ```
90
+ create ──> planning ──> running ──> completed
91
+ │ │ │
92
+ │ │ ├─> partial (有阶段被人工 skip,其余完成)
93
+ │ │ ├─> failed (阶段永久失败且人工选择 stop)
94
+ │ │ ├─> stalled (无进展,等人决定)
95
+ │ │ ├─> needs-decision(有开放式问题/阶段重试耗尽)
96
+ │ │ └─> budget-stopped(目标预算耗尽)
97
+ │ └─> paused ──resume──> running
98
+ └─> failed(拆阶段失败,重试一次后仍不可用;不再重试)
99
+ 任意状态 ──cancel──> cancelled
100
+ ```
101
+
102
+ - `planning`:有 `decomposeRunId` 时只等这个 run;用户显式给了 `phases` 时跳过。
103
+ - `running`:每个 tick 结算已完成阶段、启动依赖已满足的阶段,最多 `maxParallelPhases` 个。
104
+ - `needs-decision`:至少一个问题未回答。**不启动新阶段**;已经在跑的阶段 run 继续跑完,结果不会丢。
105
+ - `paused`:人工暂停或宿主重启后暂时找不到 owner 会话。不启动新阶段。
106
+ - `stalled`:目标级停滞。不自动重试,等人选择继续或停止。
107
+ - `completed`:所有阶段 completed。
108
+ - `partial`:所有阶段进入终态,但有 skipped(人工跳过)或 failed(人工选择继续),其余完成。
109
+ - `budget-stopped`:目标预算耗尽,停止派发,不重试。
110
+
111
+ ### 3.2 阶段
112
+
113
+ ```
114
+ pending ──依赖完成──> ready ──启动 run──> running ──run 终态──> verifying
115
+ │ │
116
+ │ ├─> completed
117
+ │ ├─> ready(可重试,attempts+1)
118
+ │ ├─> needs-decision(run 在提问)
119
+ │ └─> failed(重试耗尽/不可重试)
120
+ pending ──依赖失败/跳过──> skipped
121
+ interrupted ──宿主重启──> ready(resumeRunId=原 run,恢复而不是新建)
122
+ 任意阶段 ──目标取消──> cancelled
123
+ ```
124
+
125
+ - `verifying` 是结算瞬间的状态:读 run 的 `goalMode.achieved`、终态、失败条件,决定 completed / retry / needs-decision / failed。
126
+ - `ready` + `resumeRunId` 表示“恢复原 run”;没有 `resumeRunId` 才是“新建一次尝试”。
127
+ - 阶段 run 的 `status === 'completed'` 在 goal mode 下等价于验收成立;`partial`/`failed` 才进入重试判定。
128
+
129
+ ## 4. 依赖与并行
130
+
131
+ - 阶段依赖是显式的 `dependsOn`。只有全部依赖 `completed` 才变 `ready`;依赖 `failed`/`skipped` 的阶段直接 `skipped`(级联,不重跑)。
132
+ - 同一 tick 可以启动多个互不依赖的阶段;上限 `maxParallelPhases`,同时受 `maxActiveRuns` 约束(超出的阶段 run 排队,不丢)。
133
+ - 阶段内部的任务线并行仍由 run 的 `maxParallel` 与写冲突检测负责。长期目标不提高这个值。
134
+ - 阶段 run 的 goal 文本带阶段编号和已完成阶段的结论摘要,后续阶段能读到前序产出,不需要共享内存。
135
+
136
+ ## 5. 预算
137
+
138
+ 三层,全部是硬停:
139
+
140
+ 1. **目标预算** `budget`:所有阶段 run、拆阶段 run、重试 run 的用量合计。达到即 `budget-stopped`,不再派发。
141
+ 2. **阶段预算** `phaseBudget`:每个阶段 run 自己的一次上限(goal mode 的 `budget`,同时进入 run limits)。跑飞只影响一个阶段,不会烧穿整个目标。
142
+ 3. **阶段内轮次** `maxRoundsPerPhase` + `maxWallClockMinutes`:由 goal mode 执行,防止同一阶段无限重来。
143
+
144
+ 派发前计算 `remaining = budget - spent`,把阶段预算收紧到 `min(phaseBudget, remaining)`。剩余为 0 时不启动。
145
+
146
+ ## 6. 停滞检测
147
+
148
+ 两层,分别回答“这个阶段是不是在原地打转”和“整个目标是不是没有前进”。
149
+
150
+ 阶段级(复用 goal mode 的 `assessRound`):
151
+
152
+ - 有机器验收且这一轮没有改动任何文件 → `no-changes`,阶段 run 立即停。
153
+ - 同一个失败条件连续 `noProgressRounds` 轮 → `no-progress`。
154
+ - 这两种结果都进入阶段重试;重试指令必须写清“上一轮失败在哪个条件、下一步改什么”,不允许只写“再试一次”。
155
+
156
+ 目标级:
157
+
158
+ - `progressAt` 只在阶段 completed、skipped 或人工回答后前进。
159
+ - 距 `progressAt` 超过 `stallAfterMinutes`,或连续 `maxAttemptsPerPhase * 2` 次阶段尝试都没有带来阶段完成 → `stalled`,写一条 decision(选项:`continue` / `stop`),**不自动重试**。
160
+ - 没有 running 阶段、也没有 ready 阶段,剩余阶段全部被失败/跳过依赖卡死 → `failed`(死锁不可通过等待解决)。
161
+
162
+ ## 7. 人工介入点
163
+
164
+ 必须问人:
165
+
166
+ - 阶段重试耗尽:`phase-exhausted`,选项 `retry`(带一句新指示,重置尝试次数并新建 run)/ `skip`(级联跳过下游)/ `stop`。
167
+ - 目标级停滞:`stalled`,选项 `continue`(重置停滞计数,允许再推进)/ `stop`。
168
+ - 阶段 run 的 worker 主动提问(attention):目标转 `needs-decision`,问题原文和 `runId/attentionId` 一起显示,用现有 `superagent_answer` 回答;目标层不复制一份问题。
169
+ - 验收证据互相矛盾:`verification-conflict`,选项 `accept`(以机器校验为准,计为完成)/ `retry`(换人重试)/ `stop`。两个方向都不算达成:
170
+ - 机器校验通过、但 worker 自己的结论是否定的(held / failed / 明说没能验证,例如 worker shell 里 `spawn EPERM` 而宿主进程里同一命令 exit 0);
171
+ - 机器校验失败、但 worker 或验收模型声称成功(exit code 是事实,不是意见)。
172
+ decision 的 `source.worker` 保存 worker 原话,`source.machine` 保存命令、`exitCode`、`detail`,便于人工对照。
173
+ - 权限策略拦截/需要审批:按不可重试失败处理,等人通过现有审批卡批准后回答 `retry`。
174
+ - 宿主重启后原会话无法恢复:`paused`,等人从新会话 `superagent_goal resume`。
175
+
176
+ 直接失败、不重试:
177
+
178
+ - 拆阶段返回的计划不可解析/不合法,修复一次后仍不合法 → `failed`。
179
+ - 阶段依赖有环、引用不存在的阶段 → 创建时直接报错,不创建目标。
180
+ - 目标预算耗尽 → `budget-stopped`,不靠重试绕过。
181
+ - 显式拒绝(权限、能力缺失)→ 阶段 `failed`,不自动重试;是否继续由人决定。
182
+ - 用户 `cancel` → `cancelled`;用户 `pause` → `paused`。
183
+
184
+ ## 8. 重启恢复
185
+
186
+ 持久化的是目标记录 + 每个阶段引用的 run id;任务级细节不复制。
187
+
188
+ 宿主启动顺序:
189
+
190
+ 1. `orchestrator.recover()` 把上一个进程遗留的活跃 run 标记为 `interrupted`,并释放 run 锁。
191
+ 2. `longGoal.init()` 读取所有目标;对 `autoResume` 且状态为 `planning/running` 的目标:
192
+ - 阶段 `currentRunId` 对应 run 是 `interrupted` → 阶段置 `ready`,记 `resumeRunId`;目标保持 `running`,写 `recovery`。
193
+ - 拆阶段 run 是 `interrupted` → 保留 id,下一 tick 恢复同一个 run(不重新拆)。
194
+ - 阶段 run 已经 `completed` 但目标没来得及记账(崩溃窗口)→ 直接记阶段完成并推进。
195
+ 3. tick 解析 owner 会话(与 schedule 相同的恢复顺序:live → resume 持久会话 → create 新会话)。解析成功才恢复/启动 run;失败则目标 `paused`,不猜。
196
+ 4. 恢复阶段 run 用 `orchestrator.resume(runId)`:已完成的 subtask 保持完成,只继续没做完的,**不会重跑已完成的阶段**。
197
+ 5. 每个目标在派发/恢复时持有 `goals/<id>.lock`(`acquireFileLock`,死进程可回收),避免两个宿主进程同时推进同一目标。
198
+
199
+ ## 9. 工具面
200
+
201
+ 一个工具,动作枚举:
202
+
203
+ - `superagent_goal action=create goal=... [phases=[...]] [budget=...] [phase_budget=...] ...`
204
+ - `superagent_goal action=status goal_id=...`
205
+ - `superagent_goal action=list`
206
+ - `superagent_goal action=answer goal_id=... decision_id=... answer=retry|skip|stop|continue [note=...]`
207
+ - `superagent_goal action=resume|pause|cancel goal_id=...`
208
+
209
+ 阶段 run 继续用 `superagent_status` / `superagent_cancel` / `superagent_answer` 观察和操作。
210
+
211
+ ## 10. 进度可见
212
+
213
+ - `superagent_goal status` 输出:目标状态、每个阶段的 status/attempts/runId、当前 run 的进度行、验收通过数、下一步。
214
+ - 每个阶段完成、进入 needs-decision、目标完成/停止时,向 owner 会话发一条 followup(走现有 outbox,不另建消息通道)。
215
+ - 阶段 run 本身在看板上有卡片;goal 文本前缀让卡片能归属到阶段。
216
+ - 不做截图式“证明”:验收结论以 run 文件里的 exit code、`goalMode.checks` 和 goal JSON 的阶段状态为准。
217
+
218
+ ## 11. 本期不做
219
+
220
+ - 不做独立的长期目标看板页面;复用 run 卡片 + status。
221
+ - 不做跨目标共享记忆/知识库;阶段之间的上下文通过阶段 goal 文本里的前序摘要传递。
222
+ - 不修改宿主源码,不改变沙箱/权限默认值,不为跑通放宽审批。
223
+ - 不碰 0.14.3 的发布路径;新代码在 `feat/long-goal` 分支,合并等发布完成后再定。