工具与参数

层级：参考适用：0.1.x（具体变化见 CHANGELOG）权威性：工具结构与参数定义的唯一来源

七个工具的五块模型、action.kind、等待条件、输出/安全块，以及全部参数的权威定义。

1. 结构与规则

参数的权威定义（类型 / 单位 / 默认值 / 范围 / 必填 / 含义）见参数定义。本文只讲结构与规则，具体以运行时为准。

1. 调用结构

一次调用 = { tasks: [ … ] }（1–16 个任务，任务之间并行）。每个任务五类块，每个工具只消费其中一部分；未列出的块传进来会被拒绝（不会静默忽略）：

工具	消费的块
`shell_run` / `shell_send`	`target` / `action` / `wait` / `output` / `safety`
`shell_read`	`target` / `action` / `wait` / `output`
`shell_audit`	`target` / `action` / `output`
`shell_manage`	`target` / `action` / `safety`（仅 `dryrun`）
`shell_open`	`action`（它创建会话，没有目标）
`shell_state`	不套块：只有一组扁平过滤参数

硬规则：

操作只由 action.kind 表达；参数只描述该操作的细节，不能拿参数暗示操作。
action 必填（没有“只带 wait 等上一个命令”的用法）；每个任务只做一个操作。
同一个 shell 在一次调用里只能出现一次（重复出现整次调用被拒，请拆成多次调用）。
各 kind 只接受自己的载荷；多传字段会被拒绝并列出允许的字段。

2. `target`

值	含义
`mine`（默认）	本对话创建的全部 shell；只有一个时即该会话
`*`	全部存活 shell（必须显式传；*写操作不允许 ``**）
`dsh-ab12cd` / `dsh-a,dsh-b`	显式 id（逗号分隔）

跨对话访问：工具层不阻止用具体 id 操作其它对话创建的 shell；“无用户明确要求时不要操作非自己创建的 shell”是使用约定，不是系统强制。* 用于查看全部，写操作会拒绝。

3. `wait`

kind	含义	参数	支持工具
`none`	立即返回（命令继续在后台跑）= 异步启动	—	`shell_run`
`idle`	等回到空闲/提示符（默认行为）	—	`shell_run` / `shell_read`
`bell`	等到响铃（BEL）	—	`shell_run` / `shell_read`
`match`	等待开始后新出现的输出匹配正则（JS 方言、区分大小写）	`pattern`	`shell_run` / `shell_read`
`exit`	命令结束；可校验退出码。同一次 shell_run 可直接用；`shell_read` 上用于已异步启动并拿到 `runId` 的命令，扫缓冲里的退出码标记	`code`（0–255）、`runId`（仅 read）	`shell_run` / `shell_read`
`file`	文件出现（支持 `~`）	`path`	`shell_run`
`noproc`	进程从窗格进程树消失	`proc`	`shell_run`
`cpu`	前台进程 CPU 占用低于阈值	`threshold`（0–100）	`shell_run`
`foreground`	前台命令变成指定进程	`proc`	`shell_read`

通用字段：timeoutMs（默认 30000，上限 24 小时；超时只回报“超时”，不杀进程）、 pollMs（默认 150，仅 shell_run 与 shell_send；shell_send 只有 pollMs）、 runId（仅 shell_read 的 exit：绑定到某一次 shell_run，其返回里带 run=<id>）。

4. `output` / `safety`

output.lines：默认 20，上限 2000（tail 保留最后 N 行；since 超过 2000 行保留最后 2000 行并标注）。
output.showing（仅 shell_run）：since（默认，本次调用新增）/ tail（显式，含旧屏/回显）/ screen / diff / summary。
output.structured（仅 shell_run）：返回块结构化（默认）或纯文本。
safety.bypassGuard：跳过危险命令守卫（必须同时给非空 reason）。
safety.dryrun：只回报会执行什么，不执行。
safety.lock：require（默认，同 shell 写操作串行，无单独超时）/ ignore。
shell_manage 的 safety 只接受 dryrun（预演 close/reap/macro-rm/workspace-delete）。

5. 各工具的 action.kind

工具	kind
`shell_open`	`open`
`shell_run`	`run` / `steps` / `retry`
`shell_send`	`send`
`shell_read`	`read` / `subscribe` / `unsubscribe`
`shell_manage`	`rename` / `resize` / `respawn` / `close` / `reap` / `idle` / `snapshot` / `snapshot-list` / `doctor` / `macro-set` / `macro-rm` / `macro-list` / `vault-list` / `macro-history` / `macro-restore` / `workspace-save` / `workspace-list` / `workspace-restore` / `workspace-delete`
`shell_audit`	`audit`

各 kind 自己的参数见参数定义。

6. 常见错误与修法

现象	原因	修法
`tasks 不认识的字段：session/command`	字段放错了层级	改成 `{ tasks: [{ target, action }] }`
`action 不认识的字段`	把别的 action 的参数混进来了	按对应 kind 只传自己的字段
`shell_run.action.command 在 kind=run 时必填`	少了 command	补上；或改用 `steps`
`target.sessions="*" 不允许写操作`	写操作不允许扇出到全部 shell	改成具体 id 或 `mine`
`无法等待 exit：expanded（不会注入 __DSH_EXIT__ 标记）`	命令里含 `/` 展开	改用 `wait.kind="idle"`，或包一层 `sh -c "…"`
命令跑完但 shell 没了	命令里写了 `exit`	它会结束 shell 本身；需要提前返回用子 shell `( … )`
`同一个 shell 在一次调用里只能被操作一次`	两个任务指向同一 shell	拆成多次调用

7. 附录：枚举取值与两条硬约束

契约：操作是操作，参数是参数 —— action.kind 表达操作，其余字段只描述该操作的细节；不允许用参数暗示操作（例如用 until:"done" 表示等待）。

shell_manage action=reap：只清理闲置 ≥ 10 分钟且「丢失但记录还在」的僵尸会话（阈值 REAP_MIN_IDLE_MS）。

shell_state.state：

值	含义
`idle`	空闲（前台是 shell 且窗格安静）
`busy`	忙碌（前台有命令或 CPU 活跃）
`user-busy`	人正在操作（AI 写入会被拒）
`ai-busy`	本对话正在操作
`locked`	已锁定（手动锁或他人占用）
`unlocked`	未锁定
`attached`	有客户端附着（面板/终端已连上）

shell_state.owner：mine 本对话创建 · others 别的对话创建 · panel 人在面板创建 · unknown 未登记。

shell_run.retry.mode：last 直接重跑本 shell 最近一条命令 · last-failed 只有上一条失败时才重跑。

其余枚举：wait.kind 见 §3；shell_read.read.mode：tail 末尾 · screen 当前可见屏 · history 历史缓冲 · since 自上次读以来 · diff 与上次相比 · summary 摘要；output.showing：tail / screen / diff / since / summary； safety.lock：require（串行等待）/ ignore；target.sessions：mine / * / 显式 id。

8. 长任务示例（异步启动 → 读增量 → 取退出码）

{ "tasks": [{ "action": { "kind": "open", "label": "build", "cwd": "/repo" } }] }
{ "tasks": [{ "target": { "sessions": "dsh-ab12cd" },
              "action": { "kind": "run", "command": "make -j8" },
              "wait": { "kind": "none" } }] }                      // 返回里带 run=<id>
{ "tasks": [{ "target": { "sessions": "dsh-ab12cd" },
              "action": { "kind": "read", "mode": "since" } }] }   // 反复取新增
{ "tasks": [{ "target": { "sessions": "dsh-ab12cd" },
              "action": { "kind": "read" },
              "wait": { "kind": "exit", "runId": "ab12cd34", "timeoutMs": 180000 } }] }
{ "tasks": [{ "target": { "sessions": "dsh-ab12cd" }, "action": { "kind": "close" } }] }

↑ 回到目录

2. 参数定义

本节按当前版本的参数定义整理；实际行为以运行时为准。

工具级参数（所有 `tasks` 型工具）

参数	类型	单位	默认	范围	必填	含义	备注
`tasks`	array	个	—	1 – 16	是	一次调用里的任务列表；任务之间并行执行，同一 shell 在一次调用里只能出现一次。	超过 16 个直接拒绝；重复出现同一个 shell 会整次调用被拒。
`concurrency`	number	个	4	1 – 8	否	任务之间、任务内各会话之间的最大并行数。	超过上限夹到 8；1 = 完全串行。

`target` 块

参数	类型	单位	默认	范围	必填	含义	备注
`sessions`	string		mine	mine / * / 逗号分隔的 shell id	否	操作目标：mine = 本对话创建的全部 shell（默认；只有一个会话时即该会话，多个时必须用 id 精确指定）；* = 全部存活 shell（只读可用；写操作会被拒绝）；或显式 id（如 dsh-ab12cd,dsh-cd34）。	同一个 shell 在一次调用里只能出现在一个任务中。

`wait` 块

参数	类型	单位	默认	范围	必填	含义	备注
`kind`	enum		idle	none / idle / bell / match / exit / file / noproc / cpu / foreground	否	等待条件：none = 立即返回（异步启动）；idle = 等回到空闲/提示符；bell = 等响铃；match = 新输出匹配正则；exit = 命令结束（可校验退出码）；file = 文件出现；noproc = 进程消失；cpu = 前台进程 CPU 低于阈值；foreground = 前台变成指定进程。	shell_run 支持 none/idle/bell/match/exit/file/noproc/cpu；shell_read 支持 idle/bell/match/exit/foreground；shell_send 只有 pollMs。
`timeoutMs`	number	ms	30000	0 – 86400000	否	等待条件最多等多久；超时只回报“超时”，不杀进程。	上限 24 小时；两分钟以上的命令请显式给值。shell_run / shell_read 支持。
`pollMs`	number	ms	150	20 – 100000	否	轮询间隔（shell_run 检查条件、shell_send 等屏幕稳定的间隔）。	shell_run / shell_send 支持；shell_read 不支持。
`code`	number	退出码	—	0 – 255	否	kind=exit 时同时校验退出码；不符会立即回报 `exit=N ≠ 期望`。	仅 kind=exit 有意义。
`runId`	string		—	shell_run 返回的 run=	否	kind=exit 时绑定到某一次具体的 shell_run（多命令先后跑时不会认错退出码）。	仅 shell_read 支持；不传则绑定本 shell 最近一次 shell_run。
`pattern`	string		—	JS 正则	否	kind=match 时要匹配的正则（区分大小写，只匹配等待开始后新出现的输出）。	仅 kind=match；正则非法会直接拒绝。
`path`	string		—	文件路径（支持 ~）	否	kind=file 时要等的文件。	仅 kind=file。
`proc`	string		—	进程名	否	kind=noproc 等该进程从窗格进程树消失；kind=foreground 等前台变成该进程。	noproc 仅 shell_run；foreground 仅 shell_read。
`threshold`	number	%	—	0 – 100	否	kind=cpu 时前台进程 CPU 占用低于该阈值即到达。	仅 shell_run。

`output` 块

参数	类型	单位	默认	范围	必填	含义	备注
`lines`	number	行	20	0 – 2000	否	返回多少行；tail 保留最后 N 行；since 的新增超过 2000 行会保留最后 2000 行并标注丢弃量。	上限 2000；history 模式另有更大的读法。
`showing`	enum		since	tail / screen / diff / since / summary	否	返回形状：默认 since 只返回本次 shell_run 发送后新增的输出；显式 tail 才返回末尾缓冲（含旧屏/回显）/ screen 当前可见屏 / diff 与上次读取相比 / summary 末尾若干行并标注总行数。	仅 shell_run 支持；shell_read 用 action.mode。
`structured`	boolean		true	true / false	否	true = 按块结构化返回（汇总头 + 每任务一段）；false = 一段纯文本。	仅 shell_run。

`safety` 块

参数	类型	默认	范围	必填	含义	备注
`bypassGuard`	boolean	false	true / false	否	跳过危险命令守卫（必须同时给非空 reason；审计记 bypass-guard）。	只在用户明确要求时用；无 reason 会被拒绝。shell_run / shell_send 支持。
`dryrun`	boolean	false	true / false	否	只回报将要执行什么，不真正执行。	shell_run / shell_send / shell_manage（仅破坏性动作）支持。
`lock`	enum	require	require / ignore	否	require = 同一 shell 的写操作串行（默认，无单独超时）；ignore = 不等待会话锁。	人工锁定与它无关：被人工锁定的 shell 会立刻 REFUSED。
`reason`	string		任意文本	否	写进审计的原因（bypassGuard 时必填）。	会进审计记录。
`force`	boolean	false	true / false	否	引用库口令组未解锁时是否强制继续（口令组仍会被拒绝）。	只影响引用展开路径。

各工具的 action 参数

`shell_open.open`

参数	类型	单位	默认	范围	必填	含义	备注
`count`	number	个	1	1 – 64	否	一次创建几个 shell（预检：现有 + count 超上限就整批拒绝）。	任务内部并发创建，上限默认 8（设置项 maxSessions）。
`cwd`	string		继承部署配置	目录路径	否	起始工作目录；省略则继承部署配置（有对话信息时用对话目录）。	—
`label`	string			≤32 字符	否	会话命名基名，同时是面板显示名。	任务级 label 是分块名，两者不同。
`cols`	number	列	120	20 – 1000	否	初始列数（tmux 宽度）。	—
`rows`	number	行	32	5 – 500	否	初始行数（tmux 高度）。	—
`idleMinutes`	number	分钟	0	0 – 1440	否	闲置多少分钟自动关闭；0 = 永不自动关闭；省略 = 跟随全局设置（总开关关时永不回收，开启时按 idleCloseMinutes 兜底）。	闲置 = 无输入且前台无命令；只读屏不算活动。
`watch`	boolean		false	true / false	否	创建后顺便订阅新输出（等价于再调一次 shell_read 的 subscribe；重复订阅幂等）。	TUI 程序不要订阅。
`from`	string			旧会话 id	否	从快照复活：传旧会话 id（取该会话最近一次快照）。	close / 空闲回收 / resize / rename 会自动留快照。

`shell_run.run`

参数	类型	单位	默认	范围	必填	含义	备注
`command`	string		—	任意命令	是	要执行的命令；可用引用引用库的值。	命令会被包装以注入退出码标记；不可包装的命令在 wait=exit 时发送前拒绝。

`shell_run.steps`

参数	类型	单位	默认	范围	必填	含义	备注
`steps`	array	步	—	1 – 50	是	步骤序列：每步 { label?, send?, expect?, timeoutMs? }；send 自动回车，expect 只支持 idle / match / file / bell（exit/noproc/cpu 用 run + wait）。	适合短交互流程；steps 不注入退出码标记。

`shell_run.retry`

参数	类型	单位	默认	范围	必填	含义	备注
`mode`	enum		—	last / last-failed	是	last = 直接重跑本 shell 最近一条命令；last-failed = 只有上一条失败时才重跑。	—

`shell_send.send`

参数	类型	默认	范围	必填	含义	备注
`text`	string	—	不含换行	是	要输入的文本；不含回车（提交要另外给 keys:[“Enter”]）。只发控制键时传空串 ““。	含 \n / \r 会被拒绝（会被终端当成提交）。
`keys`	array		tmux 键名数组	否	文本之后要按的键，如 [“Enter”]、[“C-c”]、[“Tab”]。	只有 shell_run 注入的命令才有退出码标记。
`preKeys`	array		tmux 键名数组	否	文本之前要按的键，常用于先 Ctrl-C 清场。	—

`shell_read.read`

参数	类型	单位	默认	范围	必填	含义	备注
`search`	string		—	JS 正则	否	在缓冲里搜索（区分大小写）；命中返回「共 N 处，本页 M 处，从第 K 条起」。	给 search 时忽略 mode。
`context`	number	行	0	0 – 8	否	搜索命中行前后各取几行上下文。	—
`matchOffset`	number	条	0	0 – 100000	否	搜索分页：跳过前 N 个命中；续翻用返回里的 `matchOffset=K`。	—
`mode`	enum		tail	tail / screen / history / since / diff / summary	否	读哪里：tail 末尾 / screen 当前可见屏 / history 历史缓冲 / since 自上次读以来 / diff 与上次相比 / summary 摘要。	读取形状用 mode，不用 output.showing。
`ifChanged`	boolean		false	true / false	否	true 时只有屏幕变化才返回内容（没变化只回 unchanged）。	—

`shell_read.subscribe`

无参数。

`shell_read.unsubscribe`

无参数。

`shell_manage.rename`

参数	类型	单位	默认	范围	必填	含义	备注
`newName`	string		—	≤32 字符	是	新的显示名。	—

`shell_manage.resize`

参数	类型	单位	默认	范围	必填	含义	备注
`cols`	number	列	保持当前	20 – 1000	否	新列数（不传则保持）。	—
`rows`	number	行	保持当前	5 – 500	否	新行数（不传则保持）。	—

`shell_manage.respawn`

无参数。

`shell_manage.close`

无参数。

`shell_manage.reap`

无参数。

`shell_manage.idle`

参数	类型	单位	默认	范围	必填	含义	备注
`idleMinutes`	number	分钟	0	0 – 1440	否	闲置多少分钟自动关闭；0 = 永不自动关闭。	—

`shell_manage.snapshot`

无参数。

`shell_manage.snapshot-list`

无参数。

`shell_manage.doctor`

参数	类型	单位	默认	范围	必填	含义	备注
`note`	string			任意文本	否	自检备注（写进审计）。	—

`shell_manage.macro-set`

参数	类型	默认	范围	必填	含义	备注
`name`	string	—	≤64 字符	是	宏名。	—
`text`	string	—	任意文本	是	宏内容（命令片段）。	—
`scope`	enum	conversation	global / conversation / shell	否	宏的可见范围。	—
`submit`	boolean	true	true / false	否	展开后是否自动回车。	—
`note`	string		任意文本	否	备注（写进审计）。	—

`shell_manage.macro-rm`

参数	类型	单位	默认	范围	必填	含义	备注
`name`	string		—	宏名	是	要删除的宏名。	—

`shell_manage.macro-list`

无参数。

`shell_manage.vault-list`

无参数。

`shell_manage.macro-history`

参数	类型	单位	默认	范围	必填	含义	备注
`name`	string		—	宏名	是	要回看历史的宏名。	—
`days`	number	天	7	1 – 3650	否	回看最近几天。	—

`shell_manage.macro-restore`

参数	类型	单位	默认	范围	必填	含义	备注
`name`	string		—	宏名	是	要还原的宏名。	—
`at`	number	ms（epoch）	—	历史时间戳	是	要还原到的历史时间戳（用 macro-history 查）。	—

`shell_manage.workspace-save`

参数	类型	单位	默认	范围	必填	含义	备注
`name`	string		—	≤64 字符	是	工作区名。	—

`shell_manage.workspace-list`

无参数。

`shell_manage.workspace-restore`

参数	类型	单位	默认	范围	必填	含义	备注
`name`	string		—	工作区名	是	要恢复的工作区名（会新开 shell，不是原地恢复）。	—

`shell_manage.workspace-delete`

参数	类型	单位	默认	范围	必填	含义	备注
`name`	string		—	工作区名	是	要删除的工作区名。	—

`shell_audit.audit`

参数	类型	单位	默认	范围	必填	含义	备注
`actor`	string			操作者 id 或 panel	否	按操作者过滤。	—
`source`	enum			tool / panel / host / cli	否	按来源过滤。	—
`days`	number	天	1	1 – 3650	否	回看最近几天。	—
`export`	boolean		false	true / false	否	导出原始 JSONL（配合 days；最多 output.lines 条）。	—

`shell_state` 过滤条件

参数	类型	默认	范围	必填	含义	备注
`scope`	enum	mine	mine / *	否	mine = 本对话创建的（默认）；* = 全部存活 shell（必须显式传）。	—
`sessions`	string		id 或逗号分隔	否	按 shell id 过滤。	—
`label`	string		子串	否	按显示名子串过滤。	—
`fg`	string		子串	否	按前台命令子串过滤。	—
`cwd`	string		子串	否	按工作目录子串过滤。	—
`state`	enum		idle / busy / user-busy / ai-busy / locked / unlocked / attached	否	按状态过滤（逗号分隔可多选，取并集）。	—
`owner`	enum		mine / others / panel / unknown	否	按创建者过滤。	—
`withGit`	boolean	false	true / false	否	附带 git 分支（每行一次 git 调用）。	—
`verbose`	boolean	false	true / false	否	附带诊断尾（服务端/宿主/看门狗/配置等）。	—

↑ 回到目录

工具与参数

目录

1. 结构与规则

1. 调用结构

2. target

3. wait

4. output / safety

5. 各工具的 action.kind

6. 常见错误与修法

7. 附录：枚举取值与两条硬约束

8. 长任务示例（异步启动 → 读增量 → 取退出码）

2. 参数定义

工具级参数（所有 tasks 型工具）

target 块

wait 块

output 块

safety 块

各工具的 action 参数

shell_open.open

shell_run.run

shell_run.steps

shell_run.retry

shell_send.send

shell_read.read

shell_read.subscribe

shell_read.unsubscribe

shell_manage.rename

shell_manage.resize

shell_manage.respawn

shell_manage.close

shell_manage.reap

shell_manage.idle

shell_manage.snapshot

shell_manage.snapshot-list

shell_manage.doctor

shell_manage.macro-set

shell_manage.macro-rm

shell_manage.macro-list

shell_manage.vault-list

shell_manage.macro-history

shell_manage.macro-restore

shell_manage.workspace-save

shell_manage.workspace-list

shell_manage.workspace-restore

shell_manage.workspace-delete

shell_audit.audit

shell_state 过滤条件

相关文档

2. `target`

3. `wait`

4. `output` / `safety`

工具级参数（所有 `tasks` 型工具）

`target` 块

`wait` 块

`output` 块

`safety` 块

`shell_open.open`

`shell_run.run`

`shell_run.steps`

`shell_run.retry`

`shell_send.send`

`shell_read.read`

`shell_read.subscribe`

`shell_read.unsubscribe`

`shell_manage.rename`

`shell_manage.resize`

`shell_manage.respawn`

`shell_manage.close`

`shell_manage.reap`

`shell_manage.idle`

`shell_manage.snapshot`

`shell_manage.snapshot-list`

`shell_manage.doctor`

`shell_manage.macro-set`

`shell_manage.macro-rm`

`shell_manage.macro-list`

`shell_manage.vault-list`

`shell_manage.macro-history`

`shell_manage.macro-restore`

`shell_manage.workspace-save`

`shell_manage.workspace-list`

`shell_manage.workspace-restore`

`shell_manage.workspace-delete`

`shell_audit.audit`

`shell_state` 过滤条件