@downcity/agent 1.1.25 → 1.1.35

package/src/plugin/builtins/asr/Plugin.ts

@@ -7,9 +7,11 @@
  * - 当前作为 chat 入站消息增强中间件接入语音转写。
  */
 
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type { VoicePluginConfig } from "@/plugin/builtins/voice/types/VoicePlugin.js";
-import { CHAT_PLUGIN_POINTS } from "@/service/builtins/chat/runtime/PluginPoints.js";
+import { CHAT_PLUGIN_POINTS } from "@/plugin/builtins/chat/runtime/PluginPoints.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import {
   listVoiceModels,
@@ -31,11 +33,9 @@ import {
   writeVoiceTranscriberConfig,
 } from "@/plugin/builtins/asr/Dependency.js";
 
-/**
- * asrPlugin：声明式插件定义。
- */
-export const asrPlugin: Plugin = {
-  name: "asr",
+function createAsrPluginDefinition(plugin: Plugin): Plugin {
+  return {
+    name: "asr",
   title: "Automatic Speech Recognition",
   description:
     "Detects voice and audio attachments in inbound chat messages, runs transcription through the configured ASR dependency, and appends readable text so the agent can work with spoken input like normal message content.",
@@ -113,7 +113,7 @@ export const asrPlugin: Plugin = {
     statusAction: "status",
   },
   async availability(context) {
-    if (!isPluginEnabled({ plugin: asrPlugin, context })) {
+    if (!isPluginEnabled({ plugin, context })) {
       return {
         enabled: false,
         available: false,
@@ -147,7 +147,7 @@ export const asrPlugin: Plugin = {
       },
       execute: async ({ context }) => {
         const config = readVoicePluginConfig(context);
-        const availability = await asrPlugin.availability!(context);
+        const availability = await plugin.availability!(context);
         const transcriberConfig = readVoiceTranscriberConfig(context);
         return {
           success: true,
@@ -401,7 +401,7 @@ export const asrPlugin: Plugin = {
         },
       },
       execute: async ({ context, payload }) => {
-        const pluginStatus = await asrPlugin.availability!(context);
+        const pluginStatus = await plugin.availability!(context);
         if (!pluginStatus.enabled || !pluginStatus.available) {
           return {
             success: false,
@@ -450,7 +450,7 @@ export const asrPlugin: Plugin = {
         },
       },
       execute: async ({ context }) => {
-        const availability = await asrPlugin.availability!(context);
+        const availability = await plugin.availability!(context);
         const dependencyStatus = await checkVoiceTranscriber(context);
         return {
           success: true,
@@ -477,7 +477,7 @@ export const asrPlugin: Plugin = {
   },
   system(context) {
     const config = readVoicePluginConfig(context);
-    if (!isPluginEnabled({ plugin: asrPlugin, context }) || config.injectPrompt !== true) {
+    if (!isPluginEnabled({ plugin, context }) || config.injectPrompt !== true) {
       return "";
     }
     return [
@@ -485,4 +485,17 @@ export const asrPlugin: Plugin = {
       "Audio attachments may be transcribed before agent execution.",
     ].join("\n");
   },
-};
+  };
+}
+
+/**
+ * AsrPlugin：语音识别插件。
+ */
+export class AsrPlugin extends BasePlugin {
+  readonly name = "asr";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createAsrPluginDefinition(this));
+  }
+}

package/src/plugin/builtins/auth/Plugin.ts

@@ -7,9 +7,11 @@
  * - auth plugin 只负责统一暴露扩展点 / action 边界，不改变底层存储模型。
  */
 
+import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type { JsonValue } from "@/types/common/Json.js";
-import { CHAT_PLUGIN_POINTS } from "@/service/builtins/chat/runtime/PluginPoints.js";
+import { CHAT_PLUGIN_POINTS } from "@/plugin/builtins/chat/runtime/PluginPoints.js";
 import {
   AUTH_ACTIONS,
   type AuthObservePrincipalPayload,
@@ -32,7 +34,7 @@ import {
   readAuthorizationSnapshot,
   recordObservedAuthorizationPrincipal,
 } from "@/plugin/builtins/auth/runtime/AuthorizationStore.js";
-import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
+import type { ChatDispatchChannel } from "@/plugin/builtins/chat/types/ChatDispatcher.js";
 
 function toChannel(value: unknown): ChatDispatchChannel | null {
   const text = String(value || "").trim().toLowerCase();
@@ -68,11 +70,9 @@ function toSnapshotData(snapshot: ChatAuthorizationSnapshot): JsonValue {
   };
 }
 
-/**
- * authPlugin：统一承载授权能力。
- */
-export const authPlugin: Plugin = {
-  name: "auth",
+function createAuthPluginDefinition(): Plugin {
+  return {
+    name: "auth",
   title: "User Authorization System",
   description:
     "Controls who can talk to the agent in chat channels, records observed users and chats, and resolves each user's effective role for downstream service decisions.",
@@ -206,4 +206,17 @@ export const authPlugin: Plugin = {
       },
     },
   },
-};
+  };
+}
+
+/**
+ * AuthPlugin：统一承载授权能力。
+ */
+export class AuthPlugin extends BasePlugin {
+  readonly name = "auth";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createAuthPluginDefinition());
+  }
+}

package/src/plugin/builtins/auth/runtime/AuthorizationStore.ts

@@ -15,7 +15,7 @@ import type {
   ChatAuthorizationStateFile,
 } from "@/plugin/builtins/auth/types/AuthPlugin.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
+import type { ChatDispatchChannel } from "@/plugin/builtins/chat/types/ChatDispatcher.js";
 
 function getAuthorizationStatePath(rootPath: string): string {
   return path.join(rootPath, ".downcity", "chat", "authorization", "state.json");

package/src/plugin/builtins/auth/types/AuthPlugin.ts

@@ -7,8 +7,8 @@
  * - chat / console / plugin 执行链路都从这里共享同一份边界定义。
  */
 
-import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
-import { CHAT_PLUGIN_POINTS } from "@/service/builtins/chat/runtime/PluginPoints.js";
+import type { ChatDispatchChannel } from "@/plugin/builtins/chat/types/ChatDispatcher.js";
+import { CHAT_PLUGIN_POINTS } from "@/plugin/builtins/chat/runtime/PluginPoints.js";
 
 /**
  * auth plugin 稳定名称。

package/src/plugin/builtins/chat/Action.ts

@@ -0,0 +1,477 @@
+/**
+ * Chat command services.
+ *
+ * 关键点（中文）
+ * - chat 语义（chatKey 与 sessionId 映射）统一收口在本模块
+ * - 通过 SessionRunScope（ALS）读取当前请求上下文
+ */
+
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import { getSessionRunScope } from "@executor/SessionRunScope.js";
+import {
+  sendActionByChatKey,
+  sendTextByChatKey,
+} from "./runtime/ChatkeySend.js";
+import { deleteChatSessionById } from "./runtime/ChatSessionDelete.js";
+import type { ChatDispatchAction } from "./types/ChatDispatcher.js";
+import type {
+  ChatSessionSnapshot,
+  ChatDeleteResponse,
+  ChatReactResponse,
+  ChatSendResponse,
+} from "./types/ChatCommand.js";
+
+/**
+ * 读取字符串环境变量。
+ *
+ * 关键点（中文）
+ * - 自动 trim；空字符串视为未设置。
+ */
+function readEnvString(name: string): string | undefined {
+  const value = String(process.env[name] || "").trim();
+  return value ? value : undefined;
+}
+
+/**
+ * 读取数字环境变量。
+ *
+ * 关键点（中文）
+ * - 解析失败返回 undefined，不抛错。
+ */
+function readEnvNumber(name: string): number | undefined {
+  const raw = readEnvString(name);
+  if (!raw) return undefined;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed)) return undefined;
+  return parsed;
+}
+
+/**
+ * 解析 chat 上下文快照。
+ *
+ * 优先级（中文）
+ * 1) 显式参数
+ * 2) SessionRunScope（ALS）
+ * 3) 环境变量回退
+ */
+export function resolveChatSessionSnapshot(input?: {
+  sessionId?: string;
+  chatKey?: string;
+  context?: AgentContext;
+}): ChatSessionSnapshot {
+  const requestCtx = getSessionRunScope();
+
+  const explicitSessionId = String(input?.sessionId || "").trim();
+  const explicitChatKey = String(input?.chatKey || "").trim();
+  const requestSessionId =
+    typeof requestCtx?.sessionId === "string" && requestCtx.sessionId.trim()
+      ? requestCtx.sessionId.trim()
+      : undefined;
+  const envSessionId = readEnvString("DC_SESSION_ID");
+  const envChatKey = readEnvString("DC_CTX_CHAT_KEY");
+  const channel = readEnvString("DC_CTX_CHANNEL") || undefined;
+  const chatId =
+    readEnvString("DC_CTX_TARGET_ID") || readEnvString("DC_CTX_CHAT_ID");
+  const messageThreadId =
+    readEnvNumber("DC_CTX_THREAD_ID") ||
+    readEnvNumber("DC_CTX_MESSAGE_THREAD_ID");
+  const chatType =
+    readEnvString("DC_CTX_TARGET_TYPE") ||
+    readEnvString("DC_CTX_CHAT_TYPE");
+  const userId =
+    readEnvString("DC_CTX_ACTOR_ID") ||
+    readEnvString("DC_CTX_USER_ID");
+  const messageId = readEnvString("DC_CTX_MESSAGE_ID");
+  const sessionId =
+    explicitSessionId ||
+    requestSessionId ||
+    envSessionId ||
+    explicitChatKey ||
+    envChatKey;
+  const chatKey =
+    explicitChatKey ||
+    mapSessionIdToChatKey(sessionId) ||
+    envChatKey;
+
+  const snapshot: ChatSessionSnapshot = {
+    ...(sessionId ? { sessionId } : {}),
+    ...(chatKey ? { chatKey } : {}),
+    channel,
+    chatId,
+    messageThreadId,
+    chatType,
+    userId,
+    messageId,
+  };
+
+  return snapshot;
+}
+
+/**
+ * 将 sessionId 映射为可发送的 chatKey。
+ *
+ * 关键点（中文）
+ * - 当前实现下：chat plugin runtime 内部把 sessionId 视作可发送 chatKey。
+ * - 不再依赖字符串规则推导（sessionId 可为随机值）。
+ */
+export function mapSessionIdToChatKey(sessionId?: string): string | undefined {
+  const key = String(sessionId || "").trim();
+  if (!key) return undefined;
+  return key;
+}
+
+/**
+ * 提取最终 sessionId。
+ */
+export function resolveSessionId(input?: {
+  sessionId?: string;
+  chatKey?: string;
+  context?: AgentContext;
+}): string | undefined {
+  const snapshot = resolveChatSessionSnapshot({
+    sessionId: input?.sessionId,
+    chatKey: input?.chatKey,
+    context: input?.context,
+  });
+  const key = String(snapshot.sessionId || "").trim();
+  return key ? key : undefined;
+}
+
+/**
+ * 提取最终 chatKey（用于发送路径）。
+ */
+export function resolveChatKey(input?: {
+  chatKey?: string;
+  sessionId?: string;
+  context?: AgentContext;
+}): string | undefined {
+  const snapshot = resolveChatSessionSnapshot({
+    chatKey: input?.chatKey,
+    sessionId: input?.sessionId,
+    context: input?.context,
+  });
+  const key = String(snapshot.chatKey || "").trim();
+  return key ? key : undefined;
+}
+
+/**
+ * 解析当前发送应绑定的 reply messageId。
+ *
+ * 关键点（中文）
+ * - 只有显式 reply 且未手动传入 messageId 时才尝试补全。
+ * - 仅在目标 chatKey 与当前请求上下文一致时，才复用 `DC_CTX_MESSAGE_ID` / ALS 快照。
+ * - 这样可把一次 run 固定到触发它的那条消息，避免处理中被后续新消息覆盖。
+ */
+function resolveReplyMessageIdForChatSend(params: {
+  chatKey: string;
+  context: AgentContext;
+  replyToMessage: boolean;
+  explicitMessageId?: string;
+}): string | undefined {
+  const explicitMessageId =
+    typeof params.explicitMessageId === "string" && params.explicitMessageId.trim()
+      ? params.explicitMessageId.trim()
+      : undefined;
+  if (explicitMessageId) return explicitMessageId;
+  if (params.replyToMessage !== true) return undefined;
+
+  const snapshot = resolveChatSessionSnapshot({
+    context: params.context,
+  });
+  const snapshotChatKey = String(snapshot.chatKey || "").trim();
+  const snapshotMessageId = String(snapshot.messageId || "").trim();
+  if (!snapshotChatKey || !snapshotMessageId) return undefined;
+  return snapshotChatKey === params.chatKey ? snapshotMessageId : undefined;
+}
+
+/**
+ * 规范化 `chat send` 文本。
+ *
+ * 关键点（中文）
+ * - 当文本只包含字面量转义（如 `\n`）且没有真实换行时，自动解码为真实控制字符。
+ * - 这样可兼容模型/脚本把多行文本写成 `\\n` 的场景，避免用户看到原样 `\n`。
+ */
+export function normalizeChatSendText(raw: string): string {
+  const text = String(raw ?? "");
+  if (!text) return text;
+
+  const hasRealLineBreak = text.includes("\n") || text.includes("\r");
+  let normalized = text;
+
+  if (
+    !hasRealLineBreak &&
+    (text.includes("\\n") || text.includes("\\r") || text.includes("\\t"))
+  ) {
+    normalized = text
+      .replace(/\\r\\n/g, "\n")
+      .replace(/\\n/g, "\n")
+      .replace(/\\r/g, "\r")
+      .replace(/\\t/g, "\t");
+  }
+
+  return normalized;
+}
+
+/**
+ * 发送前延迟。
+ *
+ * 关键点（中文）
+ * - 支持延迟毫秒（delayMs）或绝对时间（sendAtMs）
+ * - 超长等待按分片 setTimeout，避免超出 Node 单次定时器上限
+ */
+function resolveTargetWaitMs(params: {
+  delayMs: number;
+  sendAtMs?: number;
+}): number {
+  const delayMs = params.delayMs;
+  const sendAtMs = params.sendAtMs;
+  const rawWaitMs =
+    typeof sendAtMs === "number" ? Math.max(0, sendAtMs - Date.now()) : delayMs;
+  if (!Number.isFinite(rawWaitMs) || Number.isNaN(rawWaitMs) || rawWaitMs <= 0) return 0;
+  return Math.trunc(rawWaitMs);
+}
+
+async function waitByTimeoutChunks(waitMs: number): Promise<void> {
+  if (!Number.isFinite(waitMs) || Number.isNaN(waitMs) || waitMs <= 0) return;
+  const MAX_TIMEOUT_MS = 2_147_483_647;
+  let remaining = Math.trunc(waitMs);
+  while (remaining > 0) {
+    const chunk = Math.min(remaining, MAX_TIMEOUT_MS);
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, chunk);
+    });
+    remaining -= chunk;
+  }
+}
+
+async function waitBeforeSend(params: {
+  delayMs: number;
+  sendAtMs?: number;
+}): Promise<void> {
+  await waitByTimeoutChunks(resolveTargetWaitMs(params));
+}
+
+/**
+ * 按 chatKey 发送文本。
+ *
+ * 关键点（中文）
+ * - chat plugin runtime 不关心具体平台；由 runtime sender 做 channel 分发。
+ * - 返回统一结构，便于上层链路做可观测与错误汇总。
+ */
+export async function sendChatTextByChatKey(params: {
+  context: AgentContext;
+  chatKey: string;
+  text: string;
+  delayMs?: number;
+  sendAtMs?: number;
+  /**
+   * 延迟发送是否异步调度（不阻塞当前调用）。
+   *
+   * 关键点（中文）
+   * - 仅在存在有效 delay/sendAt 时生效。
+   * - 默认 false，保持 CLI/API 的阻塞行为不变。
+   */
+  nonBlockingDelay?: boolean;
+  replyToMessage?: boolean;
+  messageId?: string;
+}): Promise<ChatSendResponse> {
+  const chatKey = String(params.chatKey || "").trim();
+  const text = normalizeChatSendText(String(params.text ?? ""));
+  const delayMs =
+    typeof params.delayMs === "number" && Number.isFinite(params.delayMs)
+      ? Math.max(0, Math.trunc(params.delayMs))
+      : 0;
+  const sendAtMs =
+    typeof params.sendAtMs === "number" && Number.isFinite(params.sendAtMs)
+      ? Math.max(0, Math.trunc(params.sendAtMs))
+      : undefined;
+  if (!chatKey) {
+    return {
+      success: false,
+      error: "Missing chatKey",
+    };
+  }
+  if (delayMs > 0 && typeof sendAtMs === "number") {
+    return {
+      success: false,
+      chatKey,
+      error: "delayMs and sendAtMs cannot be used together",
+    };
+  }
+
+  const replyToMessage = params.replyToMessage === true;
+  const messageId = resolveReplyMessageIdForChatSend({
+    context: params.context,
+    chatKey,
+    replyToMessage,
+    explicitMessageId: params.messageId,
+  });
+  const targetWaitMs = resolveTargetWaitMs({ delayMs, sendAtMs });
+  if (params.nonBlockingDelay === true && targetWaitMs > 0) {
+    // 关键点（中文）：异步调度延迟发送，让调用方可立即结束当前 run。
+    void (async () => {
+      try {
+        await waitByTimeoutChunks(targetWaitMs);
+        const delayed = await sendTextByChatKey({
+          context: params.context,
+          chatKey,
+          text,
+          replyToMessage,
+          ...(messageId ? { messageId } : {}),
+        });
+        if (!delayed.success) {
+          params.context.logger.warn("Delayed chat send failed", {
+            chatKey,
+            error: delayed.error || "chat send failed",
+          });
+        }
+      } catch (error) {
+        params.context.logger.warn("Delayed chat send failed", {
+          chatKey,
+          error: String(error),
+        });
+      }
+    })();
+    return {
+      success: true,
+      chatKey,
+    };
+  }
+
+  await waitBeforeSend({ delayMs, sendAtMs });
+
+  const result = await sendTextByChatKey({
+    context: params.context,
+    chatKey,
+    text,
+    replyToMessage,
+    ...(messageId ? { messageId } : {}),
+  });
+  return {
+    success: Boolean(result.success),
+    chatKey,
+    ...(result.success ? {} : { error: result.error || "chat send failed" }),
+  };
+}
+
+/**
+ * 按 chatKey 发送平台动作（typing/react）。
+ *
+ * 关键点（中文）
+ * - 动作分发与文本发送复用同一 chatKey 解析与 channel dispatcher。
+ */
+export async function sendChatActionByChatKey(params: {
+  context: AgentContext;
+  chatKey: string;
+  action: ChatDispatchAction;
+  messageId?: string;
+  reactionEmoji?: string;
+  reactionIsBig?: boolean;
+}): Promise<ChatReactResponse> {
+  const chatKey = String(params.chatKey || "").trim();
+  if (!chatKey) {
+    return {
+      success: false,
+      error: "Missing chatKey",
+    };
+  }
+
+  const result = await sendActionByChatKey({
+    context: params.context,
+    chatKey,
+    action: params.action,
+    messageId: params.messageId,
+    reactionEmoji: params.reactionEmoji,
+    reactionIsBig: params.reactionIsBig,
+  });
+  const messageId = String(params.messageId || "").trim();
+  return {
+    success: Boolean(result.success),
+    chatKey,
+    ...(messageId ? { messageId } : {}),
+    ...(result.success ? {} : { error: result.error || "chat action failed" }),
+  };
+}
+
+/**
+ * 按 sessionId 发送文本。
+ *
+ * 关键点（中文）
+ * - sessionId -> chatKey 映射关系只在 chat plugin runtime 内部维护。
+ */
+export async function sendChatTextBySessionId(params: {
+  context: AgentContext;
+  sessionId: string;
+  text: string;
+  delayMs?: number;
+  sendAtMs?: number;
+  replyToMessage?: boolean;
+  messageId?: string;
+}): Promise<{ success: boolean; sessionId: string; error?: string }> {
+  const sessionId = String(params.sessionId || "").trim();
+  if (!sessionId) {
+    return {
+      success: false,
+      sessionId: "",
+      error: "Missing sessionId",
+    };
+  }
+
+  const result = await sendChatTextByChatKey({
+    context: params.context,
+    chatKey: sessionId,
+    text: params.text,
+    delayMs: params.delayMs,
+    sendAtMs: params.sendAtMs,
+    replyToMessage: params.replyToMessage === true,
+    ...(typeof params.messageId === "string" && params.messageId.trim()
+      ? { messageId: params.messageId.trim() }
+      : {}),
+  });
+  return {
+    success: Boolean(result.success),
+    sessionId,
+    ...(result.success ? {} : { error: result.error || "chat send failed" }),
+  };
+}
+
+/**
+ * 按 chatKey/sessionId 彻底删除 chat 会话。
+ *
+ * 关键点（中文）
+ * - chatKey 与 sessionId 在 chat plugin runtime 内部等价使用。
+ * - 删除包含：路由映射 + chat 审计目录 + session 目录 + 渠道状态清理。
+ */
+export async function deleteChatByChatKey(params: {
+  context: AgentContext;
+  chatKey?: string;
+  sessionId?: string;
+}): Promise<ChatDeleteResponse> {
+  const chatKey = resolveChatKey({
+    context: params.context,
+    chatKey: params.chatKey,
+    sessionId: params.sessionId,
+  });
+  const sessionId = String(chatKey || "").trim();
+  if (!sessionId) {
+    return {
+      success: false,
+      error:
+        "Missing chatKey/sessionId. Provide --chat-key or --session-id, or ensure DC_CTX_CHAT_KEY/DC_SESSION_ID is injected.",
+    };
+  }
+
+  const result = await deleteChatSessionById({
+    context: params.context,
+    sessionId,
+  });
+  return {
+    success: result.success,
+    sessionId: result.sessionId,
+    deleted: result.deleted,
+    removedMeta: result.removedMeta,
+    removedChatDir: result.removedChatDir,
+    removedSessionDir: result.removedSessionDir,
+    ...(result.success ? {} : { error: result.error || "chat delete failed" }),
+  };
+}