🚀 使用
工具一览
| 工具名 | 提供商 | 用途 |
|---|
subagent_with_model | spawn | 全新上下文的子代理，可指定模型 |
subagent_fork_with_model | fork | 继承当前对话上下文的子代理，可指定模型 |
subagent_status | —（进程级共享） | 查看当前工作区的委派花名册 |
调用参数
| 参数 | 说明 |
|---|
description / prompt / run_in_background | 与官方 subagent 工具语义一致 |
model（可选） | 子代理模型 id（枚举来自模型页）；省略 → 设置卡片默认值 → 继承主 agent 模型；锁定默认模型开启且默认值存在时，此参数被忽略 |
provider（可选） | 提供商路由；省略时自动解析（优先当前路由 → 唯一路由 → 歧义报错列出选项） |
max_tokens（可选） | 子代理最大输出 token；省略 → 设置卡片默认值 |
task_id（可选） | 给本次委派起名（如 t-research）；省略时等于 run id；其他委派可用它做 depends_on |
depends_on（可选） | 依赖的 task_id 列表：全部满足（completed / idle）才启动，否则报错列出未满足项 |
persona（可选） | 子代理角色人设：替换该子代理的部署人设（continuable 子代理持久化并在冷恢复时重应用）；提供商需支持 persona 能力 |
示例
subagent_with_model(description="整理日志", prompt="……", model="")
subagent_fork_with_model(
description="评审方案", prompt="……",
task_id="t-review", depends_on=["t-research"],
persona="你是一名资深代码评审，只指出真实缺陷，不客套。"
)
subagent_status() # 查看所有委派的状态与 task_id
运行状态语义
| 状态 | 含义 | 满足 depends_on |
|---|
running | 子代理正在工作 | 否 |
idle | continuable 子代理干净结束一轮（仍可被继续唤醒） | ✅ |
completed | 前台 / 后台一次性任务完成 | ✅ |
failed / cancelled | 失败 / 取消（终态，不可回退） | 否 |
注册表文件
每次委派追加一条记录到 /.dsh-subagents/runs.jsonl（追加式 JSONL，按 runId last-write-wins 折叠，超 400 行自动压缩为"活跃 + 近期终态"）。每条记录含 modelSource（模型来源：arg / default / inherited）。目录名可用 stateDir 配置；stateDir: "" 为纯内存模式，不写任何文件。多进程同时写同一工作区不保证一致（单 dsh 进程内已用 promise 链锁串行化）。
⚙️ 配置项（每个实例）
| 键 | 默认 | 含义 |
|---|
provider | 必填 | ctx.subagents 提供商名（spawn / fork / …） |
toolName | subagent_with_model | 模型可见的工具名，每个实例必须不同 |
backgroundMode | continuable | continuable（默认后台、返回持久子代理 id）或 one-shot |
maxDepth | 3 | 委派深度上限；0 禁止委派；provider-managed 交给提供商 |
stateDir | .dsh-subagents | 注册表目录名（工作区下）；"" = 纯内存跟踪 |
statusToolName | subagent_status | 花名册工具名；"" 禁用；进程内只注册一次（首个实例生效） |
trackRuns | true | 总开关：false 完全关闭注册表 / 事件 / 门控 / 花名册，回到 v0.2.x 行为 |
lockDefaultModel | false | 锁定默认模型：开启且默认模型已配置时，忽略每次调用指定的 model（设置卡片开关与之等效，任一开启即生效） |