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

docs: document topology graph v0.2 contract

Browse Source
This commit is contained in:
赵义仑
2026-06-16 21:20:35 +08:00
parent 1ea4c52ad1
commit a7458265c0
4 changed files with 213 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -4,48 +4,107 @@ This document describes the JSON shape emitted by the engine. It is a practical
## `TopologyGraph`
- `schemaVersion`: currently `0.1`.
- `schemaVersion`: currently `0.2`.
- `metadata.artifactVersion`: currently `topology-graph-v0.2`.
- `metadata.inputUrl`: raw URL or file path supplied by the caller.
- `metadata.entryUrl`: entry URL after Playwright navigation.
- `metadata.generatedAt`: ISO timestamp for this artifact generation.
- `metadata.engineVersion`: engine implementation version that emitted the artifact.
- `metadata.mode`: `scan` or `explore`.
- `metadata.crawlSessionId`: unique non-deterministic identifier for this graph generation session. It is intentionally different across runs.
- `metadata.inputSeed`: caller-supplied input seed. In v0.2 this is the raw `inputUrl`.
- `metadata.inputFingerprint`: deterministic hash of input URL, mode, and policy/scoring versions.
- `metadata.runtimeContext`: browser engine, viewport, locale, timezone, and auth context.
- `metadata.site`: base URL and entry URL.
- `metadata.riskPolicyVersion`: currently `risk-policy-v0.2`.
- `metadata.normalizationRuleVersion`: currently `normalization-v0.2`.
- `metadata.locatorScoringVersion`: currently `locator-scoring-v0.2`.
- `states`: page states.
- `elements`: actionable elements bound to a state.
- `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.
## Evidence Levels
- `observed`: directly captured browser fact.
- `derived`: deterministic rule output from observed facts.
- `verified`: re-resolved or replay-verified claim.
- `heuristic`: conservative inference such as risk classification.
- `external`: human or downstream annotation.
## `StateNode`
- `stateId`: stable id derived from URL, DOM hash, visible text hash, and actionable signature hash.
- `url`, `route`, `title`: browser-visible state identity.
- `domHash`: hash of full `document.documentElement.outerHTML`.
- `visibleTextHash`: hash of normalized visible body text.
- `actionableSignatureHash`: hash of actionable element signatures.
- `modalStack`: visible dialogs or modal-like surfaces.
- `openedByEdgeId`: edge that opened this state, if known.
- `stateId`: stable id derived from URL, normalized state hashes, and actionable signatures.
- `lifecycle`: `observed`, `fingerprinted`, `verified`, `stale`, `deprecated`, or `conflicted`.
- `url`, `route`, `urlCanonicalKey`, `title`, `language`, `viewport`: browser-visible and normalized state identity.
- `stateHash`, `domHash`, `visibleTextHash`, `actionableSignatureHash`: deterministic state fingerprints.
- `modalStack`: visible modal context.
- `frameContext`: reserved frame context path. In v0.2.1 this is emitted as an empty array.
- `openedByEdgeId`: first edge that observed this state in the current run. It is not the only possible predecessor.
- `createdAt`: ISO timestamp for state capture.
- `evidence`: observed and derived state facts.
## `ActionableElement`
- `elementId`: stable id within the captured state.
- `elementId`: state-local element id. It encodes state identity and must not be treated as a global DOM node id.
- `stateId`: owning state.
- `tag`, `role`, `accessibleName`, `text`, `label`, `placeholder`: semantic identity.
- `attributes`: selected stable attributes such as `data-testid`, `id`, `name`, `type`, `href`, and ARIA fields.
- `bbox`: page-space bounding box.
- `attributes`: selected stable attributes such as test id, id, name, type, href, and ARIA fields.
- `bbox`: geometry.
- `framePath`, `shadowPath`: reserved containment paths. In v0.2.1 these are emitted as empty arrays.
- `interactability`: visibility, enabled/editable status, and whether the element receives events.
- `context`: nearest dialog, form, section, row, landmark, and list item anchors.
- `parameterSurface`: input/select/textarea constraints, options, required state, pattern, min/max, and maxLength.
- `locators`: scored locator candidates.
- `evidence`: observed and derived element facts.
## `LocatorCandidate`
- `descriptor`: structured Playwright locator descriptor.
- `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.
- `descriptor`: structured locator descriptor.
- `expression`: human-readable locator expression.
- `score`: ranking score.
- `verified`: whether it resolved to exactly one element during capture.
- `matchCount`: observed locator match count.
- `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.
- `identity`: semantic identity checks for tag, role, accessible name, text, and visibility.
- `evidence`: generation and verification facts.
## `ActionEdge`
- `fromStateId`, `toStateId`: source and resulting states.
- `elementId`: action target.
- `actionType`: currently focused on `click`, with type support for future `fill`, `select`, and navigation actions.
- `preconditions`: reserved for stored open paths.
- `effects`: URL, visible text, network, download, dialog, storage, or DOM effects.
- `riskLevel`: `low`, `medium`, or `high`.
- `edgeId`: action edge id.
- `fromStateId`, `toStateId`, `elementId`, `actionType`: source state, resulting state if observed, target element, and action kind.
- `actionParams`, `preconditions`, `parameterSpecs`: action payload and future replay metadata.
- `effects`: snapshot-diff effects observed after replay.
- `riskLevel`, `riskCategory`: risk classification used by default exploration.
- `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.
## `EffectRecord`
- `type`: exactly one of `url`, `dom`, `visibleText`, or `actionableInventory`.
- `before`, `after`: populated for v0.2.1 snapshot-diff effects.
- `description`: human-readable effect summary.
- v0.2.1 emits snapshot-diff effects only: URL, DOM hash, visible text hash, and actionable inventory hash.
- Network, storage, download, and dialog event buffers are not emitted in v0.2.1 and are future work, not current contract.
## `SkippedAction`
- `skippedActionId`, `stateId`, `elementId`, `actionType`: state-local skipped action identity.
- `riskLevel`, `riskCategory`: risk-policy classification.
- `reason`: policy decision string such as `blocked:destructive`.
- `evidence`: risk-policy evidence explaining why the action was skipped.
- `createdAt`: ISO timestamp for the skip record.
- `SkippedAction` is only for risk-policy default-explorer refusals. Hidden, disabled, obscured, duplicate-locator, locator-not-found, action, and effect failures are `FailedObservation`.
## `FailedObservation`
- `failedObservationId`, `stateId`, optional `elementId`, optional `actionType`: failed observation identity.
- `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`.