cdp_hub/docs/tasks/T-401.md

---
id: T-401
title: 已验证实例的 CDP 页面目标只读查看
phase: 4
deps: [T-302, T-303, T-310]
status: DONE
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` 通过。

## 执行记录

- 状态：DONE
- 变更：新增受限 `RemoteDebugTargetInspector`，先以 `/json/version` 复核 browser kind，再只读获取 `127.0.0.1:{actualPort}/json/list`；HTTP transport 禁用代理、拒绝重定向，响应限制为 1 MiB / 200 个目标，DTO 仅含 ID、类型、标题与脱敏 URL。主程序 adapter 仅接受运行中或外部已关联实例。Gio 编辑弹层新增“查看标签页”入口与只读目标模态层，后台异步读取并按实例 ID、状态/端口快照、请求代次拒绝过期结果；Escape 或关闭按钮会返回入口焦点。HTML 原型同步展示读取中、已读取、只读边界和关闭反馈。
- 验证：已执行 `gofmt -w internal/platform/browser/cdp.go internal/platform/browser/cdp_test.go cmd/chub/main.go cmd/chub/main_test.go internal/ui/shell.go internal/ui/shell_test.go`、`go test ./...`、`go test -race ./cmd/chub ./internal/ui`、`go vet ./...`、`go build -o build/chub.exe ./cmd/chub`、Node HTML T-401 原型检查和 `powershell -ExecutionPolicy Bypass -File scripts/smoke-windows.ps1`，均通过。
- 阻塞：无。