Files

T

iomgaa 6bdb802f01 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

2026-07-06 20:59:03 -04:00

5.1 KiB

Raw Blame History

name, description, argument-hint

name	description	argument-hint
harness-eval	评估功能的真实运行性能。从 Wiki 读取 schema 和 metric 定义，查询 SQLite 日志，对比基线，调用 LLM judge 做语义评估，产出诊断和迭代建议。触发短语: harness eval, 评估性能, 性能评估。	[run_id]

Harness Eval

Overview

在真实环境中运行程序后，评估性能是否达标，诊断问题，决定是否迭代。

核心原则： 不是"通过就停"，而是基于真实指标判断"跑得好不好"。

触发方式

自动：subagent-driven-development Step 10，所有任务完成 + final review 通过后
手动：/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: 准备

列出 research-wiki/schemas/ 下所有 schema 实体，获取表名和列信息
列出 research-wiki/metrics/ 下所有 metric 实体，获取基线值和阈值
确认 results/harness.db 存在，查询 _runs 表获取最新运行状态
如果指定了 run_id，使用该 run_id；否则使用最近一次 status='completed' 的 run

Phase 2: 运行

2a: 检查已有运行记录

在 subagent-driven-development 流程中，某个子任务可能已经执行过全局运行并将结果写入了 harness.db。此时 harness-eval 不应重复运行，直接复用已有记录即可。

查询 _runs 表，查找 status='completed' 且 git_sha 与当前 HEAD 匹配的记录
找到匹配记录 → 使用该记录的 run_id，跳过运行，直接进入 Phase 3。在最终报告中注明「复用已有运行: run_id=xxx」
未找到匹配记录 + 自动触发 → 继续 2b
未找到匹配记录 + 手动触发 → 询问用户是否需要执行运行

2b: 重跑流水线（仅无可用记录时）

make deploy-testing 起服务（api / worker / Postgres / Redis / 对象存储）
对真实样本重跑流水线，结果落 results/harness.db；属长时操作，建议按「长时命令执行约定」在 tmux 中运行
轮询检查 _runs 表状态，等待完成
确认 _runs 表中对应 run 的 status = 'completed'
如果 status = 'failed'，直接进入 Phase 6 诊断

Phase 3: 硬性指标检查

对 research-wiki/metrics/ 中每个标记为硬性判定的指标：

从 metric 实体中读取：指标名、基线值、阈值、对应的 schema（表名和列名）
执行 SQL 查询获取当前运行的实际值
对比：实际值 vs 阈值
记录结果：pass / fail + 具体数值

Phase 4: 语义评估

对 research-wiki/metrics/ 中每个标记为语义判定的指标：

收集 evidence：相关表的数据、_events 表的事件、配置信息
调用 LlmJudge.evaluate(EvalRequest)（请求体封装 criteria、evidence、rubric）
记录结果：Verdict

Phase 5: 综合判定

硬性指标全部 pass 且语义评估全部 pass → 通过
任一不通过 → 不通过，进入 Phase 6

Phase 6: 诊断与迭代决策（仅不通过时）

收集失败信息：哪些指标不达标、实际值与期望值的差距
查询 _events 表获取运行过程中的关键事件
调用 LlmJudge.diagnose(error_context, log)
向用户报告：
- 问题根因分析
- 修复建议
- 是否建议再迭代一轮

Phase 7: 记录到 Wiki

创建 finding 实体：

conda run -n chs python3 .claude/tools/research_wiki.py add_entity research-wiki/ --type finding --id eval-<run_id> --title "Harness 评估: <run_id>"

在 finding 中记录完整评估报告（硬性指标表 + 语义评估结果 + 诊断结论）

建立 edge：

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 "..."

如果通过且用户确认，更新 metric 实体中的基线值为当前值
重建索引

输出格式

评估完成后，向用户输出结构化报告：

字段	内容
运行信息	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/ 流水线落地后接入。

5.1 KiB Raw Blame History Unescape Escape