策略驱动的 CLI 框架，用于在代码仓库中运行确定性、可审计的 LLM Agent 工作流
项目概述#
AgentPlane 是一个策略驱动的 CLI 框架，旨在解决 LLM Agent 在代码仓库中执行时缺乏可预测性和可审计性的问题。其核心理念是"确定性优于魔法"（Determinism over Magic），确保 Agent 遵循可复现的执行路径。
核心设计理念#
- Determinism over Magic: Agent 遵循可复现的执行路径
- Guardrails by Default: 默认启用安全护栏
- Policy-first execution: 每次运行都遵循定义的管道
- Traceability: 任务状态、产物和 Agent 行为均可追溯
执行管道#
Preflight → Plan → Approval → Tasks → Verify → Finish → Export
关键特性#
- Policy-first execution: 每次运行遵循定义的管道
- Approval & planning gates: 无明确同意不执行任何操作
- Role-based workflows: 支持 ORCHESTRATOR, PLANNER, CREATOR, INTEGRATOR 等角色
- Safety guardrails by default: 仓库外操作、网络访问、无限制写入默认禁用
- Team workflow support: 支持
direct和branch_pr两种工作流模式 - Explicit commit allowlists: 强制使用明确的提交允许列表
角色系统#
- ORCHESTRATOR: 驱动会话并解释用户目标
- PLANNER: 将目标分解为计划步骤/任务
- CREATOR: 实现代码/配置更改
- INTEGRATOR: 验证并合并更改
工作流模式#
- direct 模式: 单检出模式，Agent 和任务在同一工作树中运行，适合实验和快速迭代
- branch_pr 模式: 结构化团队工作流，每个任务通过独立 worktree + 跟踪的 PR 产物
状态转换规则#
- TODO → DOING | BLOCKED
- DOING → DONE | BLOCKED
- BLOCKED → TODO | DOING
执行配置文件#
- conservative: 保守模式
- balanced: 平衡模式
- aggressive: 激进模式
适用场景#
- 企业级开发团队的 AI 辅助编程工作流
- 需要审计追溯的合规性项目
- DevOps 自动化任务执行（结合 Git 工作流）
- 多角色协作的 AI Agent 任务管理
环境要求#
- Node.js >= 20
- 包管理器：Bun 1.3.6（推荐）/ npm
安装方式#
# 全局安装
npm install -g agentplane
# 或使用 npx（无需安装）
npx agentplane init
快速开始#
npx agentplane init # 初始化仓库
npx agentplane quickstart # 查看 CLI 快速入门
agentplane --help # 查看帮助
agentplane --version # 查看版本
核心命令示例#
# 配置管理
agentplane config show
agentplane config set workflow_mode branch_pr
# 任务管理
agentplane task list
agentplane task new --title "..." --description "..." --priority med --owner CODER
# 工作流操作
agentplane start <task-id> --author CODER --body "Start: ..."
aventplane verify <task-id> --ok --by REVIEWER --note "Looks good"
# Preflight 检查
agentplane preflight --mode full
关键配置文件#
- AGENTS.md: 策略与护栏配置（仓库根目录）
- .agentplane/config.json: 执行配置文件设置
- .agentplane/tasks/: 每任务记录存储
项目结构#
agentplane/
├── packages/
│ ├── agentplane/ # 主 CLI 包
│ ├── core/ # 核心库
│ ├── recipes/ # 示例配方
│ ├── spec/ # 规范定义
│ └── testkit/ # 测试工具包
├── schemas/ # JSON Schema 定义
└── docs/ # 参考文档
分层架构#
| 层级 | 路径 | 职责 |
|---|---|---|
| CLI 层 | src/cli/ | 解析、格式化、退出码、帮助渲染 |
| 用例层 | src/usecases/ | 通过端口协调策略检查和副作用 |
| 端口层 | src/ports/ | 仅接口定义 |
| 适配器层 | src/adapters/ | 唯一允许直接访问 OS/git/network 原语 |
待确认信息#
- 具体支持的 LLM 后端（文档提到 Redmine 后端同步，但未明确 LLM 提供商）
- 与 LangChain、AutoGPT 等框架的集成能力
- 官方网站 agentplane.org 当前为临时页面，完整网站正在重建中