@jw-king/dsh-plugin-parallel

DeepSeek Harness (DSH) 插件：封装 Parallel Search & Extract API，提供网页搜索和内容提取工具。

English | 中文文档

概述

为 DeepSeek Harness 添加两个工具：

| 工具 | 说明 | |---|---| | web_parallel_search | 实时网页搜索，返回带摘要的排序结果 | | web_parallel_fetch | 从公开 URL 提取干净的 Markdown 内容 |

两个工具均直接调用 Parallel Search & Extract API。

安装

# 通过 DSH CLI 安装（推荐）
dsh plugin --profile web add @jw-king/dsh-plugin-parallel

# 本地开发安装
pnpm install && pnpm run build
dsh plugin --profile web add file:./path/to/dsh-plugin-parallel

认证

插件通过 DSH credentials seam（ctx.credentials）管理 Parallel API key。

方式一：DSH Web UI（推荐）

1. 打开 DSH Web UI → 设置 → 插件
2. 找到 @jw-king/dsh-plugin-parallel，填写 API key
3. key 写入 $DSH_HOME/.credentials.yaml

方式二：环境变量（CLI / 无头模式）

export PARALLEL_API_KEY="your-key-from-platform.parallel.ai"

降级优先级

| 优先级 | 来源 | 说明 | |---|---|---| | 1 | credentialKey('dsh-plugin-parallel', 'parallel-api-key') | DSH 托管存储（.credentials.yaml） | | 2 | credentialRef('PARALLEL_API_KEY') | DSH credentials 服务 → 环境变量 | | 3 | process.env['PARALLEL_API_KEY'] | 直接读取（测试/CI 兜底） | | 4 | 无 key | 工具调用直接报错（Parallel API 无匿名层） |

API key 永不写入配置文件、日志或错误消息。

更新

升级到最新发布版本（升级后重启 dsh web 生效）：

# 方式一：npx 运行 DSH
npx @deepseek-ai/dsh plugin --profile web add @jw-king/dsh-plugin-parallel@latest

# 方式二：全局安装的 CLI
dsh plugin --profile web add @jw-king/dsh-plugin-parallel@latest

# 查看当前安装的版本
dsh plugin --profile web why @jw-king/dsh-plugin-parallel

add @latest 不受已记录 semver 范围限制；而 dsh plugin --profile web update @jw-king/dsh-plugin-parallel 只会在已记录的 ^0.2.x 范围内升级。

⚠️ pnpm v11 注意：默认 minimumReleaseAge（24 小时）供应链策略会跳过刚发布的版本，add @latest 可能静默停留在旧版本（提示 Already up to date）。此时用以下命令一次性覆盖策略升级——无需指定版本：

dsh plugin --profile web update @jw-king/dsh-plugin-parallel --latest --config.minimumReleaseAge=0

备选：锁定精确版本（add @jw-king/[email protected]，pnpm 自动放行）；或在 profile 的 ~/.dsh/profiles/web/pnpm-workspace.yaml 中永久放行该 scope：minimumReleaseAgeExclude: ['@jw-king/*']（pnpm ≥ 10.17 支持通配符）。

卸载

# 方式二（全局 CLI）：从 profile 移除插件（bundles 注册自动清理）
dsh plugin --profile web remove @jw-king/dsh-plugin-parallel

# 方式一（npx）：把 dsh 换成 npx @deepseek-ai/dsh
npx @deepseek-ai/dsh plugin --profile web remove @jw-king/dsh-plugin-parallel

与升级同理：若已装版本发布不足 24 小时，remove 也会被 minimumReleaseAge 策略拦截，追加 --config.minimumReleaseAge=0 即可。

可选的手动清理（不再使用时）：

• ~/.dsh/.credentials.yaml 中 dsh-plugin-parallel 下的 parallel-api-key 凭据条目（或通过 DSH Web UI → 设置 → 插件删除）
• PARALLEL_API_KEY 环境变量：[Environment]::SetEnvironmentVariable('PARALLEL_API_KEY', $null, 'User')（Windows）或从 shell 配置文件中移除

工具

web_parallel_search

使用 Parallel Search API 实时搜索网页。

参数：

| 名称 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | objective | string | ✅ | — | 用自然语言描述要回答的问题 | | search_queries | string[] | ✅ | — | 关键词查询（1–5 条，每条 3–6 词） | | mode | string | ❌ | fast | turbo / fast / basic / advanced | | max_results | number | ❌ | 5 | 最大结果数（1–20） | | max_chars_total | number | ❌ | 8000 | 摘要总字符上限 |

示例：

{
  "objective": "AI agent 最新进展是什么？",
  "search_queries": ["AI agent 2025", "大模型智能体"],
  "mode": "fast",
  "max_results": 5
}

web_parallel_fetch

从公开 URL 提取干净的 Markdown 内容。

参数：

| 名称 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | urls | string[] | ✅ | — | 公开 URL（1–10 个） | | objective | string | ❌ | — | 可选，聚焦提取内容的方向 | | max_chars_total | number | ❌ | 8000 | 摘要总字符上限 | | full_content | boolean | ❌ | false | 是否返回完整页面 Markdown |

示例：

{
  "urls": ["https://example.com/article"],
  "max_chars_total": 5000
}

测试

pnpm install
pnpm run test       # 单元测试（vitest，离线运行）
pnpm run test:e2e   # E2E 测试（需设置 PARALLEL_API_KEY）
pnpm run verify     # DSH 插件规范合规检查

测试分层

| 层级 | 命令 | 说明 | |---|---|---| | 单元 | pnpm run test | 纯逻辑 + schema 检查，mock fetch | | E2E | pnpm run test:e2e | 真实 Parallel API 调用，无 key 时自动跳过 | | 合规 | pnpm run verify | DSH Plugin Standard v2.0 MUST 级校验 |

项目结构

@jw-king/dsh-plugin-parallel/
├── src/
│   ├── index.ts              # 插件入口：工具注册
│   ├── helpers.ts            # 纯函数：输入清洗、渲染、HTTP 客户端
│   └── credentials.ts        # DSH credentials seam 封装
├── lib/                      # 构建产物（发布时包含）
├── cordis.patch.yml          # bundle patch 描述
├── scripts/
│   └── verify-plugin.mjs     # 合规检查脚本
├── tests/
│   ├── unit/
│   │   ├── helpers.spec.ts   # 17 cases：清洗、渲染
│   │   └── plugin.spec.ts    # 16 cases：schema、凭证 mock、fetch mock
│   └── e2e/
│       └── search.spec.ts    # 6 cases：真实 API 集成
├── CONTRIBUTING.md
├── CHANGELOG.md
├── README.md
├── README.zh-CN.md
├── package.json
└── tsconfig.json

开发

pnpm install
pnpm run typecheck   # 类型检查
pnpm run build       # 编译到 lib/
pnpm run test        # 运行单元测试
pnpm run verify      # 运行合规检查
pnpm run pack        # 模拟打包检查

规范遵循

本插件严格遵循 DSH 插件规范 v2.0：

• P1 最小运行面：纯 host bundle，无浏览器 client
• P2 单一事实源：包名 = patch name = export name
• P3 生命周期可清理：工具由 Cordis 自动管理生命周期
• P4 默认拒绝：无本地 HTTP 路由；API key 经 DSH credentials 管理；错误不泄露内部细节
• P5 可验证可发布：typecheck/build/test/verify/pack 脚本齐备

API 参考

• Parallel Search API
• Parallel Extract API
• MCP 服务（替代访问方式）

贡献指南

详见 CONTRIBUTING.md。

许可

MIT © jw-king