@rei-standard/amsg-server 2.6.0-next.16 → 2.6.0-next.17

package/README.md

@@ -47,6 +47,9 @@ const rei = await createReiServer({
 // PUT  /api/v1/push-subscription    -> rei.handlers.pushSubscription.PUT
 // GET  /api/v1/push-subscription    -> rei.handlers.pushSubscription.GET
 // DELETE /api/v1/push-subscription  -> rei.handlers.pushSubscription.DELETE
+// PUT  /api/v1/llm-credentials      -> rei.handlers.llmCredentials.PUT
+// GET  /api/v1/llm-credentials      -> rei.handlers.llmCredentials.GET
+// DELETE /api/v1/llm-credentials    -> rei.handlers.llmCredentials.DELETE
 ```
 
 ## 关于 `messageType: 'instant'`
@@ -160,6 +163,51 @@ const message = body.length <= remainingBytes ? body : body.slice(0, remainingBy
 
 装不下的内容（长文、附件详情）建议走旁路：正文存进 `client_state`，push 里只带一个引用键，客户端上线后用 `GET /client-state` 取回。单用户 Worker 的 fire-time hook 用 `ctx.writeState()` 写，见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md)。
 
+## LLM 凭据（用户级）与 credRefs
+
+LLM API 凭据（`apiUrl` / `apiKey` / `primaryModel`）有两种给法：
+
+- **内联**：随排程请求带三件套，冻结进任务行（一直以来的方式，继续支持）。
+- **引用**：凭据先用 `PUT /llm-credentials` 集中登记，排程 payload 里只带
+  `credRefs: { chat: '<credId>' }`。到点投递时按 credId 现读——换 Key 覆盖对应
+  行就够了，所有引用它的任务（包括角色在 fire 里给自己排的、客户端根本不知道
+  存在的那些）下次触发用的都是新凭据。
+
+| 端点 | 语义 |
+|---|---|
+| `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 }` |
+
+客户端侧对应 `client.putLlmCredentials(credentials)` / `listLlmCredentials()` / `deleteLlmCredentials(opts)`。
+
+`credId` 是客户端起名的**不透明字符串**（1–128 字符、不含控制字符），服务端不
+解释语义。约定：`char:<charId>/<purpose>`（角色级）、`global/<purpose>`（全
+局）。`credRefs` 的 purpose 键里只有 `chat` 由服务端消费（fire 时的主 LLM 调
+用）；其余 purpose（如情绪评估的副 API）归宿主 hook 侧，fire hook 的 ctx 上有
+`resolveLlmCredential(credId)` 可按需取用（每次返回新对象；拿到就用，别挂到
+ctx / metadata / push 上）。
+
+配套的规则：
+
+- 排程 / 更新时对 `credRefs` 里的**全部** credId 做存在性检查，缺的返回
+  `409 CREDENTIAL_NOT_FOUND` 并点名（先登记再排程）。
+- `credRefs.chat` 与内联三件套在同一个请求里不能都传（`400`）：chat 凭据只能
+  有一个来源。
+- fire 时的解析顺序：`credRefs.chat` → 查表；行没了 → 退回任务里的内联三件套
+  （如有）；都没有 → 本轮失败，`lastError` 记 `CREDENTIAL_MISSING`，走常规重
+  试——补传凭据后下一轮自愈。
+- hook 的 `ctx.scheduleTask()` 自排任务时：父任务带 `credRefs` 就复制**引用**
+  （不复制凭据本体），换 Key 自动作用于整条自排链；存量内联任务照旧复制三件套。
+- 任务投影（`GET /messages` / hook 的 `ctx.task`）带 `credRefs`（只是名字，不
+  是机密），客户端对账用；凭据本体照旧被白名单挡在外面。
+- 数据库侧是 `llm_credentials` 表（`(user_id, cred_id)` 主键，`encrypted_value`
+  密文，时间戳 ISO8601 文本）。内置的 D1 / pg / neon 适配器都实现了，
+  `initSchema()` 会建表。自定义适配器要补 `upsertLlmCredentials` /
+  `getLlmCredentials` / `listLlmCredentials` / `deleteLlmCredentials` 四个方法，
+  缺任何一个这几个端点返回 501、带 `credRefs` 的排程也会被拒。
+- 特性探测：`GET /capabilities` 的 `features` 含 `'llm-credentials'`。
+
 ## 读一条任务：列表 vs 单条
 
 | 端点 | 给什么 |
@@ -173,12 +221,13 @@ const message = body.length <= remainingBytes ? body : body.slice(0, remainingBy
 
 ## 更新任务时能改哪些字段
 
-`PUT /update-message` 的可写字段：`contactName` / `avatarUrl` / `userMessage` / `completePrompt` / `messages` / `nextSendAt` / `recurrenceType` / `tzId` / `metadata` / `maxTokens` / `temperature` / `splitPattern`，以及凭据三件套 `apiUrl` / `apiKey` / `primaryModel`。
+`PUT /update-message` 的可写字段：`contactName` / `avatarUrl` / `userMessage` / `completePrompt` / `messages` / `nextSendAt` / `recurrenceType` / `tzId` / `metadata` / `maxTokens` / `temperature` / `splitPattern`、凭据三件套 `apiUrl` / `apiKey` / `primaryModel`，以及凭据引用 `credRefs`。
 
 - `contactName` 必须是非空字符串（口径与排程时一致），空串 / `null` / 非字符串一律 `400`。用户给角色改了名之后，之前排的任务推送出来的通知标题（「来自 <contactName>」）靠它跟着改。
 - `metadata` 是整体替换，不深合并——只改一个子字段的读-改-写流程见上一节。
 - `avatarUrl` 显式传 `null` 是「不改」而不是「清空」（§6.2 的软清空策略要求非法头像被摘掉时保留旧头像，「摘掉」和「传了个 null」在这一层是同一件事）。
 - 凭据三件套传 `null` 同样只是忽略：清掉任何一个，任务到点就发不出去。
+- `credRefs` 是整体替换（语义同 `metadata`），同样做存在性检查；与内联三件套在同一个请求里混着传返回 `400`。给存量内联任务补 `credRefs` 时不动已存的三件套——那份留作 fire 时表行缺失的兜底。
 - `pushSubscription` 不收（`400 PUSH_SUBSCRIPTION_NOT_ACCEPTED`），它是用户级的一份，走 `PUT /push-subscription`。
 
 ## 推送自带任务身份

package/dist/adapters/d1.d.ts

@@ -237,6 +237,51 @@ export class D1Adapter {
      * @returns {Promise<boolean>} true = 确实删掉了一行
      */
     deletePushSubscription(userId: string): Promise<boolean>;
+    /**
+     * 批量 upsert 这个用户的凭据（value 已是密文，加密在上层）。已存在的行
+     * 覆盖 encrypted_value 并刷 updated_at，created_at 保留首次写入的时刻。
+     *
+     * @param {string} userId
+     * @param {Array<{ credId: string, encryptedValue: string }>} entries
+     * @returns {Promise<number>} 实际写入/覆盖的行数
+     */
+    upsertLlmCredentials(userId: string, entries: Array<{
+        credId: string;
+        encryptedValue: string;
+    }>): Promise<number>;
+    /**
+     * 按 cred_id 批量读这个用户的凭据行（`encrypted_value` 是密文，解密在上
+     * 层）。排程时的存在性检查和 fire 时的解析共用这一个口。
+     *
+     * @param {string} userId
+     * @param {string[]} credIds
+     * @returns {Promise<Array<{ cred_id: string, encrypted_value: string, updated_at: string }>>}
+     */
+    getLlmCredentials(userId: string, credIds: string[]): Promise<Array<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at，密文不出
+     * 这个方法）。按 cred_id 排序，输出稳定。
+     *
+     * @param {string} userId
+     * @returns {Promise<Array<{ cred_id: string, updated_at: string }>>}
+     */
+    listLlmCredentials(userId: string): Promise<Array<{
+        cred_id: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 删凭据。`credIds` 传数组删指定那几行；传 null 删这个用户的全部
+     * （「清空云端数据」用）。
+     *
+     * @param {string} userId
+     * @param {string[]|null} credIds
+     * @returns {Promise<number>} 删掉的行数
+     */
+    deleteLlmCredentials(userId: string, credIds?: string[] | null): Promise<number>;
     /**
      * 发送前把这一批 push 落进 outbox（一次 batch）。(user_id, message_id)
      * 唯一：重试同一 occurrence 带着同一批 messageId 再来时更新 payload、不加

package/dist/adapters/interface.d.ts

@@ -179,6 +179,39 @@ export type DbAdapter = {
      * （建了也永远发不出去）。内置的 D1 / pg / neon 适配器都实现了。
      */
     deletePushSubscription?: (userId: string) => Promise<boolean>;
+    /**
+     * 批量覆盖写这个用户的 LLM 凭据（`encryptedValue` 是密文，加密在上层）。
+     * 已存在的行覆盖 encrypted_value 并刷 updated_at。返回实际写入/覆盖的行数。
+     */
+    upsertLlmCredentials?: (userId: string, entries: Array<{
+        credId: string;
+        encryptedValue: string;
+    }>) => Promise<number>;
+    /**
+     * 按 cred_id 批量读凭据行（密文原样返回）。排程时的存在性检查和 fire 时的
+     * 解析共用这一个口。
+     */
+    getLlmCredentials?: (userId: string, credIds: string[]) => Promise<Array<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at，密文不出这个
+     * 方法）。按 cred_id 排序。
+     */
+    listLlmCredentials?: (userId: string) => Promise<Array<{
+        cred_id: string;
+        updated_at: string;
+    }>>;
+    /**
+     * 删凭据：数组删指定那几行，null 删全部。返回删掉的行数。
+     *
+     * llm_credentials 四个方法要么都实现、要么都不实现：缺任何一个，
+     * `PUT/GET/DELETE /llm-credentials` 返回 501，带 `credRefs` 的
+     * `POST /schedule-message` 也会被拒。内置的 D1 / pg / neon 适配器都实现了。
+     */
+    deleteLlmCredentials?: (userId: string, credIds: string[] | null) => Promise<number>;
     /**
      * （可选）投递期间的租约续期（runScheduledTick 的心跳）。只在行仍是
      * pending 且 lease_until 非空时生效——收尾放掉租约之后，迟到的心跳不会把

package/dist/adapters/neon.d.ts

@@ -68,4 +68,15 @@ export class NeonAdapter {
     }>;
     upsertPushSubscription(userId: any, encryptedSubscription: any, updatedAt: any): Promise<boolean>;
     deletePushSubscription(userId: any): Promise<boolean>;
+    upsertLlmCredentials(userId: any, entries: any): Promise<number>;
+    getLlmCredentials(userId: any, credIds: any): Promise<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }[]>;
+    listLlmCredentials(userId: any): Promise<{
+        cred_id: string;
+        updated_at: string;
+    }[]>;
+    deleteLlmCredentials(userId: any, credIds?: any): Promise<number>;
 }

package/dist/adapters/pg-shared.d.ts

@@ -101,6 +101,53 @@ export function upsertPushSubscription(query: PgQuery, userId: string, encrypted
  * @returns {Promise<boolean>} true = 确实删掉了一行
  */
 export function deletePushSubscription(query: PgQuery, userId: string): Promise<boolean>;
+/**
+ * 批量 upsert 这个用户的凭据（value 已是密文，加密在上层）。已存在的行覆盖
+ * encrypted_value 并刷 updated_at，created_at 保留首次写入的时刻。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {Array<{ credId: string, encryptedValue: string }>} entries
+ * @param {string} now - ISO8601 时间戳（与 SQLite 侧同口径的 TEXT）
+ * @returns {Promise<number>} 实际写入/覆盖的行数
+ */
+export function upsertLlmCredentials(query: PgQuery, userId: string, entries: Array<{
+    credId: string;
+    encryptedValue: string;
+}>, now: string): Promise<number>;
+/**
+ * 按 cred_id 批量读这个用户的凭据行（密文原样返回，解密在上层）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {string[]} credIds
+ * @returns {Promise<Array<{ cred_id: string, encrypted_value: string, updated_at: string }>>}
+ */
+export function getLlmCredentials(query: PgQuery, userId: string, credIds: string[]): Promise<Array<{
+    cred_id: string;
+    encrypted_value: string;
+    updated_at: string;
+}>>;
+/**
+ * 这个用户名下所有凭据的对账清单（只有 cred_id 和 updated_at）。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @returns {Promise<Array<{ cred_id: string, updated_at: string }>>}
+ */
+export function listLlmCredentials(query: PgQuery, userId: string): Promise<Array<{
+    cred_id: string;
+    updated_at: string;
+}>>;
+/**
+ * 删凭据。`credIds` 传数组删指定那几行；传 null 删这个用户的全部。
+ *
+ * @param {PgQuery} query
+ * @param {string} userId
+ * @param {string[]|null} credIds
+ * @returns {Promise<number>} 删掉的行数
+ */
+export function deleteLlmCredentials(query: PgQuery, userId: string, credIds?: string[] | null): Promise<number>;
 /**
  * pg / neon 共用的 Postgres 查询实现。
  *

package/dist/adapters/pg.d.ts

@@ -70,4 +70,15 @@ export class PgAdapter {
     }>;
     upsertPushSubscription(userId: any, encryptedSubscription: any, updatedAt: any): Promise<boolean>;
     deletePushSubscription(userId: any): Promise<boolean>;
+    upsertLlmCredentials(userId: any, entries: any): Promise<number>;
+    getLlmCredentials(userId: any, credIds: any): Promise<{
+        cred_id: string;
+        encrypted_value: string;
+        updated_at: string;
+    }[]>;
+    listLlmCredentials(userId: any): Promise<{
+        cred_id: string;
+        updated_at: string;
+    }[]>;
+    deleteLlmCredentials(userId: any, credIds?: any): Promise<number>;
 }

package/dist/adapters/schema.d.ts

@@ -35,6 +35,7 @@ export const INDEXES: ({
     critical: boolean;
 })[];
 export const PUSH_SUBSCRIPTION_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS push_subscriptions (\n    user_id VARCHAR(255) PRIMARY KEY,\n    subscription TEXT NOT NULL,\n    updated_at BIGINT NOT NULL\n  )\n";
+export const LLM_CREDENTIALS_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS llm_credentials (\n    user_id VARCHAR(255) NOT NULL,\n    cred_id VARCHAR(128) NOT NULL,\n    encrypted_value TEXT NOT NULL,\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL,\n    PRIMARY KEY (user_id, cred_id)\n  )\n";
 export const VERIFY_TABLE_SQL: "\n  SELECT table_name\n  FROM information_schema.tables\n  WHERE table_schema = 'public'\n    AND table_name = 'scheduled_messages'\n";
 export const COLUMNS_SQL: "\n  SELECT column_name, data_type, is_nullable\n  FROM information_schema.columns\n  WHERE table_schema = 'public'\n    AND table_name = 'scheduled_messages'\n  ORDER BY ordinal_position\n";
 export const UPDATABLE_COLUMNS: Set<string>;

package/dist/adapters/schema.sqlite.d.ts

@@ -32,6 +32,7 @@ export const SQLITE_INDEXES: {
 }[];
 export const CLIENT_STATE_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS client_state (\n    user_id TEXT NOT NULL,\n    namespace TEXT NOT NULL,\n    key TEXT NOT NULL,\n    value TEXT NOT NULL,\n    updated_at INTEGER NOT NULL,\n    PRIMARY KEY (user_id, namespace, key)\n  )\n";
 export const PUSH_SUBSCRIPTION_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS push_subscriptions (\n    user_id TEXT PRIMARY KEY,\n    subscription TEXT NOT NULL,\n    updated_at INTEGER NOT NULL\n  )\n";
+export const LLM_CREDENTIALS_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS llm_credentials (\n    user_id TEXT NOT NULL,\n    cred_id TEXT NOT NULL,\n    encrypted_value TEXT NOT NULL,\n    created_at TEXT NOT NULL,\n    updated_at TEXT NOT NULL,\n    PRIMARY KEY (user_id, cred_id)\n  )\n";
 export const MESSAGE_OUTBOX_TABLE_SQL: "\n  CREATE TABLE IF NOT EXISTS message_outbox (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    user_id TEXT NOT NULL,\n    message_id TEXT NOT NULL,\n    task_uuid TEXT,\n    session_id TEXT,\n    message_index INTEGER,\n    total_messages INTEGER,\n    payload TEXT NOT NULL,\n    created_at INTEGER NOT NULL,\n    delivered_at INTEGER,\n    acked_at INTEGER,\n    UNIQUE (user_id, message_id)\n  )\n";
 export const MESSAGE_OUTBOX_INDEX_SQL: "\n  CREATE INDEX IF NOT EXISTS idx_outbox_unacked\n    ON message_outbox (user_id, id)\n    WHERE acked_at IS NULL\n";
 /**

package/dist/{chunk-34I2YSWE.mjs → chunk-5FXVSC5O.mjs}

@@ -93,6 +93,16 @@ var PUSH_SUBSCRIPTION_TABLE_SQL = `
     updated_at BIGINT NOT NULL
   )
 `;
+var LLM_CREDENTIALS_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS llm_credentials (
+    user_id VARCHAR(255) NOT NULL,
+    cred_id VARCHAR(128) NOT NULL,
+    encrypted_value TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (user_id, cred_id)
+  )
+`;
 var VERIFY_TABLE_SQL = `
   SELECT table_name
   FROM information_schema.tables
@@ -127,6 +137,7 @@ export {
   MIGRATIONS,
   INDEXES,
   PUSH_SUBSCRIPTION_TABLE_SQL,
+  LLM_CREDENTIALS_TABLE_SQL,
   VERIFY_TABLE_SQL,
   COLUMNS_SQL,
   UPDATABLE_COLUMNS

package/dist/{chunk-TFFBMYA2.cjs → chunk-E7OWP3VL.cjs}

@@ -84,6 +84,46 @@ async function deletePushSubscription(query, userId) {
   );
   return rows.length > 0;
 }
+async function upsertLlmCredentials(query, userId, entries, now) {
+  let upserted = 0;
+  for (const entry of entries) {
+    const rows = await query(
+      `INSERT INTO llm_credentials (user_id, cred_id, encrypted_value, created_at, updated_at)
+       VALUES ($1, $2, $3, $4, $4)
+       ON CONFLICT (user_id, cred_id) DO UPDATE SET
+         encrypted_value = EXCLUDED.encrypted_value,
+         updated_at = EXCLUDED.updated_at
+       RETURNING cred_id`,
+      [userId, entry.credId, entry.encryptedValue, now]
+    );
+    if (rows.length > 0) upserted++;
+  }
+  return upserted;
+}
+async function getLlmCredentials(query, userId, credIds) {
+  if (!credIds || credIds.length === 0) return [];
+  return query(
+    `SELECT cred_id, encrypted_value, updated_at
+     FROM llm_credentials
+     WHERE user_id = $1 AND cred_id = ANY($2)`,
+    [userId, credIds]
+  );
+}
+async function listLlmCredentials(query, userId) {
+  return query(
+    "SELECT cred_id, updated_at FROM llm_credentials WHERE user_id = $1 ORDER BY cred_id ASC",
+    [userId]
+  );
+}
+async function deleteLlmCredentials(query, userId, credIds = null) {
+  if (credIds !== null && credIds.length === 0) return 0;
+  const rows = credIds === null ? await query("DELETE FROM llm_credentials WHERE user_id = $1 RETURNING cred_id", [userId]) : await query("DELETE FROM llm_credentials WHERE user_id = $1 AND cred_id = ANY($2) RETURNING cred_id", [userId, credIds]);
+  return rows.length;
+}
+
+
+
+
 
 
 
@@ -92,4 +132,4 @@ async function deletePushSubscription(query, userId) {
 
 
 
-exports.claimTask = claimTask; exports.renewTaskLease = renewTaskLease; exports.getTaskStatusInfo = getTaskStatusInfo; exports.getPushSubscription = getPushSubscription; exports.upsertPushSubscription = upsertPushSubscription; exports.deletePushSubscription = deletePushSubscription;
+exports.claimTask = claimTask; exports.renewTaskLease = renewTaskLease; exports.getTaskStatusInfo = getTaskStatusInfo; exports.getPushSubscription = getPushSubscription; exports.upsertPushSubscription = upsertPushSubscription; exports.deletePushSubscription = deletePushSubscription; exports.upsertLlmCredentials = upsertLlmCredentials; exports.getLlmCredentials = getLlmCredentials; exports.listLlmCredentials = listLlmCredentials; exports.deleteLlmCredentials = deleteLlmCredentials;