Skip to content

Commit cfbe7ac

Browse files
TommyLemonTommyLemon
committed
checkpoint before checking out main
1 parent 2455fad commit cfbe7ac

37 files changed

Lines changed: 3679 additions & 506 deletions

‎.cursor/skills/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Project skills
2+
3+
Cursor Agent Skills for this repository. Keep them versioned in git alongside the code.
4+
5+
| Skill | Path |
6+
|-------|------|
7+
| A2API demo | [a2api-demo/SKILL.md](./a2api-demo/SKILL.md) |
8+
9+
Add new skills as `.cursor/skills/<name>/SKILL.md`.

‎.cursor/skills/a2api-demo/SKILL.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: a2api-demo
3+
description: Work on the A2API monorepo (protocol, runtime, chat-demo UI/APIJSON). Use when changing envelopes, BoundExecutor, chat-demo charts/tables/detail, account AI settings, or APIJSON Demo integration.
4+
---
5+
6+
# A2API demo skill
7+
8+
## Layout
9+
10+
- `packages/protocol` — A2API 0.1 envelopes / validators
11+
- `packages/runtime` — `ApiJsonClient`, HITL, `BoundExecutor`
12+
- `apps/chat-demo` — Hono API + Vite client (Bootstrap chat + steady-state UI)
13+
- `conversations/` — git-managed chat examples
14+
- `.cursor/skills/` — project skills (this file)
15+
16+
## Local run
17+
18+
```bash
19+
cp .env.example .env
20+
npm install && npm run dev
21+
```
22+
23+
- Client http://localhost:5173 · API http://localhost:3000 · APIJSON Demo http://localhost:8080
24+
25+
## Product rules (locked)
26+
27+
- Steady-state filter/sort/page must not call the LLM (`usedLlm: false`).
28+
- Sensitive writes (default `delete`) go to Admin approval; other writes auto-execute and store `auto_approved` audit rows (`apps/chat-demo/data/approvals.jsonl`).
29+
- Chart field pool = all query tables × fields (not table visible-column config).
30+
- UI copy is English; Chinese NLP matching may remain for intent only.
31+
- Account menu (top-right) holds AI Model / Base URL / API Key; pass as `llm` on `/api/chat` and `/api/analyze`.
32+
33+
## Detail smart fields
34+
35+
- Avatar-like URL fields (`head`, `avatar`, …) → `<img>` + URL input
36+
- `sex` / `gender` → Male(0) / Female(1) select; **Raw** toggle for original values
37+
38+
## Before finishing
39+
40+
- `npm run typecheck` in `apps/chat-demo` when touching TS
41+
- Prefer editing under the project workspace root after `move_agent_to_root`

‎.env.example‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,14 @@ APIJSON_BASE_URL=http://localhost:8080
33

44
# Optional: OpenAI-compatible API for bootstrap refinement
55
# Without a key, deterministic intent rules are used (Demo tables still work).
6+
# You can also set Model / Base URL / API Key from the top-right account menu in the UI.
67
# OPENAI_API_KEY=
78
# OPENAI_BASE_URL=https://api.openai.com/v1
89
# OPENAI_MODEL=gpt-4o-mini
10+
# OPENAI_LANGUAGE=en
11+
12+
# Approval policy: comma-separated APIJSON methods that require Admin approval.
13+
# Other writes (e.g. post/put) auto-execute and store an auto_approved audit row.
14+
# SENSITIVE_METHODS=delete
915

1016
PORT=3000

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ dist/
66
.DS_Store
77
.a2api/
88
coverage/
9+
apps/chat-demo/data/*.jsonl

‎README-Chinese.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# A2API
2+
3+
Agent-to-API 协议与 MVP Demo：生成简单任务 UI，**调通 APIJSON 请求**，之后用户通过界面改筛选 / 排序 / 分页即可再次调用 APIJSON（HTTP），**不再经过 LLM**。
4+
5+
不走 SQL 执行路径。**敏感写操作**（默认 `delete`）进入 Admin 审批队列；**其它写操作**自动执行，并在后台留下 `auto_approved` 审批记录。
6+
7+
英文文档：[README.md](./README.md)
8+
9+
## 环境要求
10+
11+
- Node.js 18+
12+
- 本地 [APIJSONBoot-MultiDataSource](https://github.com/APIJSON/APIJSON-Demo)（或兼容服务）运行在 `http://localhost:8080`
13+
14+
## 快速开始
15+
16+
```bash
17+
cd ~/a2api
18+
cp .env.example .env
19+
npm install
20+
npm test
21+
npm run build
22+
npm run dev
23+
```
24+
25+
- 客户端（Vite）：http://localhost:5173
26+
- API（Hono）：http://localhost:3000
27+
28+
打开客户端地址。右上角 **Login** 可登录/注册，并配置 **AI Model / Base URL / API Key**（参考 APIAuto）。可点快捷芯片（例如 **List the latest 3 moments with authors**），再改排序/分页并点击 **Query / Refresh** —— 右侧会显示 `usedLlm: false` 以及实际发出的 APIJSON 请求体。
29+
30+
对话示例见 [`conversations/`](./conversations/)；项目 Agent skills 见 [`.cursor/skills/`](./.cursor/skills/)。
31+
32+
可选：在 `.env` 中设置 `OPENAI_API_KEY`，用 LLM 辅助 Bootstrap。未配置时，内置意图规则仍可识别 User / Moment / Comment（中英文说法均可）。
33+
34+
## 仓库结构
35+
36+
| 路径 | 作用 |
37+
|------|------|
38+
| `packages/protocol` | A2API 0.1 信封、JSON Pointer、校验器、CRUD 夹具测试 |
39+
| `packages/runtime` | `ApiJsonClient`、`HitlController`、`BoundExecutor` |
40+
| `apps/chat-demo` | 编排器 + 聊天 UI（Bootstrap）+ 绑定筛选（稳态） |
41+
42+
## 协议（MVP）
43+
44+
信封格式：`{ "version": "0.1", "<type>": { ... } }`
45+
46+
- `proposeRequest` — 候选 APIJSON 调用
47+
- `reviseRequest` / `decision` — 修改 / 批准|拒绝
48+
- `bindRequest` — `code == 200` 后，产出模板 + `paramMap` 供 UI 驱动调用
49+
- `requestResult` / `status` — 结果与状态
50+
51+
读操作自动执行。非敏感的 `post` / `put` 自动执行并写审计记录。敏感方法（默认 `delete`，可用 `SENSITIVE_METHODS` 覆盖）需在 **Admin** 页签批准/拒绝。
52+
53+
## 两阶段体验
54+
55+
1. **Bootstrap（聊天 / AI 或规则）** — 生成 UI + 提出 APIJSON → 校验 → 执行至成功 → 发出 `bindRequest`
56+
2. **稳态（无 LLM）** — 筛选/排序/分页 → `BoundExecutor` 将 `paramMap` 合并进 `bodyTemplate` → `POST {baseUrl}/{method}`
57+
58+
## UI | Data 页签
59+
60+
顶部页签：
61+
62+
- **UI** — 聊天 Bootstrap + 绑定表格 / 详情 / 图表
63+
- **Data** — 类 APIAuto HTTP 调试
64+
- **Admin** — 敏感操作审批队列 + 审计（含自动通过记录）
65+
66+
另外：
67+
68+
- **Embed APIAuto** — iframe 打开 `http://localhost:8080/api/index.html?send=true&type=JSON&url=...&json=...`（分享链接自动填充并发送）
69+
- **Open APIAuto in new window** — 同一分享链接在新标签打开
70+
71+
Agent / 控制台自动化：
72+
73+
```js
74+
a2apiAgent.switchTab("data")
75+
a2apiAgent.debug({
76+
url: "http://localhost:8080/get",
77+
json: { User: { id: 38710 } },
78+
send: true, // 内置发送
79+
// useApiAuto: true, // 或加载 iframe 并自动发送
80+
})
81+
```
82+
83+
## 配置 APIJSON
84+
85+
```bash
86+
export APIJSON_BASE_URL=http://localhost:8080
87+
# 或编辑 .env
88+
```
89+
90+
请确保 Demo 库表（User / Moment / Comment）在该服务上可用。
91+
92+
**写操作（POST/PUT/DELETE）：** Demo 常要求已登录会话（`@role` OWNER/LOGIN）。MVP 仍会生成请求并展示 HITL 批准/拒绝界面；若 APIJSON 返回未登录，请通过 Demo/APIAuto 会话 Cookie 登录，或在本地放宽 Access。**读操作**可直接使用公开 Demo 数据。
93+
94+
## 脚本
95+
96+
```bash
97+
npm test # protocol + runtime 单元测试
98+
npm run build # 编译 packages + demo
99+
npm run dev # API :3000 + Vite :5173
100+
npm run typecheck
101+
```
102+
103+
## 二期（不在本 MVP）
104+
105+
版本化快照（复用 / 自动调整 / 手动调整）、本地优先存储、跨设备同步（APIJSON 表或文件导入导出）——见设计方案。

‎README.md‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# A2API
22

3-
Agent-to-API protocol and MVP demo: generate a simple task UI, **tune an APIJSON request until it works**, then let users change filters/sort/paging by operating the UI — which calls APIJSON over HTTP **without going through the LLM again**.
3+
Agent-to-API protocol and MVP demo: generate a simple task UI, **tune an APIJSON request until it works**, then let users change filters, sort, and paging from the UI — which calls APIJSON over HTTP **without going through the LLM again**.
44

5-
No SQL execution path. Writes go through human approval (HITL).
5+
No SQL execution path. **Sensitive writes** (default: `delete`) wait in the Admin approval queue; **other writes** auto-execute and leave an `auto_approved` audit record on the server.
6+
7+
Chinese documentation: [README-Chinese.md](./README-Chinese.md)
68

79
## Requirements
810

@@ -23,9 +25,11 @@ npm run dev
2325
- Client (Vite): http://localhost:5173
2426
- API (Hono): http://localhost:3000
2527

26-
Open the client URL. Try chips such as「查最近 3 条动态及作者」, then change sort/page and click **查询 / 刷新** — the right panel shows `usedLlm: false` and the exact APIJSON body.
28+
Open the client URL. Use **Login** (top-right) to open the account menu and set **AI Model / Base URL / API Key** (APIAuto-style). Try chips such as **List the latest 3 moments with authors**, then change sort/page and click **Query / Refresh** — the right panel shows `usedLlm: false` and the exact APIJSON body.
29+
30+
Curated chat examples live in [`conversations/`](./conversations/); project Agent skills in [`.cursor/skills/`](./.cursor/skills/).
2731

28-
Optional: set `OPENAI_API_KEY` in `.env` to refine bootstrap with an LLM. Without it, built-in intent rules for User / Moment / Comment still work.
32+
Optional: set `OPENAI_API_KEY` in `.env` to refine bootstrap with an LLM. Without it, built-in intent rules for User / Moment / Comment still work (English and Chinese phrases).
2933

3034
## Monorepo layout
3135

@@ -44,7 +48,7 @@ Envelopes: `{ "version": "0.1", "<type>": { ... } }`
4448
- `bindRequest` — after `code == 200`, template + `paramMap` for UI-driven calls
4549
- `requestResult` / `status` — outcomes
4650

47-
Read methods auto-execute. `post` / `put` / `delete` require Approve (editable JSON).
51+
Read methods auto-execute. Non-sensitive `post` / `put` auto-execute with an audit row. Sensitive methods (default `delete`, override `SENSITIVE_METHODS`) wait for **Admin** Approve/Reject.
4852

4953
## Two-phase UX
5054

@@ -55,13 +59,14 @@ Read methods auto-execute. `post` / `put` / `delete` require Approve (editable J
5559

5660
Top tabs:
5761

58-
- **UI** — chat bootstrap + bound table/detail
59-
- **Data** — APIAuto-style split: left Method / URL / JSON / Header + Send; right Response JSON
62+
- **UI** — chat bootstrap + bound table/detail/charts
63+
- **Data** — APIAuto-style HTTP debugger
64+
- **Admin** — sensitive approval queue + audit trail (`auto_approved` / approved / rejected)
6065

6166
Also:
6267

63-
- **嵌入 APIAuto** — iframe `http://localhost:8080/api/index.html?send=true&type=JSON&url=...&json=...` (share-link auto fill + send)
64-
- **新窗口打开 APIAuto** — same share URL in a new tab
68+
- **Embed APIAuto** — iframe `http://localhost:8080/api/index.html?send=true&type=JSON&url=...&json=...` (share-link auto fill + send)
69+
- **Open APIAuto in new window** — same share URL in a new tab
6570

6671
Agent / console automation:
6772

@@ -75,7 +80,6 @@ a2apiAgent.debug({
7580
})
7681
```
7782

78-
7983
## Configure APIJSON
8084

8185
```bash
@@ -85,7 +89,7 @@ export APIJSON_BASE_URL=http://localhost:8080
8589

8690
Ensure the Demo schema (User / Moment / Comment) is available on that server.
8791

88-
**Writes (POST/PUT/DELETE):** the Demo often requires a logged-in session (`@role` OWNER/LOGIN). The MVP still generates the request and shows the HITL Approve/Reject UI; if APIJSON returns「未登录」, log in via your Demo/APIAuto session cookies or relax Access for local testing. **Reads** work out of the box against the public Demo data.
92+
**Writes (POST/PUT/DELETE):** the Demo often requires a logged-in session (`@role` OWNER/LOGIN). The MVP still generates the request and shows the HITL Approve/Reject UI; if APIJSON returns "not logged in", log in via your Demo/APIAuto session cookies or relax Access for local testing. **Reads** work out of the box against the public Demo data.
8993

9094
## Scripts
9195

0 commit comments

Comments
 (0)