@rei-standard/amsg-server 2.6.0-next.27 → 2.6.0-next.29

package/README.md

@@ -275,7 +275,7 @@ LLM API 凭据（`apiUrl` / `apiKey` / `primaryModel`）有两种给法：
 |---|---|
 | `PUT /llm-credentials` | 批量登记 / 覆盖。body =（加密后的）`{ credentials: [{ credId, value: { apiUrl, apiKey, primaryModel } }] }`，一批 ≤100 条，单用户 ≤500 行 |
 | `GET /llm-credentials` | 对账清单 `{ credentials: [{ credId, updatedAt }] }`。**凭据本体永远不回传** |
-| `DELETE /llm-credentials` | 删除。body =（加密后的）`{ credIds: [...] }` 或 `{ all: true }` |
+| `DELETE /llm-credentials` | 删除。body =（加密后的）`{ credIds: [...] }` / `{ all: true }` / `{ credIdPrefix: 'char:<charId>/' }`，**三选一**，混着传返回 400 |
 
 客户端侧对应 `client.putLlmCredentials(credentials)` / `listLlmCredentials()` / `deleteLlmCredentials(opts)`。
 
@@ -582,6 +582,28 @@ clientStateTtl: {
 
 `GET /capabilities` 的 features 里有 `client-state-ttl`。
 
+## 清理云端数据：先对账，再按角色删
+
+整表全清（`DELETE /client-state` 不带参数、`DELETE /llm-credentials { all: true }`）之外，还有一组按名字来的口子，给「这个角色本地已经删了，云端那份也该走」这类收尾用。
+
+| 端点 | 语义 |
+|---|---|
+| `GET /client-state/namespaces[?limit=<n>]` | 云端有哪些命名空间：`{ namespaces: [{ namespace, entryCount, byteSize, updatedAt }], truncated, limit }`（加密信封）。默认最多 200 条，被截断时 `truncated: true` |
+| `DELETE /client-state?namespace=<ns>` | 只清这一个命名空间，连它的大值切片行一起。返回 `{ deleted, namespace }`；不带 `namespace` 参数仍是整表全清 |
+| `DELETE /llm-credentials { credIdPrefix }` | 按 `cred_id` 前缀删。一个角色名下通常有 `char:<charId>/chat`、`/instant`、`/emotion` 几行，前缀一把清掉 |
+| `DELETE /outbox` | 主动删收件箱的行：body =（加密后的）`{ messageIds: [...] }`（一次 ≤200 条）或 `{ all: true }`。在此之前只能等 cron 的 TTL 老化 |
+
+用法就是三步：拉一份 `GET /client-state/namespaces`，跟本地清单对一遍，本地已经没有的逐个 `DELETE /client-state?namespace=`。
+
+几件容易踩的事：
+
+- **命名空间清单里没有保留命名空间。** 单条 value 超过 200KB 时库会把它切片存进一个内部命名空间，那是存储实现细节。统计把它折算进原命名空间：`byteSize` 和 `updatedAt` 算进去，`entryCount` 不算（切片是一个逻辑条目的几段）。按命名空间删也是连切片行一起删，不会留下读不出来的孤儿。
+- **`byteSize` 是存储字节，不是原文字节。** 值落库前都加密过，这个数比明文大一截——它回答的是「这个命名空间在云端占多大地方」。
+- **清单有上限。** `truncated: true` 时手上这份不是全集，别拿它反推「本地有、云端没有 = 可以删」。
+- **`DELETE /outbox` 和 ack 是两回事。** ack 之后行还在（等 TTL 老化），只是不再被 `GET /outbox` 返回；删是把行拿掉，补收不回来——只在确认对完账之后用。
+- **`credIdPrefix` 按字典序前缀匹配，不是通配符。** 前缀里的 `%` `_` `\` 都只是普通字符。
+- 三条新端点各有自己的 feature 名：`client-state-namespaces`、`client-state-delete-namespace`、`llm-credentials-delete-prefix`、`outbox-delete`。老 worker 上探不到就走降级路径（例如退回整表全清，或者先提示用户更新后端）。内置适配器里只有 D1 实现，pg / neon 上这几条返回 501。
+
 ## 循环任务的时区（`tzId`）
 
 `daily` / `weekly` 任务可以带一个 IANA 时区 id：

package/dist/adapters/d1.d.ts

@@ -275,6 +275,61 @@ export class D1Adapter {
      * @returns {Promise<number>} rows deleted
      */
     clearClientState(userId: string): Promise<number>;
+    /**
+     * 这个用户名下有哪些命名空间，各自几条、占多少字节、最后更新是什么时候
+     * （宿主对账「云端到底存了什么」用）。
+     *
+     * `foldPrefix` 传进来的是大值分块那个保留命名空间的前缀（见
+     * lib/state-chunks.js）：以它开头的行不单独成一个命名空间，而是折算进
+     * 去掉前缀之后的那个原命名空间——保留命名空间是库的存储实现细节，宿主眼里
+     * 那些切片行就是原命名空间占掉的地方。折算口径：
+     *   - `byte_size` / `updated_at` 算进去（存储确实占着、写入确实发生过）；
+     *   - `entry_count` 不算（切片是一个逻辑条目的几段，不是几个条目）。
+     * 不传 `foldPrefix` = 不折算，保留命名空间按普通命名空间原样列出来。
+     *
+     * 前缀由调用方传、不由适配器自己知道：分块是 lib 层的约定，适配器只照着折。
+     *
+     * 折算写在 SQL 里而不是取回来在 JS 里合，是因为有 `limit`：保留命名空间以
+     * \u001f 开头，BINARY 排序下排在所有正常命名空间前面，先取 limit 条再折算
+     * 的话额度会被切片命名空间吃光，正常命名空间一条都露不出来。
+     *
+     * `LENGTH(CAST(value AS BLOB))` 数的是字节不是字符——TEXT 上的 `LENGTH()`
+     * 按字符算，密文虽然是 ASCII 十六进制、两者相同，但换个存法就悄悄差一截。
+     *
+     * 这条语句要把该用户的 client_state 全扫一遍（GROUP BY 本来就得看每一行），
+     * 所以没为它单独加索引：它是宿主按需点开的对账口，不在 cron 路径上。别把它
+     * 塞进每分钟跑的东西里（理由见 adapters/schema.sqlite.js 的 CLIENT_STATE_INDEXES）。
+     *
+     * @param {string} userId
+     * @param {{ limit?: number, foldPrefix?: string|null }} [opts]
+     * @returns {Promise<Array<{ namespace: string, entry_count: number, byte_size: number, updated_at: number }>>}
+     *   按 namespace 升序，最多 `limit` 条。
+     */
+    listClientStateNamespaces(userId: string, { limit, foldPrefix }?: {
+        limit?: number;
+        foldPrefix?: string | null;
+    }): Promise<Array<{
+        namespace: string;
+        entry_count: number;
+        byte_size: number;
+        updated_at: number;
+    }>>;
+    /**
+     * 把这几个命名空间下这个用户的行一次删光（一次 batch = 一次事务）。
+     *
+     * 调用方传的是「原命名空间 + 它的切片保留命名空间」两个（见
+     * lib/state-chunks.js 的 chunkNamespaceFor）：只删前者的话，大值那几行切片
+     * 留在库里成孤儿——读不出来、也不会被别的路径清掉。哪些命名空间算一组由调
+     * 用方决定，适配器只负责它们在同一个事务里删完。
+     *
+     * 条件是 `user_id = ? AND namespace = ?`，吃的是主键
+     * (user_id, namespace, key) 的前两列，不扫表。
+     *
+     * @param {string} userId
+     * @param {string[]} namespaces
+     * @returns {Promise<number>} 删掉的行数合计（含切片行）
+     */
+    deleteClientStateNamespaces(userId: string, namespaces: string[]): Promise<number>;
     /**
      * 这个用户当前登记的推送订阅（密文原样返回，解密在上层）。
      *
@@ -347,6 +402,32 @@ export class D1Adapter {
      * @returns {Promise<number>} 删掉的行数
      */
     deleteLlmCredentials(userId: string, credIds?: string[] | null): Promise<number>;
+    /**
+     * 按 cred_id 前缀删这个用户的凭据（宿主按角色清理：`char:<charId>/` 一把清
+     * 掉该角色名下的 chat / instant / emotion 几行）。
+     *
+     * **不用 LIKE。** 两条 D1 的限制在这儿各埋一个雷：
+     *   - LIKE / GLOB 的 pattern 在 D1 上最长 50 字节（SQLite 默认 50000，官方文
+     *     档没写这一条）。`char:<uuid>/` 就是 42 字节，前缀里再多点东西、或者
+     *     cred_id 用上契约允许的 128 字符，pattern 当场超限，整条语句报
+     *     `LIKE or GLOB pattern too complex`——本地 better-sqlite3 上永远复现不
+     *     了，只有真实 D1 才炸。
+     *   - 退一步「先 SELECT 出匹配的 cred_id 再按 id 批量删」也不是好路：单条语
+     *     句最多 100 个绑定参数，得自己切批，还平白多一个来回和一个「查完到删完
+     *     之间又写进来一行」的窗口。
+     * 走字典序范围（`cred_id >= 前缀 AND cred_id < 上界`）两条都绕开了：没有长度
+     * 上限，前缀里的 `%` `_` `\` 只是普通字符，一条语句三个绑定参数，而且直接吃
+     * (user_id, cred_id) 主键索引。上界算法见本文件顶部的 prefixRangeEnd。
+     *
+     * 前缀没有字典序上界时（prefixRangeEnd 返回空串，实际用不到——见那个函数的
+     * 说明）范围条件一行都匹配不上，删 0 行。宁可少删，也不能把别人的行带走。
+     *
+     * @param {string} userId
+     * @param {string} credIdPrefix - 非空前缀，空串由上层拒掉（空前缀 = 删全部，
+     *   那是 `deleteLlmCredentials(userId, null)` 的活儿，不能从这个口误伤进来）
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteLlmCredentialsByPrefix(userId: string, credIdPrefix: string): Promise<number>;
     /**
      * 发送前把这一批 push 落进 outbox（一次 batch）。(user_id, message_id)
      * 唯一：重试同一 occurrence 带着同一批 messageId 再来时更新 payload、不加
@@ -431,6 +512,23 @@ export class D1Adapter {
      * @returns {Promise<number>} 本次真正被 ack 的行数
      */
     ackOutboxMessages(userId: string, messageIds: string[], ackedAt: number): Promise<number>;
+    /**
+     * 主动删 outbox 的行：数组删指定那几条，传 null 删这个用户的全部。
+     *
+     * 跟 `discardOutboxMessages` 是两件事：那个只撤「还没发出去的」，是取消 / 顶
+     * 替时的收尾；这个不看 delivered_at / acked_at，是宿主的清理口（对完账之后
+     * 把某几条、或者整个收件箱清掉）。在此之前 message_outbox 只能等 cron 的
+     * TTL（已签收 7 天 / 任何行 28 天）自己老化。
+     *
+     * 数组形态走 `_runInClauseWrite`：D1 单条语句最多 100 个绑定参数，`user_id`
+     * 占掉 1 个，所以一批最多 99 个 id，多了自动切批、整组仍在一个事务里（切开
+     * 之后「只删掉前 99 个」那种中间态比原问题更难查）。
+     *
+     * @param {string} userId
+     * @param {string[]|null} messageIds - null = 这个用户的全部
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteOutboxMessages(userId: string, messageIds?: string[] | null): Promise<number>;
     /**
      * outbox 的例行清理（run-tick 每跳顺手调）：已 ack 的行留短一些，未 ack 的
      * 也不无限留（Web Push TTL 上限四周，比它更老的推送谁也收不到了）。

package/dist/adapters/interface.d.ts

@@ -180,6 +180,32 @@ export type DbAdapter = {
      * (optional; single-user/D1 only) Delete every entry of this user; returns rows deleted.
      */
     clearClientState?: (userId: string) => Promise<number>;
+    /**
+     * （可选；单用户/D1）这个用户名下有哪些命名空间，各自几条 / 占多少字节 / 最后
+     * 更新是什么时候。按 namespace 升序，最多 `limit` 条（调用方自己判断有没有被截断：
+     * 多要一条，回来的比 limit 多就说明还有）。
+     * `foldPrefix` 是大值分块那个保留命名空间的前缀（见 lib/state-chunks.js）：以它
+     * 开头的行不单独列，字节数与最后更新时刻折算进去掉前缀后的原命名空间，条目数不
+     * 折算（切片是一个逻辑条目的几段）。折算必须在取 `limit` 之前做——保留命名空间以
+     * \u001f 开头，排在所有正常命名空间前面，先截断再折算会把额度全吃掉。
+     * 不实现 → `GET /client-state/namespaces` 返回 501。
+     */
+    listClientStateNamespaces?: (userId: string, opts?: {
+        limit?: number;
+        foldPrefix?: string | null;
+    }) => Promise<Array<{
+        namespace: string;
+        entry_count: number;
+        byte_size: number;
+        updated_at: number;
+    }>>;
+    /**
+     * （可选；单用户/D1）把这几个命名空间下这个用户的行一次删光，要在同一个事务里。
+     * 调用方传的是「原命名空间 + 它的切片保留命名空间」两个：只删前者会把大值的切片
+     * 行留成孤儿。返回删掉的行数合计。不实现 → `DELETE /client-state?namespace=` 返回
+     * 501（不带 namespace 的整表全清仍走 clearClientState，不受影响）。
+     */
+    deleteClientStateNamespaces?: (userId: string, namespaces: string[]) => Promise<number>;
     /**
      * （可选；单用户/D1）按命名空间清掉 `updated_at` 早于 `updatedBefore`（epoch 毫秒）
      * 的行，不限用户。宿主配了 `clientStateTtl` 时 runScheduledTick 每跳顺手调；
@@ -238,12 +264,22 @@ export type DbAdapter = {
     }>>;
     /**
      * 删凭据：数组删指定那几行，null 删全部。返回删掉的行数。
+     */
+    deleteLlmCredentials?: (userId: string, credIds: string[] | null) => Promise<number>;
+    /**
+     * （可选）按 cred_id 前缀删（宿主按角色清理：`char:<charId>/` 一把清掉该角色
+     * 名下的几行）。返回删掉的行数。这一个单独可选，不在下面那组「四个要么都实现」
+     * 里——不实现时 `DELETE /llm-credentials` 的 `credIdPrefix` 入参返回 501，另外
+     * 两种入参（`credIds` / `all`）照常。
+     * 实现时别用 LIKE：D1 把 LIKE / GLOB 的 pattern 压到 50 字节，`char:<uuid>/`
+     * 就已经 42 字节了，稍长一点整条语句报 `pattern too complex`。走字典序范围
+     * （`cred_id >= 前缀 AND cred_id < 上界`）没有长度上限，见 adapters/d1.js。
      *
      * llm_credentials 四个方法要么都实现、要么都不实现：缺任何一个，
      * `PUT/GET/DELETE /llm-credentials` 返回 501，带 `credRefs` 的
      * `POST /schedule-message` 也会被拒。内置的 D1 / pg / neon 适配器都实现了。
      */
-    deleteLlmCredentials?: (userId: string, credIds: string[] | null) => Promise<number>;
+    deleteLlmCredentialsByPrefix?: (userId: string, credIdPrefix: string) => Promise<number>;
     /**
      * （可选）投递期间的租约续期（runScheduledTick 的心跳）。只在行仍是
      * pending 且 lease_until 非空时生效——收尾放掉租约之后，迟到的心跳不会把
@@ -307,6 +343,15 @@ export type DbAdapter = {
      * （可选；单用户/D1）客户端确认收到（POST /outbox/ack，幂等）。
      */
     ackOutboxMessages?: (userId: string, messageIds: string[], ackedAt: number) => Promise<number>;
+    /**
+     * （可选；单用户/D1）主动删行：数组删指定那几条，null 删这个用户的全部
+     * （`DELETE /outbox`）。与 `discardOutboxMessages` 分工不同——那个只撤还没发出
+     * 去的行（取消 / 顶替的收尾），这个不看 delivered_at / acked_at，是宿主对完账
+     * 之后的清理口。不实现 → `DELETE /outbox` 返回 501。
+     * 数组形态要按 D1 的 100 个绑定参数上限切批（`user_id` 占 1 个 → 一批最多 99
+     * 个 id），切开的几条仍要在一个事务里。
+     */
+    deleteOutboxMessages?: (userId: string, messageIds: string[] | null) => Promise<number>;
     /**
      * （可选；单用户/D1）outbox 例行清理（runScheduledTick 每跳顺手调）。
      *