sap-browser-automation

SAP 浏览器自动化

将此技能用作 SAP 专用技能的共享浏览器层。它负责界面选择、身份验证初始化、隔离的 Edge/CDP 启动、状态复用、目标验证、证据收集、故障恢复和清理。使用此技能的技能仍负责 SAP 操作边界：故事编辑、规划回写、模型更改、Datasphere 部署、SQL 执行和测试验收。

相关技能

• sap-sac-scripting：SAC 故事/运行时脚本编写和报表故事实现。
• sap-sac-test-automation：SAC 验收、探索包、Playwright 测试套件和证据收集。
• sap-sac-planning：SAC 规划模型、回写、版本、数据操作和锁。
• sap-datasphere：Datasphere 建模、部署、空间、连接和管理。
• browser:control-in-app-browser：已安装的应用内 Browser 运行时和安全的手动身份验证。

使用此技能的时机

当 Agent 必须与已通过身份验证的 SAP Web UI 交互、选择或检查浏览器目标、通过环回 CDP 启动 Edge、复用已获批准的 Edge 配置文件、将限定范围的浏览器状态转移到已安装的兼容客户端，或从浏览器初始化/身份验证失败中恢复时，请使用此技能。对于不需要可见浏览器状态的纯代码、纯 API、纯 CLI 或原生数据库任务，请勿使用此技能。

快速参考

需求	路径
在当前浏览器中手动进行 SSO	使用 In-app Browser，然后验证是否已登录
企业版 Edge 或未安装 Playwright	使用全新隔离的 Edge、复制的配置文件和环回 CDP
独立的兼容浏览器上下文	使用现有 Playwright，并通过限定范围的 storageState 或 CDP 转移状态
缺少身份验证或浏览器初始化失败	用户协助登录、故障恢复，或仅移交规范

用户指定的浏览器和连接方式具有约束力

如果用户指定 Chrome、Edge、Chrome DevTools MCP、CDP 或本地 DevTools 桥接程序，则只能使用该浏览器和连接方式。不得擅自改用 In-app Browser、ChatGPT 浏览器扩展、Playwright、Computer Use、其他浏览器或 Shell 自动化。如果指定的界面不可用，请报告确切的阻碍，并在该边界处停止。

操作约定

• 如果连接器、API、CLI 或数据库原生检查无需浏览器即可回答请求，优先使用它们。
• 仅当用户未指定其他浏览器或连接方式时，才优先使用应用内 Browser。
• 如果应用内 Browser 的目标页面重定向到 SSO，请用户在应用内 Browser 中手动完成身份验证。使用其安全身份验证功能；切勿在聊天中索要密码或 OTP。
• 应用内验证完成后，如果任务需要 CDP、企业扩展或可复用配置文件，请使用新的 Edge 路径，以便可靠地自动化操作。
• 将 MCP 配置和 MCP 可用性分开检查。配置完成后，确认 MCP 服务工具已出现在活动工具注册表中。仅成功执行 codex mcp get 检查，并不代表 MCP 已可用。
• 要求进行实时握手，例如调用 list_pages，并确认返回的页面属于指定浏览器。如果配置后仍缺少工具，请用户重启 Codex 或开启新任务，然后再继续。
• 重新使用用户已登录的常规 Edge 配置文件或关闭 Edge 前，必须征得用户明确许可。
• 仅在 Edge 关闭后复制，并复制到隔离的配置文件路径。将副本、Cookie、令牌、本地存储和存储状态文件视为凭据。
• 将 CDP 绑定到 127.0.0.1；切勿将端口、WebSocket 端点、配置文件或身份验证状态暴露给网络、代码库、日志、屏幕截图或 Oracle 审查。
• 交互前，先核实租户、主机、路径、标题、已通过身份验证的 DOM 和目标页面。切勿猜测第一个标签页或目标 ID。
• 默认只执行只读操作。使用该流程的 SAP 技能必须明确授权写入、发布、部署、规划、模型、权限或破坏性操作。
• 浏览器启动、CDP 附加或成功的登录重定向，都不能证明请求的 SAP 任务已完成。

仅在需要时加载针对性参考资料：

• Edge 启动、CDP 发现、目标选择和恢复，请参阅 references/edge-cdp-control.md。
• 复制已通过身份验证的 Edge 配置文件、在可用时导出限定范围的状态，并将其注入兼容客户端，请参阅 references/auth-state-bootstrap.md。
• 手动进行应用内身份验证及其能力边界，请参阅 references/in-app-browser-auth.md。
• 运行 scripts/edge-profile.ps1，以确定性的方式克隆配置文件并执行启动、状态检查和停止操作。
• 运行 scripts/cdp-agent.mjs，以发现目标、检查、交互、截屏并传输身份验证状态。它要求 Node.js 22 或更高版本，且无需 npm 包。

标准工作流

1. 对任务分类并选择操作界面

记录目标应用、租户/主机、请求的 URL、读写意图、所需证据，以及用户是否批准复用配置文件。按以下顺序选择：

1. 如果现有非浏览器工具足够，就使用该工具。
2. 用户明确指定的浏览器和连接方式（需先检查活动工具并完成实时握手）。
3. 如果用户未指定其他浏览器或连接方式，则使用应用内 Browser 查看已通过身份验证的界面，并手动完成 SSO。
4. 使用全新的隔离 Edge 和环回 CDP，以支持企业浏览器行为和可复用身份验证。
5. 使用已安装的 Playwright，通过 CDP 连接或使用本地存储状态。
6. 经批准的桌面/人工协助，或仅移交规范说明。

除非用户明确请求并批准，否则不要在企业环境中安装 Playwright、浏览器二进制文件、MCP 服务或扩展。如果 Playwright 不可用，Edge/CDP 仍是主要自动化操作界面。

2. 在应用内浏览器中进行身份验证

如果没有指定其他浏览器或连接，请使用已安装的 Browser 技能打开目标页面。 检查可见状态。如果页面需要 SSO，请暂停操作，让用户通过受支持的安全身份验证流程手动完成登录。验证目标域名上存在明确的已登录信号，并在允许的情况下保留屏幕截图或等效证据。

不要从应用内浏览器提取 Cookie、本地存储、会话存储、配置文件数据库、密码或令牌。它的会话与 Edge 独立。如果手动登录后仍无法显示已通过身份验证的页面，请记录失败情况，并继续使用获准的 Edge 路径。

此路径在 Codex 或 Claude Desktop 中运行。其运行时验证延后至这些桌面环境中进行，不属于独立的 Edge/CDP 验收测试。

3. 捕获实时 Edge 状态，然后引导启动全新的 Edge

在操作用户的常规 Edge 配置文件之前，说明预期操作范围并征求确认：

我将从当前已通过身份验证的 Edge 目标捕获获准的 SAP 会话，关闭常规 Edge，并将所选配置文件克隆到隔离的自动化目录中。可以继续吗？

如果用户拒绝，请让他们在隔离配置文件中进行一次身份验证。如果用户同意：

1. 确定常规 Edge 用户数据根目录、所选的 Default 或 Profile N、目标 URL、租户主机、目标路径/标题、获准的 SAP 来源，以及本地临时状态文件路径。
2. 在常规 Edge 仍在运行且可见已通过身份验证时，打开 edge://inspect/#remote-debugging，并启用 允许对此浏览器实例进行远程调试。
3. 针对常规用户数据目录运行 scripts/cdp-agent.mjs export-auth。要求使用主机、路径和/或标题筛选条件，且筛选结果必须唯一对应一个获准页面。对获准的 SAP 或身份提供方 Cookie 作用域重复使用 --origin。
4. 关闭常规 Edge，并验证没有 msedge.exe 进程仍在使用源配置文件。
5. 使用所选配置文件名称和新的或空的自动化根目录运行 scripts/edge-profile.ps1 -Action CloneLaunch。此帮助程序会保留 Profile N，拒绝非空的克隆目标，使用 --remote-debugging-port=0 启动，并验证通过 DevToolsActivePort 发现的侦听器。
6. 运行 scripts/cdp-agent.mjs inspect，并验证租户、路径、标题、可见的已登录状态以及页面就绪状态。
7. 如果克隆导致易失状态丢失，则针对隔离目标运行 scripts/cdp-agent.mjs import-auth，重新加载页面，并再次检查已通过身份验证的状态。
8. 如果身份验证仍失败，请让用户在隔离配置文件中登录一次。之后通过 scripts/edge-profile.ps1 -Action LaunchExisting 重用该配置文件；切勿覆盖已有内容的自动化根目录进行克隆。

完整的 Windows 命令、路径检查、CDP 探测和恢复方案见 references/edge-cdp-control.md 和 references/auth-state-bootstrap.md。

4. 操作已验证的目标

直接使用隔离的 Edge 实例。运行 scripts/cdp-agent.mjs --help 查看完整的命令功能。捆绑的驱动程序支持确定性目标、检查/快照、导航、求值、选择器或坐标点击、文本输入、按键、屏幕截图，以及无需 Playwright 的身份验证状态导出/导入。只有在使用方任务需要时，才使用现有的 Playwright 安装；不要为此工作流安装它。

身份验证状态通过 CDP Storage.getCookies 和 Storage.setCookies，以及页面范围的 localStorage 和 sessionStorage 进行传递。导入后重新检查 SSO 重定向、SameSite 行为、证书和可见的就绪状态。应用内浏览器仍使用独立会话。

5. 验证就绪状态并执行域操作

进行任何更改之前，请验证：

• 租户和应用身份；
• 已通过身份验证，而不只是访问了非登录 URL；
• 当前位于正确的 Story Designer、Modeler、Data Builder、SQL 编辑器或测试目标区域；
• 可见的就绪标记，且不存在阻塞性错误；
• 已批准的主机/路径和选定的目标页面；
• 当前模型/故事/组件元数据（当使用该技能的流程有此要求时）。

记录页面专属证据，并明确记录无数据/错误状态。不要将微调指示器消失、CDP 连接成功或浏览器窗口打开视为任务完成。

6. 如实恢复或移交

按以下后备流程操作：

1. 根据所选浏览器的文档化故障排除指南重试。
2. 使用 Edge/CDP 恢复流程和 DevToolsActivePort 后备方案。
3. 请求用户在隔离的 Edge 配置文件中进行一次性手动身份验证。
4. 如果环境支持，请使用已批准的桌面/手动协助。
5. 如果无法验证已通过身份验证的目标，请停止，并提供可直接实施的规格、确切缺失的证据以及下一步手动操作。

当用户明确指定了浏览器或连接方式时，不要通过此流程切换到其他界面。如果请求的界面不可用或实时握手失败，请停止。

将身份验证状态报告为 verified、missing、expired、blocked 或 unknown；绝不要仅凭浏览器引导过程推断身份验证成功。

故障排除

常见故障请参阅共享的 Edge 参考文档，其中包括 CDP 端点被拒绝或缺失、404 发现响应、目标错误、SSO 重定向、未通过身份验证的复制配置文件、策略阻止，以及运行时/组件错误。如果恢复流程无法建立已通过身份验证且经过验证的目标，请停止并移交缺失的证据，而不是猜测或声称已完成。

来源与验证

公开来源审查，以及文档化行为与未经验证的租户行为之间的区别，记录在 docs/project/sap-browser-automation-source-review-2026-07-14.md 中。

安全与证据

配置文件副本和身份验证状态文件可能包含 Cookie、刷新令牌、已保存的密码、历史记录、扩展程序和企业会话数据。请将其保存在访问受限的用户本地路径中。不要将它们放在代码库下、提交它们、发送给 Oracle、纳入错误报告，或将其内容粘贴到聊天中。从证据中移除租户 ID、故事 ID、查询字符串、类似会话的 URL 值、Cookie 值、WebSocket 端点和无关标签页。

对于任何具有写入能力的操作，请记录批准用户、目标、预期变更、变更前/后的验证结果，以及回滚或清理状态。使用该技能的 SAP 流程仍是判断操作本身是否获准的权威依据。