Skip to content

README.zh-CN.md

Latest commit

 

History

History
211 lines (145 loc) · 9.63 KB

README.zh-CN.md

File metadata and controls

211 lines (145 loc) · 9.63 KB
Raw

A3L

English README

A3L 是一门 AI-first 紧凑语言，也是一个可安装的 Agent Skill。它把较长的结构化结果整理成易扫读、类 PPT 的单文件 HTML 汇报：Agent 只需编写很短的非 JSON A3L 源码，由编译器确定性地生成完整页面，并用一个产物链接加短文本 fallback 完成交付。

安装 Agent Skill

一条命令安装自包含的 a3l skill，并交互选择支持的 Agent 和安装范围：

npx skills add agent-dance/A3L --skill a3l

需要仍在安全支持期内的 Node.js 22 或更高版本。

全局、非交互安装：

# Codex
npx skills add agent-dance/A3L --skill a3l --global --agent codex --yes

# Claude Code
npx skills add agent-dance/A3L --skill a3l --global --agent claude-code --yes

安装后新开一个 Agent 会话。遇到较长的状态报告、项目评审、计划、对比、流程、仪表盘、发布说明、风险、决策或复盘时，skill 应优先生成类 PPT 汇报；也可以明确要求：用 A3L 把结果做成类 PPT 总结。 很短的回答、代码、原始命令输出、错误堆栈和明确要求 Markdown 的任务仍使用文本。

成功时只交付一个 HTML 链接和短 fallback，不再复制一份完整 Markdown：

View: dist/present/<topic>.html

<短 fallback 摘要>

平台专用命令和源码仓库 fallback 见 一分钟安装。

正确理解 Token 数据

A3L 有三类不同的 token 指标，不能混用：

  • A3L → HTML 展开比：衡量一小段 A3L 能生成多少 HTML。仓库内 o200k_base 语料当前报告 460.45x 源码到 HTML 展开比；它证明了紧凑编写和渲染器复用能力，不是 Markdown 节省结论。
  • 语义等价格式 A/B：把等价 Markdown 报告与“A3L 源码 + 短产物交付”对比。仓库内 12 场景全部保留原始事实，短/中/长报告的 P50 输出节省分别为 24.02%、30.79%、34.19%；生成 HTML 不计入节省。这是确定性格式证据，不是真实 Agent 结果。
  • 真实 Agent A/B：验证实际 Agent 是否正确触发 skill、生成产物、保留事实、避免误触，并相对自己的 Markdown baseline 减少完整任务输出。只有跨 Agent 门禁通过后，才能宣称普遍的 Agent 节省。

输入上下文也是实际成本。当前格式基准中的 SKILL.md 为 858 个输入 token：在中/长报告语料上，共享上下文到第 9 份报告才摊销到不亏，第 116 份后才达到 30% 有效节省。完整假设和逐场景结果见 reports/agent-token-ab.md。

npm run bench:tokens 复现展开比，node scripts/agent-token-ab.js 复现确定性 Markdown A/B，npm run claude:eval 复现 Claude 行为实测。

成品预览

项目自带两张生产级展览页，全部由 A3L 自己编译而成。点任意截图即可用 htmlpreview.github.io 在浏览器里打开真实交互页面，无需任何安装。

A3 内置能力展览馆 — 上层 / 中层 / 展示层 capsule 的可点击目录，带实时 iframe 预览与压缩统计

A3 内置能力展览馆
50 个 capsule · 点卡片即弹出实时预览 + 原始 A3L 源码对比
在线预览 ↗ · 完整长图 · 原始 HTML 		A3 价值与生产级证据仪表盘 — token 压缩率、三层架构、覆盖矩阵与验证体系

A3 价值与生产级证据
Token 压缩、三层数据、覆盖矩阵、验证体系，所有数据来自可重复脚本
在线预览 ↗ · 完整长图 · 原始 HTML

两张展览页都是单文件 HTML，由 npm run build:showcase 生成；上方的在线预览链接通过 htmlpreview.github.io 路由，任何人都能直接在 GitHub 上点开，无需克隆仓库。

A3L 代表 Agent Abstract Assembly Language：

  • Agent：优先服务 AI Agent，而不是优先服务人类手写。
  • Abstract：表达高于原始 HTML/CSS/JS 的 UI 和开发意图。
  • Assembly：像汇编一样短、紧凑、面向编译器。
  • Language：它是一门有确定编译边界的独立 DSL。

A2UI 给 A3L 的核心启发是架构层面的：把结构、状态、动作声明式拆开。A3L 保留这种分离思想，但用更短的符号语法替代 JSON，因为 JSON 会在 key、引号、逗号、花括号上消耗大量 token。

示例

生产级 A3L 优先从 capsule 开始：一个高层意图 opcode 可以编译出完整 HTML/CSS/JS。

!counter#app"Counter"

运行精确的“源码到生成 HTML”展开基准：

npm run bench:tokens

当前 o200k_base 结果显示所有 production capsule case 都超过 20x 展开目标，详见 reports/token-report.md。这项基准没有把 A3L 与等价 Markdown 答案对比。

A3L 现在采用三层扩展模型：

  • Lower：精确表达一次性的 HTML/CSS/state/event。
  • Middle：26 个自闭环可复用组件，可以嵌入自定义布局。
  • Upper：完整页面或页面流程模板，现在由中层组件加少量 lower glue 组合而成。

更多说明：

  • 架构模型：docs/ARCHITECTURE.md
  • 内置能力全貌：docs/COMPONENT_CATALOG.md
  • 设计系统研究：docs/DESIGN_SYSTEM_RESEARCH.md
  • 三层压缩率数据：reports/layer-report.md

当 AI 需要精确控制结构、样式、状态和事件时，仍然可以使用 lower-layer A3L：

=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}

编译：

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

默认输出一个自包含文件：

  • index.html

a3c 每次编译后都会打印 A3L 源码到生成 HTML 的精确 token 数据。它是展开/复用指标，不是 Markdown A/B 节省。如果明确需要三文件 bundle，可以使用：

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

语言表面

  • !counter#app"Counter"：生产 capsule。
  • =t"Title"：metadata。
  • main#id.class(...)：HTML tree。
  • .class{p:24;br:8}：带别名的 CSS。
  • $n=0：state。
  • #btn@click{n++;#out.txt=n}：event action list。

正式 MVP 语法和别名表见 docs/SPEC.md。 给通用 Agent 使用的短提示面见 docs/AI_AUTHORING_GUIDE.md。

验证

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

npm run ai:smoke 会调用本机 codex exec，给它短需求并要求它独立写 A3L，然后编译、校验输出和压缩率。最新结果保存在 reports/ai-smoke.md。

完整生产门禁：

A3L_CODEX_BIN=/path/to/codex \
  A3L_EVAL_JUDGE=codex-default \
  A3L_EVAL_JUDGE_COMMAND=scripts/codex-judge-provider.js \
  npm run verify:prod

生产门禁在没有真实判分器时会主动失败，不会悄悄退回 mock。源码仓库提供 Codex 与 Claude Code 两种适配器，也可以换成任何遵循文档所述 JSON stdin/stdout 协议的可执行程序。仅运行真实判分 Skill 门禁可使用 npm run skill:eval:prod:codex 或 npm run skill:eval:prod:claude；Claude 版本更适合较慢的手动或定时验证。

依赖

编译器使用成熟的 Node.js runtime 和 node:test。唯一 dev dependency 是 @dqbd/tiktoken，用于使用 o200k_base 做真实 tokenizer 计量。

Agent 展示适配器

标准 skill 入口是 skills/a3l/SKILL.md；编译器 runtime 已包含在同一目录中，因此冷安装后的 skill 不依赖目标工作区存在本仓库的 bin/、src/ 或 node_modules/。

优先使用上方一命令 Skill 安装。agent-adapter/ 下的片段只用于源码仓库或没有 Skill 发现能力的 Agent。所有入口遵循同一决策：较长、结构化、适合类 PPT 汇报的结果使用 A3L；保留精确证据；没有合适 capsule/compiler 或编译失败时，回退为简洁 Markdown。

本地顺滑查看：

npm run serve:present
# 打开 http://127.0.0.1:41731/present/<topic>.html

手动 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 -

研究说明

公开 A2UI 文档描述的是 JSONL/JSON-oriented protocol，包含组件目录以及 UI 结构和状态分离。A3L 继承分离原则，但把 JSON 替换成紧凑源码形式，并通过 target-neutral IR 为未来的 shell、Node、React、Python 等 emitter 留出扩展路径。

参考：