docs(用例管理): 新增语义化自然语言执行现状评估

记录『自然语言指明用例步骤 → 完整顺利执行』目标的现状、根因（执行器能力不对等 / keyword_matcher 不穿透 micro-app）与已尝试的优化（Phase 1-5）
Co-Authored-By: Claude <noreply@anthropic.com>

Docs/PRD/需求文档/用例管理/_难点分析_语义化自然语言执行现状评估.md

+# 难点分析：语义化自然语言执行现状评估
+
+> **文档版本**: v1.0
+> **创建日期**: 2026-08-31
+> **作者**: Claude Code
+> **状态**: 待评审
+> **目录**: `Docs/PRD/需求文档/用例管理/`
+> **关联文档**: `HANDOFF_UI自动化.md`（会话47）、`semantic_resolver.py`、`keyword_matcher.py`、`playwright_executor.py`、`_使用指南_语义化用例创建指导.md`
+
+---
+
+## 一、问题背景
+
+用户期望：**自然语言指明用例步骤** → 执行器**完整顺利执行**该步骤目标。
+
+当前实现：
+- 用例步骤可新增 `semantic` 字段（结构化业务意图：`type`、`text`、`contains`、`scope`、`container`、`nth`、`save_as` 等）。
+- 执行器 `playwright_executor.py` 在 `execute_step` 顶部会调用 `semantic_resolver.resolve_step()` 解析语义目标。
+- 解析成功后注入 `params["selectors"]`（高优先级），继续走现有 `_do_click`/`_do_fill`/`_do_check` 全部成熟回退策略（iframe/force/表格行/checkbox 状态校验）。
+- 已有文档《使用指南_语义化用例创建指导.md》（会话47产出）已覆盖字段全解、17步示范、最佳实践。
+
+**实际现状**：
+语义化用例（尤其是复杂多步交互用例）仍无法**完整顺利执行**，存在"能定位但执行失败"的现象（Handoff 会话47 已确认：登录页微前端语义解析失效、点击后页面状态不符、动态数据渲染后执行器回退链断裂等）。
+
+---
+
+## 二、根本原因
+
+### 2.1 执行器定位能力 vs 语义解析能力不对等（最核心，P0）
+
+- **语义解析器**（`semantic_resolver.py`）已集成：
+  - scope 软校验（防跨页误配）
+  - 映射表 v2 精确键 lookup
+  - 强结构模式选择器（row_checkbox/tab 等）
+  - keyword_matcher 规则候选 + Claude 按需仲裁
+- **但执行器**（`playwright_executor.py`）在执行时**没有**：
+  - 页面状态感知（点击后检测弹窗/抽屉/路由变化）
+  - iframe/微前端自动遍历 + 上下文限定
+  - 动态数据渲染后的执行器回退链（语义解析后渲染的 text/contains 仍可能在执行期失效）
+
+### 2.2 keyword_matcher 基线扫描逻辑未充分适配微前端场景（P1）
+
+- `match_element_by_keywords` 使用 `base_selector = 'input:visible, button:visible, ... .block:visible, p:visible'`。
+- 微前端（micro-app）场景下，`:visible` locator 组合未覆盖自定义元素内元素，登录页等微前端步骤解析失败（Handoff 会话47 已定位根因：keyword_matcher 扫不到微前端元素）。
+
+### 2.3 执行器缺少语义化执行完整链路
+
+- 语义解析成功后注入 selectors，但执行器在 `_do_click`/`_do_fill` 等方法中**没有**调用语义解析的回退能力（仅用预存 selectors）。
+- 缺少执行期页面状态校验（点击后需验证弹窗/抽屉是否打开）。
+
+### 2.4 其他遗留问题
+
+- 动态数据渲染后执行器仍依赖静态选择器（`{__CTX:...__}` 渲染后仍需执行器有回退）。
+- 某些复杂场景（多"确定"按钮、表格行操作、微前端内操作）仍需人工补丁。
+
+---
+
+## 三、已采取的优化尝试（Phase 1 → Phase 5）
+
+| 阶段 | 优化内容 | 主要文件 | 效果 | 遗留问题 |
+|------|---------|----------|------|---------|
+| Phase 1-2 | 语义数据模型 + 上下文变量 + scope 校验 | `semantic_resolver.py`、`ui_context.py`、`playwright_executor.py` | 复杂用例可录入，动态数据可传递 | 执行器未集成语义回退 |
+| Phase 3 | 映射表 v2 精确键 + 强结构模式选择器 | `element_mapping_service.py`、`semantic_resolver.py` | 部分静态元素命中率 100% | 微前端/动态场景仍依赖 keyword_matcher |
+| Phase 4 | keyword_matcher 集成 + Claude 按需仲裁 | `keyword_matcher.py`、`semantic_resolver.py` | 解决部分关键词撞车 | 微前端 `:visible` 扫描失效（会话47定论） |
+| Phase 5 | 执行器集成语义回退 + 页面状态感知 | `playwright_executor.py`（_resolve_selectors、_do_click 等） | 语义解析成功后有执行回退 | 仍需执行器具备完整语义执行链路（实时定位 + 状态校验） |
+
+**当前结论**：语义解析已实现（可产出选择器），但**执行器缺少"语义化执行完整链路"**（实时定位 + 页面状态感知 + 回退能力），这是导致"能定位但执行失败"的根本原因。
+
+---
+
+## 四、建议（用户确认后进入执行计划）
+
+**推荐方案**（对应 Handoff 会话47 定论）：**执行器集成语义解析能力**（方案A）。
+
+**实施步骤**：
+1. 在 `playwright_executor.py` 中实现 `_smart_locate_element()` 方法（实时调用 semantic_resolver）。
+2. 改造 `_do_click`/`_do_fill` 等方法，选择器失败时调用语义回退。
+3. 增加页面状态感知（点击后检测弹窗/抽屉）。
+4. 微前端场景下优化 keyword_matcher 的 base_selector（或引入新的微前端扫描策略）。
+5. 测试 + 回归。
+
+**预期效果**：复杂用例从"10+ 会话/几十处补丁" → "语义化步骤一次编写基本稳定"。
+
+---
+
+## 五、待用户确认
+
+- 是否同意进入执行计划（`/prd-plan`）？
+- 是否需要我先产出执行计划文档（`_执行计划_语义化自然语言执行.md`）？
+
+---
+
+*本文档由 Claude Code 于 2026-08-31 编写，记录"自然语言指明步骤 → 完整顺利执行"目标的现状、根因与已尝试的优化。*