@downcity/plugins 1.0.174 → 1.0.194

package/src/chat/runtime/ChatSession.ts

@@ -1,168 +0,0 @@
-/**
- * ChatSession：chat 专用 Executor 实现。
- *
- * 关键点（中文）
- * - ChatSession 在实例化时持有自己的 context composer 实例。
- * - chat 当前 turn 的 step 合并/step 回发状态都绑定在 Session 自身，不再新增 `runChat` 一层入口。
- * - 外层仍只调用标准 `run(...)`；chat 语义由 ChatSession 内部收敛。
- */
-
-import type { LanguageModel, Tool } from "ai";
-import { Executor } from "@downcity/agent";
-import type { SessionHistoryComposer } from "@downcity/agent";
-import type { SessionHistoryStore } from "@downcity/agent";
-import type { SessionCompactionComposer } from "@downcity/agent";
-import type { SessionSystemComposer } from "@downcity/agent";
-import type { ChatSessionContextComposer } from "@/chat/runtime/ChatSessionContextComposer.js";
-import type { Logger } from "@downcity/agent";
-import type { SessionAssistantStepCallback } from "@downcity/agent";
-import type { SessionRunResult } from "@downcity/agent";
-import type { SessionRunContext } from "@downcity/agent";
-import type { ChatSessionTurnState } from "@/chat/runtime/ChatSessionTypes.js";
-
-type ChatSessionOptions = {
-  /**
-   * 当前会话 ID。
-   */
-  sessionId: string;
-
-  /**
-   * 当前 session 的 history store。
-   */
-  historyStore: SessionHistoryStore;
-
-  /**
-   * 当前 session 的 history composer。
-   */
-  historyComposer: SessionHistoryComposer;
-
-  /**
-   * 读取当前 session 使用的模型实例。
-   */
-  getModel: () => LanguageModel | undefined;
-
-  /**
-   * 统一日志器。
-   */
-  logger: Logger;
-
-  /**
-   * 当前 session 对应的 compaction Composer。
-   */
-  compactionComposer: SessionCompactionComposer;
-
-  /**
-   * 当前 session 对应的 system Composer。
-   */
-  systemComposer: SessionSystemComposer;
-
-  /**
-   * 获取当前可用工具集合。
-   */
-  getTools: () => Record<string, Tool>;
-
-  /**
-   * 读取当前 chat session effective Agent env。
-   */
-  getEnv: () => Record<string, string>;
-
-  /**
-   * 当前 session 绑定的 chat context composer。
-   */
-  contextComposer: ChatSessionContextComposer;
-
-  /**
-   * session 更新后的异步回调。
-   */
-};
-
-/**
- * Chat 专用 Session。
- */
-export class ChatSession extends Executor {
-  /**
-   * ChatSession 持有的 composer 实例。
-   */
-  readonly contextComposer: ChatSessionContextComposer;
-
-  private activeTurnState: ChatSessionTurnState | null = null;
-
-  constructor(options: ChatSessionOptions) {
-    const contextComposer = options.contextComposer;
-    super({
-      sessionId: options.sessionId,
-      historyStore: options.historyStore,
-      historyComposer: options.historyComposer,
-      getModel: options.getModel,
-      logger: options.logger,
-      compactionComposer: options.compactionComposer,
-      systemComposer: options.systemComposer,
-      getTools: options.getTools,
-      getEnv: options.getEnv,
-      contextComposer,
-    });
-    this.contextComposer = contextComposer;
-  }
-
-  /**
-   * 读取当前绑定的 chat turn 状态。
-   */
-  getTurnState(): ChatSessionTurnState | null {
-    return this.activeTurnState;
-  }
-
-  /**
-   * 处理一次 assistant step 回发。
-   *
-   * 关键点（中文）
-   * - step 持久化由基类 `Session.run` 先完成。
-   * - 这里仅负责把当前 turn 绑定的外部回发钩子继续调出去。
-   */
-  private readonly forwardAssistantStep: SessionAssistantStepCallback = async (
-    step,
-  ): Promise<void> => {
-    const callback = this.activeTurnState?.onAssistantStepCallback;
-    if (typeof callback !== "function") return;
-    await callback(step);
-  };
-
-  /**
-   * 运行当前 chat session 的一次请求。
-   *
-   * 关键点（中文）
-   * - 外层继续走统一的内部执行入口。
-   * - ChatSession 只是在 run 生命周期里临时绑定 turn 状态给自己的 composer。
-   */
-  override async run(params: {
-    query: string;
-    onStepCallback?: ChatSessionTurnState["onStepCallback"];
-    onAssistantStepCallback?: ChatSessionTurnState["onAssistantStepCallback"];
-  }): Promise<SessionRunResult> {
-    this.activeTurnState = {
-      ...(typeof params.onStepCallback === "function"
-        ? { onStepCallback: params.onStepCallback }
-        : {}),
-      ...(typeof params.onAssistantStepCallback === "function"
-        ? { onAssistantStepCallback: params.onAssistantStepCallback }
-        : {}),
-    };
-    try {
-      const run_context: SessionRunContext = {
-        sessionId: this.sessionId,
-        ...(typeof params.onStepCallback === "function"
-          ? { onStepCallback: params.onStepCallback }
-          : {}),
-        onAssistantStepCallback: this.forwardAssistantStep,
-        injectedUserMessages: [],
-        deferredPersistedUserMessages: [],
-        pendingAssistantFileParts: [],
-      };
-      return await super.run({
-        query: params.query,
-        runContext: run_context,
-      });
-    } finally {
-      this.activeTurnState = null;
-    }
-  }
-}

package/src/chat/runtime/ChatSessionContextComposer.ts

@@ -1,106 +0,0 @@
-/**
- * ChatSessionContextComposer：chat 专用 context composer。
- *
- * 关键点（中文）
- * - 由 chat 层在 Session 实例化时注入，不再依赖 run 时层层传 callback。
- * - step 合并消息读取自 ChatSession 当前绑定的 turn context。
- * - 其余能力（tools / fallback assistant）继续复用默认本地实现。
- */
-
-import type { ModelMessage, Tool } from "ai";
-import { drainInjectedUserMessages } from "@downcity/agent";
-import { LocalSessionContextComposer } from "@downcity/agent";
-import type { SessionRecordV1 } from "@downcity/agent";
-import type { SessionSystemMessage } from "@downcity/agent";
-import type { ChatSessionTurnState } from "@/chat/runtime/ChatSessionTypes.js";
-
-type ChatSessionContextComposerOptions = {
-  /**
-   * 当前 session 标识。
-   */
-  sessionId: string;
-
-  /**
-   * 读取当前可用工具集合。
-   */
-  getTools: () => Record<string, Tool>;
-
-  /**
-   * 读取当前已绑定的 chat turn 状态。
-   */
-  getTurnState: () => ChatSessionTurnState | null;
-};
-
-/**
- * ChatSession 专用 context composer。
- */
-export class ChatSessionContextComposer extends LocalSessionContextComposer {
-  private readonly getTurnState: ChatSessionContextComposerOptions["getTurnState"];
-
-  constructor(options: ChatSessionContextComposerOptions) {
-    super({
-      sessionId: options.sessionId,
-      getTools: options.getTools,
-    });
-    this.getTurnState = options.getTurnState;
-  }
-
-  createPrepareStepHandler(
-    input: {
-      system: SessionSystemMessage[];
-      appendMergedUserMessages: (
-        messages: SessionRecordV1[],
-      ) => Promise<ModelMessage[]>;
-    },
-  ): (input: { messages?: ModelMessage[] }) => Promise<{
-    system: SessionSystemMessage[];
-    messages?: ModelMessage[];
-  }> {
-    return async ({
-      messages,
-    }: {
-      messages?: ModelMessage[];
-    }): Promise<{
-      system: SessionSystemMessage[];
-      messages?: ModelMessage[];
-    }> => {
-      const injectedMessages = drainInjectedUserMessages();
-      const turnState = this.getTurnState();
-      const onStepCallback = turnState?.onStepCallback;
-      if (
-        typeof onStepCallback !== "function" &&
-        injectedMessages.length === 0
-      ) {
-        return { system: input.system };
-      }
-
-      const incomingMessages: ModelMessage[] = Array.isArray(messages)
-        ? messages
-        : [];
-      let outMessages: ModelMessage[] | undefined;
-      try {
-        const mergedMessages =
-          typeof onStepCallback === "function"
-            ? await onStepCallback()
-            : [];
-        const mergedWithInjected = [
-          ...injectedMessages,
-          ...(Array.isArray(mergedMessages) ? mergedMessages : []),
-        ];
-        const mergedModelMessages = await input.appendMergedUserMessages(
-          mergedWithInjected,
-        );
-        if (mergedModelMessages.length > 0) {
-          // 关键点（中文）：保持当前 step 顺序，仅把新增 chat user 消息追加到末尾。
-          outMessages = [...incomingMessages, ...mergedModelMessages];
-        }
-      } catch {
-        // ignore merge hook failures
-      }
-      return {
-        system: input.system,
-        ...(Array.isArray(outMessages) ? { messages: outMessages } : {}),
-      };
-    };
-  }
-}

package/src/chat/runtime/ChatSessionTypes.ts

@@ -1,32 +0,0 @@
-/**
- * ChatSession 相关类型定义。
- *
- * 关键点（中文）
- * - Chat 专用 session 会把“队列消息合并 / step 回发”收敛到 chat 层自身。
- * - 普通 Session 仍可复用基础 `run / append*` 能力，不强耦合 chat 语义。
- */
-
-import type { SessionUserMessageV1 } from "@downcity/agent";
-import type { SessionAssistantStepCallback } from "@downcity/agent";
-
-/**
- * ChatSession 单次 turn 绑定的运行态。
- */
-export interface ChatSessionTurnState {
-  /**
-   * 提取本轮 step 边界新增的 user 消息。
-   *
-   * 关键点（中文）
-   * - 该回调用于把同一 chat lane 后续到达的消息并入当前推理。
-   * - 若未提供，则表示当前 turn 不启用 step 合并。
-   */
-  onStepCallback?: () => Promise<SessionUserMessageV1[]>;
-
-  /**
-   * assistant step 回发钩子。
-   *
-   * 关键点（中文）
-   * - ChatSession 内部会先完成 step 持久化，再调用该钩子做真实渠道发送。
-   */
-  onAssistantStepCallback?: SessionAssistantStepCallback;
-}

package/src/tts/Plugin.ts

@@ -1,284 +0,0 @@
-/**
- * TtsPlugin：文本转语音插件。
- *
- * 关键点（中文）
- * - TTS 能力通过 constructor 注入，推荐传入 `city.ai.tts`。
- * - plugin 不负责本地模型、Python 依赖、provider 或项目配置。
- * - action 返回 AI SDK UIMessage，音频 file part 会由 plugin tool bridge 统一落盘到资源目录。
- */
-
-import { BasePlugin } from "@downcity/agent";
-import { createAction } from "@downcity/agent";
-import { z } from "zod";
-import type { AgentContext } from "@downcity/agent";
-import type {
-  JsonObject,
-  JsonValue,
-} from "@downcity/agent";
-import type {
-  TtsPluginInput,
-  TtsPluginOptions,
-  TtsPluginResult,
-  TtsPluginSimpleAudioResult,
-  TtsPluginUiMessageResult,
-} from "@/tts/types/TtsPlugin.js";
-
-const DEFAULT_TTS_PLUGIN_NAME = "tts";
-const DEFAULT_TTS_PLUGIN_TITLE = "TTS";
-const DEFAULT_TTS_PLUGIN_DESCRIPTION =
-  "Synthesize speech through an injected TTS function and return assistant audio file parts.";
-const DEFAULT_MEDIA_TYPE = "audio/wav";
-const DEFAULT_FILENAME = "speech.wav";
-
-/**
- * 判断值是否为普通对象。
- */
-function to_record(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value as Record<string, unknown>;
-}
-
-/**
- * 归一化 action payload。
- */
-function normalize_tts_payload(payload: JsonValue | undefined): TtsPluginInput {
-  const record = to_record(payload ?? {});
-  if (!record) {
-    throw new TypeError("TtsPlugin.synthesize payload must be an object");
-  }
-  const text = typeof record.text === "string" ? record.text.trim() : "";
-  if (!text) {
-    throw new Error("TtsPlugin.synthesize requires text");
-  }
-  return {
-    ...(record as TtsPluginInput),
-    text,
-  };
-}
-
-/**
- * 判断返回值是否已经是 AI SDK UIMessage。
- */
-function is_ui_message_result(value: TtsPluginResult): value is TtsPluginUiMessageResult {
-  const record = to_record(value);
-  return Boolean(record && Array.isArray(record.parts));
-}
-
-/**
- * 读取简单音频结果中的 URL。
- */
-function read_audio_url(record: Record<string, unknown>): string {
-  const url =
-    typeof record.url === "string"
-      ? record.url.trim()
-      : typeof record.data_url === "string"
-        ? record.data_url.trim()
-        : typeof record.audio_path === "string"
-          ? record.audio_path.trim()
-          : "";
-  if (!url) {
-    throw new TypeError(
-      "TtsPlugin tts function must return a UIMessage or { url | data_url | audio_path }",
-    );
-  }
-  return url;
-}
-
-/**
- * 把简单音频结果归一为 UIMessage。
- */
-function simple_audio_to_ui_message(
-  result: TtsPluginSimpleAudioResult,
-): TtsPluginUiMessageResult {
-  const record = to_record(result);
-  if (!record) {
-    throw new TypeError("TtsPlugin tts function returned an invalid result");
-  }
-  const url = read_audio_url(record);
-  const media_type =
-    typeof record.media_type === "string" && record.media_type.trim()
-      ? record.media_type.trim()
-      : DEFAULT_MEDIA_TYPE;
-  const filename =
-    typeof record.filename === "string" && record.filename.trim()
-      ? record.filename.trim()
-      : DEFAULT_FILENAME;
-  const text = typeof record.text === "string" ? record.text.trim() : "";
-
-  return {
-    id: `tts:${Date.now()}`,
-    role: "assistant",
-    parts: [
-      ...(text ? [{ type: "text" as const, text }] : []),
-      {
-        type: "file" as const,
-        mediaType: media_type,
-        filename,
-        url,
-      },
-    ],
-  };
-}
-
-/**
- * 校验并归一化 TTS 返回结果。
- */
-function normalize_tts_result(result: TtsPluginResult): TtsPluginUiMessageResult {
-  if (is_ui_message_result(result)) {
-    return result;
-  }
-  return simple_audio_to_ui_message(result);
-}
-
-/**
- * Agent TTS 插件。
- */
-export class TtsPlugin extends BasePlugin {
-  /**
-   * 当前 plugin 稳定名称。
-   */
-  readonly name: string;
-
-  /**
-   * 插件标题。
-   */
-  readonly title: string;
-
-  /**
-   * 插件说明。
-   */
-  readonly description: string;
-
-  private readonly tts: TtsPluginOptions["tts"];
-  private readonly language?: string;
-  private readonly voice?: string;
-  private readonly format?: string;
-
-  constructor(options: TtsPluginOptions) {
-    super();
-    const name = String(options.name || DEFAULT_TTS_PLUGIN_NAME).trim();
-    if (!name) {
-      throw new Error("TtsPlugin requires a non-empty name");
-    }
-    if (typeof options.tts !== "function") {
-      throw new Error("TtsPlugin requires a tts function");
-    }
-    this.name = name;
-    this.title = String(options.title || DEFAULT_TTS_PLUGIN_TITLE).trim();
-    this.description = String(
-      options.description || DEFAULT_TTS_PLUGIN_DESCRIPTION,
-    ).trim();
-    this.tts = options.tts;
-    this.language =
-      typeof options.language === "string" && options.language.trim()
-        ? options.language.trim()
-        : undefined;
-    this.voice =
-      typeof options.voice === "string" && options.voice.trim()
-        ? options.voice.trim()
-        : undefined;
-    this.format =
-      typeof options.format === "string" && options.format.trim()
-        ? options.format.trim()
-        : undefined;
-  }
-
-  /**
-   * TTS 插件给模型的使用说明。
-   */
-  system(_context: AgentContext): string {
-    return [
-      "# TTS Plugin",
-      "",
-      "Use this plugin when the user asks to create spoken audio, voice output, narration, or a reusable audio file.",
-      "Do not call it for ordinary text replies unless the user explicitly wants audio.",
-      "",
-      "Call through `plugin_call`:",
-      "",
-      "```ts",
-      "plugin_call({",
-      `  plugin: "${this.name}",`,
-      '  action: "synthesize",',
-      "  payload: {",
-      '    text: "...",',
-      "  },",
-      "});",
-      "```",
-      "",
-      "Payload rules:",
-      "- `text` is required.",
-      "- Optional fields: `language`, `voice`, `format`, `speed`, `provider_options`.",
-      "- The returned audio file part is saved under project `.downcity/resources` and attached to the final assistant message automatically.",
-    ].join("\n");
-  }
-
-  /**
-   * 执行一次 TTS 合成。
-   */
-  private async synthesize(input: TtsPluginInput): Promise<TtsPluginUiMessageResult> {
-    const result = await this.tts({
-      ...(this.language ? { language: this.language } : {}),
-      ...(this.voice ? { voice: this.voice } : {}),
-      ...(this.format ? { format: this.format } : {}),
-      ...input,
-    });
-    return normalize_tts_result(result);
-  }
-
-  /**
-   * 显式 action 集合。
-   */
-  readonly actions = {
-    synthesize: createAction({
-      description:
-        "Synthesize speech from text. Returns a UIMessage whose audio file part is auto-saved under the project resources directory.",
-      input_schema: {
-        zod: z
-          .object({
-            text: z.string(),
-            language: z.string().optional(),
-            voice: z.string().optional(),
-            format: z.string().optional(),
-            speed: z.number().optional(),
-            provider_options: z.record(z.string(), z.unknown()).optional(),
-          })
-          .passthrough(),
-        json_schema: {
-          type: "object",
-          required: ["text"],
-          properties: {
-            text: { type: "string", description: "Text to synthesize." },
-            language: { type: "string", description: "Language code, optional." },
-            voice: { type: "string", description: "Voice, optional." },
-            format: { type: "string", description: "Audio format, optional." },
-            speed: { type: "number", description: "Speech speed, optional." },
-          },
-        },
-      },
-      examples: [
-        { title: "Default voice", payload: { text: "Hello, world" } },
-        {
-          title: "Specific voice",
-          payload: { text: "Welcome back", voice: "alloy", format: "mp3" },
-        },
-      ],
-      execute: async ({ input }: { input: JsonValue }) => {
-        try {
-          const synth_input = normalize_tts_payload(input);
-          const message = await this.synthesize(synth_input);
-          return {
-            success: true,
-            data: message as unknown as JsonObject,
-            message: "speech synthesized",
-          };
-        } catch (error) {
-          return {
-            success: false,
-            error: String(error),
-            message: String(error),
-          };
-        }
-      },
-    }),
-  };
-}