Skip to content

Commit 0890abe

Browse files
committed
docs: publish independent AXI interface specification
1 parent 9fb7d81 commit 0890abe

22 files changed

Lines changed: 4646 additions & 0 deletions

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# 保留第三方发布字节;压缩库通过版本、许可证和 SHA-256 审阅。
2+
content/assets/mermaid.min.js -diff -text

‎.github/workflows/pages.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: AXI documentation
2+
on:
3+
push:
4+
branches: [main]
5+
workflow_dispatch:
6+
permissions:
7+
contents: read
8+
concurrency:
9+
group: axi-pages
10+
cancel-in-progress: false
11+
jobs:
12+
build:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: actions/setup-python@v5
17+
with:
18+
python-version: "3.12"
19+
cache: pip
20+
cache-dependency-path: |
21+
requirements.txt
22+
requirements-test.txt
23+
- uses: actions/configure-pages@v5
24+
id: pages
25+
- run: python -m pip install -r requirements-test.txt
26+
- run: mkdocs build --strict
27+
env:
28+
AXI_SITE_URL: ${{ steps.pages.outputs.base_url }}
29+
- run: python -m playwright install --with-deps chromium
30+
- run: python scripts/verify-site.py
31+
- uses: actions/upload-artifact@v4
32+
with:
33+
name: site-validation
34+
path: .dev/
35+
- uses: actions/upload-pages-artifact@v3
36+
with:
37+
path: site
38+
deploy:
39+
needs: build
40+
runs-on: ubuntu-latest
41+
permissions:
42+
pages: write
43+
id-token: write
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
steps:
48+
- uses: actions/deploy-pages@v4
49+
id: deployment

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/site/
2+
/.venv/
3+
/.dev/
4+
__pycache__/

‎README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# AXI 设计规范
2+
3+
> 面向 AI Agent 的操作界面设计标准,覆盖发现、定位、执行、观察、恢复与交付。
4+
5+
[在线阅读](https://limecloud.github.io/axi/)
6+
7+
## 简介
8+
9+
将 Agent 作为产品的一类正式使用者,为它提供与人类界面共享业务语义、权限和状态的操作界面。本规范使用 AXI 表示 Agent eXperience Interface;这是本规范的约定,不声明为行业统一标准或既有 AXI 项目的官方版本。
10+
11+
文档独立于特定业务、宿主和部署域名。外部资料集中在参考文献,正文完整说明采纳的规则,不以外链代替规范。
12+
13+
## 角色分流
14+
15+
- 产品与交互设计 → [规范首页](content/index.md)、[原则与架构](content/architecture.md)
16+
- 开发工具、插件与网站 → [操作合同](content/contracts.md)、[发现与交付](content/discovery.md)、[浏览器界面](content/browser.md)
17+
- 验收与维护 → [验证标准](content/verification.md)、[参考与取舍](content/references.md)
18+
- 实际接入 → [合同示例与采用清单](content/examples.md)
19+
20+
## 快速上手
21+
22+
### 前置条件
23+
24+
- Python >= 3.11。
25+
- `uv`,或能创建独立虚拟环境的 Python 包管理器。
26+
27+
### 安装与运行
28+
29+
在本目录执行,依赖仅安装到工具管理的隔离环境:
30+
31+
```bash
32+
uv run --no-project --with-requirements requirements.txt mkdocs serve --dev-addr 127.0.0.1:8000
33+
uv run --no-project --with-requirements requirements.txt mkdocs build --strict
34+
```
35+
36+
### 测试
37+
38+
构建后执行浏览器验收。第一次需要安装测试浏览器;已有 Chrome 时可通过 `AXI_BROWSER_PATH` 指定其可执行文件路径。
39+
40+
```bash
41+
uv run --no-project --with-requirements requirements-test.txt playwright install chromium
42+
uv run --no-project --with-requirements requirements-test.txt python scripts/verify-site.py
43+
```
44+
45+
测试覆盖项目子路径、所有页面与站内链接、图表解析与渲染、桌面/手机布局、导航、搜索和无外部运行时请求。证据写入 `.dev/site-validation.json`。
46+
47+
## 配置 / 参数
48+
49+
| 名称 | 用途 | 是否必填 |
50+
| --- | --- | --- |
51+
| `AXI_SITE_URL` | 构建时的站点规范地址;Actions 自动提供 | 否 |
52+
| `AXI_BROWSER_PATH` | 测试时使用的浏览器可执行文件绝对路径 | 否 |
53+
54+
## 部署说明
55+
56+
GitHub Pages 使用 [发布工作流](.github/workflows/pages.yml) 构建并上传 `site/`。推送 `main` 或手动触发工作流后,先完成严格构建和浏览器验收,再部署静态站点。Pages 的发布来源设置为 GitHub Actions。站点使用相对资源地址,图表脚本、字体和样式不依赖外站。
57+
58+
标准版本见 [规范首页](content/index.md)。正文、图表和示例作为一个版本审阅;第三方图表库的许可证、固定版本及摘要见 [资源清单](content/assets/third-party.json)。
59+
60+
## 边界
61+
62+
本规范不定义新的模型、Agent Runtime 或传输协议,不替代业务权限和服务端事务。符合规范需要行为与任务证据;文档完整或支持某个协议不能单独构成符合性声明。

‎content/architecture.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# 原则与架构
2+
3+
## 1. 两类界面,同一业务
4+
5+
人类界面和 Agent 操作界面必须表达同一资源、权限、修订、副作用和结果。Agent 的界面可以由 CLI、工具协议、站点工具与语义控件组合,不要求另画一套屏幕,也不要求每个按钮都有一个独立工具。
6+
7+
```mermaid
8+
flowchart TB
9+
U[使用者的目标与授权] --> H[人类界面:视觉、编辑、比较、接管]
10+
U --> A[Agent 操作界面:发现、定位、执行、核验]
11+
I[能力索引与精确合同] --> A
12+
S[按需方法与示例] --> A
13+
A --> T[结构化工具与可选站点工具]
14+
A --> B[语义浏览器操作]
15+
H --> V[共享应用用例]
16+
T --> V
17+
B --> V
18+
V --> G[身份、权限、输入、修订与费用校验]
19+
G --> D[(业务事实与操作记录)]
20+
D --> O[向两类界面提供实时状态、产物与证据]
21+
```
22+
23+
工具协议是接入方式,业务服务是事实源。浏览器显示的状态是投影,静态索引是路标,Skill 是方法,均不能越过最终授权或覆盖业务终态。
24+
25+
## 2. 七项原则
26+
27+
| 原则 | 必须达到的行为 |
28+
| --- | --- |
29+
| 目标可发现 | 能从业务用途定位能力、所需上下文和入口;未知目标不要求遍历全站 |
30+
| 对象可消歧 | 明确当前账号范围、资源、修订与所属区域;同名对象不自动选第一项 |
31+
| 合同可执行 | 参数有精确结构,副作用和授权边界清楚,错误能指导下一步 |
32+
| 状态可观察 | 明确装载、空、无权、失败、等待、部分完成和完成;不伪造进度 |
33+
| 中断可恢复 | 未知结果沿原操作读取或重放,保留原输入、键和修订 |
34+
| 上下文有边界 | 输入、输出、发现和等待有界;需要更多内容时可精确继续读取 |
35+
| 结果可验证 | 核对实际产物、质量与成本;把失败、部分成功和未验证分开报告 |
36+
37+
速度优化应当减少无效发现、模型决策和重复等待。不能通过跳过授权、隐藏错误、损失必要字段或弱化质量核验来制造速度提升。
38+
39+
## 3. 四层信息架构
40+
41+
```mermaid
42+
flowchart LR
43+
L1[发现层:用途、工具名、所需对象、深链] --> L2[方法层:按目标读取 Skill 分支]
44+
L2 --> L3[合同层:当前版本 Schema、错误与副作用]
45+
L3 --> L4[状态层:实际对象、权限、修订与结果]
46+
L4 --> N[执行当前最小必要动作]
47+
N --> L4
48+
```
49+
50+
有明确上下文和已知合同可以直接进入执行,不必机械经过四次查询。层级用于分工,不是固定回合数。发现层应当小而稳定;状态层必须从当前范围读取,不能把上次会话的“当前项目”隐式当作事实。
51+
52+
## 4. 架构边界
53+
54+
- 优先复用业务用例;不让 Agent 接入层直接写数据库。
55+
- 批量读取与等待放在确定性代码中;跨对象事务必须由业务明确提供。
56+
- 不把任意 Shell、SQL、URL 或脚本执行器作为面向普通业务的通用捷径。
57+
- GUI、工具和本机执行器可以共存;不叠加另一个推理 Agent 来替代可直接表达的操作。
58+
- 客户端缓存必须限定账号、资源和修订;撤权、切换身份和资源变化时清除不适用内容。
59+
60+
## 5. 最小实施顺序
61+
62+
先覆盖真实高频任务:建用途索引、补对象语义、统一状态与恢复,再按证据添加批量和等待。只有定位或往返仍是已证实瓶颈时增加新的工具;工具数量少或多本身不是质量结论。

‎content/assets/MERMAID-LICENSE.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2014 - 2022 Knut Sveidqvist
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎content/assets/diagrams.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/* 图形为本文档的一部分,使用本地资源,不依赖外站脚本。 */
2+
mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: "neutral", flowchart: { htmlLabels: false }, fontFamily: "system-ui, sans-serif" });
3+
const diagrams = [...document.querySelectorAll(".axi-diagram")];
4+
const sources = diagrams.map(node => node.textContent);
5+
// Mermaid 接收纯文本,Markdown 生成的 code 容器不能进入图表解析器。
6+
diagrams.forEach((node, index) => {
7+
node.textContent = sources[index];
8+
node.tabIndex = 0;
9+
node.setAttribute("role", "region");
10+
node.setAttribute("aria-label", "图表,可使用方向键横向滚动");
11+
});
12+
mermaid.run({ nodes: diagrams }).then(() => {
13+
diagrams.forEach(node => {
14+
const svg = node.querySelector("svg");
15+
// 长流程保留文字尺寸,在图表区域滚动,避免整图缩成不可读的小字。
16+
if (svg?.viewBox.baseVal.width) svg.style.minWidth = `${Math.ceil(svg.viewBox.baseVal.width)}px`;
17+
});
18+
}).catch(() => {
19+
diagrams.forEach((node, index) => {
20+
if (node.querySelector("svg:not([aria-roledescription='error'])")) return;
21+
node.textContent = sources[index];
22+
node.setAttribute("aria-label", "图表渲染失败,以下为图表源文本");
23+
});
24+
});

‎content/assets/mermaid.min.js‎

Lines changed: 3636 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎content/assets/site.css‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.md-grid { max-width: 1440px; }
2+
.md-typeset { font-size: .82rem; line-height: 1.8; }
3+
.md-typeset h1, .md-typeset h2, .md-typeset h3 { font-weight: 650; letter-spacing: 0; }
4+
.md-typeset .axi-diagram { overflow-x: auto; padding: 20px 8px; border: 1px solid #e6e8eb; border-radius: 6px; }
5+
.md-typeset .axi-diagram svg { display: block; margin: auto; height: auto; min-width: 540px; }
6+
.md-typeset table:not([class]) { font-size: .74rem; }
7+
@media (max-width: 760px) { .md-typeset .axi-diagram { padding: 12px 0; } }

‎content/assets/third-party.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"name": "mermaid",
3+
"version": "11.17.2",
4+
"source": "https://cdn.jsdelivr.net/npm/mermaid@11.17.2/dist/mermaid.min.js",
5+
"license": "MIT",
6+
"sha256": "581ed7d74bd9048d0e3a91363927d72ef22942d7722546b27f7cc29e35390eb8"
7+
}

0 commit comments

Comments
 (0)