1. 项目概述一个为本地Pi环境设计的指令自进化工具如果你在深度使用Pi这个本地AI开发环境并且手头积累了不少.pi/skills/下的技能文件、AGENTS.md这样的代理描述或者各种.md格式的提示词模板你可能会遇到一个共同的痛点这些指令文件一旦写好就变成了静态的“死文档”。随着项目迭代和需求变化你只能手动去猜测哪里需要优化或者凭感觉去调整几个关键词效率低下且缺乏依据。pk-pi-hermes-evolve这个Pi原生扩展包就是为了解决这个问题而生。它借鉴了Nous Research团队在Hermes Agent Self-Evolution项目中提出的核心思想并将其适配到了Pi的本地工作流中。简单来说这个工具能让你指定的一个指令文件比如一个技能描述SKILL.md实现“自我进化”。它不会直接覆盖你的原文件而是通过一个严谨的“生成-评估-选择”循环产生多个优化后的候选版本并生成一份详细的评估报告供你审阅。整个过程完全在本地运行你可以把它理解为一个专为文本指令优化的、自动化且可审查的“提示词调优助手”。无论你是想提升一个代码审查技能的准确性还是想让一个总结代理的输出更简洁都可以通过它来系统性地寻找更优的指令表达。2. 核心设计思路与架构解析2.1 灵感来源与本地化适配这个项目的核心灵感来源于Nous Research的hermes-agent-self-evolution。原项目旨在让AI智能体通过自我反思和迭代来进化其能力是一个相对庞大和复杂的系统。pk-pi-hermes-evolve所做的是提取其“Phase 1”的精髓——即针对静态指令文本的进化流程——并将其深度整合到Pi的生态中。注意这里有一个关键的设计哲学转变。原版Hermes可能更偏向于一个独立的、中心化的智能体进化平台。而本工具则完全遵循Pi的“扩展”哲学轻量、无侵入、以会话和项目上下文为核心。它不试图接管你的项目而是作为一个增强工具在你需要时提供智能化的辅助。这种适配体现在几个方面状态管理进化过程产生的所有中间文件、候选版本和报告都严格存放在项目目录下的.pi/hermes-self-evolution/路径中。这符合Pi扩展将生成物隔离在特定目录下的最佳实践避免了污染项目源码。上下文利用工具可以直接从你当前的Pi会话历史session.jsonl中提取任务示例作为评估数据集的一部分。这意味着进化过程可以紧密贴合你最近的实际工作场景让优化更有针对性。交互模式它提供了两种使用方式通过/evolve命令进行交互式操作以及通过self_evolve_artifact工具让AI模型在对话中主动调用。这覆盖了从人工驱动到模型驱动的不同工作流。2.2 混合后端架构灵活性与功能性的平衡为了在易用性和功能强大之间取得平衡项目采用了独特的混合后端架构。这是理解其能力边界的关键。TypeScript后端 这是默认且始终可用的后端。它的实现逻辑相对直接通过Pi的子进程调用功能模拟一个本地的“代理进化循环”。具体来说它会调用本地的LLM通过Pi配置的模型让LLM扮演“候选生成器”和“裁判”的角色进行多轮迭代。这个后端的优点是零额外依赖安装即用并且与Pi的TypeScript运行时环境无缝集成执行效率高。Python后端可选 这是功能更强大的进阶选项。当你的系统安装了Python和DSPy库后工具会自动或手动切换到此后端。DSPy是一个用于构建基于语言模型应用的框架它提供了如dspy.GEPA生成-评估-优化-调整等高级编程范式。使用Python后端意味着更强大的合成能力可以利用DSPy的模块如dspy.Predict,dspy.ChainOfThought更结构化地生成评估任务和候选指令。潜在的GEPA路径如果安装的DSPy版本支持dspy.GEPA工具会尝试使用这一更接近原版Hermes理念的优化算法进行候选生成。未来的扩展性为集成更复杂的评估器如基于代码执行的测试或基准测试框架奠定了基础。后端选择策略 工具提供了auto默认、python、typescript三种模式。在auto模式下它会自动检测Python环境和DSPy是否可用优先使用功能更强的Python后端否则优雅地降级到TypeScript后端。这种设计确保了工具在各种用户环境下的可用性。2.3 进化循环拆解从指令到优化候选整个自进化过程可以被抽象为一个标准化的循环无论后端如何实现其逻辑内核是一致的。理解这个循环你就掌握了工具的核心工作原理。目标选定与数据准备输入你指定一个需要进化的指令文件Artifact。数据集生成工具会围绕这个指令生成一个小型的评估数据集。数据来源可以是合成的Synthetic让LLM根据指令内容自动生成一系列相关的输入-输出示例对。会话的Session从你最近的Pi会话历史中提取与该指令可能相关的对话记录作为示例。混合的Mixed结合以上两者。数据集划分生成的数据集会按比例默认约50%/20%/30%划分为训练集Train、验证集Validation和保留集Holdout。这是一个关键的质量控制步骤防止过拟合。候选生成与迭代分析弱点基于训练集让LLM分析当前指令版本在应对这些示例时可能存在的不足例如指令模糊、缺少约束条件、格式要求不明确等。生成候选针对分析出的弱点LLM会生成若干个修改后的指令候选版本。在PythonDSPy后端这个过程可能涉及GEPA或MIPRO等算法进行多轮优化。代理评分与选择裁判评估使用另一个或同一个LLM作为“裁判”让它在验证集上对原始指令和所有候选指令进行盲评打分。评分标准通常包括指令的清晰度、执行结果的准确性、完整性等。优胜者选出综合评分选出表现最佳的候选指令。最终评估与报告生成保留集验证使用从未参与过候选生成和中间评分的保留集对原始指令和最佳候选指令进行最终评估。这确保了评估结果的公正性和泛化能力。生成报告将所有过程数据、评分详情、候选版本内容以及最终对比结果整理成一份结构化的report.md文件并连同所有相关文件保存到时间戳目录下。整个过程中你的原始文件original.md会被完整拷贝并保存绝不会被自动修改。所有的变化都体现在新生成的best-candidate.md和candidates/目录下的文件中等待你的人工审查和决策。3. 详细使用指南与实操要点3.1 环境准备与安装安装过程非常简洁这得益于Pi优秀的包管理机制。你有两种主要安装方式全局安装推荐用于频繁使用pi install npm:pk-pi-hermes-evolve执行后/evolve命令和self_evolve_artifact工具将对所有Pi项目可用。项目本地安装用于隔离依赖pi install -l npm:pk-pi-hermes-evolve这会将包安装到当前项目的.pi/packages/目录下仅在本项目内生效适合在团队协作或特定项目中管理依赖。启用Python后端可选但推荐如果你希望使用功能更强大的DSPy路径需要额外步骤# 1. 确保已安装Python3.8和pip # 2. 进入包内的Python后端目录 cd $(pi package path pk-pi-hermes-evolve)/python_backend # 如果上一步找不到也可以先找到全局包路径通常在 ~/.pi/packages/ 下 # 3. 安装Python依赖 pip install -e .安装后工具在auto模式下会自动检测并使用此后端。实操心得在开发机上我通常选择全局安装以方便随时调用。但在为某个具体项目例如一个专门的智能体项目构建优化流水线时我会采用项目本地安装并确保Python后端也被安装这样能保证环境的一致性和可复现性。记得用pi package list来查看已安装的包。3.2 通过命令交互式使用/evolve命令是与工具交互最直观的方式。基础用法/evolve不带任何参数运行工具会交互式地列出当前项目下可能的目标文件如.pi/skills/下的所有SKILL.md或根目录的AGENTS.md等让你用光标选择。/evolve path/to/file.md直接指定要进化的文件路径。/evolve last快速打开最近一次进化运行生成的报告文件方便回顾。交互流程详解当你运行/evolve .pi/skills/code-review/SKILL.md后会经历以下对话步骤确认目标工具会显示即将进化的文件路径和预览内容请你确认。设定进化目标你需要用自然语言描述希望改进的方向。例如“让代码审查的反馈更结构化优先指出安全性问题并给出具体的代码修改建议。” 这个目标会引导后续的生成和评估。选择评估数据源mixed混合结合合成任务和会话历史。这是最常用且平衡的选择既能覆盖通用场景又能结合你的实际使用习惯。synthetic合成完全由LLM生成示例。适合全新编写的技能或没有历史会话数据时。session会话仅从历史会话中提取。适合优化一个已经过初步使用、但希望其更贴合你个人工作流的技能。选择后端通常选择auto即可。如果你明确想测试某个后端可以在此指定python或typescript。开始运行确认后工具开始执行进化循环。你会在Pi的会话中看到进度提示如“正在生成数据集...”、“正在进行第N轮迭代...”、“正在生成最终报告...”。整个过程耗时取决于指令复杂度、数据集大小和模型速度通常需要几十秒到几分钟。3.3 通过工具让模型驱动进化self_evolve_artifact工具的存在体现了Pi“对话即编程”的理念。你可以在与AI模型的自然对话中直接要求它对某个指令进行优化。典型使用场景你在和Pi讨论如何改进一个“写作助手”技能对话可能是这样的你“我觉得当前这个写作助手的回复有点啰嗦而且不太会举例。你能帮我优化一下它的指令吗”Pi“当然可以。我可以使用self_evolve_artifact工具来分析并优化.pi/skills/writing-assistant/SKILL.md文件。您希望我主要从哪个方面进行优化是精简度、举例能力还是其他方面”你“主要优化精简度和举例的相关性同时保持友好的语气。”Pi“好的我将以‘提升回复的精简度增强举例的相关性和针对性同时保持友好语气’为目标使用混合数据源来进化该技能文件。”此时Pi会在后台调用该工具执行与/evolve命令类似的流程并将最终的报告和最佳候选文件路径返回给你。这种方式将进化过程无缝嵌入到了你的工作流中感觉更像是AI在主动提供协助。高级参数goldenTaskId这是一个非常重要的功能用于确保评估的可复现性和跨周期可比性。在工具调用时你可以指定一个goldenTaskId例如使用 self_evolve_artifact 在 .pi/skills/summarize/SKILL.md 上goldenTaskId 设为 “summarize-v1-core”。当提供此ID后工具会在生成数据集时将**验证集Validation Split**标记为一个“黄金数据集”。这个数据集会被保存下来。未来无论你何时、以何种参数甚至使用不同版本的进化工具再次运行进化只要指定相同的goldenTaskId它就会使用同一套“黄金验证集”来评分。这让你可以科学地比较不同优化策略或不同时期进化结果的有效性避免了因每次随机生成测试数据而带来的评估波动。4. 输出结果分析与后续操作4.1 理解输出目录结构每次进化运行都会在.pi/hermes-self-evolution/runs/下生成一个以时间戳和文件名命名的独立目录。理解其中每个文件的作用能帮助你高效地审查结果。.pi/hermes-self-evolution/runs/20240520_142310-code-review-SKILL/ ├── original.md # 原始文件的完整拷贝 ├── best-candidate.md # 评分最高的候选指令 ├── report.md # **最重要的文件**包含完整评估报告 ├── manifest.json # 本次运行的元数据目标、参数、后端等 ├── dataset.json # 生成的数据集包含train/val/holdout划分 └── candidates/ # 所有生成的候选版本 ├── candidate-1.md ├── candidate-1.json # 该候选的元信息和评分细节 ├── candidate-2.md └── ...report.md报告精读报告是决策的核心。一份典型的报告会包含以下章节执行摘要一目了然地展示原始指令和最佳候选指令在保留集上的最终得分对比。进化配置回顾本次运行的目标、数据源、后端等参数。数据集统计展示生成的示例数量及划分情况。候选生成分析列出LLM分析出的原始指令主要弱点。详细评分对比一个表格对比原始指令和每个候选指令在验证集各项指标如清晰度、准确性上的得分。保留集最终评估证明最佳候选指令优势的关键部分使用未参与训练的数据进行公平比较。候选指令内容完整展示best-candidate.md的内容。建议与下一步工具可能会给出是否采纳的建议但最终决定权在你。4.2 人工审查与决策流程工具严格遵循“人类在环”原则所有更改都需要你手动确认。审查时我通常会遵循以下步骤快速浏览报告摘要首先看最终得分提升是否显著例如从7.5分提升到8.8分。如果提升微小如0.2分可能需要权衡修改带来的收益是否值得。仔细阅读“弱点分析”这部分价值极高。LLM指出的问题往往能给你带来新的视角即使你不采纳具体的候选修改这些分析本身也能指导你手动优化。对比original.md和best-candidate.md使用diff工具或并排查看逐行审视变化。关注结构性变化是否增加了步骤、分点了结构更清晰了吗具体性变化模糊的表述如“好好检查”是否被替换为具体的标准如“检查输入验证、错误处理和资源泄露”约束条件是否增加了之前忽略的限制如“输出请使用Markdown表格格式”风格变化语气、措辞是否符合你的期望查看候选示例如果对最佳候选不满意可以浏览candidates/目录下的其他版本或许有不同优化方向的方案。做出决定采纳将best-candidate.md的内容复制并替换原文件。混合采纳从多个候选版本中选取优点组合成你自己的新版本。仅采纳思路根据报告中的分析自己重新撰写指令。放弃认为本次进化未产生有价值的结果保持原状。避坑技巧不要盲目相信分数。有时LLM裁判会偏好更冗长、更“安全”的指令但这可能不符合你追求简洁高效的目标。务必结合你自己的判断。我常把分数看作一个筛选器帮我从多个候选版本中快速缩小范围但最终选择哪条“鱼”还得自己“尝”。5. 高级功能与开发集成5.1 Sokoban基准测试脚手架项目近期引入的Sokoban推箱子基准测试脚手架标志着它从单纯的指令优化工具向一个具备实证评估能力的框架演进。这个功能对于严肃的智能体开发或提示工程研究非常有用。它解决了什么问题以往优化指令后我们只能依赖LLM的“代理评分”来判断好坏这是一种“模拟评估”。Sokoban基准测试则提供了“真实评估”的可能。通过让智能体实际玩一个已知的游戏推箱子我们可以客观地测量指令修改前后智能体解决实际问题的能力变化如通关率、步骤效率。如何使用这个脚手架脚手架脚本位于scripts/sokoban_benchmark.py它提供了一套标准化的工作流初始化一个测试运行python scripts/sokoban_benchmark.py init \ --run-id my-experiment \ --training-levels level-1 level-2 level-3 \ --heldout-level level-final这会为名为my-experiment的运行创建一个目录结构并指定哪些关卡用于“训练”进化过程可以参考哪个关卡用于“保留测试”最终评估。准备一次尝试python scripts/sokoban_benchmark.py prepare-attempt \ --run-id my-experiment \ --arm baseline \ --attempt 1这会在对应目录生成本次尝试所需的所有文件特别是prompt.md给AI的指令和input-skill.md当前要测试的技能文件。对于improvement分支它可能会调用进化工具先优化技能。执行与记录你或AI模型根据prompt.md执行任务玩推箱子关卡然后将结果填写到生成的result.json中。完成后运行python scripts/sokoban_benchmark.py record-attempt \ --run-id my-experiment \ --arm baseline \ --attempt 1脚本会验证结果格式并更新状态。分析结果python scripts/sokoban_benchmark.py analyze --run-id my-experiment最终脚本会汇总“基线组”和“改进组”在多次尝试后的表现特别是在保留关卡上的表现给出一个量化的性能对比报告。实操心得这个脚手架目前还处于“半自动化”状态需要人工或通过其他自动化工具如浏览器自动化来执行prompt.md中的任务并记录结果。但它定义了清晰的接口输入技能、输出结果和数据结构为未来实现全自动化评估打下了坚实基础。对于团队来说可以用它来严谨地验证某个技能优化是否真的带来了任务完成度的提升。5.2 使用Ralph循环进行自动化进化对于希望将进化过程集成到CI/CD流水线或进行大规模自动化实验的开发者项目提供了与ralph一个AI工作流引擎集成的示例脚本scripts/ralph_otel.py。这是什么你可以把它理解为一个“超级自动化脚本”。它读取一个定义好的任务文件hermes_parity_task.json然后自动执行一系列复杂的步骤例如检查代码库状态、运行进化命令、验证产出物、判断任务是否成功并根据结果决定下一步重试或继续。关键特性可观测性通过OpenTelemetry集成你可以将整个循环的每一步如ralph.run/,loop.step,model.infer的追踪数据发送到可观测性平台如Jaeger可视化执行过程和性能瓶颈。确定性检查在“裁判”环节它可以执行一些针对代码库的确定性检查例如验证生成的执行轨迹是否合规、验证集支持是否已实现等确保进化的产出符合项目标准。面向仓库的交付整个循环围绕一个代码仓库repo进行确保所有变更和产出物都在版本控制之下。基本用法cd /path/to/your/project python scripts/ralph_otel.py \ --task-file scripts/tasks/hermes_parity_task.json \ --repo . \ --model your-preferred-model \ # 例如: zai/glm-5.1 --telemetry-export console # 在控制台输出追踪信息运行后ralph会接管控制权按照任务定义一步步执行并将中间产物保存在.pi/hermes-self-evolution/ralph-runs/目录下。这对于实现“每晚自动运行进化并生成报告”的自动化流水线非常有用。6. 常见问题、局限性与未来展望6.1 常见问题排查在实际使用中你可能会遇到以下问题1. 运行/evolve命令无反应或报错“未找到命令”。原因包未正确安装或Pi会话未刷新。解决首先运行pi package list确认pk-pi-hermes-evolve在列表中。如果不在重新安装。如果在尝试退出当前Pi会话并重新进入或者运行pi reload重新加载扩展。2. 进化过程非常缓慢或内存占用很高。原因生成的数据集过大或使用的LLM模型本身较慢、消耗资源多。解决检查并调整Pi配置中使用的模型可以尝试换用更轻量的模型进行进化评估。在目标描述中可以尝试要求生成“一个包含5到10个典型示例的紧凑评估集”。虽然工具本身有控制但明确的指令有助于LLM生成更精炼的数据。如果使用Python后端且安装了重型ML库确保你的机器资源充足。3. 生成的候选指令看起来和原版差别不大或优化方向偏离目标。原因进化目标描述不够具体评估数据集未能覆盖关键场景LLM作为裁判的评判标准与你的期望有偏差。解决细化目标将“让它更好”改为“专注于减少指令中的开放性词汇将‘可能’、‘一些’等替换为具体数字或布尔条件”。提供种子示例在运行进化前可以手动在会话中与Pi进行几次你期望的技能交互这些高质量的历史记录会被session数据源采集从而引导进化方向。人工干预数据集高级用户可以直接修改dataset.json文件增删或修改示例然后重新运行评分环节但这需要一定的技术能力。4. 切换到backend: python时失败回退到 TypeScript。原因Python路径未找到或DSPy库未安装。解决设置环境变量PI_HERMES_EVOLVE_PYTHON指向你的Python解释器绝对路径。进入包的python_backend目录运行pip list | grep dspy确认DSPy已安装。如果没有运行pip install -e .会安装所需依赖。6.2 当前已知局限理解工具的边界能帮助你将其用在正确的场景避免不切实际的期望。非代码进化核心优化对象是文本指令Markdown文件。它不会重构你的Python/TypeScript函数或类。对于代码进化需要更专门的工具。模拟评估为主尽管引入了Sokoban基准测试的概念但核心的进化循环仍严重依赖LLM作为“代理裁判”进行模拟评分。这种评估与真实世界任务的表现可能存在差距。无自动合并工具严格遵循“不自动覆盖”原则。每次优化后都需要人工审查和手动合并这虽然安全但也增加了操作成本。性能开销每一轮进化都涉及多次LLM调用生成数据集、多轮迭代、评分等对于长指令或大数据集时间和token消耗是可观的。6.3 生态定位与未来可能pk-pi-hermes-evolve在Pi的生态中填补了一个重要的空白本地化、可审查的AI工作流组件优化工具。它不像云端SaaS那样需要数据出境也不像一些重型框架那样需要复杂的配置。它就是一个“即插即用”的Pi扩展在你觉得某个技能或提示词不够好用的时候提供一个系统化的改进思路。从项目路线图来看它正在从“指令优化器”向“智能体能力评估框架”演进。Sokoban基准和Ralph循环的集成展示了团队对构建闭环、可度量优化系统的野心。未来如果能够集成更丰富的真实环境评估如单元测试通过率、API调用成功率并实现更平滑的“审查-应用”工作流它的实用性将会再上一个台阶。对我个人而言这个工具最大的价值在于它将提示词优化的过程从“艺术”部分地转向了“工程”。它提供了一个结构化的框架来提出问题、生成假设、测试验证并生成报告。即使最终不采用它生成的候选指令整个分析报告本身也常常能给我带来关键的启发让我对自己编写的指令有更深刻的认知。在本地AI智能体开发日益复杂的今天这类提升基础组件质效的工具其重要性只会越来越高。