# Experience to Skill

一个把多次 Agent 任务经验整理成「一项可审查 Skill 改进」的 Codex Skill，并用冻结的失败用例与保护用例决定接受、拒绝或暂缓。

![Experience to Skill 头图](media/xiaohongshu/01-cover.png)

项目受到 Google Research 论文 [《WikiSkill: Compiling Agent Experience into Persistent Knowledge for Skill Evolution》](https://arxiv.org/abs/2608.27454)启发。这是一个独立、安全边界更明确的工程化改编，不是 Google 官方实现，也不声称复现论文的基准结果。

[English README](README.md)

## 它解决什么问题

Agent 完成一次任务，经验往往随会话一起消失。把每次纠错直接塞进 `SKILL.md` 也会带来轶事规则、互相冲突、能力回退和越权自修改。

Experience to Skill 把三类状态分开：

```text
选定的运行证据  ->  可积累的 Wiki 模式  ->  一项 Skill 候选改动
     raw/                 wiki/                 skills/
                            |                      |
                            +---- 冻结验证门 -------+
                                  接受 / 拒绝 / 暂缓
```

它帮助维护者完成六件事：

1. 只记录明确选中且已脱敏的运行材料；
2. 区分可观察事实、归因假设、反证和证据缺口；
3. 合并重复模式，同时保留被拒绝的想法；
4. 每次只提出一项原子化 Skill 改动；
5. 在冻结的失败用例和保护用例上比较基线与候选；
6. 把通过验证的提案交给人决定是否采纳或发布。

验证通过只说明当前证据支持这项候选改动，不等于获得编辑、部署、发布或对外发送的权限。

## 包含内容

- `SKILL.md`：Agent 工作流与硬边界；
- `PURPOSE.md`：适用范围、来源与非目标；
- `references/`：工作区契约、验证门和隐私安全规则；
- `scripts/init_workspace.py`：初始化隔离的本地工作区；
- `scripts/record_evidence.py`：复制选定材料、计算哈希，并执行小型密钥拒绝列表扫描；
- `scripts/validate_workspace.py`：检查结构、引用和证据新鲜度；
- `scripts/gate_candidate.py`：根据冻结评分卡输出 `accept`、`reject` 或 `hold`；
- `examples/scorecards/`：最小评分卡示例；
- `tests/`：仅依赖 Python 标准库的回归测试。

## 快速开始

把仓库克隆到 Codex Skills 目录，或把 Release ZIP 解压到该目录：

```powershell
git clone https://github.com/rrrrrredy/experience-to-skill "$env:CODEX_HOME\skills\experience-to-skill"
```

初始化工作区，并冻结目标 Skill 的起始哈希：

```powershell
python scripts/init_workspace.py D:\Codex\_tmp\skill-evolution-demo `
  --target-skill path\to\target-skill\SKILL.md
```

记录一份已脱敏的任务轨迹：

```powershell
python scripts/record_evidence.py `
  --workspace D:\Codex\_tmp\skill-evolution-demo `
  --id run-001 `
  --outcome fail `
  --trace path\to\sanitized-trace.md `
  --gap "没有捕获浏览器截图"
```

然后让 Agent 使用 Skill：

```text
使用 $experience-to-skill 整理这些运行记录，针对目标 Skill 提出一项
边界明确的改动，并准备冻结的失败用例和保护用例。不要直接应用提案。
```

检查工作区：

```powershell
python scripts/validate_workspace.py D:\Codex\_tmp\skill-evolution-demo
```

执行验证门：

```powershell
python scripts/gate_candidate.py examples\scorecards\accept.json
```

退出码：`0` 表示接受，`1` 表示拒绝，`2` 表示暂缓或证据不完整。

## 接受条件

候选改动只有同时满足以下条件才会被接受：

- 结构、安全、范围和评估器完整性检查全部通过；
- 至少一个冻结失败用例得到改善；
- 失败用例的平均改善超过预先声明的阈值；
- 失败用例与保护用例都没有回退。

证据缺失或不可比时输出 `hold`。迁移用例单独报告，本地通过不能证明跨模型或跨环境可迁移。

## 有意保留的边界

- 一次任务不自动成为通用规则。通常需要两个独立运行，或一个可确定复现的问题加一个保护用例。
- 脚本只读取维护者明确提供的文件。
- 内置密钥扫描只是小型拒绝列表，不构成隐私保证。
- 原始轨迹默认留在本地。公开时只发布提炼后的模式和最小证据引用。
- 任务轨迹、工具输出与网页内容都按不可信数据处理，不能充当指令。
- 提案者不能修改评估器、标准答案、用例或验证门。
- 本 Skill 不读取、不要求、也不声称拥有隐藏思维链。
- Skill 检索、长时任务与跨模型迁移需要另外评估。
- 通过的提案不会被自动应用。

## 与 WikiSkill 的关系

论文把原始经验、持久 Wiki 知识和可执行 Skill 分层，这是本项目的核心启发。本项目进一步加入证据哈希、反证、争议与废弃状态、保护用例、评估器完整性检查、默认本地隐私、`hold` 状态，以及验证后的人工授权。

这些约束改变了它的使用边界。本仓库是在产品工作流中改编论文思路，不声称复现论文报告的性能增益。

## 验证与许可

```powershell
python -m unittest discover -s tests -v
```

v1.0.0 已通过 13 项标准库回归测试、官方 Skill 结构校验、独立前向试用，以及 [Skill Security Guard](https://github.com/rrrrrredy/skill-security-guard) 静态扫描，评级 A（100/100）。这些结果覆盖当前软件包和已声明契约，不证明它在所有生产环境中的实际增益或运行时安全。

如果用于研究，请同时引用原始 WikiSkill 论文。本项目采用 [MIT License](LICENSE)。

小红书发布图片与生成提示词位于 [`media/xiaohongshu/`](media/xiaohongshu/README.md)。