A3L

中文 README

A3L is a compact AI-first language that lets agents prefer more expressive HTML artifacts over Markdown while emitting only tiny A3L source, saving 380x output tokens on the covered production corpus. It is inspired by A2UI, but it is not JSON. The MVP here ships a parser, a Web emitter, CLI, examples, tests, compression benchmarks, and visual showcase pages.

Visual Showcase

Two production showcase pages are built with A3L itself and live in dist/. Click any thumbnail for the full interactive page rendered live in your browser (no install needed).

A3 内置能力展览馆 50 capsules · 点卡片即弹出实时预览 + 原始 A3L 源码对比 Live preview ↗ · Full screenshot · Raw HTML

A3 价值与生产级证据 Token 压缩、三层数据、覆盖矩阵、验证体系，全部来自可重复脚本 Live preview ↗ · Full screenshot · Raw HTML

Both pages are self-contained single HTML artifacts produced by npm run build:showcase; the live-preview links above route through htmlpreview.github.io so anyone can open them directly from GitHub without cloning.

A3L means Agent Abstract Assembly Language:

• Agent: designed for AI agents first, not human hand-authoring first.
• Abstract: expresses UI/development intent above raw HTML/CSS/JS.
• Assembly: keeps the source terse, compact, and compiler-oriented.
• Language: defines an independent DSL with a deterministic compiler boundary.

A2UI's useful lesson is architectural: keep structure, state, and actions declarative. A3L keeps that separation but uses terse glyph forms because JSON spends too many tokens on keys, quotes, commas, and braces.

Example

Production A3L starts with capsules: high-level intent opcodes that compile into full HTML/CSS/JS.

!counter#app"Counter"

Run the real token benchmark:

npm run bench:tokens

Current o200k_base results exceed the 20x target on every production capsule case; see reports/token-report.md.

A3L now uses a three-layer expansion model:

• Lower syntax for exact one-off HTML/CSS/state/event work.
• Middle components for 26 self-contained reusable modules that can be nested inside custom layouts.
• Upper capsules for full-page/page-flow intents, now composed from middle components plus small lower-layer glue.

See docs/ARCHITECTURE.md for the extension model, docs/COMPONENT_CATALOG.md for the full built-in surface, docs/DESIGN_SYSTEM_RESEARCH.md for the design-system rationale, and reports/layer-report.md for measured layer ratios.

Lower-layer A3L is still available when the AI needs exact markup, styles, state, and events:

=t"Counter"
main#app.app(h1"A3L Counter" p#read($n) button#inc.btn"+")
.app{w:360;mx:a;mt:18vh;p:28;ta:c;bg:#fff;br:16}
.btn{p:10/18;bd:0;br:999;bg:#111827;c:#fff;cur:p}
$n=0
#inc@click{n++;#read.txt=n}

Compile it:

npm test
node bin/a3c.js examples/capsule-counter.a3 -o dist/counter

Default generated file:

• index.html

a3c prints exact token compression stats after every compile, using the A3L source and the generated single HTML file. If a three-file bundle is explicitly needed, use:

node bin/a3c.js examples/capsule-counter.a3 --bundle -o dist/counter-bundle

Language Surface

• !counter#app"Counter": production capsule.
• =t"Title": metadata.
• main#id.class(...): HTML tree.
• .class{p:24;br:8}: CSS with aliases.
• $n=0: state.
• #btn@click{n++;#out.txt=n}: event action list.

See docs/SPEC.md for the formal MVP grammar and alias table. See docs/AI_AUTHORING_GUIDE.md for the short prompt surface that was used in Codex AI smoke tests.

Verification

npm test
npm run bench:coverage
npm run bench:layers
npm run agent:smoke
npm run ai:smoke

npm run ai:smoke invokes local codex exec, asks it to author A3L from short requirements, compiles the result, and verifies the output. Latest results are stored in reports/ai-smoke.md.

For the full production gate:

npm run verify:prod

Dependencies

The compiler uses the mature Node.js runtime and node:test. The only dev dependency is @dqbd/tiktoken, used for real OpenAI-compatible tokenizer measurement with o200k_base.

Agent Presentation Adapter

To let a general coding agent use A3L instead of long Markdown reports, append the short snippet in agent-adapter/ONE_MINUTE_INSTALL.md to AGENTS.md or CLAUDE.md.

Manual smoke test:

echo '!status#app"Adapter Ready"[state=Ready ok=1 warn=0 fail=0 next="Use A3L for structured summaries"]' | node bin/a3present.js -

Research Notes

Public A2UI docs describe a JSONL/JSON-oriented protocol with component catalogs and a separation between UI structure and state. A3L takes the separation principle, then replaces JSON with compact source forms and a target-neutral IR so future emitters can target shell commands or other development languages.

References:

• https://a2ui.org/introduction/what-is-a2ui/
• https://a2ui.org/introduction/core-concepts/