# dsh-touchstone · 试金石

> **为 DeepSeek Harness 的自适应改造提供评测环节。**
> 对 harness 的任何改动（提示词、家规、预设）均可在同一组基准用例上，与"改动前"进行对照运行、评分并生成对比报告：**评分提升则保留，退步则回退。**

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件 · MIT · 兼容桌面版与网页版

[English](README.md) | [简体中文](README.zh-CN.md)

---

## 目录

- [概述](#概述)
- [背景与动机](#背景与动机)
- [快速开始](#快速开始)
- [使用示例](#使用示例)
- [核心概念](#核心概念)
- [检查项](#检查项)
- [运行流程](#运行流程)
- [配置与数据](#配置与数据)
- [适用边界](#适用边界)
- [常见问题](#常见问题)
- [开发](#开发)
- [作者与许可](#作者与许可)

---

## 概述

试金石为 DeepSeek Harness 提供一个**变更评测台**。对 agent 配置的任何一处改动，都可以放到一组**基准用例**上，与改动前的版本并排运行，得到逐条用例的得分对比：

```
用例          改动前    改动后    变化
先说结论        0%      100%    +100%
```

并输出基于证据的结论：**✓ 评分提升，建议保留。** / **✗ 评分退步，建议回退。** / **– 无显著差异。**

评分仅反映当前用例集上的表现，最终决策仍由使用者作出。

## 背景与动机

DeepSeek Harness 以「一切皆插件」为设计核心：提示词、工具、预设乃至 agent 循环均可替换。其官方文档指出，harness 距离真正的自适应演化，尚缺少关键的一环：

> DSH 已将 agent 拆分为可定位、可替换的组件，**但尚缺完整的"学习闭环"——提出修改，并以 Eval 评估该修改是否有效。**

当前生态已提供**撤销/回退**能力（变更失败时可恢复），但缺少**评测**能力（在提交变更前先做量化）。试金石补足的正是这一环节。

实现上刻意保持轻量：**仅使用 `ctx.llm.stream()` 这一公开接口**，不修改 harness 本体，也不依赖任何内部服务，因此同时兼容 DSH 0.1.x（网页版）与 0.2（桌面版）。

## 快速开始

1. **安装**（选择对应的 profile）：
   ```shell
   dsh plugin --profile desktop add dsh-touchstone      # 桌面版
   dsh plugin --profile web add dsh-touchstone          # 网页版
   ```
   安装后重启 DSH。

2. **打开**：进入设置（桌面端：左下角**账号菜单 → 设置**，或 `Ctrl + ,`），在左侧选择 **🪨 试金石**。

3. **新建用例**：在「基准用例」区域点击 **+ 加一条用例**，填写：
   - **名称**：便于识别，例如「先说结论」。
   - **prompt**：发送给 agent 的输入语句。
   - **检查项**：点击「+ 加一条检查项」，选择「必须包含」，并填入期望出现的文本。

4. **新建候选**：在「候选方案」区域点击 **+ 加一个候选**，填写：
   - **名称**：例如「加一条开场格式」。
   - **提示词**：拟测试的系统提示内容。
   - **模式**：`追加到现状`（在当前基础上追加）或 `整篇替换`。

5. **运行**：点击候选旁的 **跑一遍**。

6. **查看报告**：在「对账」区域查看逐条得分与总体结论。

> 注：输入框采用**失焦保存**（blur），输入完成后点击其他区域或按 Tab 即自动保存。

## 使用示例

**场景**：为 agent 增加一条"开场格式"规则，需要确认模型是否会遵守。

| 字段 | 取值 |
|---|---|
| 用例 · 名称 | `开场格式` |
| 用例 · prompt | `用一句话介绍什么是人工智能。` |
| 用例 · 检查项 | `必须包含` → `笔记：` |
| 候选 · 名称 | `加个开场标记` |
| 候选 · 提示词 | `回答的开头必须恰好是「笔记：」四个字，然后继续正文。` |
| 候选 · 模式 | `追加到现状` |

点击「跑一遍」，约数十秒后得到报告：

```
加个开场标记        改动前 0% → 改动后 100%
用例          改动前    改动后    变化
开场格式        0%      100%    +100%
✓ 评分提升，建议保留。
```

该报告为判断提供了数据依据：在改动前配置下该指令未生效，在候选配置下生效。

## 核心概念

| 概念 | 说明 |
|---|---|
| **用例（Case）** | 一条 prompt 及若干检查项，用于约束 agent 的稳定表现 |
| **检查项（Check）** | 对输出的一条断言：必须包含 / 必须不含 / 匹配正则 / 模型裁判 |
| **候选（Variant）** | 一份待测提示词；模式为追加或整篇替换；对照组为内置的「现状（不改）」 |
| **对账（Report）** | 候选平均分与对照组之差，含逐条 delta 与总体结论 |

## 检查项

| 类型 | 判定方式 | 适用场景 |
|---|---|---|
| **必须包含** | 输出中出现指定文本 | 最易实现、最可复现；适用于"必须出现某结论/格式" |
| **必须不含** | 输出中不出现指定文本 | 禁止类约束 |
| **匹配正则** | 输出匹配指定正则 | 格式类校验，例如 `^笔记：` |
| **模型裁判** | 另调用一次模型，仅返回 PASS / FAIL 及一句理由 | 主观标准，例如"结论先给，再给理由" |

> 建议优先使用规则检查而非模型裁判：规则评分可复现性最高；裁判本身也是模型，存在偏差。
> 检查项可设置**权重**（默认 1），评分为加权通过率。

## 运行流程

1. 取所有**已启用**的用例，与所选候选（以及始终参与的对照组「现状」）组合。
2. 对每个组合构造一次模型调用：`system` 为该候选的提示词，`messages` 为该用例的 prompt；通过 `ctx.llm.stream()` 收集全文与用量。
3. 计分：规则检查在本地判定；模型裁判另行调用一次模型。
4. 保存本次运行并返回报告。

全过程**仅读取配置、调用模型**，不会修改任何文件。

## 配置与数据

- **运行模型**：在 DSH 设置中为 `dsh-touchstone` 配置 `provider` / `model` / `temperature` / `maxOutput`；可另行为裁判指定模型（`judgeProvider` / `judgeModel`，留空则与运行模型相同）。
- **数据位置**：`$DSH_HOME/touchstone/bench.json`（`DSH_HOME` 默认为 `~/.dsh`），保存用例、候选及最近 **40 次**运行记录。
- 如需重置，删除该文件即可（系统会重建）。

## 适用边界

- 本插件为**文本层**评测：比较的是"同一 prompt 下模型输出的差异"，**不**运行完整 agent 回路。
  - 适用于「修改提示词 / 家规 / 预设文案」类改动；
  - 不适用于「修改工具实现」这类需要真实副作用的改动。
- **模型裁判本身存在偏差**，规则检查的可复现性更高。评分宜作为参考证据，而非最终判决。
- 评分仅反映**当前用例集**上的表现；用例设计不当会导致评测失真。

## 常见问题

**Q：一次运行耗时与成本如何？**
A：每个「用例 × 方案」组合消耗一次模型调用（使用模型裁判时再加一次）。用例少、输出短时开销较小，建议先用一两条用例验证。

**Q：能否直接对比两个候选？**
A：当前每个候选均与「现状」对照。候选之间比较可查阅两份报告（同一组用例、同一基线）。

**Q：输入框中的中文为何乱码？**
A：早期开发版本存在该问题——输入框曾按每次按键写回服务端，会中断输入法合成。**当前版本已修复**：文本编辑保持在本地，失焦时才落盘。

**Q：是否会修改我的文件？**
A：不会。仅读取配置并调用模型。

## 开发

```shell
npm install
npm run build      # src/index.ts -> lib/index.js ; src/client/index.ts -> lib/client.js
npm run typecheck
npm test           # 纯逻辑单测（针对构建产物运行，无需 DSH）
```

- **宿主侧**（`src/index.ts`）：存储、运行引擎、路由与配置 schema。
- **浏览器侧**（`src/client/index.ts`）：设置页「试金石」。
- 本地迭代：`node build.mjs --watch`，随后刷新页面（客户端改动即时生效）。

## 作者与许可

- **作者：Hwayn（幻弈）**
- **协作者：Yucheng Xiao（肖宇成）** —— 方向、需求与测试
- 许可：MIT