Agent of Empires结构化视图完全指南：ACP协议、工具调用卡片与审批流一次讲透

Agent of Empires结构化视图完全指南ACP协议、工具调用卡片与审批流一次讲透【免费下载链接】agent-of-empiresManage multiple Claude Code, OpenCode agents from either TUI or Web for easy access on mobile. Also supports Mistral Vibe, Codex CLI, Gemini CLI, Pi.dev, Copilot CLI, Factory Droid Coding.项目地址: https://gitcode.com/gh_mirrors/ag/agent-of-empiresAgent of Empires简称 AoE是一款统一管理 Claude Code、Codex、OpenCode、Gemini CLI 等多款 AI 编码 Agent 的开源工具支持 TUI 与 Web 双端手机也能随时接管。它的核心亮点是结构化视图Structured View不再盯着终端里滚动的字符而是把 Agent 的计划Plan、**工具调用卡片Tool Call Cards和审批流Approvals**直接渲染成结构化的界面。本文带你一次看懂它背后的 ACP 协议、卡片渲染与审批机制。什么是结构化视图为什么不用终端传统用法中Agent 跑在一个终端窗口里你只能看它打印出来的内容。结构化视图则直接把 Agent 的内部状态画出来计划卡片Agent 的 Todo 清单实时显示1 进行中 · 1 待办 · 1 已完成️工具调用卡片每次读文件、改代码、跑命令都有一张专属卡片编辑类直接内嵌迷你 Diff⚠️审批卡片危险操作如git push --force会弹出带确认环的审批卡等你拍板。它同时渲染在 Web 仪表盘和原生 TUI 中两端共用同一个aoe serve守护进程会话状态、待审批项实时同步。结构化视图是移动端优先设计的从手机竖屏一路放大到桌面多窗格布局都能用。一分钟快速上手三步进入结构化视图运行aoe serve打开 Web 仪表盘点击New session选择项目与 Agent如claude、codex直接启动——结构化视图默认开启打开会话你会看到计划和工具调用卡片而不是终端画面。想先用 CLI 自检环境两条命令就够了aoe acp doctor # 检查 Node 与各 Agent 适配器是否就绪 aoe acp doctor --fix # 自动补装缺失的适配器无需 sudoWeb 向导里每个会话都有Use structured view开关默认开可以随时切回终端视图已有会话也能在侧边栏右键菜单双向切换worktree、文件与提交都会原样保留。ACP协议让结构化成为可能的标准结构化视图说的是ACPAgent Client ProtocolAgent 客户端协议——一套基于 JSON-RPC 的编辑器与 Agent 通信标准。在 AoE 中角色分工非常清晰aoe 是客户端Client守护进程aoe serve为每个会话派生一个独立的 worker 进程在 worker 与 Web/TUI 之间转发协议Agent 是服务端Server每个支持 ACP 的 AgentClaude Code、Codex、OpenCode、Gemini 等都作为服务端接入。这套设计带来的好处是任何实现了 ACP 的 Agent 都能即插即用。AoE 内置了一份已验证的 ACP 适配器注册表见 docs/structured-view.md 的 Supported agents 表格覆盖了claude-agent-acp、codex-acp、pi-acp等主流适配器没有 ACP 适配器的工具如 aider、cursor则自动落到终端视图。几个值得新手记住的安全细节详见 docs/development/internals/structured-view.md 的 Security model 章节️ Agent从不直接碰磁盘文件读写全部由 aoe 代劳并强制沙箱根目录边界审批 nonce 由服务端生成、一次性有效即使 Agent 被攻破也无法伪造一次审批 每个内置适配器只透传它真正需要读取的凭据环境变量如 Claude 只拿到ANTHROPIC_API_KEY等最小化泄漏面。协议层的完整实现位于 src/acp/感兴趣的读者可以对照 src/acp/acp_client/ 中的握手、生命周期与权限处理器源码。工具调用卡片Agent 的每一步操作都一目了然结构化视图最直观的体验就是按工具种类渲染卡片而不是一刀切的通用行工具类型卡片内容编辑/写入文件路径 主题色着色的紧凑 Diff执行命令命令本身 有界的输出预览读取文件路径 内容预览删除操作目标对象Diff 默认截断在 20 行、预览 12 行超出部分显示 N more长会话也不会刷屏。几个贴心设计️时间线折叠连续 3 次以上无文字的静默工具调用会合并成一张 actions 卡连续 Todo 更新合并成 updated N times 卡Compact tools 开关一键把所有工具卡片折叠到只剩标题方便快速扫描出错卡片始终保持展开️内联媒体工具返回的图片、音频会直接渲染在卡片上展示不了的内容降级为带标签的占位符而不是直接丢弃本地文件引用Agent 消息里的path:line链接点击后直接打开应用内文件查看器不用离开会话。编辑类卡片对应的完整 Diff 面板则长这样右侧列出全部变更文件审批流危险命令如何被安全地拦住审批Approvals是结构化视图的安全带。当 Agent 想执行需要批准的工具时界面上会浮出一张审批卡片。两级确认强度✅良性工具读取、搜索、列目录点一下Allow即可破坏性操作rm -rf、git push --force、写系统路径长按 800ms才完成确认界面上有一圈倒计时确认环——单点只会触发 Deny从机制上杜绝误触。权限模式决定哪些操作免问输入框底部的模式选择器对应 Agent 支持的权限档位以claude-agent-acp为例模式行为default所有 Write/Edit/Bash 都走审批卡acceptEdits编辑类自动放行Bash 和未知工具仍会询问plan只读Agent 只起草计划不执行任何副作用工具bypassPermissions全放行YOLO 模式需启动aoe serve时设置ALLOW_BYPASS1审批的兜底与提醒⏱️超时自动取消默认 300 秒未处理即自动作废可通过[acp] approval_timeout_secs调整见 docs/structured-view/controls.md双通道提醒审批到达且你不在仪表盘时Web 推送会深链回会话浏览器端还会播放审批提示音即使aoe serve跑在远程机器上也一样有效⌨️TUI 免进审批在 TUI 主列表选中会话按a即可回答第一个待审批项无需进入完整视图❓结构化提问AskUserQuestionAgent 中途的选择题会渲染成单选/多选卡片你的答案会作为你的回合记录进转录。常见问题速查doctor、限流与卡顿症状解法doctor报 Node 缺失安装 Node.js 22再跑aoe acp doctor --fix适配器版本过低按提示npm install -g官方适配器或在仪表盘点Restart agent转到底部无反应aoe acp logs --session id看适配器原始日志或仪表盘Open agent log触发限流被停车横幅会给出重置时间或换 Agent 继续按钮可配置rate_limit_auto_resume自动恢复审批卡消失说明超时自动取消了Agent 通常会再次询问完整的失败模式手册见 docs/structured-view/troubleshooting.md配置项汇总见 docs/guides/configuration.md。小结把 AI Agent 管成一支军团Agent of Empires 的结构化视图做对了一件关键的事用 ACP 协议把 Agent 的内部状态翻译成人能扫读的计划、卡片与审批再叠加长按确认、超时兜底、沙箱代管文件读写等安全设计让远程让 AI 写代码这件事既看得懂、也信得过。无论是手机上扫一眼审批还是桌面端多会话并行它都值得一试 延伸阅读结构化视图总览docs/structured-view.md界面与快捷键docs/structured-view/interface.md模式、审批与模型控制docs/structured-view/controls.md内部机制贡献者向docs/development/internals/structured-view.md【免费下载链接】agent-of-empiresManage multiple Claude Code, OpenCode agents from either TUI or Web for easy access on mobile. Also supports Mistral Vibe, Codex CLI, Gemini CLI, Pi.dev, Copilot CLI, Factory Droid Coding.项目地址: https://gitcode.com/gh_mirrors/ag/agent-of-empires创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考