feat(llm): add GLM-5.2 to Zhipu providers; docs(webchat): integration guide + EN translation

2026-09-13 03:13:41 +08:00 · 2026-06-18 16:21:53 +08:00 · 2026-06-18 16:21:53 +08:00 · 5893d4b33d
commit 5893d4b33d
parent 03a4cbd3e1
5 changed files with 375 additions and 5 deletions
--- a/mateclaw-server/src/main/resources/db/migration/h2/V153__zhipu_glm_5_2.sql
+++ b/mateclaw-server/src/main/resources/db/migration/h2/V153__zhipu_glm_5_2.sql
@ -0,0 +1,21 @@
+-- V153: add the GLM-5.2 flagship to the native Zhipu (BigModel / Z.AI)
+-- providers. GLM-5.2 is served by the same OpenAI-compatible chat completions
+-- schema as the rest of the GLM-5 line, on both the standard /api/paas/v4
+-- endpoints and the /api/coding/paas/v4 subscription endpoints — so it is
+-- added to all four existing Zhipu providers:
+--   * zhipu-cn            (https://open.bigmodel.cn/api/paas/v4)
+--   * zhipu-intl          (https://api.z.ai/api/paas/v4)
+--   * zhipu-cn-codingplan (https://open.bigmodel.cn/api/coding/paas/v4)
+--   * zhipu-intl-codingplan (https://api.z.ai/api/coding/paas/v4)
+--
+-- Coding-plan rows keep temperature 0.2 to favour deterministic code output,
+-- matching the V90 catalog. Aggregator platforms (Volcano Ark, DashScope /
+-- Bailian, ModelScope) do not host GLM-5.2 yet and are intentionally left
+-- untouched — their hosted GLM line still tops out at glm-5 / glm-4.7.
+MERGE INTO mate_model_config (id, name, provider, model_name, description, temperature, max_tokens, top_p, builtin, enabled, is_default, create_time, update_time, deleted)
+KEY (id)
+VALUES
+  (1000000214, 'GLM-5.2',        'zhipu-cn',              'glm-5.2', '最新旗舰模型',                                       0.7, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000224, 'GLM-5.2',        'zhipu-intl',            'glm-5.2', 'Latest flagship model (International)',               0.7, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000238, 'GLM-5.2 Coding', 'zhipu-cn-codingplan',  'glm-5.2', '智谱编码套餐 — GLM-5.2 最新旗舰',                     0.2, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000239, 'GLM-5.2 Coding', 'zhipu-intl-codingplan','glm-5.2', 'Zhipu Coding Plan — GLM-5.2 latest flagship (International)', 0.2, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0);
--- a/mateclaw-server/src/main/resources/db/migration/kingbase/V153__zhipu_glm_5_2.sql
+++ b/mateclaw-server/src/main/resources/db/migration/kingbase/V153__zhipu_glm_5_2.sql
@ -0,0 +1,18 @@
+-- V153: add the GLM-5.2 flagship to the native Zhipu (BigModel / Z.AI)
+-- providers. See the H2 copy for full background. Adds glm-5.2 to all four
+-- existing Zhipu providers (standard + coding plan, China + International).
+-- Aggregator platforms (Volcano Ark, DashScope / Bailian, ModelScope) do not
+-- host GLM-5.2 yet and are intentionally left untouched.
+INSERT INTO mate_model_config (id, name, provider, model_name, description, temperature, max_tokens, top_p, builtin, enabled, is_default, create_time, update_time, deleted)
+VALUES
+  (1000000214, 'GLM-5.2', 'zhipu-cn', 'glm-5.2', '最新旗舰模型', 0.7, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000224, 'GLM-5.2', 'zhipu-intl', 'glm-5.2', 'Latest flagship model (International)', 0.7, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000238, 'GLM-5.2 Coding', 'zhipu-cn-codingplan', 'glm-5.2', '智谱编码套餐 — GLM-5.2 最新旗舰', 0.2, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000239, 'GLM-5.2 Coding', 'zhipu-intl-codingplan', 'glm-5.2', 'Zhipu Coding Plan — GLM-5.2 latest flagship (International)', 0.2, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0)
+ON CONFLICT (id) DO UPDATE SET
+  name = EXCLUDED.name,
+  model_name = EXCLUDED.model_name,
+  description = EXCLUDED.description,
+  builtin = EXCLUDED.builtin,
+  enabled = EXCLUDED.enabled,
+  update_time = EXCLUDED.update_time;
--- a/mateclaw-server/src/main/resources/db/migration/mysql/V153__zhipu_glm_5_2.sql
+++ b/mateclaw-server/src/main/resources/db/migration/mysql/V153__zhipu_glm_5_2.sql
@ -0,0 +1,18 @@
+-- V153: add the GLM-5.2 flagship to the native Zhipu (BigModel / Z.AI)
+-- providers. See the H2 copy for full background. Adds glm-5.2 to all four
+-- existing Zhipu providers (standard + coding plan, China + International).
+-- Aggregator platforms (Volcano Ark, DashScope / Bailian, ModelScope) do not
+-- host GLM-5.2 yet and are intentionally left untouched.
+INSERT INTO mate_model_config (id, name, provider, model_name, description, temperature, max_tokens, top_p, builtin, enabled, is_default, create_time, update_time, deleted)
+VALUES
+  (1000000214, 'GLM-5.2',        'zhipu-cn',              'glm-5.2', '最新旗舰模型',                                       0.7, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000224, 'GLM-5.2',        'zhipu-intl',            'glm-5.2', 'Latest flagship model (International)',               0.7, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000238, 'GLM-5.2 Coding', 'zhipu-cn-codingplan',  'glm-5.2', '智谱编码套餐 — GLM-5.2 最新旗舰',                     0.2, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0),
+  (1000000239, 'GLM-5.2 Coding', 'zhipu-intl-codingplan','glm-5.2', 'Zhipu Coding Plan — GLM-5.2 latest flagship (International)', 0.2, 4096, 0.8, TRUE, TRUE, FALSE, NOW(), NOW(), 0)
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  model_name = VALUES(model_name),
+  description = VALUES(description),
+  builtin = VALUES(builtin),
+  enabled = VALUES(enabled),
+  update_time = VALUES(update_time);
--- a/mateclaw-server/src/main/resources/docs/en/webchat.md
+++ b/mateclaw-server/src/main/resources/docs/en/webchat.md
@ -0,0 +1,250 @@
+# Web / API Access (WebChat) Guide
+
+MateClaw's WebChat channel lets external websites reach the conversation engine over plain HTTP / SSE, with no JWT. Visitor identity is isolated under a shared API Key via `visitorId + visitorToken` (HMAC-signed).
+
+There are two integration paths:
+
+- **Embeddable widget** — drop in one JS file, call `init(...)` once, and a chat bubble appears in the corner. Fastest to ship; ideal for marketing sites / landing-page support.
+- **Custom HTTP / SSE integration** — call the REST + SSE endpoints below and render your own UI. For deeply customized experiences.
+
+## Embeddable widget (mateclaw-webchat)
+
+The widget is a zero-dependency browser library shipped in both UMD (`<script>` tag) and ESM (npm) formats.
+
+**Option 1: script tag (UMD)**
+
+```html
+<script src="https://<your-deployment>/mateclaw-webchat.umd.js"></script>
+<script>
+  MateClawWebChat.init({
+    apiKey: 'your-channel-api-key',   // from the channel edit page
+    server: 'https://<your-deployment>',
+    title: 'Support',
+    placeholder: 'Type a message...'
+  })
+</script>
+```
+
+**Option 2: npm (ESM)**
+
+```bash
+npm install @mateclaw/webchat
+```
+
+```ts
+import { init } from '@mateclaw/webchat'
+
+init({ apiKey: 'your-channel-api-key', server: 'https://<your-deployment>' })
+```
+
+**Config options**
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `apiKey` | yes | — | Channel API Key |
+| `server` | yes | — | MateClaw server URL (no trailing slash) |
+| `position` | no | `bottom-right` | Bubble position: `bottom-right` / `bottom-left` |
+| `primaryColor` | no | `#D97757` | Primary color (any CSS color) |
+| `title` | no | `MateClaw` | Panel title |
+| `placeholder` | no | `Type a message...` | Input placeholder |
+
+**Behavior**
+
+- The visitor ID is generated on first open and persisted in `localStorage` (key `mc-webchat-visitor`), then reused — you don't manage it yourself.
+- The panel is themed entirely through CSS variables (`--mc-primary` / `--mc-bg-elevated` / ...); the host page can override them under `:root`.
+- The widget consumes the `/stream` SSE protocol described below. For richer interactions (session list, attachments, revocation), call the HTTP endpoints directly and build your own UI.
+
+## Custom integration: basics
+
+- **Base URL**: `https://<your-MateClaw-deployment>/api/v1/channels/webchat`
+- **Auth**: every endpoint requires the header `X-MC-Key: <API Key>` (from the channel edit page).
+- **Session-management endpoints** additionally require `X-MC-Visitor-Token: <HMAC>` (issued by the server and returned on the first `/stream` call).
+- **Response envelope**: `R<T>` → `{"code": 200, "msg": "...", "data": T}`; anything other than 200 is an error.
+- **Charset**: UTF-8. The SSE stream uses `text/event-stream; charset=UTF-8`.
+
+## Endpoint list
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| POST | `/stream` | API Key | SSE streaming chat (issues visitorToken) |
+| GET | `/config` | API Key | Get channel config (title/placeholder/...) |
+| POST | `/sessions` | API Key | Explicitly create an empty session thread |
+| GET | `/sessions` | + visitorToken | List sessions (excludes archived by default) |
+| GET | `/sessions/page` | + visitorToken | Paginated + keyword search |
+| PUT | `/sessions/title` | + visitorToken | Rename |
+| PUT | `/sessions/pinned` | + visitorToken | Pin / unpin |
+| PUT | `/sessions/archive` | + visitorToken | Archive / unarchive |
+| DELETE | `/sessions` | + visitorToken | Delete |
+| POST | `/sessions/stop` | + visitorToken | Stop an in-flight stream |
+| POST | `/sessions/regenerate` | + visitorToken | Regenerate the last assistant reply |
+| GET | `/sessions/messages` | + visitorToken | Message list (paginated) |
+| POST | `/upload` | + visitorToken | Upload an attachment (returns fileId) |
+| GET | `/files` | + visitorToken | Download a file (uploaded or agent-generated) |
+
+Admin-level (require a MateClaw JWT, outside the permitAll set above):
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/api/v1/admin/webchat/revoked-visitor` | Revoke a visitor's management token |
+| DELETE | `/api/v1/admin/webchat/revoked-visitor` | Un-revoke |
+
+> In the admin console, the "Conversations" list hides WebChat visitor sessions from regular admins by default — only a global admin sees them. This is a cross-workspace isolation and visitor-privacy guard.
+
+## Auth flow
+
+```text
+┌──────────┐  POST /stream {visitorId:"v1", message:"hi"}
+│  Client  │ ─────────────────────────────────────────────► ┌──────────┐
+└──────────┘                                                  │ MateClaw │
+   ▲                                                          └──────────┘
+   │  SSE meta event: {sessionId, conversationId, visitorToken}
+   │  SSE content_delta events: {text}
+   │  SSE done event
+   └─────────────────────────────────────────────────────────
+                                                              │
+┌──────────┐  GET /sessions X-MC-Visitor-Token: <visitorToken>│
+│  Client  │ ─────────────────────────────────────────────► │
+└──────────┘ ◄──── 200 {code:200, data:[...]}                │
+```
+
+`visitorToken` is valid for 7 days by default; re-issue it through any `/stream` call once it expires. Every `/stream` call (even with a still-valid token) returns a fresh token in the meta event — the client should keep updating its stored copy.
+
+## Error codes
+
+| HTTP | When |
+|---|---|
+| 400 | Invalid parameter (visitorId / sessionId charset, title length, etc.) |
+| 401 | Invalid API Key / missing, expired, or revoked visitorToken |
+| 404 | The given sessionId does not exist or does not belong to the visitor |
+| 409 | More than 5 inactive empty sessions |
+
+The error message is in `R.msg` and can be shown directly to the user.
+
+## SSE event protocol
+
+`/stream` and `/sessions/regenerate` return `text/event-stream`:
+
+```
+event: meta
+data: {"sessionId":"s1","conversationId":"webchat:abc123:v1:s1","visitorToken":"xxx.yyy"}
+
+event: phase
+data: {"phase":"planning","timestamp":1716700000000}
+
+event: tool_start
+data: {"tool":"web_search"}
+
+event: tool_end
+data: {"tool":"web_search","success":true}
+
+event: plan
+data: {"steps":["search the web","summarize"]}
+
+event: content_delta
+data: {"text":"He"}
+
+event: content_delta
+data: {"text":"llo"}
+
+event: thinking_delta
+data: {"text":"..."}    (optional, reasoning trace)
+
+event: done
+data: {"status":"completed"}
+
+event: error
+data: {"message":"..."}  (on failure)
+```
+
+> The SSE spec requires clients to ignore unknown event types. The server may emit internal events prefixed with an underscore (e.g. `_usage_final`); these carry no contract for visitors and can be safely ignored.
+
+### Optional real-time progress events
+
+`phase` / `tool_start` / `tool_end` / `plan` are **optional** events — used to show an "AI is typing…" bubble, tool-execution badges ("Searching…"), or a Plan-and-Execute step checklist in your SDK. The SDK can ignore them all and still render the full reply from `content_delta` alone.
+
+| Event | Triggered when | Data fields |
+|---|---|---|
+| `phase` | the agent enters a new execution phase (planning / generating / summarizing / ...) | `phase`, `timestamp` |
+| `tool_start` | the agent calls a tool | `tool` (tool name) |
+| `tool_end` | a tool call finishes | `tool`, `success` |
+| `plan` | a Plan-and-Execute agent breaks work into steps | `steps` (string array) |
+
+**Note**: `tool_start` / `tool_end` carry **only the tool name**, never the call arguments or results — agent tool calls may involve PII (file paths, user queries, credentials), which would leak if forwarded to a third-party website frontend. The SDK should map tool names to localized labels (`web_search` → "Searching…").
+
+## File upload / download
+
+1. `POST /upload` (multipart): returns `{fileId, fileName, contentType, size}`.
+2. Add the fileId to the `attachmentIds` array in the body of the next `/stream` call. Unknown / expired / foreign fileIds are silently dropped (only the text part is sent, no error).
+3. The agent reads server-side files directly; the `fileUrl` in a message is a relative download path (`/api/v1/channels/webchat/files?storedName=...`) — the client appends auth headers to download.
+4. Agent-generated files (PDF/DOCX/...) appear in assistant replies as `/api/v1/files/generated/<uuid>` URLs, downloadable **without auth**, with a 7-day TTL.
+
+## Session lifecycle: pin / archive / delete
+
+- **Pin** (`PUT /sessions/pinned`): sorted first in the `/sessions` list.
+- **Archive** (`PUT /sessions/archive`): a soft close — the thread stays in the DB (history queryable, addressable by sessionId, files downloadable) but is hidden from `/sessions` by default (pass `includeArchived=true` to return it), and no longer counts against the "≤ 5 inactive empty sessions" quota.
+- **Delete** (`DELETE /sessions`): permanent, unrecoverable.
+
+Each session returned by `/sessions` includes: `sessionId`, `title`, `lastActiveTime`, `messageCount`, `pinned`, `archived`, `streamStatus` (`running` / `idle`).
+
+## visitorToken revocation (admin)
+
+A visitor abusing the channel? An admin calls:
+
+```bash
+curl -X POST https://mate.example.com/api/v1/admin/webchat/revoked-visitor \
+  -H "Authorization: Bearer <admin JWT>" \
+  -H "Content-Type: application/json" \
+  -d '{"channelId":123, "visitorId":"v1", "reason":"abuse"}'
+```
+
+After revocation, all of that visitor's management endpoints return 401 (`/stream` is unaffected and can re-issue a fresh token). Revocation state is briefly cached, so under a multi-instance deployment it takes up to ~10 minutes to fully propagate. Un-revoke via `DELETE` on the same endpoint.
+
+## curl examples
+
+**Step 1: send the first message**
+
+```bash
+curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
+  -H "X-MC-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"visitorId":"v1","message":"hi"}'
+```
+
+Save the `visitorToken` and `sessionId` from the meta event.
+
+**Step 2: list sessions**
+
+```bash
+curl https://mate.example.com/api/v1/channels/webchat/sessions?visitorId=v1 \
+  -H "X-MC-Key: your-api-key" \
+  -H "X-MC-Visitor-Token: <from step 1>"
+```
+
+**Step 3: upload an attachment and send**
+
+```bash
+# upload
+curl -X POST https://mate.example.com/api/v1/channels/webchat/upload \
+  -H "X-MC-Key: your-api-key" \
+  -H "X-MC-Visitor-Token: <token>" \
+  -F "visitorId=v1" \
+  -F "file=@report.pdf"
+# returns {"fileId":"abc-uuid", ...}
+
+# send a message with the attachment
+curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
+  -H "X-MC-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"visitorId":"v1","sessionId":"<sid>","message":"take a look at this report","attachmentIds":["abc-uuid"]}'
+```
+
+## Limits
+
+- Inactive empty sessions per visitor ≤ 5 (creation is rejected past 5 — send a message or delete an old session first)
+- Upload: single file ≤ configured cap, extension + MIME dual whitelist; ≤ 50 files / 200 MB per session (configurable)
+- visitorToken expires in 7 days; agent-generated file URLs have a 7-day TTL
+- Currently a single-instance deployment (staging registry + streamTracker are both in-memory). Multi-instance support is on the roadmap.
+
+## Related
+
+- Upstream epic issue: https://github.com/matevip/mateclaw/issues/355
--- a/mateclaw-server/src/main/resources/docs/zh/webchat.md
+++ b/mateclaw-server/src/main/resources/docs/zh/webchat.md
@ -2,7 +2,59 @@

 MateClaw 的 WebChat 渠道让外部网站通过纯 HTTP / SSE 接入对话能力,无需 JWT。访客身份通过 `visitorId + visitorToken`(HMAC 签发)在共享的 API Key 之下做隔离。

-## 基础
+接入有两条路径:
+
+- **嵌入式小部件** —— 引入一个 JS 文件、调一次 `init(...)`,右下角即出现聊天气泡。最快上线,适合官网 / 落地页客服。
+- **自定义 HTTP / SSE 集成** —— 直接调用下面的 REST + SSE 端点,自己渲染 UI。适合需要深度定制交互的场景。
+
+## 嵌入式小部件(mateclaw-webchat)
+
+小部件是一个零依赖的浏览器库,产物同时提供 UMD(`<script>` 标签)和 ESM(npm)两种格式。
+
+**方式一:script 标签(UMD)**
+
+```html
+<script src="https://<你的部署地址>/mateclaw-webchat.umd.js"></script>
+<script>
+  MateClawWebChat.init({
+    apiKey: 'your-channel-api-key',   // 从渠道编辑页拿
+    server: 'https://<你的部署地址>',  // MateClaw 服务地址
+    title: '在线客服',
+    placeholder: '输入消息...'
+  })
+</script>
+```
+
+**方式二:npm(ESM)**
+
+```bash
+npm install @mateclaw/webchat
+```
+
+```ts
+import { init } from '@mateclaw/webchat'
+
+init({ apiKey: 'your-channel-api-key', server: 'https://<你的部署地址>' })
+```
+
+**配置项**
+
+| 字段 | 必填 | 默认 | 说明 |
+|---|---|---|---|
+| `apiKey` | 是 | — | 渠道 API Key |
+| `server` | 是 | — | MateClaw 服务地址(不带尾斜杠) |
+| `position` | 否 | `bottom-right` | 气泡位置:`bottom-right` / `bottom-left` |
+| `primaryColor` | 否 | `#D97757` | 主色(任意 CSS 颜色) |
+| `title` | 否 | `MateClaw` | 面板标题 |
+| `placeholder` | 否 | `Type a message...` | 输入框占位符 |
+
+**行为说明**
+
+- 访客 ID 首次打开时在 `localStorage`(键 `mc-webchat-visitor`)生成并复用,无需自行管理。
+- 面板样式全部走 CSS 变量(`--mc-primary` / `--mc-bg-elevated` / ...),宿主页可在 `:root` 覆盖做主题定制。
+- 小部件内部消费本指南下半部分描述的 `/stream` SSE 协议;若要更复杂的交互(会话列表、附件、撤销等),直接走下面的 HTTP 端点自建。
+
+## 自定义集成:基础

 - **Base URL**:`https://<你的 MateClaw 部署地址>/api/v1/channels/webchat`
 - **认证**:所有端点都要求请求头 `X-MC-Key: <API Key>`(从渠道编辑页拿)。
@ -36,6 +88,8 @@ MateClaw 的 WebChat 渠道让外部网站通过纯 HTTP / SSE 接入对话能
 | POST | `/api/v1/admin/webchat/revoked-visitor` | 撤销某 visitor 的管理 token |
 | DELETE | `/api/v1/admin/webchat/revoked-visitor` | 取消撤销 |

+> 管理控制台里的「会话」列表默认对普通管理员隐藏 WebChat 访客会话,仅全局管理员可见 —— 这是跨工作区隔离与访客隐私的防护。
+
 ## 认证流程

 ```text
@ -53,7 +107,7 @@ MateClaw 的 WebChat 渠道让外部网站通过纯 HTTP / SSE 接入对话能
 └──────────┘ ◄──── 200 {code:200, data:[...]}                │
 ```

-`visitorToken` 默认 7 天有效;过期后通过任意 `/stream` 调用重新签发。
+`visitorToken` 默认 7 天有效;过期后通过任意 `/stream` 调用重新签发。每次 `/stream`(即便旧 token 仍有效)都会在 meta 事件里回传一个新 token,客户端应持续更新本地存储,保持常新。

 ## 错误码

@ -102,6 +156,8 @@ event: error
 data: {"message":"..."}  (出错时)
 ```

+> SSE 规范要求客户端忽略未知事件类型。服务端可能发出以下划线开头的内部事件(如 `_usage_final`),这些不对访客承诺、可安全忽略。
+
 ### 可选的实时进度事件

 `phase` / `tool_start` / `tool_end` / `plan` 是**可选**事件 —— 用于在
@ -123,10 +179,18 @@ SDK 里展示"AI 正在打字..."气泡、工具执行徽章("正在搜索...")
 ## 文件上传 / 下载

 1. `POST /upload`(multipart):返回 `{fileId, fileName, contentType, size}`。
-2. 在下一次 `/stream` 的请求体里把 fileId 加到 `attachmentIds` 数组。
+2. 在下一次 `/stream` 的请求体里把 fileId 加到 `attachmentIds` 数组。未知 / 过期 / 不属于该访客的 fileId 会被静默丢弃(仅发送文本部分,不报错)。
 3. Agent 下载时直接读服务端文件;消息里的 `fileUrl` 是相对下载路径(`/api/v1/channels/webchat/files?storedName=...`),客户端拼接鉴权头就能下载。
 4. Agent 生成的文件(PDF/DOCX/...)在助手回复里以 `/api/v1/files/generated/<uuid>` URL 形式出现,**无鉴权下载**,7 天 TTL。

+## 会话生命周期:置顶 / 归档 / 删除
+
+- **置顶**(`PUT /sessions/pinned`):在 `/sessions` 列表里排序优先。
+- **归档**(`PUT /sessions/archive`):软关闭 —— 线程留在库里(历史可查、可按 sessionId 寻址、文件可下载),但默认从 `/sessions` 列表隐藏(传 `includeArchived=true` 才返回),且不再占用"未活跃空会话 ≤ 5"的配额。
+- **删除**(`DELETE /sessions`):永久删除,不可恢复。
+
+`/sessions` 返回的每个会话含:`sessionId`、`title`、`lastActiveTime`、`messageCount`、`pinned`、`archived`、`streamStatus`(`running` / `idle`)。
+
 ## visitorToken 撤销(管理员)

 某个 visitor 滥用?管理员调:
@ -138,7 +202,7 @@ curl -X POST https://mate.example.com/api/v1/admin/webchat/revoked-visitor \
  -d '{"channelId":123, "visitorId":"v1", "reason":"abuse"}'
 ```

-撤销后该 visitor 的所有管理端点调用返回 401(`/stream` 不受影响,可重新签发新 token)。
+撤销后该 visitor 的所有管理端点调用返回 401(`/stream` 不受影响,可重新签发新 token)。撤销状态带短时缓存,多实例下最长约 10 分钟生效。取消撤销用 `DELETE` 同一端点。

 ## curl 示例

@ -189,4 +253,3 @@ curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
 ## 关联

 - 上游 epic issue:https://github.com/matevip/mateclaw/issues/355
- 完整 PR 链:#341 / #343 / #346 / #347 / #348 / #349 / #352 / #354 / #356 / #357 / #358 / #359 / #360 / #361