dsh-planner-executor

Readme

# dsh-planner-executor

DeepSeek Harness 插件：**规划/执行分离**。

- 主模型（会话所选模型）负责分析问题、制定计划、汇总结果；
- 执行工作通过工具 `delegate_execution` 委派给**独立的执行子代理**；
- 执行子代理的模型 / LLM 提供方 / 人格 / 工具范围在 Web 设置面板「**规划与执行**」分节配置（留空 = 继承主模型）；
- 子代理在独立会话中执行，**中间步骤永不进入主会话**，只有最终汇报回到主模型 —— 最大化节约主模型 token，且让不同角色各用最合适的模型。

零构建依赖、纯 JS（ESM 宿主 + 手写浏览器 bundle），即装即用。

## 安装

```bash
# 1. 安装进 web profile
dsh plugin --profile web add "github:mikuuuuuue/dsh-planner-executor"

# 2. 把插件加入 bundle 层
#    编辑 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles，追加：
#    "dsh-planner-executor"

# 3. 重启 dsh web 进程
```

> 本地开发提示：以 `file:` 方式安装本地源码目录时，pnpm 会**拷贝**目录而非
> 符号链接，改动源码后需重新执行 install 再重启；发布新版本后重新 add 升级。

## 测试

```bash
npm install   # 拉取 devDependencies
npm test      # host-boot（24 项）+ client-smoke（1 项）
```

## 配置

Web 设置 → 「规划与执行」：

| 字段 | 含义 |
|---|---|
| 子代理后端 | `spawn`（全新上下文，省 token，默认）/ `fork`（继承主代理已完成轮次） |
| LLM 提供方 | 执行子代理的 provider 路由；留空 = 继承主模型提供方 |
| 执行模型 | 执行子代理的模型 ID；留空 = 继承主模型 |
| 单次执行最大 Token | 子代理 token 预算；0 = 继承 |
| 最大委派深度 | 递归上限；0 = 禁止委派（默认 3） |
| 执行者人格 | 子代理 persona（覆盖部署默认人格） |
| 允许工具 / 禁止工具 | 子代理工具过滤（逗号分隔）；`delegate_execution` 自身**永远**被禁止 |
| 规划者指引 | 只对顶层主代理显示的系统提示词段（引导「规划 → 委派 → 汇总」） |

保存后对**下一次** `delegate_execution` 调用即时生效（每次调用实时读取设置）。

## 工作原理

- 主代理调用 `delegate_execution(task, context)` → 插件读取设置 → `ctx.subagents.start(backend, { agentOptions: { provider?, model?, maxTokens? }, persona, toolFilter, maxDepth, ... })`。
- 子代理通过 `agentOptions` 显式指定模型/提供方（`resolveChildAgentOptions` 覆盖继承值），在其独立会话中执行并返回最终汇报；`run.result` 的 `stopReason` 非 `completed` 时（超限/取消/拒绝/失败）映射为带原因的错误并附保留的部分输出。
- 安全边界（由 dsh-subagent 接缝保证 + 插件自加）：
  - 子代理权限固定在继承的沙箱范围内，审批策略固定为 `never`，无法自拓宽；
  - 子代理的工具目录不含 `delegate_execution`（toolFilter 强制 deny），且即使被构造调用，深度守卫（`delegationDepth > 0`）也会拒绝；
  - `maxDepth` 限制递归委派。
- 规划指引段按深度动态渲染：只有顶层代理（delegation depth 0）看得到；子代理与冷组装看到空串。

## 已知限制

- 工具从宿主平面注册（对个人单 profile 部署无影响）：所有会话的主代理都可见 `delegate_execution`；执行子代理因 toolFilter 不可见。
- 不支持按次调用的动态模型参数（模型选择是部署级配置，保证 schema 与 KV cache 前缀稳定）。
- 未引入 `outputSchema` 结构化汇报（可作后续增强）。

## 测试

`test/host-boot.test.mjs` 用真实 cordis Context + 内存 settings 提供方 + 假 subagents/llm/webServer 驱动工具与设置路由；`test/client-smoke.test.mjs` 在 Node 中加载浏览器 bundle 校验契约。

## License

MIT