chore: track claude skills, tools, templates, reference code and research-wiki
- Add all claude skills (brainstorming, commit, debugging, TDD, etc.) - Add claude hooks (pre-commit-guard, post-edit-quality) - Add research templates (experiment plan, research brief, etc.) - Add claude tools (arxiv/semantic_scholar/openalex fetch, wiki, exa) - Add TRM4 reference implementation as algorithm fidelity baseline - Add research-wiki content (plans, index, graph, query_pack) - Update .gitignore to exclude .graphify_version runtime state
This commit is contained in:
@@ -0,0 +1,130 @@
|
||||
---
|
||||
name: harness-eval
|
||||
description: "评估功能的真实运行性能。从 Wiki 读取 schema 和 metric 定义，查询 SQLite 日志，对比基线，调用 LLM judge 做语义评估，产出诊断和迭代建议。触发短语: harness eval, 评估性能, 性能评估。"
|
||||
argument-hint: "[run_id]"
|
||||
---
|
||||
|
||||
# Harness Eval
|
||||
|
||||
## Overview
|
||||
|
||||
在真实环境中运行程序后，评估性能是否达标，诊断问题，决定是否迭代。
|
||||
|
||||
**核心原则：** 不是"通过就停"，而是基于真实指标判断"跑得好不好"。
|
||||
|
||||
## 触发方式
|
||||
|
||||
1. **自动**：subagent-driven-development Step 10，所有任务完成 + final review 通过后
|
||||
2. **手动**：`/harness-eval` 或 `/harness-eval <run_id>`
|
||||
|
||||
## 前置条件
|
||||
|
||||
- `research-wiki/schemas/` 中有至少一个 schema 实体
|
||||
- `research-wiki/metrics/` 中有至少一个 metric 实体
|
||||
- `results/harness.db` 存在且包含数据
|
||||
- `.env` 中有 LLM API key（用于 LlmJudge）
|
||||
|
||||
## 长时命令执行约定
|
||||
|
||||
对真实样本重跑流水线属于长时操作。超过 30s 的命令建议在 tmux 中后台运行，便于人工随时 attach 检查进度；短命令直接前台执行即可。
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Phase 1: 准备
|
||||
|
||||
1. 列出 `research-wiki/schemas/` 下所有 schema 实体，获取表名和列信息
|
||||
2. 列出 `research-wiki/metrics/` 下所有 metric 实体，获取基线值和阈值
|
||||
3. 确认 `results/harness.db` 存在，查询 `_runs` 表获取最新运行状态
|
||||
4. 如果指定了 run_id，使用该 run_id；否则使用最近一次 status='completed' 的 run
|
||||
|
||||
### Phase 2: 运行
|
||||
|
||||
#### 2a: 检查已有运行记录
|
||||
|
||||
在 subagent-driven-development 流程中，某个子任务可能已经执行过全局运行并将结果写入了 `harness.db`。此时 harness-eval **不应重复运行**，直接复用已有记录即可。
|
||||
|
||||
1. 查询 `_runs` 表，查找 `status='completed'` 且 `git_sha` 与当前 `HEAD` 匹配的记录
|
||||
2. **找到匹配记录** → 使用该记录的 run_id，**跳过运行**，直接进入 Phase 3。在最终报告中注明「复用已有运行: run_id=xxx」
|
||||
3. **未找到匹配记录 + 自动触发** → 继续 2b
|
||||
4. **未找到匹配记录 + 手动触发** → 询问用户是否需要执行运行
|
||||
|
||||
#### 2b: 重跑流水线（仅无可用记录时）
|
||||
|
||||
1. `make deploy-testing` 起服务（api / worker / Postgres / Redis / 对象存储）
|
||||
2. 对真实样本重跑流水线，结果落 `results/harness.db`；属长时操作，建议按「长时命令执行约定」在 tmux 中运行
|
||||
3. 轮询检查 `_runs` 表状态，等待完成
|
||||
4. 确认 `_runs` 表中对应 run 的 status = 'completed'
|
||||
5. 如果 status = 'failed'，直接进入 Phase 6 诊断
|
||||
|
||||
### Phase 3: 硬性指标检查
|
||||
|
||||
对 `research-wiki/metrics/` 中每个标记为硬性判定的指标：
|
||||
|
||||
1. 从 metric 实体中读取：指标名、基线值、阈值、对应的 schema（表名和列名）
|
||||
2. 执行 SQL 查询获取当前运行的实际值
|
||||
3. 对比：实际值 vs 阈值
|
||||
4. 记录结果：pass / fail + 具体数值
|
||||
|
||||
### Phase 4: 语义评估
|
||||
|
||||
对 `research-wiki/metrics/` 中每个标记为语义判定的指标：
|
||||
|
||||
1. 收集 evidence：相关表的数据、_events 表的事件、配置信息
|
||||
2. 调用 `LlmJudge.evaluate(EvalRequest)`（请求体封装 criteria、evidence、rubric）
|
||||
3. 记录结果：Verdict
|
||||
|
||||
### Phase 5: 综合判定
|
||||
|
||||
- 硬性指标全部 pass **且** 语义评估全部 pass → **通过**
|
||||
- 任一不通过 → **不通过**，进入 Phase 6
|
||||
|
||||
### Phase 6: 诊断与迭代决策（仅不通过时）
|
||||
|
||||
1. 收集失败信息：哪些指标不达标、实际值与期望值的差距
|
||||
2. 查询 `_events` 表获取运行过程中的关键事件
|
||||
3. 调用 `LlmJudge.diagnose(error_context, log)`
|
||||
4. 向用户报告：
|
||||
- 问题根因分析
|
||||
- 修复建议
|
||||
- 是否建议再迭代一轮
|
||||
|
||||
### Phase 7: 记录到 Wiki
|
||||
|
||||
1. 创建 finding 实体：
|
||||
```bash
|
||||
conda run -n chs python3 .claude/tools/research_wiki.py add_entity research-wiki/ --type finding --id eval-<run_id> --title "Harness 评估: <run_id>"
|
||||
```
|
||||
2. 在 finding 中记录完整评估报告（硬性指标表 + 语义评估结果 + 诊断结论）
|
||||
3. 建立 edge：
|
||||
```bash
|
||||
conda run -n chs python3 .claude/tools/research_wiki.py add_edge research-wiki/ --from "finding:eval-<run_id>" --to "metric:<id>" --type evaluates --evidence "..."
|
||||
```
|
||||
4. 如果通过且用户确认，更新 metric 实体中的基线值为当前值
|
||||
5. 重建索引
|
||||
|
||||
## 输出格式
|
||||
|
||||
评估完成后，向用户输出结构化报告：
|
||||
|
||||
| 字段 | 内容 |
|
||||
|------|------|
|
||||
| 运行信息 | run_id, git_sha, 耗时 |
|
||||
| 硬性指标表 | 指标名, 基线, 当前, 阈值, 判定 |
|
||||
| 语义评估表 | 维度, 得分, 判定, 说明 |
|
||||
| 综合判定 | 通过/不通过 |
|
||||
| 诊断（如有） | 根因, 建议 |
|
||||
|
||||
## 与 subagent-driven-development 集成
|
||||
|
||||
在 SKILL.md 的 Step 9（final whole-implementation review）之后追加 Step 10：
|
||||
|
||||
```
|
||||
Step 10: Harness 评估
|
||||
调用 /harness-eval skill
|
||||
通过 → 进入 finishing-a-development-branch
|
||||
不通过 → 根据诊断结果，回到 Step 2 迭代相关 task
|
||||
```
|
||||
|
||||
## 评估范围
|
||||
|
||||
本 skill 当前覆盖①工程评估；②提取信度/③诊断效度的全量评估待 `app/` 流水线落地后接入。
|
||||
Reference in New Issue
Block a user