1. 项目概述一个能自我进化的AI编程伙伴如果你和我一样每天都要和代码打交道那你肯定遇到过这样的场景为了解决一个特定的Bug你花了半天时间查文档、搜Stack Overflow、试了各种方案最后终于搞定。但一个月后当类似的问题再次出现时你发现自己又得从头来一遍那些宝贵的“踩坑经验”好像都随着时间蒸发了。更让人头疼的是当你需要快速上手一个新框架或者实现一个复杂功能时面对海量的开源项目和最佳实践你常常感到无从下手不知道哪个方案最适合当前的项目。这就是我最初想构建Evolving Programming Agent的动机。它不是一个简单的代码补全工具也不是一个只会执行命令的脚本。你可以把它理解为一个拥有“成长型思维”的AI编程伙伴。它的核心目标很简单让每一次编程实践都成为下一次更高效、更精准工作的养料。这个智能体能够从你日常的编程任务中自动提取经验从优秀的GitHub开源项目中学习架构范式并将这些知识结构化地存储起来形成一个专属于你的、不断进化的“编程知识大脑”。想象一下当你下次说“帮我修复一个React组件的内存泄漏问题”时这个智能体不仅能调用大模型生成代码还能瞬间从你的知识库里调出之前处理过的类似案例、从开源社区学到的性能优化模式甚至结合当前项目的技术栈比如你用了Redux还是MobX给出最贴合上下文的解决方案。这背后是一套由统一协调大脑Orchestrator、**强制审查门控Review Gating和自动进化闭环Evolution Loop**构成的完整工程系统。2. 核心架构与设计哲学2.1 为什么是“编排架构”而非“单体Agent”在AI编程助手的早期探索中很多方案倾向于打造一个“全能型”的超级Agent期望它能理解一切、完成一切。但实际开发中这种思路很快会遇到瓶颈。代码生成、代码审查、知识归纳、信息检索这些任务对模型的能力要求、上下文长度和思考模式差异巨大。让同一个模型角色在“创造者”和“批判者”之间频繁切换不仅效率低下还容易产生逻辑混乱。因此Evolving Programming Agent 采用了清晰的多Agent编排架构。这就像组建一个高效的小型开发团队SKILL.mdOrchestrator扮演技术负责人或项目经理的角色。它不直接写代码而是负责“理解需求”意图识别、“拆解任务”工作流调度和“把控质量”最终验证。它是整个系统的指挥中枢。coder这是团队的核心开发工程师。它接收清晰的任务指令来自Orchestrator拆解后的子任务并严格按照预设的工作流指南如full-mode.md进行代码编写或修改。reviewer独立的代码审查专家。它的上下文与coder完全隔离确保审查的客观性。它拥有一份详细的审查清单专注于代码质量、安全性、性能和维护性拥有“一票否决权”。evolver团队的知识管理专员。在任务完成后它负责复盘从本次开发或修复过程中提炼出可复用的模式、遇到的陷阱及解决方案并将其结构化地存入知识库。retrieval资料检索员。在任务开始前并行运行根据任务描述快速从本地知识库和项目上下文中抓取相关信息为coder提供充足的“背景资料”。这种分工的核心优势在于“各司其职”和“强制隔离”。审查者不会因为参与了代码编写而“手下留情”知识归纳者可以专注于模式提取而非实现细节。整个流程通过一个Python实现的强制状态机来驱动确保任何任务都必须经历pending待处理→ in_progress进行中→ review_pending待审查→ completed完成/rejected拒绝的完整生命周期杜绝了代码未经审查就“偷偷”合并的情况。2.2 知识库系统的长期记忆与进化引擎如果说多Agent编排是系统的“骨架”和“肌肉”那么知识库就是它的“大脑”和“长期记忆”。这是实现“自我进化”的关键。这个知识库不是简单的代码片段堆积而是一个有分类、有生命周期、可量化评估的智能系统。2.2.1 多维分类与精准检索知识被精细地分为七大类确保检索时能精准命中experience(经验)存放优化、重构、性能调优等实战心得。tech-stack(技术栈)针对特定框架如React、Spring Boot的配置、惯用法和生态工具链。scenario(场景)对应“如何实现一个购物车”、“如何搭建用户权限系统”等功能性场景。problem(问题)专门收录各种Bug、报错信息及其根因分析和解决方案。testing(测试)测试模式、Mock技巧、覆盖率提升策略等。pattern(模式)架构设计模式、代码组织范式等高级抽象。skill(技能)通用的编程技巧、工具链使用心得等。当用户提出一个需求时retrieval会启动四级检索策略精确匹配直接匹配知识条目的name或triggers字段。部分匹配对查询词进行分词匹配部分触发词。模糊匹配对于中文可选用jieba分词进行更细粒度的匹配若不安装则回退到基于正则的简单分割。语义搜索如果配置了Embedding模型可将查询和知识内容转化为向量进行语义相似度匹配。最终系统会综合这四种方式的得分给出一个按相关性排序的知识列表供coder参考。2.2.2 动态生命周期管理知识并非只进不出。为了避免知识库臃肿和失效知识干扰系统引入了游戏化的“生命力”概念usage_count(使用计数)每次被成功检索并应用计数1。这代表了知识的“实用性”。effectiveness(有效性分数)一个介于0到1之间的浮点数。新知识默认0.5。每次被成功使用分数增加长期未被使用分数会随时间定期衰减。垃圾回收(GC)系统会定期运行清理任务将那些effectiveness分数低于阈值如0.1且长期未用的知识条目移入“存档”或直接删除。--dry-run参数可以让你预览哪些条目将被清理。可视化看板通过knowledge dashboard命令可以直观查看知识库的健康状况各类知识占比、高频使用条目、濒临失效条目等让你对智能体的“知识水平”一目了然。这种设计使得知识库成为一个动态的、自净化的生态系统真正有用的知识会被不断强化而过时或无效的知识则被自然淘汰。2.3 跨平台设计一次构建多处运行作为一个日常在多个IDE和AI编程工具间切换的开发者我深知环境割裂的痛苦。因此这个项目从设计之初就确立了跨平台的目标。它原生支持OpenCode、Claude Code、Cursor 和 OpenClaw四大平台。实现的关键在于路径抽象和配置检测。系统启动时会自动检测当前运行环境并设置对应的技能目录和知识库路径。例如在OpenCode中技能安装在~/.config/opencode/skills/下在Claude Code中则是在~/.claude/skills/。而全局知识库统一存放在~/.config/opencode/knowledge/实现了跨平台的知识共享。注意项目级知识库路径为$PROJECT_ROOT/.opencode/knowledge/这保证了不同项目的知识天然隔离避免A项目的特殊配置干扰B项目。统一的命令行接口scripts/run.py封装了所有差异你只需要记住一套命令无论在哪个平台下都能执行模式控制、知识库操作、GitHub学习等功能。安装脚本install.sh也提供了--all参数可以一键为所有检测到的平台安装必要组件。3. 从零开始安装、配置与初体验3.1 环境准备与一键安装开始之前请确保你的系统满足以下基本要求Python 3.8这是核心运行时环境。Git用于克隆仓库和后续的GitHub学习功能。可选jieba如果你需要处理中文查询安装它可以让模糊匹配更准确。安装过程非常简单项目提供了自动化脚本# 1. 克隆仓库到本地 git clone https://github.com/richenlin/evolving-programming-agent.git cd evolving-programming-agent # 2. 一键安装推荐 # 此脚本会自动检测你系统中已安装的AI编程平台OpenCode/Claude Code/Cursor并完成相应配置。 ./scripts/install.sh --all # 如果你在国内使用镜像加速安装可选依赖会快很多 ./scripts/install.sh --all --china安装脚本主要做了以下几件事为evolving-agent这个核心技能创建独立的Python虚拟环境位于~/.config/opencode/skills/evolving-agent/.venv/避免依赖冲突。将技能文件SKILL.md及各Agent定义复制到对应平台的技能目录。初始化全局知识库目录结构。安装必要的Python依赖如PyYAML用于解析配置。3.2 核心工作流初探你的第一次智能编程安装完成后你不需要记忆复杂的命令。在最常用的OpenCode或Claude Code中只需一个简单的命令即可唤醒你的智能体/evolve输入这个命令后系统会启动SKILL.md即Orchestrator主进程并进入协调状态。此时你就可以用最自然的语言向它下达任务了。场景一快速修复一个Bug假设你正在开发一个React应用遇到了一个“列表渲染时键值重复”的警告。输入指令直接在聊天框输入“帮我修复这个React列表key重复的警告。”幕后流程Orchestrator识别出“修复”关键词判定为Simple Mode任务。retrieval并行启动从知识库中搜索“React”、“key”、“warning”、“list rendering”等相关经验。Orchestrator分析当前文件拆解出“定位重复key”、“生成唯一key”、“替换并测试”等子任务。coder依据simple-mode.md工作流指南逐个执行子任务修改代码。reviewer在独立上下文中审查修改检查是否引入了新问题如性能下降、逻辑错误。审查通过状态变为completed。evolver被触发它分析整个修复过程提炼出“React列表渲染中稳定key的生成方法”这一经验自动存储到知识库的problem和skill分类下并打上react,frontend,warning等标签。场景二开发一个新功能现在你需要为一个后台管理系统添加一个“用户角色管理”页面。输入指令“创建一个用户角色管理页面包含角色列表、创建、编辑和权限分配功能。”幕后流程Orchestrator识别出“创建”关键词判定为Full Mode任务。它首先进行“顺序思考”输出一个feature_list.json将大功能拆解为①角色列表组件带分页和搜索、②创建角色模态框表单、③编辑角色页面、④权限分配树形组件、⑤对应的API服务层函数。coder根据这份清单并行或串行地开发各个子功能模块。每个模块开发完后都需经过reviewer的严格审查。全部完成后evolver会总结本次开发中涉及到的“表单验证模式”、“权限树组件设计”、“前后端数据交互规范”等存入知识库。场景三向开源项目学习你想借鉴一个优秀的UI库的组件设计。输入指令“学习这个仓库 https://github.com/shadcn/ui 的组件设计模式。”幕后流程Orchestrator将任务路由给github-to-knowledge模块。该模块克隆或读取仓库分析目录结构、组件定义文件如.tsx、样式文件和故事书Storybook。提取出诸如“复合组件模式”、“Props设计技巧”、“样式组合策略”等架构范式。将这些范式转化为结构化的知识条目存储到pattern和tech-stack分类中。未来当你需要设计一个类似的弹窗或表单组件时retrieval就能自动推荐这些学到的模式。3.3 统一命令行工具精细化管理你的智能体除了在IDE中交互项目还提供了功能强大的命令行工具run.py用于进行精细化的管理和运维。首先设置一下环境变量每个终端会话一次即可# 自动检测并设置技能目录路径 SKILLS_DIR$([ -d ~/.config/opencode/skills/evolving-agent ] echo ~/.config/opencode/skills || echo ~/.claude/skills)3.3.1 模式与状态管理你可以随时查看或切换智能体的工作模式。进化模式开启时evolver会在任务后自动运行关闭时则只执行编程任务不进行知识归纳。# 查看当前模式状态 python $SKILLS_DIR/evolving-agent/scripts/run.py mode --status # 完整初始化系统重置状态、检查依赖 python $SKILLS_DIR/evolving-agent/scripts/run.py mode --init # 开启进化模式 python $SKILLS_DIR/evolving-agent/scripts/run.py mode --on # 关闭进化模式纯执行模式 python $SKILLS_DIR/evolving-agent/scripts/run.py mode --off3.3.2 知识库的深度操作知识库是核心命令行提供了全方位的管理能力。# 1. 查询与搜索 # 查看知识库概览统计条目数、分类分布 python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge query --stats # 用关键词查询支持混合模式先关键词匹配再语义搜索 python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge query --trigger react, hooks --mode hybrid # 全文搜索内容字段 python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge query --search 内存泄漏 # 2. 生命周期维护 # 手动触发知识有效性衰减计算 python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge decay # 预览哪些低分条目将被清理安全检查 python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge gc --dry-run # 执行实际清理 python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge gc # 3. 备份与恢复 # 导出整个知识库为JSON python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge export --output my_knowledge_backup.json # 从JSON文件导入知识库--merge 策略可选 skip/overwrite/merge python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge import --input my_knowledge_backup.json --merge merge3.3.3 项目上下文感知智能体可以分析你当前的项目让建议更精准。# 检测当前目录项目的技术栈如识别出是ReactTypeScriptTailwind项目 python $SKILLS_DIR/evolving-agent/scripts/run.py project detect . # 存储针对当前项目的特定经验比如本项目特有的组件库使用规范 python $SKILLS_DIR/evolving-agent/scripts/run.py project store --tech react --pattern 本项目使用 company/ui 的Button组件时需额外传递sizecompact属性4. 高级使用与定制化指南4.1 理解并定制工作流智能体的行为由workflows/目录下的指南文件驱动。理解它们你就能预测甚至定制智能体的行为。simple-mode.md(简单模式)这是最常用的流程专注于“修复”。当你遇到Bug、报错或需要优化时触发。它的核心是“分析-定位-修复-验证”的快速闭环。我通常会在这里面加入一些针对特定语言如JavaScript的异步错误处理、Python的异常类型的排查模板让coder的思考更结构化。full-mode.md(完整模式)用于功能开发。其核心是“需求拆解-模块设计-并行开发-集成测试”。这个工作流强调前期设计sequential-thinking产出feature_list.json这对于保持代码结构清晰至关重要。你可以根据团队规范在这里定制代码风格检查、单元测试生成等环节的触发条件。consult-mode.md(咨询模式)用于解答“如何做”、“为什么”这类问题。它首先进行知识检索然后直接由Orchestrator组织答案。如果分析发现需要实际修改代码它会自动建议并切换到Simple Mode。你可以在这里丰富“解释风格”比如要求它多用类比、附带代码示例等。定制示例假设你的团队强制要求在每次提交前运行eslint和prettier。你可以在full-mode.md的“最终验证”阶段前插入一个自定义步骤### 5. 代码风格与质量检查 - 请对修改过的所有文件运行 npm run lint:fix (或 yarn eslint --fix)。 - 接着运行 npm run format (或 yarn prettier --write). - 检查终端输出确保没有错误。如果有无法自动修复的lint错误请说明原因并手动修正。这样每次智能体完成开发后都会自动帮你执行团队规范。4.2 配置多模型路由以优化成本与效果不同的任务适合不同的模型。让GPT-4去审查一个简单的语法错误是杀鸡用牛刀而让轻量级模型去设计复杂架构又力不从心。MODEL-CONFIG.md文件允许你为不同Agent角色分配不同的模型提供商和模型。# 示例配置 (位于 evolving-agent/config/models.yaml) model_routing: orchestrator: provider: openai model: gpt-4-turbo-preview # 需要较强的理解和规划能力 temperature: 0.1 # 低随机性保证决策稳定 coder: provider: anthropic model: claude-3-opus-20240229 # 需要强大的代码生成能力 temperature: 0.2 reviewer: provider: openai model: gpt-4 # 审查需要极高的严谨性和深度 temperature: 0.0 # 零随机性审查标准必须一致 evolver: provider: openai model: gpt-3.5-turbo # 知识归纳任务相对简单使用性价比高的模型 temperature: 0.3 retrieval: provider: local # 检索任务可能使用本地Embedding模型如all-MiniLM-L6-v2 model: sentence-transformers/all-MiniLM-L6-v2配置心得Orchestrator和Reviewer值得用最好的模型如GPT-4。前者决定了任务拆解是否合理后者是代码质量的最后防线。这里的投资回报比最高。Coder可以根据任务复杂度灵活配置。日常bug修复用Claude 3 Sonnet或GPT-3.5 Turbo可能就够了大型功能开发再切换到更强的模型。Evolver和Retrieval是降低成本的关键。知识归纳是总结性工作语义搜索有专用轻量模型完全可以使用低成本或本地模型长期下来能节省大量token消耗。设置API密钥在对应的平台配置文件如OpenCode的设置或环境变量中设置好OPENAI_API_KEY、ANTHROPIC_API_KEY等。系统会自动读取。4.3 知识库的维护与优化策略一个健康的知识库需要主动维护。以下是我在实践中总结的几个策略1. 定期运行“知识衰减”与“垃圾回收”就像整理你的书桌一样需要定期清理。我通常会在每周一早上手动执行一次python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge decay python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge gc --dry-run查看--dry-run的结果确认没有误伤重要但近期未用的知识比如一些季节性功能的代码模式然后再执行真正的清理。2. 主动“喂养”高质量知识智能体的进化不仅靠自动提取你也可以主动“教”它。当你解决了一个特别经典或复杂的问题后可以显式地保存经验# 通过管道传入内容并自动归纳存储 echo 问题React useEffect中无限循环。原因依赖数组包含每次渲染都会变化的对象。解决方案使用useMemo缓存对象或将对象属性拆解到依赖数组中。 | python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge summarize --auto-store --category problem --name React useEffect无限循环排查你也可以直接编辑知识库的JSON文件但更推荐用命令行工具因为它会帮你处理ID生成、时间戳等元数据。3. 利用Dashboard进行知识审计定期运行knowledge dashboard关注“僵尸知识”effectiveness分数持续低于0.2的条目。考虑是彻底删除还是通过手动“使用”一次来激活它。“热门知识”usage_count最高的条目。这反映了你日常开发中最常遇到的问题或模式可以思考是否能将这些知识进一步抽象形成团队内的标准工具函数或组件。分类均衡如果problem类知识远多于pattern类可能说明你的开发模式更偏向“救火”而非“预先设计”。可以有意地多让智能体学习一些架构模式pattern知识。5. 常见问题与故障排查在实际使用中你可能会遇到一些典型问题。这里记录了我踩过的坑和解决方案。5.1 安装与启动问题问题1安装脚本执行失败提示权限不足或路径错误。排查首先确认你是否在项目根目录下执行脚本。使用ls -la scripts/install.sh检查文件是否存在且有执行权限x。解决如果没有执行权限运行chmod x scripts/install.sh。如果提示python命令找不到请确保Python 3.8已正确安装并加入PATH。可以尝试使用python3代替或者修改脚本首行的shebang。问题2在IDE中输入/evolve没有反应或提示“命令未找到”。排查这说明技能没有正确安装到对应平台的目录。运行python $SKILLS_DIR/evolving-agent/scripts/run.py info查看环境信息确认skill_path是否正确指向了你的IDE如OpenCode的技能目录。解决可以手动将evolving-agent/文件夹复制到正确的技能目录下如~/.config/opencode/skills/然后重启你的IDE。5.2 任务执行流程问题问题3任务一直卡在pending或in_progress状态没有进展。排查这通常是由于某个Agent尤其是coder的执行超时或出错导致的。首先检查IDE的Agent调用日志看是否有明显的错误信息如API调用失败、上下文超长。解决检查API密钥和网络确认你配置的模型提供商如OpenAI、Anthropic的API密钥有效且额度充足。简化任务如果任务描述过于复杂可能导致Orchestrator拆解出太多子任务。尝试将大任务拆分成更小的、清晰的指令。检查工作流文件确认workflows/下的simple-mode.md或full-mode.md文件内容完整没有语法错误导致Agent指令解析失败。问题4reviewer总是拒绝reject代码但反馈的意见很模糊。排查Reviewer的审查标准定义在agents/reviewer.md和references/下的审查清单中。可能是审查标准过于严格或者与当前项目的小众技术栈不匹配。解决定制审查清单根据你的项目实际情况编辑references/目录下的文件。例如如果你的项目是Python Django后端可以弱化对前端ESLint规则的检查强化对数据库查询N1问题、序列化器性能的检查。调整Reviewer模型尝试为reviewer角色换用逻辑更清晰、解释更详细的模型如GPT-4并在提示词中要求它“给出具体的、可操作的修改建议”。5.3 知识库相关问题问题5感觉智能体没有用到我之前存储的知识每次都在“从零开始”。排查首先运行knowledge query --stats确认知识条目已成功存入。然后在下次执行任务时观察retrieval Agent的日志输出如果平台提供看它是否成功检索并附带了相关知识。解决优化触发词知识条目的triggers字段是关键。确保你存储知识时设置了足够多、足够贴切的关键词。例如一个关于“Python连接MySQL超时”的知识触发词应包括[“python”, “mysql”, “connection”, “timeout”, “pymysql”, “数据库连接”]。检查检索模式默认是混合模式hybrid。如果你没有安装语义搜索所需的sentence-transformers库系统会回退到关键词匹配。确保你的查询描述中包含了触发词里的关键词。知识分类确保知识被存入了正确的分类。一个关于“使用Redis缓存用户会话”的知识更适合放在pattern或tech-stack下而不是problem下。问题6从GitHub学习时提取到的模式很空洞比如只有“使用了函数式组件”没有实际价值。排查github-to-knowledge模块的提取逻辑依赖于对仓库代码结构的解析。如果仓库本身文档不全、结构混乱或者提取的配置不够具体就容易得到泛化的结果。解决指定学习目标不要笼统地说“学习这个仓库”。尝试更具体的指令如“学习这个仓库shadcn/ui中lib/components/ui/button.tsx文件里关于variant和size属性是如何通过cva库组合生成CSS类的模式。”事后人工提炼自动提取后使用knowledge query查看提取结果然后手动编辑对应的知识条目补充更详细的示例代码、适用场景和注意事项。智能体的“学习”能力是一个辅助核心还是需要你的经验来把关和提炼。5.4 性能与成本优化问题7处理复杂任务时API调用次数多token消耗大成本高。策略善用本地知识库这是降低成本最有效的方式。一个检索到的、精准的本地知识条目可能节省掉向大模型描述复杂背景的数百个token。模型路由配置如前文所述为Evolver和Retrieval配置低成本模型。对于简单的代码补全任务也可以尝试为Coder配置gpt-3.5-turbo-instruct这类更便宜的补全模型。精简上下文检查工作流文件避免在提示词中携带过多不必要的历史对话或文件全文。利用retrieval来提供精准的上下文而不是把所有东西都塞进主提示词。关闭进化模式在完成一些简单的、一次性的任务时使用mode --off临时关闭进化模式避免不必要的知识归纳步骤。经过几个月的深度使用和迭代这个Evolving Programming Agent已经从一个实验性的想法变成了我日常开发中不可或缺的“副驾驶”。它最大的价值不在于替代我思考而在于将我的经验、从开源世界汲取的养分以及项目本身的规范固化成一个可检索、可复用、可进化的数字资产。每一次与它的交互不仅是完成当前任务更是在为未来所有类似的任务铺路。这种“越用越聪明”的体验正是智能编程工具应该前进的方向。如果你也厌倦了重复的搜索和试错不妨试试构建或使用这样一个系统开始积累属于你自己的编程知识复利。