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

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)