admin/action-topology-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add topology graph v0.2.2 contract

Browse Source
This commit is contained in:
赵义仑
2026-06-24 09:47:23 +08:00
parent a7458265c0
commit 2f12fe8cda
16 changed files with 1041 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
schemas/topology-graph.schema.md
View File

@@ -1,6 +1,6 @@
# Topology Graph Schema
This document describes the JSON shape emitted by the engine. It is a practical schema note, not yet a formal JSON Schema file.
This document describes the JSON shape emitted by the engine. A formal JSON Schema is also provided in `schemas/topology-graph.schema.json`.
## `TopologyGraph`
@@ -24,6 +24,7 @@ This document describes the JSON shape emitted by the engine. It is a practical
- `edges`: observed actions from one state to another.
- `skippedActions`: state-local default-explorer actions that risk policy refused to execute.
- `failedObservations`: failed locator, actionability, action, or effect observations recorded as evidence.
- `summary`: machine-readable artifact counts and grouped counts.
## Evidence Levels
@@ -64,11 +65,12 @@ This document describes the JSON shape emitted by the engine. It is a practical
- `locatorId`: locator candidate id.
- `elementId`: parent element id. This must equal the containing `ActionableElement.elementId`.
- `framework`: `playwright` or `css`.
- `strategy`: locator strategy such as role, label, placeholder, text, test id, or CSS.
- `strategy`: locator strategy such as role, label, placeholder, text, test id, CSS, or scoped.
- `descriptor`: structured locator descriptor.
- `expression`: human-readable locator expression.
- `score`, `reason`, `verified`, `matchCount`, `failureCount`, `lastVerifiedAt`: ranking and verification metadata.
- `scopes`: context-scope evidence such as row, dialog, form, or section anchors. In v0.2.1 scopes are ranking and disambiguation evidence only; they are not executable scoping unless descriptor support is added.
- `scopes`: context-scope evidence such as row, dialog, form, or section anchors.
- `descriptor.kind: "scoped"`: executable scoped locator descriptor. In v0.2.2 this contains a scope descriptor plus a base target descriptor, with row, dialog, form, and list-item scopes used for execution when available.
- `identity`: semantic identity checks for tag, role, accessible name, text, and visibility.
- `evidence`: generation and verification facts.
@@ -82,6 +84,7 @@ This document describes the JSON shape emitted by the engine. It is a practical
- `confidence`: confidence in observed edge replayability.
- `createdAt`: ISO timestamp for edge capture.
- In v0.2.1 default exploration replays each edge from a clean entry-state context.
- Navigation timeout during entry or replay can be recorded as `FailedObservation` instead of aborting artifact generation.
## `EffectRecord`
@@ -103,8 +106,16 @@ This document describes the JSON shape emitted by the engine. It is a practical
## `FailedObservation`
- `failedObservationId`, `stateId`, optional `elementId`, optional `actionType`: failed observation identity.
- `stateId` may be `null` for graph-level failures such as entry navigation timeout before any state exists.
- `reason`: machine-readable failure code.
- `message`: diagnostic message.
- `evidence`: observed facts explaining the failure.
- `createdAt`: ISO timestamp for the failure record.
- `FailedObservation` covers hidden, disabled, obscured, locator, action, and effect failures. Risk-policy default-explorer refusals belong in `SkippedAction`.
## `summary`
- `states`, `elements`, `edges`, `skippedActions`, `failedObservations`: total counts for the artifact.
- `failedObservationsByReason`: count map keyed by `FailedObservation.reason`.
- `skippedActionsByRiskCategory`: count map keyed by skipped action risk category.
- `edgesByRiskCategory`: count map keyed by executed edge risk category.