# AnchorProtocol

**Repository Path**: anchorstack/anchor-protocol

## Basic Information

- **Project Name**: AnchorProtocol
- **Description**: AnchorJSON 是 AI 与企业系统之间的确定性执行协议，约定 AI 如何以结构化、可校验、可回滚的方式读写企业数据。
- **Primary Language**: Unknown
- **License**: CC-BY-4.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-14
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AnchorJSON 协议（Anchor Protocol）

> **把 AI 的概率性意图，锚定为企业数据的确定性操作。**

AnchorJSON 是 AI 与企业系统之间的**确定性执行协议**，约定 AI 如何以结构化、可校验、可回滚的方式读写企业数据。协议只约定行为边界，不约定实现细节，任何语言、框架、数据库均可实现。

- **协议名称**：AnchorJSON
- **当前版本**：v0.1
- **定位**：AI ↔ 企业系统之间的执行协议
- **许可**：CC BY 4.0

---

## 为什么需要 AnchorJSON

AI 的输出是概率性的，而企业数据的写入必须是确定性的：要么全成功，要么全回滚。直接让 AI 生成 SQL 或调用内部接口，会带来四类问题：

| 问题 | AnchorJSON 的解法 |
| --- | --- |
| 意图模糊，无法校验 | 用 JSON Schema 约束的信封 + 五组原语表达意图 |
| 越权访问、跨租户读写 | 执行层强制注入 `tenant_id`，不信任上游传入 |
| 写坏数据无法回滚 | 单指令/批量指令均为一个 ACID 事务 |
| 高风险操作无人把关 | 无条件全表更新/删除直接拦截，高风险操作人类在环 |

---

## 设计原则

| 原则 | 说明 |
| --- | --- |
| **协议与实现分离** | 协议约定行为边界，不约定实现细节 |
| **分层可扩展** | Core 只约定语法，Standard 提供通用动作，Extensions 允许自定义子协议 |
| **传输层复用 HTTP** | 能交给 HTTP 的交给 HTTP，不重复造轮子 |
| **确定性优先** | 所有写操作保证 ACID，要么全成功，要么全回滚 |
| **多租户隔离** | 执行层强制注入 `tenant_id`，不信任上游传入 |
| **人类在环** | 高风险操作必须经过人工确认 |
| **语言无关** | 协议不绑定任何编程语言或框架 |

---

## 协议分层

| 层次 | 内容 | 是否必须 |
| --- | --- | --- |
| **Core** | 信封格式 + 五组原语 + 执行语义 | ✅ 必须 |
| **Standard** | query / create / update / delete / batch | ⚠️ 推荐 |
| **Extensions** | 子协议（CRM / ERP / HRM 等） | ❌ 可选 |

> Core 是"语法"，Standard 是"常用句型"，Extensions 是"行业术语"。

---

## 快速开始

一个查询请求（`action: query`）：

```json
{
  "anchor_version": "0.1",
  "action": "query",
  "target": "orders",
  "payload": {
    "where": {"status": "pending"},
    "fields": ["id", "customer_name", "amount"],
    "order_by": ["-created_at"],
    "load_mode": "pagination",
    "page": 1,
    "page_size": 20
  }
}
```

对应的响应：

```json
{
  "anchor_version": "0.1",
  "code": 0,
  "message": "ok",
  "data": { },
  "trace_id": "uuid"
}
```

---

## 请求信封

```json
{
  "anchor_version": "0.1",
  "action": "string",
  "target": "string",
  "payload": { }
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `anchor_version` | string | ✅ | 协议版本，固定为 `"0.1"` |
| `action` | string | ✅ | 动作标识符，可含命名空间（`{domain}.{action}`） |
| `target` | string | ✅ | 目标实体（表名或注册的逻辑处理器名） |
| `payload` | object | ✅ | 动作载荷，由 Core 五组原语 + 子协议扩展组成 |

**元信息通过 HTTP Header 传递，不放入请求体**：认证 `Authorization`、追踪 `X-Trace-Id`、幂等 `X-Idempotency-Key`、干跑 `X-Dry-Run`、超时 `X-Timeout-Ms`、优先级 `X-Priority` 等。

---

## Core 五组原语

五组原语共同回答"如何精准地锚定一次数据操作"。

| 组别 | 回答的问题 | 关键字段 |
| --- | --- | --- |
| **1. 目标定位 Targeting** | 操作哪些数据 | `where`（支持 `and`/`or`/`not` 嵌套与 `eq`/`in`/`contains` 等操作符） |
| **2. 投影 Projection** | 操作哪些字段 | `fields` / `data` / `returning`（支持 `$field`、`$inc`、`$mul`、`$func`） |
| **3. 排序与分页 Ordering** | 按什么顺序、取多少 | `order_by` + `load_mode`（`pagination` / `cursor` / `full_load` / `lazy_load`） |
| **4. 并发控制 Concurrency** | 如何防止冲突 | `version` 乐观锁，冲突返回 409 |
| **5. 跨表联查 Joins** | 如何关联其他实体 | `joins`（`entity` + `type` + `on`，仅支持等值关联） |

---

## Standard 标准动作

| 动作 | 用途 |
| --- | --- |
| `query` | 查询 |
| `create` | 创建 |
| `update` | 更新（必须携带 `version`） |
| `delete` | 删除（默认逻辑删除，`where` 必须含主键） |
| `batch` | 批量（**一个事务**，任一条失败即整体回滚） |

---

## Extensions 子协议

子协议使用 `{domain}.{action}` 命名空间，可扩展 `payload`，但**不得修改 Core 原语的语义**；未注册的 action 返回 422。

| 子协议 | action 示例 |
| --- | --- |
| `AnchorJSON-CRM` | `crm.merge_contacts` |
| `AnchorJSON-ERP` | `erp.approve_po` |
| `AnchorJSON-HRM` | `hrm.transfer_employee` |

---

## 执行语义

| 语义 | 约定 |
| --- | --- |
| **事务边界** | 单个指令是一个事务；批量指令是一个事务 |
| **租户注入** | 执行层从 Token 解析 `tenant_id`，强制覆盖请求体 |
| **风险拦截** | 禁止无条件全表更新/删除，返回 400 |
| **乐观锁** | 版本不匹配返回 409 |
| **幂等性** | 支持 `X-Idempotency-Key`，相同 Key 返回首次结果 |
| **dry_run** | 支持 `X-Dry-Run: true`，只校验不执行 |
| **审计日志** | 必须记录 `trace_id`、`user_id`、`action`、`target`、操作前后快照 |
| **能力发现** | 提供 `GET /api/v1/capabilities`，返回支持的 action 列表 |

---

## 错误码

| 错误码 | 含义 | 触发条件 |
| --- | --- | --- |
| 400 | 请求参数错误 | 必填字段缺失、类型不匹配、无条件更新 |
| 401 | 未认证 | Token 过期或无效 |
| 403 | 无权限 | 权限校验失败 |
| 404 | 资源不存在 | 目标实体或记录不存在 |
| 409 | 冲突 | 乐观锁版本冲突 |
| 422 | 校验失败 | 未注册的 action、JSON Schema 校验不通过 |
| 429 | 请求过于频繁 | 速率限制触发 |
| 500 | 服务器内部错误 | 未预期异常 |
| 503 | 服务不可用 | 外部依赖熔断中 |

---

## 兼容性

任何实现声称"兼容 AnchorJSON v0.x"，必须：

1. 通过官方一致性测试套件
2. 支持 v0.x 定义的所有 Core 原语
3. 对未知字段采取"忽略而非报错"策略
4. 对未注册的 action 返回 422

---

## 仓库结构

```
anchorjson-spec/
├── README.md            # 项目总览（本文件）
├── SPEC.md              # 协议规范
├── versioning.md        # 版本策略
└── LICENSE              # CC BY 4.0 许可
```

> 暂不设立 CHANGELOG.md、architecture.md、faq.md；如后续确有需要再按需补充。

---

## 不在 v0.1 范围内

跨数据库分布式事务、存储过程和触发器、自定义 SQL 片段、跨租户查询、查询时计算公式、字段级权限规则、业务规则与审计策略——这些均由执行层元数据负责定义。

---

## 文档

- [SPEC.md](./SPEC.md) — 协议规范全文
- [versioning.md](./versioning.md) — 版本策略：变更分级、兼容性边界与废弃流程

## 许可

协议文档采用 CC BY 4.0 许可，任何人均可自由实现。