py-code-agent：一款支持百种模型、具备五层自愈能力的AI编程助手

py-code-agent 是一款基于 ReAct 推理循环的AI编程助手，采用插件化架构设计，支持100+模型提供商，并独创五层自愈机制保障系统稳定性。

在AI编程助手领域，大多数工具要么绑定特定模型提供商，要么缺乏灵活的扩展机制。py-code-agent 的出现打破了这一局面——它是一个基于 ReAct（Reasoning + Acting）推理循环的AI编程助手，采用插件化架构设计，通过 LiteLLM 支持100多个模型提供商，并独创了五层自愈机制来保障系统稳定性。

py-code-agent 的设计理念是模块化和可扩展性。其核心架构分为多个层次：

• CLI 层：提供 chat、run、config、plugin、channel websocket 等命令接口
• 核心层：包含 Agent（ReAct 循环）、Session、Events、PluginManager
• LLM 层：通过 LiteLLM 统一接入 OpenAI、Anthropic、Azure、Ollama 等100+提供商
• 插件系统：基于 pluggy 的可扩展架构，支持四层插件加载（内置、本地、全局、PyPI）
• 工具与通道层：文件操作、Bash 执行、WebSocket、MCP 网关、A2A 协议

传统的AI助手往往是单次问答模式，而 py-code-agent 引入了 ReAct（Reasoning + Acting）推理循环。当启用 react.enabled: true 时，Agent 会遵循"思考 → 行动 → 观察"的循环：

1. 思考（Thought）：LLM 分析当前任务状态，决定下一步行动
2. 行动（Action）：调用工具或生成最终答案
3. 观察（Observation）：将工具执行结果反馈到上下文中
4. 重复：直到调用 task_done 或达到最大轮数

这种模式使 Agent 能够自主编码——它可以编写文件、运行测试、修复错误，并持续迭代直到任务完成。例如，当要求"创建一个打印斐波那契数列的 Python 脚本"时，Agent 会主动分析需求、编写代码、验证输出，而非仅仅返回代码片段。

py-code-agent 最具创新性的特性是其五层自愈机制。在插件化系统中，插件崩溃或配置错误往往会导致整个系统不可用。该项目通过以下五层防护解决这个问题：

层级	场景	修复策略
第一层	Hook 方法崩溃	运行时 try/except 包装
第二层	插件缺少 Hook 方法	注入空操作存根
第三层	导入错误（缺少依赖包）	自动 pip install 后重试
第四层	属性错误	注入缺失属性
第五层	Tool execute() 崩溃	AST 修补源文件并重新加载

这种设计确保了即使某个插件出现问题，系统也能继续运行，甚至自动修复问题。第五层的 AST 修补尤为创新——它能够在运行时修改源代码并重新加载，无需重启整个系统。

py-code-agent 的插件系统采用四层加载策略，优先级从高到低依次为：

1. 内置插件：随包分发的核心插件，如 SoulPlugin（加载 soul.md 人格定义）、AgentIdentityPlugin（自我意识）、PlanPlugin（复杂任务规划）
2. 本地插件：项目特定的 ./.py-code-agent/plugins/ 目录
3. 全局插件：用户级别的 ~/.config/py-code-agent/plugins/ 目录
4. 入口点插件：通过 PyPI 分发的社区插件

已发布的社区插件包括：

• py-code-agent-git：Git 状态与操作
• py-code-agent-search：通过 DuckDuckGo 进行网络搜索
• py-code-agent-mcp-gateway：MCP 服务器连接（支持10,000+工具）
• py-code-agent-a2a-gateway：Agent 间通信（A2A v0.3.0）
• py-code-agent-grep：代码搜索引擎（文本 + AST）

py-code-agent 支持多种通信通道：

• CLI 通道：通过 py-code-agent chat 启动交互式终端，适合本地开发
• WebSocket 通道：通过 py-code-agent channel websocket --port 8080 启动服务，支持远程接入和集成

WebSocket 模式使用简单的 JSON 消息格式，便于与其他系统集成。这种设计使 py-code-agent 既可以作为个人开发助手，也可以部署为团队服务。

py-code-agent 引入了 Skill 系统，支持从 SKILL.md 文件加载可复用工作流，且与 Claude Code 兼容。Skill 的发现路径按优先级排序：

• ./.py-code-agent/skills/<name>/SKILL.md
• ~/.config/py-code-agent/skills/<name>/SKILL.md
• ~/.claude/skills/<name>/SKILL.md

这意味着为 Claude Code 编写的 Skill 可以直接在 py-code-agent 中使用，实现了工作流的跨平台复用。