第一阶段实施计划
版本：0.1。日期：2026-10-20。状态：补编设计稿；当前实施状态见 阅读导航。
本阶段交付账号、授权、设备配对、任务分发与 browser.open_url 的真实闭环，对应总规格阶段 0–4。目标是证明同一个受控任务能完成授权、持久化、执行与回报，并在拒绝、断线和崩溃时保留可信状态。
当前起点与工作边界
仓库当前只有开发约定与补编规格，没有现成的应用、迁移、依赖锁或 CI。此计划不代表相应模块已经初始化，也不把文档中的目标命令当作可运行脚本。
本次工作止于补齐文档。后续明确要求开始开发时，按以下里程碑执行；常规实现选择在既有规范内推进，需要真实业务答案的项目按 Q01–Q09 在其依赖点确认，不在最初阶段追问全部生产细节。
里程碑与退出条件
| 阶段 | 工作内容 | 必须形成的产物 | 退出条件 |
|---|---|---|---|
| M0 工程与契约 | 创建实际需要的模块目录；明确协议源、请求响应 DTO、状态转换、错误码；固定依赖及检查脚本 | Web/API/Agent 项目配置与锁文件，协议 Schema 和示例，CI，初始 Alembic 迁移，README 实际命令 | 类型、Lint、Schema 校验可运行；真实 MySQL 空库迁移成功；所有文档中的辅助身份接口形成契约 |
| M1 身份与权限 | 一次性管理员初始化、会话、账号管理、角色与对象级授权、登录限速和撤销；生产配置支持 MFA 门禁 | Identity/Authorization 服务，用户与会话表，管理与登录页面，审计 | 跨用户与越权测试通过；禁用/重置使旧会话及订阅失效；不会禁用最后有效管理员 |
| M2 设备接入 | 一次性配对、受保护凭据、轮换/撤销、WSS、心跳、连接代次与重连对账 | Agent 传输层与日志层、设备页面、配对管理、设备身份 API | 真实 Windows 完成配对和连接；并发复用/过期/旧凭据/旧连接均拒绝 |
| M3 任务基础 | 设备与能力授权、幂等创建、事务待分发、唯一开始许可、事件回放、取消、超时和未知结果 | Task Service、分发器、Agent 执行接口、任务页面和审计查询 | MySQL 并发及故障注入通过；服务重启不丢事实；重复投递不重复执行；权限撤销不能取得新许可 |
| M4 浏览器闭环 | D04 网络出口约束、类型化 browser.open_url、真实结果回报、执行清理 |
浏览器执行器、网络策略、端到端用例、真实 Windows 证据 | 允许目标成功，禁止目标及旁路被阻止；执行日志与控制台一致；取消/断线/未知结果可追踪 |
| R 预生产与发布 | 完成适用安全门禁、部署配置、兼容发布、备份恢复及回滚演练 | 版本清单、运行手册、实际验收记录、恢复证据 | 负责人确认 Q01–Q06；生产管理员 MFA 与 TLS 验证；七项适用门禁均有通过证据 |
M0–M4 是首个交付闭环；R 是把该闭环用于生产的额外退出条件。完成 M4 不自动等于可以生产上线。
首次工程初始化的具体约束
- 检查实际目录和用户修改，保留规格原件及新增资料。按需建立
apps/web、services/api、agents/windows-agent、packages/protocol、deploy和测试目录。 - 选择并固定 Node/Python 版本和依赖管理工具，提交锁文件；不把“最新版”作为可复现发布依据。
- 将总纲中的 API/消息补成严格 Schema，提供至少一个合法样例和未知字段、错误版本、过大消息等非法样例。
- 建立真实 MySQL 8.4 集成环境和 Alembic 流程。测试库与业务库分开，迁移账号与运行账号分开。
- 为前端配置类型检查、Lint、构建；为 Python 配置类型检查、Lint、单元和集成测试。工具名称和命令在配置存在且执行成功后写进 README。
- 提供无秘密环境变量示例和服务启动说明；真实
.env、日志、截图、浏览器配置和备份不入库。 - CI 必须检查协议生成差异、Schema 一致性及受影响安全用例。平台受限的 Windows E2E 单独记录执行环境，不能用 Linux 模拟结果冒充。
需要前置的技术验证
M0 阶段可以并行准备 D04 网络出口方案和 Windows 身份验证，但仅在获授权的测试设备上进行。若 Q02/Q03 尚未确定，完成方案和可运行测试框架，不访问真实业务站点、不配置真实设备网络。
浏览器安全验证必须先于 M4 对用户开放，至少覆盖实际目的 IP、DNS 重绑定、跨域重定向、子资源、IPv6、Service Worker、WebSocket、代理失效及旁路流量。默认空域名清单应使任务被拒绝。
任务故障注入至少选取六个边界：数据库提交后发送前、投递后确认前、开始许可提交后响应前、实际动作发生后结果落盘前、结果落盘后回报前、服务端提交结果后确认前。每次记录是否有副作用依据、最终状态及是否发生重跑。
Web 页面范围
| 路由 | 首版职责 | 必须展示的状态 |
|---|---|---|
/login |
登录及 MFA 挑战 | 错误、限速、挑战到期、会话失效 |
/admin/users |
账号、角色、禁用和重置访问 | 加载、空列表、失败、敏感动作验证 |
/admin/devices |
配对、连接、撤销、凭据运维摘要 | 未授权、离线、已撤销、配对码过期 |
/admin/grants |
用户设备及能力授权 | 当前授权、变更失败、撤销生效 |
/admin/audit |
脱敏审计与关联任务摘要 | 查询范围、无结果、不可读取内容 |
/app/devices |
本人可见设备、可用能力和创建任务 | 无设备、无执行权、离线、策略未配置 |
/app/tasks 与任务详情 |
本人任务、事件、结果和取消 | 排队、执行中、取消待确认、未知结果、结果已清理 |
/app/chat |
后续聊天入口 | 首版不开放可执行入口，不显示模拟成功 |
界面必须能解释 unknown_outcome：当前无法确认操作结果，系统不会自动重做。取消按钮提交后显示待确认，不直接显示已取消。结果按文本安全展示，不执行 Agent 返回的 HTML 或脚本。
集成与验收场景
基础演示使用一台获授权的 Windows 测试设备、一个管理员、两个不同操作员和一个观察者，测试站点必须属于明确批准范围。
先验证管理员创建账号并完成配对，确认新设备尚无操作员执行权限。再只向操作员 A 授予设备与 browser.open_url，由 A 创建任务并看到真实结果。操作员 B 访问任务和结果必须被拒绝；观察者只能访问其许可的只读数据，不能创建任务。
随后复用相同幂等键，验证返回原任务；换参数复用键应冲突。依次注入用户禁用、设备撤销、能力收回、连接替换、进程重启和结果确认丢失，按总纲记录终态及事件。浏览器网络策略单独进行禁止目标测试，不能只演示成功网址。
所有测试映射到验收矩阵中的用例 ID，报告填写环境、版本、步骤、实际结果、日志或事件引用。没有执行的项目保留“未执行”；失败项目保留原因和修复记录，不改为“不适用”逃避门禁。
并行工作与集成责任
M0 完成协议及 DTO 后，Web 与 API 可以按契约并行。M1 的身份与授权接口稳定后，M2 的 Agent 传输可与管理页面并行。M3 的状态机、幂等和许可协议由同一负责模块维护，其他模块只按契约实现，避免各自增加状态。
一项功能变更同时检查接口、协议、迁移、授权和测试，不以“前端已完成”代替闭环。合并前保存实际检查结果；没有真实数据库或设备时，完成不依赖环境的工作并明确缺失证据。
交付与回滚
每个里程碑交付实际改动、执行过的检查、未验证范围及迁移影响。涉及数据库时保留前向兼容迁移和恢复计划；涉及 Agent 时记录 API、协议及浏览器构建兼容范围。
首版不承诺固定工期。完成 M0 的依赖与网络验证后，根据真实开发环境、设备条件和 Q01–Q06 再估算剩余工作；不得用未经验证的人日数字替代技术风险评估。