123 lines
9.1 KiB
Markdown
123 lines
9.1 KiB
Markdown
# mulit_agent（子 Agent）重构蓝图
|
||
|
||
## 1. 目标与边界
|
||
|
||
`mulit_agent` 是可部署到本机或远程主机的**独立执行平面**，以 Tkinter 程序运行。每个实例拥有独立身份、运行配置、技能、插件、工作目录和本地执行记录；它接收 `controller` 的已授权任务，运行模型与工具，并可靠地回传状态和结果。
|
||
|
||
LLM Provider、模型、Skills、MCP 工具、定时任务与执行策略都由 `controller` 统一配置和下发。子 Agent 本机界面只用于首次配对、Agent 名称和连接诊断；收到配置快照后，敏感 Key 仅写入当前 Windows 用户的凭据管理器，绝不显示在窗口或可迁移 JSON 中。
|
||
|
||
### 独立交付约束
|
||
|
||
`mulit_agent` 必须是可单独安装、启动和升级的程序：拥有自己的源码包、`pyproject.toml`、依赖锁定文件、数据目录、配置和安装包。运行时不得导入、调用或要求 `multi-claw-dashboard`、`multi-claw-agent`、Node.js、FastAPI、React、现有 MultiClaw 数据库、配置文件或启动脚本。现有 MultiClaw 只能作为迁移期间的行为参考或一次性数据导入来源，不能成为前置运行环境。
|
||
|
||
子 Agent 发行目录中的 `config/agent-config.json` 保存非敏感、可迁移的配置。启动时直接加载该文件；配对窗口修改地址后点击“保存并连接”时，应用必须原子回写该文件。Agent 凭据绝不写进 JSON，而是只保存于当前 Windows 用户的凭据库；因此复制程序目录到新电脑后会保留总控地址等偏好，但必须重新配对。
|
||
|
||
本次重构的目标是将现有 FastAPI Agent 的执行能力迁移为可视、可诊断、可后台运行的 Tkinter 子 Agent。保留可扩展的 Provider、工具、技能、插件、定时任务和安全隔离能力，但不承担全局调度或跨 Agent 数据管理。
|
||
|
||
子 Agent 负责：
|
||
|
||
- 与总控建立受认证的连接，报告身份、健康、能力、进度和结果。
|
||
- 在本地执行任务、模型调用、技能、插件、工具和定时任务。
|
||
- 维护任务取消、超时、资源限制、日志、工件和本地恢复记录。
|
||
- 提供 Tkinter 本机配置界面和系统托盘运行状态。
|
||
|
||
子 Agent 不负责：
|
||
|
||
- 保存全局 Agent 名册、全局任务编排、跨 Agent 结果汇总或用户权限策略。
|
||
- 直接访问总控数据库，或调用其他 Agent 绕过总控进行任务派发。
|
||
- 在未收到本地策略允许且总控鉴权通过的情况下执行危险工具或配置变更。
|
||
|
||
> 目录名按当前仓库使用 `mulit_agent`（原请求中的拼写）保留；若后续修正为 `multi_agent`，应在独立提交中统一迁移路径、启动脚本和安装配置。
|
||
|
||
## 2. 目标架构
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ mulit_agent（Tkinter 子 Agent 程序） │
|
||
│ Presentation: 配对窗口 / 系统托盘 / 本机设置 │
|
||
│ Application : SessionService / TaskExecutor / CapabilityService │
|
||
│ Domain : AgentSession、TaskRun、Policy、Artifact │
|
||
│ Infrastructure: 标准线程 WSS、LLM Provider、工具、SQLite、沙箱 │
|
||
└───────────────────────┬─────────────────────────────────────────┘
|
||
│ 版本化 HTTPS + WebSocket，认证与确认
|
||
▼
|
||
controller（唯一总控）
|
||
```
|
||
|
||
推荐目录结构：
|
||
|
||
```text
|
||
mulit_agent/
|
||
├── app.py # GUI 与后台运行入口
|
||
├── requirements.txt
|
||
├── src/
|
||
│ ├── presentation/ # Tkinter 窗口与系统托盘
|
||
│ ├── application/ # 会话、任务、能力、配置用例
|
||
│ ├── domain/ # 任务运行状态与策略
|
||
│ └── infrastructure/ # 传输、Provider、工具、插件、SQLite
|
||
├── skills/ # 本机安装的技能
|
||
├── plugins/ # 本机安装的插件
|
||
├── workspace/ # 受控任务工作目录
|
||
├── tests/
|
||
└── docs/
|
||
```
|
||
|
||
应用可显示主窗口，也应支持最小化到系统托盘和无交互后台模式。GUI 仅观察/控制本机运行态，实际任务引擎不得依赖窗口存在。
|
||
|
||
## 3. 核心功能设计
|
||
|
||
### 3.1 会话与通信
|
||
|
||
`ControllerSession` 管理注册凭据、WebSocket、心跳、自动重连、离线队列和消息确认。启动时加载本机身份与安全存储中的凭据，发送 `agent.hello` 和能力快照；连接丢失时继续执行已获授权的任务，但不接收新任务，并按策略缓存状态和结果等待回传。
|
||
|
||
子 Agent 只信任配置的总控端及其证书/公钥。任务命令必须通过协议版本、签名/令牌、时间窗、唯一消息 ID 和本地策略校验，拒绝原因以标准错误事件回报。
|
||
|
||
### 3.2 任务运行时
|
||
|
||
`TaskExecutor` 以持久化状态机运行任务：
|
||
|
||
`received → accepted → queued → preparing → running → finalizing → completed/failed/cancelled/timed_out`。
|
||
|
||
每个任务创建受控工作目录与 `TaskRun` 记录；执行器提供取消令牌、截止时间、并发额度、输出大小限制和资源记账。模型流式输出以增量事件发送，最终结果必须包含状态、文本、工件引用、用量、错误及起止时间。
|
||
|
||
### 3.3 Provider、技能、插件和工具
|
||
|
||
LLM Provider 以统一异步接口抽象，适配 Anthropic、OpenAI、Gemini、OpenRouter、DeepSeek、MiniMax 等现有能力。技能与插件采用 manifest、版本、来源、权限、依赖和启停状态管理；安装前校验签名/哈希（可用时）和权限，安装后在隔离环境探测能力。
|
||
|
||
工具执行经过 `ToolPolicy`：按 Agent 全局策略、总控任务策略和任务上下文取最严格限制。文件、Shell、浏览器、Docker 和桌面控制等高风险工具默认拒绝，需显式授权、路径/域名白名单和审计。插件不可直接修改总控端配置或读取总控凭据。
|
||
|
||
### 3.4 本地存储、可观测性与 UI
|
||
|
||
本地 SQLite 保存 Agent 元数据、任务运行、离线事件、工件索引、技能/插件清单和有限期日志；密钥存入系统凭据库或加密仓库。日志按 `task_id`、`correlation_id`、级别和组件结构化记录，并对提示词、凭据和附件脱敏。
|
||
|
||
Tkinter 窗口只负责 Agent 名称、总控地址和配对码；连接成功后由系统托盘提示在线、忙碌和故障。所有耗时操作运行在后台线程或受控子进程中，UI 线程不得运行模型、工具或阻塞网络。
|
||
|
||
## 4. 与总控端的接口契约
|
||
|
||
子 Agent 必须使用 `controller/docs/BLUEPRINT.md` 中定义的共享协议包；本地接口不可替代总控协议。
|
||
|
||
协议包必须独立版本化并作为普通依赖安装，或分别内置在两个安装包中；它不得依赖本仓库当前的 MultiClaw 模块。子 Agent 不读取总控的文件、数据库或配置，两个程序仅通过受认证的网络协议协作。
|
||
|
||
| 场景 | 子 Agent 输入 | 子 Agent 输出 |
|
||
| --- | --- | --- |
|
||
| 首次连接 | 注册挑战、配置的控制端地址 | 身份、版本、能力、健康信息 |
|
||
| 常态运行 | 心跳确认、配置/策略更新 | 心跳、能力变更、指标、告警 |
|
||
| 任务执行 | 下发、取消、查询、重试命令 | 接收确认、进度、流片段、最终结果 |
|
||
| 本地运维 | 启动/停止/升级请求 | 执行状态、诊断和错误 |
|
||
|
||
收到重复的 `task_id + attempt` 命令必须返回已有运行状态而非再次执行。未完成事件先落本地再发送；收到总控确认后才能清理。工件只发送受控元数据和可授权下载引用，不默认上传工作目录或敏感文件。
|
||
|
||
## 5. Tkinter 并发与运行规范
|
||
|
||
- 主线程只运行 Tkinter GUI 与事件分发；模型、工具、压缩、安装和数据库批处理必须移出 GUI 线程。
|
||
- WSS I/O 在独立线程运行；CPU 密集任务进入受控线程或子进程。
|
||
- 执行器与界面经事件队列通信，不在后台线程直接触碰 Tkinter 控件。
|
||
- 关闭程序时停止接收任务、向总控报告 draining、等待或安全取消运行项、刷写离线队列并关闭连接。
|
||
- 连接成功后窗口隐藏到系统托盘；从托盘菜单或双击图标可恢复配对设置。
|
||
|
||
## 6. 迁移原则与验收
|
||
|
||
先复用现有 Python Agent 已验证的 Provider、任务运行、技能、插件和配置逻辑，再把框架耦合收敛到基础设施适配器；不要把 FastAPI 路由函数复制进 Tkinter 控制器。旧 Agent 过渡期由协议适配器接入，新的 Tkinter Agent 以独立数据目录运行，避免覆盖旧配置或技能目录。
|
||
|
||
首个可发布版本验收条件：可从总控注册并显示在线；可可靠执行一个普通模型任务、流式回传、取消和重启恢复；断网期间可缓存并重传结果；未授权或超策略工具调用会被阻止并审计；GUI 和后台模式均可稳定运行。
|