本地项目截图被导航策略中断：需要受控且可随升级保留的开发预览授权

**提交人**: Karl L
**客户端版本**: 0.1.73

---

## 问题与影响
Agent 完成本地 Web 项目修改后，用户要求查看实际界面截图；独立外置浏览器在打开本地开发服务器时返回 `browser navigation blocked by policy`，任务因此停在“代码已改、实际画面未验证”。用户需要的是可用且随官方升级保留的本地预览能力，而不是反复改安装包或关闭安全策略。

关联已有问题 #2325；本报告补充实际工具复现与交付中断的影响，请维护者按重复问题关联处理。相关方案 #2445 已关闭且未合并；#2942 仍未合并，不能作为当前正式版已具备的解决办法。

## 已实际复现
在同一 Cindy 专用外置浏览器中：
1. 使用 browser.open 打开 https://example.com，成功。
2. 使用 browser.navigate 打开本机开发服务的 loopback URL（形如 http://127.0.0.1:端口/）。
3. 返回 HTTP 400、`BROWSER_RUNTIME_ACTION_FAILED`，错误为 `browser navigation blocked by policy`。
4. 无法进入后续 snapshot/screenshot；诊断标签页随后已关闭。

这是本次实际工具复现，不是根据错误文字猜测。用户此前也在请求本地页面截图时遇到相同错误；整体发生比例未知。未验证侧边栏后端，不把结论泛化到所有浏览器模式。

## 定位
已检查安装版打包代码：managed browser 的 ssrfPolicy 只包含 `allowRfc2544BenchmarkRange` 和 `allowIpv6UniqueLocalRange`，没有本地预览授权。这与 #2325 中描述的独立外置浏览器默认策略一致，而非网站故障或 fake-IP 修复失效。

本地源码中的 hostname 级白名单候选仅能证明放行 loopback 可消除这一类拒绝，不能证明它安全或已经在安装版生效。本次没有修改 app.asar、关闭 SSRF、重启当前客户端，或将这个候选部署为正式修复。

## 建议的持久解决方向（用户明确要求提交方案）
- 为用户明确指定的开发服务提供受支持的预览授权入口，以当前任务与精确 origin（协议、主机、端口）为边界；不默认信任所有 localhost 端口。
- 同一授权范围内后续导航、交互、截图复用授权，避免每一步重复确认；地址或端口变化时重新判断。
- 在请求发出前校验重定向各跳，拒绝未授权的其它端口、私网与元数据地址；覆盖失效/撤销及任务结束的授权清理。
- 区分本地预览未授权与普通网络失败，并给出可执行的官方恢复入口。不要让 Agent 只看到一句 policy error 后中止验证，也不要诱导其裸跑浏览器绕过限制。
- 静态 HTML 预览与 Vite 等开发服务器分别验收；静态产物入口不能直接当作带开发服务器功能的等价替代。
- 方案进入官方源码、自动回归测试和正式发布流程；若引入用户配置，明确升级迁移与恢复默认语义，不依赖修改安装包或替换更新器。

## 建议回归范围
已授权 origin 的 open/navigate → snapshot/screenshot；相邻端口拒绝；IPv4/IPv6 边界；公网重定向到未授权本机服务拒绝；授权过期和撤销；配置透传及升级迁移。需要真实正式打包链路验收，不能仅用单测通过宣称用户问题已解决。

当前状态：根因与复现已确认；尚无已部署、已端到端验证的修复。
---
## 提交时的任务环境

仅代表提交时快照,不一定是故障环境。OS 来自提交客户端本机,不含 SSH 远端主机;Harness / 模型来自当前任务。与运行环境无关的反馈可忽略本段。
**OS**: darwin arm64 (25.5.0)
**Harness**: Codex
**Model ID**: ` gpt-6-astra `
**界面语言**: zh-CN

Start by tracing the managed browser navigation path and its ssrfPolicy, then compare browser.open and browser.navigate behavior for loopback URLs. Review the existing issues #2325, #2445, and #2942 before defining scope. Done requires an approved origin-scoped authorization flow, redirect and lifecycle checks, regression coverage for the listed boundaries, and validation through the formal packaging and upgrade path.

Written by the indexing model from the issue text.