docs: define read-only CDP target viewing

docs/02-requirements.md

@@ -18,6 +18,7 @@
 | BR-014 | 用户可以在完整代理地址下拉框中维护无认证代理，并在创建或编辑实例时选择代理；代理认证信息不得保存、记录或进入启动参数。 | P1 |
 | BR-015 | GUI 实例主操作在 Chub 托管运行态提供优雅停止、在可启动状态提供启动；外部关联或未知外部实例不得获得生命周期控制。 | P1 |
 | BR-016 | 每个已保存实例有独立、持久化的首选远程调试端口；它与运行时实际端口分离，未启动实例仍可在列表看到建议端口。 | P1 |
+| BR-017 | 用户可以仅通过已验证的 loopback CDP 端点查看 Chub 实例的页面目标（标签页）标题、脱敏 URL 和类型；该功能不得控制页面、关闭标签页或接管外部浏览器。 | P1 |
 
 ## 验收标准
 
@@ -40,7 +41,9 @@
 - 受管运行实例点击主操作后进入关闭中，成功退出后恢复启动入口；停止失败不自动强制终止，也绝不影响其他 Chrome/Edge。
 - Chub 在当前应用会话中启动的 Chrome/Edge 根进程意外退出后，实例状态立即变为“已退出”，清空运行时 PID/端口，并显示包含实例名称和浏览器类型的可关闭提示；配置与 User Data Dir 保留，关闭提示后启动入口可用。
 - 用户从 Chub 发起优雅停止时，不显示“浏览器已退出”意外退出提示；外部已关联、外部占用、未知占用以及应用关闭后无法继续监控的实例均不弹出此提示。
+- 用户只能对“运行中”或“外部已关联”且已有实际、已验证 CDP 端口的实例打开页面目标查看；读取失败时保留实例配置和当前编辑内容，给出可恢复的重试提示。
+- 页面目标列表只显示标题、类型和移除 userinfo、query、fragment 的 URL；不得保存、记录、发布或展示 CDP WebSocket URL，也不得发送导航、关闭、创建或脚本执行命令。
 
 ## 不做
 
-全局杀 Chrome/Edge、自动登录、页面操作、验证码处理、平台 API 集成、远程控制和跨用户权限提升；通过 CDP 管理或关闭外部实例。
+全局杀 Chrome/Edge、自动登录、页面操作、验证码处理、平台 API 集成、远程控制和跨用户权限提升；通过 CDP 管理或关闭外部实例。首个 CDP 查看版本不提供物理窗口 ID 或分组，后续仅在经过独立安全评审的 WebSocket CDP 任务中考虑。

docs/04-architecture.md

@@ -13,6 +13,7 @@ Platform Windows
     ├─ Job Object
     └─ profile occupancy inspector
     ├─ loopback CDP endpoint inspector
+    ├─ loopback CDP target reader (read-only `/json/list`)
     ├─ remote-debug port allocator
     └─ instance status refresher
     ↓
@@ -42,8 +43,9 @@ UI/CLI 不直接操作 `exec.Cmd`、Win32 handle 或数据库。Application 层
 - Proxy：本地配置保存稳定 `proxy_id` 指向的代理库项（名称与无认证端点）；启动 adapter 在后台解析为当前 `LaunchSpec.ProxyServer` 快照。代理不能含 userinfo，删除被引用项会被拒绝；修改代理只影响后续启动，不影响已运行实例。
 - GUI stop：主操作只对 Chub registry 中可验证的托管实例调用 `StopProfile(userDataDir, false)`，随后有限等待 registry 释放。外部关联、占用和未知实例永远不调用停止接口；超时或失败不自动强制关闭。
 - 受管退出监控：仅为当前会话由 Chub 启动并获得进程句柄的实例建立一个 `Wait` 监控任务。退出事件携带实例 ID、启动代次和 PID，UI 仅在三者仍匹配且当前未处于 Chub 请求的停止中时，将运行时状态改为“已退出”并排队显示提示；过期事件、外部实例和应用退出后的监控取消均不得生成意外退出提示。
+- CDP 页面目标查看：UI 仅将当前已保存实例快照交给后台 adapter；adapter 只接受“运行中”或“外部已关联”的有效实际端口，先复核对应 browser kind 的 loopback `/json/version`，再读取同一端口的 `/json/list`。结果 DTO 仅含 target ID、标题、类型和脱敏 URL；UI 以实例 ID、端口和请求代次丢弃过期结果。该链路不建立 WebSocket、不开启页面控制，也不提供物理窗口 ID。
 
-Chrome 和 Edge 共用大部分 Chromium 参数，但 executable 默认路径、进程名称和安装方式不同，通过 `BrowserDefinition` 封装差异。CDP 端点只绑定 `127.0.0.1`；端口号和 `/json/version` 是诊断数据，WebSocket URL 不进入持久化、事件或普通 UI 文案。
+Chrome 和 Edge 共用大部分 Chromium 参数，但 executable 默认路径、进程名称和安装方式不同，通过 `BrowserDefinition` 封装差异。CDP 端点只绑定 `127.0.0.1`；端口号和 `/json/version` 是诊断数据，WebSocket URL 不进入持久化、事件或普通 UI 文案。`/json/list` 仅用于只读页面目标信息；URL 在 DTO 边界移除 userinfo、query 和 fragment。
 
 ## 风险
 

docs/06-tasks.md

@@ -47,6 +47,12 @@
 | T-309 | 实例首选调试端口与安全推荐分配 | T-302,T-303,T-308 | DONE |
 | T-310 | 实例创建与编辑表单边框层级 | T-308,T-309 | DONE |
 
+## Phase 4：CDP 只读观察
+
+| ID | 任务 | 依赖 | 状态 |
+| --- | --- | --- | --- |
+| T-401 | 已验证实例的 CDP 页面目标只读查看 | T-302,T-303,T-310 | DOING |
+
 ## Backlog
 
 CDP tab/window 管理、导入导出启动配置、进程资源监控、多用户权限和远程主机管理。

docs/07-user-stories.md

@@ -13,6 +13,7 @@
 | US-009 | 用户可以在设置中通过完整代理地址下拉框维护无认证代理，并在新建或编辑实例时从下拉选择器选择代理。 | P1 |
 | US-010 | 用户可以通过实例行的同一主操作启动或优雅停止 Chub 托管的浏览器，而不会关闭外部浏览器。 | P1 |
 | US-011 | 用户手动关闭 Chub 启动的 Chrome/Edge 后，可以立即获知该实例已退出，并重新启动该实例。 | P1 |
+| US-012 | 用户可以查看已验证运行实例的 CDP 页面目标标题、脱敏 URL 和类型，而不会向浏览器发送控制命令。 | P1 |
 
 ## 验收场景
 
@@ -47,3 +48,7 @@ CLI/API 返回稳定错误码和结构化数据；未知 PID、身份不匹配
 ### 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，也不提供导航、关闭或创建页面命令。

docs/08-interaction-checklist.md

@@ -13,6 +13,7 @@
 | IX-009 | 实例主启停操作 | 主操作、编辑、删除的固定顺序与间距；启动图标、停止图标、外部重新检测 | 已退出、启动中、托管运行、停止中、失败恢复、外部关联 | P1 |
 | IX-010 | 受管浏览器退出提示 | 受管根进程退出后的状态恢复、提示队列和焦点回归 | 意外退出、Chub 请求停止、多个同时退出、过期事件、编辑/确认弹层打开、应用关闭 | P1 |
 | IX-011 | 实例首选调试端口 | 新建/编辑端口推荐、列表建议/准备/实际/外部文案、启动回退与保存 | 旧配置迁移、重复/非法端口、外部冲突、启动失败、外部关联、过期结果 | P1 |
+| IX-012 | CDP 页面目标查看 | 编辑弹层的“查看标签页”、只读目标列表与关闭 | 无可验证端口、读取中、空列表、读取失败、状态变更、Escape/焦点回归 | P1 |
 
 ## 通用规则
 
@@ -29,3 +30,4 @@
 - 实例主操作根据归属和状态切换启动、停止、重新检测或禁用，并固定排在编辑和删除之前。停止中禁止重复请求；停止失败恢复原状态并保留焦点。外部关联不显示停止入口；行内图标间距与命中区必须避免误操作。
 - 受管浏览器意外退出是当前会话的异步状态提示，不是用户确认决策：状态先更新为“已退出”，再显示可关闭信息弹层；弹层只含“知道了”，Escape/Enter 均可关闭，关闭后焦点回到对应启动入口。多个退出合并到一个提示；已有编辑、未保存确认或删除确认弹层时排队，不能丢弃输入或叠加模态层。Chub 发起停止、外部实例、代次/PID 不匹配和应用退出取消监控时均不提示。
 - 调试端口的“建议/准备/实际/外部”必须同时以文字和数值表达，不能将首选端口称为已监听端口。创建和停止实例编辑使用首选端口输入；运行中、启动中、停止中和外部关联实例只读。推荐仅基于 Chub 保存实例，系统端口复检与 CDP 校验只在后台启动任务执行；回退不得使用其他 Chub 实例的逻辑预留端口。
+- CDP 页面目标查看是只读、可关闭的临时对话框：入口仅对已有实际已验证端口的“运行中”或“外部已关联”实例可用；打开后焦点位于关闭按钮，Escape 关闭并回到“查看标签页”入口。读取中、空列表和错误均用文字表达，错误不丢失编辑输入；结果只含标题、类型和脱敏 URL，不能把目标 ID、WebSocket URL 或物理窗口 ID当作控制授权。

docs/api.md

@@ -8,6 +8,23 @@ MVP 首先提供本地 Go application service 和 CLI；是否增加 loopback HT
 
 `LaunchSpec` 使用已分配的 `RemoteDebugPort`；端口分配不属于 UI，也不允许由 `ExtraArgs` 覆盖。`InstanceView` 返回实际关联端口、PID、占用来源和归属。外部关联只公开经 `DevToolsActivePort` 与 `/json/version` 验证的端口，不公开 CDP WebSocket URL。
 
+只读 CDP 目标查看使用 platform `RemoteDebugTargetInspector`：
+
+```go
+type RemoteDebugTarget struct {
+    ID    string
+    Type  string
+    Title string
+    URL   string // 已移除 userinfo、query 与 fragment
+}
+
+type RemoteDebugTargetInspector interface {
+    ListRemoteDebugTargets(ctx context.Context, kind BrowserKind, port int) ([]RemoteDebugTarget, error)
+}
+```
+
+调用者必须提供当前实例已经验证的实际端口；实现仍会复核 `/json/version` 的浏览器类型。该接口只请求 loopback HTTP `/json/list`，不公开或使用 `webSocketDebuggerUrl`，也不提供导航、关闭、创建 target 或执行脚本的接口。
+
 UI 编辑使用独立的 `EditableInstance` DTO（`ID`、名称、浏览器类型、User Data Dir、启动 URL、`ProxyID`），不将运行时 PID、状态、来源或实际远程调试端口写回配置。`ProxyProfile` DTO 只包含 `ID`、名称和已校验的无认证端点；不提供认证字段。状态刷新使用 `RefreshInstanceStatus(ctx, []InstanceSnapshot) ([]InstanceStatusResult, error)` 形状：每个结果以 `ID` 和快照版本对应，错误可按行返回；实现只能检查调用方提供的实例范围。
 
 ## Application service
@@ -30,7 +47,7 @@ GUI 将优雅停止封装为异步 `InstanceStopper(ctx, InstanceRow) error` ada
 
 参数数组由 `internal/platform/browser.BuildArgs` 生成；Chrome/Edge executable 由同包 `Discoverer.Resolve` 解析。二者都不接收 shell 命令行字符串。CDP 端点检测和端口分配均通过 platform port 执行，UI 只消费 DTO 结果。
 
-状态刷新、受管进程退出和目录选择必须通过后台 adapter 回到 UI 结果通道；UI frame 不直接做进程、文件或 CDP I/O。受管退出结果至少包含实例 ID、启动代次、受管 PID、退出码和是否为 Chub 请求停止；UI 以实例 ID、代次和 PID 丢弃过期结果。刷新不构成外部实例接管授权。
+状态刷新、受管进程退出、目录选择和 CDP 页面目标读取必须通过后台 adapter 回到 UI 结果通道；UI frame 不直接做进程、文件或 CDP I/O。受管退出结果至少包含实例 ID、启动代次、受管 PID、退出码和是否为 Chub 请求停止；UI 以实例 ID、代次和 PID 丢弃过期结果。刷新和页面目标读取都不构成外部实例接管授权。
 
 ## CLI 当前合约
 

docs/current-state.md

@@ -3,7 +3,7 @@
 ## 快照
 
 - 日期：2026-07-27
-- 阶段：Phase 3 真实实例操作（T-301 至 T-310、T-201 至 T-208 已完成）
+- 阶段：Phase 4 CDP 只读观察（T-301 至 T-310、T-201 至 T-208 已完成；T-401 进行中）
 - 代码：已建立 Go module `chub`、`cmd/chub` 入口、logging 测试基座、浏览器 domain/application 合约、Chrome/Edge 参数/发现模块、启动 registry、Windows 身份/占用检查、loopback CDP 端口分配与端点校验、优雅关闭、Job Object、真实 Chrome/Edge smoke、JSON 配置存储、启动恢复、CLI JSON 合约、应用内事件总线、UI 状态测试和 Windows smoke 脚本，T-001 至 T-003、T-101 至 T-104、T-201 至 T-208、T-301 至 T-309 已完成
 - UI：Gio 双页 Shell 使用左侧“实例/设置”导航；实例页以等宽“新建实例 / 刷新实例状态”命令区开始，窄内容区自动堆叠。列表固定显示实例名称、浏览器类型、用户数据目录、调试端口、状态和带边框的操作列；端口列在未启动/已退出时显示“建议 {端口}”、启动中显示“准备 {端口}”、托管运行显示“实际 {端口}”、外部关联显示“外部 {端口}”，避免将持久首选端口误作监听事实。新建表单从设置的起始端口推荐最低未冲突端口，编辑停止实例可修改首选端口；启动后台优先该端口并避开其他实例的首选/实际端口，成功回退后才保存新的首选值。操作顺序固定为启动/停止（或重新检测）、编辑、删除，删除与相邻操作保持更大间距以降低误点。主操作在已退出时启动，在 Chub 托管运行或调试不可用时显示停止，在启动/停止中禁用，在外部关联、外部占用或未知占用时仅重新检测；优雅停止通过后台 adapter 验证 registry 的 PID/profile 身份并等待其释放，绝不按进程名关闭或接管外部 Chrome/Edge。刷新通过后台回调只检查已保存实例，以配置快照丢弃编辑或删除后的过期结果；它结合 Chub registry、指定 profile 的外部占用证据和 loopback CDP 端点更新状态，但不扫描、接管或关闭其他 Chrome/Edge。双击、Enter 或编辑图标打开实例编辑弹层，支持名称、浏览器类型、User Data Dir、启动 URL、首选端口、完整地址代理选择和只读实际端口；保存保留未公开启动选项，Escape 对脏表单先请求确认，活跃/外部关联实例锁定身份约束字段。设置页使用完整代理地址选择器、地址输入及保存/删除操作；选择会回填地址，保存按稳定 `proxyId` 新增或更新，删除未引用代理前必须确认，仍被实例引用的代理会被拒绝。启动通过异步回调接到 Windows 浏览器启动器：未占用目录从已保存的起始端口（空值默认 9666）选择 loopback CDP 端口，并在启动时按已选代理 ID 解析最新的 `--proxy-server` 参数；同目录外部浏览器只有在 `DevToolsActivePort` 与 CDP 端点可验证时才显示“外部已关联”，且不会接管其生命周期。删除使用确认弹层，只删除 Chub 实例配置而不删除 User Data Dir。新建、编辑和删除实例会保存到本地配置；四个设置路径有独立异步可取消搜索，切换页面后输入和任务状态保留；新建实例表单使用 Label、Windows 原生目录选择器和 Chrome/Edge RadioButton；CLI `list/events` 已可用，`start/stop/restart` 等待 BrowserManager adapter
 - T-307：本应用会话启动的受管 Chrome/Edge 根进程由单实例后台 `Wait` 监控；意外退出按 ID、启动代次和 PID 验证后立即变为“已退出”，清空运行时 PID/端口，并以可关闭、可合并的提示告知用户。提示关闭后焦点回到启动操作；Chub 请求停止、外部实例、过期事件和应用关闭取消监控均不提示。
@@ -11,7 +11,7 @@
 - 浏览器核心：设计参考来自 `D:\OPC\shop_helm\internal\platform\chrome`，尚未复制或接入本项目
 - T-309：实例保存 `PreferredRemoteDebugPort`，旧 JSON 读取时按稳定顺序补齐；配置拒绝无效或重复端口。推荐仅基于保存实例快照，启动后台跳过其他实例的逻辑预留和当前实际端口；成功的本地端口回退会保存为新的首选值。实际 CDP 端点仍是运行时端口唯一事实来源。
 - T-310：实例新建页使用外层工作区、字段组件和操作区三级边框；编辑弹层使用可辨外框，并为字段、运行态信息、反馈和操作区添加一致描边。紧凑窗口下沿用原有路径/操作重排，字段状态和键盘交互未改变。
-- blocker：无。
+- blocker：无；T-401 正在实现已验证实例的只读 CDP 页面目标查看。
 
 ## 当前目录
 

docs/tasks/T-401.md

@@ -0,0 +1,38 @@
+---
+id: T-401
+title: 已验证实例的 CDP 页面目标只读查看
+phase: 4
+deps: [T-302, T-303, T-310]
+status: DOING
+created: 2026-07-27
+owner: codex
+---
+
+## 需求与边界
+
+用户需要确认一个已运行实例中打开了哪些页面，但首版必须维持只读和最小 CDP 能力。平台只可向经 browser kind 复核的 `127.0.0.1:{actualPort}/json/list` 发起有限 HTTP 请求；GUI 仅通过后台回调获取 DTO。
+
+- 仅“运行中”或“外部已关联”且已有有效实际端口的实例可请求页面目标。外部关联仅允许读取，不产生生命周期接管授权。
+- 返回每个 target 的 ID、标题、类型与脱敏 URL；URL 必须移除 userinfo、query 和 fragment。不得保存、日志记录、事件发布或显示 `webSocketDebuggerUrl`。
+- 不建立 WebSocket，不调用 CDP 命令；不提供导航、刷新、创建、关闭标签页、执行脚本或物理窗口 ID/分组。
+- 编辑对话框操作区提供“查看标签页”入口。结果显示在可关闭模态层；读取中、空列表、端点失效、状态变化和关闭后过期结果都有文本反馈。Escape 关闭并把焦点返回入口。
+- 请求有超时、响应字节数与目标数量上限；UI frame 不执行 HTTP I/O。删除、刷新、退出或端口变化后，旧结果不得覆盖当前视图。
+
+## 设计决策
+
+`/json/list` 返回的是 CDP target，不含可靠的物理窗口 ID。T-401 因此将 UI 命名为“标签页（CDP 页面目标）”，不把 target 列表误称为窗口管理。未来如需窗口分组，应单独评审 WebSocket CDP、授权和更高风险控制能力。
+
+## 验收要点
+
+- Chrome 与 Edge 的有效 loopback endpoint 在再次验证版本后可读取 `/json/list`；无效端口、browser kind 不符、非 200、超时、畸形/超限响应返回稳定的端点不可用错误。
+- 目标 DTO 排除 WebSocket URL 并脱敏 URL；列表显示标题、类型和 URL，空结果明确提示。
+- 对未启动、启动中、停止中、调试不可用、外部占用或未知占用实例，“查看标签页”不可提交；对运行中和外部已关联实例可用，但不产生任何浏览器控制调用。
+- GUI 请求异步、防重复、可关闭；按实例 ID、实际端口和请求代次拒绝过期结果。错误和空列表不丢失编辑表单状态；Escape 关闭查看层并恢复焦点。
+- HTML 原型和 Gio 使用同一文案与状态；覆盖 platform、adapter、UI 状态与过期结果测试。`gofmt`、`go test ./...`、`go test -race ./cmd/chub ./internal/ui`、`go vet ./...`、`go build -o build/chub.exe ./cmd/chub`、HTML 脚本检查和 `scripts/smoke-windows.ps1` 通过。
+
+## 执行记录
+
+- 状态：DOING
+- 变更：待实施。
+- 验证：待执行。
+- 阻塞：无。