必须补齐的七项要求

文档性质：补编设计稿；编写日期：2026-10-20。当前实施状态统一见阅读导航。本文件规定后续实施和验收要求，不表示相关控制已实现、测试已通过或系统已可生产使用。

1. 依据、适用范围与判定方式

本次未找到原“必须补齐的七项要求”正文，因此依据根目录 AGENTS.md重新归纳为七个门禁领域。下列七项不声称与缺失原文的编号、措辞或分组相同；后续找到历史资料时保留原件并记录差异，以根目录约定解决已明确的冲突。

首个交付闭环采用单 API 实例、MySQL 8.4 和 Windows Agent；Redis、额外任务队列不作为安全控制生效的前提。本文不授权实现后续模块、操作真实设备或部署生产。架构、状态转换和接口以正式开发规格为准。

时间、容量、速率、重试、保留期、备份目标和部署规模等参数只在设计决策与参数基线维护。本文引用相应参数，不设另一套默认数值。参数尚未确定时，相应验收结论为“未执行”或“阻塞”，不能根据测试现场临时选择一个宽松值后宣布通过。

每个门禁同时检查实现、异常路径和运行证据：

• 已启用能力必须通过全部适用用例，不能只验证正常流程。
• 未启用能力必须验证服务器入口、Agent 分发、协议类型和执行适配器的关闭边界；仅隐藏 UI 不算禁用。
• 缺少所需真实环境时记录具体未验证范围。模拟测试不能替代 MySQL 8.4 集成测试、真实 Windows 执行或真实恢复演练。
• 测试失败、证据不足、有效期内的测试版本与发布版本不一致，均不能将门禁标为通过。
• 开发闭环验收与生产发布验收分开记录。生产要求不能因开发演示已成功而被省略。

用例和证据索引见验收用例与证据矩阵。

2. 门禁一：身份、对象授权与撤销

必须实现的控制

1. 禁用公开注册。首个管理员通过一次性初始化创建，初始化完成后关闭可重复创建入口；没有内置管理员密码。用户管理、重置访问和授权管理仅允许 super_admin。
2. 登录具备限速、失败响应和会话撤销。生产管理员启用 MFA；恢复流程同样具有身份核验和审计，不能成为绕过 MFA 的接口。使用 Cookie 会话时设置 Secure、HttpOnly、SameSite，并落实适用的 CSRF 防护。
3. 服务器统一检查用户是否有效、角色是否允许、对象是否可见、设备授权和能力授权是否有效。客户端提供的所有者字段不能改变归属；管理员路径、页面可见性和缓存结果不能替代授权。
4. operator 只能在已授权设备上执行已授权能力。viewer 只能读取自己的任务和已授权设备，不能创建、取消或推进任务，不能因持有设备查看权读取他人正文和输出。角色变更后的历史访问仍需按当前权限重新判断。
5. super_admin 可按运维需要查看设备、任务运维摘要和审计，但不默认拥有他人任务正文、输出或私人聊天正文访问权。排障读取需要独立授权、明确原因、受限范围和追加审计。
6. HTTP、WebSocket 初次订阅、断线续订、历史事件补齐、截图和文件读取逐次进行对象级授权。对于不可见对象，错误表现不能泄露其存在性。
7. 用户禁用、设备撤销、能力或设备授权撤销后，阻止新的执行开始，并关闭或失效对应会话和订阅。

撤销与执行开始的并发边界

将“服务端成功提交开始许可事务”作为逻辑执行开始点。创建任务、排队、发送任务或 Agent 收到任务都不等于已开始。开始许可绑定不可变任务内容、当前设备会话及适用授权，Agent 在完成本地策略检查后按协议申请许可，未取得有效许可不得执行。

开始许可事务与撤销事务遵循正式规格规定的相同锁定顺序，对相关身份、设备、授权和任务进行串行化判断：

• 撤销事务先提交：后续开始许可必须被拒绝，Agent 不能凭已收到的任务继续执行。
• 开始许可事务先提交：任务已逻辑开始，随后撤销只能请求取消；不能保证已发生副作用被撤回，也不能直接标记 cancelled。
• 许可提交后连接中断，无法判断 Agent 是否收到或执行：进入结果核对流程；不能因许可响应丢失而重新执行。

该边界需要真实数据库并发屏障测试及 Agent 故障注入证据，不能仅凭代码执行顺序推断有效。

放行条件与阻断条件

身份和授权正向、跨用户拒绝、权限撤销及上述两个提交顺序均有证据。生产 MFA 未落实、仍可跨对象读取、撤销与开始存在竞态，或只能通过前端限制访问时，禁止发布对应能力。

对应验收：IAM-01 至 IAM-07。

3. 门禁二：设备身份、凭据与通信

必须实现的控制

1. 配对码高熵、短期有效、一次性、限速并仅保存哈希；消费与设备建立在事务中完成。并发使用同一码最多产生一个有效配对结果；不能先查询再分别写入。
2. 配对后的设备默认没有操作员执行授权。设备使用独立设备凭据；网页登录凭据不能连接 /ws/agent，设备凭据不能访问用户接口。
3. Agent 的设备秘密存入 Windows DPAPI 或 Credential Manager 等受保护存储，备份、日志和报错中不出现明文。凭据丢失走重新配对，不回退到共享秘密或默认密码。
4. 设备凭据支持轮换和撤销。轮换过程、允许的切换窗口及失效条件以参数基线和协议为准；撤销后旧凭据、旧连接和重连均不能恢复执行能力。
5. 生产使用有效 TLS/WSS，校验证书和主机名；不提供跳过校验选项。长期凭据不放在 WebSocket URL。设备身份绑定到已认证连接，不能信任消息中的另一个 device_id。
6. Agent 仅出站连接、普通用户运行，安装、启动和卸载可见。不能开放公网控制监听，也不能绕过 UAC、锁屏、Windows 会话隔离或关闭安全工具。

放行条件与阻断条件

必须在真实 MySQL 8.4 验证配对竞争，在真实 Windows 验证受保护存储和凭据失效，并提供 TLS 拒绝证据。允许无效证书、复用用户令牌、旧凭据撤销后仍可取得开始许可，或安装需要隐蔽绕过系统权限时，阻止设备接入发布。

对应验收：DEV-01 至 DEV-05。

4. 门禁三：任务幂等、状态真实性与重连

必须实现的控制

1. 任务、初始事件和可恢复的分发依据在同一数据库事务中持久化后才发送。数据库是任务事实来源；单实例内存不能成为唯一队列或事件历史。
2. 所有请求和消息验证版本、大小、类型、字段、身份绑定、时间约束及参数。未知任务类型、未知字段和不兼容版本被明确拒绝，不静默降级。
3. 服务端对幂等键作用域和规范化内容建立唯一约束及冲突检查；相同内容返回原任务，不同内容拒绝。Agent 持久保存去重与执行记录，并在副作用开始前落盘；重复投递返回已有状态或结果。
4. 开始许可与本地执行记录共同约束执行；不得假设网络能保证“恰好一次”。Agent 崩溃、服务端重启、数据库提交结果不明等情况下，宁可保留不确定结果，也不能自动重做可能有副作用的动作。
5. 状态集合严格使用根目录规定的 11 个状态。task.rejected 是事件：已创建任务在尚未执行时被 Agent 拒绝，保存该事件和明确错误码，将任务置为 failed，不新增 rejected 状态。执行后的异常按实际证据处理，不伪装为执行前拒绝。
6. 取消请求进入 cancel_requested，收到确认后才能进入 cancelled。取消与完成竞争时保留已确认真实结果，不凭 UI 请求成功宣称已取消。
7. timeout 不能被用来断言副作用不存在。结果不确定时使用 unknown_outcome，禁止自动重试；经核实修正必须保存依据和审计。
8. 重连先对账，再决定可执行工作。已过期、已撤销、最终完成或结果不明的任务不得再次执行。控制台按持久事件顺序续传，每次补齐重新授权。
9. 事件去重和顺序由持久化机制保证。重复、延迟或乱序回报不能覆盖已确认的最终结果；冲突进入核对与审计，不静默接受最后一次写入。
10. 许可事务原子领取全局及设备并发名额；取消、许可与执行期限按统一基线处理。进入未知结果或设备离线不证明执行器停止，未经可靠停止确认不能释放名额启动下一任务。许可预算从请求发出的单调时间保守计算，不靠时钟容差延长。

放行条件与阻断条件

必须覆盖创建并发、重复投递、执行前后崩溃、许可响应丢失、取消竞争和重连。只验证无故障正常流程、仅靠内存去重、自动重试 unknown_outcome，或断线直接改为失败，均不得通过本门禁。

对应验收：TSK-01 至 TSK-08。

5. 门禁四：浏览器与能力执行边界

必须实现的控制

1. browser.open_url 仅接受策略批准的 HTTP/HTTPS URL；同时检查规范化地址、DNS 解析、每次重定向和实际出站目标。默认阻止环回、私网、链路本地及云元数据目标，覆盖 IPv4、IPv6 及等价地址表示。
2. 防护必须约束浏览器实际网络出口。DNS 预解析或 Playwright 请求路由只能作为组成部分，不能单独作为防止 DNS 重绑定、目标替换和出站旁路的证明。
3. 验证主文档、子资源、嵌套框架、重定向链、WebSocket、Service Worker 以及浏览器可能使用的其他联网通道。未实现目标约束的通道必须明确禁用，并验证无法直连、改用其他解析路径或绕过受控出口。
4. 使用 Agent 专属独立浏览器上下文，不接管个人浏览器的 Cookie、配置文件和会话。上下文隔离与生命周期按正式规格执行；browser.page_title 只能读属于该任务或会话的自动化上下文。
5. 网络、页面、步骤、执行时间和输出大小受参数基线约束。禁止页面通过下载、外部协议或自动启动本机程序扩展执行能力。
6. 后续 desktop.launch_app 只接受登记的 app_id；截图有独立权限、交互会话边界和保留策略；shell.run_profile 只接受登记配置和类型化参数。任何阶段均不接受任意 Shell 字符串或任意进程路径。

放行条件与阻断条件

必须在隔离测试网络与真实 Windows 浏览器中证明禁止目标没有被实际连接，并记录受控出口观测证据。测试端点仅模拟云元数据和受限网段，不触及真实云元数据或用户内网服务。

如果实际网络目标、子资源或旁路约束未完成或未验证，保持 browser.open_url 禁用，不能通过“仅允许可信用户”或“前端只显示白名单 URL”替代。桌面、Shell 或截图未实现时验证服务端和 Agent 双侧关闭。

对应验收：CAP-01 至 CAP-05。

6. 门禁五：数据、秘密、审计与内容呈现

必须实现的控制

1. 所有表结构通过 Alembic 管理，迁移在真实 MySQL 8.4 验证。UUID 使用 CHAR(36)，主外键类型和比较规则一致；UTC 使用 DATETIME(6) 并恢复为带时区值；数据库使用统一 utf8mb4、JSON 映射、外键、唯一约束和查询索引。
2. 数据库使用普通业务账号，MySQL 3306 不暴露公网。权限变更、配对消费、任务幂等及开始许可具有事务和并发证据，不以 SQLite 测试替代。
3. 密码使用安全哈希；设备、平台和个人模型秘密分层保存。除经授权且只显示一次的初始化、配对、轮换与 MFA 秘密交付外，API 返回不得包含秘密；前端包、URL、localStorage、任务载荷、异常栈、普通日志、聊天及产物不得泄露秘密。必要认证输入同样不得被日志采集；诊断采用脱敏标记和 correlation_id。
4. 审计受控追加，记录身份、动作、目标摘要、结果和关联标识。普通用户不能修改或删除；常规业务写入路径不能覆盖已有审计。审计字段本身也需要秘密和隐私最小化。
5. 为日志、任务输出、聊天、截图和文件分别配置保留、访问和清理规则，清理操作审计化。幂等及事件证据的保留必须与重试、重连和核对窗口兼容，不能提前清理后造成重复执行。
6. 命令和设备输出按文本显示；Markdown/HTML 经安全处理。错误和历史结果中嵌入脚本、链接或工具指令不会获得浏览器脚本执行或设备执行权限。

放行条件与阻断条件

空库和已有版本迁移、事务回滚、时间/JSON 往返及约束均需要真实数据库记录。存在秘密外泄、可越权读取产物、可改写审计，或输出能执行未授权脚本时阻止对应功能发布。保留期未确定、清理未验证或恢复目标未落实时不通过生产验收。

对应验收：DAT-01 至 DAT-05。

7. 门禁六：模型、聊天、Skill 与 MCP 隔离

此门禁在首个闭环中验证禁用边界；后续获授权开发并启用时验证完整控制。标记“未来功能”不等于可保留一个绕过检查的隐藏接口。

必须实现的控制

1. 模型只能提出答复或结构化计划，每个工具动作进入同一身份、授权、状态、超时与审计流程。网页、附件、模型输出、Skill 文本和 MCP 返回中的指令不改变系统策略或权限。
2. BYOK 配置只允许所有者读取元数据、替换、测试和删除。保存后不返回密钥明文；服务端加密存储或密钥服务管理，业务库优先存 secret_ref。撤销、删除和轮换失效缓存引用并按策略销毁秘密。
3. 模型和远程 MCP 地址实施有效 TLS、SSRF、DNS/重定向、实际目标、超时与响应大小约束。切换服务商、重试或故障转移不能越过白名单及数据出站授权。
4. 请求、工具、工作流步骤、费用、时间和输出大小受到预算及速率限制。高风险审批绑定不可变内容；参数、目标或执行版本变化后原审批失效，后续每一步重新授权。
5. Skill 固定可信来源、不可变版本、兼容范围、声明权限和完整性证据；导入拒绝路径穿越、符号链接及超大包。部署前审核，更新重新验证，可执行 Skill 默认禁用。
6. MCP Server 和 stdio 可执行文件/参数必须登记，新工具默认禁用，Schema 变化后禁用并重新审核。扩展无法读取 Agent 秘密、改变策略或自行提权；紧急禁用、撤销及回滚可审计。

放行条件与阻断条件

首版没有模型或扩展执行入口可达，未声明的任务类型也被 Agent 拒绝。未来启用时必须新增真实服务交互证据，并在隔离环境验证恶意返回、费用耗尽、配置撤销、包篡改和 Schema 变化。模拟服务只证明本地控制流程，不能证明真实服务商出站范围和费用行为。

对应验收：EXT-01 至 EXT-05。

8. 门禁七：供应链、发布、恢复与监控

必须实现的控制

1. Web、API、Agent、协议和数据库迁移分别记录版本、来源及兼容范围；依赖和镜像固定版本或 digest。发布内容可复现或可追溯，不使用浮动镜像标签作为生产发布依据。
2. Agent 更新验证可信签名或受保护发布清单的来源与完整性，仅下载哈希不足以证明来源。支持测试设备、小批量发布、健康检查、暂停和失败回滚；高风险任务执行中不强制更新或重启。
3. 发布前备份数据库及必要配置，在隔离环境完成恢复验证。密钥保护和备份恢复设计相互兼容，不能恢复出数据库却无法恢复合法加密数据或错误复活已撤销凭据。
4. 数据库采用兼容迁移；不可逆变更必须有经验证的恢复方案。应用回滚、数据库恢复和 Agent 回滚分别说明适用条件，不将回退应用二进制等同于数据库回滚。
5. 恢复后的待处理任务先核对，不能重跑可能已执行的任务。恢复过程可能丢失的任务、事件和撤销记录必须被识别，不能把旧备份中的授权或凭据自动视为当前有效。 如果无法取得可靠的备份后撤销事实，则保持登录和执行关闭，使旧会话与设备凭据全部失效并重新核准身份与授权；设备自报不能替代服务端授权恢复。
6. 公网入口为 HTTPS/WSS，HTTP 仅按需用于证书验证或跳转；限制 SSH 管理来源。数据库、缓存及 Agent 控制端口不对公网开放。
7. 健康和就绪检查区分进程存活与可接受任务；数据库不可用、关键策略未就绪或协议不兼容时不对外承诺可执行。提供任务积压、失败、Agent 离线、数据库/存储、模型费用及备份异常的监控、告警和关联 ID。
8. 生产前从参数基线明确备份保留、RPO、RTO 和恢复演练目标，验证凭据泄露处置流程及负责人。值班说明必须能指向实际观测、撤销、停发和恢复步骤。

放行条件与阻断条件

发布包来源无法验证、兼容性未知、备份未恢复过、撤销数据恢复后失效、关键告警没有演练，或实际恢复未达到确定目标时不通过生产门禁。首版未启用自动更新时，自动更新入口保持关闭，人工发布包仍必须验证来源和完整性。

对应验收：OPS-01 至 OPS-05。

9. 评审与证据交接

每次验收记录实施版本、配置基线版本、门禁适用性、用例结果、证据位置、剩余问题和责任人。通过结论必须由实际执行结果支持，不能从本设计稿直接生成。

发布评审需要以下输入：

• 已实现范围、明确禁用的范围及其边界验证结果。
• 完整用例矩阵、失败或阻塞列表、真实环境与模拟环境的区分。
• 安装、卸载、凭据撤销、事件核对、回滚和恢复的实际演练记录。
• 参数基线中的生产待决项、适用门禁和版本兼容结论。

当前所有安全及运行验收均未执行。本次文档补齐仅能通过文档一致性和链接检查，不能替代上述证据。