@downcity/plugins 1.0.173 → 1.0.193

package/src/chat/runtime/ChatPluginActionRegistry.ts

@@ -12,14 +12,11 @@ import type { PluginActions } from "@downcity/agent";
 import { createAction } from "@downcity/agent";
 import { z } from "zod";
 import type {
-  ChatCloseActionPayload,
-  ChatConfigurationActionPayload,
-  ChatConfigureActionPayload,
   ChatDeleteActionPayload,
   ChatHistoryActionPayload,
+  ChatHistoryClearActionPayload,
   ChatInfoActionPayload,
   ChatListActionPayload,
-  ChatOpenActionPayload,
   ChatReactActionPayload,
   ChatReconnectActionPayload,
   ChatSendActionPayload,
@@ -30,7 +27,6 @@ import type {
 import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
 import {
   mapChatChannelCommandInput,
-  mapChatConfigureCommandInput,
   mapChatDeleteCommandInput,
   mapChatHistoryCommandInput,
   mapChatInfoCommandInput,
@@ -46,12 +42,9 @@ import {
   executeChatListAction,
   executeChatReactAction,
   executeChatSendAction,
+  execute_chat_history_clear_action,
 } from "./ChatActionExecution.js";
 import {
-  executeChatCloseAction,
-  executeChatConfigurationAction,
-  executeChatConfigureAction,
-  executeChatOpenAction,
   executeChatReconnectAction,
   executeChatStatusAction,
   executeChatTestAction,
@@ -166,95 +159,6 @@ export function createChatPluginActions(params: {
         });
       },
     }),
-    open: createAction({
-      description: "Open and enable the specified chat channel.",
-      input_schema: {
-        zod: z.object({}).passthrough(),
-        json_schema: { type: "object", properties: {}, additionalProperties: true },
-      },
-      command: {
-        description: "Open chat channel (enabled=true, and start it if configured).",
-        configure(command: Command) {
-          command.option("--channel <name>", "Specify channel (telegram|feishu|qq).");
-        },
-        mapInput: mapChatChannelCommandInput,
-      },
-      execute: async (actionParams) => {
-        return executeChatOpenAction({
-          state: params.channelState,
-          context: actionParams.context,
-          payload: actionParams.input as ChatOpenActionPayload,
-        });
-      },
-    }),
-    close: createAction({
-      description: "Close and disable the specified chat channel.",
-      input_schema: {
-        zod: z.object({}).passthrough(),
-        json_schema: { type: "object", properties: {}, additionalProperties: true },
-      },
-      command: {
-        description: "Close chat channel (enabled=false and stop runtime).",
-        configure(command: Command) {
-          command.option("--channel <name>", "Specify channel (telegram|feishu|qq).");
-        },
-        mapInput: mapChatChannelCommandInput,
-      },
-      execute: async (actionParams) => {
-        return executeChatCloseAction({
-          state: params.channelState,
-          context: actionParams.context,
-          payload: actionParams.input as ChatCloseActionPayload,
-        });
-      },
-    }),
-    configuration: createAction({
-      description: "View chat channel configuration metadata.",
-      input_schema: {
-        zod: z.object({}).passthrough(),
-        json_schema: { type: "object", properties: {}, additionalProperties: true },
-      },
-      command: {
-        description: "View chat channel configuration metadata (fields, types, descriptions).",
-        configure(command: Command) {
-          command.option("--channel <name>", "Specify channel (telegram|feishu|qq).");
-        },
-        mapInput: mapChatChannelCommandInput,
-      },
-      execute: async (actionParams) => {
-        return executeChatConfigurationAction({
-          context: actionParams.context,
-          payload: actionParams.input as ChatConfigurationActionPayload,
-        });
-      },
-    }),
-    configure: createAction({
-      description: "Update runtime parameters for a chat channel.",
-      input_schema: {
-        zod: z.object({}).passthrough(),
-        json_schema: { type: "object", properties: {}, additionalProperties: true },
-      },
-      command: {
-        description: "Update runtime parameters for a chat channel, optionally restarting it immediately.",
-        configure(command: Command) {
-          command
-            .requiredOption("--channel <name>", "Specify channel (telegram|feishu|qq).")
-            .requiredOption(
-              "--config-json <json>",
-              "Configuration patch JSON, for example '{\"channelAccountId\":\"qq-main\",\"enabled\":true}'.",
-            )
-            .option("--restart", "Restart the channel immediately after configuration.", false);
-        },
-        mapInput: mapChatConfigureCommandInput,
-      },
-      execute: async (actionParams) => {
-        return executeChatConfigureAction({
-          state: params.channelState,
-          context: actionParams.context,
-          payload: actionParams.input as ChatConfigureActionPayload,
-        });
-      },
-    }),
     list: createAction({
       description: "List chat conversations recorded by the current agent.",
       input_schema: {
@@ -297,6 +201,7 @@ export function createChatPluginActions(params: {
         return executeChatInfoAction({
           context: actionParams.context,
           payload: actionParams.input as ChatInfoActionPayload,
+          run_context: actionParams.run_context,
         });
       },
     }),
@@ -327,6 +232,7 @@ export function createChatPluginActions(params: {
         return executeChatSendAction({
           context: actionParams.context,
           payload: actionParams.input as ChatSendActionPayload,
+          run_context: actionParams.run_context,
         });
       },
     }),
@@ -355,6 +261,7 @@ export function createChatPluginActions(params: {
         return executeChatReactAction({
           context: actionParams.context,
           payload: actionParams.input as ChatReactActionPayload,
+          run_context: actionParams.run_context,
         });
       },
     }),
@@ -381,6 +288,7 @@ export function createChatPluginActions(params: {
         return executeChatContextAction({
           context: actionParams.context,
           payload: actionParams.input as ChatSessionActionPayload,
+          run_context: actionParams.run_context,
         });
       },
     }),
@@ -403,6 +311,7 @@ export function createChatPluginActions(params: {
         return executeChatDeleteAction({
           context: actionParams.context,
           payload: actionParams.input as ChatDeleteActionPayload,
+          run_context: actionParams.run_context,
         });
       },
     }),
@@ -432,6 +341,25 @@ export function createChatPluginActions(params: {
         return executeChatHistoryAction({
           context: actionParams.context,
           payload: actionParams.input as ChatHistoryActionPayload,
+          run_context: actionParams.run_context,
+        });
+      },
+    }),
+    history_clear: createAction({
+      description: "Clear the Chat Plugin event history for one Session.",
+      input_schema: {
+        zod: z.object({ sessionId: z.string().min(1) }),
+        json_schema: {
+          type: "object",
+          properties: { sessionId: { type: "string" } },
+          required: ["sessionId"],
+          additionalProperties: false,
+        },
+      },
+      execute: async (actionParams) => {
+        return await execute_chat_history_clear_action({
+          context: actionParams.context,
+          payload: actionParams.input as unknown as ChatHistoryClearActionPayload,
         });
       },
     }),

package/src/chat/runtime/ChatPluginSystem.ts

@@ -7,6 +7,7 @@
  * - 该模块只负责 prompt 解析与拼装，不承担运行态控制职责。
  */
 import type { AgentContext } from "@downcity/agent";
+import type { PluginRunContext } from "@downcity/agent";
 import {
   buildCurrentChatEnvironmentPrompt,
   resolveCurrentChatEnvironmentPromptInput,
@@ -42,8 +43,12 @@ function resolveCurrentChatPromptChannel(
  */
 export async function buildCurrentChannelPrompts(
   context: AgentContext,
+  run_context?: PluginRunContext,
 ): Promise<string[]> {
-  const chatEnvironment = await resolveCurrentChatEnvironmentPromptInput(context);
+  const chatEnvironment = await resolveCurrentChatEnvironmentPromptInput(
+    context,
+    run_context,
+  );
   if (!chatEnvironment) return [];
   const channel = resolveCurrentChatPromptChannel(
     String(chatEnvironment.channel || "")
@@ -59,11 +64,12 @@ export async function buildCurrentChannelPrompts(
  */
 export async function buildChatPluginSystem(
   context: AgentContext,
+  run_context?: PluginRunContext,
 ): Promise<string> {
   return [
     CHAT_PLUGIN_PROMPT,
-    await buildCurrentChatEnvironmentPrompt(context),
-    ...(await buildCurrentChannelPrompts(context)),
+    await buildCurrentChatEnvironmentPrompt(context, run_context),
+    ...(await buildCurrentChannelPrompts(context, run_context)),
   ]
     .filter(Boolean)
     .join("\n\n");

package/src/chat/runtime/ChatQueueStore.ts

@@ -171,11 +171,11 @@ export function getSharedChatQueueStore(): ChatQueueStore {
  * 从运行时解析 chat queue store。
  *
  * 关键点（中文）
- * - 新路径优先读取 `context.pluginInstances.chat.queueStore`。
+ * - 新路径优先读取当前 Agent 注册的 ChatPlugin 实例。
  * - 迁移阶段若拿不到，则回退到共享 queue store，保证旧入口可继续工作。
  */
 export function resolveChatQueueStore(context?: AgentContext): ChatQueueStorePort {
-  const chatService = context?.pluginInstances?.get?.("chat") as
+  const chatService = context?.plugins.get("chat") as
     | { queueStore?: ChatQueueStorePort }
     | undefined;
   if (chatService?.queueStore) {

package/src/chat/runtime/ChatQueueWorker.ts

@@ -466,6 +466,6 @@ export class ChatQueueWorker {
    * - 在使用点显式校验，避免隐藏依赖来源。
    */
   private requireContext(sessionId: string) {
-    return this.context.session.get(sessionId);
+    return this.context.sessions.runtime(sessionId);
   }
 }

package/src/chat/runtime/ChatSessionDelete.ts

@@ -8,11 +8,9 @@
  * - 清理运行中 agent 与队列，避免残留任务继续执行
  */
 
-import fs from "fs-extra";
-import path from "node:path";
 import type { AgentContext } from "@downcity/agent";
 import { resolveChatQueueStore } from "@/chat/runtime/ChatQueue.js";
-import { removeChatMetaBySessionId } from "@/chat/runtime/ChatMetaStore.js";
+import { clean_chat_storage } from "@/chat/runtime/ChatStorage.js";
 
 function normalizeSessionId(sessionId: string): string {
   return String(sessionId || "").trim();
@@ -53,32 +51,24 @@ export async function deleteChatSessionById(params: {
     // 关键点（中文）：先停执行，再删文件，避免删除过程中仍有任务写入。
     resolveChatQueueStore(params.context).clear(sessionId);
 
-    const removedMetaResult = await removeChatMetaBySessionId({
-      context: params.context,
-      sessionId,
+    const chat_result = await clean_chat_storage({
+      root_path: params.context.rootPath,
+      session_id: sessionId,
     });
-
-    const chatDir = path.join(params.context.rootPath, ".downcity", "chat", sessionId);
-    const sessionDir = params.context.paths.getDowncitySessionDirPath(sessionId);
-    const hadChatDir = await fs.pathExists(chatDir);
-    const hadSessionDir = await fs.pathExists(sessionDir);
-    if (hadChatDir) {
-      await fs.remove(chatDir);
-    }
-    if (hadSessionDir) {
-      await fs.remove(sessionDir);
-    }
+    const removed_session_dir = await params.context.sessions.remove(sessionId);
 
     const deleted =
-      removedMetaResult.removed || hadChatDir || hadSessionDir;
+      chat_result.removed_route ||
+      chat_result.removed_chat_dir ||
+      removed_session_dir;
 
     return {
       success: true,
       sessionId,
       deleted,
-      removedMeta: removedMetaResult.removed,
-      removedChatDir: hadChatDir,
-      removedSessionDir: hadSessionDir,
+      removedMeta: chat_result.removed_route,
+      removedChatDir: chat_result.removed_chat_dir,
+      removedSessionDir: removed_session_dir,
     };
   } catch (error) {
     return {

package/src/chat/runtime/ChatStorage.ts

@@ -0,0 +1,203 @@
+/**
+ * Chat Plugin 存储路径与离线维护能力。
+ *
+ * 关键点（中文）
+ * - Chat Plugin 是 channel meta、chat history 与渠道缓存路径的唯一所有者。
+ * - AgentContext 只提供项目根目录，不暴露任何 Chat 领域路径。
+ * - CLI 离线维护通过本模块操作 Chat 存储，不复制内部 JSON 结构。
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import type {
+  ChatStorageCleanInput,
+  ChatStorageCleanResult,
+} from "@/chat/types/ChatStorage.js";
+import type {
+  ChannelContextMetaFileV1,
+  ChannelContextRouteV1,
+} from "@/chat/types/ChannelContext.js";
+
+function normalize_text(input: unknown): string {
+  return String(input || "").trim();
+}
+
+function normalize_thread_id(input: unknown): number | undefined {
+  const value = Number(input);
+  if (!Number.isFinite(value) || value <= 0) return undefined;
+  return Math.trunc(value);
+}
+
+function get_downcity_path(root_path: string): string {
+  return path.join(root_path, ".downcity");
+}
+
+/** 返回 Chat 渠道路由目录。 */
+export function get_chat_channel_dir_path(root_path: string): string {
+  return path.join(get_downcity_path(root_path), "channel");
+}
+
+/** 返回 Chat 渠道路由文件。 */
+export function get_chat_channel_meta_path(root_path: string): string {
+  return path.join(get_chat_channel_dir_path(root_path), "meta.json");
+}
+
+/** 返回单个 Chat 会话的事件目录。 */
+export function get_chat_session_dir_path(
+  root_path: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_downcity_path(root_path),
+    "chat",
+    encodeURIComponent(normalize_text(session_id)),
+  );
+}
+
+/** 返回单个 Chat 会话的事件流文件。 */
+export function get_chat_history_path(
+  root_path: string,
+  session_id: string,
+): string {
+  return path.join(get_chat_session_dir_path(root_path, session_id), "history.jsonl");
+}
+
+/** 返回飞书渠道的消息去重目录。 */
+export function get_feishu_dedupe_dir_path(root_path: string): string {
+  return path.join(get_downcity_path(root_path), ".cache", "feishu", "dedupe");
+}
+
+async function read_channel_meta(
+  root_path: string,
+): Promise<Partial<ChannelContextMetaFileV1>> {
+  const raw = await fs.readJson(get_chat_channel_meta_path(root_path)).catch(() => null);
+  return raw && typeof raw === "object"
+    ? raw as Partial<ChannelContextMetaFileV1>
+    : {};
+}
+
+function build_target_key(input: ChatStorageCleanInput): string {
+  const channel = normalize_text(input.channel);
+  const chat_id = normalize_text(input.chat_id);
+  if (!channel || !chat_id) return "";
+  return [
+    channel,
+    chat_id,
+    normalize_text(input.target_type),
+    normalize_thread_id(input.thread_id) || "",
+  ].join("|");
+}
+
+function matches_target(
+  route: ChannelContextRouteV1,
+  input: ChatStorageCleanInput,
+): boolean {
+  const channel = normalize_text(input.channel);
+  const chat_id = normalize_text(input.chat_id);
+  const target_type = normalize_text(input.target_type);
+  const thread_id = normalize_thread_id(input.thread_id);
+  if (!channel || !chat_id) return false;
+  if (normalize_text(route.channel) !== channel) return false;
+  if (normalize_text(route.chatId) !== chat_id) return false;
+  if (target_type && normalize_text(route.targetType) !== target_type) return false;
+  if (thread_id && normalize_thread_id(route.threadId) !== thread_id) return false;
+  return true;
+}
+
+function resolve_session_id(
+  meta: Partial<ChannelContextMetaFileV1>,
+  input: ChatStorageCleanInput,
+): string {
+  const explicit = normalize_text(input.session_id);
+  if (explicit) return explicit;
+  const target_key = build_target_key(input);
+  const mapped = normalize_text(
+    target_key ? meta.sessionIdByTargetKey?.[target_key] : "",
+  );
+  if (mapped) return mapped;
+  for (const route of Object.values(meta.routesBySessionId || {})) {
+    if (route && matches_target(route, input)) {
+      return normalize_text(route.sessionId);
+    }
+  }
+  return "";
+}
+
+async function remove_route(
+  root_path: string,
+  meta: Partial<ChannelContextMetaFileV1>,
+  session_id: string,
+): Promise<boolean> {
+  const routes_by_session_id = { ...(meta.routesBySessionId || {}) };
+  const session_id_by_target_key = { ...(meta.sessionIdByTargetKey || {}) };
+  let removed = false;
+  if (routes_by_session_id[session_id]) {
+    delete routes_by_session_id[session_id];
+    removed = true;
+  }
+  for (const [target_key, mapped_session_id] of Object.entries(
+    session_id_by_target_key,
+  )) {
+    if (normalize_text(mapped_session_id) !== session_id) continue;
+    delete session_id_by_target_key[target_key];
+    removed = true;
+  }
+  if (!removed) return false;
+  await fs.ensureDir(get_chat_channel_dir_path(root_path));
+  await fs.writeJson(
+    get_chat_channel_meta_path(root_path),
+    {
+      ...meta,
+      v: 1,
+      updatedAt: Date.now(),
+      routesBySessionId: routes_by_session_id,
+      sessionIdByTargetKey: session_id_by_target_key,
+    },
+    { spaces: 2 },
+  );
+  return true;
+}
+
+/**
+ * 清空单个 Chat 会话的事件历史。
+ */
+export async function clear_chat_history(
+  root_path: string,
+  session_id: string,
+): Promise<boolean> {
+  const history_path = get_chat_history_path(root_path, session_id);
+  const existed = await fs.pathExists(history_path);
+  if (existed) await fs.remove(history_path);
+  return existed;
+}
+
+/**
+ * 清理单个 Chat 会话的领域存储。
+ *
+ * 关键点（中文）
+ * - 只删除 Chat Plugin 自己拥有的路由与事件目录。
+ * - Agent Session 数据由调用方通过 Session API 单独删除。
+ */
+export async function clean_chat_storage(
+  input: ChatStorageCleanInput,
+): Promise<ChatStorageCleanResult> {
+  const root_path = path.resolve(normalize_text(input.root_path) || ".");
+  const meta = await read_channel_meta(root_path);
+  const session_id = resolve_session_id(meta, input);
+  if (!session_id) {
+    return {
+      session_id: "",
+      removed_chat_dir: false,
+      removed_route: false,
+    };
+  }
+  const chat_dir_path = get_chat_session_dir_path(root_path, session_id);
+  const removed_chat_dir = await fs.pathExists(chat_dir_path);
+  if (removed_chat_dir) await fs.remove(chat_dir_path);
+  const removed_route = await remove_route(root_path, meta, session_id);
+  return {
+    session_id,
+    removed_chat_dir,
+    removed_route,
+  };
+}

package/src/chat/runtime/SystemPrompt.ts

@@ -7,8 +7,8 @@
  * - 统一从 request context + ChatMetaStore 读取当前 chat 元信息。
  */
 
-import { getSessionRunContext } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
+import type { PluginRunContext } from "@downcity/agent";
 import type { ChatEnvironmentPromptInput } from "@/chat/types/ChatPromptContext.js";
 import { readChatMetaBySessionId } from "@/chat/runtime/ChatMetaStore.js";
 
@@ -25,8 +25,9 @@ function normalizePromptValue(value: unknown, fallback: string): string {
  */
 export async function resolveCurrentChatEnvironmentPromptInput(
   context: AgentContext,
+  run_context?: PluginRunContext,
 ): Promise<ChatEnvironmentPromptInput | null> {
-  const sessionId = String(getSessionRunContext()?.sessionId || "").trim();
+  const sessionId = String(run_context?.sessionId || "").trim();
   if (!sessionId) return null;
 
   const meta = await readChatMetaBySessionId({
@@ -77,8 +78,12 @@ export function buildChatEnvironmentPrompt(input: ChatEnvironmentPromptInput): s
  */
 export async function buildCurrentChatEnvironmentPrompt(
   context: AgentContext,
+  run_context?: PluginRunContext,
 ): Promise<string> {
-  const input = await resolveCurrentChatEnvironmentPromptInput(context);
+  const input = await resolveCurrentChatEnvironmentPromptInput(
+    context,
+    run_context,
+  );
   if (!input) return "";
   return buildChatEnvironmentPrompt(input);
 }

package/src/chat/types/ChannelConfiguration.ts

@@ -82,7 +82,7 @@ export interface ChatChannelConfigurationField {
    */
   nullable: boolean;
   /**
-   * 是否允许通过 `chat.configure` 写入。
+   * 是否允许上游产品写入。
    */
   writable: boolean;
   /**
@@ -136,7 +136,7 @@ export interface ChatChannelConfigurationDescriptor {
      */
     canBindChannelAccount: boolean;
     /**
-     * 是否支持 `chat.configure`。
+     * 上游产品是否支持编辑该渠道配置。
      */
     canConfigure: boolean;
   };

package/src/chat/types/ChatPluginActionPayload.ts

@@ -7,7 +7,6 @@
  * - 字段命名保持与 CLI/API 参数一致，降低映射心智负担。
  */
 
-import type { JsonValue } from "@downcity/agent";
 import type {
   ChatDeleteRequest,
   ChatHistoryRequest,
@@ -66,6 +65,14 @@ export type ChatSessionActionPayload = {
  */
 export type ChatHistoryActionPayload = ChatHistoryRequest;
 
+/**
+ * `chat.history_clear` action 的输入载荷。
+ */
+export interface ChatHistoryClearActionPayload {
+  /** 要清空 Chat 事件历史的 Session 标识。 */
+  sessionId: string;
+}
+
 /**
  * `chat.react` action 的输入载荷。
  */
@@ -115,51 +122,3 @@ export type ChatReconnectActionPayload = {
    */
   channel?: ChatChannelName;
 };
-
-/**
- * `chat.open` action 的输入载荷。
- */
-export type ChatOpenActionPayload = {
-  /**
-   * 指定目标渠道；省略时表示全部渠道。
-   */
-  channel?: ChatChannelName;
-};
-
-/**
- * `chat.close` action 的输入载荷。
- */
-export type ChatCloseActionPayload = {
-  /**
-   * 指定目标渠道；省略时表示全部渠道。
-   */
-  channel?: ChatChannelName;
-};
-
-/**
- * `chat.configuration` action 的输入载荷。
- */
-export type ChatConfigurationActionPayload = {
-  /**
-   * 指定目标渠道；省略时表示全部渠道。
-   */
-  channel?: ChatChannelName;
-};
-
-/**
- * `chat.configure` action 的输入载荷。
- */
-export type ChatConfigureActionPayload = {
-  /**
-   * 要更新的目标渠道。
-   */
-  channel: ChatChannelName;
-  /**
-   * 渠道配置 patch；值类型遵循 channel configuration 元信息。
-   */
-  config: Record<string, JsonValue>;
-  /**
-   * 配置完成后是否立即重启目标渠道；默认由上层解释为 true。
-   */
-  restart?: boolean;
-};

package/src/chat/types/ChatPluginOptions.ts

@@ -12,24 +12,6 @@ import type { StoredChannelAccount } from "@downcity/agent";
 import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
 import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
 
-/**
- * Chat channel 运行态 patch。
- */
-export interface ChatChannelRuntimePatch {
-  /**
-   * 是否启用该 channel。
-   */
-  enabled?: boolean;
-  /**
-   * 绑定的账号池记录 ID。
-   *
-   * 说明（中文）
-   * - 传入字符串表示绑定到该账号池记录。
-   * - 传入 `null` 表示清空账号池绑定。
-   */
-  channelAccountId?: string | null;
-}
-
 /**
  * Chat channel 对象协议。
  */
@@ -50,10 +32,6 @@ export interface ChatChannel {
    * 解析当前 channel 的运行态账号。
    */
   getAccount(context: AgentContext): StoredChannelAccount | null;
-  /**
-   * 应用运行态配置 patch。
-   */
-  applyRuntimePatch(patch: ChatChannelRuntimePatch): void;
 }
 
 /**