experience-lwc-runtime-observe

预览 LWC Runtime — 本地开发 + DOM 检查

指导 Agent 依次完成通常会一起执行的两项工作：

1. 使用 Salesforce CLI 启动 Lightning Preview 会话，让 LWC 应用或组件在本地开发环境中渲染。
2. 导航到该预览 URL 并提取运行时 DOM 子树，以便 Agent（或用户）了解实际渲染的内容。

DOM 检查的前提是启动预览。请按此顺序进行。

何时使用此技能

• 用户想在部署前于本地预览 LWC 应用或组件 （sf lightning dev app / sf lightning dev component）。
• 用户想获取特定组件在运行时渲染的 HTML 子树，用于比较差异、截图流水线，或了解 shadow DOM。
• 用户询问为什么模板内容“不在 DOM 中”——这几乎总是对 shadow DOM 的误解，可在步骤 2 中处理。

先决条件

• 已安装 Salesforce CLI（sf）。使用 sf version 检查。
• 已安装 @salesforce/plugin-lightning-dev。使用 sf plugins 检查。
• 已通过身份验证的 org（sf org list 至少显示一个已连接的 org）。
• 如需提取 DOM：Agent 执行环境中可用浏览器自动化工具（Playwright、Puppeteer、Chrome DevTools Protocol——具体取决于已接入的工具）。

---

步骤 1 — 启动 Lightning Preview

询问用户（或根据请求推断）目标范围是 app 还是 component。

1a. 验证工具链

询问用户（或根据请求推断）预览应面向哪个 org 别名。使用该别名运行随附的验证脚本，并显示脚本输出的任何错误——不要在说明文字中再次调用 sf version / sf plugins / sf org display。该脚本会检查 CLI 是否存在、是否安装了 @salesforce/plugin-lightning-dev，以及指定目标别名是否已通过身份验证且处于 Connected 状态；如果失败，则会以非零状态退出并提供可执行的错误消息：

"<skill_dir>/scripts/verify-toolchain.sh" <orgAlias>

如果脚本报告目标别名未通过身份验证或不处于 Connected 状态，请引导用户前往 启用本地开发 并运行 sf org login web --alias <orgAlias>，然后在继续之前重新运行 验证脚本。

1b. 查看子命令的标志

# For app scope
sf lightning dev app --help

# For component scope
sf lightning dev component --help

注意区分必需与可选标志。如果必需标志含义不明确，请在运行前询问用户。

1c. 启动预览

每条预览命令前都加上 OPEN_BROWSER=false——CLI 默认会打开 浏览器窗口，而 Agent 操作时不希望如此。 （该环境变量未在 --help 中说明；除非用户明确要求打开浏览器窗口，否则请使用它。）

范围	命令
app	OPEN_BROWSER=false sf lightning dev app -o <orgAlias> -n <appName> -t desktop
component	OPEN_BROWSER=false sf lightning dev component -o <orgAlias> -n <componentName>

预览启动后，记录 URL，并严格按以下格式输出：

Lightning Preview running at URL: <URL>

如果任何子步骤失败，请停止并向用户显示错误——不要试图掩盖身份验证或插件安装问题。

---

步骤 2 — 提取运行时 DOM

仅当步骤 1 已生成可访问的预览 URL 后，才运行此步骤。

2a. 获取经过身份验证的入口 URL — 不将令牌暴露给 Agent 上下文

sf org open --url-only --json 返回的入口 URL 包含一个用于验证会话的短时有效 OTP。**切勿直接运行 sf org open——其输出会进入 Agent 工具输出流，并将身份验证令牌泄露到对话记录中，违反 Agent 安全标准 S1。**捆绑的辅助脚本是获取该 URL 的唯一受支持方式：它在内部运行 sf org open，将标准输出重定向到权限为 chmod 600 的临时文件，并抑制标准错误，因此 URL 片段或令牌子串绝不会进入 Agent 上下文。

请改用捆绑的辅助脚本。该脚本会将 URL 写入权限为 chmod 600 的临时文件，并且只输出 export 赋值语句（不包含任何令牌信息）。先捕获辅助脚本的输出，确保非零退出状态会中止调用方——单独使用 eval "$(...)" 会掩盖失败，导致 Agent 在 $FRONTDOOR_URL_FILE 未设置的情况下继续执行：

frontdoor_env="$("<skill_dir>/scripts/open-frontdoor.sh" <orgAlias> <previewUrl>)" || exit 1
eval "$frontdoor_env"

辅助脚本会抑制 sf 和 python3 的标准错误与标准输出，因此不完整的 URL 和进度信息都不会进入 Agent 对话记录。

浏览器驱动必须：

1. 从 $FRONTDOOR_URL_FILE 读取 URL。
2. 导航到该 URL 以建立会话。
3. 使用后立即删除临时文件。
4. 切勿 cat 或以其他方式回显文件内容。

**OTP 令牌很快就会过期。**先启动浏览器驱动，然后在即将导航时调用辅助脚本——否则令牌会过期。

2b. 导航并等待

1. 在自动化浏览器中打开步骤 1 中的预览 URL。
2. 等待网络空闲，并等待初始渲染完成。
3. 如果预期元素不存在，先短暂等待再重试，然后再判定失败——本地开发页面有时会分两个阶段完成水合。

2c. 提取子树

两个确定性的字符串操作——将组件名称转换为 c-<kebab> 选择器，以及用精确的 DOM_OUTPUT_START / DOM_OUTPUT_END 标记包裹提取出的 HTML——由 <skill_dir>/scripts/extract-dom.sh 处理。不要重新推导选择器，也不要在说明文字中拼接标记；请调用该脚本。

实际的 DOM 遍历必须由浏览器自动化驱动（Playwright / Puppeteer / CDP）执行；该脚本不会驱动浏览器。

如果 scope 为 component

按确定性方式计算选择器：

selector="$("<skill_dir>/scripts/extract-dom.sh" selector <componentName>)"

然后使用驱动穿透 lwr_dev-preview-container 的 shadow root，定位与 $selector 匹配的第一个可见元素，并读取其子树 HTML（通过 element.shadowRoot.innerHTML）。将该 HTML 传入包裹步骤：

printf '%s' "$html_subtree" \
  | "<skill_dir>/scripts/extract-dom.sh" wrap component <componentName>

如果 scope 为 app

使用驱动识别主要应用根节点（优先选择 document.body 或主应用容器，而不是 document.documentElement），排除 <head> 和未渲染的节点，并读取子树 HTML。将其传入包裹步骤：

printf '%s' "$html_subtree" \
  | "<skill_dir>/scripts/extract-dom.sh" wrap app

将脚本的标准输出原样作为 DOM 输出发出。

2d. 关于 LWC Shadow DOM（最常见的陷阱）

Lightning Web Components 使用 Shadow DOM。模板内容无法直接通过宿主元素查询：

访问方式	获取内容
element.innerHTML	为空，或仅包含插槽中的 light-DOM 内容
element.outerHTML	只有宿主标签，没有子元素
element.shadowRoot.innerHTML	实际渲染的模板内容

如果浏览器驱动的 DOM 查询默认不会穿透 shadow root，请显式遍历 shadowRoot。大多数现代自动化驱动都提供穿透 shadow root 的查询辅助工具——请使用它。

---

示例

如需完整的端到端示例（预览组件、安全地捕获入口 URL，并提取其 DOM），请加载 examples/component-preview-and-dom.md。

---

验证清单

• 针对目标别名运行 <skill_dir>/scripts/verify-toolchain.sh <orgAlias>，退出状态为 0。
• 使用 OPEN_BROWSER=false 运行预览命令。
• 日志中记录的预览 URL 格式为 Lightning Preview running at URL: <URL>。
• 通过 <skill_dir>/scripts/open-frontdoor.sh 获取入口 URL（切勿直接运行 sf org open）。
• DOM 提取使用 shadowRoot 遍历（不要对宿主使用 innerHTML）。
• DOM 输出由 <skill_dir>/scripts/extract-dom.sh wrap … 生成（标记由脚本负责）。

---

故障排除

• verify-toolchain.sh 报告“目标组织别名未通过身份验证或未连接” — 运行 sf org login web --alias <orgAlias>（该别名必须与传递给 verify-toolchain.sh 的别名以及预览命令使用的 -o 值一致）。
• verify-toolchain.sh 报告缺少插件 — 使用 sf plugins install @salesforce/plugin-lightning-dev 安装。
• 预览打开了浏览器窗口 — 你忘记设置 OPEN_BROWSER=false。
• 提取的 DOM 为空 — 你查看的是宿主上的 innerHTML。请改用 element.shadowRoot.innerHTML。同时确认你已穿透 lwr_dev-preview-container shadow root。
• 入口令牌失效 — 令牌已过期。重新调用 <skill_dir>/scripts/open-frontdoor.sh，并在约 60 秒内导航。