设计决策与参数基线
版本：0.1。日期：2026-10-20。状态：补编设计稿。
本文件集中记录首个交付闭环的架构选择、建议默认参数和需要业务确认的事项，防止各模块独立选择相互冲突的规则。根目录 AGENTS.md 的明确要求优先；本文件的新增选择是待实现、待验证的设计，不代表已经部署或获得生产验收。
决策状态
| 标记 | 含义 |
|---|---|
| 规范要求 | 来自根目录约定，实现时必须满足 |
| 建议采用 | 当前资料下的实现方案，可以在说明影响后调整 |
| 上线前确认 | 需要业务或运维负责人确定实际值；未确认不得宣称满足生产目标 |
| 验证阻塞 | 必须通过指定技术验证才能开放相应能力 |
原始规格未随仓库提供。本次补编不推断历史决策，也不声称恢复原文。文档间冲突先按根目录要求处理；新增设计的变更应同步总纲、相关规格和验收矩阵。
架构决策
| ID | 选择 | 状态 | 边界与重新评估条件 |
|---|---|---|---|
| D01 | FastAPI 模块化单体，首版单 API 实例、单 worker，分发与超时扫描为进程内受管理后台任务 | 建议采用 | 不承诺高可用；多实例前必须设计连接归属、跨进程撤销、分发锁与全局限速 |
| D02 | MySQL 是任务、事件、授权和审计的事实来源；任务与待分发记录同事务提交 | 规范要求与建议采用 | 进程内队列仅作唤醒提示；数据库扫描负责恢复；不强制 Redis 或消息队列 |
| D03 | 同源 Web，服务端存储不透明会话，Cookie 使用 Secure、HttpOnly、SameSite=Strict、Path=/ | 建议采用 | 不设 Domain；状态变更校验 CSRF token 和 Origin；WebSocket 握手校验会话及 Origin |
| D04 | 浏览器独立进程与上下文，受控出站代理结合进程网络限制，验证实际目的地址 | 验证阻塞 | 路由拦截仅作辅助；无法证明无旁路时禁止启用 browser.open_url |
| D05 | Windows 标准用户可见运行；设备凭据采用用户作用域 DPAPI 或 Credential Manager，附文件 ACL | 建议采用 | 首版不做系统服务接管交互桌面；换运行账号、丢失凭据或重装后重新配对 |
| D06 | packages/protocol 维护一个协议源，生成或验证 JSON Schema、Python 与 TypeScript 类型 |
规范要求与建议采用 | 生成文件不得各端手改；新增字段须明确版本协商，未知字段拒绝 |
| D07 | 服务端开始许可事务是逻辑执行开始点，与撤销事务按相同行锁顺序串行化 | 建议采用 | 许可前撤销必须阻止开始；许可后按已开始任务处理，实际副作用不能保证撤回 |
| D08 | 首版任务只开放 browser.open_url，每任务新建独立上下文并在结束后关闭 |
建议采用 | 不保留登录态、不接管个人浏览器；后续 browser.page_title 需先明确上下文归属和生命周期 |
| D09 | Agent 本地持久执行日志仅保存去重、许可、执行结果与待确认回报 | 建议采用 | 不是第二套业务事实来源；日志损坏或丢失时停止新执行并重新核对，不能空日志自动重跑 |
| D10 | 身份、授权、任务和审计在同一服务内分模块，先按垂直闭环交付 | 建议采用 | 按需求扩展聊天与模型；不为未来功能预先开放空实现接口 |
数据库仍按根目录要求使用 MySQL 8.4 LTS、mysql+asyncmy、UUID CHAR(36)、UTC DATETIME(6) 和 utf8mb4。依赖的精确补丁版本、浏览器构建与镜像 digest 在工程初始化时锁定并记录，不在文档中编造可用版本清单。
建议默认参数
以下数值是便于设计和验收的试点默认值，不是实测容量、服务承诺或已确认的生产策略。配置必须有类型、范围和启动校验，越界时拒绝启动或拒绝请求，不静默放宽。
| ID | 参数 | 建议默认值 | 变更或验收要求 |
|---|---|---|---|
| P01 | 试点容量和执行并发 | 20 台设备、25 个用户；全局同时执行 10 个任务，每设备 1 个 | 作为测试负载；超额排队受 TTL 限制，正式容量须压测确认 |
| P02 | 任务时间 | timeout_seconds 默认 60 秒、允许 1–120 秒；创建后 300 秒内必须取得开始许可 |
expires_at 是最晚开始时刻；执行预算从开始许可时刻计时，不能靠重连重置 |
| P03 | 心跳和离线判定 | 每 20 秒心跳，连续 60 秒未收到则离线 | 离线阻止新分发；不把在线状态当授权证明，也不据此推断任务失败 |
| P04 | 登录限速 | 单账号 15 分钟内 5 次失败、单来源 IP 15 分钟内 30 次失败后限速 | 不永久锁号；响应避免用户枚举；只信任配置的反向代理来源头；多实例前共享计数 |
| P05 | Web 会话 | 空闲 30 分钟、绝对 12 小时；敏感管理动作要求最近 5 分钟内重新验证 | 生产管理员需 MFA；后台心跳不能自动延长无人操作的会话 |
| P06 | 配对和设备秘密 | 配对码至少 128 位随机熵、5 分钟有效、一次性；设备秘密至少 256 位随机熵；配对按来源 IP 每分钟 10 次尝试限速 | 服务端只存秘密哈希；不可短数字码替代高熵码；日志不记录提交码 |
| P07 | 输入及协议大小 | HTTP 任务创建请求最多 8 KiB；WebSocket 解压后单消息最多 64 KiB；URL 最多 2048 字符；分页最多 100 条 | 解压前同样限制帧与缓冲区，首版关闭 WebSocket 压缩；全链路一致限制 |
| P08 | 任务结果 | 结构化结果 UTF-8 序列化最多 16 KiB；标题最多 512 字符 | 文本截断带 truncated 标志，禁止把截断 JSON 当完整 JSON；不得返回 Cookie 或网页正文 |
| P09 | 保留与清理 | 任务参数、结果及普通事件 30 天；审计 180 天；幂等最小墓碑首版不自动删除；应用日志 14 天；未来聊天 30 天、截图与文件 24 小时 | 上线前确认；进行中、结果不明或待调查任务暂缓清理，须有复核与解除保留记录 |
| P10 | 备份与恢复 | 建议 RPO 24 小时、RTO 4 小时；每日加密备份、保留 30 天、异机保存 | 上线前确认并演练计时；备份成功不等于恢复成功；更小 RPO 需另设计 binlog 等措施 |
| P11 | 浏览器访问策略 | 精确批准的域名；默认空清单；HTTPS 443；HTTP 80 仅显式批准；禁止 IP 字面量及其他端口 | 域名、子资源域名分别登记；私网等禁止范围即便在域名清单中也不能放行 |
| P12 | 后续模型与扩展预算 | 功能关闭；模型预算、工具次数、步骤数和允许出站目标均未配置 | 未配置不是无限额；任何一项缺失都不能启用相应执行能力 |
| P13 | 连接恢复 | 带随机抖动的指数退避，基数 1 秒、上限 30 秒 | 只自动重连与重传相同结果，不自动重做副作用任务；认证被撤销则停止重试并提示重新配对 |
| P14 | 执行许可与时钟 | 开始许可 5 秒内有效；允许时钟偏差不超过 30 秒 | Agent 同时采用本地单调时钟限制执行预算；超出偏差暂停执行，不能扩大许可或任务有效期 |
| P15 | 幂等键 | 客户端随机 UUID；作用域为请求者用户 ID 与幂等键，所有创建入口共享 | 最小墓碑按 P09 保留；结果清理不允许相同键重新执行；未来清理墓碑必须先设计可验证拒绝旧键的版本化机制 |
| P16 | 取消确认窗口 | 自取消请求提交起 30 秒，保存 cancel_confirmation_deadline |
到期仍不确定则进入 unknown_outcome；不能据此假定停止或释放执行名额 |
| P17 | 凭据轮换准备 | 准备态有效期 10 分钟；每设备最多一个未结束轮换 | 到期未确认的新凭据失效，旧凭据仅在原有效状态下继续有效；确认操作幂等 |
| P18 | 身份辅助流程 | 登录 MFA 挑战 5 分钟、每挑战最多 5 次验证；MFA 绑定准备 10 分钟；管理员发放初始访问材料 24 小时内一次性使用 | 超时重新发起，不能延长原凭据；临时身份仅可改密码、完成 MFA 或登出 |
| P19 | 浏览器网络资源 | 单任务出站通道累计收发最多 32 MiB；最多 200 个请求；主导航最多 10 次重定向 | 包含子资源及加密隧道流量，采用保守统计；超过任一上限立即停止新增网络动作并收尾，不能只等最终结果截断 |
P09 的墓碑至少保存请求者 ID、键、内容摘要、任务 ID、终态与完成时间，不保留已经到期的参数和结果正文。首版不删除此最小去重依据，也不允许依据客户端“这是新键”的声明重新执行旧请求。Agent 对账确认前不能清理执行记录；结果不明记录保持冻结。清理策略应同时覆盖主库、对象存储、缓存、导出物和备份到期，不能宣称主库删除即可立即清除历史备份。
P14 的时钟偏差仅用于识别时钟异常，绝不延长许可。Agent 在开始请求发出时记录单调时间 t0，从 t0 分别计时许可有效期及执行预算，收到响应后扣除已经消耗的往返时间；若许可剩余时间不为正则不能开始。服务端仍按自身 UTC 截止时间检查。P01 的全局和设备执行名额需在许可事务内原子领取，只有得到执行器已停止的可靠证据才释放；进入 unknown_outcome 本身不会释放名额。
需要确认的业务与运行条件
| ID | 问题 | 当前处理方式 | 最迟确定时点 |
|---|---|---|---|
| Q01 | 实际设备数、用户数、任务峰值与是否要求高可用 | 按 P01 做试点设计，D01 不提供高可用 | 容量验收和生产拓扑设计前 |
| Q02 | 允许访问哪些业务域名、子资源、是否需要登录态 | 空清单，禁止执行；首版不保存登录态 | 首次真实浏览器测试前 |
| Q03 | Windows 版本、运行账号、交互会话以及网络策略安装条件 | 标准用户可见运行；单独确认安装阶段是否允许管理员配置网络限制 | D04 技术验证前 |
| Q04 | 生产域名、TLS 证书管理、服务器与备份存储位置 | 使用占位说明，不生成真实配置或秘密 | 预生产部署前 |
| Q05 | 日志、任务、审计、聊天、截图与文件的保留要求 | P09 作为建议；需确认隐私、业务和存储约束 | 持久化功能对真实用户开放前 |
| Q06 | 允许的数据损失、恢复时长及谁响应故障 | P10 作为目标；指定实际负责人后完成演练 | 生产门禁评审前 |
| Q07 | 模型服务商、数据出站范围、费用上限与密钥管理设施 | 模型及 BYOK 默认关闭 | 模型功能设计冻结前 |
| Q08 | 审批人员、任务风险分级、截图授权和 Shell 配置清单 | 对应能力默认关闭，不以管理员身份绕过 | 开放对应能力前 |
| Q09 | 缺失的原始规格与历史资料是否另有副本 | 保留补编来源说明，收到原件后逐项比对，不覆盖原件 | 合并原始资料时 |
Q01–Q09 不要求阻止文档与通用工程基础工作；它们只阻塞依赖该答案的实现选择、真实执行或发布。负责人和批准日期留待实际指定，不虚构姓名或验收记录。
开发前必须通过的技术验证
- 浏览器网络约束：证明代理解析与实际连接使用同一获准地址，覆盖 IPv4/IPv6、重定向、子资源、Service Worker、WebSocket、QUIC/WebRTC 和代理失效；网络限制安装不得由普通 Agent 静默提权。
- MySQL 并发与事务：同时消费配对码、相同键建任务、授权撤销与开始许可竞争、重复最终事件，验证唯一约束与锁顺序。
- 故障恢复：在持久化、分发、领取许可、开始副作用、结果落盘和回报确认各边界终止进程，验证不会靠重跑消除不确定性。
- Windows 凭据与运行身份：验证另一普通 Windows 用户无法使用设备秘密；运行身份变更时安全失败；正常退出后浏览器和出站代理不遗留后台任务。
这些验证的实现与执行属于后续开发任务。本次文档补齐仅定义通过条件。