整体技术方案与架构说明

1. 系统定位与核心目标

一个“多服务协同的 AI Agent 执行平台”，核心目标是把“用户任务”稳定地转化为“可执行的 Agent 运行”，并提供：

• 任务编排与执行（即时、定时、夜间窗口）
• 会话与运行状态全链路可追踪（SSE + 持久化事件）
• 插件化能力装配（MCP、Skill、Plugin、Subagent、Slash Command）
• 可回放产物（Workspace 文件、归档、截图）
• 面向外部生态的 OpenAPI 兼容入口

2. 功能全景（按业务域）

3. 总体架构图

4. 分层架构说明

4.1 Frontend（交互与编排层）

• 技术栈：Next.js 16 + React 19 + TypeScript + Tailwind + shadcn/ui
• 关键交互：
• Home 页任务编排：提示词、附件、仓库、浏览器、能力选择、计划模式、定时模式
• Chat 执行页：聊天面板 + 电脑面板 + 产物面板三联动
• SSE 驱动实时状态（会话流 + 侧边栏状态流）
• 按 stream_seq 缓冲乱序事件，发现缺口时从历史接口补齐，再按顺序渲染
• 终态刷新服务端消息历史，用持久化结果校准本地流式内容
• Capabilities 中心统一管理 Skill/MCP/Subagent/Plugin/定时任务等
• 代理策略：frontend/app/api/v1/[...path]/route.ts 与 v2 路由作为同源代理层

源码依据：

• frontend/features/home/components/home-page-client.tsx
• frontend/features/chat/hooks/use-execution-session.ts
• frontend/components/shared/sidebar/main-sidebar.tsx
• frontend/lib/api-client.ts

4.2 Backend（控制面与数据面核心）

• 路由分层：
• /api/v1：主业务 API
• /api/v2/turns：回合式入口
• /openapi/v1/*：外部兼容入口
• 核心职责：
• 会话/运行/消息/工具执行/用量持久化
• 任务入队与幂等（idempotency_key）
• 高频流事件先通过 SSE 分发，再按批次持久化，避免数据库写入阻塞用户看到回复
• 按 run 维护接收与持久化进度，支持重复请求去重、序号缺口检查和历史补拉
• 回调处理与终态补偿（message reconcile、通知、workbench 触发）
• 中间件：RequestContextMiddleware、RequestLoggingMiddleware、AuthMiddleware

源码依据：

• backend/app/main.py
• backend/app/api/v1/__init__.py
• backend/app/core/middleware/*.py
• backend/app/services/task_service.py
• backend/app/services/callback_service.py
• backend/app/services/callback/
• backend/app/services/stream_ingress_service.py
• backend/app/services/stream_event_service.py

回调服务目录说明：

• backend/app/services/callback_service.py：对外兼容入口，继续导出 CallbackService，保持旧导入路径稳定。
• backend/app/services/callback/orchestrator.py：回调主编排，串联 session 更新、run 状态推进、消息落库、usage 记录、事件持久化和终态副作用。
• backend/app/services/callback/parsing.py：Poco Agent 消息、任务系统消息、stream event、UUID、stop reason 等纯解析逻辑。
• backend/app/services/callback/message_service.py：会话消息落库、工具执行记录、pre_compact 消息和 stopped run 的 partial assistant 消息补偿。
• backend/app/services/callback/usage_service.py：ResultMessage usage 持久化、stream usage 回填、用户/团队 quota counter 增量同步。
• backend/app/services/callback/run_state_service.py：run 解析、run 状态同步、scheduled task / step 的 last run 状态同步。
• backend/app/services/callback/stream_builder.py：callback 到 stream records / transient envelopes 的构建，以及 stream event 持久化策略判断。
• backend/app/services/callback/terminal_effect_service.py：终态后的 message reconcile、session summary、webhook、通知、workbench 触发、自动发布和产物推荐入队。

4.3 Executor Manager（调度与运行时编排）

• 调度内核：APScheduler + Pull 模式队列消费
• 关键能力：
• claim_run -> prepare -> dispatch -> start_run
• 预备阶段状态回传（environment/skills/mcp/plugins/subagent/ready）
• 容器池（ephemeral/persistent warm container）
• 为每个 run 签发限权实时令牌，并把 Backend 实时入口与 Manager 普通回调入口一并下发给 Executor
• 高频直达失败时接收 Executor 的有序批量降级回调
• 终态后 workspace 导出与回传
• 浏览器基础沙箱（per-user base browser）生命周期管理

源码依据：

• executor_manager/app/core/lifespan.py
• executor_manager/app/services/run_pull_service.py
• executor_manager/app/services/container_pool.py
• executor_manager/app/services/callback_service.py

4.4 Executor（执行引擎层）

• 关键职责：
• 准备工作区（代码仓、输入文件、插件目录、上下文）
• 构造执行引擎运行选项与 hook
• 执行工具权限门禁（Plan 模式）
• AskUserQuestion/ExitPlanMode 人机交互回路
• 注入内置 MCP（时间、图像理解、Playwright）
• 高频流事件写入本地 journal（待发送记录），并按 stream_seq 直达 Backend；确认持久化后再清理记录
• 直达通道持续失败时，把未持久化事件按批次交给 Executor Manager 转发
• 停止机制（soft interrupt + hard cancel）

源码依据：

• executor/app/api/v1/task.py
• executor/app/core/engine.py
• executor/app/core/task_registry.py
• executor/app/hooks/*.py

5. 核心时序

与主分支的关键差异

5.1 即时任务执行链路

5.2 实时消息异常降级链路

正常情况下，高频流事件不经过 Executor Manager。只有直达 Backend 持续失败时，Executor 才会启用已有的 Manager 回调通道；因此异常降级不会把正常流量重新压回 Manager。

5.3 定时任务分发链路

5.4 Plan 模式（先计划后执行）

6. 数据模型与状态机

6.1 核心实体关系

6.2 Run 状态机

6.3 关键业务对象

• 会话：agent_sessions（用户上下文、配置快照、导出状态、直接父会话与 fork 点）
• 运行：agent_runs（队列状态、调度模式、权限模式、租约、错误）
• 事件：agent_stream_events（SSE 回放与恢复基础）
• 定时任务：agent_scheduled_tasks + agent_scheduled_task_steps
• 工作台：workbench_scope / workbench_insight / workbench_artifact

多级分叉不复制数据库消息。读取某个分支时，后端通过递归 CTE 沿 parent_session_id 向上解析会话链，并用每一级的 fork_point_message_id 限制祖先消息和运行记录的可见范围。查询包含同用户校验和循环保护；首次执行分支时只复制直接父分支的一份快照。运行前 Manager 优先使用当前会话的活动工作区，其次恢复当前会话的本地完整归档；只有仍处于 fork_pending 的首次分叉才会恢复并复制直接父工作区，已运行分支不会回退到父快照。

7. 能力装配与执行前准备机制

运行前装配由 Manager 统一完成，避免执行容器内做重复配置读取：

• MCP：按用户安装 + 会话显式选择解析
• Skill：落地到用户技能目录（执行时从 user/project setting source 加载）
• Plugin：解压并转换为本地插件路径注入
• Subagent：解析定义并落地
• Slash Commands：同步至会话上下文
• CLAUDE.md / System Prompt / AGENTS.md：按用户配置装配
• input_files：附件分发/拉取后注入任务配置

源码依据：

• executor_manager/app/services/config_resolver.py
• executor_manager/app/services/*_stager.py
• executor/app/core/engine.py

7.1 Agent 与多 Agent 能力分层方案

1. 单 Agent 执行层（当前主链路）

• 一条任务对应一个主执行会话，负责规划、调用工具、产出结果、回调状态。
• 对应本项目：TaskService -> RunService -> RunPullService -> AgentExecutor -> CallbackService。

2. Subagent（子代理）层（同会话内隔离执行）

• 子代理定位：针对特定子任务的“专用执行单元”，独立上下文窗口、独立系统提示词、独立工具权限。
• 主 Agent 负责“委派 + 汇总”，子代理聚焦局部问题，减少主上下文污染。
• 适合场景：代码审查、专项排障、文档整理、只读分析等高频子任务。

3. 多 Agent 并行层（同会话内并发委派）

• 由主 Agent 并行拉起多个子代理处理互不依赖的研究路径，再统一合并结论。
• 适合场景：模块并行调研、跨目录影响分析、并行测试诊断。
• 约束：子代理链路需控制深度，避免“无限嵌套委派”导致成本和复杂度失控。

4. Agent Team 层（跨会话协同团队）

• 由 Lead Agent + Teammates 构成，使用共享任务列表与消息机制协作。
• 每个 teammate 保持完整独立上下文，可直接互通消息，适合需要“讨论/挑战/协商”的复杂任务。
• 适合场景：跨前后端大改造、多假设并行排障、复杂方案评审。

7.2 上下文自动压缩与会话治理方案

为保证长会话稳定性与成本可控，目前将“自动压缩 + 主动治理”作为执行器标准能力：

1. 自动压缩

• 会话接近上下文上限时自动进行历史压缩，保留关键决策与有效结论。
• 与 prompt caching 联动，降低重复上下文的 token 消耗。

2. 手动压缩与压缩策略注入

• 支持通过压缩指令追加“保留重点”（如代码片段、API 约束、测试结论）。
• 支持在项目级指令文件中配置压缩偏好（例如优先保留错误栈和改动摘要）。

3. 会话切换治理

• 对无关任务建议随时开启新会话，同时支持分叉会话功能等手段，避免上下文持续膨胀。
• 对高体量工具定义（如大量 MCP）采用延迟加载/按需加载策略（借助 ToolsSearch 工具实现），降低常驻上下文占用。

4. 观测与告警

• 在事件流中增加上下文水位与压缩事件（如 context.usage、context.compact_boundary）。
• 对“压缩失败、压缩后关键信息缺失、会话恢复失真”建立告警和兜底策略。

8. 实时通信与可观测性

8.1 SSE 设计

• 会话流：/api/v1/sessions/{session_id}/stream
• 侧栏状态流：/api/v1/sessions/sidebar-status/stream
• 高频流入口：/api/v1/callback/stream
• 持久化确认：/api/v1/callback/stream/flush

消息分成实时展示和可靠恢复两层：

1. Backend 接收单个 run 内连续递增的 stream_seq 后，先广播给在线订阅者，再由后台任务批量写入 agent_stream_events。
2. Executor 同时保留本地待发送记录；只有 Backend 返回 durable_through（已持久化到的序号）后，才删除对应记录。
3. 前端只按连续 stream_seq 渲染。后到事件会先缓冲，缺失事件通过 stream-events?run_id=...&from_stream_seq=... 补齐。
4. SSE 重连继续使用 Last-Event-ID 和事件历史；订阅队列溢出后也会触发 catch-up。
5. run.done / run.error 不会跳过尚未补齐的流事件，终态后再刷新消息历史进行最终校准。
6. OpenAI 兼容流复用 Backend 的 run 级有序事件源，遇到缺口时先恢复历史，再继续输出后续内容和终态。

SSE 空闲期间发送心跳 ping，用于保持连接和及时发现断线。

8.2 可观测性

• 全链路 request_id / trace_id
• 调度关键阶段埋点（timing step 日志）
• 失败场景抓取容器日志（终态失败时）

源码依据：

• backend/app/services/stream_event_service.py
• backend/app/api/v1/sessions.py
• executor_manager/app/scheduler/task_dispatcher.py
• executor_manager/app/services/callback_service.py

9. 安全与权限模型

• API 鉴权：
• 外部：Authorization: Bearer <token>
• 内部：X-Internal-Token
• API Key 能力边界：conversation/global/admin scope 分级
• 普通回调安全：Executor Manager 使用内部 token 调用 Backend
• 实时回调安全：Executor 使用仅限单个 session/run、带有效期的 X-Stream-Token，不持有全局内部 token
• Plan 模式工具门禁：未审批前禁止写入/执行类工具

源码依据：

• backend/app/core/middleware/auth.py
• backend/app/core/deps.py
• backend/app/api/v1/callback.py
• executor/app/core/engine.py

10. 部署拓扑与运行方案

10.1 容器镜像分层

• docker/sandbox：默认 full 基础运行时，包含桌面/浏览器能力
• docker/executor：在 sandbox 之上组装执行器，预装 Playwright MCP、universal-db-mcp 和 agent-browser，并作为 latest 单镜像使用
• docker/executor/start.sh：控制是否启动桌面/VNC/code-server 相关服务

10.2 运行模式建议

• 开发环境：四服务分开启动，便于调试路由与回调
• 生产环境：Backend + Manager 高可用，Executor 按需弹性扩展
• 浏览器能力：通过 ENABLE_SANDBOX_SERVICES 按容器运行时启用，非浏览器任务不启动桌面/VNC/code-server 服务

11. 稳定性与容错设计总结

• 幂等：idempotency_key 防重复入队
• 租约：claim lease + 超时回收，避免僵尸任务占用
• 运行恢复：stale running 自动 fail，保证状态收敛
• 容器容错：启动重试、不健康容器清理、容量保护
• 流式容错：Executor 本地待发送记录 + 接收/持久化双进度 + 有界重试 + Manager 批量降级
• 顺序恢复：stream_seq 连续消费 + SSE 断线重连 + 历史缺口补拉 + event replay
• 终态补偿：workspace 导出异步回调 + message reconcile

---

附录 A：关键源码索引

• Frontend：frontend/features/* frontend/components/shared/*
• Backend API：backend/app/api/v1 backend/app/api/v2 backend/app/api/openapi_v1
• Backend 核心服务：backend/app/services/task_service.py run_service.py callback_service.py callback/ stream_ingress_service.py stream_event_service.py
• Executor Manager：executor_manager/app/services/run_pull_service.py container_pool.py
• Executor：executor/app/core/engine.py executor/app/api/v1/task.py executor/app/core/stream_callback.py executor/app/hooks/callback.py
• Frontend 消息顺序：frontend/features/chat/components/execution/chat-panel/hooks/use-chat-messages.ts frontend/features/chat/utils/stream-sequence-buffer.ts
• 部署：docker/sandbox/* docker/executor/*