# 用户故事

| ID | 用户故事 | 优先级 |
| --- | --- | --- |
| US-001 | 用户可以创建 Chrome/Edge 实例配置，并指定 user data dir、profile 和 URL。 | P0 |
| US-002 | 用户可以启动两个不同隔离环境，并看到各自 PID 和运行状态。 | P0 |
| US-003 | 用户可以发现同一 user data dir 已被占用，避免重复启动。 | P0 |
| US-004 | 用户可以优雅关闭实例；无响应时在确认后强制终止。 | P0 |
| US-005 | 用户可以重启指定实例，并确认旧实例已经退出。 | P0 |
| US-006 | 用户可以通过 CLI/API 查询、启动和关闭实例。 | P1 |
| US-007 | 用户可以看到实例的首选或实际本地调试端口；同目录外部浏览器已启用调试时，Chub 只关联并展示状态。 | P1 |
| US-008 | 用户可以刷新已保存实例的运行状态，并通过对话框编辑非运行实例的基本配置而不影响其他浏览器。 | P1 |
| US-009 | 用户可以在设置中通过完整代理地址下拉框维护无认证代理，并在新建或编辑实例时从下拉选择器选择代理。 | P1 |
| US-010 | 用户可以通过实例行的同一主操作启动或优雅停止 Chub 托管的浏览器，而不会关闭外部浏览器。 | P1 |
| US-011 | 用户手动关闭 Chub 启动的 Chrome/Edge 后，可以立即获知该实例已退出，并重新启动该实例。 | P1 |
| US-012 | 用户可以查看已验证运行实例的 CDP 页面目标标题、脱敏 URL 和类型，而不会向浏览器发送控制命令。 | P1 |
| US-013 | 用户可以从 Windows 通知区域快速显示 Chub、刷新已保存实例状态或明确退出应用，而不会在菜单中误操作浏览器实例。 | P1 |
| US-014 | 用户复制或升级 Chub 后，实例配置与程序一同保存在可执行文件目录；首次升级会安全带入旧 AppData 配置且不丢失已有新配置。 | P1 |
| US-015 | 用户可以用易读名称维护代理，并在实例列表快速确认每个实例使用的代理；新建实例会得到程序目录内独立的默认 User Data Dir。 | P1 |
| US-016 | 用户可以从设置页选择 Chrome 或 Edge 的本机可执行文件，或搜索标准安装位置，并立即知道当前路径是否已确认或被更新。 | P1 |
| US-017 | 用户删除实例时默认只移除配置；在浏览器已停止且明确勾选后，可以同时删除该实例的 User Data Dir。 | P1 |
| US-018 | 用户可让新实例数据与日志默认跟随 chub.exe 所在目录，并通过唯一实例名称获得可读、独立且可写的默认 User Data Dir。 | P1 |
| US-019 | 用户可以在实例列表中更清楚地阅读每条实例记录，并更稳妥地点击启动、编辑或删除操作，而不会改变既有快捷键和行操作规则。 | P1 |

## 验收场景

### US-003 占用保护

给定一个已运行的 Chrome/Edge，使用相同规范化 user data dir 启动时，系统拒绝第二次启动，显示已知 PID 和占用来源，并保留原配置。

### US-004 安全关闭

用户点击关闭后按钮进入 STOPPING；浏览器正常退出则显示 EXITED；等待超时后只显示强制终止确认，不自动扩大关闭范围。

### US-006 CLI/API

CLI/API 返回稳定错误码和结构化数据；未知 PID、身份不匹配和权限不足必须拒绝操作并给出恢复建议。

### US-007 本地 CDP 与外部关联

给定未占用的 user data dir，实例先保存一个首选 loopback CDP 端口；新建时从设置中的起始端口推荐一个不与其他 Chub 实例预留或实际端口冲突的值。启动优先使用该端口，并在后台检查实际可用性；若仅外部端口冲突，跳过 Chub 预留端口后回退到下一个可验证端口并更新当前实例的首选端口。列表区分建议、准备、实际和外部端口。给定同目录已由外部浏览器占用，只有 `DevToolsActivePort` 与 `/json/version` 可验证时才显示“外部已关联”；否则拒绝第二次启动。无论哪种外部状态，Chub 都不提供生命周期控制。

### US-008 刷新与编辑实例

给定已保存的实例，用户点击刷新或按 F5 后，Chub 只检查这些实例并更新运行状态、PID、端口与占用来源。用户双击行、按 Enter 或点击编辑图标可以打开编辑对话框；保存名称、浏览器类型、User Data Dir 和启动 URL 后更新本地配置。实际调试端口只读显示。若实例正在运行、启动中或为外部关联，浏览器类型和 User Data Dir 保持不可编辑。Escape 在无修改时关闭对话框，有修改时要求用户选择保存、不保存或继续编辑。

### US-009 代理选择

给定用户在设置中保存的无认证代理，设置下拉框和创建/编辑表单均展示完整地址。设置页默认输入为空；选择项会回填地址，保存会更新当前项或在未选择时新建。实例仅关联代理 ID；启动时使用该 ID 的最新端点。含用户名、密码或 URL 路径的端点被拒绝，仍被引用的代理不能删除；删除未引用项前要求确认。

### US-010 受管实例启停

给定 Chub 启动且仍可在 registry 中验证的实例，运行态主操作显示停止图标。点击后先显示停止中，再请求浏览器正常退出；成功后恢复启动图标。给定外部已关联或未知占用的同目录浏览器，Chub 不显示停止入口，也不发送关闭请求。

### US-011 受管实例意外退出

给定 Chub 在当前会话中启动且处于运行态的 Chrome/Edge，用户关闭最后一个浏览器窗口、浏览器崩溃或进程被外部结束时，Chub 等待该受管根进程句柄并把匹配实例更新为“已退出”。Chub 显示“检测到‘实例名’的 Chrome/Edge 已退出”的可关闭信息提示，说明配置和 User Data Dir 未被删除；关闭提示后焦点回到该实例的启动入口。给定 Chub 已请求优雅停止、外部关联/占用实例、过期启动代次或应用已关闭，Chub 不显示意外退出提示。

### US-012 只读 CDP 页面目标

给定一个“运行中”或“外部已关联”实例已经存在经验证的实际 loopback CDP 端口，用户从实例编辑对话框打开“查看标签页”，Chub 在后台再次验证 browser kind 后读取 `/json/list`，并显示页面目标的标题、类型和脱敏 URL。读取中可关闭对话框；请求失败、端点失效或实例状态变化时不改变实例配置或生命周期。给定未启动、启动中、停止中、调试不可用、外部占用或未知占用实例，入口禁用并说明需要已验证端口。页面目标查看不展示 WebSocket URL、物理窗口 ID，也不提供导航、关闭或创建页面命令。

### US-013 Windows 通知区域入口

给定 Chub 正在运行，Windows 通知区域出现一个 Chub 图标；用户双击图标或选择默认“显示 Chub”命令后，主窗口显示并置前。用户选择“刷新实例状态”后，Chub 沿用页面刷新相同的已保存实例范围和后台去重规则。用户选择“退出 Chub”后，应用进入明确退出协调流程并清理图标；该菜单不列出实例，也不提供启动、停止、重启、删除或外部接管。Explorer 重启后图标会恢复，图标失效仅显示可恢复诊断，不影响窗口和浏览器实例。首版关闭主窗口仍按原退出语义处理，不会自动隐藏到通知区域。

### US-014 便携配置迁移

给定用户从 `build\\chub.exe` 或已发布目录启动 Chub，配置读取和后续保存均使用同级 `config.json`，不受启动脚本或当前工作目录影响。给定目标配置不存在且旧 `%APPDATA%\\chub\\config.json` 合法，Chub 校验旧配置并原子写入目标，旧文件作为恢复备份保留。给定目标配置已存在，Chub 只读取目标，不覆盖、合并或删除它。给定目标目录不可写或旧配置畸形，Chub 不创建新文件、不丢失旧文件，显示可恢复的配置诊断；不得静默切回 AppData 造成后续配置分叉。

### US-015 代理名称与独立默认目录

给定用户在设置中选择已有代理，Chub 回填代理名称和完整无认证地址；用户保存时必须同时通过名称必填/不区分大小写唯一和地址格式/重复校验。给定已有实例选择该代理，用户修改其名称或地址后，实例保留相同 `proxyId`，列表立即显示最新名称，后续启动使用最新地址，已运行浏览器不被修改。给定用户打开新建实例表单，Chub 先分配稳定实例 ID，再填入实际 `chub.exe` 同级 `user_data_dirs\\<实例 ID>`；每次新建得到不同子目录。目录不可写或被用户改为空/非法路径时，保留表单输入并提供可恢复提示，不创建目录、不回退到当前工作目录，也不影响已有实例。

### US-016 浏览器 executable 选择与搜索反馈

给定用户位于设置页，点击 Chrome 或 Edge 路径旁的“选择”后，Chub 在后台打开 Windows 原生文件选择器，并只接受已有的绝对 `.exe` 文件。成功选择只更新对应输入框并在字段旁说明已选择；取消、错误或不合规路径保留原输入并给出可恢复说明。点击“搜索”后，按钮在任务进行期间显示“取消”；搜索发现标准安装路径时，即使结果与当前值相同，也在同一字段旁显示“已确认当前路径可用”。切换到实例页再返回后，输入、选择/搜索状态和字段反馈保持，不执行全盘扫描或任何浏览器进程操作。

### US-017 删除实例及 User Data Dir

给定用户点击实例删除图标，确认框默认只说明删除 Chub 配置，User Data Dir 保留。用户可以勾选默认未选中的“同时删除 User Data Dir 中的数据”；框内显示对象名称、目录路径和不可恢复提示，确认按钮变为“删除实例及数据”。仅当实例显示为“已退出”或“启动失败”时该选项可用；运行、启动/停止、外部关联、外部占用和未知占用状态明确提示先停止并刷新。确认后 Chub 在后台再次检查该目录的 Chub registry 与外部浏览器占用，并校验目录边界；删除成功才从列表和配置移除实例。用户取消、占用、目录边界、权限或 I/O 失败时，实例配置和 User Data Dir 都保持，用户可关闭浏览器、检查权限后重试。

### US-018 便携默认目录与唯一实例名称

给定用户在设置页保持“跟随程序目录”，新建实例时默认 User Data Dir 显示为实际 `chub.exe` 所在目录下的 `user_data_dirs\\instance-<安全化实例名>-<短ID>`，日志目录显示为同级 `logs`；快捷方式的工作目录不会影响二者。用户改选自定义目录后，只有之后新建实例与之后的日志写入受影响，已有 profile 不移动。提交新建或编辑实例时，名称去首尾空白并按 Windows 不区分大小写规则验证；若与其他实例重复，名称字段就地提示并保留输入。启动前后台创建并检查 profile 目录可写；若程序目录受保护或路径无效，浏览器不启动，用户可改选可写目录。