127 lines
9.6 KiB
Markdown
127 lines
9.6 KiB
Markdown
# 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. 目标架构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 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 │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
推荐目录结构：
|
||
|
||
```text
|
||
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 超时均有可见、可审计的处理结果。
|