# 方舟联网搜索插件（dsh-web-search-ark）使用指南

> 版本 1.0.0 ｜ 适配 DSH `0.1.1-rc.2` ｜ 仓库
> <https://github.com/of1102/dsh-web-search-ark>

## 一、这是什么

本插件让 DSH 内置的 `web_search` 工具**通过火山方舟（Ark）的"联网内容插件"工作**，
适用于「DeepSeek 模型走方舟 API、没有 DeepSeek 官网 key」的部署。

- 官方搜索 provider 只连 DeepSeek 官网的 Anthropic Messages 端点，会报
  `Authentication Fails ... key is invalid`；
- 本插件注册 provider `ark-official`，改调方舟的 Responses API
  （`https://ark.cn-beijing.volces.com/api/v3/responses`）并携带原生
  `{"type":"web_search","max_keyword":N}` 工具；
- 附带「设置 → 插件」页的设置卡片，可改模型、接口地址、单轮最大关键词数，
  卡片支持像内置卡片一样折叠/展开；API key 字段为密码输入框并显示
  「已配置 / 未配置」状态徽标。

## 二、包里有什么

发布 zip 内含 `web-search-ark/` 目录（4 个文件，勿改名）：

```
dsh-web-search-ark-1.0.0.zip
└── web-search-ark/
    ├── package.json                # 依赖声明、bundle 声明、客户端注入清单
    ├── cordis.patch.yml            # bundle 补丁：默认模型 / 凭证名 / maxKeyword
    └── lib/
        ├── index.js                # 服务端 provider（ark-official）
        └── client.js               # 浏览器设置卡片
```

仓库内另有：`README.md`（英文）、`docs/使用指南.md`（本文件）、
`examples/example-cordis.patch.yml`（用户补丁示例）、`test/`（冒烟测试）、
`scripts/release.mjs`（发布打包脚本）、`release/SHA256SUMS.txt`（校验和）。

## 三、环境要求

| 项目 | 要求 |
|---|---|
| DSH | **`0.1.1-rc.2`（推荐，已验证）**，`npx @deepseek-ai/dsh@0.1.1-rc.2` |
| Node / pnpm | `dsh plugin` 是 pnpm 转发器，需 pnpm（`npm i -g pnpm` 或 `corepack enable`） |
| 火山方舟账号 | 已开通 **联网内容插件**，有一把可用 API key |
| 网络 | 能访问 `ark.cn-beijing.volces.com`（或你自己的 `ARK_SEARCH_BASE_URL`） |

> 为什么钉版本：客户端 `inject` 契约、WebError 码等依赖 DSH 内部 API，
> `@latest` 未来升到新版本后插件需要重新验证。请使用已经验证的
> `0.1.1-rc.2`，并保持整台机器上的 DSH 依赖版本一致。

## 四、安装步骤（在新电脑上）

```bash
# ① 安装 DSH
npx @deepseek-ai/dsh@0.1.1-rc.2

# ② 确认 pnpm 可用（dsh plugin 命令依赖它）
npm install -g pnpm        # 或者: corepack enable

# ③ 解压插件，并把插件目录放进 DSH 主目录内部（关键！）
unzip dsh-web-search-ark-1.0.0.zip
mkdir -p ~/.dsh/profiles/web/packages
cp -R web-search-ark ~/.dsh/profiles/web/packages/

# ④ 注册插件：自动写入 package.json 依赖 + 追加 dsh.profile.bundles
dsh plugin --profile web add ~/.dsh/profiles/web/packages/web-search-ark

# ⑤ 编辑 ~/.dsh/profiles/web/cordis.patch.yml，追加（若已有条目，合并进数组）：
#    - id: web
#      config:
#        searchProvider: ark-official

# ⑥ 配置方舟 key（与聊天模型同一把即可）：
#    方法 A：启动后在 设置 → 模型 页面写入
#    方法 B：~/.dsh/.credentials.yaml 中写入 VOLCENGINE_API_KEY
#    方法 C：启动环境导出 VOLCENGINE_API_KEY

# ⑦ 重启并验证
dsh web
```

### ⚠️ 关键注意事项（踩过的坑）

1. **插件目录必须放在 `~/.dsh` 内部**（官方姿势就是
   `~/.dsh/profiles/<profile>/packages/`）。放在 `/tmp` 或任意目录再用
   `dsh plugin add`，启动会报
   `Cannot find package '@deepseek-ai/schemastery'`——因为 Node 从插件文件的
   真实路径向上找依赖，而 `@deepseek-ai/*` 的共享桥在
   `~/.dsh/profiles/node_modules/`。
2. **`dsh plugin add` 传入绝对路径**：相对路径会相对 profile 目录解析。
3. **补丁只写 `web.searchProvider`**：插件的配置行（模型、key 名、maxKeyword）
   已随 bundle 补丁自动注入，不要再在用户补丁里抄一遍。

## 五、验证安装成功

```bash
# 组合配置里应出现这三样
dsh --profile web --dump-config | grep -E "searchProvider: ark-official|web-search-ark|maxKeyword: 5"
```

浏览器：`设置 → 插件`，应出现「方舟联网搜索」卡片，可点标题折叠/展开。
之后任意让助手联网搜索，工具返回的引用来源即来自方舟搜索。

## 六、配置项说明

| 配置 | 默认 | 说明 |
|---|---|---|
| `apiKeyEnv` | `VOLCENGINE_API_KEY` | 凭证名：从 `~/.dsh/.credentials.yaml`、启动环境变量或设置文件里的 `apiKey` 字面量解析 |
| `baseURL` | `https://ark.cn-beijing.volces.com/api/v3` | Responses API 基点（自动拼接 `/responses`）；也可用环境变量 `ARK_SEARCH_BASE_URL` |
| `model` | `deepseek-v4-flash-ga-260731` | 执行搜索子任务的模型 ID |
| `maxKeyword` | `5` | 单轮最多拆分的关键词搜索数（方舟允许 1–50） |

> **注意区分两个数量**：`maxKeyword` 控制方舟侧拆几个关键词（影响费用），
> 而 DSH 工具层的 `searchMaxResults`（默认 8）才是返回给模型的引用条数上限。

## 七、费用提示

方舟联网内容插件**按实际搜索调用计费**：一次 `web_search` 可能拆成最多
`maxKeyword` 个关键词搜索，逐次计费；工具层无缓存，重复调用会重复计费。
每次请求都会记录到会话的 `web/ark-search-llm-request`，可在方舟用量看板对账。

## 八、常见问题

| 现象 | 原因与处理 |
|---|---|
| 打开历史会话报 `SessionFormatUnsupportedError`，提示 `contains event type "web/ark-search-llm-request"` | 插件没有在读取会话前正确加载，或安装内容不完整。**确认安装的是完整的 1.0.0 发布包并重启 `dsh web`；日志文件本身无需也不应手改。** |
| `Authentication Fails ... invalid` | 正在用官方 provider 连 DeepSeek 官网。确认第 ⑤ 步补丁已写、`dump-config` 显示 `searchProvider: ark-official` |
| `WEB_PROVIDER_CREDENTIAL_MISSING` | 按第 ⑥ 步配好 `VOLCENGINE_API_KEY` |
| `模型没有触发联网搜索 / no web_search_call` | 方舟控制台确认该账号已开通联网内容插件；或换一个模型 ID 重试 |
| 启动页 `Failed to load plugins ... waiting for services` | 客户端模块契约错误；确认解压的是本包最新 4 个文件，别混用旧版本 |
| `Cannot find package '@deepseek-ai/schemastery'` | 插件目录不在 `~/.dsh` 内部（见第四节注意事项 1） |
| `dsh: pnpm not found on PATH` | 先 `npm i -g pnpm` 或 `corepack enable` |

## 九、升级 / 卸载

- **升级**：替换 `~/.dsh/profiles/web/packages/web-search-ark/` 下 4 个文件，
  重启 `dsh web` 即可（依赖是 `link:` 实时生效，无需重装）；若只更新了
  `lib/client.js`，刷新浏览器页面即可。
- **卸载**：
  ```bash
  dsh plugin --profile web remove dsh-web-search-ark
  rm -rf ~/.dsh/profiles/web/packages/web-search-ark
  # 并删除 cordis.patch.yml 中 web.searchProvider 那一条
  ```
  卸载后 `web_search` 回到官方 provider；若只有方舟 key，搜索将不可用直到重新配置。

## 十、开发与发布

```bash
npm ci                        # 安装测试所需的 DSH 开发依赖
npm test                      # 离线契约 + 客户端卡片 + 会话加载检查
SMOKE_LIVE=1 npm run test:live    # 额外做一次真实方舟搜索（需要 key）
npm run release               # 生成 release/ 下的 zip 与 SHA256SUMS
```

打 `v*` 标签会触发 GitHub Actions：跑测试、打包并把产物挂到 Release。

## 十一、校验

```bash
# release/ 里同时放着 zip 和解包后的 web-search-ark/，原地即可全部校验：
cd release && shasum -a 256 -c SHA256SUMS.txt
```