Evolving Programming Agent

持续学习、自我进化的 AI 编程智能体

EN: A continuously learning, self-evolving AI programming agent with orchestrated coding, review gating, and knowledge accumulation.

Evolving Programming Agent 是一个模块化的 AI 编程系统。它不仅仅是一个代码生成工具，更是一个能够从 GitHub 学习最佳实践、从日常任务中积累经验、并不断优化自身能力的"成长型"智能体。

EN: This project is a modular AI engineering system. Beyond code generation, it learns from GitHub repositories, accumulates practical experience from daily tasks, and continuously improves through an evolution loop.

🚀 核心特性

EN: Key capabilities include orchestrator-driven workflow, strict review gating, DAG-based parallel execution, mandatory post-task evolution, and role-specific model routing.

🧠 统一协调大脑: 上下文感知的意图识别 + 任务调度，先检查活跃会话再做关键词匹配
🔒 Python 强制状态机: pending → in_progress → review_pending → completed/rejected，coder 不能自审、不能跳过 reviewer，支持幂等转换和审计日志
🔄 自动进化闭环: 编程任务结束后自动提取经验（Bug 修复、架构模式）并存入知识库
🔍 四级知识检索: 精确匹配 → 部分匹配 → 模糊匹配（可选 jieba 中文分词）→ 语义搜索（可选 embedding），按综合相关性排序
📉 知识库生命周期: usage_count 自动追踪 → effectiveness 定期衰减 → gc 清理低分条目 → dashboard 可视化
📚 GitHub 学习引擎: 主动分析 GitHub 开源项目，提取架构范式和代码规范，转化为可复用的技能
🧩 多项目知识隔离: 全局知识 ~/.config/opencode/knowledge/ + 项目级知识 $PROJECT_ROOT/.opencode/knowledge/，检索时合并去重
🌐 跨平台支持: OpenCode（原生多 agent）、Claude Code（Task tool 调度）平台

📋 系统要求

必需依赖

依赖	版本要求	说明
Python	>= 3.8	项目运行环境
PyYAML	>= 6.0,< 7.0	解析 SKILL.md frontmatter

可选依赖

依赖	版本要求	说明
Git	>= 2.0	GitHub 仓库学习功能
jieba	>= 0.42, < 1.0	中文分词（不安装则 fallback 到正则分割）
sentence-transformers	>= 2.2	语义搜索 embedding（不安装则 fallback 到关键词模式）

🏗️ 架构概览

Evolving Programming Agent 采用 多 Agent 编排架构，SKILL.md 主进程即 orchestrator，直接调度子 agent 完成编程闭环。Python 状态机强制校验所有状态转换，支持幂等转换和审计日志：

EN: SKILL.md acts as the orchestrator (main process), directly dispatching @coder, @reviewer, @evolver, and @retrieval in a hard-gated loop. A Python state machine enforces all transitions with idempotency and audit logging.

用户输入
    ↓
SKILL.md (orchestrator 主进程)
    ├─ 步骤1: 初始化
    ├─ 步骤2: 意图识别
    ├─ 步骤3: 编程调度闭环
    │   ├─► @retrieval (并行知识预取)
    │   ├─► @coder (按工作流执行，可并行多个)
    │   ├─► @reviewer (独立上下文审查)
    │   └─► @evolver (全部完成后条件执行)
    ├─► GitHub学习 → github-to-knowledge
    └─► 知识归纳 → knowledge-base

核心组件

组件	目录	职责
evolving-agent	`evolving-agent/`	Orchestrator 主进程。初始化、意图识别、子 agent 调度、最终验证
agents	`evolving-agent/agents/`	子 agent 角色定义（coder/reviewer/evolver/retrieval）
programming-assistant	`evolving-agent/modules/programming-assistant/`	@coder 工作流指南（simple-mode/full-mode/consult-mode）
github-to-knowledge	`evolving-agent/modules/github-to-knowledge/`	学习引擎。从 GitHub 提取知识存入知识库
knowledge-base	`evolving-agent/modules/knowledge-base/`	统一知识库。存储、查询、归纳知识

📦 安装

EN: Clone the repository and run the installer to set up all components for OpenCode/Claude Code/Cursor.

快速安装

# 克隆仓库
git clone https://github.com/richenlin/evolving-programming-agent.git
cd evolving-programming-agent

# 安装所有组件 (支持 OpenCode, Claude Code, Cursor)
./scripts/install.sh --all

Python 环境配置

每个 Skill 拥有独立的虚拟环境，避免依赖冲突：

# evolving-agent 的虚拟环境
~/.config/opencode/skills/evolving-agent/.venv/

# 仅 evolving-agent 使用共享虚拟环境

🎮 快速开始

EN: Start with /evolve, then describe tasks in natural language. Programming requests are routed to the orchestrator pipeline automatically.

1. 启动协调器

推荐使用统一入口命令 /evolve 启动会话：

/evolve

系统将初始化环境并进入协调态。

2. 执行编程任务

直接用自然语言描述需求，orchestrator 主进程自动识别意图并调度子 agent：

"帮我用 React 写一个登录页面" "修复这个 CORS 跨域问题" "重构这个组件，提高可维护性"

EN examples: "Build a login page with React" "Fix this CORS issue" "Refactor this component for maintainability"

3. 从 GitHub 学习

让智能体学习优秀的开源项目：

"学习这个仓库 https://github.com/shadcn/ui"

系统将自动提取组件设计模式，并在后续编程中复用。

4. 显式保存经验

虽然系统会自动进化，您也可以显式要求保存：

"记住这个解决方案，以后遇到类似问题直接用" "保存这个修复经验，标记为跨域问题"

📖 统一命令行接口

EN: run.py is the unified cross-platform CLI for mode control, knowledge operations, GitHub learning, project detection, and environment diagnostics.

所有功能通过 run.py 统一调用，支持跨平台（OpenCode/Claude Code/Cursor）：

设置路径变量（每个 shell 会话执行一次）

# 自动检测平台并设置路径
SKILLS_DIR=$([ -d ~/.config/opencode/skills/evolving-agent ] && echo ~/.config/opencode/skills || echo ~/.claude/skills)

进化模式控制

# 查看状态
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 --off

知识库操作

# 查看统计
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge query --stats

# 按触发词查询（支持 --mode keyword|semantic|hybrid）
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge query --trigger "react,hooks"

# 按分类查询
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge query --category problem

# 全文搜索
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge query --search "跨域"

# 触发检测（自动匹配相关知识）
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge trigger --input "修复CORS问题"

# 归纳并自动存储
echo "内容" | python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge summarize --auto-store

# 存储知识
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge store --category experience --name "xxx"

# 生命周期管理
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               # 执行清理

# 导入导出
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge export --output backup.json
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge import --input backup.json --merge skip

# 可视化 dashboard
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge dashboard        # 文本输出
python $SKILLS_DIR/evolving-agent/scripts/run.py knowledge dashboard --json # JSON 输出

GitHub 学习

# 获取仓库信息
python $SKILLS_DIR/evolving-agent/scripts/run.py github fetch <url>

# 提取模式
python $SKILLS_DIR/evolving-agent/scripts/run.py github extract --input repo_info.json

# 存储到知识库
python $SKILLS_DIR/evolving-agent/scripts/run.py github store --input extracted.json

项目检测

# 检测当前项目技术栈
python $SKILLS_DIR/evolving-agent/scripts/run.py project detect .

# 存储项目经验
python $SKILLS_DIR/evolving-agent/scripts/run.py project store --tech react --pattern "xxx"

# 查询项目经验
python $SKILLS_DIR/evolving-agent/scripts/run.py project query --project .

环境信息

# 显示环境信息（表格格式）
python $SKILLS_DIR/evolving-agent/scripts/run.py info

# 显示环境信息（JSON 格式）
python $SKILLS_DIR/evolving-agent/scripts/run.py info --json

🔄 核心工作流

EN: The core loop is: intent routing -> orchestrated task batches -> review gate -> mandatory evolution and knowledge storage.

编程 + 进化闭环

用户请求 ("帮我修复这个 Bug")
    ↓
SKILL.md (orchestrator 主进程)
    ├─ 步骤1: 初始化
    ├─ 步骤2: 意图识别 → 编程-修复
    ├─ 步骤3: 编程调度闭环
    │   ├─ 3.1 任务分析+拆解（orchestrator 执行）
    │   ├─ 3.2 @retrieval 并行知识预取
    │   ├─ 3.3 @coder 按 simple-mode.md 执行（可并行多个）
    │   ├─ 3.4 @reviewer 独立上下文审查
    │   │    ├─ pass   → completed
    │   │    └─ reject → reviewer_notes 回流 @coder
    │   └─ 3.5 @evolver 知识归纳（进化模式激活时）
    └─ 步骤4: 最终验证

GitHub 学习闭环

用户请求 ("学习这个仓库 https://github.com/xx/repo")
    ↓
evolving-agent (协调器)
    ↓
github-to-knowledge (学习器)
    │
    ├─► Fetch Repo Info
    ├─► Extract Patterns/Stacks
    └─► Store to knowledge-base
          │
          ▼
knowledge-base (更新索引)
    │
    ▼
(后续编程任务中自动复用该知识)

📚 知识分类系统

EN: Knowledge is categorized into experience, tech-stack, scenario, problem, testing, pattern, and skill for targeted retrieval.

分类	目录	触发场景
experience	`experiences/`	优化、重构、最佳实践
tech-stack	`tech-stacks/`	框架相关
scenario	`scenarios/`	创建、实现功能
problem	`problems/`	修复、调试、报错
testing	`testing/`	测试相关
pattern	`patterns/`	架构、设计模式
skill	`skills/`	通用技巧

知识条目 Schema

{
  "id": "category-name-hash",
  "category": "experience|tech-stack|scenario|problem|testing|pattern|skill",
  "name": "名称",
  "triggers": ["触发词"],
  "content": {},
  "sources": ["来源"],
  "tags": [],
  "created_at": "ISO-8601",
  "updated_at": "ISO-8601",
  "usage_count": 0,
  "last_used_at": null,
  "effectiveness": 0.5
}

🎯 编程模式

EN: Full Mode targets feature development with structured task lifecycle; Simple Mode focuses on fast bug-fix loops with the same review/evolution gate.

Full Mode（完整开发）

触发关键词: 创建、实现、添加、开发

工作流（orchestrator 调度 @coder 按 full-mode.md 执行）:

orchestrator 任务拆解（sequential-thinking → feature_list.json）
@coder 并行执行开发（pending → in_progress → review_pending）
@reviewer 独立上下文审查（pass/reject）
@evolver 知识归纳

Simple Mode（快速修复）

触发关键词: 修复、fix、bug、重构、优化、报错

工作流（orchestrator 调度 @coder 按 simple-mode.md 执行）:

orchestrator 问题分析 + 任务拆解
@coder 修复
@reviewer 审查
@evolver 知识归纳

Consult Mode（轻量咨询）

触发关键词: 怎么、为什么、解释

工作流（orchestrator 直接执行 consult-mode.md，无需子 agent）:

知识检索
分析回答（如需改代码 → 切换到 Simple Mode）
知识归纳判断

📂 项目结构

EN: The repository is organized around the coordinator (evolving-agent), role agents, modular workflows, utilities, docs, and tests.

evolving-programming-agent/
├── evolving-agent/                 # [Core] Orchestrator 主进程
│   ├── SKILL.md                    # 主进程入口（初始化 → 意图识别 → 调度 → 验证）
│   ├── agents/                     # 子 Agent 角色定义
│   │   ├── coder.md                # 代码执行器（按工作流文件执行）
│   │   ├── reviewer.md             # 代码审查器（独立上下文）
│   │   ├── evolver.md              # 知识进化器
│   │   ├── retrieval.md            # 知识检索器
│   │   ├── orchestrator.md         # 备选调度器（SKILL.md 已取代其职责）
│   │   └── references/             # 审查参考清单
│   ├── command/
│   │   └── evolve.md               # /evolve 命令（透传 SKILL.md 流程）
│   ├── scripts/                    # Python 脚本
│   │   ├── run.py                  # 统一 CLI 入口
│   │   ├── core/                   # 核心（状态机、配置、路径、原子写入）
│   │   ├── knowledge/              # 知识库（检索、存储、生命周期）
│   │   ├── github/                 # GitHub 学习
│   │   └── programming/            # 编程助手
│   ├── modules/
│   │   ├── programming-assistant/  # @coder 工作流指南
│   │   │   └── workflows/
│   │   │       ├── simple-mode.md  # 修复指南
│   │   │       ├── full-mode.md    # 开发指南
│   │   │       ├── consult-mode.md # 咨询工作流（orchestrator 直接执行）
│   │   │       └── evolution-check.md # 知识归纳流程
│   │   ├── github-to-knowledge/    # 学习引擎
│   │   └── knowledge-base/         # 统一知识库
│   └── references/
│       ├── commands.md             # 命令速查
│       └── platform.md             # 平台差异定义
│
├── docs/                           # 文档
│   ├── architecture-review.md      # 综合评估报告（v6.0）
│   ├── mvp-build-plan.md           # 构建计划（Phase 1~5）
│   ├── SOLUTION.md                 # 历史架构说明
│   └── MODEL-CONFIG.md             # 多模型配置指南
├── tests/                          # 测试（148 passed）
├── scripts/                        # 安装/卸载脚本
├── requirements.txt                # Python 依赖（含可选依赖注释）
└── README.md                       # 本文件

🌍 跨平台支持

EN: Supported platforms: OpenCode, Claude Code, and Cursor, with automatic path detection for skills and knowledge directories.

Evolving Programming Agent 支持三大 AI 编程平台：

平台	Skills 目录	多 Agent 方式	全局知识库
OpenCode	`~/.config/opencode/skills/`	原生 `@agent` 调度	`~/.config/opencode/knowledge/`
Claude Code	`~/.claude/skills/`	Task tool spawn subagent	`~/.config/opencode/knowledge/`
Cursor	`~/.claude/skills/`	Task tool spawn subagent	`~/.config/opencode/knowledge/`

全局知识库跨平台复用。项目级知识存放在 $PROJECT_ROOT/.opencode/knowledge/，天然隔离。

🤝 贡献

欢迎提交 Pull Request 或 Issue 来帮助改进这个项目！

📄 许可证

MIT License

📖 相关文档

EN: Start with docs/architecture-review.md for architecture and docs/MODEL-CONFIG.md for multi-model setup.

综合评估报告 (docs/architecture-review.md): v6.0 架构审查 + 优化方案实施结果
构建计划 (docs/mvp-build-plan.md): Phase 1~5 全部任务详情
模型配置 (docs/MODEL-CONFIG.md): 多角色模型与 provider 配置
历史架构 (docs/SOLUTION.md): 架构演进背景
Orchestrator 主进程 (evolving-agent/SKILL.md): 初始化 → 意图识别 → 子 agent 调度 → 验证

Name		Name	Last commit message	Last commit date
Latest commit History 121 Commits
docs		docs
evolving-agent		evolving-agent
scripts		scripts
tests		tests
.gitignore		.gitignore
README.md		README.md
opencode.json.template		opencode.json.template
pytest.ini		pytest.ini
requirements-optional.txt		requirements-optional.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Evolving Programming Agent

🚀 核心特性

📋 系统要求

必需依赖

可选依赖

🏗️ 架构概览

核心组件

📦 安装

快速安装

Python 环境配置

🎮 快速开始

1. 启动协调器

2. 执行编程任务

3. 从 GitHub 学习

4. 显式保存经验

📖 统一命令行接口

设置路径变量（每个 shell 会话执行一次）

进化模式控制

知识库操作

GitHub 学习

项目检测

环境信息

🔄 核心工作流

编程 + 进化闭环

GitHub 学习闭环

📚 知识分类系统

知识条目 Schema

🎯 编程模式

Full Mode（完整开发）

Simple Mode（快速修复）

Consult Mode（轻量咨询）

📂 项目结构

🌍 跨平台支持

🤝 贡献

📄 许可证

📖 相关文档

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages