orca-eval

技能：orca-eval

内容

目的和背景

• 目的： 自我改进闭环：回顾会话日志 → 提炼最佳实践 / 反模式 → 生成 md 报告 → 提出行动建议（提升为技能、修改 CLAUDE.md、添加 hook 等）。报告只是建议——所有行动都必须经过 propose → 审批门槛，不得自行执行。
• 触发条件（何时使用）：
  • /orca-eval [N] — N = 要扫描的最近会话数量（例如 5/10/15）
  • 未指定 N → 仅扫描当前会话
  • 用户说“评估会话”“提炼最佳实践”“根据历史优化流程”
• 非目标： 不自行执行行动（提升技能、修改 CLAUDE.md、添加 hook）；不修改 / 删除会话日志；不每 30 个会话自动触发（Phase 2，不在此技能范围内）。

思维模型

*.jsonl 会话日志 → orca-eval-scan.sh 摘要（提示词 · 工具错误 · 重复命令）→ 4 类信号（Correction · Repetition · Friction · Win）→ 发现 → 恰好 1 项行动（promote-to-skill · update-CLAUDE.md · add-hook · keep · ignore）→ 报告草稿 → 停止并等待批准。

输入和输出约定

	字段	必填？	含义
输入	N	否	按 mtime 排序的最近 *.jsonl 会话数量；默认 = 当前会话
输入	会话日志 ~/.claude/projects/<project-slug>/*.jsonl	是	只读
输出	llmwiki/wiki/draft/orca/DDMMYY-eval-report.md	是	按报告模板
输出	更新 wiki/index.md + wiki/log.md	是	—
输出	向用户显示的行动表	是	“完成” = 用户已看到表格；尚未执行行动

规则和能力

• RULE-01 (MUST)：对会话日志只读——不得修改 / 删除 *.jsonl。
• RULE-02 (MUST)：不得载入完整转录——单个会话可能有数百 KB；通过扫描器摘要读取。
• RULE-03 (MUST)：每项发现只关联 1 项行动；只有用户批准后才能执行行动（如果涉及代码 / 技能更改，则通过 propose）。
• RULE-04 (MUST)：Claude Code 的 JSONL 格式没有公开规范——扫描器失败时回退到当前会话并明确说明，不得生成空报告。
• 能力：通过扫描器读取本地会话日志；写入 wiki 草稿、索引和日志。无网络访问，不修改代码 / 配置。

故障边界

• 扫描器失败 → 部分完成：回退到当前会话并明确说明；不得生成空报告。
• 没有任何信号 → 报告明确写出 0 项发现（不得捏造发现）。
• 用户尚未批准 → 行动状态为 proposed，技能停止。

使用方法

主工作流

步骤	类型	输入	操作	输出 / 退出	失败 / 后续
W01	确定性	N	从仓库根目录运行扫描：skills/orca-eval/assets/orca-eval-scan.sh [N]	摘要	失败 → B01
W02	判断	摘要	提炼 4 类信号	发现列表 + 证据	—
W03	执行	发现	按模板生成报告 + 更新索引 / 日志	报告草稿	—
W04	判断	发现	提出行动建议：向用户显示行动表，停止	行动表	未批准 → 停止

各步骤详述（W01–W04 的权威说明）：

1. 扫描 — 从仓库根目录运行 skills/orca-eval/assets/orca-eval-scan.sh [N]。脚本会返回精简摘要（用户提示词、工具错误、重复的 Bash 命令）。不得载入完整转录——单个会话可能有数百 KB。
2. 提炼 — 从摘要中查找 4 类信号：
   • Correction（纠正）：用户纠正 Agent 的说法（“不，用 X”“错了”“actually…”）→ 新的行为规则
   • Repetition（重复）：跨会话重复 ≥ 3 次的命令 / 操作序列 → 技能化候选项
   • Friction（阻碍）：重复出现的工具错误、多次权限提示、重试循环 → hook / 权限 / 配置候选项
   • Win（成功）：用户快速批准且无需修改的工作流 → 记录为应保留的最佳实践
3. 报告 — 按下方模板写入 llmwiki/wiki/draft/orca/DDMMYY-eval-report.md。更新 wiki/index.md + wiki/log.md。
4. 行动建议 — 每项发现只关联 1 项行动：promote-to-skill / update-CLAUDE.md / add-hook / keep / ignore。向用户显示行动表。停止——只有用户批准后才能执行行动（如果涉及代码 / 技能更改，则通过 propose）。

输入

参数	含义	默认值
N	最近的 session 数量（按 *.jsonl 的 mtime 排序）	当前 session

Session 日志位于 ~/.claude/projects/<project-slug>/*.jsonl — slug 是将 cwd 中的 / 替换为 -（例如 -Users-giatran-orca-workspaces-setup-evaluation）。

分支

ID	类型	条件	行为	跳过 / 失败	重新汇合
B01	恢复	scanner 失败（JSONL 格式变更）	回退到当前 session，并在报告中明确说明	没有可扫描内容 → 提示，不生成空报告	W02
B02	必需条件	操作为代码/skill 变更且用户已批准	转到 propose → gate	用户未批准 → 停止	—

验证和停止

Scanner 是确定性的；信号分类需要判断 — 每条发现都必须在表格中附有证据（session + 简短引文）。在 W04 硬性停止，等待用户批准。

示例

• 正向： /orca-eval 10 → 扫描最新的 10 个 *.jsonl → 发现用户 4 次修正「使用 ./scratchpad/，不要用 /private/tmp」（Correction）→ 将发现关联到 update-CLAUDE.md；报告 llmwiki/wiki/draft/orca/DDMMYY-eval-report.md + action 表，停止。
• 边界/失败： orca-eval-scan.sh 因 JSONL 格式变更而出错 → 回退到当前 session，报告明确记录 scanner 失败；没有任何信号 → 提示 0 条发现，不生成空报告。

参考 — 报告模板

---
type: draft
title: "DDMMYY-eval-report"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

# DDMMYY-eval-report
**Type:** draft
**Status:** proposed
**Tags:** orca-eval, eval-report
**Proposed:** YYYY-MM-DD
**Scope:** <N session / session hiện tại> — <danh sách file jsonl đã quét>

## Best practices
| # | Tín hiệu | Loại | Bằng chứng (session, trích dẫn ngắn) |
|---|----------|------|--------------------------------------|

## Đề xuất action
| # | Finding | Action | Lý do |
|---|---------|--------|-------|

## Origin
- **Sessions:** <paths đã quét>
- **Generated by:** /orca-eval

参考 — 限制

• 对 session 日志只读 — 不修改/删除 *.jsonl。
• Claude Code 的 JSONL 格式没有公开规范 — scanner 失败时回退到当前 session 并明确说明，不生成空报告。
• 每 30 个 session 自动触发：Phase 2（需要 Stop-hook + counter），尚未包含在此 skill 中。

参考 — 参考资料（社区 — 声称于 2026-06-11）

Repo	可借鉴之处
BayramAnnakov/claude-reflect	使用 Regex 捕捉修正（“no, use X”、“remember:”），queue → 两阶段 review，路由到全局或项目 CLAUDE.md，/reflect-skills 查找重复模式并将其转化为 skill
haddock-development/claude-reflect-system	Stop-hook 在 session 结束时自动运行（可作为 Phase 2 每 30 个 session 自动触发的示例），跨 skill 提取最佳实践
netresearch/claude-coach-plugin	摩擦检测 — 统计 permission prompts / retry loops，作为改进信号
robonuggets/skills — calibrate	Session 内自我改进：审查当前对话，有针对性地提出 skill/memory 修改建议
a-c-m reflection.md gist	精简的单文件版本 — 保持此 skill 简洁，避免过度设计

起源

• 原始文件： llmwiki/raw/evalution-engineering.md
• 草稿： wiki/draft/orca/110626-orca-eval-skill.md