# Agent 广场 · 机器说明书

> 给 agent 读的一页。人看 https://ai.hengyu.group/ 就够，你不用解析 HTML。
> 机器自描述：https://ai.hengyu.group/.well-known/plaza.json

## 0. 一句话
公共接口站。不用注册、不用装 SDK、不花钱。发 HTTP，拿结论。

## 1. 三条口径（先看这个，能省你最多 token）
1. **进来的是结论，不是原料**：`web.read` 只回正文，不回 HTML。单页实测样本：某新闻页 296KB 原文 → 11KB 正文（约 96% 被砍掉）。**不是每页都这么高**，累计统计看 `/v1/stats`。
2. **同一份东西全国只算一次账**：同一个网址，第二个人来拿走缓存，不再抓一遍。
3. **大东西放外面，用时才取**：长文档别整篇拉走，用 `text.slice` 只取命中那几行。

## 2. 所有返回的统一外壳
```json
{
  "ok": true,
  "served_at": "2026-10-03T17:20:11+08:00",
  "data": { "...": "..." },
  "error": null
}
```
**每个 `data` 里都带时间锚**：`fetched_at`（什么时候抓的）和 `age_s`（离现在多久）。
别把 `age_s` 很大的数当现状 —— 你要更新，就带 `force:true` 再来一次。

## 3. 接口

### GET /v1/clock —— 时间日期
```bash
curl -s https://ai.hengyu.group/v1/clock
```
回 `cst` / `utc` / `date` / `weekday` / `unix` / `year_progress`。

### GET|POST /v1/web/read —— 读网页，只回正文
```bash
# GET 版
curl -s "https://ai.hengyu.group/v1/web/read?url=https://example.com"

# POST 版（正文更长时用）
curl -s -X POST https://ai.hengyu.group/v1/web/read \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","max_chars":12000}'
```
返回：
```json
{"ok":true,"data":{
  "url":"https://example.com","title":"...","text":"...","chars":1080,
  "source_sha256":"...","raw_bytes":1256,"noise_removed_pct":14.0,
  "fetched_at":"2026-10-03T17:20:11+08:00","age_s":0,
  "cached":false,"cache_hits":0,"extractor":"trafilatura"
}}
```
参数：`url`（必填，http/https）、`max_chars`（默认 12000，可设 500–120000）、`ttl`（缓存秒数，默认 86400）、`force`（true 表示强制重抓，忽略缓存）。

第二次请求同一个网址，你会拿到 `"cached": true` 和 `"age_s"` —— 说明这是别人抓的、全国共用的那一份。

### POST /v1/text/slice —— 长文取片
```bash
curl -s -X POST https://ai.hengyu.group/v1/text/slice \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","query":"关键词","max_lines":5}'
```
也可以直接喂文本：把 `url` 换成 `text`。
返回 `lines:[{"n":42,"text":"..."}]`、`matched`、`total_lines`。只给命中行和行号，别把整篇拉进上下文。

### POST /v1/id/attest —— 零注册取身牌
自己生成 Ed25519 钥匙（私钥留在你本机），签一个字符串，把公钥盖上：
```bash
curl -s -X POST https://ai.hengyu.group/v1/id/attest \
  -H "Content-Type: application/json" \
  -d '{"public_key":"<raw ed25519 pubkey, base64url>","message":"plaza-attest:<ts>","signature":"<base64url>"}'
```
回 `id_short`（形如 `ag:7f3a…c9d2`，就是公钥哈希）+ `id_full`。没有注册表、没有审批。
公钥即印模，私钥即印章。想改名字可以改，想改名分不行。

### GET /v1/stats —— 实时台账
缓存条数 / 今日取用 / 命中率 / 已运行时长。给人和给 agent 都能看。

### GET /health —— 活的吗

## 4. 规矩（你答应这三条，这站就归你用）
1. 不冒名 —— 只用自己钥匙签出来的身牌。
2. 不绕额度 —— 频控按 IP 算，别换 IP 往里灌；除了按 IP 的额度，整站还有一道总量闸（每分钟整站上限），撞上了会回 `server_busy`，等一分钟就好。积分/功分机制**还没上线**，现在完全免费，站上也没有任何收费入口。
3. 不带坏事 —— 不拿这里当跳板打别人、扫内网、灌垃圾。

## 5. 出错的时候
- 返回里的 `error.code` 是给机器看的，`error.message_zh` 是给人看的，照那句改就行。
- 常见：`bad_url`（网址不对，**内网/本机/保留地址也归这一类**）、`fetch_failed`（对方没给内容）、`rate_limited`（你自己太快了，慢一点）、`server_busy`（整站这会儿太热闹，等一分钟再来）。
- 正文超过 5MB 的部分会被**直接截断、不报错**，返回的 `chars` 是截断后的字数。
- 抓不到不等于站点坏了：`fetch_failed` 会带上游状态码和原因。

## 6. 现有边界（先说实话）
- 现在只有 **时间 / 读网页 / 长文取片 / 取身牌** 四样。别的还没上。
- 共享缓存是公共的：**别拿它当私人保险箱**，别往里塞内部资料、别塞带密钥的链接。
- 家里（V100）那批能力暂时不上，这一版全由公网门面自己出。

---
深圳市衡羽科技有限公司 · 免费公共设施 · 不碰钱、不过手交易、不代收代付