用 PHP 构建编码代理
长期以来，AI 工具行业的潜台词一直是：想构建代理（agents）？那就去学 Python 吧。各种框架、教程、大会演讲，全都指向同一个方向。想用 PHP 来实验自主系统的开发者，通常只有两条路：要么换技术栈，要么自己从底层 API 调用硬拼凑，然后祈祷它能稳定运行。
Neuron AI 诞生的目的就是填补这个空白。现在，随着 Neuron v3 引入了以工作流（workflow）为优先的架构，我想用最直接的方式证明这一点：构建一个生态系统普遍认为“只能用其他语言实现”的东西。这就是 Maestro 的诞生——第一个完全用 PHP 构建的编码代理（coding agent）。
Neuron 是什么？
Neuron 是一个专为开发代理式应用（agentic applications）而生的 PHP 框架。它帮你处理了编排、数据加载、调试等繁重工作，让你可以专注于项目的创造性核心。从第一行代码到复杂的多代理系统，你可以自由构建自己想象中的、能思考和行动的 AI 实体。
Neuron 的架构充分考虑了有生产经验的工程师对“生产级软件”的真实期待。
强类型系统
整个框架充分利用了 PHP 8+ 成熟的类型系统，每个方法签名、属性、返回值都做了明确的类型标注。代码库 100% 通过 PHPStan 严格类型检查。
对 IDE 极其友好
强类型 + 详细的 PHPDoc 注释，让你的 IDE 能提供非常精准的自动补全（代理配置、工具参数、响应处理等）。这大大加快了调试周期，也更容易与 Symfony、Laravel 等框架集成。我们假设你构建的是需要团队长期维护、扩展、理解的系统，而不是一次性玩具。
精心设计的架构
Neuron 在合适的地方使用标准 PSR 接口，外部依赖极少，避免不同 PHP 环境和框架版本之间的冲突。这种设计大大降低了“引入新库导致依赖地狱”的概率。
对于跨多个项目工作的团队，这种一致性非常宝贵。无论你在纯 PHP 写微服务、扩展 WordPress、还是在企业级的 Symfony/Laravel 项目里加功能，Neuron 的模式和写法都是通用的，知识迁移几乎无缝。
社区驱动
这些设计原则为整个 PHP 社区的 AI 开发创造了一个统一的生态。Neuron 不是把创新分散在各个框架专属方案里，而是让 Laravel 开发者、Symfony 贡献者、WordPress 插件作者、自定义框架维护者都能站在同一个基础上协作。当 Neuron 核心能力提升时，所有 PHP 开发者都能受益。
这种通用性也吸引了来自 PHP 生态各部分的贡献者，带来更健壮的实现、更广的测试覆盖、更快的特性迭代，以及对新手更好的社区支持。
编码代理到底在做什么？
在看代码之前，先明确一下定义，因为“coding agent”这个词经常被滥用。
Maestro 不是代码补全工具。它是一个在你终端里运行的自主代理，它会读取你的项目文件、对代码库进行推理、然后提出修改建议。它以循环方式工作：你给它一个任务 → 它决定调用哪些工具（读文件、搜索代码模式、写更改）→ 顺序执行 → 报告结果。
最关键的词是 “提出” ——在真正触碰你的文件系统之前，它会请求你的批准。
这一点不是可有可无。任何拥有写权限的代理，如果不经确认就直接改你代码库，都是巨大风险。Maestro 的工具批准机制是我最喜欢的功能之一，它直接对应了 Neuron v3 引入的核心概念：人机交互工作流中断（human-in-the-loop workflow interruption）。
架构概览
仓库结构体现了清晰的关注点分离。入口是 bin/maestro，它启动一个 Symfony Console 命令。从这里开始，一切都很清晰：
bin/maestro└─MaestroCommand(SymfonyConsole)├─Settings(加载.maestro/settings.json)├─EventDispatcher+CliOutputListener└─AgentOrchestrator└─CodingAgent(继承自NeuronAIAgent)├─ProviderFactory→AIProviderInterface├─FileSystemToolkit(只读文件系统工具)└─McpConnector[](可选的MCP服务器)
CodingAgent 继承自 Neuron 的 Agent 基类，并额外加了一个工具批准中间件。每次要写文件前，这个中间件会拦截，抛出 ToolApprovalRequestedEvent 并暂停。AgentOrchestrator 捕获这个中断，通过 CLI 向用户显示批准提示，根据用户选择恢复或中止执行。
这种“中断 → 呈现 → 恢复”的模式，如果没有底层以工作流为核心的框架支持，实现起来会非常痛苦。而在 Neuron v3 中，这几乎是自然而然的写法。
快速上手
全局安装（推荐）：
composer global require neuron-core/maestro
确保 Composer 的全局 bin 目录在 PATH 中：
export PATH="$HOME/.config/composer/vendor/bin:$PATH"
也可以作为项目开发依赖安装，然后用 vendor/bin/maestro 执行。
配置文件放在项目根目录下的 .maestro/settings.json，最少需要指定提供者和密钥：
{"provider": {"type": "anthropic","api_key": "sk-ant-your-key-here","model": "claude-sonnet-4-20250514","max_tokens": 8192 }}
Maestro 开箱支持：Anthropic、OpenAI、Gemini、Cohere、Mistral、Ollama、Grok、Deepseek 等，通过 ProviderFactory 根据 type 自动路由。
想完全本地跑？指向 Ollama 即可：
{"provider": {"type": "ollama","base_url": "http://localhost:11434","model": "llama2" }}
给代理提供项目上下文
默认情况下，Maestro 会尝试加载项目目录下的 Agents.md 文件。你也可以指定其他 Markdown 文件（比如 CLAUDE.md、PROJECT_RULES.md），在 settings.json 中配置：
{"provider": { ... },"context_file": "CLAUDE.md"}
代理会在对话一开始就把这个文件内容附加到系统提示（system prompt）里。这是一个简单但极其有效的机制。一个知道你项目用 PSR-12、控制器不写业务逻辑、偏好依赖注入而非服务定位器的代理，从第一句话开始就能给出更靠谱的建议。
工具批准流程
当代理想修改文件时，不会直接写入，而是暂停并显示类似下面内容：
代理想要向 src/Service/UserService.php 写入更改[1] 允许一次[2] 本会话允许[3] 始终允许[4] 拒绝
最常用的是 [2] 本会话允许 ——一次性批准某个文件类型或工具的写操作，之后的同类操作不再询问。
[3] 始终允许 会把偏好持久化到 .maestro/settings.json 的 allowed_tools 里，未来所有会话都跳过提示。
这种灵活的粒度控制非常实用：刚开始可以严格审核，建立信任后逐步放开。
这是 Neuron 框架最有意思的能力之一，得益于工作流架构支持执行中断，你可以创建高度定制化的人机协作体验。想了解更多：https://docs.neuron-ai.dev/workflow/human-in-the-loop
事件系统
Maestro 使用轻量级的 PSR-14 兼容事件调度器，主要有三个事件：
AgentThinkingEvent —— 每次调用 AI 前触发AgentResponseEvent —— 模型返回响应时触发ToolApprovalRequestedEvent —— 需要工具批准时触发
CliOutputListener 订阅这些事件并负责所有终端输出渲染。
这种设计让代理核心逻辑保持干净——CodingAgent 根本不知道输出是怎么显示的。如果你想基于同一个代理做 Web 界面，只需换一套监听器，其他代码不用动。
MCP 集成（扩展能力）
对于需要文件系统之外更多能力的团队，Maestro 支持配置模型上下文协议（MCP）服务器：
{"mcp_servers": {"github": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-github"],"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" } } }}
每个配置项都会启动一个子进程，并作为额外工具源接入代理。代理就能调用 GitHub 操作、搜索网络，或使用任何兼容 MCP 的服务，与原生文件工具并行工作。
这证明了什么？
Maestro 用事实证明：别人用 Python 和 TypeScript 实现的那些模式，现在完全可以用 PHP 表达出来。
工作流架构带来的工具批准、人机中断、事件驱动渲染管道、多模型抽象、MCP 集成……这些都不需要跳出 PHP 生态。
真正干重活的是 Neuron AI 框架，尤其是 v3 引入的工作流能力。如果没有在代理循环中暂停执行、根据用户输入精确恢复的能力，工具批准系统会需要大量额外脚手架。
想看源码：https://github.com/neuron-core/maestroNeuron AI 文档：https://docs.neuron-ai.dev
