Beaver Project / Skill Learning

Skill Replay Eval
从文本评分到行为证据

让技能草稿评估真正覆盖任务执行、工具调用、副作用和草稿保真，而不是只看生成文本是否“像一个好技能”。

Beaver 技能学习评估方案技术分享 · 架构设计 · UI 与测试路线
skill-replay-eval-design.md

system context

Beaver 是多实例 AI 工作台，Skill Replay Eval 位于单实例技能学习链路。

01

auth-portal

用户注册、登录和模型配置引导入口。

02

authz-service

账号、后端身份和内部授权编排。

03

deploy-control

创建、配置和管理独立 app-instance 容器。

04

router-proxy

按实例域名把外部流量转发到对应容器。

05

app-instance

单用户工作台，包含前端、后端、workspace 和 skills。

技能页

处理 published skills、candidates、draft review。

学习管线

从历史任务发现候选，合成草稿，再进行安全和评估门禁。

本方案

增强草稿评估，给发布前审查提供可追溯证据。

project boundary: app-instance/backend + app-instance/frontend

current_state.py

旧评估的问题：它在评“草稿文本”，不是评“任务结果”。

heuristic-only

现状

  • 只从 candidate.source_run_ids 构造轻量报告。
  • 历史 run 使用 validation_result.score 或 success fallback。
  • 候选得分主要估算自 draft text。
  • 不复跑任务，不执行工具，不比较旧技能和新草稿行为。
behavior evidence

目标

  • 用历史任务作为 eval cases，运行 baseline 与 candidate 两个 arm。
  • 安全工具真实执行，危险或不可用工具进入 surrogate 判断。
  • 报告分开披露执行覆盖、替身覆盖、阻塞覆盖和置信度。
  • 修订和合并草稿必须证明没有无理由丢失原技能内容。
risk: high-looking score can still hide tool regressions

evaluation_model

核心模型：历史 case 选择 + 双臂 replay。

Case selection

候选类型
选择来源
优先级
规模
new_skill
source runs + 相似主题 accepted runs
相似任务主题
最多 10 个
revise_skill
激活目标 skill/version 的 accepted runs
近期优先，再按任务分散
最多 10 个
merge_skills
相关 skills 共同激活的 accepted runs
共同出现证据
最多 10 个

Two arms

same task

输入一致

同一任务文本、同一历史上下文、同一模型设置、同一最大工具迭代数。

baseline

旧行为

new_skill 无技能；revise_skill 用旧技能；merge_skills 用旧相关技能。

candidate

新草稿

将 draft skill 作为 pinned draft guidance 注入，并记录行为差异。

same inputs, different skill guidance, comparable outputs

tool_policy

所有工具都被覆盖，只是进入不同执行模式。

modeexecuted

能安全隔离的工具，在 replay 环境中真实执行。

modesurrogate

不能安全执行，但记录 intended call，由 LLM 替身判断效果。

modeblocked

既不能执行，也无法可靠判断，明确降低置信度。

reportcoverage

执行、替身、阻塞覆盖率分开披露。

工具类型
默认模式
原因
例子
workspace read/write
executed
可在临时 workspace clone 中执行
读写代码、生成文件、测试 artifact
web/search read
executed
只读且可缓存输出
搜索、打开网页、读取公开文档
external write
surrogate
默认不能写生产第三方系统
邮件、日历、消息发送
destructive action
surrogate / blocked
删除、支付、权限变更不可自动执行
不可逆外部写入
principle: include third-party tools without production side effects

replay_environment

隔离 replay 环境：让任务复跑有证据，但不污染真实世界。

每个 case、每个 arm 都创建独立状态。runner 负责执行、拦截、记录，评估器在 runner 外部读取 artifacts 和 side effects。

session

Temporary session id

避免污染真实会话状态。

workspace

Temporary workspace root

文件读写落在临时 clone。

trace

Tool call trace

记录调用、参数、模式和理由。

journal

Side-effect journal

外部写入不落生产，只留证据。

replay_case.json
{
  "case_id": "run-accepted-042",
  "arm": "candidate",
  "workspace_root": "/tmp/beaver-replay/...",
  "tool_calls": [
    { "tool": "filesystem.write",
      "mode": "executed" },
    { "tool": "outlook.send_mail",
      "mode": "surrogate" }
  ],
  "artifacts": ["draft.md"],
  "side_effects": ["intended_email"]
}
pattern: OfficeBench-style isolated testbed, adapted to Beaver skills

surrogate_evaluator

替身评估不是跳过工具，而是评估 intended effect。

输入 payload

  • 工具名称和 schema。
  • 候选 arm 计划调用的 arguments。
  • 工具被分类为 surrogate 的原因。
  • 历史 accepted evidence 和任务预期副作用。
  • assistant 在调用前后的 rationale。

判断维度

  • 调用是否满足任务目标。
  • 参数是否完整、正确、可执行。
  • 是否遗漏、重复或不必要。
  • 是否有越权、危险或不可逆风险。
  • candidate 相比 baseline 是否真实改善。
surrogate_score.py
candidate_score = quality(intended_effect, arguments, evidence)
risk_penalty = risk(missing_args, duplicated_calls, unsafe_scope)
confidence = lower_than_real_execution

case_score = candidate_score - risk_penalty
surrogate contributes to score, but lowers confidence

report_and_gates

报告兼容旧 UI，同时新增 replay 证据和发布门禁信号。

legacypassed

保留 passed、score_delta、cases、status 等旧字段。

coverage3 modes

execution、surrogate、blocked coverage。

qualitydelta

baseline mean、candidate mean、improved/regression count。

trustconfidence

低置信度不能自动等同可发布。

SkillDraftEvalReport
{
  "eval_version": "replay-v1",
  "mode": "replay",
  "execution_coverage": 0.58,
  "surrogate_coverage": 0.33,
  "blocked_coverage": 0.09,
  "confidence": "medium",
  "case_reports": [...],
  "tool_mode_summary": {...}
}

Publish gate logic

  • 高分但低置信度，进入更强人工 review。
  • 重要工具全部 blocked，不允许自动 pass。
  • 部分 case 失败，status = partial，降低 confidence。
  • replay 基础设施失败，status = replay_error。
  • provider 不可用时保留 skipped-provider 行为，但标明没有 replay evidence。
score answers quality, confidence answers how much we can trust it

preservation_contract

修订草稿必须保留原技能内容，除非明确说明改变理由。

为什么需要

现有 synthesizer 对 revision 和 merge 只拿到候选理由、相关技能名、工具名、任务摘要和 session excerpts，没有完整 base skill body。

failure mode

重新生成看起来更整洁，但可能丢掉原技能里的安全边界、工具约束、工作流顺序和异常处理。

新合同

  • 向 synthesis prompt 传入 base skill name、version、完整 frontmatter 和完整 content。
  • 要求模型默认保留现有指令，只有在明确理由下才改变。
  • 输出 preserved_sections、changed_sections、dropped_sections、change_reason。
  • preservation checker 比较 base 和 draft，未解释的关键丢失会标记风险。
revision is an edit contract, not a fresh rewrite

implementation_plan

实现路径：扩展现有技能学习管线，新增小模块而不是重写系统。

backend model

数据层兼容

  • 扩展 SkillDraftEvalReport。
  • 新增 replay 字段默认值。
  • 保留旧 payload 读取能力。
learning helpers

评估能力拆分

  • case_selection.py
  • preservation.py
  • replay.py
  • surrogate.py
pipeline + ui

接入和展示

  • eval.py 编排 replay。
  • pipeline.py 更新发布门禁。
  • loop.py 支持 replay executor override。
  • Skills UI 展示 coverage、case 和 preservation。
target files
app-instance/backend/beaver/skills/learning/
  case_selection.py
  preservation.py
  replay.py
  surrogate.py
  eval.py
  synthesizer.py
  pipeline.py

app-instance/frontend/app/(app)/skills/page.tsx
app-instance/frontend/types/index.ts
architecture: focused helpers under existing SkillLearningPipelineService.evaluate_draft()

skills_review_ui

评审页先给结论，再让审核者展开证据。

Concise summary

passfailed

发布门禁结论。

delta+0.18

candidate - baseline。

exec58%

真实执行覆盖。

confmedium

证据可信度。

Detailed evidence

  • Replay cases：每个历史任务的 baseline/candidate 分数。
  • Tool calls by mode：executed、surrogate、blocked 分类和理由。
  • Artifacts and side effects：产物和副作用 journal。
  • Preservation report：修订草稿的保留、变更、删除风险。
  • Raw eval payload：保留完整 JSON 供深度排查。
UX principle

用户不需要预先配置每个工具的策略。系统在报告里解释覆盖、阻塞和不确定性，让审核者知道该相信多少。

page: app-instance/frontend/app/(app)/skills/page.tsx

testing_strategy

交付标准：覆盖决策逻辑与真实工具形态。

01模型兼容

旧 payload 可读，新 replay 字段可写，UI 不被旧数据破坏。

02核心逻辑

case selection、arm construction、tool mode aggregation、surrogate payload。

03保真检查

base section 保留、删除风险、publish gate 对 preservation risk 的处理。

04混合工具

安全文件写真实执行，外部写入被拦截为 surrogate，生成可审计报告。

Unit tests

历史 case 选择、双臂构造、工具模式分类、替身评分 payload、保真检查、低置信发布门禁。

Integration-style tests

stub filesystem write、stub external write、candidate 同时改善真实 artifact 和 surrogate side effect。

next: implement tasks 1-12 from the current plan
Q

Questions

技能发布前，不只要看草稿写得好不好，还要看它在历史任务里做了什么、没做什么、敢不敢相信。

behavior evidence tool coverage confidence gates draft preservation
Beaver Skill Replay Eval