配置实验矩阵 young-tim/dsh-profile-lab

DSH Profile Lab

CI
DSH plugin

DSH Profile Lab 是 DeepSeek Harness 的本地实验与发布门禁工具。它在隔离 workspace 中重复运行多个 DSH profile/patch 组合，基于官方持久化 session 事件计算质量、token、费用、时延和稳定性，并输出可审计报告。

产品包含完整的命令行闭环、三个 DSH 工具，以及 Web profile 会话中的“Profile 组合对比” 页签：profile_lab_run 完成后会自动生成报告，页签读取当前会话最近一次结构化报告； profile_lab_compare 仍可重新读取已有输出目录，展示方案概览、基线差异、用例矩阵与 Pareto 前沿。云托管、账号系统和自动安装插件仍不属于本产品边界。

作为 DSH 插件安装

当前可直接从 GitHub 安装到 headless 或 web profile：

dsh plugin --profile headless add github:young-tim/dsh-profile-lab
或
dsh plugin --profile web add github:young-tim/dsh-profile-lab

安装后重启对应 DSH 进程，模型即可使用 profile_lab_run、 profile_lab_compare 和 profile_lab_gate。Web profile 还会在“对话 / 轨迹”旁增加“Profile 组合对比”页签；当前会话尚无成功的运行或对比报告时，空状态会说明如何准备实验配置、让模型运行评测并生成报告。卸载命令：

插件同时提供 profile-lab-author-cases Skill。用户要求构建、规划或改进评测用例时， AI 会先确认范围与预算、提出用例矩阵建议，获得明确确认后才创建文件，验证通过后再询问是否执行真实评测；未经确认不会产生模型调用费用。

dsh plugin --profile headless remove dsh-profile-lab
dsh plugin --profile web remove dsh-profile-lab

第三方 DSH 插件以当前用户权限运行。安装前应检查源码；Profile Lab 默认临时复用当前 DSH 登录凭证，子进程结束后立即清理。安全边界见 docs/SECURITY.md。

环境要求

- Node.js ^22.19.0 || >=24.0.0
- pnpm 11
- @deepseek-ai/dsh 0.1.0-rc.7
- 一个可运行的 DSH profile；默认 driver 是 PATH 中的 dsh

真实运行可能调用模型并产生费用。每次运行会安全快照当前 DSH_HOME/settings.yaml，因此沿用用户已有的 Provider、base URL、模型列表和默认模型；默认的 run.credentials: inherit 还会临时复用 DSH_HOME/.credentials.yaml，无需在案例中指定模型或 Key。CI 可使用 credentials: env-only 并通过 run.env_allowlist 显式授权所需环境变量。

在 DSH 对话中使用

安装并重启 DSH 后，不需要记忆工具参数，可以直接用自然语言描述目标。AI 会按需加载 profile-lab-author-cases Skill，并调用 profile_lab_run、profile_lab_compare 或 profile_lab_gate。

示例：让 AI 协助构建用例

先让 AI 调研并确认范围，不要立即写文件：

帮我为支付重试功能设计一套 Profile Lab 用例。先检查现有 experiment 和 cases，和我确认测试范围、关键风险、断言和预算，然后给出用例矩阵建议；暂时不要创建或运行。

如果 Skill 没有自动触发，可以明确指定：

请加载 profile-lab-author-cases Skill，帮我规划这套评测用例。

AI 应先询问类似问题：

- 这次要比较什么方案，最终要支持哪个发布决策？
- 哪些正常路径、边界条件和禁止行为必须覆盖？
- 应观察最终输出、工具调用还是资源上限？
- 最多允许多少次模型调用、多少 Token 或多长时间？

回答后，AI 会先给出建议矩阵。你可以继续调整：

保留正常成功、超时重试和禁止重复扣款三个用例；删除纯格式检查。smoke 用例最多两次模型调用，完整评测每个方案重复五次。先把最终文件清单和断言给我确认。

只有明确确认后 AI 才会创建文件：

我确认这个用例矩阵。请创建 case YAML 和必要的 fixture，更新 experiment，并只做 Schema 校验，不要运行模型。

创建和校验完成后，AI 会再次询问是否运行。也可以拒绝或暂缓：

先不运行。把预计调用次数、重试上限和输出目录建议告诉我。

示例：用自然语言运行用例

运行完整实验：

运行 experiments/payment/experiment.yml 中的全部用例，结果保存到新的 .profile-lab/payment-2026-08-20。运行前先告诉我方案数、用例数、重复次数和预计模型调用总数，得到我确认后再开始。

只跑 smoke 用例：

使用 experiments/payment/experiment.yml 只运行带 smoke 标签的用例，输出到新的 .profile-lab/payment-smoke-001。不要复用旧结果目录。

只跑指定用例：

运行 payment-success 和 duplicate-charge-guard 两个用例，其他用例跳过。开始前先向我确认实际调用次数和费用风险。

profile_lab_run 完成后会自动生成报告，“Profile 组合对比”页签会展示方案组成、Patch 详情、通过率、Token、时延、用例矩阵和 Pareto 前沿。

示例：读取历史结果和执行门禁

读取已有结果目录并刷新 UI：

读取 .profile-lab/payment-2026-08-20 的实验结果并生成最新对比报告。它是 output 目录，不要把它作为 experiment 文件传入。

检查是否允许发布：

对 .profile-lab/payment-2026-08-20 执行发布门禁：候选通过率至少 95%，相对基线下降不超过 2 个百分点，错误率不超过 1%，中位 Token 增长不超过 15%。解释每个未通过原因。

示例：只要建议，不创建文件

评审现有 cases/ 的覆盖情况，指出遗漏、脆弱断言和可能的数据泄漏，只给建议，不修改文件，也不要运行评测。

10 分钟快速开始

pnpm install --frozen-lockfile
pnpm build

校验完整 experiment、case 和嵌套字段
node dist/cli.js schema --check examples/experiment.yml

使用已登录的真实 DSH；结果目录必须为空或由 Profile Lab 创建
node dist/cli.js run examples/experiment.yml \
--output .profile-lab/real-run

node dist/cli.js compare .profile-lab/real-run
node dist/cli.js gate .profile-lab/real-run \
--policy examples/policy-pass.yml

不调用模型的发布验收使用仓库内 deterministic driver：

node dist/cli.js run examples/experiment.yml \
--driver fixtures/fake-dsh \
--output .profile-lab/acceptance --restart
node dist/cli.js compare .profile-lab/acceptance
node dist/cli.js gate .profile-lab/acceptance \
--policy examples/policy.yml

从 npm/tarball 安装后可直接使用 pnpm exec dsh-profile-lab 或安装器生成的同名 bin；仓库内开发命令使用刚构建的 node dist/cli.js，避免命中过期副本。

examples/ 是可真实执行的两 variant、两 case、五次重复实验。base 使用空 overlay， candidate 修改 system prompt；两个 case 都要求读取隔离 workspace 中的明确 marker。

Experiment

schema_version: 1
name: profile-comparison
cases_dir: cases
workspace_template: repo
baseline: base
variants:
- { id: base, profile: headless, patch: variants/base.yml }
- { id: candidate, profile: headless, patch: variants/candidate.yml }
repetitions: 5
run:
concurrency: 2
timeout_ms: 600000
max_runs: 100
max_total_tokens: 100000
credentials: inherit # 默认值，可省略 pricing:
base: { input_per_million: 0.14, output_per_million: 0.28 }
candidate: { input_per_million: 0.14, output_per_million: 0.28 }

所有路径以 experiment 文件所在目录为基准。variant patch 必须是官方 DSH 接受的 top-level YAML patch array。配置、case、workspace、patch 和可选 judge 的内容哈希都会进入 manifest；任一输入变化后继续 resume 会失败，必须显式 --restart。

可用筛选参数：--tag tag-a,tag-b 和 --case case-a,case-b。筛选结果为空属于配置错误。--restart 只清理带有 Profile Lab 所有权标记的结果目录。

Cases 和断言

name: read-marker
prompt: Read README and return the alpha marker.
tags: [smoke]
retries: 1
assert:
turn_end: completed
tools_not_called: [dangerous_tool]
output_contains: PROFILE_LAB_ALPHA
max_steps: 8
max_tokens: 5000
no_tool_errors: true

支持 turn_end、有序 tools_called、tools_exact、tools_not_called、 output_contains、output_not_contains、output_matches、 tool_args_contains、tool_result_contains、max_steps、max_tokens、 no_tool_errors 和可选 output_judge。非法断言会在启动 cell 前失败。

可选的 output judge

Judge 是用户明确配置的本地可执行 adapter，不会自动调用任何模型：

judge:
command: ./judge-adapter
timeout_ms: 60000
env_allowlist: [JUDGE_API_KEY]

adapter 从 stdin 接收 {"prompt", "output", "rubric"}，最后一行 stdout 返回：

{
"pass": true,
"reason": "meets rubric",json
"usage": { "inputTokens": 10, "outputTokens": 2 }
}

结构断言先执行；结构失败时 judge 不会运行。Judge 证据和 token 单独记录，并计入实验总 token 预算。

结果与恢复

结果目录包含：

- manifest.json：规范化 experiment、workspace/case/patch/judge 哈希
- journal.json：原子写入的 cell 与 attempt 结果，可用于 resume
- .runs//attempt-N/：隔离 workspace、已清除凭证的 DSH_HOME、patch 副本和原始证据
- run-state.json：完整、预算停止或取消状态
- report.json、report.md、report.html：机器、评审和离线浏览格式

再次执行相同 run 会跳过已经 pass/fail 的 cell。输入哈希变化时默认拒绝恢复。
SIGINT 会停止派发、终止活动子进程树、刷新 journal 并返回退出码 3。

Gate 与退出码

Policy 支持 min_candidate_pass_rate、max_pass_rate_drop_pp、 max_median_token_increase_pct 和 max_error_rate。所有非 baseline variant 都会被评估，而不是只检查第一个 candidate。

| Code | Meaning |
| 0 | run/compare 完整，或 gate 通过 |
| 1 | gate 检测到策略回归 |
| 2 | CLI、Schema、输入、baseline 或 policy 配置错误 |
| 3 | 基础设施错误、预算停止、取消或不完整结果 |

安全模型

- 每个 attempt 使用独立 workspace、DSH_HOME 和 patch 副本。
- 从宿主 DSH_HOME 快照 settings.yaml，让隔离子进程沿用 Provider、base URL 和默认模型；配置哈希进入 manifest，快照在 attempt 的 finally 清理。
- 默认从宿主 DSH_HOME 临时复制凭证，权限设为 0600，并与设置快照一同清理；凭证不会进入 manifest、journal 或报告。credentials: env-only 可彻底禁用凭证文件继承。
- 源 workspace、patch 和 judge 在运行后重新哈希；发生变化会失败关闭。
- 拒绝 workspace 中的 symlink、socket、device、FIFO 等特殊文件。
- 子进程使用 argv 数组和 shell: false；超时终止整个进程组并升级到 SIGKILL。
- 环境变量默认不继承，仅保留 PATH、HOME、隔离 DSH_HOME 和显式 allowlist 名称。
- journal 与报告在落盘前脱敏；HTML 无脚本、远程资源、遥测或网络请求。

开发与发布验证 bash
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm test:coverage
pnpm build
pnpm test:integration
pnpm test:package

详细产品合同见 docs/DEVELOPMENT_SPEC.md。