62 lines
9.8 KiB
Markdown
62 lines
9.8 KiB
Markdown
# 产品需求
|
|
|
|
| ID | 需求 | 优先级 |
|
|
| --- | --- | --- |
|
|
| BR-001 | 支持 Chrome 和 Edge，允许自动发现或手动指定 executable。 | P0 |
|
|
| BR-002 | 启动配置支持 `user-data-dir`、`profile-directory`、URL、代理、headless 和额外参数。 | P0 |
|
|
| BR-003 | 启动前检测目标 user data dir 是否占用，禁止同一环境重复启动。 | P0 |
|
|
| BR-004 | 实例列表显示浏览器类型、PID、user data dir、启动时间和状态。 | P0 |
|
|
| BR-005 | 支持优雅关闭、强制关闭和重启，并明确操作影响。 | P0 |
|
|
| BR-006 | 监控 Chub 注册实例的启动失败、异常退出、退出码和进程消失；受管进程意外退出时及时更新 GUI，外部实例只允许刷新检测。 | P0 |
|
|
| BR-007 | 启动参数按数组传递，不通过 shell 拼接。 | P0 |
|
|
| BR-008 | 只允许管理工具注册且经过身份校验的 PID。 | P0 |
|
|
| BR-009 | 支持本地配置持久化，绝不保存浏览器凭证。 | P1 |
|
|
| BR-010 | 提供 CLI 或本地 API，供脚本启动、查询和关闭实例。 | P1 |
|
|
| BR-011 | Chub 启动的 Chrome/Edge 必须启用仅限 loopback 的本地 CDP；端口从设置的起始端口分配，空值默认 9666。 | P1 |
|
|
| BR-012 | 同一 user data dir 被外部浏览器占用时，只能在其 CDP 端点可验证时关联为外部实例；不得接管生命周期。 | P1 |
|
|
| BR-013 | 用户可以刷新已保存实例的状态，并编辑未运行实例的名称、浏览器类型、user data dir 和启动 URL；刷新和编辑不得扩大到未授权的浏览器进程。 | P1 |
|
|
| BR-014 | 用户可以在完整代理地址下拉框中维护无认证代理，并在创建或编辑实例时选择代理；代理认证信息不得保存、记录或进入启动参数。 | P1 |
|
|
| BR-015 | GUI 实例主操作在 Chub 托管运行态提供优雅停止、在可启动状态提供启动；外部关联或未知外部实例不得获得生命周期控制。 | P1 |
|
|
| BR-016 | 每个已保存实例有独立、持久化的首选远程调试端口；它与运行时实际端口分离，未启动实例仍可在列表看到建议端口。 | P1 |
|
|
| BR-017 | 用户可以仅通过已验证的 loopback CDP 端点查看 Chub 实例的页面目标（标签页）标题、脱敏 URL 和类型；该功能不得控制页面、关闭标签页或接管外部浏览器。 | P1 |
|
|
| BR-018 | Chub 运行时提供一个 Windows 通知区域图标，允许显示主窗口、刷新已保存实例状态和显式退出应用；图标及菜单不得绕过实例授权边界或泄露实例路径、URL、代理等敏感信息。 | P1 |
|
|
| BR-019 | Chub 默认将本地 `config.json` 保存到正在执行的 `chub.exe` 同级目录；首次使用新位置时安全迁移旧 `%APPDATA%\\chub\\config.json`，新位置既有配置永不被旧配置覆盖。 | P1 |
|
|
| BR-020 | 用户可为无认证代理维护必填、唯一的代理名称；新建实例默认使用实际 `chub.exe` 同级 `user_data_dirs\\<稳定实例 ID>`，实例列表在用户数据目录与调试端口之间显示代理名称。 | P1 |
|
|
| BR-021 | 设置中的 Chrome 与 Edge 可执行文件路径必须支持 Windows 原生 `.exe` 文件选择；标准安装路径搜索必须在对应字段旁可感知地报告搜索、取消、确认当前路径、更新路径或失败，且不丢失已有输入。 | P1 |
|
|
| BR-022 | 删除实例确认框默认只删除 Chub 实例配置；用户可显式、默认未勾选地选择同时删除该实例的 User Data Dir。数据删除必须在后台重新确认目标目录未被 Chub 或外部浏览器占用，并通过绝对路径、非卷根及非链接边界校验；失败时保留实例配置和目录。 | P1 |
|
|
|
|
## 验收标准
|
|
|
|
- 两个不同 user data dir 可以并行启动，互不阻塞。
|
|
- 同一 user data dir 的第二次启动被拒绝，并显示已知 PID/来源。
|
|
- 新启动实例使用 `127.0.0.1` 上的远程调试端口；从默认或已保存的起始端口开始递增，并在列表显示实际关联端口。
|
|
- 外部实例只有在其 `DevToolsActivePort` 和本地 CDP 端点均通过浏览器类型校验时才显示“外部已关联”；关联后不得显示关闭、强制关闭或重启入口。
|
|
- 外部实例未启用 CDP、端点失效或权限不足时，显示“外部占用”或“未知占用”，且不得再次使用同一目录启动浏览器。
|
|
- 关闭操作不会影响其他 Chrome/Edge 实例。
|
|
- 工具重启后，无法确认身份的外部进程只能报告 UNKNOWN，不得被关闭。
|
|
- 异常退出后状态在合理时间内变为 EXITED/FAILED。
|
|
- 新建实例从全局起始端口推荐一个未被其他 Chub 实例逻辑预留或实际使用的首选端口；启动优先使用它，并在后台复检 loopback 可用性与 CDP 端点。
|
|
- 外部端口冲突时只能回退到未被其他 Chub 实例预留的端口；成功验证后更新当前实例首选端口，失败或外部关联不得改写配置。
|
|
- 参数中不出现密码、Cookie、Token 或代理 userinfo。
|
|
- UI 覆盖加载、空、占用、启动失败、关闭中、成功和权限错误。
|
|
- 刷新仅检查 Chub 已保存的实例；任务执行中不可重复触发，过期结果不得覆盖已经删除或编辑后的记录。
|
|
- 实例编辑支持保存、取消和 Escape；有未保存修改时必须先确认，运行中或外部关联实例不能修改浏览器类型或 user data dir。
|
|
- 代理仅接受无认证的 `scheme://host:port` 端点。删除仍被实例引用的代理必须被拒绝；实例保存后按稳定代理 ID 解析最新端点。
|
|
- 设置页默认代理输入为空；选择下拉项后回填完整地址，保存更新当前项、未选择时新建。删除未引用项须经确认，确认取消或引用保护不能改变任何实例选择。
|
|
- 代理名称为必填、去首尾空白且不区分大小写唯一的非敏感显示名称；名称和地址在同一次保存中校验、保存。代理选择器显示“名称 · 地址”，实例列表只显示名称或“无代理”，避免把完整地址挤入表格。
|
|
- 点击“新建实例”后，User Data Dir 默认填入实际 `chub.exe` 同级 `user_data_dirs\\<稳定实例 ID>`，每个新实例必须得到不同子目录；不得使用当前工作目录或让多个实例共享根目录。目录不可写时保留输入并给出可恢复的权限/路径提示，用户可改用目录选择器。
|
|
- 受管运行实例点击主操作后进入关闭中，成功退出后恢复启动入口；停止失败不自动强制终止，也绝不影响其他 Chrome/Edge。
|
|
- Chub 在当前应用会话中启动的 Chrome/Edge 根进程意外退出后，实例状态立即变为“已退出”，清空运行时 PID/端口，并显示包含实例名称和浏览器类型的可关闭提示；配置与 User Data Dir 保留，关闭提示后启动入口可用。
|
|
- 用户从 Chub 发起优雅停止时，不显示“浏览器已退出”意外退出提示；外部已关联、外部占用、未知占用以及应用关闭后无法继续监控的实例均不弹出此提示。
|
|
- 用户只能对“运行中”或“外部已关联”且已有实际、已验证 CDP 端口的实例打开页面目标查看；读取失败时保留实例配置和当前编辑内容，给出可恢复的重试提示。
|
|
- 页面目标列表只显示标题、类型和移除 userinfo、query、fragment 的 URL；不得保存、记录、发布或展示 CDP WebSocket URL，也不得发送导航、关闭、创建或脚本执行命令。
|
|
- 通知区域仅显示一个 Chub 图标；Tooltip 仅含非敏感汇总状态。双击或默认菜单项显示并置前主窗口，刷新命令仍只检查已保存实例，退出命令走明确的应用退出协调流程。
|
|
- 图标创建失败、Explorer 重启、菜单关闭和应用退出不会阻塞 UI 帧，也不会导致浏览器启动、关闭、接管或按进程名枚举。退出时必须移除图标；外部 Chrome/Edge 永远不因通知区域命令被停止。
|
|
- 默认配置路径必须由实际可执行文件路径解析，而非当前工作目录；迁移只在新位置不存在且旧配置存在、可读取、可校验时执行。迁移使用现有原子写入并保留旧配置恢复备份；目标目录不可写或旧配置畸形时，不创建半成品配置、不静默回退或混合两个配置来源，并给出可恢复诊断。
|
|
- 设置页的 Chrome/Edge“选择”必须打开仅允许现有 `.exe` 的 Windows 原生文件选择器；取消、选择失败或不合规结果必须保留原输入。搜索标准安装路径时，结果即使与当前路径相同，也必须在同一字段旁明确表示“已确认当前路径可用”；搜索、取消、成功和失败不得依赖页面下方的全局反馈。
|
|
- 删除实例确认框默认不删除 User Data Dir。只有用户勾选“同时删除 User Data Dir 中的数据”并再次点击具体的“删除实例及数据”后，才允许删除该目录；对运行中、启动/停止中、外部关联、外部占用或未知占用实例，数据删除选项禁用并说明需先停止/刷新。后台须在实际删除前重新检查 Chub registry 与外部占用，拒绝相对路径、卷根、普通文件和符号链接/重解析点。数据删除成功后才移除实例配置；检查、占用或删除失败时实例配置和目录均保留，并给出可恢复提示。
|
|
|
|
## 不做
|
|
|
|
全局杀 Chrome/Edge、自动登录、页面操作、验证码处理、平台 API 集成、远程控制和跨用户权限提升；通过 CDP 管理或关闭外部实例。首个 CDP 查看版本不提供物理窗口 ID 或分组，后续仅在经过独立安全评审的 WebSocket CDP 任务中考虑。首个通知区域版本不改变窗口关闭语义、不把关闭按钮隐藏到通知区域，也不在菜单中直接启动、停止、重启或删除实例。首个便携配置版本不提供 UI 路径选择、自动合并多个 `config.json`、网络同步或安装版的 AppData 回退；可配置路径参数另行评审。
|