action-topology-engine/docs/design/action-topology-engine-v0.2.md

# 网站可操作拓扑引擎设计文档 v0.2

## 0. 文档读法

本文同时保留两类内容：

- **v0.2.1 当前输出契约**：已经由当前代码、`README.md`、`schemas/topology-graph.schema.md` 和 `src/types.ts` 支持的 artifact 形态。
- **未来设计目标**：拓扑引擎后续可以演进的方向，但不代表 v0.2.1 已经发出或支持。

没有明确标注为 v0.2.1 当前输出契约的扩展能力，都应按未来设计目标理解，不能作为当前 artifact 消费合同。

## 1. 项目定位

本项目是一个确定性的 website action topology engine。它的职责不是自动完成任务，也不是理解自然语言指令，而是为一个网站建立可被机器消费的“可操作拓扑图”。

它输出的是底层地图：页面有哪些状态，状态中有哪些可操作项，这些可操作项如何稳定定位，执行动作后产生什么可观察变化。

## 2. 明确边界

本项目只负责拓扑图。

不负责 rrweb 录制，不负责将 rrweb 对齐到拓扑，不负责生成浏览器自动化脚本，不负责生成 skill，不负责 LLM 规划，不负责通用浏览器 Agent。

这些都可以是下游消费者，但不能反向污染本项目的模型边界。

## 3. 核心世界观

网站不是一组 DOM 节点，而是一组可操作状态。

基本认知单元是：

```text
State -- Action(Actionable Element) --> State / Observable Effects
```

真正有价值的不是“页面上有一个按钮”，而是“在某个状态下，有一个可定位、可验证、可执行的动作；执行后，浏览器世界发生了某些可观察变化”。

### 3.1 确定性的含义

本项目所谓确定性，不是指同一个网站每次探索都会得到完全相同的图。真实网站会受到账号、权限、数据、时间、A/B 实验、feature flag、语言、viewport、网络和服务端状态影响。

这里的确定性指：拓扑事实的来源、生成规则和验证方式是可复验的。引擎只依据可观察、可记录、可复验的浏览器事实生成拓扑，不依赖不可验证的推测。

因此，每份拓扑 artifact 都必须带有生成上下文：入口 URL、账号角色、环境、viewport、locale、浏览器类型、登录状态、采集时间、站点版本或数据特征。同一网站在不同上下文下可以生成不同拓扑，引擎不强行合并。

### 3.2 网站状态不是页面截图

State 不是截图，也不是完整 DOM 快照。State 是在特定环境上下文下，页面在某一时刻呈现出的可操作上下文。

拓扑关心的是：哪些动作可见、可定位、可执行；执行后世界如何变化。像素差异、随机节点、埋点、广告、时间戳，不应轻易制造新状态。

### 3.3 v0.2.1 当前输出契约

v0.2.1 当前 artifact 输出以下事实：

- `TopologyGraph` metadata、state、element、locator、edge、skipped action、failed observation。
- state 的 URL、route、title、language、viewport、DOM hash、visible text hash、actionable signature hash、state hash、modal stack 和 lifecycle。
- element 的语义字段、bbox、interactability、context anchors、parameter surface、locator candidates 和 evidence。
- locator candidate 的 Playwright/CSS descriptor、score、verification metadata、identity evidence、failure count 和 `scopes`。
- 默认探索只从干净 entry-state context 执行低风险 one-hop click replay。
- risk policy 拒绝的默认探索动作记录为 `SkippedAction`。
- locator、actionability、action 或 effect 失败记录为 `FailedObservation`。
- effect 只发出 snapshot-diff 类型：`url`、`dom`、`visibleText`、`actionableInventory`；这些 v0.2.1 effect 会填充 `before` 和 `after`。

v0.2.1 当前不发出 network、download、dialog、storage effect buffer；不捕获真实 frame/shadow path；不发出可执行的 row/card action template；`frameContext`、`framePath`、`shadowPath` 字段存在，但当前实现为空路径。locator `scopes` 只是证据和排序/消歧线索，不是可执行 scoped descriptor。

## 4. 设计目标

拓扑图面向机器消费，目标是稳定、可复验、可解释。

它应该让下游系统判断：当前状态是否已知，某动作是否存在，目标元素如何定位，动作前需要什么状态，动作后应该观察什么结果，动作风险如何，失败时原因是什么。

## 5. 核心概念

`State`：页面的可操作上下文。URL 只是其中一部分；弹窗、菜单、抽屉、tab、筛选条件、可见文本、可操作项集合都会影响状态。frame 和 shadow DOM 是未来设计目标中的状态边界；v0.2.1 当前只保留空路径字段，不捕获真实 frame/shadow 层级。

`Actionable Element`：某个状态下可由浏览器执行动作的对象。它不能脱离状态全局存在。同样一个“保存”按钮，在不同弹窗或表格行中是不同元素。

`Locator Candidate`：定位该元素的一组候选方法及其证据，不是单个 selector，也不是对 DOM 结构的永久承诺。

`Action Edge`：从一个状态经过一个动作到另一个状态的边。边的价值在于记录动作和结果，而不是只记录“点击过”。

`Effect`：动作后的可观察变化。v0.2.1 当前只发出 URL、DOM hash、visible text hash 和 actionable inventory hash 的 snapshot diff。网络请求、弹窗事件、下载、storage、history、focus、validation 等属于未来设计目标；没有对应代码前，不能作为当前输出契约。

`Parameter Surface`：动作或元素可接受的参数形态。拓扑引擎不负责生成业务参数，但应记录输入槽位、约束和来源证据。

`Risk Classification`：对动作探索风险的保守分类。它不是业务授权，也不是最终执行许可，只用于指导拓扑探索和下游消费时的风险处理。

`Evidence Level`：拓扑字段的证据等级，区分直接观察、规则推导、复验结论、启发式猜测和外部标注。

### 5.1 事实与证据等级

拓扑 artifact 中的信息必须区分证据等级。

`Observed Fact` 是直接来自浏览器的事实，例如 URL、DOM 属性、AX role、bounding box、visibility、enabled 状态。network request 观察属于未来设计目标，不是 v0.2.1 当前 artifact 字段。

`Derived Fact` 是由确定性规则推导出的信息，例如状态签名、元素上下文、locator 候选评分、重复元素分组。

`Verified Claim` 是经过重新加载、重新定位、重新执行或效果复验后确认的信息。

`Heuristic Guess` 是启发式判断，例如某动作可能高风险、某输入框可能是客户编号。

`External Annotation` 是人工或下游系统补充的信息，不属于拓扑引擎原生事实。

拓扑引擎可以存储启发式信息，但不能把启发式信息伪装成已验证事实。

### 5.2 Risk Classification

风险分类回答的是：这个动作是否适合默认探索，是否可能造成副作用，是否需要人工确认或沙盒环境，是否应该只记录不执行。

建议风险类型包括：`read_only`、`navigation`、`ui_reveal`、`input_edit`、`form_submit`、`data_mutation`、`destructive`、`auth_sensitive`、`payment_sensitive`、`unknown`。

`read_only`、`navigation`、`ui_reveal` 通常可作为默认探索候选。`input_edit` 可以记录但默认不提交。`form_submit`、`data_mutation` 默认不探索。`destructive`、`auth_sensitive`、`payment_sensitive` 默认只记录不执行。`unknown` 按高风险处理。

### 5.3 Parameter Surface

很多动作不是简单 click，而是填写、选择、上传、筛选、提交、选择表格行或对业务对象执行动作。

拓扑不需要知道“应该填什么”，但需要知道参数面：输入框的 type、name、label、placeholder、required、pattern、maxlength、validation；选择控件的 options、selected value、disabled options；日期控件的格式、范围和边界；表单的字段、必填项、提交动作和校验行为。网络 body 线索属于未来设计目标，不是 v0.2.1 当前输出字段。

它的目标是让下游知道：这个动作需要哪些输入，哪些是必填，约束是什么，输入和后续 effect 是否有关联。

## 6. 状态建模原则

状态必须从机器能复验的事实出发，而不是从页面名称出发。

同一个 URL 可以有多个状态，不同 URL 也可能落到相似状态。状态判断不能只靠路由。v0.2.1 当前状态签名由 URL、title、DOM hash、visible text hash 和 actionable signature hash 派生，并记录 modal stack。frame/shadow 边界和更细的业务上下文归并是未来设计目标。

### 6.1 State Lifecycle

State 在拓扑中应有生命周期。

`observed` 表示首次观察到。`fingerprinted` 表示已生成状态签名。`verified` 表示经过重新进入或复验，关键可操作项仍成立。`stale` 表示曾经有效但近期复验失败或证据过期。`deprecated` 表示确认不再可达或被新状态替代。`conflicted` 表示不同页面上下文被错误归并，或同一签名下出现不兼容事实。

下游应优先消费 verified 状态，对 observed 或 stale 状态保持谨慎。

### 6.2 状态等价与归并

状态归并应服务动作判断，而不是追求像素级一致。

时间戳、随机 id、埋点节点、广告、非目标列表数据轻微变化、loading 到 loaded 的瞬态变化，通常不应单独构成新状态。

可操作项集合变化、modal/dialog/drawer/menu 打开或关闭、tab/stepper 改变、form schema 改变、权限导致动作可见性改变、关键筛选条件改变、目标业务对象上下文改变，通常应构成新状态。frame 上下文改变应构成新状态是未来设计目标；v0.2.1 当前不捕获真实 frame context。

未来状态签名应优先基于 URL canonical form、可见可操作项签名、关键 heading/landmark、modal stack、selected tab、form signature、frame path、shadow boundary 和业务对象上下文，而不是完整 DOM hash。v0.2.1 当前状态 hash 仍包含 DOM hash、visible text hash 和 actionable signature hash；这不是 frame/shadow/state-signature 完整捕获能力。

## 7. 元素建模原则

元素应按用户感知和浏览器语义识别，而不是按 DOM 结构识别。

重要证据包括角色、可访问名称、标签、占位符、可见文本、ARIA 信息、输入类型、是否可见、是否启用、是否接收事件、所在上下文、附近标题、所属表格行、所属弹窗或表单。

框架特征只作为线索，不作为地基。React、Vue、Angular、AntD、MUI 等只说明页面可能有动态 id、portal、虚拟列表、隐藏副本等风险。

## 8. 定位哲学

定位器以可复现为目标，而不是以当下能找到为目标。

优先级应是用户视角和显式契约：role、label、placeholder、text、test id、稳定业务属性。CSS 和 XPath 只能作为 fallback。

locator 是否可信，不能只看它是否匹配一个节点，还要看它是否匹配正确语义，是否重载后仍成立，是否命中隐藏副本，是否依赖脆弱结构，是否需要上下文消歧。

## 9. 上下文消歧

真实页面里“编辑”“查看”“删除”“保存”“确定”会大量重复。v0.2.1 当前记录 dialog、form、section、row、landmark、listitem 等 context anchors。card 专用 anchor 属于未来设计目标。

机器需要的是“客户 A 这一行的编辑按钮”，不是“第 3 个编辑按钮”。

### 9.1 重复结构与动作模板

v0.2.1 当前不会发出可执行的 row/item/card action template，也不会把 locator `scopes` 编译成 scoped execution descriptor。当前 artifact 只记录 context anchors 和 locator scopes 作为证据、排序和消歧线索。

未来设计目标中，重复元素不应全部平铺为互不相关的独立元素。

表格每行的“编辑”、订单卡片的“查看详情”、文件列表的“下载”，未来应尽量表达为 row/item/card action template。

模板会记录重复容器类型、候选 identity 字段、行或卡片上下文、动作元素相对位置、动作语义、风险等级和 locator 消歧方式。下游执行时，应先定位目标 row/card，再在该上下文内定位动作。只有在新增可执行 scoped descriptor 支持后，这一段才可作为当前执行合同。

## 10. 动作边原则

动作边表达一个可验证的行为关系。

它应说明：从哪个状态出发，作用于哪个元素，动作类型是什么，是否需要参数，风险如何，动作后出现什么可观察 effect，结果状态是否可识别。

### 10.1 Handler Trace 不是核心事实

未来如果运行环境允许，引擎可以记录事件监听器、调用栈、source map 映射和框架组件线索。

但 Handler Trace 只能作为辅助证据，不应成为动作边成立的前提。动作边的核心事实来自动作前状态、目标元素、动作类型、可观察 effect、结果状态、定位复验和风险分类。

### 10.2 失败观察

失败不是噪声。失败应记录为 Failed Observation，而不是伪装成成功动作边。

典型失败包括：`locator_not_found`、`locator_not_unique`、`element_hidden`、`element_disabled`、`element_obscured`、`state_precondition_missing`、`frame_inaccessible`、`shadow_root_closed`、`navigation_timeout`、`network_error`、`permission_denied`、`auth_required`、`captcha_or_challenge`、`risk_policy_blocked`、`effect_not_observed`、`unexpected_state`。

失败观察要帮助下游判断：是 locator 坏了，状态没到，页面变化了，权限不够，风险策略拦截，还是目标本身不存在。

## 11. 探索策略原则

默认探索必须保守。少而准，比广而脆更符合本项目价值。

低风险动作可以探索；提交、确认、支付、授权、删除、注销等动作应记录为高风险，不默认执行。探索目标不是点遍所有东西，而是建立可靠、可复验的拓扑边。

## 12. 输出契约

拓扑 artifact 应该是机器可读、稳定演进、可版本化的事实集合。

它不包含下游意图，不描述“如何完成某个业务任务”，不内置 skill 语义。它只提供事实：状态、元素、定位候选、动作边、效果、风险、失败原因和证据等级。

### 12.1 Artifact 版本化

每次生成或更新拓扑，应记录 artifact version、schema version、site identifier、base URL、crawl session id、browser engine、viewport、locale、auth context、created time、input seed、risk policy version、normalization rule version、locator scoring version。

拓扑更新不应简单覆盖旧结果。系统应支持比较状态差异、locator 健康度变化、新增或消失动作、风险等级变化、effect 变化，并能标记 stale 或 deprecated 状态。

### 12.2 拓扑事实不等于任务语义

拓扑引擎未来可以记录某按钮文本是“导出”，某请求路径包含 `/export`，某动作产生下载事件。v0.2.1 当前不记录网络请求路径，也不发出下载事件 effect。

但它不应在内部上升为“完成导出销售报表任务”的 skill。

拓扑图描述的是：在什么状态下，什么元素可被定位，可以执行什么动作，动作后出现什么可观察效果，这个动作有什么风险。

它不描述用户真正想完成什么业务目标，不选择业务路径，不决定业务参数，不包装 skill，不根据自然语言规划动作序列。

## 13. 成功标准

好的拓扑图应该满足：状态不是靠 URL 粗暴判断；元素绑定到具体状态；locator 有候选和可信理由；重复元素可以通过上下文区分；动作边有可观察 effect；高风险动作不被默认执行；失败原因能被机器理解；下游系统不需要重新猜测页面结构。

frame/shadow/modal 边界都不应被忽略是未来质量目标。v0.2.1 当前只实现 modal/context 相关记录；frame/shadow 字段为空路径，不能视为已实现捕获能力。

### 13.1 质量指标

拓扑质量应能被度量。

核心指标包括：`state_match_accuracy`、`locator_unique_rate`、`locator_stability_rate`、`action_effect_observed_rate`、`duplicate_disambiguation_success_rate`、`risk_false_negative_rate`、`risk_skip_rate`、`failed_observation_explainability_rate`、`stale_detection_rate`、`downstream_reguess_rate`。

其中最重要的反向指标是 `downstream_reguess_rate`。如果下游仍要重新猜页面结构，说明拓扑没有履行职责。

## 14. 设计底线

本项目必须保持底层拓扑引擎的克制。

一旦它开始理解用户任务、生成脚本、包装 skill、绕过风控、或者做智能规划，它就越界了。

它应该像地图测绘，不像司机；像浏览器行为地形图，不像自动驾驶系统。

## 15. 一句话总结

本项目要建立的是：**网站可操作世界的确定性拓扑地图**。

它记录浏览器事实，抽象页面状态，识别可操作项，生成可验证定位候选，观察动作效果，并把这些组织成下游机器可以信任的图。