Agentic Loop：面向Windows的Planner-Executor智能体编排框架

在AI辅助编程工具百花齐放的今天，大多数方案都面临着同一个挑战：如何让AI智能体在复杂、长期的应用构建任务中保持可控、可观测、可干预。Agentic Loop项目提供了一个独特的答案——它采用"Planner-led"架构，将决策与执行分离，并通过一个Windows友好的Go CLI实现人机协作的闭环。

架构核心：分离决策与执行

Agentic Loop的架构由三个核心角色组成：

Planner（规划器）

Planner是决策者，负责选择"接下来做什么"。它通过OpenAI Responses API进行推理，输出结构化的动作指令。Planner不直接操作代码，而是生成高层次的执行计划。

Executor（执行器）

Executor是代码工人，负责执行具体的仓库操作。主要执行器基于Codex（通过app-server模式），接收Planner的指令并返回执行结果作为数据。

CLI（命令行界面）

CLI是一个"惰性"的桥接和运行时容器。它不决定工作何时完成，不改写人类回复，也不发明工作流策略。它的职责是：

• 持久化状态
• 路由结构化的Planner输出
• 管理传输层
• 向操作员显示可见状态

这种分离设计的关键优势在于：安全暂停点只发生在AI回合完成并已持久化检查点之后，人类始终掌握最终控制权。

关键设计原则

Agentic Loop的设计文档中明确了一系列"不可协商"的原则：

1. Planner决定下一步：CLI不替代Planner做决策
2. Executor返回数据：执行结果以结构化数据返回，而非自然语言
3. 人类回复原样转发：不做修改或解释
4. 机械停止原因持久化：操作员可以看到为什么停止，而CLI不做语义判断

这些原则确保了系统的可预测性和可审计性，对于生产环境中的应用构建至关重要。

V2控制台：从CLI到桌面GUI

项目正在向V2控制台演进，目标是提供一个可选的Windows友好的操作员控制台。目前已实现的功能包括：

核心基础设施

• 本地控制服务器：通过orchestrator control serve提供公共回环控制服务
• 事件总线：进程内事件总线和事件流骨架，支持未来控制台附加
• 安全点干预：持久化的控制消息队列，将操作员消息和待处理动作上下文反馈给Planner
• 运行时配置重载：无需重启进程即可调整日志详细程度（quiet/normal/verbose/trace）

桌面GUI功能（Electron外壳）

目前已实现的桌面外壳功能：

• 引导式Home仪表板：回答"是否已连接"、"加载了哪个仓库"、"循环是否运行"、"是否需要我"、"发生了什么"、"接下来该点击什么"
• 始终可见的状态条：显示连接状态（Ready/Not Connected/Connecting/Reconnecting）、仓库根目录、运行ID、循环状态、阻塞器、详细程度、更新状态
• 标签导航：Home、Run、Action Required、Chat、Files、Live Output、Workers、Terminal、Settings、Dogfood Notes
• 运行控制区域：简化版的Start Build / Continue Build操作
• 运行时可见性：显示运行经过时间、目标、停止原因、完成状态
• 待处理动作详情：显示Planner结果、保持状态、保持原因、调度目标、执行器提示摘要
• 工件浏览器：支持浏览和查看工件内容
• 契约文件编辑器：支持编辑.orchestrator/brief.md、.orchestrator/roadmap.md等文件
• AI自动填充向导：通过引擎协议起草标准契约文件并预览
• 仓库浏览器：只读浏览仓库文件
• 操作员终端标签：本地shell会话，与引擎运行权限分离
• Action Required面板：清晰显示需要执行器批准的状态和Planner的ask_human暂停
• Codex/模型就绪卡片：真实显示Planner模型健康状态、Codex可执行文件路径/版本
• 自动模型健康检查：GUI连接/重连时以及Start Build/Continue Build之前自动检查
• 后端身份可见性：显示PID、启动时间、二进制路径、版本、修订版本
• Side Chat面板：基于上下文代理基础，仅从可观察的运行时状态回答
• 运行时超时与自主性设置：支持超时预设和所有七种独立超时编辑
• 更新卡片：GitHub发布检查和变更日志复制
• Dogfood Notes面板：记录与仓库和最新运行关联的时间戳摩擦笔记
• Worker面板：显示真实Worker ID、状态、范围、工作区路径、批准状态
• Live Output面板：基于/v2/events，显示可读的Planner/Executor/Worker/批准/模型行
• Control Chat面板：基于真实的inject_control_message

日常Dogfood工作流

项目推荐的日常使用流程：

powershell -ExecutionPolicy Bypass -File .\scripts\start-v2-dogfood.ps1 -RepoPath D:\\Projects\\target-repo

该辅助脚本从orchestrator仓库构建，但控制服务器绑定到-RepoPath指定的目标仓库。Shell会显示预期仓库和后端报告的仓库；如果不匹配，会隐藏错误仓库的运行状态并建议重启后端。

关键操作

1. 启动构建：在Home仪表板确认连接状态为Ready，检查Current Repo卡片，然后点击Start Build
2. 回答Planner问题：打开Action Required，输入原始答案，点击Send Answer and Continue
3. 清除安全停止：如果请求了安全停止，打开Action Required并点击Clear Stop and Continue
4. 记录摩擦：在Dogfood Notes面板捕获摩擦和bug

权限与自主性配置

Agentic Loop支持四种权限/自主性配置文件：

• guided（引导模式）：高干预，Planner频繁询问人类
• balanced（平衡模式）：适度自主性，在关键决策点询问
• autonomous（自主模式）：低干预，仅在必要时暂停
• full_send（全权模式）：最小干预，最大化AI自主性

这些配置通过运行时配置动态调整，无需重启。

运行时超时设置

系统支持七种独立的可配置超时：

• Planner请求超时
• Executor空闲等待超时
• Executor回合超时
• 子代理超时
• Shell命令超时
• 安装超时
• 人类等待超时

其中Executor回合和人类等待默认无限制，其他有合理默认值。

技术选型：为什么是Go？

Agentic Loop选择Go语言实现，主要考虑以下因素：

1. Windows友好：Go编译为单一可执行文件，部署简单
2. 并发模型：Go的goroutine和channel适合处理Planner-Executor之间的异步通信
3. 静态链接：无依赖，适合分发
4. 跨平台：虽然主要面向Windows，但代码可移植到Linux和macOS

与类似方案的对比

特性	Claude Code	Codex CLI	Agentic Loop
架构	单体Agent	单体Agent	Planner-Executor分离
人机协作	对话式	对话式	结构化Action Required
状态持久化	会话级	会话级	检查点级
可观测性	日志	日志	结构化事件流
GUI	无	无	Electron外壳
目标平台	跨平台	跨平台	Windows优先

实用意义：谁应该关注Agentic Loop？

Agentic Loop特别适合以下场景：

1. Windows开发者：原生Windows支持，无需WSL或虚拟机
2. 长期项目：需要多天甚至多周的持续开发，需要持久化状态和可恢复性
3. 团队协作：结构化的契约文件（brief.md、roadmap.md、decisions.md）便于多人协作
4. 可审计需求：所有Planner决策和Executor动作都有结构化记录
5. 可控自主性：可根据任务敏感度和团队偏好调整AI自主性级别

项目状态与路线图

目前项目处于积极开发阶段，V2控制台已实现核心功能，但以下功能仍在规划中：

• 完整的LLM支持的Side Chat升级和工具调用后端
• Worker应用控制
• Worker特定的批准控制
• 打包的GUI安装程序

已足够稳定用于日常Dogfood的功能：

• 本地控制服务器 + 事件流
• 可重连的Shell附加
• Planner安全的状态/进度可见性
• Control Chat注入
• 工件浏览
• 标准契约编辑
• Worker可见性和基本操作

结语

Agentic Loop代表了一种务实的人机协作编程范式。它不追求完全自主的AI编程，而是专注于构建一个可靠的基础设施，让AI和人类在各自擅长的领域发挥作用。Planner负责决策，Executor负责执行，人类负责监督和干预——这种清晰的分工让复杂的应用构建任务变得可管理、可预测、可审计。对于需要在Windows环境下进行长期AI辅助开发的团队，Agentic Loop提供了一个值得认真考虑的选择。