mioku-plugin-agent 0.1.1 → 0.2.1

package/README.md

@@ -12,11 +12,11 @@
   - `auto` 自动：文件与命令直接执行，但**每条命令先由工作模型审查**，危险操作（删除用户文件、清库、`git push`、sudo 等）转用户审批；执行通知与审批请求都即时推送
   - `full` 完全访问：不审批，命令与写入/编辑汇总成一条转发记录
   - `yolo` 静默：权限最高且**不推送任何中间通知**，用户只收到最终结果
-- **个人工作区**：每个 QQ 号独立工作区，默认 `data/agent/workspace/<qq号>`
+- **个人工作区**：每个「适配器 + 用户」独立工作区，默认 `data/agent/workspace/<适配器>_<用户id>`（openid 平台同样隔离）
 - **聊天内审批**：非 full 权限档下 bash 命令需 `.agent approve` 批准（不带 id 时处理该用户最近一次请求）；每条命令都必须带 `purpose`，审批与执行告知都会带上用途
 - **操作合并转发**（仅 `full`）：命令、写入、编辑不再逐条推送，而是攒到本轮结束、在最终回复**之前**合并成一条合并转发消息（卡片来源「Agent 执行记录」，外显小字是操作条数与用户请求摘要，总摘要是各类操作计数与失败数；首节点为简介，其余节点按时间顺序记录每条命令/文件改动，含用途、耗时与失败输出）。适配器不支持转发时自动降级为普通文本消息。`read`/`glob`/`grep`/联网/看图等只读操作不记录。`auto` 不合并，仍逐条即时推送
 - **工具面**：read / write / edit / glob / grep / bash / view_image / send_file / send_image / web_search (SearXNG) / web_fetch / todo_write
-- **附件自动下载**：用户发来的图片/文件/音视频统一按文件自动落到 `download/<今天日期>/`，**保留原始文件名与后缀**（`file_name` → segment 的 `file` → `path` → URL 文件名，缺后缀才用 content-type 补）；user 消息里带 `message_id`、`name` 和 `[file://路径]`，图片额外作为图片内容附加给模型。QQ 文件消息只有 `file_id` 时按平台 API（`get_file` / `get_group_file_url` / `get_private_file_url`）换取下载地址与原始文件名
+- **附件自动下载**：用户发来的图片/文件/音视频统一按文件自动落到 `download/<今天日期>/`，**保留原始文件名与后缀**（`file_name` → segment 的 `file` → `path` → URL 文件名，缺后缀才用 content-type 补）；user 消息里带 `message_id`、`name` 和 `[file://路径]`，图片额外作为图片内容附加给模型。文件消息只有 `file_id` 时按平台分支解析下载地址，见下
 - **消息引用**：模型在回复首行写 `[reply:message_id]` 即可引用（回复）指定聊天消息，标记会被移除并只作用于本轮第一条消息
 - **运行中插话**：Agent 正在跑时用户继续发消息，不再排队等下一轮，而是并入**当前请求**的下一次迭代（DSH 式 steering），模型在同一个回复里就能看到并调整；日志里 `steer queued` 表示已入队、`steer merged into running turn` 表示已并入本轮请求
 - **看图**：`view_image` 查看本地图片；多模态主模型直接把图片附加进对话，非多模态时交给视觉模型转成描述
@@ -34,6 +34,8 @@
 
 默认仅 bot 主人私聊可用；可在配置中允许管理员或指定用户。
 
+私聊中以 `.` / `/` / `~` 开头的消息视为命令，agent 直接忽略不处理
+
 ## 命令
 
 | 命令                                                               | 说明                                                                   | 权限     |

package/commands/index.ts

@@ -4,15 +4,16 @@ import type { SessionPlanItem } from "../db";
 import { maybeCompact } from "../core/compaction";
 import { generateSessionTitle } from "../core/title";
 import { stopAgentTurn } from "../core/loop";
+import { identityOf } from "../core/identity";
 import { PERMISSION_LEVELS } from "../tools/perm";
 
 const CLEAR_CONFIRM_TTL_MS = 60_000;
 
 const resumeListCache = new Map<
-  number,
+  string,
   { generations: number[]; at: number }
 >();
-const pendingClear = new Map<number, number>();
+const pendingClear = new Map<string, number>();
 
 async function reply(event: MessageEvent, text: string): Promise<void> {
   await event.reply(text, true);
@@ -21,12 +22,12 @@ async function reply(event: MessageEvent, text: string): Promise<void> {
 async function requireUser(
   host: AgentHost,
   event: MessageEvent,
-): Promise<number> {
-  const userId = Number(event.user_id || event.sender?.user_id || 0);
-  if (!userId) {
-    await reply(event, "agent 命令需要在 QQ 私聊中使用");
+): Promise<string> {
+  const identity = identityOf(event);
+  if (!identity.userId) {
+    await reply(event, "agent 命令需要在私聊中使用");
   }
-  return userId;
+  return identity.scope;
 }
 
 function formatTime(ts: number): string {
@@ -56,7 +57,7 @@ async function backgroundTitle(
   host.logger.info(`[agent] session ${sessionId} titled: ${title}`);
 }
 
-function cachedResumable(host: AgentHost, userId: number): number[] {
+function cachedResumable(host: AgentHost, userId: string): number[] {
   const cached = resumeListCache.get(userId);
   if (cached && Date.now() - cached.at < 5 * 60_000) return cached.generations;
   const current = host.sessions.sessionId(userId);
@@ -67,7 +68,7 @@ function cachedResumable(host: AgentHost, userId: number): number[] {
   return generations;
 }
 
-function invalidateResumeCache(userId: number): void {
+function invalidateResumeCache(userId: string): void {
   resumeListCache.delete(userId);
 }
 

package/core/compaction.ts

@@ -34,7 +34,7 @@ export interface CompactionResult {
 
 export async function maybeCompact(
   host: AgentHost,
-  userId: number,
+  userId: string,
   options: { force?: boolean } = {},
 ): Promise<CompactionResult> {
   const settings = host.getSettings();

package/core/download.ts

@@ -3,6 +3,8 @@ import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 import type { Bot } from "mioku";
 import type { MediaAttachment, MediaKind } from "./media";
+import type { AgentPlatform } from "../platforms/types";
+import { EMPTY_FILE_LOOKUP } from "../platforms/types";
 
 const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
 const DOWNLOAD_TIMEOUT_MS = 60_000;
@@ -212,52 +214,18 @@ function candidateSources(item: MediaAttachment): string[] {
 async function platformLookup(
   bot: Bot | undefined,
   item: MediaAttachment,
+  platform: AgentPlatform | undefined,
 ): Promise<{ sources: string[]; names: string[] }> {
-  const sources: string[] = [];
-  const names: string[] = [];
-  if (!bot || !item.fileId) return { sources, names };
-
-  const attempts: Array<[string, Record<string, unknown>]> = [
-    ["get_file", { file_id: item.fileId }],
-  ];
-  if (item.groupId) {
-    attempts.push([
-      "get_group_file_url",
-      { group_id: Number(item.groupId), file_id: item.fileId },
-    ]);
-  }
-  if (item.userId) {
-    attempts.push([
-      "get_private_file_url",
-      { user_id: Number(item.userId), file_id: item.fileId },
-    ]);
-  }
-
-  for (const [action, params] of attempts) {
-    try {
-      const result = (await bot.sendApi(action, params)) as Record<
-        string,
-        unknown
-      > | null;
-      if (!result || typeof result !== "object") continue;
-      for (const key of ["url", "file", "path"]) {
-        const value = result[key];
-        if (typeof value === "string" && value.trim())
-          sources.push(value.trim());
-      }
-      const base64 = result.base64 ?? result.data;
-      if (typeof base64 === "string" && base64.trim()) {
-        sources.push(`base64://${base64.trim()}`);
-      }
-      for (const key of ["file_name", "name"]) {
-        const value = result[key];
-        if (typeof value === "string" && value.trim()) names.push(value.trim());
-      }
-    } catch {
-      // 平台不支持该 action 时忽略，继续尝试下一个
-    }
+  if (!bot || !item.fileId || !platform) return EMPTY_FILE_LOOKUP;
+  try {
+    return await platform.resolveFile(bot, {
+      fileId: item.fileId,
+      groupId: item.groupId,
+      userId: item.userId,
+    });
+  } catch {
+    return EMPTY_FILE_LOOKUP;
   }
-  return { sources, names };
 }
 
 function describeFields(item: MediaAttachment): string {
@@ -273,13 +241,14 @@ function describeFields(item: MediaAttachment): string {
 async function resolveSource(
   item: MediaAttachment,
   bot: Bot | undefined,
+  platform: AgentPlatform | undefined,
 ): Promise<{
   buffer: Buffer;
   contentType: string | null;
   fallbackName: string;
 }> {
-  const platform = await platformLookup(bot, item);
-  const candidates = [...candidateSources(item), ...platform.sources];
+  const found = await platformLookup(bot, item, platform);
+  const candidates = [...candidateSources(item), ...found.sources];
   if (candidates.length === 0) {
     throw new Error(`no downloadable source (${describeFields(item)})`);
   }
@@ -290,7 +259,7 @@ async function resolveSource(
       // 平台返回的原始文件名最可信，其次才是 URL 推断出来的名字
       return {
         ...result,
-        fallbackName: platform.names[0] ?? result.fallbackName,
+        fallbackName: found.names[0] ?? result.fallbackName,
       };
     } catch (err) {
       lastError = String(err);
@@ -302,7 +271,7 @@ async function resolveSource(
 export async function downloadMediaItems(
   items: MediaAttachment[],
   workspaceRoot: string,
-  options: { bot?: Bot } = {},
+  options: { bot?: Bot; platform?: AgentPlatform } = {},
 ): Promise<DownloadResult> {
   const dir = path.join(workspaceRoot, "download", dateStamp());
   const files: DownloadedMedia[] = [];
@@ -315,6 +284,7 @@ export async function downloadMediaItems(
       const { buffer, contentType, fallbackName } = await resolveSource(
         item,
         options.bot,
+        options.platform,
       );
       if (buffer.byteLength > MAX_DOWNLOAD_BYTES) {
         errors.push(`#${index + 1} exceeds ${MAX_DOWNLOAD_BYTES} bytes`);

package/core/emotion.ts

@@ -8,7 +8,7 @@ function normalizeName(value: unknown): string {
 
 export class EmotionManager {
   constructor(
-    private readonly store: (userId: number, emotion: string) => void,
+    private readonly store: (userId: string, emotion: string) => void,
   ) {}
 
   available(config: ChatEmotionConfig | null): string[] {
@@ -36,7 +36,7 @@ export class EmotionManager {
   }
 
   setEmotion(
-    userId: number,
+    userId: string,
     emotion: unknown,
     config: ChatEmotionConfig | null,
   ): string {

package/core/identity.ts

@@ -0,0 +1,27 @@
+import type { MessageEvent } from "mioku";
+
+/**
+ * 事件的用户身份。
+ * `userId` 是平台原始 id(QQ 号或 openid),用于权限名单匹配;
+ * `scope` 额外带上适配器,用于会话/工作区/队列隔离,避免不同平台相同 id 串号。
+ */
+export interface AgentIdentity {
+  readonly userId: string;
+  readonly adapter: string;
+  readonly botId: string;
+  readonly scope: string;
+}
+
+export const identityOf = (event: MessageEvent): AgentIdentity => {
+  const userId = String(event?.user_id ?? event?.sender?.user_id ?? "").trim();
+  const adapter = String(
+    event?.bot?.adapter ?? event?.identity?.adapter ?? "",
+  ).trim();
+  const botId = String(event?.self_id ?? event?.bot?.bot_id ?? "").trim();
+  return {
+    userId,
+    adapter,
+    botId,
+    scope: `${adapter || "unknown"}:${userId}`,
+  };
+};

package/core/loop.ts

@@ -12,6 +12,8 @@ import { TurnSender } from "./send";
 import { buildSystemPrompt } from "./prompt";
 import { maybeCompact } from "./compaction";
 import { cleanEmotionMarkers, stripThinkBlocks } from "./units";
+import { identityOf, type AgentIdentity } from "./identity";
+import type { AgentPlatform } from "../platforms/types";
 import { describeImageUrls, extractMedia, formatMediaNote } from "./media";
 import { downloadMediaItems, readImageDataUrl } from "./download";
 import { TurnActivity } from "./activity";
@@ -42,9 +44,9 @@ interface UserQueue {
   controller: AbortController | null;
 }
 
-const queues = new Map<number, UserQueue>();
+const queues = new Map<string, UserQueue>();
 
-function getQueue(userId: number): UserQueue {
+function getQueue(userId: string): UserQueue {
   let queue = queues.get(userId);
   if (!queue) {
     queue = { running: false, inbox: [], controller: null };
@@ -55,7 +57,7 @@ function getQueue(userId: number): UserQueue {
 
 export function stopAgentTurn(
   host: AgentHost,
-  userId: number,
+  userId: string,
 ): { running: boolean; dropped: number; approvals: number } {
   const queue = queues.get(userId);
   const dropped = queue?.inbox.length ?? 0;
@@ -72,29 +74,31 @@ export function stopAgentTurn(
 function kickQueue(
   host: AgentHost,
   event: MessageEvent,
-  userId: number,
+  userId: string,
   queue: UserQueue,
 ): void {
   if (queue.running) return;
   const next = queue.inbox.shift();
   if (!next) return;
   queue.running = true;
-  void drainTurns(host, event, userId, queue, next);
+  void drainTurns(host, event, identityOf(event), queue, next);
 }
 
 export function runAgentTurn(
   host: AgentHost,
   event: MessageEvent,
+  platform: AgentPlatform,
 ): Promise<void> {
-  const userId = Number(event.user_id || event.sender?.user_id || 0);
-  if (!userId) return Promise.resolve();
+  const identity = identityOf(event);
+  if (!identity.userId) return Promise.resolve();
+  const userId = identity.scope;
   const queue = getQueue(userId);
 
   // 先占住轮次再准备输入，保证消息按到达顺序处理
   const ownsTurn = !queue.running;
   if (ownsTurn) queue.running = true;
 
-  return prepareInput(host, event, userId)
+  return prepareInput(host, event, identity, platform)
     .then((input) => {
       if (!input) {
         if (ownsTurn) {
@@ -112,7 +116,7 @@ export function runAgentTurn(
         kickQueue(host, event, userId, queue);
         return;
       }
-      return drainTurns(host, event, userId, queue, input);
+      return drainTurns(host, event, identity, queue, input);
     })
     .catch((err) => {
       if (ownsTurn) {
@@ -126,7 +130,7 @@ export function runAgentTurn(
 async function drainTurns(
   host: AgentHost,
   event: MessageEvent,
-  userId: number,
+  identity: AgentIdentity,
   queue: UserQueue,
   first: PreparedInput,
 ): Promise<void> {
@@ -135,29 +139,31 @@ async function drainTurns(
   try {
     let next: PreparedInput | undefined = first;
     while (next) {
-      await executeTurn(host, event, userId, next, queue, controller.signal);
+      await executeTurn(host, event, identity, next, queue, controller.signal);
       next = queue.inbox.shift();
     }
   } finally {
     queue.controller = null;
     queue.running = false;
-    kickQueue(host, event, userId, queue);
+    kickQueue(host, event, identity.scope, queue);
   }
 }
 
 async function prepareInput(
   host: AgentHost,
   event: MessageEvent,
-  userId: number,
+  identity: AgentIdentity,
+  platform: AgentPlatform,
 ): Promise<PreparedInput | null> {
   const resolved = host.resolveModel();
   const bot = event.bot ?? host.ctx.pickBot(event.self_id);
   const media = extractMedia(event);
   const downloads = await downloadMediaItems(
     media,
-    host.workspaceRoot(userId),
+    host.workspaceRoot(identity.scope),
     {
       bot,
+      platform,
     },
   ).catch((err) => {
     host.logger.warn(`[agent] attachment download failed: ${err}`);
@@ -216,7 +222,7 @@ async function prepareInput(
 
 function steeringMessages(
   host: AgentHost,
-  userId: number,
+  userId: string,
   queue: UserQueue,
 ): AgentChatMessage[] {
   if (queue.inbox.length === 0) return [];
@@ -249,11 +255,13 @@ function steeringContent(
 async function executeTurn(
   host: AgentHost,
   event: MessageEvent,
-  userId: number,
+  identity: AgentIdentity,
   input: PreparedInput,
   queue: UserQueue,
   abortSignal: AbortSignal,
 ): Promise<void> {
+  const userId = identity.scope;
+  const sendUserId = identity.userId;
   const base = host.getBase();
   const settings = host.getSettings();
   const resolved = host.resolveModel();
@@ -263,7 +271,7 @@ async function executeTurn(
   const activity = new TurnActivity(digestMode);
 
   if (!resolved) {
-    await replyError(host, bot, userId, "AI 服务不可用，请先在 WebUI 配置模型");
+    await replyError(host, bot, sendUserId, "AI 服务不可用，请先在 WebUI 配置模型");
     return;
   }
 
@@ -286,7 +294,7 @@ async function executeTurn(
 
   const sendToUser = async (text: string): Promise<void> => {
     if (!bot) return;
-    await bot.sendMessage({ type: "private", user_id: userId }, [
+    await bot.sendMessage({ type: "private", user_id: sendUserId }, [
       host.ctx.segment.text(text),
     ]);
   };
@@ -332,6 +340,7 @@ async function executeTurn(
 
     const { tools, webSearchState } = buildTurnTools(host, {
       userId,
+      sendUserId,
       bot,
       runId,
       reporter,
@@ -390,15 +399,15 @@ async function executeTurn(
     const sender = new TurnSender(
       host,
       bot,
-      userId,
+      sendUserId,
       settings.enableMarkdownScreenshot && Boolean(host.screenshot),
     );
     const usageId = `agent:${sessionRow.sessionId}:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`;
     const usageContext = {
       usageId,
       source: "agent",
-      botId: Number(event?.self_id) || undefined,
-      userId,
+      botId: identity.botId || undefined,
+      userId: sendUserId,
       sessionId: sessionRow.sessionId,
     };
 
@@ -464,7 +473,7 @@ async function executeTurn(
     }
 
     // 批量模式：把本回合的全部操作合并成一条转发记录，放在最终回复之前
-    await flushActivity(host, activity, bot, userId, event);
+    await flushActivity(host, activity, bot, sendUserId, event);
 
     if (settings.stream && !digestMode) {
       await sender.finishStream(finalText);
@@ -483,11 +492,11 @@ async function executeTurn(
     status = "error";
     errorText = String(err);
     host.logger.error(`[agent] turn failed: ${err}`);
-    await flushActivity(host, activity, bot, userId, event);
+    await flushActivity(host, activity, bot, sendUserId, event);
     await replyError(
       host,
       bot,
-      userId,
+      sendUserId,
       `Agent 处理出错：${errorText.slice(0, 300)}`,
     );
   } finally {
@@ -552,15 +561,13 @@ async function flushActivity(
   host: AgentHost,
   activity: TurnActivity,
   bot: Bot | undefined,
-  userId: number,
+  userId: string,
   event: MessageEvent,
 ): Promise<void> {
   if (!bot || activity.total === 0) return;
   const target = { type: "private" as const, user_id: userId };
-  const selfId = String(
-    event.self_id || host.ctx.bot?.bot_id || bot.bot_id || userId,
-  );
-  const nickname = host.ctx.bot?.nickname ?? "Agent";
+  const selfId = String(event.self_id || bot.bot_id || userId);
+  const nickname = bot.nickname ?? "Agent";
   const nodes = activity.buildNodes(host.ctx, selfId, nickname);
   try {
     await bot.sendForward(target, nodes, activity.buildDisplay());
@@ -583,7 +590,7 @@ async function flushActivity(
 async function replyError(
   host: AgentHost,
   bot: Bot | undefined,
-  userId: number,
+  userId: string,
   text: string,
 ): Promise<void> {
   if (!bot) return;

package/core/send.ts

@@ -36,7 +36,7 @@ export class TurnSender {
   constructor(
     private host: AgentHost,
     private bot: Bot | undefined,
-    private userId: number,
+    private userId: string,
     private enableScreenshot: boolean,
   ) {}
 

package/core/session.ts

@@ -3,44 +3,44 @@ import type { AgentDatabase, AgentSessionRow } from "../db";
 export class SessionManager {
   constructor(private db: AgentDatabase) {}
 
-  generation(userId: number): number {
+  generation(userId: string): number {
     return this.db.getUserGeneration(userId);
   }
 
-  sessionId(userId: number): string {
+  sessionId(userId: string): string {
     return `agent:${userId}:g${this.generation(userId)}`;
   }
 
-  get(userId: number): AgentSessionRow {
+  get(userId: string): AgentSessionRow {
     return this.db.getOrCreateSession(this.sessionId(userId), userId);
   }
 
-  newSession(userId: number): AgentSessionRow {
+  newSession(userId: string): AgentSessionRow {
     this.db.bumpUserGenerationTo(userId, this.db.maxGeneration(userId) + 1);
     return this.get(userId);
   }
 
-  resume(userId: number, generation: number): AgentSessionRow | undefined {
+  resume(userId: string, generation: number): AgentSessionRow | undefined {
     const target = this.db.getSessionByGeneration(userId, generation);
     if (!target) return undefined;
     this.db.bumpUserGenerationTo(userId, generation);
     return this.db.getOrCreateSession(target.sessionId, userId);
   }
 
-  resumableSessions(userId: number, excludeSessionId: string): AgentSessionRow[] {
+  resumableSessions(userId: string, excludeSessionId: string): AgentSessionRow[] {
     return this.db
       .listSessions(userId, { archived: false })
       .filter((session) => session.sessionId !== excludeSessionId);
   }
 
-  archive(userId: number, generation: number): AgentSessionRow | undefined {
+  archive(userId: string, generation: number): AgentSessionRow | undefined {
     const target = this.db.getSessionByGeneration(userId, generation);
     if (!target) return undefined;
     this.db.setSessionMeta(target.sessionId, { archived: true });
     return this.db.getSessionByGeneration(userId, generation);
   }
 
-  reset(userId: number): void {
+  reset(userId: string): void {
     this.db.resetSession(this.sessionId(userId));
   }
 
@@ -48,11 +48,11 @@ export class SessionManager {
     return this.db.getMessagesAfter(session.sessionId, session.summaryUpTo);
   }
 
-  append(userId: number, role: "user" | "assistant", content: string): number {
+  append(userId: string, role: "user" | "assistant", content: string): number {
     return this.db.appendMessage(this.sessionId(userId), role, content);
   }
 
-  setEmotion(userId: number, emotion: string): void {
+  setEmotion(userId: string, emotion: string): void {
     this.db.setSessionMeta(this.sessionId(userId), { emotion });
   }
 }

package/db.ts

@@ -18,6 +18,14 @@ function rowString(row: SqlRow, key: string, fallback = ""): string {
   return typeof value === "string" ? value : fallback;
 }
 
+/** id 列可能是 TEXT(openid)也可能是 INTEGER 亲和存下的数字,统一转字符串 */
+function rowId(row: SqlRow | null | undefined, key: string, fallback = ""): string {
+  const value = row?.[key];
+  if (value == null) return fallback;
+  const text = String(value);
+  return text.length > 0 ? text : fallback;
+}
+
 export type SessionPlanStatus = "pending" | "in_progress" | "completed";
 
 export interface SessionPlanItem {
@@ -27,7 +35,7 @@ export interface SessionPlanItem {
 
 export interface AgentSessionRow {
   sessionId: string;
-  userId: number;
+  userId: string;
   generation: number;
   emotion: string;
   summary: string;
@@ -51,7 +59,7 @@ export interface AgentMessageRow {
 export interface AgentRunRow {
   id: number;
   sessionId: string;
-  userId: number;
+  userId: string;
   model: string;
   status: "ok" | "error";
   iterations: number;
@@ -93,7 +101,7 @@ export class AgentDatabase {
     this.db.run(`
       CREATE TABLE IF NOT EXISTS sessions (
         session_id TEXT PRIMARY KEY,
-        user_id INTEGER NOT NULL,
+        user_id TEXT NOT NULL,
         generation INTEGER NOT NULL DEFAULT 0,
         emotion TEXT NOT NULL DEFAULT '',
         summary TEXT NOT NULL DEFAULT '',
@@ -106,7 +114,7 @@ export class AgentDatabase {
         updated_at INTEGER NOT NULL
       );
       CREATE TABLE IF NOT EXISTS user_state (
-        user_id INTEGER PRIMARY KEY,
+        user_id TEXT PRIMARY KEY,
         generation INTEGER NOT NULL DEFAULT 0,
         updated_at INTEGER NOT NULL
       );
@@ -121,7 +129,7 @@ export class AgentDatabase {
       CREATE TABLE IF NOT EXISTS runs (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         session_id TEXT NOT NULL,
-        user_id INTEGER NOT NULL,
+        user_id TEXT NOT NULL,
         model TEXT NOT NULL DEFAULT '',
         status TEXT NOT NULL DEFAULT 'ok',
         iterations INTEGER NOT NULL DEFAULT 0,
@@ -142,23 +150,55 @@ export class AgentDatabase {
         created_at INTEGER NOT NULL
       );
     `);
+    this.#widenLegacyIdColumns();
+  }
+
+  /**
+   * 旧库的 user_state.user_id 是 INTEGER PRIMARY KEY(rowid 别名),
+   * 写入 openid 会直接抛 SQLiteError: datatype mismatch,这里重建成 TEXT。
+   */
+  #widenLegacyIdColumns(): void {
+    const info = this.db
+      .query("PRAGMA table_info(user_state)")
+      .all() as Array<{ name?: string; type?: string }>;
+    const column = info.find((item) => item.name === "user_id");
+    if (!column || String(column.type ?? "").toUpperCase() === "TEXT") return;
+
+    this.db.run("BEGIN");
+    try {
+      this.db.run("ALTER TABLE user_state RENAME TO user_state_legacy");
+      this.db.run(`
+        CREATE TABLE user_state (
+          user_id TEXT PRIMARY KEY,
+          generation INTEGER NOT NULL DEFAULT 0,
+          updated_at INTEGER NOT NULL
+        );
+        INSERT INTO user_state (user_id, generation, updated_at)
+          SELECT CAST(user_id AS TEXT), generation, updated_at FROM user_state_legacy;
+        DROP TABLE user_state_legacy;
+      `);
+      this.db.run("COMMIT");
+    } catch (err) {
+      this.db.run("ROLLBACK");
+      throw err;
+    }
   }
 
-  getUserGeneration(userId: number): number {
+  getUserGeneration(userId: string): number {
     const row = this.db
       .query("SELECT generation FROM user_state WHERE user_id = ?")
       .get(userId) as SqlRow | null;
     return rowNumber(row, "generation", 0);
   }
 
-  maxGeneration(userId: number): number {
+  maxGeneration(userId: string): number {
     const row = this.db
       .query("SELECT MAX(generation) AS max FROM sessions WHERE user_id = ?")
       .get(userId) as SqlRow | null;
     return rowNumber(row, "max", -1);
   }
 
-  bumpUserGenerationTo(userId: number, generation: number): void {
+  bumpUserGenerationTo(userId: string, generation: number): void {
     this.db.run(
       `INSERT INTO user_state (user_id, generation, updated_at) VALUES (?, ?, ?)
        ON CONFLICT(user_id) DO UPDATE SET generation = ?, updated_at = ?`,
@@ -166,7 +206,7 @@ export class AgentDatabase {
     );
   }
 
-  getOrCreateSession(sessionId: string, userId: number): AgentSessionRow {
+  getOrCreateSession(sessionId: string, userId: string): AgentSessionRow {
     const now = Date.now();
     this.db.run(
       `INSERT INTO sessions (session_id, user_id, generation, created_at, updated_at)
@@ -181,7 +221,7 @@ export class AgentDatabase {
   }
 
   getSessionByGeneration(
-    userId: number,
+    userId: string,
     generation: number,
   ): AgentSessionRow | undefined {
     const row = this.db
@@ -191,7 +231,7 @@ export class AgentDatabase {
   }
 
   listSessions(
-    userId: number,
+    userId: string,
     options: { archived?: boolean } = {},
   ): AgentSessionRow[] {
     const rows = options.archived === undefined
@@ -314,7 +354,7 @@ export class AgentDatabase {
   }
 
   /** 删除该用户的全部会话（含归档）及其消息、运行记录与工具调用明细。 */
-  clearUserSessions(userId: number): ClearSessionsResult {
+  clearUserSessions(userId: string): ClearSessionsResult {
     const ids = this.listSessions(userId).map((session) => session.sessionId);
     const result: ClearSessionsResult = {
       sessions: ids.length,
@@ -360,7 +400,7 @@ export class AgentDatabase {
     return rowNumber(row, "count", 0);
   }
 
-  startRun(sessionId: string, userId: number, model: string): number {
+  startRun(sessionId: string, userId: string, model: string): number {
     const result = this.db
       .query(
         "INSERT INTO runs (session_id, user_id, model, started_at) VALUES (?, ?, ?, ?)",
@@ -408,7 +448,7 @@ export class AgentDatabase {
       );
   }
 
-  getRunStats(userId: number): { runs: number; toolCalls: number } {
+  getRunStats(userId: string): { runs: number; toolCalls: number } {
     const runRow = this.db
       .query("SELECT COUNT(*) AS count FROM runs WHERE user_id = ?")
       .get(userId) as SqlRow | null;
@@ -449,7 +489,7 @@ function toSessionRow(row: SqlRow): AgentSessionRow {
   const sessionId = rowString(row, "session_id");
   return {
     sessionId,
-    userId: rowNumber(row, "user_id", 0),
+    userId: rowId(row, "user_id"),
     generation: rowNumber(row, "generation", parseGeneration(sessionId)),
     emotion: rowString(row, "emotion"),
     summary: rowString(row, "summary"),

package/handlers/message.ts

@@ -1,13 +1,29 @@
 import type { MessageEvent } from "mioku";
 import type { AgentHost } from "../types";
+import { identityOf } from "../core/identity";
 import { runAgentTurn } from "../core/loop";
+import { genericPlatform } from "../platforms/generic";
+import type { AgentPlatform } from "../platforms/types";
 
-export function createMessageHandler(host: AgentHost) {
-  return async (e: MessageEvent) => {
-    if (e.message_type === "group") return;
-    const userId = Number(e.user_id || e.sender?.user_id || 0);
-    if (!userId || userId === Number(e.self_id || 0)) return;
-    if (!(await host.isAllowed(userId))) return;
-    await runAgentTurn(host, e);
-  };
+/** 私聊里以命令前缀开头的消息交给命令系统，agent 不处理 */
+const COMMAND_PREFIX = /^[./~]/;
+
+/** 各平台分支共用的入口：权限/自消息过滤后进入 agent 轮次 */
+export async function handleAgentMessage(
+  host: AgentHost,
+  event: MessageEvent,
+  platform: AgentPlatform = genericPlatform,
+): Promise<void> {
+  if (event.message_type === "group") return;
+  const identity = identityOf(event);
+  if (!identity.userId || identity.userId === identity.botId) return;
+  const text = host.ctx.text(event);
+  if (COMMAND_PREFIX.test(text)) {
+    host.logger.debug(
+      `[agent] command ignored | user=${identity.userId} text=${text.slice(0, 60)}`,
+    );
+    return;
+  }
+  if (!(await host.isAllowed(identity.userId))) return;
+  await runAgentTurn(host, event, platform);
 }

package/index.ts

@@ -5,7 +5,7 @@ import { SessionManager } from "./core/session";
 import { EmotionManager } from "./core/emotion";
 import { ApprovalManager } from "./tools/approval";
 import { readChatSharedConfig } from "./core/chat-config";
-import { createMessageHandler } from "./handlers/message";
+import { registerAgentPlatforms } from "./platforms";
 import { registerCommands } from "./commands";
 import { mergeAgentConfig } from "./utils/config";
 import { workspaceRootFor } from "./tools/perm";
@@ -23,13 +23,13 @@ import type {
   ResolvedModel,
 } from "./types";
 
-function normalizeIdList(input: unknown): number[] {
+function normalizeIdList(input: unknown): string[] {
   if (!Array.isArray(input)) return [];
   return Array.from(
     new Set(
       input
-        .map((item) => Math.floor(Number(item)))
-        .filter((id) => Number.isFinite(id) && id > 0),
+        .map((item) => String(item ?? "").trim())
+        .filter((id) => id.length > 0),
     ),
   );
 }
@@ -136,18 +136,18 @@ export default definePlugin({
       getSettings: () => cachedSettings,
       getChatShared: () => readChatSharedConfig(configService),
       resolveModel,
-      workspaceRoot: (userId: number) =>
+      workspaceRoot: (userId: string) =>
         workspaceRootFor(cachedBase.workspaceDir, userId),
-      isAllowed: async (userId: number) => {
-        const owners = (ctx.config.owners ?? []).map(Number);
-        if (owners.includes(userId)) return true;
-        if (
-          cachedBase.access.allowAdmins &&
-          (ctx.config.admins ?? []).map(Number).includes(userId)
-        ) {
+      isAllowed: async (userId: string) => {
+        const target = String(userId ?? "").trim();
+        if (!target) return false;
+        const matches = (list: readonly unknown[] | undefined): boolean =>
+          (list ?? []).some((item) => String(item ?? "").trim() === target);
+        if (matches(ctx.config.owners)) return true;
+        if (cachedBase.access.allowAdmins && matches(ctx.config.admins)) {
           return true;
         }
-        return normalizeIdList(cachedBase.access.users).includes(userId);
+        return normalizeIdList(cachedBase.access.users).includes(target);
       },
       updateBase: async (patch) => {
         if (configService) {
@@ -160,7 +160,7 @@ export default definePlugin({
     };
 
     registerCommands(host);
-    ctx.handle("message", createMessageHandler(host));
+    const disposePlatforms = registerAgentPlatforms(ctx, host);
 
     const resolved = resolveModel();
     ctx.logger.info(
@@ -168,6 +168,7 @@ export default definePlugin({
     );
 
     return () => {
+      disposePlatforms();
       approvals.dispose();
       db.close();
       ctx.logger.info("agent 插件已卸载");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-agent",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "超级用户 Agent 插件",
   "main": "index.ts",
   "type": "module",

package/platforms/generic.ts

@@ -0,0 +1,11 @@
+import type { AgentPlatform } from "./types";
+import { EMPTY_FILE_LOOKUP } from "./types";
+
+/** 未单独登记的适配器(如 stdin、未来的新平台)走的兜底分支 */
+export const genericPlatform: AgentPlatform = {
+  adapter: "",
+  route: "message",
+  async resolveFile() {
+    return EMPTY_FILE_LOOKUP;
+  },
+};

package/platforms/icqq.ts

@@ -0,0 +1,47 @@
+import type { AgentPlatform, PlatformFileLookup } from "./types";
+import { EMPTY_FILE_LOOKUP, mergeFileLookup } from "./types";
+
+interface IcqqFileHolder {
+  getFileUrl?(fileId: string): Promise<string>;
+  getFileInfo?(fileId: string): Promise<{ url?: string; name?: string } | null>;
+}
+
+interface IcqqFileClient {
+  pickGroup?(groupId: string): IcqqFileHolder;
+  pickFriend?(userId: string): IcqqFileHolder;
+}
+
+/** icqq:pickGroup / pickFriend 上的 getFileInfo / getFileUrl */
+export const icqqPlatform: AgentPlatform = {
+  adapter: "icqq",
+  route: "icqq:message",
+  async resolveFile(bot, ref): Promise<PlatformFileLookup> {
+    const client = bot.as<IcqqFileClient>();
+    const holder = ref.groupId
+      ? client.pickGroup?.(ref.groupId)
+      : ref.userId
+        ? client.pickFriend?.(ref.userId)
+        : undefined;
+    if (!holder) return EMPTY_FILE_LOOKUP;
+
+    const found: PlatformFileLookup = { sources: [], names: [] };
+    if (holder.getFileInfo) {
+      try {
+        mergeFileLookup(found, await holder.getFileInfo(ref.fileId));
+      } catch {
+        // 文件不存在或无权限时继续尝试 getFileUrl
+      }
+    }
+    if (found.sources.length === 0 && holder.getFileUrl) {
+      try {
+        const url = await holder.getFileUrl(ref.fileId);
+        if (typeof url === "string" && url.trim()) {
+          found.sources.push(url.trim());
+        }
+      } catch {
+        // 调用方会回退到消息段里自带的 url/file
+      }
+    }
+    return found;
+  },
+};

package/platforms/index.ts

@@ -0,0 +1,49 @@
+import type { MessageEvent, MiokuContext } from "mioku";
+import type { AgentHost } from "../types";
+import { handleAgentMessage } from "../handlers/message";
+import { genericPlatform } from "./generic";
+import { icqqPlatform } from "./icqq";
+import { onebotv11Platform } from "./onebotv11";
+import { qqOfficialPlatform } from "./qq-official";
+import type { AgentPlatform } from "./types";
+
+/** 每个平台一个分支文件，新增平台在这里登记即可 */
+export const AGENT_PLATFORMS: readonly AgentPlatform[] = [
+  onebotv11Platform,
+  icqqPlatform,
+  qqOfficialPlatform,
+];
+
+/**
+ * 按适配器前缀路由注册平台分支：
+ * `onebotv11:message` / `icqq:message` / `qq-official:message` 各管自己的差异，
+ * 未登记的适配器由通用 `message` 分支兜底。
+ */
+export function registerAgentPlatforms(
+  ctx: MiokuContext,
+  host: AgentHost,
+): () => void {
+  const disposers: Array<() => void> = [];
+
+  for (const platform of AGENT_PLATFORMS) {
+    disposers.push(
+      ctx.handle(platform.route, (event) =>
+        handleAgentMessage(host, event as unknown as MessageEvent, platform),
+      ),
+    );
+  }
+
+  const owned = new Set(AGENT_PLATFORMS.map((platform) => platform.adapter));
+  disposers.push(
+    ctx.handle("message", (event) => {
+      const messageEvent = event as unknown as MessageEvent;
+      const adapter = String(messageEvent?.bot?.adapter ?? "");
+      if (owned.has(adapter)) return;
+      return handleAgentMessage(host, messageEvent, genericPlatform);
+    }),
+  );
+
+  return () => {
+    for (const dispose of disposers) dispose();
+  };
+}

package/platforms/onebotv11.ts

@@ -0,0 +1,40 @@
+import type { AgentPlatform, PlatformFileLookup } from "./types";
+import { EMPTY_FILE_LOOKUP, mergeFileLookup } from "./types";
+
+/** onebotv11:get_file / get_group_file_url / get_private_file_url */
+export const onebotv11Platform: AgentPlatform = {
+  adapter: "onebotv11",
+  route: "onebotv11:message",
+  async resolveFile(bot, ref): Promise<PlatformFileLookup> {
+    const attempts: Array<[string, Record<string, unknown>]> = [
+      ["get_file", { file_id: ref.fileId }],
+    ];
+    if (ref.groupId) {
+      attempts.push([
+        "get_group_file_url",
+        { group_id: ref.groupId, file_id: ref.fileId },
+      ]);
+    }
+    if (ref.userId) {
+      attempts.push([
+        "get_private_file_url",
+        { user_id: ref.userId, file_id: ref.fileId },
+      ]);
+    }
+    const found: PlatformFileLookup = { sources: [], names: [] };
+    for (const [action, params] of attempts) {
+      try {
+        mergeFileLookup(
+          found,
+          await bot.sendApi<Record<string, unknown>>(action, params),
+        );
+      } catch {
+        // 协议端不支持该 action 时继续尝试下一个
+      }
+      if (found.sources.length > 0) break;
+    }
+    return found;
+  },
+};
+
+export { EMPTY_FILE_LOOKUP };

package/platforms/qq-official.ts

@@ -0,0 +1,14 @@
+import type { AgentPlatform } from "./types";
+import { EMPTY_FILE_LOOKUP } from "./types";
+
+/**
+ * QQ 官方通道：附件事件自带公网 URL(见 adapter 的 segments.ts),
+ * 官方没有 file_id 换下载地址的公开接口,所以这里不做事。
+ */
+export const qqOfficialPlatform: AgentPlatform = {
+  adapter: "qq-official",
+  route: "qq-official:message",
+  async resolveFile() {
+    return EMPTY_FILE_LOOKUP;
+  },
+};

package/platforms/types.ts

@@ -0,0 +1,53 @@
+import type { Bot } from "mioku";
+
+/** 需要按平台换取下载地址的附件引用 */
+export interface PlatformFileRef {
+  fileId: string;
+  groupId?: string;
+  userId?: string;
+}
+
+export interface PlatformFileLookup {
+  sources: string[];
+  names: string[];
+}
+
+export const EMPTY_FILE_LOOKUP: PlatformFileLookup = { sources: [], names: [] };
+
+/** 把平台返回的原始结果合并成下载来源(各平台实现共用) */
+export const mergeFileLookup = (
+  target: PlatformFileLookup,
+  result: unknown,
+): void => {
+  if (!result || typeof result !== "object") return;
+  const record = result as Record<string, unknown>;
+  for (const key of ["url", "file", "path"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      target.sources.push(value.trim());
+    }
+  }
+  const base64 = record.base64 ?? record.data;
+  if (typeof base64 === "string" && base64.trim()) {
+    target.sources.push(`base64://${base64.trim()}`);
+  }
+  for (const key of ["file_name", "name"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim()) {
+      target.names.push(value.trim());
+    }
+  }
+};
+
+/**
+ * 一个平台分支：自己订阅 `adapter:message` 路由，自己处理平台专有差异。
+ * 新增平台只要加一个文件并登记到 `platforms/index.ts`。
+ */
+export interface AgentPlatform {
+  /** 适配器名，与 `bot.adapter` 对应 */
+  readonly adapter: string;
+  /** 该分支订阅的事件路由，如 `onebotv11:message` */
+  readonly route: string;
+  /** 平台专有的 file_id → 下载来源；没有该能力时返回空 */
+  resolveFile(bot: Bot, ref: PlatformFileRef): Promise<PlatformFileLookup>;
+}

package/tools/approval.ts

@@ -2,7 +2,7 @@ import type { AgentPermissionLevel } from "../types";
 
 export interface PendingApproval {
   id: string;
-  userId: number;
+  userId: string;
   command: string;
   cwd: string;
   level: AgentPermissionLevel;
@@ -18,7 +18,7 @@ interface PendingEntry extends PendingApproval {
 
 export class ApprovalManager {
   private pending = new Map<string, PendingEntry>();
-  private latestByUser = new Map<number, string>();
+  private latestByUser = new Map<string, string>();
   private seq = 0;
 
   create(
@@ -55,7 +55,7 @@ export class ApprovalManager {
     return true;
   }
 
-  resolveLatest(userId: number, approved: boolean): PendingApproval | null {
+  resolveLatest(userId: string, approved: boolean): PendingApproval | null {
     const id = this.latestByUser.get(userId) ?? this.latestFor(userId);
     if (!id) return null;
     const entry = this.pending.get(id);
@@ -65,13 +65,13 @@ export class ApprovalManager {
     return approval;
   }
 
-  latestByUserId(userId: number): PendingApproval | null {
+  latestByUserId(userId: string): PendingApproval | null {
     const id = this.latestByUser.get(userId) ?? this.latestFor(userId);
     const entry = id ? this.pending.get(id) : undefined;
     return entry ? this.toPending(entry) : null;
   }
 
-  cancelByUser(userId: number): number {
+  cancelByUser(userId: string): number {
     const ids = [...this.pending.values()]
       .filter((entry) => entry.userId === userId)
       .map((entry) => entry.id);
@@ -79,7 +79,7 @@ export class ApprovalManager {
     return ids.length;
   }
 
-  listByUser(userId: number): PendingApproval[] {
+  listByUser(userId: string): PendingApproval[] {
     return [...this.pending.values()]
       .filter((entry) => entry.userId === userId)
       .sort((a, b) => a.createdAt - b.createdAt)
@@ -95,7 +95,7 @@ export class ApprovalManager {
     this.latestByUser.clear();
   }
 
-  private latestFor(userId: number): string | undefined {
+  private latestFor(userId: string): string | undefined {
     let latest: PendingEntry | undefined;
     for (const entry of this.pending.values()) {
       if (entry.userId !== userId) continue;

package/tools/bash.ts

@@ -47,7 +47,7 @@ export interface BashReporter {
 }
 
 interface BashToolDeps {
-  userId: number;
+  userId: string;
   policy: FsPolicy;
   config: BashConfig;
   approvals: ApprovalManager;

package/tools/deliver.ts

@@ -8,7 +8,7 @@ import { sendImageSource, sendLocalFile } from "../core/attachment";
 interface DeliverToolDeps {
   ctx: MiokuContext;
   bot: Bot | undefined;
-  userId: number;
+  userId: string;
   policy: FsPolicy;
 }
 

package/tools/index.ts

@@ -25,7 +25,10 @@ import { assessCommandRisk } from "../core/risk";
 import type { TurnActivity } from "../core/activity";
 
 export interface TurnToolOptions {
-  userId: number;
+  /** 会话/工作区隔离键(适配器 + 平台用户 id) */
+  userId: string;
+  /** 平台原始用户 id,用于发送消息 */
+  sendUserId: string;
   bot: Bot | undefined;
   runId: number;
   reporter: BashReporter;
@@ -120,13 +123,13 @@ export function buildTurnTools(
     createSendFileTool({
       ctx: host.ctx,
       bot: options.bot,
-      userId: options.userId,
+      userId: options.sendUserId,
       policy,
     }),
     createSendImageTool({
       ctx: host.ctx,
       bot: options.bot,
-      userId: options.userId,
+      userId: options.sendUserId,
       policy,
     }),
   ];
@@ -175,6 +178,7 @@ export function buildTurnTools(
     createTodoTool({
       host,
       userId: options.userId,
+      sendUserId: options.sendUserId,
       bot: options.bot,
       quiet: isQuietMode(policy.level),
     }),

package/tools/perm.ts

@@ -19,12 +19,16 @@ export function normalizePermissionLevel(value: unknown): AgentPermissionLevel {
   return "workspace-write";
 }
 
+/** 作用域键里可能含 `:`(适配器前缀),统一替换成目录安全字符 */
+const sanitizeSegment = (value: string): string =>
+  String(value ?? "").replace(/[^A-Za-z0-9._-]+/g, "_") || "unknown";
+
 export interface FsPolicy {
   level: AgentPermissionLevel;
   workspaceRoot: string;
 }
 
-export function workspaceRootFor(baseDir: string, userId: number): string {
+export function workspaceRootFor(baseDir: string, userId: string): string {
   const raw = String(baseDir ?? "").trim();
   const base =
     raw && path.isAbsolute(raw)
@@ -33,7 +37,7 @@ export function workspaceRootFor(baseDir: string, userId: number): string {
           process.cwd(),
           raw || path.join("data", "agent", "workspace"),
         );
-  return path.resolve(base, String(userId));
+  return path.resolve(base, sanitizeSegment(userId));
 }
 
 export function resolveWorkspacePath(policy: FsPolicy, target: string): string {

package/tools/todo.ts

@@ -38,12 +38,15 @@ export function formatPlanText(items: SessionPlanItem[]): string {
 
 export function createTodoTool(options: {
   host: AgentHost;
-  userId: number;
+  /** 会话隔离键 */
+  userId: string;
+  /** 平台原始用户 id,用于推送 */
+  sendUserId: string;
   bot: Bot | undefined;
   /** yolo 模式：不推送清单，用户只看最终回复 */
   quiet?: boolean;
 }): AITool {
-  const { host, userId, bot, quiet } = options;
+  const { host, userId, sendUserId, bot, quiet } = options;
   return {
     name: "todo_write",
     description: DESCRIPTION,
@@ -114,7 +117,7 @@ export function createTodoTool(options: {
       if (bot && !quiet) {
         await bot
           .sendMessage(
-            { type: "private", user_id: userId },
+            { type: "private", user_id: sendUserId },
             [host.ctx.segment.text(formatPlanText(items))],
           )
           .catch((err) =>

package/types.ts

@@ -19,7 +19,7 @@ export type AgentPermissionLevel =
 
 export interface AgentAccessConfig {
   allowAdmins: boolean;
-  users: number[];
+  users: string[];
 }
 
 export interface AgentBaseConfig {
@@ -104,8 +104,8 @@ export interface AgentHost {
   getSettings(): AgentSettingsConfig;
   getChatShared(): Promise<ChatSharedConfig>;
   resolveModel(): ResolvedModel | null;
-  workspaceRoot(userId: number): string;
-  isAllowed(userId: number): Promise<boolean>;
+  workspaceRoot(userId: string): string;
+  isAllowed(userId: string): Promise<boolean>;
   updateBase(patch: Partial<AgentBaseConfig>): Promise<void>;
   logger: MiokuContext["logger"];
 }