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

controller/docs/steps/01-项目骨架与运行基线.md

@@ -0,0 +1,9 @@
+# 01：项目骨架与运行基线
+
+1. 在 `controller` 建立蓝图所列分层目录、应用入口、依赖锁定和测试目录；所有模块可从入口启动。
+2. 安装并固定 Go、Wails2、React/TypeScript、SQLite 驱动和测试依赖；在目标 Windows 环境验证 WebView2 运行时。
+3. 建立 `AppConfig`，区分开发/测试/生产配置，支持数据目录、控制端 ID、监听地址、日志级别和传输超时；发行目录的 `config/controller-config.json` 优先加载并由设置页原子回写，禁止把密钥放进该文件、仓库或默认配置。
+4. 创建最小 Wails `App`、React 管理界面、异常提示和优雅退出骨架；Go 控制平面通过窄 Wails 绑定接入。
+5. 配置 lint、类型检查、单元测试和打包命令，提供一条本地启动命令。
+
+验收：空壳程序可打开并正常退出；配置错误会给出可理解的信息；测试、格式检查和类型检查可在干净环境运行。

controller/docs/steps/02-共享协议与安全边界.md

@@ -0,0 +1,9 @@
+# 02：共享协议与安全边界
+
+1. 新建独立的共享协议包，定义 Pydantic 消息模型、状态枚举、错误码和 `/api/v1` 路由常量；供 `controller` 和 `mulit_agent` 共同依赖。
+2. 实现注册、心跳、能力、任务、取消、进度、流片段、结果和配置消息；每种消息都含版本、消息 ID、关联 ID 和 UTC 时间。
+3. 为消息建立 JSON Schema 和正反例测试；未知字段、错误版本和无效状态转换必须拒绝并返回标准错误。
+4. 实现 Agent 凭据签发、HMAC/短期令牌校验、请求时间窗、重放去重与凭据撤销；密钥仅经系统凭据库或加密存储读取。
+5. 明确附件、上下文和日志的大小限制、脱敏规则及权限校验点。
+
+验收：两端可用同一协议包序列化和反序列化全部基础消息；篡改、过期、重放和越权请求都有自动化测试。

controller/docs/steps/03-存储与领域模型.md

@@ -0,0 +1,9 @@
+# 03：存储与领域模型
+
+1. 设计并创建版本化迁移：Agent、能力快照、任务、任务节点、工作流、事件、审计、用户和 UI 偏好。
+2. 定义领域实体和值对象，使用显式状态转换函数约束 Agent、任务和工作流状态，禁止在界面层直接拼写状态字符串。
+3. 实现 Repository 和事务边界；任务状态、事件与审计记录必须同事务落库。
+4. 实现启动恢复：将中断任务标记为待确认，向在线 Agent 查询最终状态后再决定恢复、重试或失败。
+5. 提供备份、迁移前检查和失败回滚策略；记录数据保留期限。
+
+验收：新库和升级库均可迁移；重启后任务和审计可查询；模拟中途退出不会产生孤儿节点或矛盾状态。

controller/docs/steps/04-通信与Agent注册.md

@@ -0,0 +1,9 @@
+# 04：通信与 Agent 注册
+
+1. 实现 `CommunicationService`：HTTP 客户端、WebSocket 客户端、连接状态、超时、退避重连、确认和去重。
+2. 实现注册/撤销、凭据签发、`agent.hello`、心跳和能力同步用例；将在线判定和最后活动时间持久化。
+3. 定义 `AgentLifecyclePort`，提供本地、Docker、远程等适配器接口；首版可先实现远程连接适配器。
+4. 将网络事件转换为 Go 应用层状态，React 前端通过定时查询或受控事件订阅更新 ViewModel；网络 goroutine 不得直接访问 WebView。
+5. 加入连接诊断页所需的最近错误、延迟、协议版本和重连次数数据。
+
+验收：可在不重启 UI 的情况下注册、断开、重连和撤销测试 Agent；重复心跳和乱序事件不会错误覆盖较新的状态。

controller/docs/steps/05-任务调度与编排.md

@@ -0,0 +1,9 @@
+# 05：任务调度与编排
+
+1. 实现创建、验证、排队、派发、取消、重试和查询任务的应用服务，所有请求使用幂等键。
+2. 先完成单 Agent 指派和流式事件归档，再增加并行任务和结果汇总；汇总模型调用必须是可替换策略。
+3. 引入 DAG 工作流模型，验证无环、依赖已满足、输入映射合法和失败传播规则。
+4. 实现超时、断线、Agent 拒绝、部分成功和控制端重启恢复路径；明确每种情况是否重试及最大次数。
+5. 在任务详情中提供事件时间线、节点状态、输出、错误和人工取消入口。
+
+验收：单任务、并行任务和三节点 DAG 在模拟传输层中可重复执行；取消与重试不会重复执行同一次尝试。

controller/docs/steps/06-Wails2管理界面.md

@@ -0,0 +1,9 @@
+# 06：Wails2 管理界面
+
+1. 完成应用外壳、导航、主题、全局错误提示和可访问性基础；文本、日期和状态颜色统一由展示层映射。
+2. 实现概览页：在线数、运行任务、失败告警和最近事件；使用定时刷新加事件推送，避免阻塞 UI。
+3. 实现 Agent 列表和详情：注册、撤销、连接诊断、能力、健康信息和配置下发入口。
+4. 实现任务页面：创建、选择 Agent、任务流、取消、重试、结果和会话历史。
+5. 实现工作流、设置和审计页；危险操作必须二次确认并显示影响对象。
+
+验收：在 100 个模拟 Agent、持续流式事件下界面仍可交互；所有关键动作都有加载、成功和失败状态。

controller/docs/steps/07-迁移兼容与可靠性.md

@@ -0,0 +1,9 @@
+# 07：迁移兼容与可靠性
+
+1. 盘点现有 Dashboard 的 Agent、任务、编排、工作流、配置和审计数据，编写字段映射与不可迁移项清单。
+2. 为旧 FastAPI Agent 实现协议兼容适配器或网关；功能开关确保每个 Agent 同时只接收一个控制端的变更命令。
+3. 制定导出、备份、导入、校验、灰度切换和回退流程，并在副本数据库演练。
+4. 对网络分区、重复投递、进程崩溃、慢 Agent 和版本不兼容做故障注入测试。
+5. 增加运行指标：连接率、派发延迟、任务耗时、失败率、重试率和 UI 错误率。
+
+验收：可将代表性旧数据导入新端并核对数量与关键状态；失败切换可在不丢失任务记录的前提下回退。

controller/docs/steps/08-测试发布与运维.md

@@ -0,0 +1,9 @@
+# 08：测试发布与运维
+
+1. 建立 Go 领域单测、协议契约测试、WSS 集成测试、React 构建测试和端到端演练；关键状态机覆盖正常与异常路径。
+2. 配置 CI：依赖安装、静态检查、测试、协议兼容矩阵和 Windows 打包验证。
+3. 使用 PyInstaller 或同等方案打包 Windows 安装物，确定数据目录、升级策略、签名和卸载时的数据保留策略。
+4. 编写管理员手册、故障排查、备份恢复、密钥轮换、日志收集和版本兼容说明。
+5. 以试点 Agent 完成发布演练，设定回滚阈值和上线后监控窗口。
+
+验收：从空白 Windows 环境可安装、连接测试 Agent、执行任务并升级；发布包附带校验、版本和回滚说明。

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

@@ -0,0 +1,26 @@
+# 09：单 Agent 任务闭环
+
+## 本阶段目标
+
+让总控可以选择一个已认证且在线的子 Agent，下发单条文本任务，并持续展示 `queued → accepted → running → completed/failed` 的状态和最终结果。
+
+## 已实现范围
+
+1. 控制端 SQLite 新增 `task_runs` 与 `task_events`，保存任务、状态变更、输出和错误。
+2. 仅向当前 WSS 会话中已认证的在线 Agent 下发 `task_dispatch` 消息；消息携带协议版本、任务 ID、文本指令和 UTC 时间。
+3. 控制端只接受来自该任务目标 Agent 的 `task_event`，并忽略终态任务的重复事件。
+4. Wails React 总控界面提供在线 Agent 选择、任务输入、下发按钮，以及最近任务的状态与结果显示；Go 只向前端暴露这些受限用例。
+5. 当 WSS 连接在下发瞬间断开时，任务会标记为失败而非伪装为已执行。
+
+## 本阶段刻意限制
+
+- 这是单 Agent、文本任务闭环；尚不支持取消、重试、工作流、附件或多 Agent 编排。
+- 子 Agent 目前运行安全的内置演示执行器，不会调用 LLM、Shell、浏览器、文件或任何高风险工具。
+- 模型 Provider 的 API 密钥和工具授权策略将在后续阶段单独设计，不能为了演示而写入任务数据库或配置文件。
+
+## 验收步骤
+
+1. 启动总控，完成一个 Agent 的配对并确认其显示为在线。
+2. 在“单 Agent 任务”区域选择该 Agent，输入任意文本并下发。
+3. 确认任务依次显示为 `accepted`、`running`、`completed`，且出现内置演示执行器的结果。
+4. 重启总控，确认最近任务仍显示在任务记录中。

controller/docs/steps/10-Wails2迁移与信息架构.md

@@ -0,0 +1,20 @@
+# 10：Wails2 迁移与信息架构
+
+## 已完成迁移
+
+1. `controller` 根目录已切换为 Wails2 工程：Go 负责控制平面，React/TypeScript 负责界面。
+2. 旧 PySide6 总控入口、项目定义、源码与测试已从工作根目录移除；旧发布产物仅保留在隐藏归档目录，不能被默认构建入口使用。
+3. `build.ps1` 和 `build.bat` 默认构建 Wails 发布包 `build/bin/MultiClawController.exe`。
+4. 当前 Wails 控制平面已覆盖首次配对、TLS 指纹校验、WSS 心跳、单 Agent 任务下发和最终结果回传。
+
+## 当前界面架构
+
+- **概览**：总控状态、在线 Agent、运行任务、当前电脑 IP 和 Agent 连接地址；不展示配对码。
+- **任务**：选择在线 Agent、下发文本任务、查看持久化的最近任务结果。
+- **安全与配对**：沿用旧 Dashboard 的“密钥独立页面”原则，生成仅可使用一次、十分钟有效的配对码。该配对码不同于旧系统的长期 API Key，包含 TLS 指纹且不写入界面持久化状态。
+
+## 验收
+
+1. 启动 `build/bin/MultiClawController.exe`，确认概览显示本机 IP。
+2. 在“安全与配对”生成代码，并在子 Agent 使用该 IP/连接地址完成配对。
+3. 在“任务”页面向在线 Agent 下发文本任务，确认状态与结果回传。

controller/docs/steps/11-Agent管理与配对生命周期.md

@@ -0,0 +1,26 @@
+# 11：Agent 管理与配对生命周期
+
+## 本阶段目标
+
+让 Wails 总控能管理多个子 Agent，而不仅是显示在线数量。
+
+## 已实现范围
+
+1. 新增独立 **Agent** 页面，列出当前在线和离线的 Agent。
+2. 每个 Agent 显示不可变 ID、显示名称、状态和最后心跳时间。
+3. 允许修改显示名称，不改变 Agent 身份或凭据。
+4. “撤销配对”会立即关闭当前 WSS 会话并删除配对记录；Agent 再次连接时会被拒绝，必须重新配对。
+5. “添加 / 重新配对”只跳转到独立的“安全与配对”页面，不在 Agent 列表或概览页泄露配对码。
+
+## 安全边界
+
+- 前端只有 Agent 查询、改名和撤销三个受限绑定，不可读到凭据哈希、TLS 私钥或数据库原始内容。
+- 撤销会移除 Agent 配对记录，但不删除已有任务与审计历史。
+- 已移除的 Agent 不能通过旧凭据认证。
+
+## 验收
+
+1. 完成一个 Agent 的配对后，确认其出现在 Agent 页面并显示在线。
+2. 修改名称并刷新，确认名称被持久化。
+3. 点击“撤销配对”并确认，Agent 卡片立即消失且连接断开。
+4. 重启 Agent，确认旧凭据被拒绝；生成新配对码后可作为新的 Agent 加入。

controller/docs/steps/12-任务取消超时与重试.md

@@ -0,0 +1,39 @@
+# 12：任务取消、超时与重试
+
+## 目标
+
+让总控对单 Agent 任务拥有最小、可审计的控制闭环：下发时设定超时；执行中可以取消；失败、取消或超时后可以创建一次新的尝试。原始任务记录始终保留。
+
+## 已实现
+
+1. `task_runs` 增加 `deadline_at`、`timeout_seconds`、`attempt` 与 `retry_of` 字段；旧数据库通过增量迁移保持可打开。
+2. 下发的 `task_dispatch` 携带 ISO 8601 的“无进展截止时间”和尝试次数。Agent 回传 `accepted` 或 `running` 等有效进展后，总控会以该任务的超时窗口重新计算截止时间。
+3. 总控在界面轮询快照/任务列表时检查连续无进展的任务：将状态置为 `timed_out`、保存事件，并向已连接的 Agent 发送 `task_cancel`。
+4. 新任务默认使用 5 分钟无进展超时；任务页可选择 5、15、30 分钟或 1 小时。活动任务可取消。
+5. 只有 `failed`、`cancelled`、`timed_out` 的任务显示“重试”。重试会生成新的任务 ID 和新的尝试次数，并以 `retry_of` 指回原始任务，绝不覆写旧记录。
+
+## 协议约定
+
+取消消息：
+
+```json
+{
+  "type": "task_cancel",
+  "schema_version": 1,
+  "task_id": "...",
+  "reason": "由总控取消"
+}
+```
+
+Agent 必须以普通 `task_event` 回报最终状态 `cancelled` 或 `timed_out`；总控不把“取消指令已发出”误当作 Agent 已停止。
+
+## 验收
+
+1. 下发任务后确认 Agent 回传“已接收”或“执行中”，任务详情中的“下次无进展超时”应向后刷新。
+2. 在演示任务的执行窗口内点击“取消”，任务应最终显示“已取消”。
+3. 对已取消或已超时任务点击“重试”，列表应出现新的任务 ID 与“第 2 次”，旧记录仍存在。
+4. 已完成任务不应提供重试操作。
+
+## 当前边界与下一步
+
+当前 Agent 在连接中断时只在内存中暂存待发送事件；进程重启后的事件补传、任务幂等恢复和断线重连回放尚未实现。这些属于下一阶段的可靠性工作，不能作为本步骤已完成的能力对外承诺。

controller/docs/steps/13-集中配置与远程运维.md

@@ -0,0 +1,10 @@
+# 13：集中配置与远程运维
+
+1. 已完成：在总控建立 Provider、模型和 API Key 的配置档数据模型；支持向指定 Agent 下发。Provider 预设覆盖主流云端服务商和常见本地运行时，并允许自定义 OpenAI 兼容地址。
+2. 已完成：API Key 通过 Windows DPAPI 加密后存入总控本地数据库，业务查询和界面均不读取或回显明文；仅在已认证 TLS/WSS 会话内发送给目标 Agent。
+3. 已完成基础版：实现带版本的 config_snapshot / config_ack 协议。Agent 校验 LLM 配置、写入本机凭据库、原子切换运行器，并回传已应用或失败原因；离线 Agent 认证连接后自动补齐。后续补充签名、目标标签组和幂等 ID。
+4. 将总控定时器持久化并由总控触发任务下发；Agent 不保存独立 cron。
+5. 为 Skill/MCP 建立包仓库、哈希校验、权限清单、目标部署状态和回滚版本；Agent 只接受经总控签名的包。
+6. 为每台目标机器提供独立安装的 Agent 守护服务；总控可发送启动、停止、重启与升级命令，并记录确认与失败原因。
+
+验收：管理员只在总控完成一次配置，即可推送给多个指定 Agent；离线 Agent 重连后补齐配置；任意配置、部署和重启动作均可追踪。

controller/docs/steps/14-MCP受控桌面工具闭环.md

@@ -0,0 +1,19 @@
+# 14：MCP 受控桌面工具闭环
+
+## 已完成范围
+
+1. 总控可为指定 Agent 启用内置 `desktop-filesystem` MCP；分配和单调递增的部署版本持久化在总控数据库，状态为 `pending`、`sent`、`applied` 或 `failed`。
+2. 在线 Agent 会立即收到带部署版本的认证 WSS 快照；离线 Agent 在认证重连后自动重收同一持久化分配。Agent 在本机保存启用状态和版本，并对重复快照幂等回执。
+3. 该工具只识别明确的“在桌面创建文件夹”任务，只能创建桌面直接子文件夹；已存在目标、路径穿越或非法名称会失败，绝不覆盖。命中该工具意图但工具未部署/未应用时也会明确失败，绝不降级给 LLM。
+4. 总控审计记录部署请求、快照下发、Agent 回执和真实工具结果，且不记录 API Key、配对凭据或完整任务提示词。
+5. Agent 管理页显示每台 Agent 的 LLM、Skill 与 MCP 应用状态；任务输出和审计均会移除模型 `<think>` 内容。
+
+## 验证
+
+- Go WSS 协议测试覆盖 MCP 下发、持久化版本、过期回执忽略、认证重连重发、回执恢复、任务结果回传、审计和 `<think>` 过滤。
+- 子 Agent pytest 覆盖桌面文件夹创建、未部署拒绝而不调用 LLM、路径穿越拒绝、版本持久化与重复快照回执。
+- Windows 端到端手工验收需使用唯一目录名，并确认总控的任务详情、审计记录和 Agent 本地状态均为本次部署版本；不得以 Skill 文本或 LLM 回复替代真实目录创建证据。
+
+## 下一步
+
+将单一内置 MCP 升级为带版本、权限清单、哈希、签名和回滚的受控工具仓库；插件运行时扩展仍保持独立入口。

controller/docs/steps/15-Agent规模化管理.md

@@ -0,0 +1,19 @@
+# 15：Agent 规模化管理
+
+## 已实现范围
+
+1. Agent 目录由总控 SQLite 服务端分页，页大小限制为 1 至 50；名称搜索使用参数化 `LIKE` 查询并转义通配符。
+2. 支持组合筛选在线/离线、MCP、LLM 和 Skill 状态。Skill 状态会汇总为未选择、等待连接、下发中、已应用或失败；任一 Skill 失败优先显示失败。
+3. Agent 详情返回受限的最近任务、最近安全审计、部署历史和当前失败原因。详情记录有数量上限，且失败文本经过显示层脱敏；不返回 API Key、配对凭据或内部推理。
+4. 配置下发的认证确认优先于异步 LLM、Skill、MCP 快照，避免重连后出现未认证配置快照。
+
+## 回归范围
+
+- Go 测试覆盖分页、名称和状态组合筛选、非法筛选拒绝、失败原因脱敏，以及 Agent 详情的任务、审计和部署轨迹。
+- 原有 WSS/MCP 重连补发与幂等回执测试继续通过。
+
+## 验收
+
+1. 在“智能体”页面用名称与任意状态组合筛选，确认分页总数和卡片状态来自总控服务端。
+2. 打开任意卡片，确认可见最近任务、审计、部署历史和失败原因；敏感字段不得显示。
+3. 离线 Agent 的下发显示等待连接，重连后先收到认证确认，再恢复持久化配置快照。

controller/docs/steps/16-审计日志基础设施.md

@@ -0,0 +1,14 @@
+# 16：审计日志基础设施
+
+## 已实现范围
+
+1. 审计事件统一包含时间、操作者、目标 Agent、资源类型、动作、结果和安全摘要；保留旧字段，现有数据库会以加列和回填方式升级，不删除历史。
+2. 审计页面由总控服务端分页和筛选，支持按目标 Agent、资源类型、结果、起止时间查询。
+3. 已覆盖的实际链路包括：配对码创建、配对完成/撤销、Agent 改名、LLM 配置保存与下发、Skill 包保存与下发、MCP 部署与工具结果、任务创建/状态变更/取消/重试/历史清除。
+4. 所有详情经过安全摘要处理，去除内部推理并脱敏 API Key、密码、令牌、凭据等字段；任务审计不记录完整任务正文。
+5. 模板、定时任务、委派、插件包和远程运维的资源类型已预留。它们尚未实现业务动作，后续对应阶段必须调用统一 `recordAudit`，不得创建伪造审计记录。
+
+## 验证
+
+- Go 回归覆盖统一字段、按 Agent/资源/结果筛选、分页、时间格式校验和敏感详情脱敏。
+- 清除任务历史的回归继续验证：任务和时间线可删除，审计记录必须保留。

controller/docs/steps/17-多Agent并发任务中心.md

@@ -0,0 +1,25 @@
+# 17：多 Agent 并发任务中心
+
+## 目标
+
+让一个操作者可在总控一次填写多条互不依赖的任务，分别指定目标机器并同时下发；每台机器的执行状态与结果在同一页可见。
+
+## 已实现范围
+
+1. 总控增加 `CreateTasks` 受限用例。每条输入仅包含目标 Agent、文本任务和超时；一次最多 20 条。
+2. 批量下发采用逐条独立结果：一条目标离线或参数无效时，仅该行返回可读错误，其他有效行仍会创建、持久化并下发。
+3. 控制台任务区支持添加、移除和编辑多条任务草稿；每条可单独选择在线 Agent 和超时。
+4. 新增“各机器任务状态”看板：按在线 Agent 汇总近期任务、运行中的数量和最新一条状态/结果，点击可打开原有完整时间线。
+5. 既有取消、重试、超时、结果回传和任务历史能力保持不变。任务没有被改成广播；相同行中填写同一台 Agent 也仍是多个独立任务。
+
+## 验证
+
+- Go WSS 回归覆盖两个任务均成功下发，同时验证其中一条失败不会阻止其它任务、空批量会被拒绝。
+- 子 Agent 回归覆盖两个独立模型任务同时进入执行，确认执行器不会把任务串行化。
+- Wails 前端绑定和生产构建通过；两端 Windows EXE 已重新生成。
+
+## 当前边界
+
+- 看板展示总控最近 24 条任务，适合日常多机派发与结果查看；它不是工作流或定时任务系统。
+- 任务仍只会下发给当前在线 Agent。离线任务队列与进程重启后的事件外盒仍是后续可靠性工作。
+- 当前不设置人为并发上限；操作时应根据每台机器的模型、CPU 和内存能力控制同机任务数量。

controller/docs/steps/18-自然多Agent指派.md

@@ -0,0 +1,27 @@
+# 18：自然多 Agent 指派
+
+## 目标
+
+在不改变既有 WSS/TLS、任务取消、超时、重试、LLM、Skill 或受控 MCP 闭环的前提下，提供两个明确分离的任务入口：单独指派，以及公共 `@Agent名称` 批量指派。
+
+## 已实现范围
+
+1. 主导航依次提供“控制台、智能体、批量指派、单独指派”；批量指派不再放入控制台。控制台仅保留总览、各机器运行状态与统一任务记录。
+2. “单独指派”页面必须下拉选择一台在线 Agent，随后下发一条独立文本任务；状态、结果、失败、取消和重试仍在统一任务记录中处理。
+3. “批量指派”页面只提供公共 `@` 输入区，避免与“单独指派”重复。输入 `@` 会弹出在线 Agent 候选，支持名称过滤、方向键、回车确认和 Esc 关闭；点击在线 Agent 仍可插入 `@名称`，不依赖操作者记住显示名称。
+4. 每个非空行是一组独立任务。`@设计机 在桌面新建文件夹` 与下一行 `@文案机 新建文本文档` 会分别下发不同任务；`@设计机 @文案机 做发布检查` 会向两台机器创建两条内容相同的独立任务。
+5. 解析仅接受已登记 Agent 的完整显示名称和边界；未知名称、重名、离线目标、缺少任务内容和未指定目标均会显示逐项原因，绝不根据前缀或相似名称误发到其它机器。
+6. 两种入口都复用现有 `task_dispatch`、任务持久化和执行状态机，不引入对话上下文、附件、任意 Shell、远程终端或旧 FastAPI Spawn Agent。
+7. 用户任务在持久化或下发前拒绝 API Key、配对凭据、账号密码及 `<think>` 内部推理，避免其进入界面、任务记录、日志、结果或审计摘要。
+8. 新任务默认使用 5 分钟无进展超时；Agent 回传有效执行进展时，总控会续期。可按任务选择更长窗口。
+
+## 验证
+
+- Go 回归覆盖按行 `@` 拆分、同一行多 Agent 的相同任务、未知名称、重名、离线目标和无目标文本的安全拒绝。
+- 子 Agent pytest 覆盖独立文本任务；既有并发、取消、超时和 MCP 测试保留。
+- `go test -count=1 ./...`、前端 `npm run build`、子 Agent `pytest` 与 `ruff` 均通过后，再重新生成两端 Windows EXE。
+
+## 当前边界
+
+- `@` 仅用于一次性批量任务调度，不会自动把未标注文本广播给任何 Agent；非空行必须以一个或多个 `@Agent名称` 开始。
+- 不支持附件、任意 Shell、远程终端、旧 FastAPI Spawn Agent 或跨 Agent 共享上下文。

controller/docs/steps/19-图片附件任务闭环.md

@@ -0,0 +1,13 @@
+# 19：图片附件任务闭环
+
+## 已完成范围
+
+1. 批量 `@` 指派和单独指派均支持粘贴或选择 PNG、JPEG、GIF、WebP；单项任务最多 10 张、原始总大小最多 12 MiB。
+2. 多条有效批量任务带图时，每行必须明确引用“图片 1”等编号；同一行多个 Agent 共享其编号图片，未知、离线、重名和未指定目标不会收到图片。
+3. 图片只保存在总控本地 `task_images`，通过目标 Agent 的认证 WSS `task_dispatch.attachments` 下发；任务详情显示数量与缩略图，重试复用原图，清除已结束任务同时删除附件。
+4. 审计、普通日志、任务文本、结果和错误均不写入图片 Base64。
+5. 批量与单独指派页均显示本页最近任务的实时状态；任务详情在附件尚未加载时保持可用，不会造成页面空白。
+
+## 验证
+
+- 未配置“支持图片理解”的模型会安全失败，绝不降级为纯文本。

controller/docs/steps/20-默认完全访问Agent.md

@@ -0,0 +1,15 @@
+# 20. 默认完全访问 Agent
+
+## 产品决定
+
+用户明确要求新版 Agent 默认拥有其所在电脑的完全访问执行能力。总控的“插件与 MCP 工具”与 Agent 详情页显示此状态；旧“桌面文件工具已应用”仅作为兼容部署记录，不代表新版权限上限。
+
+## 可观察性
+
+- Agent 任务若实际使用本机执行工具，会回传 `full-access` 执行来源并显示为“完全访问 Agent”。
+- 任务、日志和审计仍不保存密钥、密码、凭据、附件 Base64 或模型内部推理。
+- 配对、TLS 指纹、取消、无进展超时、重试和断线语义保持不变。
+
+## 非目标
+
+总控不直接连接 Agent 的本机命令行或文件系统。ImageForge 等第三方桌面应用仍需由 Agent 本机的独立 MCP 客户端连接，不能复制旧 FastAPI 插件到总控。

controller/docs/steps/README.md

@@ -0,0 +1,23 @@
+# Controller 实施步骤索引
+
+按编号顺序执行本目录中的文档。每一步完成后应通过该文档的验收项并提交一次可回滚的变更；不要在协议、持久化和并发模型未确定前开始堆叠界面功能。
+
+1. [01-项目骨架与运行基线](01-项目骨架与运行基线.md)
+2. [02-共享协议与安全边界](02-共享协议与安全边界.md)
+3. [03-存储与领域模型](03-存储与领域模型.md)
+4. [04-通信与Agent注册](04-通信与Agent注册.md)
+5. [05-任务调度与编排](05-任务调度与编排.md)
+6. [06-Wails2管理界面](06-Wails2管理界面.md)
+7. [07-迁移兼容与可靠性](07-迁移兼容与可靠性.md)
+8. [08-测试发布与运维](08-测试发布与运维.md)
+9. [09-单Agent任务闭环](09-单Agent任务闭环.md)
+10. [10-Wails2迁移与信息架构](10-Wails2迁移与信息架构.md)
+11. [11-Agent管理与配对生命周期](11-Agent管理与配对生命周期.md)
+12. [12-任务取消超时与重试](12-任务取消超时与重试.md)
+13. [13-集中配置与远程运维](13-集中配置与远程运维.md)
+14. [14-MCP受控桌面工具闭环](14-MCP受控桌面工具闭环.md)
+15. [15-Agent规模化管理](15-Agent规模化管理.md)
+16. [16-审计日志基础设施](16-审计日志基础设施.md)
+17. [17-多Agent并发任务中心](17-多Agent并发任务中心.md)
+18. [18-自然多Agent指派](18-自然多Agent指派.md)
+19. [19-图片附件任务闭环](19-图片附件任务闭环.md)