chore: initial commit (sources + docs, ignore build artifacts and secrets)

mulit_agent/docs/BLUEPRINT.md

@@ -0,0 +1,122 @@
+# 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 和后台模式均可稳定运行。

mulit_agent/docs/CONFIGURATION.md

@@ -0,0 +1,23 @@
+# mulit_agent 配置与迁移
+
+## 可迁移配置
+
+发行目录下的 `config/agent-config.json` 随程序目录复制。首次启动时自动加载；在 Windows 发行版中，已保存的配对信息还会写入 `%LOCALAPPDATA%\MultiClawAgent\agent-settings.json` 作为本机持久副本，并同步回发行目录配置。重新编译替换发行目录不会丢失同一 Windows 用户的配对信息；复制到另一台电脑时仍需重新配对。
+
+```json
+{
+  "config_version": 1,
+  "agent_name": "",
+  "controller_url": "",
+  "agent_id": "",
+  "certificate_fingerprint": ""
+}
+```
+
+`agent_id` 与证书指纹不属于密钥，但在复制到新电脑后没有对应的 Windows 凭据；应用会保持地址预填，并要求输入总控新生成的一次性配对码以取得新凭据。
+
+## 不可迁移的安全状态
+
+Agent 凭据只存于当前 Windows 用户的凭据管理器，任务记录、日志和数据库保留在 `%LOCALAPPDATA%\MultiClawAgent`。不要复制或手工编辑 Windows 凭据；需要为新电脑重新配对。
+
+LLM API Key、模型与服务地址不由这个 JSON 文件或 Agent 窗口管理，而由总控统一下发。Agent 接收后仅将 Key 写入当前 Windows 用户的凭据管理器；它不会跟随发行目录迁移，也不会显示给本机用户。

mulit_agent/docs/STATUS.md

@@ -0,0 +1,39 @@
+# mulit_agent 当前开发进度
+
+更新时间：2026-09-15
+
+## 已完成并验证
+
+- 图片附件任务闭环：安全校验总控 `task_dispatch.attachments` 的 MIME、数量与解码大小；附件仅在执行内存传递，OpenAI 兼容、Anthropic、Gemini 分别生成正确图文载荷。无视觉能力的当前模型会安全失败，不会降级为纯文本或影响 WSS 线程。
+
+- 默认完全访问执行器：已认证总控下发的任务可由 Agent 所在 Windows 电脑实际执行文件、程序、网络和桌面应用操作。OpenAI 兼容、Anthropic、Gemini 均支持模型工具调用循环；执行过本机命令的任务会标记为“完全访问”，取消任务会终止仍在跟踪的命令。命令输出、任务结果和审计摘要仍会脱敏，不能保存 API Key、密码、凭据、图片 Base64 或内部推理。
+
+- 独立 Tkinter 子 Agent、系统托盘、独立数据目录、Windows 凭据管理器和 Windows 编译脚本；不依赖旧 MultiClaw、FastAPI、Node.js 或 PySide6。
+- 首次 WSS 配对、TLS 证书指纹校验、认证、心跳、Agent 改名、断线状态和托盘驻留。
+- 接收总控独立文本任务并持久化本地生命周期；可回传接收、运行、完成、失败、取消和超时状态。多个不同任务会分别进入后台执行，供总控同时向多台机器派发。
+- 本地演示执行器用于当前任务闭环验证；任务取消/超时后的迟到结果不会覆盖终态。
+- 本机可迁移配置与 Windows 用户持久配置双写方案已完成：同一 Windows 用户重新编译不会丢失 Agent 名称、总控地址和配对信息；复制到新电脑仍需重新配对。
+- 本地 LLM 配置窗口、配置字段与本地启用逻辑已移除。LLM 仅保留待总控下发时复用的协议适配器，不可由子 Agent 用户填写。
+- 已接入总控 LLM 配置快照：仅在已认证的 TLS/WSS 会话中接收 Provider、模型、地址和 Key；Key 写入 Windows 凭据管理器，非敏感元数据持久化到本机数据库。
+- 已支持 OpenAI 兼容 API（含主流云端、中转站与 Ollama/LM Studio/vLLM 等本地模型），并原生适配 Anthropic 和 Gemini；任务会调用已下发的模型并回传结果或安全错误。
+- 旧版受控桌面文件工具状态机保留为兼容路径；新版默认由完全访问执行器处理本机操作，不再将桌面直接子文件夹限制作为产品权限边界。
+- 模型结果在回传前会去除 `<think>...</think>`（含未闭合标签），防止内部推理进入任务输出。
+- 并发回归已验证：同一 Agent 的两条独立模型任务可以同时开始执行，任一任务完成不会阻塞另一条结果回传。
+- 总控的单独指派与按行 `@` 批量指派均复用既有文本任务入口；子 Agent 不保存跨任务上下文，回传仍走原有状态、结果、取消、超时与重试闭环。
+
+## 最近编译
+
+- `dist/MultiClawAgent/MultiClawAgent.exe` 已于 2026-09-15 重新编译（含单独/批量指派与 5 分钟无进展续期）。
+
+## 已规划，尚未实现
+
+- 总控下发的 Skills、插件和 MCP 工具的版本、权限校验与回滚。
+- 持久化离线事件外盒、重连补传、任务重启恢复。
+- 本机 Agent 守护服务与远程重启、升级。
+
+## 进度判断
+
+- **可测试基础闭环**（配对、在线、任务、取消、重试）：约 **65%**。
+- **最终集中管理目标**（统一 LLM/Skill/MCP/定时器/远程运维）：约 **35%**。
+
+当前策略：子 Agent 只接收和执行总控迁移后的能力；不会依赖或导入旧 FastAPI、Node.js、旧 Python Agent 运行环境。

mulit_agent/docs/steps/01-项目骨架与运行模式.md

@@ -0,0 +1,9 @@
+# 01：项目骨架与运行模式
+
+1. 在 `mulit_agent` 建立分层目录、入口、依赖锁定、测试目录、技能/插件目录和受控工作目录。
+2. 固定 Tkinter（Python 标准库）、`websocket-client`、`pystray`、Provider SDK、SQLite 迁移、日志和测试依赖；确认与总控端共用的协议包版本。
+3. 建立 `AgentConfig`，涵盖 Agent ID/名称、控制端地址、数据目录、资源上限、Provider 引用、日志级别和后台模式；发行目录的 `config/agent-config.json` 在启动时加载，配对窗口保存时原子回写；密钥不得写入配置文件。
+4. 分离 Tkinter GUI 入口与后台服务线程；窗口和托盘仅观察/控制应用服务。
+5. 建立结构化日志、未捕获异常处理和优雅关闭骨架。
+
+验收：GUI、后台模式均可启动和退出；配置校验可定位错误；干净环境中可通过静态检查和基础测试。

mulit_agent/docs/steps/02-协议会话与安全.md

@@ -0,0 +1,12 @@
+# 02：协议会话与安全
+
+1. 接入共享协议包，完成 hello、注册、心跳、能力、任务、确认、进度、结果和错误消息的模型及契约测试。
+2. 实现 `ControllerSession`：HTTPS 注册、WebSocket 建连、证书校验、超时、指数退避、消息 ID 去重和确认机制。
+3. 使用系统凭据库/加密仓库存储凭据；实现凭据轮换、失效、控制端地址变更和安全擦除流程。
+4. 对每个入站命令校验版本、签名/令牌、时间窗、重放、目标 Agent 和策略版本；拒绝时记录审计并回传标准错误。
+5. 建立离线事件出站盒（outbox）：先持久化、后发送、收到确认再清理。
+
+验收：子 Agent 可稳定注册、重连和报告能力；伪造、过期、重放或错投命令不被执行；断网事件恢复连接后只回传一次。
+# 局域网直连
+
+子 Agent 与总控的 WSS 连接固定使用 `NoProxy`。总控是用户配置的局域网地址，不应继承 Windows 的 HTTP 或 SOCKS 代理；否则 Qt 可能在 TLS 握手前报出代理类型不支持。该设置只影响总控 WebSocket，不改变系统代理设置。

mulit_agent/docs/steps/03-本地状态与任务生命周期.md

@@ -0,0 +1,9 @@
+# 03：本地状态与任务生命周期
+
+1. 创建 SQLite 迁移，包含本机身份、任务运行、事件出站盒、工件索引、策略快照、技能/插件清单和日志索引。
+2. 定义 `TaskRun`、取消令牌、截止时间、尝试次数和状态转换；禁止跳过状态或从终态回到运行态。
+3. 实现入队、并发控制、每任务工作目录、资源配额、取消、超时和清理策略。
+4. 重复 `task_id + attempt` 请求返回已记录状态；相同任务的不同 attempt 必须隔离目录和结果。
+5. 启动恢复时扫描非终态任务：可恢复任务继续/查询，无法恢复任务标为失败并生成事件。
+
+验收：任务在取消、超时、异常退出和重启后状态一致；并发上限和工作目录隔离可以自动测试。

mulit_agent/docs/steps/04-模型执行与流式结果.md

@@ -0,0 +1,9 @@
+# 04：模型执行与流式结果
+
+1. 从现有 `multi-claw-agent` 提取 Provider 抽象为基础设施适配器，统一异步 `generate`/`stream`、用量、错误和取消语义。
+2. 先迁移一个 Provider 的普通请求与流式请求，再逐个迁移其余 Provider；每个适配器独立做模拟 API 测试。
+3. 实现 `TaskExecutor`，将任务上下文、身份、允许工具和策略转为 Provider 请求，严格限制输入/输出大小。
+4. 流式片段按节流策略发送并写入本地运行记录；完成、失败、取消和超时都生成唯一最终事件。
+5. 对网络失败、限流、Provider 超时、无效响应和上下文过大实现标准错误映射与安全重试策略。
+
+验收：可完成普通与流式模型任务；取消能停止请求；最终用量、错误与输出可被总控准确显示。

mulit_agent/docs/steps/05-技能插件工具与隔离.md

@@ -0,0 +1,9 @@
+# 05：技能、插件、工具与隔离
+
+1. 盘点现有技能、插件和工具，定义统一 manifest（名称、版本、来源、依赖、权限、入口、哈希、状态）。
+2. 迁移技能/插件安装器，加入来源校验、依赖探测、禁用状态和失败回滚；不要自动执行未经授权的安装脚本。
+3. 建立 `ToolPolicy`，合并本机策略、总控策略和任务策略，以最严格结果控制文件、Shell、浏览器、Docker 和桌面能力。
+4. 为高风险工具配置路径/域名白名单、用户确认（如需要）、超时、输出截断和完整审计。
+5. 使用受限子进程或容器运行不可信插件/工具；最小化环境变量、工作目录和网络权限。
+
+验收：被禁用/越权工具不可执行且有原因记录；批准工具仅能访问声明范围；插件安装失败不会损坏现有运行环境。

mulit_agent/docs/steps/06-PySide6运行界面.md

@@ -0,0 +1,12 @@
+# 06：Tkinter 运行界面
+
+1. 建立主窗口、托盘菜单、连接状态条、全局通知与关闭/后台运行行为。
+2. 实现概览：控制端连接、身份、版本、健康、队列、当前任务、CPU/内存和最近告警。
+3. 实现任务页：队列、运行详情、进度、流式日志、取消和已完成结果；禁止用户绕过总控创建远程任务。
+4. 实现技能/插件页和本机配置页，危险的启停、安装和凭据操作必须二次确认并受本地权限保护。
+5. 通过线程安全事件队列接收后台事件；高频日志采用批量刷新与虚拟列表，避免界面卡顿。
+
+验收：连续流输出和多个并发任务下界面保持响应；托盘模式不影响任务完成和结果上报。
+# 托盘与命名补充
+
+配对窗口提供可持久化的 Agent 名称字段，首次配对时使用该名称注册到总控。连接成功后窗口隐藏到托盘；用户可从托盘菜单“打开配对设置”或双击托盘图标恢复窗口。关闭已连接的设置窗口仅隐藏窗口，Agent 继续在托盘运行；选择“退出”才会终止进程。

mulit_agent/docs/steps/07-兼容迁移与故障恢复.md

@@ -0,0 +1,9 @@
+# 07：兼容迁移与故障恢复
+
+1. 盘点现有 FastAPI Agent 的配置、Provider、任务、技能、插件、cron 和日志，标注可直接复用、需适配和暂不迁移的部分。
+2. 先将现有业务逻辑封装为不依赖 FastAPI 路由的服务，再由新的 Qt 传输层调用；避免复制代码。
+3. 创建旧配置和本地数据导入器，导入前备份、导入后校验；新数据目录默认与旧 Agent 隔离。
+4. 为旧控制端/旧 Agent 提供版本协商或协议适配器，制订灰度启用和回退步骤。
+5. 演练断网、控制端重启、进程崩溃、磁盘空间不足、Provider 故障和不兼容策略下的恢复行为。
+
+验收：代表性旧实例可在不覆盖原数据的情况下迁移；恢复演练后不丢失最终任务结果或重复执行任务。

mulit_agent/docs/steps/08-测试打包与交付.md

@@ -0,0 +1,9 @@
+# 08：测试、打包与交付
+
+1. 建立状态机单测、协议契约测试、Provider 模拟测试、工具策略测试、SQLite 恢复测试、Qt 界面测试和端到端联调。
+2. 在 CI 运行格式、类型、单测及控制端—子 Agent 的协议兼容矩阵；为关键安全策略设置回归用例。
+3. 使用 PyInstaller 或同等方案制作 Windows 安装包，定义数据目录、最小权限、签名、升级和卸载的数据处理。
+4. 编写部署、注册、故障排查、日志导出、密钥轮换、离线恢复、升级与卸载手册。
+5. 用试点总控与至少一个本地、一个远程 Agent 完成发布演练，记录性能与回滚阈值。
+
+验收：空白 Windows 主机可安装并注册；GUI 与后台模式均能接收、执行、取消并回传任务；升级、降级和日志导出都有可验证路径。

mulit_agent/docs/steps/09-单Agent任务闭环.md

@@ -0,0 +1,28 @@
+# 09：单 Agent 任务闭环
+
+## 本阶段目标
+
+接收来自已认证总控的单条文本任务，在本地持久化任务运行状态，并回传接收、运行和完成事件。
+
+## 已实现范围
+
+1. 本地 SQLite 新增 `task_runs` 与 `task_events`，以 `task_id` 作为幂等键记录任务生命周期。
+2. `ControllerSession` 只处理总控下发的 `task_dispatch`；无效任务载荷会被拒绝。
+3. `TaskExecutor` 对重复 `task_id` 返回已有状态，不会重复执行。
+4. 当前执行器是受限的内置演示执行器：仅生成文本结果，不运行模型、插件、Shell、浏览器、文件或桌面控制。
+5. 各阶段事件通过已配对的 WSS 会话回传；短暂断线时，内存中的待发送事件会在下一次认证连接后发送。
+6. 托盘菜单的状态文字会显示最近一次任务阶段。
+7. 总控的单独指派与按行 `@` 批量指派沿用同一条文本任务协议；子 Agent 只接收自己的独立任务文本，不保存跨任务上下文，也不会接收附件或远程终端协议。
+
+## 本阶段刻意限制
+
+- 待发送事件尚未实现跨进程持久化；本地任务记录已保存，后续会补充重启恢复与事件重放。
+- 不接收附件、不执行工具、不接入模型供应商，因此不会要求或保存任何模型 API 密钥。
+- 取消、超时、资源限制和任务工作目录将进入后续任务运行时阶段。
+
+## 验收步骤
+
+1. 完成与总控的安全配对，Agent 进入托盘并保持在线。
+2. 从总控下发一个文本任务。
+3. 确认托盘状态依次变为 `accepted`、`running`、`completed`。
+4. 在总控任务记录中确认结果到达；重复下发同一 `task_id` 时不应重复执行。

mulit_agent/docs/steps/10-任务取消超时与重试.md

@@ -0,0 +1,28 @@
+# 10：任务取消、超时与重试
+
+## 目标
+
+让子 Agent 能够执行总控的最小控制协议：收到带截止时间的任务后进入生命周期；收到取消指令或达到截止时间后停止本地演示执行器并回报终态。
+
+## 已实现
+
+1. `task_dispatch` 接收无进展截止时间 `deadline_at`，并传给本地任务执行器；进入“执行中”阶段会使用同一窗口重新开始本地无进展计时。
+2. 新增 `task_cancel` 消息处理，携带任务 ID 与取消原因。
+3. 本地执行器对每项任务维护开始、完成和截止时间计时器；取消或超时会停止其余计时器，防止稍后错误回报“已完成”。
+4. 取消回报状态为 `cancelled`，连续无进展达到截止时间的回报状态为 `timed_out`。
+5. 演示执行器保留约 1.5 秒可见执行窗口，便于实际验证取消与超时；它仍不执行模型、Shell、浏览器或本机工具。
+
+## 状态规则
+
+`accepted → running → completed` 是正常路径；`accepted/running → cancelled` 和 `accepted/running → timed_out` 是终止路径。终态任务不会再次启动或完成。
+
+## 验收
+
+1. 总控下发 1 秒超时测试任务，Agent 应回报 `timed_out`。
+2. 总控在任务运行中发送取消，Agent 应回报 `cancelled`，且不再回报 `completed`。
+3. 重试由总控创建新的任务 ID；Agent 应把它视为独立任务正常执行。
+4. 自动化测试同时覆盖取消与过期截止时间。
+
+## 当前边界与下一步
+
+待发送任务事件目前只驻留在进程内存：如果 Agent 在断线期间退出，尚未回传的事件不会在下次启动时自动补传。下一阶段将把事件外盒（outbox）、确认序号和重连回放落到本地数据库。

mulit_agent/docs/steps/11-OpenAI兼容LLM配置与执行.md

@@ -0,0 +1,15 @@
+# 11：OpenAI 兼容 LLM 配置与执行（已调整为总控下发）
+
+1. Agent 配对窗口不再提供 API 地址、模型名称或 API Key 输入框；这些值由总控按 Agent 或 Agent 组下发。地址和模型名不写入可迁移的 `config/agent-config.json`。
+2. 实现 `/chat/completions` 协议适配器，支持 OpenAI、DeepSeek、OpenRouter 及其他兼容该协议的服务。请求使用非流式文本完成格式，任务正文作为用户消息传入。
+3. `TaskExecutor` 在任务进入运行状态后改为后台调用 Provider；成功时将模型文本作为 `completed` 输出回传，失败时以 `failed` 状态和安全错误信息回传。
+4. 当前实现保留 Provider 适配器与测试，但暂不从本地窗口启用；正式 `AgentService` 将在收到并确认总控配置快照后注入真实 Provider。
+5. 验证配置文件不含 Key、Provider 请求含正确地址/认证头/模型名，以及真实执行器的完整任务事件顺序。
+
+## 当前边界
+
+- 支持普通文本完成，不支持流式片段、函数工具调用或多轮上下文；这些属于后续步骤。
+- 取消与超时会立即停止任务状态回传；已发出的 HTTP 请求由后台线程等待至服务端返回或 90 秒网络超时，结果会被丢弃，不会覆盖终态。
+- 优先使用 `https://`。`http://` 只可用于可信本机或内网模型服务，因为 API Key 和任务正文会明文传输。
+
+验收：总控下发并更新配置快照后，Agent 可执行模型任务并确认应用版本；Key 不存在于 JSON、窗口、日志或任务事件中。

mulit_agent/docs/steps/12-总控配置应用与守护服务.md

@@ -0,0 +1,9 @@
+# 12：总控配置应用与守护服务
+
+1. 已完成基础版：接收已认证 TLS/WSS 会话内带版本号的总控 LLM 配置快照；拒绝低版本配置。签名、目标标签和包哈希将在 Skill/MCP 配置阶段增加。
+2. 已完成：原子应用 Provider、模型和密钥；非敏感项进入本机受控状态，Key 进入 Windows 凭据管理器；窗口、JSON、日志和任务事件均不保存 Key。
+3. 已完成：上报已应用或失败回执；断线期间保留最后已确认配置，重启后自动恢复运行器，重连后由总控再次校准。
+4. 接收经校验的 Skill/MCP 包并在受控目录安装、启用、回滚；不执行未经签名或超出本机策略的包。
+5. 由单独安装的 Agent 守护服务处理启动、停止、重启和升级请求；托盘进程只负责执行与展示状态。
+
+验收：重新配对后的 Agent 能自动获取其总控配置；离线重连后补齐版本；总控发起重启后守护服务成功拉起 Agent 并回报在线。

mulit_agent/docs/steps/13-图片附件模型闭环.md

@@ -0,0 +1,9 @@
+# 13：图片附件与视觉模型闭环
+
+## 已完成范围
+
+1. `ControllerSession` 严格校验 `task_dispatch.attachments` 的类型、MIME、数量和解码后总大小；无效消息只拒绝该任务，不影响 WSS 会话。
+2. 附件仅在执行内存中传递，不写入本地任务库、事件、日志、错误或模型结果。
+3. OpenAI 兼容请求使用 `text` 与 `image_url`，Anthropic 使用 base64 `image` 内容块，Gemini 使用 `inline_data`。
+4. 未显式配置视觉能力的模型会安全失败，不能把图片任务降级为文本。
+5. 已部署的受控桌面文件工具可在新建桌面直接子文件夹时，将本任务附件以固定安全文件名保存其中；不允许调用方指定路径、覆盖文件或访问桌面外位置。

mulit_agent/docs/steps/14-默认完全访问执行器.md

@@ -0,0 +1,18 @@
+# 14. 默认完全访问执行器
+
+## 目标
+
+新版 Agent 默认运行在用户明确授权的完全访问模式。该模式可以在 Agent 所在 Windows 电脑操作文件、程序、网络和桌面应用，不再以“桌面直接子文件夹”作为权限边界。
+
+## 实现边界
+
+1. 总控仍只能通过已配对、TLS 固定指纹的 WSS 会话下发任务；总控不直接打开 Agent 的命令行或文件系统。
+2. Agent 将本机 PowerShell 执行能力作为模型工具 `run_powershell` 提供。OpenAI 兼容、Anthropic、Gemini 都使用各自的原生工具调用协议，并最多循环 12 次。
+3. 已实际调用本机命令的任务回传 `execution=full-access`；纯模型回答仍标记为 `llm`，不把计划文字误称为外部操作成功。
+4. 取消会终止 Agent 跟踪的执行进程；任务生命周期、无进展超时与重试保持原有语义。
+5. 命令输出在离开 Agent 前脱敏常见 API Key、密码、令牌和凭据字段；完整命令和敏感数据不写入总控审计、普通日志或任务结果。
+6. 图片附件需要本机操作时，只在当前任务期间暂存为安全清洗后的原文件名；模型可取得实际临时路径，任务完成、失败或取消后自动删除暂存目录。
+
+## 兼容性
+
+旧 `desktop-filesystem` MCP 不删除，供旧安装包和历史部署回执使用；新版完整访问模式默认不再由它拦截本机任务。ImageForge 仍需作为独立 MCP 工具包迁入，不能通过旧 FastAPI 插件文件直接安装。

mulit_agent/docs/steps/README.md

@@ -0,0 +1,17 @@
+# mulit_agent 实施步骤索引
+
+按编号顺序执行。每一步均以可独立测试、可回滚为边界；共享协议的变更必须先在两端契约测试中通过，再合入任一程序。
+
+1. [01-项目骨架与运行模式](01-项目骨架与运行模式.md)
+2. [02-协议会话与安全](02-协议会话与安全.md)
+3. [03-本地状态与任务生命周期](03-本地状态与任务生命周期.md)
+4. [04-模型执行与流式结果](04-模型执行与流式结果.md)
+5. [05-技能插件工具与隔离](05-技能插件工具与隔离.md)
+6. [06-PySide6运行界面](06-PySide6运行界面.md)
+7. [07-兼容迁移与故障恢复](07-兼容迁移与故障恢复.md)
+8. [08-测试打包与交付](08-测试打包与交付.md)
+9. [09-单Agent任务闭环](09-单Agent任务闭环.md)
+10. [10-任务取消超时与重试](10-任务取消超时与重试.md)
+11. [11-OpenAI兼容LLM配置与执行](11-OpenAI兼容LLM配置与执行.md)
+12. [12-总控配置应用与守护服务](12-总控配置应用与守护服务.md)
+13. [13-图片附件模型闭环](13-图片附件模型闭环.md)