dsh-swarm-console 0.2.2 → 0.3.1

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 CHANGED
@@ -33,7 +33,10 @@ dsh-swarm-console
33
33
  plugin_manager install_bundle dsh-swarm-console
34
34
  ```
35
35
 
36
- > 已在 DSH 0.2.2-rc.5 上实测:profile 依赖解析为 `^0.1.5`,安装后 `verify_*` 工具与三条斜杠命令均可用。
36
+ > 升级到新的次版本(0.2.x → 0.3.x)必须显式指定版本:`install_bundle dsh-swarm-console@0.3.1`,
37
+ > 因为 `^0.2.x` 的 semver 上限不含 0.3.0。
38
+
39
+ > 已在 DSH 0.2.2-rc.5 上实测:profile 依赖解析为 `^0.2.2`,安装后 `verify_*` 工具与三条斜杠命令均可用。
37
40
 
38
41
  ### 从本地目录安装(已验证)
39
42
 
@@ -47,24 +50,29 @@ plugin_manager install_bundle <本包目录的绝对路径>
47
50
  ## 快速开始
48
51
 
49
52
  ```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 重算并刷新判定
53
+ verify_contract 冻结契约(objective / workspaceRoot / criteria / constraints,testCmd 可选)
54
+ verify_run 跑证据校验:checks 是「检查请求」,由插件实际执行
55
+ /gate-status 不带参数列出本会话所有契约;带参数看单条(支持 id 前缀,如 7e28)
56
+ /gate-approve 放行:/gate-approve <id|前缀> <证据hash>(仅 GREEN + hash 一致时允许)
57
+ /gate-retry 重算并刷新判定(旧放行标 stale)
55
58
  ```
56
59
 
57
60
  示例:
58
61
 
59
62
  ```text
60
- > verify_contract {"objective":"给 README 加安装节","criteria":[{"id":"c1","text":"安装节存在","checkIds":["k1"]}]}
61
- contract 5bc483324d46 已冻结
63
+ > verify_contract {"objective":"给 README 加安装节","workspaceRoot":"D:/my-project",
64
+ "criteria":[{"id":"c1","text":"安装节存在","checkIds":["k1"]}]}
65
+ contract 7e280e5c4f7e 已冻结
62
66
 
63
- > verify_run {"contractId":"5bc483324d46","checks":[{"id":"k1","type":"file.exists","ok":true}]}
67
+ > verify_run {"contractId":"7e280e5c4f7e","checks":[{"id":"k1","type":"file.exists","path":"README.md"}]}
64
68
  门禁 GREEN:全部 1 条验收条件均有通过证据
65
69
 
66
- > /gate-approve 5bc483324d46
67
- 契约 5bc483324d46 已由用户放行(approved)
70
+ > /gate-status 7e28
71
+ 契约 7e280e5c4f7e:最近决定 GREEN @ …;尚未放行
72
+ 证据:380cdbc5b3ed
73
+
74
+ > /gate-approve 7e28 380cdbc5b3ed
75
+ 契约 7e280e5c4f7e 已由用户放行(approved)
68
76
  ```
69
77
 
70
78
  ## 能力与限制
package/docs/DETAIL.md CHANGED
@@ -1,68 +1,79 @@
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
-
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 三工具(0.3.0 契约结构)
40
+
41
+ - `verify_contract({objective, workspaceRoot, testCmd?, policyId?, constraints, criteria})` → `{contractId}`
42
+ - **`workspaceRoot` 必填**:绝对路径、必须存在且是目录;所有检查以它为根
43
+ - `testCmd` 可选:`exec` 检查**唯一允许**的命令;不声明就拒绝一切 `exec`
44
+ - `policyId` 可选:只有显式声明,且策略的检查 id 全部被契约 `checkIds` 覆盖时才启用
45
+ - `verify_run({contractId, checks})` → `{decision, reasons, evidenceHash, reproCmd?, missing?, warnings?}`
46
+ - `file.exists` 的 `path` 必须是**相对 workspaceRoot 的相对路径**(绝对路径直接判 RED)
47
+ - `exec` 的 `cmd` 必须与 `testCmd` 完全相等;执行时 `cwd` 固定为 `workspaceRoot`
48
+ - 非法检查请求不抛异常,返回 `ok:false` 并判 RED
49
+ - `verify_status({contractId})` → `{known:true, decision, at, evidenceHash, approved?, stale?, ...}`;未知 `{known:false}`
50
+
51
+ 三态规则:缺证据 YELLOW;任一 check 失败 RED(必带可复制执行的 `reproCmd`);全部有证据且通过 GREEN。
52
+
53
+ **策略层(`code-change`)当前只生成 `testCmd` 检查**。`exists` / `workspace.diff` 已从策略声明中删除——需要文件检查时由调用方在 `checks` 里显式给出。
54
+
55
+ **放行入口**:斜杠命令 `/gate-approve <id|前缀> <evidenceHash>`、`/gate-retry <id|前缀>`、`/gate-status [id|前缀]`(不带参数列出**本会话**全部契约)。放行只能由用户触发——斜杠命令由用户在交互界面直接输入,图中没有对应的模型工具,模型无法代替用户调用,H3(放行只能由用户触发)由这个结构保证,不依赖运行时身份判断。非 GREEN 时 `/gate-approve` 直接拒绝并提示先 retry。门禁卡(action-cards)为可选增强,仅在挂载该服务的 profile 生效。
56
+
57
+ 每次命令执行会在会话日志留下 `command/run` 与 `command/done` 事件,可作为放行/重试的机器证据。
58
+
59
+ **`gate-retry` 语义**:用空证据重算,结果必为 YELLOW(提示补证据);旧放行会被置 `approved=false`、`stale=true`,并保留 `lastApprovedAt` / `lastApprovedHash`,`/gate-status` 显示 `[stale] 上次放行已失效(时间)`。要转 GREEN 需重新执行 `verify_run` 并提供真实证据。
60
+
61
+ **会话隔离**:契约与运行状态都按 `${sessionId}:${contractId}` 存放;`/gate-status` 不带参数只列**本会话**契约,id 前缀解析也只在本会话内匹配(前缀最短 4 位)。
62
+
63
+ ## 命令速查
64
+
65
+ - `/gate-status`:不带参数列出本会话所有契约;带参数(或 id 前缀)查看单条
66
+ - `/gate-approve <id|前缀> <evidenceHash>`:**必须**带证据 hash 自证;缺参数会提示先 `/gate-status` 复制;非 GREEN 或 hash 不一致均拒绝
67
+ - `/gate-retry <id|前缀>`:重跑校验并把旧放行标为 `stale`
68
+
69
+ ## 已知限制
70
+
71
+ - **`exec` 检查以当前用户权限执行命令**:等同于你在终端敲那条命令。只把可信命令写进契约;不要接受来源不明的检查请求。
72
+ - **同步执行会阻塞宿主**:v0.2 的检查由 `spawnSync` 同步跑,单条最长 120 秒,期间宿主事件循环被占用,界面可能短暂无响应。异步执行排进 0.3。
73
+ - 证据存**进程内 Map**,DSH 重启即丢,不做持久化(重启后 `/gate-status` 返回「未知契约」)
74
+ - 还没有画布 —— 看不到 agent 节点、连线或过程可视化
75
+ - 多阶段评审状态机未实现
76
+ - `swarm_run` 的 `RESULT:` 解析只取**第一行**(`RESULT: ok` 后面的说明不会进结果)
77
+ - 动作卡片:代码保留为可选增强,需目标 profile 挂载 `action-cards` 服务;v1 的放行入口是斜杠命令
78
+ - `swarm_run` 只支持一次调用,不支持多轮对话或子 agent 编排
79
+