@dsh-external/dsh-task-router

Readme

# dsh-task-router

> 简体中文 | [English](README.en.md)

> **这是一个由 AI 工具大量参与制作的插件。**
> 本项目在开发过程中使用了 GLM、DeepSeek、Qwen 等 AI 工具辅助设计、编码、测试与文档撰写。

`dsh-task-router` 是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 插件：让主模型从“事必躬亲”变成“规划者 + 验收者 + 复杂问题亲自动手者”。

主模型可以把网页搜索、网页浏览总结、图片转述、图像生成、代码实现、结果核查等任务委派给子模型或外部 API，从而降低主模型 token 消耗，并保持主模型对核心决策的控制权。

---

## 功能特性

- **任务委派工具**
  - `task_search`：Tavily 搜索，返回精简摘要，主模型不接触原始网页。
  - `task_browse`：Tavily Extract 抓取网页，交给子模型总结转述。
  - `task_image_describe`：把 DSH 图片引用交给视觉模型转述。
  - `task_image_generate`：OpenAI 兼容 `/images/generations`，也支持自定义 REST 模板。
  - `task_code`：把代码实现/修改任务委派给代码子代理。
  - `task_verify`：把成果交给核查子代理，返回结构化问题清单，并支持机械问题自动回炉。
- **信息隔离**
  - 主模型默认不直接接触原始网页内容。
  - 子代理默认禁止再次调用 `task_*`，防止递归委派。
- **可视化设置**
  - DSH 设置栏中的“任务配置”页面。
  - 简单 / 高级模式切换。
  - 预设厂商、Provider / Model 下拉、API Key 凭据写入 DSH 凭据库。
  - 全局启用 / 禁用开关。
  - 暗色模式与移动端适配。
- **安全边界**
  - 子代理默认有 `toolFilter`，禁止递归委派。
  - code / verify 子代理会按角色钉入沙箱模式（code 默认 `workspace-write`，verify 默认 `read-only`）。
  - 配置只保存凭据引用，不保存明文 API Key。

---

## 安装

### 前置要求

- Node.js `>= 20.3`
- 已安装 DeepSeek Harness（DSH）环境
- 已准备的 API Key：
  - Tavily（搜索 / 浏览）
  - 代码 / 核查 / 图片转述模型对应的 Provider API Key
  - 图像生成 API Key（可选）

### 构建

```bash
npm install
npm run build
```

### 装配到 DSH

使用 DSH 的插件注入或 bundle 装配机制加载 `@dsh-external/dsh-task-router`。

常见方式：

```bash
# 使用超级模组注入器（开发热加载）
dev_inject_plugin {"dir": "/path/to/dsh-task-router"}
```

或在 DSH profile 中通过 `cordis.patch.yml` 注册：

```yaml
- insert:
    - id: dsh-task-router
      name: '@dsh-external/dsh-task-router'
      config: {}
```

> `lib/` 是构建产物，默认不提交到 Git。安装或打包时会通过 `prepare` / `prepack` 自动构建。

---

## 配置

配置存储在：

```text
~/.dsh/task-router/config.json
```

API Key 不写入该文件，而是通过 `apiKeyEnv` 引用 DSH 凭据库中的凭据。

默认角色：

| 角色 | 用途 |
|---|---|
| `main` | 主模型：规划、验收、核心决策 |
| `search` | Tavily 搜索 |
| `browse` | 网页抓取与总结 |
| `code` | 代码实现 / 修改子代理 |
| `image-describe` | 图片转述 |
| `image-generate` | 图像生成 |
| `verify` | 成果核查子代理 |

---

## 工具

| 工具 | 说明 |
|---|---|
| `task_search(query, max_results?)` | 调用 Tavily Search，返回精简结果。 |
| `task_browse(url, instruction?)` | 抓取网页并可选的子模型总结。 |
| `task_image_describe(image_ref, instruction?)` | DSH 图片引用 → 视觉模型文字转述。 |
| `task_image_generate(prompt)` | 生成图片并保存到本地。 |
| `task_code(requirement, context?, allowed_paths?, allowed_commands?)` | 委派代码子代理实现 / 修改。 |
| `task_verify(output_ref, requirement)` | 委派核查子代理并返回结构化结果。 |

---

## 已知限制

- **`allowed_paths` / `allowed_commands` 目前只是提示词建议，不是系统级强制限制**。子代理仍可能访问工作区外或执行未列出的命令。
- `task_image_describe` 只接受 DSH 图片 attachment JSON 引用，暂不支持本地文件系统路径。
- 设置页没有模型搜索 / 分页，模型很多时下拉会较长。
- 实时模型调用日志 / 实时任务状态指示器已移除（该功能存在稳定性问题）。
- 暂无 i18n 多语言支持。

---

## 安全说明

- 本地 HTTP API 的写操作（配置、凭据）会校验请求来源，只允许同源 / loopback 请求。
- 配置与凭据分离：配置中不保存明文 API Key。
- 对外错误信息经过脱敏。
- 代码子代理默认运行在可写工作区沙箱，核查子代理默认只读；但请勿把敏感工作区交给不可信模型运行。

更多细节见 [SECURITY.md](SECURITY.md)。

---

## 开发

```bash
npm run typecheck   # TypeScript 类型检查
npm test            # Vitest 单元测试
npm run build       # tsc + tsdown 构建
npm run check       # typecheck + test + build
```

### 目录结构

```text
src/
  index.ts          # host 插件入口、HTTP API、prompt hooks
  config.ts         # 配置 schema、校验、预设
  tools/            # 委派工具与子代理工具
  adapters/         # Tavily / LLM / Image / REST 适配器
  client/           # React 设置页
tests/              # 单元测试
docs/               # 技术文档
```

---

## 相关文档

- [更新日志](CHANGELOG.md)
- [安全说明](SECURITY.md)
- [贡献指南](CONTRIBUTING.md)
- [行为准则](CODE_OF_CONDUCT.md)

## 许可证

[BSD-3-Clause](LICENSE)

本项目允许任何人**二次修改、传播、商用**，只要求保留原项目署名及本声明。没有“禁止盈利”之类的限制。

## AI 参与声明 / 高度 AI 属性

本项目具有**高度 AI 性质**：

- 本项目由 **TIKO** 发起。
- 设计、编码、测试、文档整理均由 **GLM、DeepSeek、Qwen 等 AI 工具**大量参与完成。
- **连项目提交都是 DeepSeek 操作的。**
- 这不是一个“纯手工作品”，而是一个高度 AI 协作生成、并由 AI 完整执行发布流程的开源项目。

任何人若基于本项目二次修改或传播，请保留：

- 原项目名 `dsh-task-router`
- 原作者署名 **TIKO**
- 本 AI 参与声明
- 本项目许可证与版权声明