{"id":"5e93b895-4d3b-4630-8f63-12d12d1ebf8f","slug":"evoskill","kind":"skill","name":"EvoSkill","summary":"Skill optimization framework for LLMs — evolve system prompts via textual gradient descent with beam search, human-in-the-loop annotation, and DPO preference data export.","owner":"JimmyMa99","repoUrl":"https://github.com/JimmyMa99/EvoSkill","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-03-17T08:54:27.000Z","addedAt":"2026-10-21T17:01:12.429Z","logoUrl":"https://avatars.githubusercontent.com/u/101508488?u=ee589cd3b8e6956b071a8e7edda0f71683d032d3&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","data-analytics"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T06:52:11.708Z","sample":false,"url":"https://conduits.dev/tools/evoskill","language":"Python","transports":["stdio"],"install":{"pypi":"treeskill"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# EvoSkill\n\n> **Note**: 本项目由于与其他仓库重名，已迁移至 [TreeSkill](https://github.com/JimmyMa99/TreeSkill)，后续所有更新均在 TreeSkill 进行。\n\n[English](./docs_en/README.md) | 中文\n\n**Kode 前向 + AS(skill)O 自进化框架**\n\n当前主流 pipeline 已经收敛为：\n\n```text\nKode 前向执行 → 失败样本 / 反馈 → ASO 生成/修改 skill program → 评估 → 剪枝 / 合并\n```\n\n也就是说，优化对象不再只是单个 prompt，而是完整的：\n\n```text\nprogram = root prompt + skills + selection policy\n```\n\n```\n问题 / 数据集 → Kode 执行 → 文本梯度 / proposal → skill growth → prune / merge → 更好的 Agent\n```\n\n## 核心理念\n\nTreeSkill 将 LLM prompt 优化类比为深度学习的训练循环，但**完全不需要训练模型**：\n\n| 深度学习 | TreeSkill |\n|----------|----------|\n| 模型权重 | System Prompt |\n| 训练数据 | 交互反馈（人工 or LLM Judge） |\n| 损失函数 | 失败案例分析 |\n| 梯度 | 文本梯度（自然语言的失败归因） |\n| 参数更新 | Prompt 重写（Beam Search 多候选） |\n| Epoch | 优化轮次（支持断点续跑） |\n\n## 特性\n\n- **免训练 (Train-Free)** — 纯 API 调用，无需 GPU、无需微调、无需标注数据\n- **Human-in-the-Loop** — 人工反馈驱动优化：`/bad` 标记失败、`/rewrite` 提供理想回答、`/target` 设置优化方向，让领域专家直接参与 prompt 进化\n- **Beam Search APO** — 对齐 [Agent-Lightning](https://github.com/microsoft/agent-lightning/) 的优化算法：多模板梯度分析 × 多候选生成 × Beam Search 选择，持续保留 top-k prompt 跨轮优化\n- **模型无关** — 支持 OpenAI、Anthropic、任何 OpenAI 兼容 API（硅基流动、Ollama 等）\n- **Agent Skills 标准** — Skill 文件遵循 [agentskills.io](https://agentskills.io) 开放标准\n- **层级 Skill 树** — 自动拆分、剪枝、嫁接，递归 bottom-up 优化\n- **多协议工具系统** — Skill 可声明和调用多种格式的外部工具：\n  - **Python 脚本** — `script.py` 中的函数自动注册为工具\n  - **HTTP API** — 声明式调用任意 REST 端点\n  - **MCP 服务器** — 兼容 [Model Context Protocol](https://modelcontextprotocol.io/) 的工具调用\n- **断点续跑** — 优化中断后从上次进度恢复，不浪费已完成的 API 调用\n- **插件注册机制** — 通过 `@scorer`、`@gradient`、`@rewriter`、`@skill_format` 装饰器自定义优化流程的每个环节（[详细文档](./docs/REGISTRY_GUIDE.md)）\n- **多端点支持** — Actor / Judge / Rewrite 可配置不同的 API 端点、模型和协议（OpenAI / Anthropic）\n- **Kode CLI 集成** — 使用 [Kode](https://github.com/shareAI-lab/Kode-Agent) 作为 Agent 前向引擎，Skill 在真实 agent loop 中执行和验证（[配置指南](#kode-集成)）\n- **AgentHarness** — 内置轻量 agent loop，支持 bash / 文件读写 / skill 加载，无需外部依赖即可评估 Skill\n\n## 安装\n\n```bash\ngit clone https://github.com/JimmyMa99/TreeSkill.git\ncd TreeSkill\npip install -e .\n```\n\n## 当前主流 Pipeline\n\n推荐直接跑 SealQA 生命周期 demo。它使用：\n- `Kode` 作为前向执行器\n- `ASO` 作为 program / skill 修改器\n- 一个免费、稳定的本地 `search_web/fetch_url` 抽象来模拟检索\n\n```bash\n# 默认就是当前主流 pipeline\npython -m treeskill\n\n# 等价写法\npython -m treeskill sealqa-lifecycle\n```\n\n输出会落到：\n\n```text\ndemo/outputs/sealqa-tree-lifecycle/\n├── root/\n├── generated/\n├── evolved/\n├── pruned/\n├── merged/\n└── summary.json\n```\n\n如果你要跑更接近真实 ASO frontier 的最小实验：\n\n```bash\npython -m treeskill sealqa-aso\n```\n\n旧的交互式 APO/chat 入口仍保留为兼容模式：\n\n```bash\npython -m treeskill legacy-chat -- --skill demo/writing-skills\n# 或\npython -m treeskill.main --skill demo/writing-skills\n```\n\n## 快速开始\n\n### 1. 配置 API\n\n```bash\ncp demo/example/config.yaml my-config.yaml\n# 编辑 my-config.yaml，填入 API Key\n```\n\n或用环境变量：\n\n```env\nTREE_LLM_API_KEY=your-api-key\nTREE_LLM_BASE_URL=https://api.siliconflow.cn/v1\nTREE_LLM_MODEL=Qwen/Qwen2.5-14B-Instruct\n```\n\n### 2. 启动当前主流 demo\n\n```bash\npython -m treeskill\n```\n\n### 3. 启动旧版兼容 chat / APO\n\n```bash\n# 用已有 skill 目录\npython -m treeskill.main --config my-config.yaml --skill skills/fast-test-skill\n\n# 用默认 skill（自动创建）\npython -m treeskill.main --skill default\n\n# 用 skill 树目录\npython -m treeskill.main --skill my-skills/\n```\n\n### 4. Human-in-the-Loop 优化（兼容模式）\n\nTreeSkill 的核心交互模式是**人机协作优化**：领域专家通过自然语言反馈，引导 APO 引擎改进 prompt。\n\n```\nYou: 帮我写一段关于春天的短文\n\n🤖 Assistant: [生成结果]\n\nYou: /bad 太像AI写的，缺乏生活气息       ← 标记失败 + 原因\nYou: /rewrite 春天来了，小区的玉兰花...    ← 提供理想回答（可选）\nYou: /target 更像人，有生活气息            ← 设置优化方向（可选）\nYou: /optimize                            ← 触发 APO 优化\n\n✓ Skill optimized → writing-assistant (v1.0 → v1.1) (checkpoint saved)\n```\n\n每次 `/bad` 和 `/rewrite` 仍然只更新当前这条 Trace；同一次会话里所有 Trace 共享同一个 `session_id`，但每条交互都有自己独立的 `trace.id`。`/optimize` 时 APO 引擎从这些 Trace 中提取失败模式，计算文本梯度，重写 prompt。**领域专家不需要懂 prompt engineering，只需要判断回答好不好。**\n\n也支持数据集驱动的模式：\n\n```bash\n# 全自动：LLM Judge 评分 → APO 优化，无需人工\npython -m treeskill.main --optimize --dataset train.jsonl --skill my-skill --no-resume\n\n# 人机协作标注：auto-judge 打分，人可随时 override（偏好信号 → 指导 judge）\npython -m treeskill.main --annotate --dataset train.jsonl --skill my-skill\n\n# 纯手动标注\npython -m treeskill.main --annotate --dataset train.jsonl --skill my-skill --manual\n```\n\n标注模式中，人工反馈是自然语言偏好信号，既作为 APO 梯度的输入，也可导出为 DPO 微调数据。\n\nCLI 中输入 `/` 时会弹出 slash 命令候选列表，输入命令前缀时会自动收窄候选，便于快速发现和选择可用命令。\n\n## Skill 文件格式\n\n遵循 [Agent Skills 标准](https://agentskills.io/specification)，每个 Skill 是一个目录：\n\n```\nmy-skill/\n├── SKILL.md          # YAML frontmatter + Markdown body（= system prompt）\n├── config.yaml       # 可选：few-shot、temperature、工具声明、日程等\n└── script.py         # 可选：Python 工具函数\n```\n\n**SKILL.md 示例：**\n\n```markdown\n---\nname: my-writing-assistant\ndescription: 专业中文写作助手，帮助撰写和润色各类文本。\nmetadata:\n  version: \"1.0\"\n  target: \"更像真人说话，有温度\"\n---\n\n你是一位专业的中文写作助手。\n语言要自然流畅，避免 AI 腔。\n```\n\n> 详见 [docs/design/skill-format.md](./docs/design/skill-format.md)\n\n## 工具系统\n\nSkill 可以声明外部工具，agent 在对话中按需调用。支持三种协议：\n\n**config.yaml 声明示例：**\n\n```yaml\ntools:\n  # HTTP API 工具\n  - name: weather\n    type: http\n    endpoint: https://api.weather.com/current\n    method: GET\n    description: 获取当前天气\n\n  # MCP 工具\n  - name: database\n    type: mcp\n    mcp_server: localhost:5000\n    tool_name: query\n    description: 查询数据库\n```\n\n**script.py 自动注册：**\n\n```python\n# script.py 中的公开函数自动成为工具\ndef search_docs(query: str) -> str:\n    \"\"\"搜索文档库\"\"\"\n    ...\n```\n\n工具继承：子 Skill 自动继承父 Skill 的工具声明，同名覆盖。\n\n> 详见 [docs/TOOLS_GUIDE.md](./docs/TOOLS_GUIDE.md)\n\n## Skill 树\n\nSkill 通过目录嵌套形成层级：\n\n```\nwriting-skills/\n├── SKILL.md              # 根：通用写作\n├── social/\n│   ├── SKILL.md          # 社交写作\n│   └── moments/\n│       └── SKILL.md      # 朋友圈专精\n└── business/\n    ├── SKILL.md          # 商务写作\n    └── email/\n        └── SKILL.md\n```\n\n优化时 bottom-up：先叶子后父节点。反馈矛盾时自动建议拆分。支持 graft（嫁接）跨树复用 skill。\n\n> 详见 [docs/design/tree-optimization.md](./docs/design/tree-optimization.md)\n\n## 命令一览\n\n| 命令 | 作用 |\n|------|------|\n| `/bad <原因>` | 标记上条回复不好 |\n| `/rewrite <文本>` | 提供理想回答（同时积累 DPO 偏好数据） |\n| `/export-dpo <output.jsonl>` | 导出 DPO 偏好数据（用于微调） |\n| `/target <方向>` | 设置优化方向 |\n| `/optimize` | 触发 APO 优化（支持断点续跑） |\n| `/image <路径>` | 附加图片（多模态） |\n| `/audio <路径>` | 附加音频（语音输入） |\n| `/save` | 保存当前 skill |\n| `/tree` | 显示技能树 |\n| `/select <路径>` | 切换子技能（如 `social.moments`） |\n| `/split` | 分析是否需要拆分 |\n| `/ckpt` | 列出 checkpoint |\n| `/restore <名称>` | 从 checkpoint 恢复 |\n| `/tools` | 查看可用工具 |\n| `/quit` | 退出 |\n\n## AS(skill)O 主线\n\n当前推荐的优化对象是 skill program，而不是单个 prompt：\n\n| 层级 | 当前主线 |\n|------|----------|\n| 前向执行 | `Kode` |\n| 优化对象 | `root prompt + skills + selection policy` |\n| 修改动作 | `add_skill / revise_skill / drop_skill / merge_skills / adjust_selection_policy` |\n| 生命周期 | `root -> generate -> evolve -> prune -> merge` |\n| 推荐 demo | `python -m treeskill` |\n\n其中，SealQA lifecycle demo 会显式展示：\n- 从弱 root 起步\n- 自动长出检索 / 校验 / 时效性 skill\n- 自进化强化 skill 用法\n- 剪枝低收益 skill\n- 合并 / 重整 skill 集合\n\n## APO 优化原理（兼容层）\n\nAPO（Automatic Prompt Optimization）引擎对齐 [Agent-Lightning](https://github.com/microsoft/agent-lightning/) 的设计，核心是 **Beam Search + 文本梯度下降**：\n\n```\n                    ┌─ 梯度模板 1 ─┐     ┌─ 编辑模板 1（激进重写）─┐\n失败 Traces ──→     ├─ 梯度模板 2 ─┤ ──→ ├─ 编辑模板 2（保守修复）─┤ ──→ 评分 ──→ Top-K Beam\n                    └─ 梯度模板 3 ─┘     └─ branch_factor 个候选  ─┘\n```\n\n**单轮流程：**\n\n1. **采样 Traces** — 从反馈中选取失败案例\n2. **计算文本梯度** — 随机选梯度模板（3 种），让 judge 模型分析\"prompt 哪里导致了失败\"\n3. **生成候选** — 随机选编辑模板（激进重写 / 保守修复），每个 parent prompt 生成 `branch_factor` 个候选\n4. **评分选择** — 对所有候选 + 原 beam 评分，保留 top `beam_width` 个\n\n**两种模式：**\n\n| 模式 | 配置 | 行为 |\n|------|------|------|\n| 单轨 (默认) | `beam_width=1` | 一次梯度 → N 候选 → 选最佳，兼容旧版 |\n| Beam Search | `beam_width>1` | 保留 top-k prompt 跨轮优化，更稳定 |\n\n支持断点续跑——中断后 `.evo_resume.json` 记录已完成的节点，下次自动跳过。\n\n> 详见 [docs/design/apo-optimization.md](./docs/design/apo-optimization.md)\n\n## Checkpoint\n\n每次优化自动保存 checkpoint：\n\n```\nckpt/\n└── writing-assistant_v1.2_20260306_140000/\n    ├── skill/          # 完整 skill 树\n    │   └── SKILL.md\n    └── mem/\n        ├── traces.jsonl\n        └── meta.json\n```\n\n```bash\n# CLI 恢复\n/ckpt                                                # 列出\n/restore writing-assistant_v1.2_20260306_140000       # 恢复\n\n# 命令行恢复\npython -m treeskill.main --ckpt ckpt/writing-assistant_v1.2_20260306_140000\n```\n\n## 项目结构\n\n```\ntreeskill/\n├── pipeline_main.py       # 当前主入口：Kode + ASO pipeline\n├── core/                   # 核心抽象层\n│   ├── abc.py             # 抽象基类\n│   ├── optimizer.py       # TrainFreeOptimizer (TGD)\n│   ├── tree_optimizer.py  # TreeAwareOptimizer (拆分/剪枝)\n│   ├── strategies.py      # 优化策略（保守/激进/自适应）\n│   └── validators.py      # 验证器\n├── adapters/              # 模型适配器\n│   ├── openai.py          # OpenAI / 兼容 API\n│   └── anthropic.py       # Anthropic Claude 4.5/4.6\n├── schema.py              # 数据模型 (Skill, Message, Trace, ToolRef)\n├── skill.py               # SKILL.md 解析器/写入器\n├── skill_tree.py          # 层级 Skill 树管理 (graft/split/merge/prune)\n├── aso_program.py         # Skill program 数据结构\n├── aso_optimizer.py       # AS(skill)O 主循环\n├── optimizer.py           # APOEngine（兼容层，旧 pipeline）\n├── tools.py               # 工具系统 (HTTP, MCP, script.py)\n├── resume.py              # 断点续跑状态管理\n├── checkpoint.py          # Checkpoint 快照\n├── cli.py                 # 交互式 CLI (兼容层)\n├── registry.py            # 插件系统 (@adapter, @optimizer)\n└── main.py                # 旧 chat / APO 入口\n```\n\n## 配置参考\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `TREE_LLM_API_KEY` | — | API 密钥 |\n| `TREE_LLM_BASE_URL` | `https://api.openai.com/v1` | API 地址 |\n| `TREE_LLM_MODEL` | `gpt-4o` | 聊天模型 |\n| `TREE_LLM_JUDGE_MODEL` | `gpt-4o` | Judge 模型（计算梯度 + 评分） |\n| `TREE_LLM_TEMPERATURE` | `0.7` | 生成温度 |\n| `TREE_STORAGE_TRACE_PATH` | `./data/traces.jsonl` | Trace 路径 |\n| `TREE_STORAGE_SKILL_PATH` | `./skills` | Skill 目录 |\n| `TREE_APO_GRADIENT_ACCUMULATION_STEPS` | `5` | 每次梯度计算的反馈样本数 |\n| `TREE_APO_BEAM_WIDTH` | `1` | Beam 宽度（1=单轨，>1=beam search） |\n| `TREE_APO_BRANCH_FACTOR` | `2` | 每个 parent 生成的候选数 |\n| `TREE_APO_BEAM_ROUNDS` | `3` | Beam search 轮数 |\n\n完整配置模版：[`demo/example/config.yaml`](./demo/example/config.yaml)\n\n## 文档\n\n| 文档 | 说明 |\n|------|------|\n| [APO 优化原理](./docs/design/apo-optimization.md) | 两种优化模式 + TGD 循环 + 断点续跑 |\n| [树感知优化](./docs/design/tree-optimization.md) | 自动拆分、剪枝、部分优化 |\n| [Skill 文件格式](./docs/design/skill-format.md) | Agent Skills 标准 + SKILL.md 格式 |\n| [快速开始](./docs/QUICKSTART.md) | 5 分钟上手 |\n| [使用指南](./docs/USAGE_GUIDE.md) | Skill 加载、配置管理 |\n| [架构设计](./docs/ARCHITECTURE.md) | 核心架构和设计理念 |\n| [核心抽象](./docs/CORE_ABSTRACTION.md) | Prompt、Gradient、Experience 接口 |\n| [工具系统](./docs/TOOLS_GUIDE.md) | Python、HTTP、MCP 工具注册 |\n| [Kode + MiniMax Thinking 验证](./docs/KODE_MINIMAX_THINKING.md) | 原版 Kode 与 MiniMax thinking 模式兼容结论 |\n| [OpenAI 适配器](./docs/OPENAI_ADAPTER.md) | GPT-4o、o1 等 |\n| [Anthropic 适配器](./docs/ANTHROPIC_ADAPTER.md) | Claude 4.5/4.6 系列 |\n| [跨模型 Skill 迁移](./docs/design/cross-model-transfer.md) | 双模型 TGD：大模型优化，小模型执行 |\n| [优化器详解](./docs/OPTIMIZER_COMPLETE.md) | TrainFreeOptimizer 技术文档 |\n| [实验记录](./docs/EXPERIMENTS.md) | 当前主线实验与历史实验 |\n\n## Kode 集成\n\nTreeSkill 当前推荐使用 [Kode](https://github.com/shareAI-lab/Kode-Agent) 作为 Agent 前向引擎。Skill/program 在 Kode 的真实 agent loop 中执行（工具调用、文件操作、代码运行），ASO 根据执行结果修改 skill program。\n\n### 安装 Kode\n\n```bash\nnpm install -g @shareai-lab/kode\n```\n\n### 配置模型\n\n在 `~/.kode.json` 中配置模型（**不要提交此文件到 git**）：\n\n```json\n{\n  \"modelProfiles\": [\n    {\n      \"name\": \"my-model\",\n      \"modelName\": \"model-name\",\n      \"provider\": \"anthropic\",\n      \"baseURL\": \"https://your-api-endpoint\",\n      \"apiKey\": \"your-api-key\",\n      \"isActive\": true,\n      \"createdAt\": 1711500000000\n    }\n  ],\n  \"modelPointers\": {\n    \"main\": \"model-name\",\n    \"task\": \"model-name\",\n    \"compact\": \"model-name\",\n    \"quick\": \"model-name\"\n  },\n  \"defaultModelName\": \"model-name\"\n}\n```\n\n> 注意：`baseURL` 大写 URL，`apiKey` 直接写值（不支持环境变量引用）。\n\n### 验证\n\n```bash\nkode -p \"Say hello\" --output-format json --dangerously-skip-permissions\n```\n\n### 运行当前主流 Demo\n\n```bash\n# 默认：SealQA lifecycle\npython -m treeskill\n\n# 更接近真实 frontier 的 ASO 最小实验\npython -m treeskill sealqa-aso\n```\n\n### 架构\n\n```\nTreeSkill ASO 循环\n    ↓ 写入/更新 AGENTS.md / skills/\nKode CLI (前向引擎)\n    ↓ 加载 program / Skill → agent loop → 工具调用\n    ↓ 返回 JSON 结果\nTreeSkill 评估 (verify_fn / judge_fn / cached search)\n    ↓ 计算梯度 → 生成/修改/剪枝/合并 Skill\n    ↓ 回到顶部\n```\n\n## 实验结果\n\n| 实验 | 模型 | 结果 | 说明 |\n|------|------|------|------|\n| 论文分类 3 类 | Qwen3.5-4B + GLM-5 | 50% → 91.7% (+41.7%) | [详细报告](./docs/DEMO_PAPER_CLASSIFICATION.md) |\n| 论文分类 6 类 (split) | Qwen3.5-4B + GLM-5 | 10% → 86.7% (+76.7%) | auto-split 为 physics/cs/math |\n| SealQA lifecycle (cached search) | MiniMax-M2.7 | 16.7% → 100% | `root -> generate -> evolve -> prune -> merge` 全链路演示 |\n| SealQA ASO mini | MiniMax-M2.7 | 0% → 0% | 证明 skill 可增长，但无检索时不会自动补知识 |\n\n## 致谢\n\n- APO 优化引擎受 [Microsoft Agent-Lightning](https://github.com/microsoft/agent-lightning/) 启发\n- Agent Harness 架构受 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) 启发\n- Kode CLI 集成基于 [Kode Agent](https://github.com/shareAI-lab/Kode-Agent)\n- 论文分类数据集来自 [书生实战营 InternLM Tutorial](https://github.com/InternLM/Tutorial)\n"}