9.6 KiB
Controller（总控端）重构蓝图
1. 目标与边界
controller 是多智能体系统的唯一控制平面，以独立的 Wails2（Go + React/TypeScript） 桌面程序运行。它面向管理员和调度员，负责保存全局状态、编排任务、管理子 Agent 的生命周期和展示运行态；它不执行模型推理、工具调用或插件业务。
独立交付约束
controller 必须是可单独安装、启动和升级的程序：拥有自己的源码包、pyproject.toml、依赖锁定文件、数据目录、配置和安装包。运行时不得导入、调用或要求 multi-claw-dashboard、multi-claw-agent、Node.js、FastAPI、React、现有 MultiClaw 数据库、配置文件或启动脚本。现有 MultiClaw 只能作为迁移期间的行为参考或一次性数据导入来源，不能成为前置运行环境。
控制端发行目录中的 config/controller-config.json 保存非敏感、可迁移的运行设置（例如 Agent 服务监听地址和端口）。启动时优先加载该文件；后续设置界面的保存动作必须原子回写同一文件。TLS 私钥、数据库和配对凭据不写入该配置文件，而保留在当前 Windows 用户的数据目录中。
本次重构的目标是将现有 Dashboard/Express 所承载的管理与编排能力迁移为 Wails2 总控端，并与 Tkinter/Python 的 mulit_agent 形成可单独发布、单独升级、可远程连接的两个程序。
总控端负责：
- Agent 注册、认证、在线状态与能力目录。
- 任务创建、@Agent 路由、并行/串行/DAG 编排、超时和取消。
- 汇总子 Agent 的结果，并保存任务会话、审计记录和可恢复的编排状态。
- 全局配置、密钥引用、技能/插件分发策略、委派编排和运行监控。
- 提供 React/TypeScript 管理界面、通知与操作入口。
总控端不负责：
- 调用 LLM、执行 Shell/浏览器/文件等工具，或直接加载 Agent 插件。
- 直接读写任一 Agent 的本地数据库、配置或工作目录。
- 在 GUI 线程中执行网络 I/O、调度或数据库长事务。
集中配置原则
除首次配对所需的总控地址、配对码和显示名称外，子 Agent 不提供可编辑的 LLM、Skill、MCP、定时任务或执行策略配置。总控保存这些配置并按 Agent 或 Agent 组生成带版本号的配置快照；每次变更均下发、确认、审计，并允许查看每个 Agent 的已应用版本。
LLM Key 仅由总控录入和保管，使用已配对的 TLS/WSS 会话下发给指定 Agent，Agent 只将其写入本机系统凭据库。Key 不进入可迁移 JSON、不显示给 Agent 用户、不进入任务事件或日志。Skills 与 MCP 工具以已校验的包、哈希、权限清单和目标范围下发，而非直接远程执行任意文件。
远程重启依赖目标机器已安装的 Agent 守护服务：守护服务负责启动、停止和重启执行进程；总控仅发送受认证、可审计的生命周期命令。已停止的普通托盘程序不能自行被远程唤醒。
2. 目标架构
┌─────────────────────────────────────────────────────────────────────┐
│ controller（Wails2：Go + React/TypeScript） │
│ Presentation: React 页面 / ViewModel / 通知 │
│ Application : Go TaskService / Orchestrator / AgentService │
│ Domain : Task、Workflow、Agent、Policy、Audit │
│ Infrastructure: SQLite、TLS/WSS、密钥库、日志 │
└─────────────────────────┬───────────────────────────────────────────┘
│ 版本化 HTTPS + WebSocket，HMAC/令牌认证
▼
┌─────────────────────┐
│ mulit_agent（多个） │
│ PySide6 子 Agent │
└─────────────────────┘
推荐目录结构：
controller/
├── app.go # 受限的 Wails 前端绑定
├── main.go # Wails 进程入口与退出编排
├── go.mod
├── internal/ # Go 控制平面、SQLite、TLS/WSS
├── frontend/ # React/TypeScript 管理界面
├── config/ # 可迁移的非敏感配置
├── build.ps1 # Windows 发布构建入口
├── tests/
└── docs/
UI 使用 React 页面、组件与 ViewModel，至少包含控制台、Agent、模板、技能、插件、工作流、定时任务、密钥、委派、审计日志与设置页面。记忆、帮助、用户管理和登录页面不迁移。前端只能调用按用例划分的 Wails 绑定并渲染数据；不得直接访问数据库、TLS 私钥、Agent 凭据或本机工具。
3. 核心功能设计
3.1 Agent 管理
AgentService 管理注册、撤销、心跳、能力同步、配置下发和启动/停止请求。每个 Agent 由不可变 agent_id 标识，显示名称可以修改。状态机为：registered → connecting → online → degraded/offline → revoked。
总控端只通过传输接口发出动作；本地进程启动、Docker 控制或远程重启都应实现为可替换的 AgentLifecyclePort，避免 UI 和平台命令耦合。
3.2 任务与编排
任务包含 task_id、会话 ID、发起人、输入、附件引用、目标 Agent、策略、截止时间和幂等键。Orchestrator 以持久化状态机执行：
created → queued → dispatching → running → synthesizing → completed/failed/cancelled。
支持单 Agent、并行、串行、DAG 和私有指派。DAG 节点仅引用上游的已脱敏结果，不隐式共享完整会话。取消、重试和断线恢复必须基于 task_id 与尝试次数幂等处理。
3.3 存储与安全
控制端使用本地 SQLite 保存 Agent、任务、工作流、事件、审计与 UI 偏好；敏感令牌不以明文写入业务表，而由系统凭据库或经主密钥加密的密钥仓库保存。数据库迁移必须有版本号、备份和回滚说明。
总控在本机环境中以单一管理员身份运行，不提供旧 FastAPI Dashboard 的登录账户、用户或角色管理。所有创建、下发、取消、升级和授权动作仍须记入不可修改的审计事件；日志中不得写入 API Key、任务附件原文或完整提示词。
3.4 实时通信
通信层采用 HTTPS 请求（注册、命令、查询）和 WebSocket（心跳、状态、流式输出、事件）。Go 控制平面提供 TLS/WSS 监听服务；React 前端只能经 Wails 绑定读取状态或发起受校验的用例。
接口以 /api/v1 开头并带 schema_version。每个命令和事件都携带 message_id、correlation_id、UTC sent_at；收件方去重并返回确认，未确认消息可安全重发。
4. 与子 Agent 的接口契约
以下契约同时是两个程序的共同边界，最终应抽取为共享、版本化的 Python 包（例如 multiclaw_protocol），不能靠复制 Pydantic/字典定义维持一致。
该协议包必须是第三方独立依赖（有独立版本和发布物），或随两个安装包各自内置；它不得依赖本仓库现有 MultiClaw 的任何模块。两个程序除该协议契约和网络通信外不共享运行时状态、数据库或文件目录。
| 类别 | 总控端动作 | 子 Agent 回应/事件 |
|---|---|---|
| 连接 | 注册、发放凭据、心跳确认 | agent.hello、agent.heartbeat、能力清单 |
| 任务 | 下发、取消、查询、重试 | 接收确认、阶段进度、流式片段、最终结果 |
| 配置 | 获取/更新配置、技能/插件策略 | 校验结果、应用结果、需重启标记 |
| 生命周期 | 启动、停止、健康检查、升级请求 | 状态变化、健康指标、错误事件 |
任务下发的最小载荷：task_id、correlation_id、attempt、instruction、context_refs、deadline_at、policy、reply_to。最终结果最小载荷：task_id、status、output、artifacts、usage、error、started_at、finished_at。所有时间使用 ISO 8601 UTC，所有状态枚举由协议包定义。
5. Wails2 并发与安全规范
- React/WebView 只处理渲染和用户交互；不能同步执行网络、数据库或编排工作。
- Go 控制平面使用受控 goroutine 处理 WSS 会话；每条 WebSocket 连接的写入必须串行化。
- Wails 绑定只暴露
Snapshot、配对码生成、在线 Agent 查询、任务创建和任务查询等窄用例；不绑定通用数据库、文件、Shell 或凭据能力。 - 窗口关闭时依次停止新调度、关闭 WSS、持久化状态并释放数据库连接。
6. 迁移原则与验收
采用绞杀式迁移：先建立协议和只读监控，再迁移单 Agent 调度，最后迁移工作流、配置与运维能力。旧 Dashboard 与 FastAPI Agent 在过渡期可通过兼容适配器接入；任何阶段均不允许两个控制端同时向同一 Agent 发出可变更命令。
首个可发布版本验收条件：可注册并持续显示一个远程 Agent；可下发、取消并恢复单 Agent 任务；可展示流式输出与最终结果；重启总控后可恢复历史和未完成任务；断网、重复消息、非法凭据和 Agent 超时均有可见、可审计的处理结果。