dsh-swarm-console 0.2.0 → 0.2.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.md +109 -109
- package/docs/DETAIL.md +68 -62
- package/index.js +379 -379
- package/lib/core/evidence.js +98 -97
- package/lib/core/gate.js +77 -69
- package/lib/core/verify.js +214 -177
- package/package.json +47 -47
package/README.md
CHANGED
|
@@ -1,109 +1,109 @@
|
|
|
1
|
-
# Swarm Console(`dsh-swarm-console`)
|
|
2
|
-
|
|
3
|
-
> 让 agent 说「完成」之前,先过一道可机器验证的交付门禁。
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/dsh-swarm-console)
|
|
6
|
-
[](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/LICENSE)
|
|
7
|
-
[](https://nodejs.org/)
|
|
8
|
-
|
|
9
|
-
DeepSeek Harness(DSH)插件:把「任务契约 → 证据校验 → 三态门禁 → 用户放行」做成一条可核查的链路。
|
|
10
|
-
|
|
11
|
-
## 它解决什么
|
|
12
|
-
|
|
13
|
-
Agent 说「完成了」,可能只是日志刷屏、产出为零。这个插件让「完成」必须在证据上成立:
|
|
14
|
-
|
|
15
|
-
- **冻结契约**:目标 / 约束 / 验收条件写死并哈希成 `contractId`,改一个字就换 id;
|
|
16
|
-
- **证据先于验收**:每条验收条件必须绑定检查项,缺证据最多判 `YELLOW`;
|
|
17
|
-
- **三态判定**:`GREEN` / `YELLOW` / `RED`,`RED` 一定带可复制执行的复现命令;
|
|
18
|
-
- **放行只归用户**:由斜杠命令触发,模型中不存在对应工具,无法代批。
|
|
19
|
-
|
|
20
|
-
## 安装
|
|
21
|
-
|
|
22
|
-
### 从 npm 安装(已验证)
|
|
23
|
-
|
|
24
|
-
DSH 的 **插件 → 添加插件** 里输入包名,安装源选 `npm 官方源`:
|
|
25
|
-
|
|
26
|
-
```text
|
|
27
|
-
dsh-swarm-console
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
或命令行:
|
|
31
|
-
|
|
32
|
-
```text
|
|
33
|
-
plugin_manager install_bundle dsh-swarm-console
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
> 已在 DSH 0.2.2-rc.5 上实测:profile 依赖解析为 `^0.1.5`,安装后 `verify_*` 工具与三条斜杠命令均可用。
|
|
37
|
-
|
|
38
|
-
### 从本地目录安装(已验证)
|
|
39
|
-
|
|
40
|
-
```text
|
|
41
|
-
plugin_manager install_bundle <本包目录的绝对路径>
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
> 注意:以 `link` 方式安装时,卸载该插件会清空被链接目录的内容——请只链接已提交(或已备份)的目录。
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
## 快速开始
|
|
48
|
-
|
|
49
|
-
```text
|
|
50
|
-
verify_contract 冻结一个契约(objective / constraints / criteria)
|
|
51
|
-
verify_run 跑证据校验,得到 GREEN / YELLOW / RED
|
|
52
|
-
/gate-status
|
|
53
|
-
/gate-approve 放行(仅 GREEN 允许,用户手动输入)
|
|
54
|
-
/gate-retry 重算并刷新判定
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
示例:
|
|
58
|
-
|
|
59
|
-
```text
|
|
60
|
-
> verify_contract {"objective":"给 README 加安装节","criteria":[{"id":"c1","text":"安装节存在","checkIds":["k1"]}]}
|
|
61
|
-
contract 5bc483324d46 已冻结
|
|
62
|
-
|
|
63
|
-
> verify_run {"contractId":"5bc483324d46","checks":[{"id":"k1","type":"file.exists","ok":true}]}
|
|
64
|
-
门禁 GREEN:全部 1 条验收条件均有通过证据
|
|
65
|
-
|
|
66
|
-
> /gate-approve 5bc483324d46
|
|
67
|
-
契约 5bc483324d46 已由用户放行(approved)
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
## 能力与限制
|
|
71
|
-
|
|
72
|
-
已实现:
|
|
73
|
-
|
|
74
|
-
- 契约冻结与内容哈希(`contract.id`)
|
|
75
|
-
- 证据由插件执行:`verify_run` 的 `checks` 是**检查请求**而非结论——`file.exists` 由插件 `existsSync` 判定,`exec` 由插件实际执行;模型自报的 `ok` 一律忽略
|
|
76
|
-
- 证据分级与三态门禁(`GREEN` / `YELLOW` / `RED`);空契约直接 `RED`
|
|
77
|
-
- `RED` 必带可执行复现命令;缺证据不判通过
|
|
78
|
-
- 用户专属放行:`/gate-approve` `/gate-retry` `/gate-status`;重跑后旧放行标记 `stale`
|
|
79
|
-
- 外部 agent 适配层(OpenAI 兼容端点,作为原生 subagent run 使用)
|
|
80
|
-
|
|
81
|
-
⚠️ 两条必须知道的行为:
|
|
82
|
-
|
|
83
|
-
- **`exec` 检查以当前用户权限执行命令**,等同于你自己在终端敲那条命令。请只把可信命令写进契约,不要接受来源不明的检查请求。
|
|
84
|
-
- **执行期间阻塞宿主**:v0.2 采用同步执行,单条检查最长 120 秒,期间宿主事件循环被占用,界面可能短暂无响应。异步执行排进 0.3。
|
|
85
|
-
|
|
86
|
-
尚未实现(不承诺):
|
|
87
|
-
|
|
88
|
-
- 可视化画布
|
|
89
|
-
- 多阶段评审状态机
|
|
90
|
-
- 动作卡片:代码保留为可选增强,需目标 profile 挂载 `action-cards` 服务
|
|
91
|
-
- 证据持久化:v1 存在进程内,DSH 重启即丢
|
|
92
|
-
|
|
93
|
-
## 开发与门禁
|
|
94
|
-
|
|
95
|
-
```bash
|
|
96
|
-
npm run gate # probe / selftest / plugin:test / smoke / pack / wiring / dryrun / encoding 八段
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
验收记录见 [`docs/V1-ACCEPTANCE.md`](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/plugin/docs/V1-ACCEPTANCE.md):包含斜杠命令链路的日志证据(`command/run`、`command/done`)与三条硬规则的反证。
|
|
100
|
-
|
|
101
|
-
## 链接
|
|
102
|
-
|
|
103
|
-
- 仓库:https://github.com/whyissodifficult/dsh-agent-swarm-console
|
|
104
|
-
- 插件详情:见 [`docs/DETAIL.md`](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/plugin/docs/DETAIL.md)
|
|
105
|
-
- 验收记录:[`docs/V1-ACCEPTANCE.md`](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/plugin/docs/V1-ACCEPTANCE.md)
|
|
106
|
-
|
|
107
|
-
## 许可
|
|
108
|
-
|
|
109
|
-
[MIT](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/LICENSE)
|
|
1
|
+
# Swarm Console(`dsh-swarm-console`)
|
|
2
|
+
|
|
3
|
+
> 让 agent 说「完成」之前,先过一道可机器验证的交付门禁。
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/dsh-swarm-console)
|
|
6
|
+
[](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/LICENSE)
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
|
|
9
|
+
DeepSeek Harness(DSH)插件:把「任务契约 → 证据校验 → 三态门禁 → 用户放行」做成一条可核查的链路。
|
|
10
|
+
|
|
11
|
+
## 它解决什么
|
|
12
|
+
|
|
13
|
+
Agent 说「完成了」,可能只是日志刷屏、产出为零。这个插件让「完成」必须在证据上成立:
|
|
14
|
+
|
|
15
|
+
- **冻结契约**:目标 / 约束 / 验收条件写死并哈希成 `contractId`,改一个字就换 id;
|
|
16
|
+
- **证据先于验收**:每条验收条件必须绑定检查项,缺证据最多判 `YELLOW`;
|
|
17
|
+
- **三态判定**:`GREEN` / `YELLOW` / `RED`,`RED` 一定带可复制执行的复现命令;
|
|
18
|
+
- **放行只归用户**:由斜杠命令触发,模型中不存在对应工具,无法代批。
|
|
19
|
+
|
|
20
|
+
## 安装
|
|
21
|
+
|
|
22
|
+
### 从 npm 安装(已验证)
|
|
23
|
+
|
|
24
|
+
DSH 的 **插件 → 添加插件** 里输入包名,安装源选 `npm 官方源`:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
dsh-swarm-console
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
或命令行:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
plugin_manager install_bundle dsh-swarm-console
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
> 已在 DSH 0.2.2-rc.5 上实测:profile 依赖解析为 `^0.1.5`,安装后 `verify_*` 工具与三条斜杠命令均可用。
|
|
37
|
+
|
|
38
|
+
### 从本地目录安装(已验证)
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
plugin_manager install_bundle <本包目录的绝对路径>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
> 注意:以 `link` 方式安装时,卸载该插件会清空被链接目录的内容——请只链接已提交(或已备份)的目录。
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
## 快速开始
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
verify_contract 冻结一个契约(objective / constraints / criteria)
|
|
51
|
+
verify_run 跑证据校验,得到 GREEN / YELLOW / RED
|
|
52
|
+
/gate-status 不带参数列出本会话所有契约;带参数看单条(支持 id 前缀,如 1578)
|
|
53
|
+
/gate-approve 放行(仅 GREEN 允许,用户手动输入)
|
|
54
|
+
/gate-retry 重算并刷新判定
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
示例:
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
> verify_contract {"objective":"给 README 加安装节","criteria":[{"id":"c1","text":"安装节存在","checkIds":["k1"]}]}
|
|
61
|
+
contract 5bc483324d46 已冻结
|
|
62
|
+
|
|
63
|
+
> verify_run {"contractId":"5bc483324d46","checks":[{"id":"k1","type":"file.exists","ok":true}]}
|
|
64
|
+
门禁 GREEN:全部 1 条验收条件均有通过证据
|
|
65
|
+
|
|
66
|
+
> /gate-approve 5bc483324d46
|
|
67
|
+
契约 5bc483324d46 已由用户放行(approved)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## 能力与限制
|
|
71
|
+
|
|
72
|
+
已实现:
|
|
73
|
+
|
|
74
|
+
- 契约冻结与内容哈希(`contract.id`)
|
|
75
|
+
- 证据由插件执行:`verify_run` 的 `checks` 是**检查请求**而非结论——`file.exists` 由插件 `existsSync` 判定,`exec` 由插件实际执行;模型自报的 `ok` 一律忽略
|
|
76
|
+
- 证据分级与三态门禁(`GREEN` / `YELLOW` / `RED`);空契约直接 `RED`
|
|
77
|
+
- `RED` 必带可执行复现命令;缺证据不判通过
|
|
78
|
+
- 用户专属放行:`/gate-approve` `/gate-retry` `/gate-status`;重跑后旧放行标记 `stale`
|
|
79
|
+
- 外部 agent 适配层(OpenAI 兼容端点,作为原生 subagent run 使用)
|
|
80
|
+
|
|
81
|
+
⚠️ 两条必须知道的行为:
|
|
82
|
+
|
|
83
|
+
- **`exec` 检查以当前用户权限执行命令**,等同于你自己在终端敲那条命令。请只把可信命令写进契约,不要接受来源不明的检查请求。
|
|
84
|
+
- **执行期间阻塞宿主**:v0.2 采用同步执行,单条检查最长 120 秒,期间宿主事件循环被占用,界面可能短暂无响应。异步执行排进 0.3。
|
|
85
|
+
|
|
86
|
+
尚未实现(不承诺):
|
|
87
|
+
|
|
88
|
+
- 可视化画布
|
|
89
|
+
- 多阶段评审状态机
|
|
90
|
+
- 动作卡片:代码保留为可选增强,需目标 profile 挂载 `action-cards` 服务
|
|
91
|
+
- 证据持久化:v1 存在进程内,DSH 重启即丢
|
|
92
|
+
|
|
93
|
+
## 开发与门禁
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
npm run gate # probe / selftest / plugin:test / smoke / pack / wiring / dryrun / encoding 八段
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
验收记录见 [`docs/V1-ACCEPTANCE.md`](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/plugin/docs/V1-ACCEPTANCE.md):包含斜杠命令链路的日志证据(`command/run`、`command/done`)与三条硬规则的反证。
|
|
100
|
+
|
|
101
|
+
## 链接
|
|
102
|
+
|
|
103
|
+
- 仓库:https://github.com/whyissodifficult/dsh-agent-swarm-console
|
|
104
|
+
- 插件详情:见 [`docs/DETAIL.md`](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/plugin/docs/DETAIL.md)
|
|
105
|
+
- 验收记录:[`docs/V1-ACCEPTANCE.md`](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/plugin/docs/V1-ACCEPTANCE.md)
|
|
106
|
+
|
|
107
|
+
## 许可
|
|
108
|
+
|
|
109
|
+
[MIT](https://github.com/whyissodifficult/dsh-agent-swarm-console/blob/main/LICENSE)
|
package/docs/DETAIL.md
CHANGED
|
@@ -1,62 +1,68 @@
|
|
|
1
|
-
# Swarm Console
|
|
2
|
-
|
|
3
|
-
在 DSH 里调用一个外部 agent 执行一次任务,返回结构化的停止原因与文本结果。
|
|
4
|
-
|
|
5
|
-
## 配置 externalAgents
|
|
6
|
-
|
|
7
|
-
在插件配置里给出 agent 画像表。令牌只写环境变量名,不写令牌值:
|
|
8
|
-
|
|
9
|
-
```yaml
|
|
10
|
-
externalAgents:
|
|
11
|
-
deepseek:
|
|
12
|
-
baseUrl: https://api.deepseek.com/v1
|
|
13
|
-
apiKeyEnv: DEEPSEEK_API_KEY
|
|
14
|
-
models: [deepseek-flash]
|
|
15
|
-
capabilities: [reasoning, chinese]
|
|
16
|
-
capabilityRouting: true
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
每个条目必须有 `baseUrl`、`apiKeyEnv`、`models` 三项,缺一项插件激活即报错(不静默跳过)。
|
|
20
|
-
|
|
21
|
-
## 调用 swarm_run
|
|
22
|
-
|
|
23
|
-
参数:
|
|
24
|
-
|
|
25
|
-
```js
|
|
26
|
-
{ task: '要做的任务', agent: 'deepseek', model: 'deepseek-flash' }
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
`task` 必填;`agent` 省略时,若只配了一个 external agent 就自动用它;`model` 省略时用画像里的第一个。
|
|
30
|
-
|
|
31
|
-
返回:
|
|
32
|
-
|
|
33
|
-
```js
|
|
34
|
-
{ stopReason: 'completed' | 'cancelled' | 'error', text: '文本结果', ms: 1234 }
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
`stopReason='cancelled'` 表示调用被取消(`exec.signal` 触发),不抛异常。
|
|
38
|
-
|
|
39
|
-
## verify v1 三工具(实验性)
|
|
40
|
-
|
|
41
|
-
- `verify_contract({objective, constraints, criteria})` → `{contractId}`,契约内容冻结成 12 位 id
|
|
42
|
-
- `verify_run({contractId, checks})` → `{decision: 'GREEN'|'YELLOW'|'RED', reasons, evidenceHash, reproCmd?}`
|
|
43
|
-
- `verify_status({contractId})` → 有记录时 `{known:true, decision, at}`;未知契约 `{known:false}`(不返回三态值)
|
|
44
|
-
|
|
45
|
-
三态规则:缺证据 YELLOW;任一 check 失败 RED(必带可复制执行的 `reproCmd`);全部有证据且通过 GREEN。
|
|
46
|
-
|
|
47
|
-
**放行入口(v1)**:斜杠命令 `/gate-approve <contractId>`、`/gate-retry <contractId>`、`/gate-status <contractId>`。放行只能由用户触发——斜杠命令由用户在交互界面直接输入,图中没有对应的模型工具,模型无法代替用户调用,H3(放行只能由用户触发)由这个结构保证,不依赖运行时身份判断。非 GREEN 时 `/gate-approve` 直接拒绝并提示先 retry。门禁卡(action-cards)为可选增强,仅在挂载该服务的 profile 生效。
|
|
48
|
-
|
|
49
|
-
每次命令执行会在会话日志留下 `command/run` 与 `command/done` 事件,可作为放行/重试的机器证据。
|
|
50
|
-
|
|
51
|
-
**`gate-retry` 语义**:用空证据重算,结果必为 YELLOW(提示补证据);它只刷新决定时间戳,不伪造通过证据。要转 GREEN 需重新执行 `verify_run` 并提供真实证据。
|
|
52
|
-
|
|
53
|
-
##
|
|
54
|
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
- `
|
|
62
|
-
|
|
1
|
+
# Swarm Console
|
|
2
|
+
|
|
3
|
+
在 DSH 里调用一个外部 agent 执行一次任务,返回结构化的停止原因与文本结果。
|
|
4
|
+
|
|
5
|
+
## 配置 externalAgents
|
|
6
|
+
|
|
7
|
+
在插件配置里给出 agent 画像表。令牌只写环境变量名,不写令牌值:
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
externalAgents:
|
|
11
|
+
deepseek:
|
|
12
|
+
baseUrl: https://api.deepseek.com/v1
|
|
13
|
+
apiKeyEnv: DEEPSEEK_API_KEY
|
|
14
|
+
models: [deepseek-flash]
|
|
15
|
+
capabilities: [reasoning, chinese]
|
|
16
|
+
capabilityRouting: true
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
每个条目必须有 `baseUrl`、`apiKeyEnv`、`models` 三项,缺一项插件激活即报错(不静默跳过)。
|
|
20
|
+
|
|
21
|
+
## 调用 swarm_run
|
|
22
|
+
|
|
23
|
+
参数:
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
{ task: '要做的任务', agent: 'deepseek', model: 'deepseek-flash' }
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`task` 必填;`agent` 省略时,若只配了一个 external agent 就自动用它;`model` 省略时用画像里的第一个。
|
|
30
|
+
|
|
31
|
+
返回:
|
|
32
|
+
|
|
33
|
+
```js
|
|
34
|
+
{ stopReason: 'completed' | 'cancelled' | 'error', text: '文本结果', ms: 1234 }
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`stopReason='cancelled'` 表示调用被取消(`exec.signal` 触发),不抛异常。
|
|
38
|
+
|
|
39
|
+
## verify v1 三工具(实验性)
|
|
40
|
+
|
|
41
|
+
- `verify_contract({objective, constraints, criteria})` → `{contractId}`,契约内容冻结成 12 位 id
|
|
42
|
+
- `verify_run({contractId, checks})` → `{decision: 'GREEN'|'YELLOW'|'RED', reasons, evidenceHash, reproCmd?}`
|
|
43
|
+
- `verify_status({contractId})` → 有记录时 `{known:true, decision, at}`;未知契约 `{known:false}`(不返回三态值)
|
|
44
|
+
|
|
45
|
+
三态规则:缺证据 YELLOW;任一 check 失败 RED(必带可复制执行的 `reproCmd`);全部有证据且通过 GREEN。
|
|
46
|
+
|
|
47
|
+
**放行入口(v1)**:斜杠命令 `/gate-approve <contractId>`、`/gate-retry <contractId>`、`/gate-status <contractId>`。放行只能由用户触发——斜杠命令由用户在交互界面直接输入,图中没有对应的模型工具,模型无法代替用户调用,H3(放行只能由用户触发)由这个结构保证,不依赖运行时身份判断。非 GREEN 时 `/gate-approve` 直接拒绝并提示先 retry。门禁卡(action-cards)为可选增强,仅在挂载该服务的 profile 生效。
|
|
48
|
+
|
|
49
|
+
每次命令执行会在会话日志留下 `command/run` 与 `command/done` 事件,可作为放行/重试的机器证据。
|
|
50
|
+
|
|
51
|
+
**`gate-retry` 语义**:用空证据重算,结果必为 YELLOW(提示补证据);它只刷新决定时间戳,不伪造通过证据。要转 GREEN 需重新执行 `verify_run` 并提供真实证据。
|
|
52
|
+
|
|
53
|
+
## 命令速查
|
|
54
|
+
|
|
55
|
+
- `/gate-status`:不带参数列出本会话所有契约;带参数(或 id 前缀)查看单条
|
|
56
|
+
- `/gate-approve <id|前缀>`:仅 GREEN 可放行;证据 hash 不一致会拒绝
|
|
57
|
+
- `/gate-retry <id|前缀>`:重跑校验并把旧放行标为 `stale`
|
|
58
|
+
|
|
59
|
+
## 已知限制
|
|
60
|
+
|
|
61
|
+
- **`exec` 检查以当前用户权限执行命令**:等同于你在终端敲那条命令。只把可信命令写进契约;不要接受来源不明的检查请求。
|
|
62
|
+
- **同步执行会阻塞宿主**:v0.2 的检查由 `spawnSync` 同步跑,单条最长 120 秒,期间宿主事件循环被占用,界面可能短暂无响应。异步执行排进 0.3。
|
|
63
|
+
- 证据存**进程内 Map**,DSH 重启即丢,不做持久化(重启后 `/gate-status` 返回「未知契约」)
|
|
64
|
+
- 还没有画布 —— 看不到 agent 节点、连线或过程可视化
|
|
65
|
+
- 多阶段评审状态机未实现
|
|
66
|
+
- 动作卡片:代码保留为可选增强,需目标 profile 挂载 `action-cards` 服务;v1 的放行入口是斜杠命令
|
|
67
|
+
- `swarm_run` 只支持一次调用,不支持多轮对话或子 agent 编排
|
|
68
|
+
|