79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# Action Topology Engine
|
|
|
|
Small deterministic tool for building a website action topology graph.
|
|
|
|
The project intentionally does not include an LLM, a generic browser agent, or a large workflow platform. Its job is to observe a site, describe states and actionable elements, generate verifiable locator candidates, and record action edges with observable effects.
|
|
|
|
## Current Scope
|
|
|
|
- Open a URL or local HTML file with Playwright.
|
|
- Capture reproducibility metadata: browser, viewport, locale, auth mode, crawl session id, input fingerprint, and policy/scoring versions.
|
|
- Capture one page state with DOM and visible-text fingerprints.
|
|
- Extract actionable elements: buttons, links, inputs, selects, textareas, roles, tab stops, and click handlers.
|
|
- Generate locator candidates with scores, context scopes, identity checks, and verification evidence.
|
|
- Optionally run low-risk one-hop click exploration from a clean entry state.
|
|
- Replay actions from the entry state and record observed state transitions with snapshot-diff effects.
|
|
- Record state-local skipped default-exploration actions when risk policy blocks them.
|
|
- Record failed observations instead of turning failed locators or failed actions into successful edges.
|
|
- Emit state nodes, elements, locators, action edges, skipped actions, failed observations, and metadata in JSON.
|
|
|
|
## Non-Goals
|
|
|
|
- No LLM decision making.
|
|
- No natural-language task planner.
|
|
- No high-risk automatic actions.
|
|
- No full crawler or breadth-first site exploration.
|
|
- No general browser agent or workflow orchestration platform.
|
|
- No attempt to fully recover frontend business functions in this engine.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Commands
|
|
|
|
Static scan:
|
|
|
|
```bash
|
|
npm run scan -- --url ./examples/simple.html --out artifacts/simple-scan.json
|
|
```
|
|
|
|
Tests:
|
|
|
|
```bash
|
|
npm run test
|
|
```
|
|
|
|
Entry-state low-risk exploration:
|
|
|
|
```bash
|
|
npm run example
|
|
```
|
|
|
|
Build:
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
## Output Model
|
|
|
|
The output JSON follows the schema described in [schemas/topology-graph.schema.md](schemas/topology-graph.schema.md).
|
|
|
|
Key objects:
|
|
|
|
- `TopologyGraph.metadata`: artifact version, input URL, entry URL, generated timestamp, engine version, mode, non-deterministic crawl session id, deterministic input fingerprint, runtime context, site, and policy/scoring versions.
|
|
- `StateNode`: URL, route, title, canonical key, language, viewport, state hashes, modal stack, lifecycle, evidence, and first observed `openedByEdgeId`.
|
|
- `ActionableElement`: state-local element semantics, visibility/interactability, bounding box, context anchors, parameter surface, evidence, and locator candidates.
|
|
- `LocatorCandidate`: Playwright-friendly locator descriptors plus score, verification status, context `scopes`, identity evidence, and failure count.
|
|
- `ActionEdge`: low-risk replayed action from one state to another through an element, with `riskCategory`, `riskLevel`, and snapshot-diff `effects`.
|
|
- `EffectRecord`: snapshot-diff record for `url`, `dom`, `visibleText`, or `actionableInventory`, with `before` and `after` values.
|
|
- `SkippedAction`: risk-policy default exploration refusal with risk category, reason, state id, element id, and evidence.
|
|
- `FailedObservation`: locator, actionability, action, or effect failure with machine-readable reason and diagnostic evidence.
|
|
|
|
## Source Notes
|
|
|
|
The originating ChatGPT share conversation is preserved in [docs/source/chatgpt-share-6a30e583.md](docs/source/chatgpt-share-6a30e583.md).
|