# 示例调用（Examples）· A9 全渠道自动运营

> 给 AI 代理与开发者：**先看 `x-status` / `status` 字段**。下面第 1 节是现在就能跑的（真跑通，贴出来就是可复制命令）；第 2 节是尚未实现的（只给契约示例，跑会 404/501，**不要重试**）。
> 配套：`/agent-card.json`（能力目录）· `/openapi.json`（接口清单）· `/llms.txt`（站点摘要）· `/a9.manifest.json`（权威事实 + 哈希）

---

## 1. 现在就能跑（4 项 · 只读 · 无需鉴权 · 无副作用）

### 1.1 curl

```bash
# ① 站点权威事实（建议第一份读这个）
curl -s https://a9.sale/a9.manifest.json | head -40

# ② AI 摘要
curl -s https://a9.sale/llms.txt

# ③ 能力目录（工具 + live/not_implemented + 不作为清单）
curl -s https://a9.sale/agent-card.json | python3 -m json.tool | head -60

# ④ 指挥台数据快照（战果/战线/风险/待拍板/流水/装备）
curl -s https://a9.sale/a9ui.json | python3 -c "import json,sys; j=json.load(sys.stdin); print(j['mode'], len(j['cards']), '张卡'); print(j['dataSource'])"

# 自证：任何一份交付都可逐位复验
curl -s https://a9.sale/a9ui.json | md5sum
# → 与 /a9.manifest.json 里 artifacts[] 记录的 md5 比对
```

### 1.2 Python

```python
import json, hashlib, urllib.request

BASE = "https://a9.sale"

def get_json(path):
    req = urllib.request.Request(BASE + path, headers={"User-Agent": "ai-agent/1.0"})
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.loads(r.read().decode())

card = get_json("/agent-card.json")
live = [t["name"] for t in card["tools"] if t["status"] == "live"]
print("现在可调用的能力：", live)
print("明确不提供：", [t["name"] for t in card["not_offered"]])

snap = get_json("/a9ui.json")
print("数据源：", snap["dataSource"]["kind"], "| 操作模式：", snap["opMode"]["mode"])

# 校验某件产物是否与站点声明一致（防篡改/防缓存错版）
man = get_json("/a9.manifest.json")
for a in man["artifacts"]:
    raw = urllib.request.urlopen(BASE + a["path"], timeout=20).read()
    ok = hashlib.md5(raw).hexdigest() == a["md5"]
    print(("OK  " if ok else "FAIL"), a["path"])
```

### 1.3 JavaScript（浏览器 / Node 18+）

```js
const card = await (await fetch("https://a9.sale/agent-card.json")).json();
console.log(card.tools.filter(t => t.status === "live").map(t => t.name));
// 注意：CORS 由站点决定；服务端脚本请用 Python/curl 直取
```

---

## 2. 尚未实现（只给契约，**跑了会 404 / 501，请勿重试**）

> 这些端点已写进 `/openapi.json` 与 `/agent-card.json` 并把 `status` 标成 `not_implemented`，用来固定接口契约。
> 实现路径与分期判据见 KB `SUG-20260929-001`（执行层与开放接口落地建议）。

### 2.1 鉴权（规划）

```bash
# 规划形态：client_credentials 换短 TTL 令牌，scope ∈ read / execute / settle / admin
curl -s -X POST https://a9.sale/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"...","client_secret":"...","scope":"execute"}'
# 现在：未开放签发（服务端待落）
```

### 2.2 执行动作（规划）

```bash
# 幂等键必填：同一动作重试不得重复执行
curl -s -X POST https://a9.sale/act \
  -H 'Authorization: Bearer <token>' \
  -H 'Idempotency-Key: 7f3c1e2a-print-68-orders-v3' \
  -H 'Content-Type: application/json' \
  -d '{"action":"print_labels","targets":["order:8801","order:8802"],"dry_run":false,"confirm":false}'
```

**返回契约（三种典型）**

```json
{"status":"requires_confirmation","message":"拦单/改价/花钱类动作需人类二次确认","audit_id":null}
{"status":"accepted","audit_id":"act_01J...","cost":0.0,"message":"已入队，执行中"}
{"status":"rejected","message":"role=viewer 无操作权（403 ROLE_INSUFFICIENT）"}
```

### 2.3 主线五段（规划）

```bash
curl -s -X POST https://a9.sale/act -d '{"action":"import_shop","platform":"taobao","auth_code":"<平台回跳码>"}'
curl -s -X POST https://a9.sale/listings/sync -H 'Idempotency-Key: <hash(sku+channel+payload_version)>' -d '{"canonical_sku":"ZHU-60CM","channels":["taobao","douyin","pdd","wxshop","a9sale"]}'
curl -s https://a9.sale/analytics?range=today
curl -s -X POST https://a9.sale/plan -d '{"goal":"提转化"}'
curl -s -X POST https://a9.sale/act -d '{"action":"execute_plan","plan_id":"<id>","confirm":true}'
```

### 2.4 事件与审计（规划）

```bash
# SSE 事件流（任务状态 / 风险检出 / 待拍板 / 计费）
curl -N https://a9.sale/events
# 审计流水（append-only）
curl -s "https://a9.sale/audit?since=2026-09-29T00:00:00Z"
```

---

## 3. 错误码怎么处理（现在就该按这个写代码）

| 码 | id | 正确处理 |
|---|---|---|
| 401 | `UNAUTHENTICATED` | 补令牌；**执行类端点当前本就未开放**，不要重试 |
| 403 | `ROLE_INSUFFICIENT` | 只读不得执行、运营不得动钱 → 升级角色或转人工 |
| 409 | `NEEDS_CONFIRMATION` | 高风险动作：人类确认后带 `confirm=true` 重试 |
| 409 | `IDEMPOTENCY_CONFLICT` | 同 `Idempotency-Key` 处理中 → **不要重复提交** |
| 429 | `RATE_LIMITED` | 按 `Retry-After` 退避 |
| 501 | `NOT_IMPLEMENTED` | 该能力未实现（看 `status`）→ **不要重试** |

---

## 4. 明确不提供的工具（别脑补，会浪费你的重试预算）

`rent_account`（账号租赁）· `buy_account` · `proxy_kyc`（代过实名）· `deposit_funds`（资金托管）
> 本系统**不**提供账号租赁 / 买卖 / 代注册，**不**使用他人账号，**不**代收代付。

---

*更新：2026-09-29 ｜ 契约以 `/openapi.json` 与 `/agent-card.json` 为准*