# dsh-llm-verifier 研发与发布全流程 SOP

> 从「魔改 llm-as-a-verifier」到「上架 dsh-market」的完整标准作业流程。
> 本次实际执行记录见文末 [执行记录](#执行记录)。

## 0. 目标与产物

| 产物 | 位置 |
|---|---|
| 插件源码（开源） | https://github.com/TaurenMountain/dsh-llm-as-a-verifier |
| npm 包 | `dsh-llm-as-a-verifier`（registry.npmjs.org） |
| 上架入口 | [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) PR（合并后 dsh-market 自动收录） |
| 文档 | README.md / README.en.md / docs/USER-GUIDE.md / 本文档 |

## 1. 上游调研（llm-as-a-verifier）

1. 阅读上游 README、源码 `llm_verifier/{fine_grained_reward,pivot_tournament,progress,prompts}.py`，提炼核心逻辑：
   - **细粒度打分**：20 级字母尺度（A=20…T=1），对评分标签 `<score_A>/<score_B>` 后一位的 top-logprobs 分布取期望 `E=Σv·p(v)/Σp(v)`，归一化到 [0,1]；无分布时按文本正则回退，再不行取 0.5。
   - **成对提示词**：任务+双轨迹+量表在前（共享前缀以吃缓存），单一标准在尾部。
   - **Probabilistic Pivot Tournament**：环赛（随机哈密顿环，槽位偏置环上抵消）→ top-k 枢纽 → 枢纽轮；比较数 `N + k(N−k) + C(k,2)`；Bradley-Terry 软胜负 `sigmoid(Ra−Rb)` 聚合为 `w/c` 平均偏好。
   - **槽位交换**：奇数次重复交换 A/B 槽位，分数按候选顺序记回。
   - **进度追踪**：A=0%…T=100% 反向尺度，`<c1>..<cN>` 标签逐 checkpoint 评分，logprob 期望 + softmax 重归一化解码。
   - **凭证解析**：`OPENAI_BASE_URL`+`OPENAI_API_KEY` → `DEEPSEEK_API_KEY`（→ api.deepseek.com，thinking 开启）；OpenAI 兼容路径先试 `chat_template_kwargs.enable_thinking=false`，失败重试；非 DeepSeek 服务对缺失标签做 prefill（`continue_final_message`）。
2. 确认上游 **MIT 许可** → 可移植，保留版权归属（写入 LICENSE）。

## 2. DSH 插件形态调研

1. 读 DSH harness（本机 `@deepseek-ai/dsh` 安装目录与 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)）：
   - 插件 = npm 包，`package.json` 声明 `dsh.bundle.patch` 指向 `cordis.patch.yml`；
   - patch 内容：`- insert: [{ id: <cordis插件名>, name: <包名> }]`；
   - 工具插件导出 `name`/`inject`/`Config`(schemastery)/`apply(ctx, config)`，用 `ctx.tools.register(defineTool({...}))` 注册，`ctx.systemPrompt.section(...)` 注入使用引导；
   - `defineTool` 的 parameters DSL 会被编译成 JSON Schema，output 必须声明 canonical schema + `render`。
2. 读 dsh-market 与 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 的收录规范：
   - **dsh-market 本身不是插件目录**：收录 = 向 awesome-dsh-plugin 提 PR（`data/plugins/<owner>__<repo>.yml` + 重新生成 README），市场每天自动同步；
   - 上架硬性门槛：仓库 `dsh.bundle` 声明、真实代码、**仓库创建 ≥1 天、提交 ≥10 个**、加 `dsh-plugin` topic、描述与代码相符。

## 3. 魔改设计决策

| 决策 | 理由 |
|---|---|
| TypeScript 原生重写（不桥接 Python） | DSH 插件生态是 npm/Cordis；无 Python 依赖，TDD 全离线可测 |
| 三工具 + 库 API 双形态 | `verify_compare/verify_select/verify_track` 给模型；`Verifier` 类给库用户 |
| 凭证解析顺序照搬上游 | 行为可预期，文档可对照上游 |
| prefill / DeepSeek thinking 路径照搬 | 保真上游 0.2.0 行为 |
| 图输入、ProgressTracker 在线追踪、磁盘缓存 → v0.1 暂缓 | 控制首版范围，README 注明 roadmap |

## 4. 本地 TDD 开发（红-绿循环）

每模块严格「先写失败测试 → 跑红 → 实现 → 跑绿」：

1. 脚手架：package.json（含 `dsh.bundle`、peerDeps `@deepseek-ai/{cordis,dsh-tools,dsh-system-prompt,schemastery}`）、tsconfig（NodeNext + `.js` 后缀导入）、vitest、cordis.patch.yml、LICENSE（含上游归属）。
2. `tests/helpers/mock-openai.ts`：进程内 OpenAI 兼容 mock 服务器（记录请求、FIFO 响应 / script 模式），保证全离线。
3. 模块顺序与测试数：scoring(17) → tournament(13) → progress(13) → backend(13) → verifier(9) → index(11)，共 76 例。
4. 关键断言：期望打分数值、`>A` 融合 token、末位标签优先、环赛结构/确定性、枢纽对生成、槽位交换（odd rep）、prefill 请求形状、并发上限、端到端 PPT 胜者、进度曲线平均。
5. 提交纪律：每模块 `test(red)` 与 `feat(green)` 分开提交（这也是满足「≥10 commits」门槛的天然方式）。

```sh
npx vitest run          # 红：模块不存在
npm run check           # 绿：typecheck + 76 用例通过
```

## 5. 本地真实环境验证

```sh
dsh plugin --profile verifier-smoke add /path/to/dsh-llm-verifier
dsh --profile verifier-smoke --dump-config | grep -A2 dsh-llm-verifier
# 期望：bundle 出现在 layer stack，id=llm-verifier
```

验证点：安装命令可用、`dsh.bundle` 自动 reconcile 进 `bundles`、配置树组装无报错。测试完可 `dsh plugin --profile verifier-smoke remove dsh-llm-verifier` 清理。

## 6. GitHub 开源（openqht / TaurenMountain）

```sh
gh repo create TaurenMountain/dsh-llm-as-a-verifier --public \
  --description "..." --source . --remote origin --push
gh repo edit TaurenMountain/dsh-llm-as-a-verifier --add-topic dsh-plugin
```

仓库本地配置：`user.name=openqht`、`user.email=<id>+openqht@users.noreply.github.com`（用 `gh api user --jq .id` 查 id），保证提交归属于 openqht 账号。

## 7. npm 发布

```sh
npm login            # 交互式登录（2FA 时用 Access Token）
npm publish          # 自动跑 prepack → build
npm view dsh-llm-as-a-verifier   # 验证发布
```

注意：npm 官网登录 ≠ CLI 登录；发布需要本机 `npm whoami` 能返回用户名。启用 2FA 的账号建议用 Publish 类型的 Access Token（`//registry.npmjs.org/:_authToken=`）。

## 8. 上架 awesome-dsh-plugin（→ dsh-market）

```sh
gh repo fork awesome-dsh-plugin/awesome-dsh-plugin --clone
cd awesome-dsh-plugin
# 1) 新增 data/plugins/TaurenMountain__dsh-llm-as-a-verifier.yml：
#    url: https://github.com/TaurenMountain/dsh-llm-as-a-verifier
#    name: TaurenMountain/dsh-llm-as-a-verifier
#    category: tools
#    description: {en: ..., zh: ...}
# 2) 重新生成 README（勿手改）
npm ci && node scripts/generate-readme.mjs
git add -A && git commit -m "Add TaurenMountain/dsh-llm-as-a-verifier"
gh pr create --title "Add TaurenMountain/dsh-llm-as-a-verifier"
```

- CI 会检查：manifest 形状、README 可再生、**仓库 ≥1 天且 ≥10 commits**。新仓库当天提 PR 会被 CI 拦下——预期行为，**等满 24 小时后 push 一个空提交或 close/reopen 触发重跑**即可（不视为被打回）。
- 合并后：awesome-dsh-plugin.com/plugins.json 自动包含条目 → **dsh-market 一天内自动收录**，用户即可在市场里一键安装。
- 复查入口：`curl -s https://awesome-dsh-plugin.com/plugins.json | grep dsh-llm-verifier`。

## 9. 验收清单

- [ ] `npm run check` 全绿（typecheck + 76 用例）
- [ ] `dsh plugin add` + `--dump-config` 冒烟通过
- [ ] GitHub 仓库 public、topic 含 `dsh-plugin`、≥10 commits、LICENSE 含上游归属
- [ ] npm 包可安装：`npm view dsh-llm-as-a-verifier dsh`
- [ ] awesome-dsh-plugin PR 合并
- [ ] dsh-market 能搜到并一键安装

## 执行记录（本次实际过程）

| 步骤 | 结果 |
|---|---|
| 调研上游与 DSH 规范 | 提取全部算法细节；确认 MIT；确认收录走 awesome-dsh-plugin |
| TDD 红绿 | 8 个模块提交、76 用例全绿（红→绿循环见 git log，共 12 commits） |
| 本地冒烟 | `dsh plugin add` 成功，bundle 自动进 layer stack，`--dump-config` 正常 |
| GitHub | 仓库 `TaurenMountain/dsh-llm-as-a-verifier`（openqht 身份提交），topic 含 `dsh-plugin`，GitHub Actions CI 全绿 |
| npm | 已发布 `dsh-llm-as-a-verifier@0.1.1`（裸名 `dsh-llm-verifier` 当日被他人占用，故仓库与 npm 统一改为 `dsh-llm-as-a-verifier`） |
| awesome PR | [#2169](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/2169)；CI 的「仓库满 1 天」门槛到期后重跑即绿 |
| dsh-market | 收录为自动同步，预计 PR 合并后 1 天内可见 |

### 本次踩坑记录（可直接复用的经验）

1. **npm 名字冲突**：先 `npm view <名字>` 确认可用再开发/发布；本次 `dsh-llm-verifier` 被他人当天注册，最终统一改用 `dsh-llm-as-a-verifier`（仓库 + npm 包同名）。
2. **npm 2FA**：账号开启「授权+发布」级 2FA 时，发布必须用「bypass 2FA」的 token（granular token 勾选 Two-factor authentication = Bypass，或 Classic Automation token），`--otp` 不生效。
3. **gh token scope**：推送 `.github/workflows/*` 需要 `workflow` scope，用 `gh auth refresh -h github.com -s workflow` 补权。
4. **上架年龄门槛**：awesome-dsh-plugin 的 CI 要求仓库 ≥1 天 + ≥10 commits；新仓库当天提 PR 会被 CI 拦下，等 24 小时后 push 空提交触发重跑即可。
5. **npm login 管道无效**：npm CLI 从 /dev/tty 读密码，脚本无法注入；2FA 场景直接用 bypass token 最省事。