# Brain —— Agent 公共记忆/技能库 API 说明

你是正在访问本站的 Agent 的话，请直接阅读本文档。这是一套扁平结构的记忆库，存有人类的备忘录（memo）、长期记忆（memory）和工作流/技能说明（skill）。

## 认证

三级凭证，通过 `Authorization: Bearer <KEY>` 或 URL 参数 `?key=<KEY>` 传递：

- **只读密钥（read）**：可读取索引与内容
- **读写密钥（write）**：可读 + 新建/修改/删除/上传附件
- **管理员密码（admin）**：管理后台专用

注意：每个入口有防爆破冻结（24h 内错误 100 次冻结，冻结期每 30 分钟仅放行 5 次）。**认证失败请立即停止重试并告知人类**，不要猜测密钥。

## 工作方式（重要）

1. 先调 `GET /api/memories` 获取索引，只有 `name + description + type`，据此判断哪些条目相关
2. 再按需调 `GET /api/memories/:name` 获取完整内容
3. 写入前先想清楚条目名：建议格式 `YYYYMMDD-主题`，如 `20260826-图片生成工作流`

## 条目结构

- 无附件条目 = 单个 Markdown 文件；有附件条目 = 目录（index.md + assets/）
- `type` 三选一：`memo`（备忘）/ `memory`（记忆）/ `skill`（工作流，纯 Markdown 说明）

## API 一览

### 读取（read 及以上）

```
GET /api/memories
→ { "count": 2, "memories": [{ "name": "...", "description": "...", "type": "memo", "updated": "...", "has_assets": false }] }

GET /api/memories/:name        （:name 需 URL 编码，支持中文）
→ { "name": "...", "description": "...", "type": "...", "updated": "...", "content": "<markdown 正文>", "assets": [{"filename": "...", "size": 123}] }

GET /api/memories/:name/assets/:file    → 下载附件二进制
```

### 写入（write 及以上）

```
POST /api/memories
{ "name": "20260826-主题", "description": "一句话描述", "type": "memory", "content": "# 正文" }

PATCH /api/memories/:name     —— 原子修改，三选一或组合 description
{ "mode": "replace", "find": "要替换的原文（必须全文唯一）", "replace": "新文本" }
{ "mode": "append", "text": "追加到正文末尾的文本" }
{ "mode": "meta", "description": "只改描述" }

PUT /api/memories/:name       —— 整条覆盖或重命名
{ "content": "...", "description": "...", "type": "...", "newName": "可选" }

DELETE /api/memories/:name

POST /api/memories/:name/assets    —— 上传图片/Office 文件
{ "filename": "截图.png", "dataBase64": "<base64>" }
→ 返回 { "url": "...", "markdown": "![截图.png](assets/截图.png)" }，正文里用 markdown 字段引用
```

错误统一为 `{ "error": "说明" }`。所有写入自动生成 git commit，可被人类回滚——**删除/覆盖类操作前请先确认必要性**。

### 示例

```bash
# 看索引
curl "https://brain.tokenprime.cn/api/memories?key=READ_KEY"

# 读单条（中文名需 URL 编码）
curl "https://brain.tokenprime.cn/api/memories/20260826-%E4%B8%BB%E9%A2%98?key=READ_KEY"

# 原子追加
curl -X PATCH "https://brain.tokenprime.cn/api/memories/20260826-test" \
  -H "Authorization: Bearer WRITE_KEY" -H "Content-Type: application/json" \
  -d '{"mode":"append","text":"## 新发现\n今天验证了某工作流。"}'
```

## 人类使用

- 管理后台：`/admin`（恒定管理员密码登录，可编辑内容、查看/轮换密钥、解冻入口、回滚版本）
- 密钥每日 0 点自动轮换；遗忘密钥请找人类在管理后台查看