# deepseek-harness-plugins

**Repository Path**: hivedark/deepseek-harness-plugins

## Basic Information

- **Project Name**: deepseek-harness-plugins
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSeek Harness Plugins

基于 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 框架的插件集合与实验项目。

## 项目结构

```
deepseek-harness-plugins/
├── agents/                  # Agent Skill 定义（TypeScript，使用 SkillService.register）
│   ├── README.md            # Agent Skill 文档
│   ├── boss/index.ts        # 调度主管 skill
│   └── tester/index.ts      # 测试工程师 skill
├── plugins/                 # 插件目录
│   ├── weather-plugin/      # 天气查询 (JS)
│   ├── email-plugin/        # 邮件发送 (JS)
│   ├── dispatch-plugin/     # 智能调度 (JS)
│   └── ts-demo-plugin/      # TypeScript Demo
├── sdk-test/                # REST API 测试客户端
├── customization/           # 定制项目（harness-app 前端学习项目）
├── dsh-patch.yml            # 全局插件补丁配置
├── AGENTS.md                # Agent 工作指南
└── SDK-API.md               # SDK API 完整文档
```

## 快速开始

### 启动服务

```bash
dsh --patch ./dsh-patch.yml --profile web --no-open --port 3080
```

访问 http://127.0.0.1:3080

### SDK API 测试

```bash
cd sdk-test && npm install
node src/chat-test.js     # 聊天测试（含事件流）
node src/test.js          # 基础 API 测试
```

## 插件列表

### Weather Plugin
工具：`get_weather(city, country?)` - 预置北京、上海、深圳、东京、纽约、伦敦。

### Email Plugin
工具：`send_email(to, subject, body, cc?, bcc?)`。

### Dispatch Plugin
智能调度系统插件，可通过 patch 配置参数：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `maxResults` | number | 100 | 最大返回条数 |
| `mockDelay` | number | 0 | 模拟延迟（毫秒） |
| `enableCache` | boolean | false | 是否启用缓存 |
| `enablePagination` | boolean | false | 是否启用分页 |
| `defaultPageSize` | number | 20 | 默认分页大小 |

| 工具 | 说明 |
|------|------|
| `get_departments` | 部门列表，支持状态筛选 |
| `get_lines` | 线路列表，支持状态筛选 |
| `get_vehicles` | 车辆列表，支持状态/线路筛选 |
| `get_persons` | 人员列表，支持角色/部门/状态筛选 |
| `get_dispatch_summary` | 调度概览统计 |

### TS Demo Plugin
工具：`demo_echo(message, repeat?)`。

## Agent Skill（agents/）

使用 `@deepseek-ai/dsh-skill` 的 `SkillService.register()` API 注册运行时 skill：

```typescript
import type { Context } from '@deepseek-ai/cordis';

export const inject = ['skills', 'subagents'];
export const name = 'my-skill';

export function apply(ctx: Context) {
  ctx.skills.register({
    name: 'my-skill',
    description: '技能描述',
    invocation: { modelInvocable: true, userInvocable: true },
    source: 'runtime',
    provider: 'runtime',
    content: '提示词内容...',
    metadata: {
      type: 'subagent',
      subagentProvider: 'spawn',
      maxTurnCount: 12
    }
  });
}
```

patch 文件引用：`name: "file:///D:/path/to/agents/<name>/index.ts"`

## Patch 文件格式

插件 patch：

```yaml
- insert:
  - id: dsh-weather-plugin
    name: "file:///D:/path/to/plugin/src/index.js"
  - id: dsh-dispatch-plugin
    name: "file:///D:/path/to/dispatch-plugin/src/index.js"
    config:
      maxResults: 100
      mockDelay: 300
```

Agent Skill patch：

```yaml
- insert:
  - id: boss
    name: "file:///D:/path/to/agents/boss/index.ts"
  - id: tester
    name: "file:///D:/path/to/agents/tester/index.ts"
```

> 本地插件/Skill 必须使用 `file://` 绝对路径。

## 插件开发

### JavaScript 插件

```javascript
import { defineTool } from '@deepseek-ai/dsh-tools';

export default {
  name: 'plugin-name',
  inject: ['tools'],
  apply(ctx, config) {  // config 是第二个参数！
    ctx.tools.register(defineTool({
      name: 'my_tool',
      description: '...',
      parameters: { input: { type: 'string' } },
      output: {
        schema: { type: 'object', properties: { result: { type: 'string' } } },
        render: (_, value) => [{ type: 'text', text: value.result }]
      },
      async execute(args) { return { result: `处理: ${args.input}` } }
    }))
  }
}
```

### TypeScript 插件

```bash
cd plugins/ts-plugin
npm install && npm run build
```

## 常见问题

| 问题 | 解决 |
|------|------|
| 模块找不到 | 使用 `file://` 绝对路径 |
| 数据验证失败 | `null` 改为 `""`（空字符串）|
| apply 中拿不到 config | 用 `apply(ctx, config)`，不是 `ctx.config` |
| Plugin/Skill id 冲突 | 避免用 dsh 内置插件名（如 `skill`、`tester`、`subagent`）|

## 相关文档

- [AGENTS.md](./AGENTS.md) - Agent 工作指南
- [SDK-API.md](./SDK-API.md) - 完整 SDK API 文档
- [agents/README.md](./agents/README.md) - Agent Skill 定义指南
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)

## License

MIT