openclaw-memory-alibaba-local 0.1.2 → 0.1.3

package/API.md

@@ -0,0 +1,917 @@
+# openclaw-memory-alibaba-local — 接口说明
+
+本文说明**记忆管理面板**与 **Agent 工具**相关接口。管理面板的**数据接口**已改为 **Gateway WebSocket RPC**（与 OpenClaw 网关协议一致）；仅 **HTML 壳**仍通过 HTTP 提供。
+
+- **网关根 URL**：以部署为准，例如 `http://127.0.0.1:12345`，下文记为 `{GATEWAY}`。
+- **WebSocket**：`ws://` 或 `wss://` + 与 HTTP 相同的 `host`（同端口）。
+- **HTML 壳**：`{GATEWAY}/plugins/memory`（前缀匹配）。
+
+**类型约定**
+
+| 文档中的类型 | 含义 |
+|--------------|------|
+| `string` / `number` / `boolean` | JSON 基本类型 |
+| `object` | JSON **对象**（键值对；与语言里的 Map 类似，但是标准 JSON） |
+| `T[]` / `array` | JSON **数组**；若元素为对象，文档在下方单独给出「数组元素结构」表 |
+| `—` | 不适用（如响应头说明） |
+
+---
+
+## 一、Gateway WebSocket RPC（管理面板数据）
+
+### 1.1 连接与鉴权
+
+1. 浏览器建立 `WebSocket` 到 `{WS_GATEWAY}`（与页面同源：`location` 的 host + `ws:`/`wss:`）。
+2. 服务端先推送事件 `connect.challenge`（`payload.nonce`）。
+3. 客户端发送首帧请求（OpenClaw 协议）。**内嵌面板**按页面 hostname 选择 `client`（与网关 `isLocalClient`、是否清空 `scopes` 一致）：
+
+   - **回环**：`localhost` / `127.0.0.1` / `::1` → `id: "openclaw-control-ui"`，`mode: "ui"`。
+   - **非回环**（如局域网 IP、自定义域名）：`id: "openclaw-probe"`，`mode: "probe"`（避免 Control UI 在非本机 HTTP 下直接握手失败）。
+
+```json
+{
+  "type": "req",
+  "id": "<任意唯一字符串>",
+  "method": "connect",
+  "params": {
+    "minProtocol": 3,
+    "maxProtocol": 3,
+    "client": {
+      "id": "openclaw-control-ui",
+      "version": "memory-panel",
+      "platform": "<navigator.platform 或 web>",
+      "mode": "ui"
+    },
+    "role": "operator",
+    "scopes": ["operator.admin"],
+    "auth": { "token": "<与 openclaw.json gateway.auth.token 一致>" }
+  }
+}
+```
+
+4. 成功时收到 `type: "res"` 且 `ok: true`，`payload` 内含 `hello-ok` 等网关握手信息。浏览器连接会校验来源（`gateway.controlUi.allowedOrigins` 等），与官方 Control UI 一致。
+
+   **HTTP + `?token=` 时的 `openclaw.json`（`gateway.controlUi`）**：
+
+   | 访问方式 | 典型配置 |
+   |----------|----------|
+   | 本机 `http://127.0.0.1` / `localhost` + Control UI 客户端 | **`allowInsecureAuth: true`**（否则握手报错 *control ui requires device identity*） |
+   | 局域网 IP / 非回环 hostname + Probe 客户端 | 除 token 外通常需 **`dangerouslyDisableDeviceAuth: true`**，否则握手可成功但网关会**清空 `scopes`**，`memory.admin.*` 报 *missing scope*（面板 403/502） |
+   | 生产/跨机更稳妥 | **HTTPS** + 设备配对，或 SSH 转发到本机后用 `127.0.0.1` + `allowInsecureAuth` |
+
+   示例（本机开发常见）：
+
+```json
+"gateway": {
+  "controlUi": {
+    "allowInsecureAuth": true
+  }
+}
+```
+
+   局域网浏览器直连网关时（面板已用 probe 客户端）示例：
+
+```json
+"gateway": {
+  "controlUi": {
+    "dangerouslyDisableDeviceAuth": true
+  }
+}
+```
+
+5. 后续业务请求均为：
+
+```json
+{ "type": "req", "id": "<唯一>", "method": "<下表 method>", "params": { } }
+```
+
+成功：`{ "type": "res", "id": "…", "ok": true, "payload": <与原先 HTTP JSON 响应体相同> }`  
+失败：`ok: false`，`error.message` 为人类可读原因；部分失败同时带 `payload`（如 `{ "error": "…", "status": 400 }`）。
+
+### 1.2 管理方法一览
+
+| `method` | 说明 | `params`（JSON object） | 成功时 `payload` |
+|----------|------|---------------------------|------------------|
+| `memory.admin.config` | 面板配置 | 无必填字段 | 同原 `GET …/api/config` 响应 |
+| `memory.admin.facets` | 下拉去重值 | 可选 `tab`（保留字段，服务端可忽略） | 同原 `GET …/api/facets` |
+| `memory.admin.dashboard` | 大盘统计 | `timeFrom`, `timeTo`（ISO 8601）、`agentId`；可选 `sessionId` | 同原 `GET …/api/dashboard` |
+| `memory.admin.list` | 分页列表 | `tab`, `agentId`；可选 `sessionId`, `timeFrom`, `timeTo`, `category`, `page`, `limit`, `sortDesc`（布尔，默认 true） | 同原 `GET …/api/list` |
+| `memory.admin.delete` | 批量删除 | `items`: `{ agentId, id }[]` | 同原 `POST …/api/delete` |
+| `memory.admin.add` | 手工插入 | `agentId`, `text`, `category` | 同原 `POST …/api/add` |
+
+### 1.3 废弃的 HTTP JSON
+
+| 路径 | 行为 |
+|------|------|
+| `GET/POST {GATEWAY}/plugins/memory/api/*` | 若配置了 gateway token，仍校验 `?token=` 或 `Authorization: Bearer`；校验通过后返回 **`410 Gone`**，body 提示改用 WebSocket `memory.admin.*`。 |
+
+---
+
+## 二、HTTP（仅 HTML 壳）
+
+### 2.1 `GET /plugins/memory`
+
+| 项目 | 说明 |
+|------|------|
+| **功能** | 返回记忆管理端单页 HTML（壳页面；数据由 `/api/*` 拉取） |
+| **URI** | `{GATEWAY}/plugins/memory` |
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| — | — | — | — | 无查询参数 | — |
+
+**出参**（成功 `200`）
+
+| 字段 / 项 | 类型 | 说明 |
+|-----------|------|------|
+| 响应体 | `string` | HTML 文档 |
+| 响应头 `Content-Type` | — | `text/html; charset=utf-8` |
+
+---
+
+### 2.2 参考：`memory.admin.config`（原 `GET …/api/config`）
+
+| 项目 | 说明 |
+|------|------|
+| **功能** | 返回面板开关、Tab 类别、中文标签、列表筛选项等 |
+| **URI** | `{GATEWAY}/plugins/memory/api/config` |
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| — | — | — | — | 无 | — |
+
+**出参**（成功 `200`，`application/json`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `enableFullContextMemory` | `boolean` | 是否开启全文类记忆 |
+| `enableSelfImprovingMemory` | `boolean` | 是否开启自进化类记忆 |
+| `categoryLabelsZh` | `object` | 键：记忆类型代码 `string` → 值：中文展示名 `string`（动态键，无固定子字段表） |
+| `tabCategories` | `object` | 固定三键，见下表「`tabCategories` 对象结构」 |
+| `memoryTypeFilterOptions` | `object` | 固定三键，见下表「`memoryTypeFilterOptions` 对象结构」 |
+
+**`tabCategories` 对象结构**（键固定）
+
+| 键 | 类型 | 说明 |
+|----|------|------|
+| `user` | `string[]` | 用户 Tab 下的类型代码列表 |
+| `self` | `string[]` | 自进化 Tab；功能关闭时可能为 `[]` |
+| `full` | `string[]` | 全文 Tab；功能关闭时可能为 `[]` |
+
+**`memoryTypeFilterOptions` 对象结构**（键固定）
+
+| 键 | 类型 | 说明 |
+|----|------|------|
+| `user` | `object[]` | 筛选项列表，元素结构见下表 |
+| `self` | `object[]` | 同上 |
+| `full` | `object[]` | 同上 |
+
+**`memoryTypeFilterOptions.*` 数组元素（object）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `category` | `string` | 记忆类型代码 |
+| `labelZh` | `string` | 界面展示用中文 |
+
+---
+
+### 2.3 参考：`memory.admin.facets`（原 `GET …/api/facets`）
+
+| 项目 | 说明 |
+|------|------|
+| **功能** | 返回库中出现过的去重 `agentId`、`sessionId`（供下拉框） |
+| **URI** | `{GATEWAY}/plugins/memory/api/facets` |
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| — | — | — | — | 无 | — |
+
+**出参**（成功 `200`，`application/json`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agents` | `string[]` | 已排序的去重 Agent ID |
+| `sessions` | `string[]` | 已排序的去重会话 ID |
+
+---
+
+### 2.4 参考：`memory.admin.dashboard`（原 `GET …/api/dashboard`）
+
+| 项目 | 说明 |
+|------|------|
+| **功能** | 指定时间范围 + Agent（可选会话）下的记忆大盘统计 |
+| **URI** | `{GATEWAY}/plugins/memory/api/dashboard` |
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| `timeFrom` | query | `string` | **是** | ISO 8601，须可被 `Date.parse` 解析 | 无 |
+| `timeTo` | query | `string` | **是** | 同上 | 无 |
+| `agentId` | query | `string` | **是** | 非空（trim 后） | 无 |
+| `sessionId` | query | `string` | 否 | 非空则仅统计该会话；空表示不限 | 空 |
+
+**出参**（成功 `200`，`application/json`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | `number` | 满足条件的记忆条数 |
+| `timeFromMs` | `number` | 起始时间毫秒时间戳 |
+| `timeToMs` | `number` | 结束时间毫秒时间戳 |
+| `byKind` | `object` | 四大类条数，子结构见下表 |
+| `byCategory` | `object` | 键：类型代码 `string` → 值：条数 `number`（动态键） |
+| `byBucket` | `object[]` | 时间趋势桶，元素结构见下表 |
+| `topAgents` | `object[]` | 条数 Top Agent，**最多 10 条**，元素结构见下表 |
+| `topSessions` | `object[]` | 条数 Top 会话，**最多 10 条**，元素结构见下表 |
+| `importance` | `object` | 重要程度分档，子结构见下表 |
+| `uniqueAgents` | `number` | 去重 Agent 数 |
+| `uniqueSessions` | `number` | 去重会话数 |
+
+**`byKind` 对象结构**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `user` | `number` | 用户记忆类（`user_memory_*`） |
+| `self` | `number` | 自进化类（`self_improving_*`） |
+| `full` | `number` | 全文相关（含 `full_context_memory` 与 `full_context_*`） |
+| `other` | `number` | 其余类型 |
+
+**`byBucket` 数组元素（object）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 桶标识（如月份 `YYYY-MM` 或序号） |
+| `label` | `string` | 展示用标签 |
+| `count` | `number` | 该桶内条数 |
+
+说明：跨度 ≤48 小时按**小时**桶；跨度大于 60 天按**本地自然月**桶；否则按**日**桶。
+
+**`topAgents` 数组元素（object）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | `string` | Agent ID |
+| `count` | `number` | 条数 |
+
+**`topSessions` 数组元素（object）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `sessionId` | `string` | 会话 ID |
+| `count` | `number` | 条数 |
+
+**`importance` 对象结构**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `low` | `number` | 重要度小于 0.34 的条数 |
+| `mid` | `number` | 重要度大于等于 0.34 且小于 0.67 |
+| `high` | `number` | 重要度不小于 0.67 |
+| `avg` | `number` | 有效重要度的平均值；无有效值时为 `0` |
+
+**失败** `400`：缺少/非法时间、缺少 `agentId`、或命中行数超过约 5 万等，body 多为 `{ "error": string }`。
+
+---
+
+### 2.5 参考：`memory.admin.list`（原 `GET …/api/list`；RPC 中 `sortDesc` 为 **boolean**，`page`/`limit` 为 **number**）
+
+| 项目 | 说明 |
+|------|------|
+| **功能** | 分页列出记忆行（Tab 对应类别集合；全文 Tab 按 `batchId` 分组排序） |
+| **URI** | `{GATEWAY}/plugins/memory/api/list` |
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| `agentId` | query | `string` | **是** | 非空 | 无 |
+| `tab` | query | `string` | 否 | `user` \| `self` \| `full`，决定基础类别集合 | `user` |
+| `sessionId` | query | `string` | 否 | 仅该会话 | 空（不限） |
+| `timeFrom` | query | `string` | 否 | ISO 8601，过滤创建时间下限 | 不限 |
+| `timeTo` | query | `string` | 否 | ISO 8601，过滤创建时间上限 | 不限 |
+| `category` | query | `string` | 否 | 须属当前 Tab 类别且出现在该 Tab 的 `memoryTypeFilterOptions` 中 | 不按子类型过滤 |
+| `page` | query | `number` | 否 | 正整数页码 | `1` |
+| `limit` | query | `number` | 否 | 每页 1～500 | `100` |
+| `sortDesc` | query | `string` | 否 | 传 `"false"` 时部分 Tab 改为时间升序；否则降序 | 降序 |
+
+**出参**（成功 `200`，`application/json`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `items` | `object[]` | 当前页记忆行，元素结构见下表 |
+| `total` | `number` | 符合条件的总条数（分页前） |
+| `page` | `number` | 当前页码 |
+| `pageSize` | `number` | 本页条数（对应请求中的 `limit`） |
+
+**`items` 数组元素（object）**
+
+| 字段 | 类型 | 必填（于对象内） | 说明 |
+|------|------|------------------|------|
+| `id` | `string` | 是 | 行 UUID，删除时与 `agentId` 一起提交 |
+| `agentId` | `string` | 是 | Agent ID |
+| `sessionId` | `string` | 是 | 会话 ID，可能为空字符串 `""` |
+| `text` | `string` | 是 | 正文 |
+| `importance` | `number` | 是 | 重要程度 |
+| `category` | `string` | 是 | 类型代码 |
+| `createdAt` | `number` | 是 | 创建时间（毫秒时间戳） |
+| `isDeleted` | `number` | 是 | 列表一般为未删除数据，常见 `0` |
+| `batchId` | `string` | 否 | 全文快照批次 ID，用于成组展示 |
+| `seqInBatch` | `number` | 否 | 批次内顺序 |
+| `chunkIndex` | `number` | 否 | 多向量段时序号 |
+
+**失败** `400`：`agentId` 缺失、`category` 与 Tab 不匹配、匹配过多等。
+
+**特例**（功能关闭的 Tab）：`items` 为 `[]`，`total` 为 `0`，`page` 为 `1`，`pageSize` 为 `100`。
+
+---
+
+### 2.6 参考：`memory.admin.delete`（原 `POST …/api/delete`）
+
+| 项目 | 说明 |
+|------|------|
+| **功能** | 按行 ID 批量硬删除 |
+| **URI** | `{GATEWAY}/plugins/memory/api/delete` |
+| **Content-Type** | `application/json`（请求） |
+| **Body 上限** | 约 64KB |
+
+**入参（Body JSON）**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| `items` | body | `object[]` | **是** | 至少 1 个元素；元素结构见下表 | 无 |
+
+**`items` 数组元素（object）**
+
+| 字段 | 类型 | 必须 | 说明 |
+|------|------|------|------|
+| `agentId` | `string` | **是** | 非空 |
+| `id` | `string` | **是** | 行 UUID |
+
+**出参**（成功 `200`，`application/json`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `deleted` | `number` | 实际删除条数 |
+
+说明：缺 `agentId` 或 `id` 的项会被跳过；若有效项为 0，返回 `400`，`error` 为 `items required`。
+
+---
+
+### 2.7 参考：`memory.admin.add`（原 `POST …/api/add`）
+
+| 项目 | 说明 |
+|------|------|
+| **功能** | 管理端手工写入一条逻辑记忆（可对应多段向量行） |
+| **URI** | `{GATEWAY}/plugins/memory/api/add` |
+| **Content-Type** | `application/json` |
+| **Body 上限** | 约 64KB |
+
+**入参（Body JSON）**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| `agentId` | body | `string` | **是** | 非空（trim） | 无 |
+| `text` | body | `string` | **是** | trim 后非空；超长按约 8000 字符截断 | 无 |
+| `category` | body | `string` | **是** | 见附录 A 与 config 开关；本接口不使用 `full_context_memory` 字面量 | 无 |
+
+写入行的 `sessionId` 固定为 `manual_insert`。
+
+**出参**（成功 `200`，`application/json`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | 首段向量行的 UUID |
+| `createdAt` | `number` | 首行创建时间（毫秒时间戳） |
+| `chunkRows` | `number` | 写入的向量行数（段数） |
+
+**失败**：`400` / `502` / `503` 等，body 多为 `{ "error": string }`（见源码与运行时文案）。
+
+---
+
+### 2.8 HTTP 调用示例（curl；**`/api/*` 已返回 410**，仅作 HTML 与历史对照）
+
+**环境**：`http://127.0.0.1:12345`，已配置 `gateway.auth.token`；下列 curl 中 **`GET/POST …/plugins/memory/api/*` 现已为 `410 Gone`**，请改用 **WebSocket `memory.admin.*`**。库内数据变化后，实测 JSON 会与下文摘录不同。
+
+```bash
+export GATEWAY="http://127.0.0.1:12345"
+export TOKEN="你的 gateway.auth.token"
+```
+
+鉴权：**请求头** `Authorization: Bearer $TOKEN`，或 **Query** `?token=$TOKEN`。
+
+**实测状态码一览**
+
+| 请求 | HTTP |
+|------|------|
+| `GET …/plugins/memory` | `200` |
+| `GET …/api/config`（Bearer） | **`410`**（已废弃） |
+| `GET …/api/config?token=` | **`410`** |
+| `GET …/api/facets` | **`410`** |
+| `GET …/api/dashboard`（带 timeFrom/timeTo/agentId） | **`410`** |
+| `GET …/api/list` | **`410`** |
+| `POST …/api/delete`，body `{"items":[]}` | **`410`** |
+| `POST …/api/add`（示例 body） | **`410`** |
+| `POST …/api/delete`（删掉刚插入的 id） | **`410`** |
+| `GET …/api/config`，错误 Bearer | **`410`** 或 `401`（先鉴权再 410） |
+
+---
+
+**1）`GET /plugins/memory`（无 token）**
+
+```bash
+curl -sS -D - -o /tmp/memory_panel.html "$GATEWAY/plugins/memory" | head -n 12
+```
+
+**响应头（实测前若干行）**
+
+```http
+HTTP/1.1 200 OK
+X-Content-Type-Options: nosniff
+Referrer-Policy: no-referrer
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+Content-Type: text/html; charset=utf-8
+Cache-Control: no-store, no-cache, must-revalidate
+Pragma: no-cache
+```
+
+**响应体**：HTML 单页（实测整页约 65KB）。正文开头如下，余下为内联样式与脚本。
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>RDSClaw 记忆管理</title>
+<style>
+/* 与 OpenClaw Observability 面板一致的浅色卡片 + 红色主色 */
+:root {
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  color: #212121;
+  background: #f5f5f5;
+  --oc-accent: #d32f2f;
+  --oc-accent-hover: #b71c1c;
+  --oc-secondary: #7e57c2;
+  --oc-border: #e0e0e0;
+  --oc-muted: #757575;
+  --oc-card: #ffffff;
+  --oc-page: #f5f5f5;
+}
+* { box-sizing: border-box; }
+input[type="checkbox"] { accent-color: var(--oc-accent); }
+body {
+  margin: 0;
+  padding: 20px 20px 32px;
+```
+
+---
+
+**2）`GET /plugins/memory/api/config`**
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  "$GATEWAY/plugins/memory/api/config"
+```
+
+**响应体 `200`（实测 JSON，已格式化）**
+
+```json
+{
+  "enableFullContextMemory": true,
+  "enableSelfImprovingMemory": true,
+  "categoryLabelsZh": {
+    "user_memory_fact": "用户事实",
+    "user_memory_preference": "用户偏好",
+    "user_memory_decision": "用户决策",
+    "full_context_memory": "全文记忆",
+    "full_context_user": "全文 · 用户消息",
+    "full_context_assistant": "全文 · AI助手消息",
+    "full_context_system": "全文 · 系统消息",
+    "full_context_tool": "全文 · 工具调用",
+    "full_context_tool_result": "全文 · 工具结果",
+    "full_context_others": "全文 · 其他消息",
+    "self_improving_learnings": "最佳实践",
+    "self_improving_errors": "错误经验",
+    "self_improving_feature_requests": "行为诉求"
+  },
+  "tabCategories": {
+    "user": [
+      "user_memory_fact",
+      "user_memory_preference",
+      "user_memory_decision"
+    ],
+    "self": [
+      "self_improving_learnings",
+      "self_improving_errors",
+      "self_improving_feature_requests"
+    ],
+    "full": [
+      "full_context_user",
+      "full_context_assistant",
+      "full_context_system",
+      "full_context_tool",
+      "full_context_tool_result",
+      "full_context_others"
+    ]
+  },
+  "memoryTypeFilterOptions": {
+    "user": [
+      { "category": "user_memory_fact", "labelZh": "用户事实" },
+      { "category": "user_memory_preference", "labelZh": "用户偏好" },
+      { "category": "user_memory_decision", "labelZh": "用户决策" }
+    ],
+    "self": [
+      { "category": "self_improving_learnings", "labelZh": "最佳实践" },
+      { "category": "self_improving_errors", "labelZh": "错误经验" },
+      { "category": "self_improving_feature_requests", "labelZh": "行为诉求" }
+    ],
+    "full": [
+      { "category": "full_context_user", "labelZh": "全文 · 用户消息" },
+      { "category": "full_context_assistant", "labelZh": "全文 · AI助手消息" },
+      { "category": "full_context_system", "labelZh": "全文 · 系统消息" },
+      { "category": "full_context_tool", "labelZh": "全文 · 工具调用" },
+      { "category": "full_context_tool_result", "labelZh": "全文 · 工具结果" },
+      { "category": "full_context_others", "labelZh": "全文 · 其他消息" }
+    ]
+  }
+}
+```
+
+---
+
+**3）Query 传 token（与 Bearer 等价，实测 body 与上条一致）**
+
+```bash
+curl -sS "$GATEWAY/plugins/memory/api/config?token=$TOKEN"
+```
+
+**响应体**：与 **2）** 相同（实测与 Bearer 返回同一 JSON）。
+
+---
+
+**4）`GET /plugins/memory/api/facets`**
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  "$GATEWAY/plugins/memory/api/facets"
+```
+
+**响应体 `200`（实测）**
+
+```json
+{
+  "agents": ["main"],
+  "sessions": [
+    "agent:main:main",
+    "session:67505b88-3019-4c5a-88e2-53fe10abc8da",
+    "session:7e4de4fd-153c-4d14-a558-898486323f32",
+    "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f",
+    "session:97dab399-a12b-409d-a4a7-52ab04c16085",
+    "session:afca0e5d-0de8-48a2-885e-c6494d988849",
+    "session:ca4f769f-ab45-40b9-8e7c-6c16e830dd99",
+    "session:cfdce68f-9a35-4e80-aae4-90501f31538e",
+    "session:e2e-1774361036",
+    "session:e7693a60-62de-4783-ab6b-a532b8995594",
+    "session:mem-empty-1774359591"
+  ]
+}
+```
+
+---
+
+**5）`GET /plugins/memory/api/dashboard`**
+
+```bash
+curl -sS -G -H "Authorization: Bearer $TOKEN" \
+  --data-urlencode "timeFrom=2025-01-01T00:00:00.000Z" \
+  --data-urlencode "timeTo=2026-12-31T23:59:59.999Z" \
+  --data-urlencode "agentId=main" \
+  "$GATEWAY/plugins/memory/api/dashboard"
+```
+
+**响应体 `200`（实测，已格式化）**
+
+```json
+{
+  "total": 1520,
+  "timeFromMs": 1735689600000,
+  "timeToMs": 1798761599999,
+  "byKind": { "user": 20, "self": 30, "full": 1470, "other": 0 },
+  "byCategory": {
+    "full_context_user": 135,
+    "full_context_tool_result": 1095,
+    "full_context_assistant": 240,
+    "user_memory_preference": 5,
+    "user_memory_fact": 15,
+    "self_improving_errors": 2,
+    "self_improving_learnings": 26,
+    "self_improving_feature_requests": 2
+  },
+  "byBucket": [
+    { "key": "2025-01", "label": "2025-01", "count": 0 },
+    { "key": "2025-02", "label": "2025-02", "count": 0 },
+    { "key": "2025-03", "label": "2025-03", "count": 0 },
+    { "key": "2025-04", "label": "2025-04", "count": 0 },
+    { "key": "2025-05", "label": "2025-05", "count": 0 },
+    { "key": "2025-06", "label": "2025-06", "count": 0 },
+    { "key": "2025-07", "label": "2025-07", "count": 0 },
+    { "key": "2025-08", "label": "2025-08", "count": 0 },
+    { "key": "2025-09", "label": "2025-09", "count": 0 },
+    { "key": "2025-10", "label": "2025-10", "count": 0 },
+    { "key": "2025-11", "label": "2025-11", "count": 0 },
+    { "key": "2025-12", "label": "2025-12", "count": 0 },
+    { "key": "2026-01", "label": "2026-01", "count": 0 },
+    { "key": "2026-02", "label": "2026-02", "count": 0 },
+    { "key": "2026-03", "label": "2026-03", "count": 1520 },
+    { "key": "2026-04", "label": "2026-04", "count": 0 },
+    { "key": "2026-05", "label": "2026-05", "count": 0 },
+    { "key": "2026-06", "label": "2026-06", "count": 0 },
+    { "key": "2026-07", "label": "2026-07", "count": 0 },
+    { "key": "2026-08", "label": "2026-08", "count": 0 },
+    { "key": "2026-09", "label": "2026-09", "count": 0 },
+    { "key": "2026-10", "label": "2026-10", "count": 0 },
+    { "key": "2026-11", "label": "2026-11", "count": 0 },
+    { "key": "2026-12", "label": "2026-12", "count": 0 },
+    { "key": "2027-01", "label": "2027-01", "count": 0 }
+  ],
+  "topAgents": [{ "agentId": "main", "count": 1520 }],
+  "topSessions": [
+    { "sessionId": "session:e7693a60-62de-4783-ab6b-a532b8995594", "count": 871 },
+    { "sessionId": "agent:main:main", "count": 305 },
+    { "sessionId": "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f", "count": 113 },
+    { "sessionId": "session:67505b88-3019-4c5a-88e2-53fe10abc8da", "count": 104 },
+    { "sessionId": "session:7e4de4fd-153c-4d14-a558-898486323f32", "count": 29 },
+    { "sessionId": "session:mem-empty-1774359591", "count": 28 },
+    { "sessionId": "session:afca0e5d-0de8-48a2-885e-c6494d988849", "count": 28 },
+    { "sessionId": "session:cfdce68f-9a35-4e80-aae4-90501f31538e", "count": 21 },
+    { "sessionId": "session:97dab399-a12b-409d-a4a7-52ab04c16085", "count": 8 },
+    { "sessionId": "session:ca4f769f-ab45-40b9-8e7c-6c16e830dd99", "count": 7 }
+  ],
+  "importance": {
+    "low": 0,
+    "mid": 17,
+    "high": 1503,
+    "avg": 0.6994736842105452
+  },
+  "uniqueAgents": 1,
+  "uniqueSessions": 11
+}
+```
+
+---
+
+**6）`GET /plugins/memory/api/list`**
+
+```bash
+curl -sS -G -H "Authorization: Bearer $TOKEN" \
+  --data-urlencode "agentId=main" \
+  --data-urlencode "tab=user" \
+  --data-urlencode "page=1" \
+  --data-urlencode "limit=2" \
+  "$GATEWAY/plugins/memory/api/list"
+```
+
+**响应体 `200`（实测）**
+
+```json
+{
+  "items": [
+    {
+      "id": "861dcc43-66be-4a55-8157-bad77fc60e17",
+      "agentId": "main",
+      "sessionId": "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f",
+      "text": "用户偏好使用中文进行交流。",
+      "importance": 0.5,
+      "category": "user_memory_fact",
+      "createdAt": 1774378304727,
+      "isDeleted": 0,
+      "seqInBatch": 0,
+      "chunkIndex": 0
+    },
+    {
+      "id": "1231e4e7-6a81-4216-b4c9-f4755e3825d0",
+      "agentId": "main",
+      "sessionId": "session:8b8fcf30-df6c-4361-85e1-007cf3390f9f",
+      "text": "用户为 RDS 记忆插件增加了 BM25 支持。",
+      "importance": 0.7,
+      "category": "user_memory_fact",
+      "createdAt": 1774378281971,
+      "isDeleted": 0,
+      "seqInBatch": 0,
+      "chunkIndex": 0
+    }
+  ],
+  "total": 20,
+  "page": 1,
+  "pageSize": 2
+}
+```
+
+---
+
+**7）`POST /plugins/memory/api/delete`（空 `items`）**
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[]}' \
+  "$GATEWAY/plugins/memory/api/delete"
+```
+
+**响应体 `400`（实测）**
+
+```json
+{ "error": "items required" }
+```
+
+---
+
+**8）`POST /plugins/memory/api/add` → 再 `delete`（同一条 id）**
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"agentId":"main","text":"API doc embedded real response sample","category":"user_memory_fact"}' \
+  "$GATEWAY/plugins/memory/api/add"
+```
+
+**`add` 响应体 `200`（实测；该行已在后续 delete 中删掉）**
+
+```json
+{
+  "id": "a8ae8460-40ea-4878-baf8-f6fb48e5f79e",
+  "createdAt": 1774412491204,
+  "chunkRows": 1
+}
+```
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"items":[{"agentId":"main","id":"a8ae8460-40ea-4878-baf8-f6fb48e5f79e"}]}' \
+  "$GATEWAY/plugins/memory/api/delete"
+```
+
+**`delete` 响应体 `200`（实测）**
+
+```json
+{ "deleted": 1 }
+```
+
+---
+
+**9）错误 token**
+
+```bash
+curl -sS -H "Authorization: Bearer wrong-token" \
+  "$GATEWAY/plugins/memory/api/config"
+```
+
+**响应体 `401`（实测）**
+
+```json
+{
+  "error": {
+    "message": "Unauthorized",
+    "type": "unauthorized"
+  }
+}
+```
+
+---
+
+## 三、Agent 工具（非 HTTP）
+
+由网关注册为 **tool**；入参为工具调用 JSON，**不是**浏览器地址栏请求。
+
+### 2.1 `memory_recall`
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| `query` | tool 参数 | `string` | **是** | 检索语句 | 无 |
+| `limit` | tool 参数 | `number` | 否 | 正整数；实际上限受插件约束 | 约 `30` |
+
+**出参**（工具返回值，OpenClaw 惯例）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | `object[]` | 常为 `[{ "type": "text", "text": string }]`，给人/模型阅读 |
+| `details` | `object` | 机器可读；子结构见下表（依场景不同） |
+
+**`details` 常见形态**
+
+| 场景 | `details` 类型 | 字段说明 |
+|------|----------------|----------|
+| 未配置插件 | `object` | `error`：`string`，如 `"not_configured"` |
+| 无结果 | `object` | `count`：`number`，`0` |
+| 有结果 | `object` | `count`：`number`；`memories`：`object[]`，元素见下表 |
+
+**`details.memories` 数组元素（object）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | 记忆行 ID |
+| `text` | `string` | 正文 |
+| `category` | `string` | 类型代码 |
+| `importance` | `number` | 重要程度 |
+| `score` | `number` | 相关度分数 |
+| `createdAt` | `number` | 毫秒时间戳 |
+
+---
+
+### 2.2 `memory_store`
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| `text` | tool 参数 | `string` | **是** | 待存储正文 | 无 |
+| `importance` | tool 参数 | `number` | 否 | 建议 0～1 | `0.7` |
+| `category` | tool 参数 | `string` | 否 | 枚举随配置；默认用户事实类 | `user_memory_fact` |
+
+**出参**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | `object[]` | 文本摘要（`type: text`） |
+| `details` | `object` | 成功时见下表；失败时常含 `error`：`string` |
+
+**`details` 成功时（object）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `action` | `string` | `"created"` 或 `"updated"` |
+| `id` | `string` | 记忆行 ID |
+
+---
+
+### 2.3 `memory_forget`
+
+**入参**
+
+| 参数 | 位置 | 类型 | 必须 | 合法值 / 说明 | 默认值 |
+|------|------|------|------|----------------|--------|
+| `memoryId` | tool 参数 | `string` | 否 | 行 UUID；与 `query` 二选一 | 无 |
+| `query` | tool 参数 | `string` | 否 | 检索语句；与 `memoryId` 二选一 | 无 |
+
+**出参**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | `object[]` | 文本说明 |
+| `details` | `object` | 依场景不同，见下表 |
+
+**`details` 常见形态**
+
+| 场景 | 字段 | 类型 | 说明 |
+|------|------|------|------|
+| 未配置 | `error` | `string` | 如 `not_configured` |
+| 缺参 | `error` | `string` | `missing_param` |
+| 按 ID 删除成功 | `action` | `string` | `deleted` |
+| 按 ID 删除成功 | `id` | `string` | 被删 ID |
+| 按 ID 未找到 | `action` | `string` | `not_found` |
+| 按 ID 未找到 | `id` | `string` | 请求的 ID |
+| 按 query 无匹配 | `found` | `number` | `0` |
+| 按 query 自动删除 | `action` | `string` | `deleted` |
+| 按 query 自动删除 | `rows` | `number` | 删除行数 |
+| 按 query 自动删除 | `id` | `string` | 代表行 ID |
+| 按 query 仅候选 | `action` | `string` | `candidates` |
+| 按 query 仅候选 | `candidates` | `object[]` | 元素含 `id`、`text`、`category`、`score` |
+
+**`details.candidates` 数组元素（object）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | 记忆 ID |
+| `text` | `string` | 正文 |
+| `category` | `string` | 类型 |
+| `score` | `number` | 分数 |
+
+---
+
+## 四、附录
+
+### A. `POST /api/add` 与工具可用的类型代码（随配置增减）
+
+| 场景 | 允许的 `category` 示例 |
+|------|-------------------------|
+| 始终 | `user_memory_fact`、`user_memory_preference`、`user_memory_decision` |
+| 全文开启 | `full_context_user`、`full_context_assistant`、`full_context_system`、`full_context_tool`、`full_context_tool_result`、`full_context_others` |
+| 自进化开启 | `self_improving_learnings`、`self_improving_errors`、`self_improving_feature_requests` |
+
+### B. 运维备注
+
+- Service id：`openclaw-memory-alibaba-local`；无额外对外 HTTP。
+- `autoRecall`、`autoCapture` 等为行为开关，无独立 URL。
+
+---
+
+*若与实现不一致，以仓库当前源码为准。*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-alibaba-local",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "OpenClaw memory plugin: local LanceDB + DashScope-compatible embeddings",
   "type": "module",
   "license": "MIT",
@@ -17,21 +17,11 @@
     "vector-search"
   ],
   "files": [
-    "index.ts",
-    "prompt-strip.ts",
-    "bm25-recall.ts",
-    "capture-state.ts",
-    "config.ts",
-    "db.ts",
-    "embed-chunks.ts",
-    "embedding-backend.ts",
-    "categories.ts",
-    "prompts.ts",
-    "web/memory-admin-ops.ts",
-    "web/memory-routes.ts",
-    "web/memory-ui.ts",
+    "*.ts",
+    "web/**/*.ts",
     "openclaw.plugin.json",
-    "README.md"
+    "README.md",
+    "API.md"
   ],
   "dependencies": {
     "@lancedb/lancedb": "^0.27.1",