dsh-0-tools

Readme

# dsh-0-tools 零号工具（No.0 Tools）

[简体中文](./README.md) · [English](./README.en.md)

## 零号工具是什么

零号工具是面向编程零基础的用户、初次使用 DeepSeek Harness（以下简称 DSH）场景而设计的工具，具有「零门槛、零费用、零失控、零困惑」的特性，希望帮助零基础用户获得更好的使用体验。

## 主要功能

1. **【零门槛】** 一键安装 DSH 及本工具，桌面自动生成快捷方式；
2. **【零费用】** 一键接入多款国内可访问的永久免费大模型（智谱 / 硅基流动 / 讯飞星火 / OpenRouter / ……），配置后自动测速、超时智能提示；
3. **【零失控】** 若选择调用 DeepSeek 官方模型 API，将在 DSH 界面实时提示当前是高峰时段（原价）还是空闲时段（半价）；
4. **【零困惑】** 小白帮助中心汇总 DSH 官方资料与社区精选资源，新手快速上手。

## 当前版本与兼容范围

- 当前版本：**v1.8.5**
- 兼容 DSH 版本：**≥ `0.1.1`**
- **系统要求**：一键安装脚本支持 **Windows 10 / Windows 11**（`install.bat`）和 **macOS / Linux**（`install.sh`）；插件核心代码本身跨平台，已手动装好 DSH 的用户可通过 `dsh plugin --profile web add /path/to/dsh-0-tools` 手动安装。

## 免费模型清单

零号工具目前接入 4 款永久免费大模型，建议全部配齐——当某个模型繁忙或报错时，可有更多更快更稳定免费模型备选，实现"模型越多，可切换的选择越多"：

| 模型 | 提供方 | 特点 |
|------|--------|------|
| GLM-4.7-Flash + GLM-4V-Flash | 智谱 | 文本 + 图片理解，永久免费 |
| Qwen3-8B（15+款9B以下小模型） | 硅基流动 | 永久免费，国内直连，128K上下文，支持工具调用 |
| Spark Lite | 讯飞星火 | 永久免费，中文理解强 |
| OpenRouter 免费池 | OpenRouter | 自动路由数十款免费模型，某款下架自动绕开 |

> 每款模型均提供专属图文教程页，在"① 零费用·免费模型管家中心"点击「引导教程」即可查看手把手注册步骤。

## 安装与使用（图文步骤）

### 第 1 步：运行一键安装脚本

- **Windows 用户**：双击运行 `install.bat`
- **macOS / Linux 用户**：在终端中运行 `chmod +x install.sh && ./install.sh`

#### Windows 版（install.bat）

- 电脑**已经装好 DSH**：脚本会自动检测并跳过安装，直接完成本工具的安装；
- 电脑**还没装 DSH**：脚本会自动扫描运行环境，补齐缺失的环境后自动安装 DSH；
- 安装成功后，脚本会自动在**桌面生成一个「DeepSeek Harness」快捷方式**。

> 小提示：`install.bat` 是纯文本脚本，可右键 →「打开方式 → 记事本」查看全部内容后再运行（内容透明可审）。从网上下载的脚本没有数字签名，Windows 可能弹出 SmartScreen 提示（"Windows 已保护你的电脑"），点「更多信息 → 仍要运行」即可——这是 Windows 对无签名脚本的统一提示，不是病毒警告。

### 第 2 步：打开 DSH 界面

双击桌面的「DeepSeek Harness」快捷方式，浏览器会自动打开 DSH 的网页界面。当你还没配置任何免费模型时，会自动弹窗引导配置；也可以在 DSH 界面左下角点击「配置免费模型」按钮，进入同款配置界面。

![DSH 主界面 - 弹窗引导配置免费模型](screenshots/1.png)

### 第 3 步：获取并安装 API Key

建议配齐以下所有免费模型，免费模型数越多，切换选择更多！点击以下模型卡片上的「引导教程」按钮，跟着一步步注册复制 API Key（讯飞需复制 APIKey 和 APISecret 两个值，用英文冒号拼接），并粘贴在「在此处粘贴任意模型 API Key 都将自动识别」框内，点击「自动识别 API Key 一键安装免费大模型」将自动安装免费模型。

![免费模型配置中心 - 四个模型卡片 + 大粘贴框](screenshots/2.png)

> 已配置的模型会显示 ✅ 标记，并提供「一键卸载模型」（二次确认）；未配置的模型显示「引导教程 →」链接。

### 第 4 步：智能测速 + 超时提示，零费用更透明

配置好 2 个及以上免费模型后，零号工具的「免费模型管家中心」会自动开始测速监测：

- **自动测速**：后台每 60 秒对所有已配置免费模型发一次 `max_tokens=1` 的极小请求测速，记录最近 5 次响应时间取平均；
- **超时提示**：当前模型测速超时时，侧边栏底部实时显示「智谱🔴超时，建议换讯飞」（自动找到最快可用的模型），帮助用户及时了解模型健康状况；
- **状态提示**：侧边栏底部实时显示当前模型状态（智谱🟢正常 / 智谱🟡较慢 / 智谱🔴超时，建议换XX），状态条仅作提示，不可点击；
- **状态判定**：<8 秒 = 正常（🟢），8-15 秒 = 较慢（🟡），>15 秒或超时 = 超时（🔴）。

![免费模型管家中心 - 状态指示器](screenshots/3.png)


### 第 5 步：使用付费 DeepSeek 模型

如果你决定付费使用，并已申请、购买 DeepSeek 模型的 API，可在 DSH 界面左下角点「设置」，找到「模型」，在 DeepSeek 处点「编辑」，填入 DeepSeek 模型的 API 密钥。

![DeepSeek 模型 API 密钥配置](screenshots/5.png)

### 第 6 步：DeepSeek 计费提醒

当你在 DSH 界面切换选择了 DeepSeek 官方模型，界面左下角会实时显示计价提醒，根据 DeepSeek 官方 API 调用的高峰/空闲时段，提示「当前高峰时段API为原价」或「当前空闲时段API为半价」，为你提供「零失控」的费用保驾护航。

![DeepSeek 计费提醒 - 高峰时段原价](screenshots/4.png)

> DeepSeek 官方计费规则（2026-08-23 起生效）：周末（周六/周日）全天统一低谷价，不再区分峰谷；仅工作日（周一至周五）执行峰谷分段计费——高峰时段（9:00-12:00、14:00-18:00）原价，其余空闲时段半价。

## 国内镜像下载地址

本仓库为中国大陆用户提供了 Gitee 镜像，现已开放：

- **GitHub 主仓库**：`https://github.com/ai-yukin/dsh-0-tools`
- **Gitee 镜像**：`https://gitee.com/ai-yukin/dsh-0-tools`

说明：

- 本仓库以 **GitHub 为主源仓库**，Gitee 为国内镜像，已配置自动同步（Gitee 仓库「管理」→「仓库同步管理」开启 GitHub 同步），内容与主仓库保持一致；
- 国内用户推荐从 Gitee 下载，访问速度更稳定；
- 如需反馈问题或建议，请在 GitHub 主仓库的 Issues 中提交。

## 兼容性

本插件针对以下 DSH 版本开发与验证：

| DSH 版本 | 状态 |
|------|------|
| `0.1.1-rc.2` | 已实测适配通过（页面加载 / 计价条 / 模型选择器 / 设置页签 / 官方配置通道） |


## 目录结构

```
dsh-0-tools/
├── lib/
│   ├── index.js     # host 端：本地测速代理服务器（127.0.0.1:3095），绕过浏览器CORS
│   └── client.js    # 浏览器端：左下角工具条 + 设置页签「零号工具」+ 经官方 /api 读写配置
├── guide/           # v1.8.0 新增：4 款免费模型专属图文教程页
│   ├── zai.html              # 智谱教程
│   ├── openrouter-free.html  # OpenRouter 教程
│   ├── siliconflow.html       # 硅基流动教程
│   ├── xinghuo.html          # 讯飞星火教程
│   └── images/               # 教程截图
├── screenshots/     # README 用截图
├── cordis.patch.yml # web profile 注入声明
├── package.json
├── help.json        # 帮助中心在线数据源（托管于 GitHub Pages，支持远程热更新模型清单）
├── install.bat      # Windows 一键安装 + 启动 + 验证
└── install.sh       # macOS / Linux 一键安装 + 启动 + 验证
```

## 机制说明


- **配置状态判定**：浏览器端调用官方 `settings.describe` + `credentials.describe`，判断 `llm-pi-ai.providers.{provider}` 是否存在及其凭据是否已配置，作为权威来源；每 5 秒轮询一次刷新界面。
- **一键配置**：依次经官方 `credentials.set` 写入凭据、`settings.mutate` 写入 provider 配置段、`settings.update` 以合并语义把默认模型切换到对应免费模型（合并语义确保 `reasoningEffort` 等用户已设字段不被抹掉）。
- **一键卸载**：经官方通道清除 provider 配置段与对应凭据；仅当默认模型此前指向该 provider 时，恢复为配置前记录的原始默认模型，否则保持用户当前选择不变。
- **API Key 自动识别**：根据 Key 前缀/格式自动识别属于哪个模型（`sk-or-v1-` → OpenRouter，`sk-`（非sk-or-v1-）→ 硅基流动，`APIKey:APISecret` 格式或 32 位 hex → 讯飞星火，带点号的长字符串 → 智谱），识别后自动调用一键配置流程。
- **免费模型管家中心**：后台每 60 秒对所有已配置免费模型发 `max_tokens=1` 极小请求测速，记录最近 5 次响应时间取平均；当前模型超时时智能提示建议切换到最快可用模型；侧边栏实时显示状态（仅作提示，不可点击）。
- **失效残留清理**：配置中心检测本地是否残留已下线/失效的模型 provider（动态读取其 `apiKeyEnv`，不再依赖本地静态清单），在界面给出「失效残留」提示并提供一键清理，避免孤儿配置无法删除。
- **设置页签**：通过 `settings.section` 插槽注入（官方插件同款机制），id 为 `dsh-0-tools`，页签名「零号工具」。
- **帮助中心**：拉取 `https://ai-yukin.github.io/dsh-0-tools/help.json`，经统一过滤器 `filterRemotePayload` 逐字段安检（URL 强制 https、文本拒绝控制字符/换行、模型 id 与凭据名走字符白名单）后再进入界面与配置链，失败或不合规时回退内置数据；可配置模型清单与已下线模型清单均由此远程数据驱动，新增或下线模型无需重装插件。
- **教程页托管**：教程页统一托管于 GitHub Pages（`https://ai-yukin.github.io/dsh-0-tools/guide/`），国内用户可通过 Gitee 镜像仓库下载源码后本地查看教程。

## 免责声明

- 本插件为**第三方社区插件**，与 DeepSeek、智谱、硅基流动、讯飞、OpenRouter 官方均无任何关联，官方不对其提供支持。
- 使用本插件接入第三方模型服务，请自行遵守对应平台的服务条款与费用政策。
- 免费模型通道的对话内容可能被模型厂商留存用于训练，请勿在此通道输入商业机密、个人隐私等敏感内容。
- 本项目按 MIT 许可证开源，使用者需自行承担使用风险。

## 许可证

[MIT](LICENSE) © 2026 ai-yukin