@downcity/agent 1.1.1 → 1.1.5

package/src/services/chat/runtime/ChatSendMetadata.ts

@@ -1,170 +0,0 @@
-/**
- * Chat send frontmatter metadata 解析工具。
- *
- * 关键点（中文）
- * - frontmatter 中的字段语义与 `city chat send` 参数保持一致。
- * - direct 模式也复用同一解析逻辑，避免 metadata 协议分叉。
- */
-
-import type { ChatMessageSendOptions } from "@services/chat/types/ChatMessageMarkup.js";
-
-function normalizeText(value: unknown): string {
-  return String(value ?? "").trim();
-}
-
-function pickMetadataValue(
-  metadata: Record<string, unknown>,
-  keys: string[],
-): unknown {
-  for (const key of keys) {
-    if (Object.hasOwn(metadata, key)) {
-      return metadata[key];
-    }
-  }
-  return undefined;
-}
-
-function parseBoolean(value: unknown): boolean | undefined {
-  if (typeof value === "boolean") return value;
-  const text = normalizeText(value).toLowerCase();
-  if (!text) return undefined;
-  if (text === "true" || text === "1" || text === "yes") return true;
-  if (text === "false" || text === "0" || text === "no") return false;
-  return undefined;
-}
-
-function parseOptionalMessageId(value: unknown): string | undefined {
-  if (typeof value === "number" && Number.isFinite(value) && !Number.isNaN(value)) {
-    const text = String(Math.trunc(value)).trim();
-    return text ? text : undefined;
-  }
-  if (typeof value === "string") {
-    const text = value.trim();
-    return text ? text : undefined;
-  }
-  return undefined;
-}
-
-function looksLikeIsoDatetimeWithoutTimezone(value: string): boolean {
-  const text = String(value || "").trim();
-  if (!text) return false;
-  const isoLike = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(text);
-  if (!isoLike) return false;
-  return !/(?:Z|[+-]\d{2}:\d{2})$/i.test(text);
-}
-
-function parseNonNegativeInt(
-  value: unknown,
-  fieldName: string,
-  strict: boolean,
-): number | undefined {
-  const text = normalizeText(value);
-  if (!text) return undefined;
-  if (!/^\d+$/.test(text)) {
-    if (strict) {
-      throw new Error(`Invalid ${fieldName}: ${String(value)}`);
-    }
-    return undefined;
-  }
-  const parsed = Number.parseInt(text, 10);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
-    if (strict) {
-      throw new Error(`Invalid ${fieldName}: ${String(value)}`);
-    }
-    return undefined;
-  }
-  return parsed;
-}
-
-function parseSendAtMs(
-  value: unknown,
-  fieldName: string,
-  strict: boolean,
-): number | undefined {
-  const text = normalizeText(value);
-  if (!text) return undefined;
-
-  if (/^\d+$/.test(text)) {
-    const parsed = Number.parseInt(text, 10);
-    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-      if (strict) {
-        throw new Error(`Invalid ${fieldName}: ${String(value)}`);
-      }
-      return undefined;
-    }
-    return parsed < 1_000_000_000_000 ? parsed * 1000 : parsed;
-  }
-
-  if (looksLikeIsoDatetimeWithoutTimezone(text)) {
-    if (strict) {
-      throw new Error(
-        `Invalid ${fieldName}: ${String(value)}. ISO datetime must include timezone offset (e.g. +08:00 or Z).`,
-      );
-    }
-    return undefined;
-  }
-
-  const parsed = Date.parse(text);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-    if (strict) {
-      throw new Error(
-        `Invalid ${fieldName}: ${String(value)}. Use Unix timestamp (seconds/ms) or ISO datetime.`,
-      );
-    }
-    return undefined;
-  }
-  return parsed;
-}
-
-/**
- * 从 frontmatter metadata 中解析发送参数。
- *
- * 说明（中文）
- * - `strict=true` 时，非法 delay/time 会直接抛错，适用于 CLI/API 输入。
- * - `strict=false` 时，非法字段会被忽略，适用于 direct 模式的宽容解析。
- */
-export function parseChatSendOptionsFromMetadata(params: {
-  metadata: Record<string, unknown>;
-  strict?: boolean;
-}): ChatMessageSendOptions {
-  const metadata =
-    params.metadata && typeof params.metadata === "object" && !Array.isArray(params.metadata)
-      ? params.metadata
-      : {};
-  const strict = params.strict === true;
-
-  const chatKey = normalizeText(
-    pickMetadataValue(metadata, ["chatKey", "chat-key"]),
-  );
-  const delayMs = parseNonNegativeInt(
-    pickMetadataValue(metadata, ["delayMs", "delay-ms", "delay"]),
-    "delay",
-    strict,
-  );
-  const sendAtMs = parseSendAtMs(
-    pickMetadataValue(metadata, ["sendAtMs", "send-at-ms", "sendAt", "send-at", "time"]),
-    "time",
-    strict,
-  );
-  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
-    throw new Error("`delay` and `time` cannot be used together.");
-  }
-
-  const explicitMessageId = parseOptionalMessageId(
-    pickMetadataValue(metadata, ["messageId", "message-id"]),
-  );
-  const replyRaw = pickMetadataValue(metadata, ["reply"]);
-  const replyAsBoolean = parseBoolean(replyRaw);
-  const replyAsMessageId =
-    explicitMessageId || (replyAsBoolean === undefined ? parseOptionalMessageId(replyRaw) : undefined);
-  const replyToMessage =
-    replyAsBoolean === true || typeof replyAsMessageId === "string";
-
-  return {
-    ...(chatKey ? { chatKey } : {}),
-    ...(typeof delayMs === "number" ? { delayMs } : {}),
-    ...(typeof sendAtMs === "number" ? { sendAtMs } : {}),
-    ...(replyToMessage ? { replyToMessage: true } : {}),
-    ...(typeof replyAsMessageId === "string" ? { messageId: replyAsMessageId } : {}),
-  };
-}

package/src/services/chat/runtime/ChatSendRegistry.ts

@@ -1,43 +0,0 @@
-/**
- * Chat egress dispatcher registry（按 channel 路由回包能力）。
- *
- * 关键点（中文）
- * - tool（如 `chat_send`）通过 dispatcher 把消息发回对应平台
- * - dispatcher 本身不关心 chatKey/history，只关心“怎么把一段 text 发出去”
- */
-import type {
-  ChatDispatchChannel,
-  ChatDispatcher,
-} from "@services/chat/types/ChatDispatcher.js";
-
-const dispatchers = new Map<ChatDispatchChannel, ChatDispatcher>();
-
-/**
- * 注册 channel -> dispatcher 映射。
- *
- * 约束（中文）
- * - 同一 channel 重复注册时以后者覆盖，便于 server 启动阶段统一重建。
- */
-export function registerChatSender(
-  channel: ChatDispatchChannel,
-  dispatcher: ChatDispatcher,
-): void {
-  dispatchers.set(channel, dispatcher);
-}
-
-/**
- * 移除 channel 的 dispatcher 映射。
- *
- * 关键点（中文）
- * - 主要用于测试场景回收全局注册状态。
- */
-export function unregisterChatSender(channel: ChatDispatchChannel): void {
-  dispatchers.delete(channel);
-}
-
-/**
- * 获取指定 channel 的 dispatcher。
- */
-export function getChatSender(channel: ChatDispatchChannel): ChatDispatcher | undefined {
-  return dispatchers.get(channel);
-}

package/src/services/chat/runtime/ChatServiceSystem.ts

@@ -1,119 +0,0 @@
-/**
- * ChatServiceSystem：chat service 的 system prompt 组装模块。
- *
- * 关键点（中文）
- * - chat service prompt 与 channel prompt 都属于静态资产。
- * - 当前请求只注入当前 channel 的 prompt，避免平台规则串味。
- * - 该模块只负责 prompt 解析与拼装，不承担运行态控制职责。
- */
-
-import { readFileSync } from "node:fs";
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import {
-  buildCurrentChatEnvironmentPrompt,
-  resolveCurrentChatEnvironmentPromptInput,
-} from "@services/chat/runtime/SystemPrompt.js";
-
-const CHAT_DIRECT_PROMPT_FILE_URL = new URL("../PROMPT.direct.txt", import.meta.url);
-const TELEGRAM_DIRECT_PROMPT_FILE_URL = new URL(
-  "../channels/telegram/PROMPT.direct.txt",
-  import.meta.url,
-);
-const FEISHU_DIRECT_PROMPT_FILE_URL = new URL(
-  "../channels/feishu/PROMPT.direct.txt",
-  import.meta.url,
-);
-const QQ_DIRECT_PROMPT_FILE_URL = new URL(
-  "../channels/qq/PROMPT.direct.txt",
-  import.meta.url,
-);
-
-/**
- * 加载 chat service 使用说明提示词。
- *
- * 关键点（中文）
- * - 启动阶段即加载，缺失时直接抛错，避免静默失效。
- */
-function loadChatServicePrompt(fileUrl: URL): string {
-  try {
-    return readFileSync(fileUrl, "utf-8").trim();
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `failed to load chat service prompt from ${fileUrl.pathname}: ${reason}`,
-    );
-  }
-}
-
-const CHAT_SERVICE_PROMPT = loadChatServicePrompt(CHAT_DIRECT_PROMPT_FILE_URL);
-
-/**
- * 加载单个 channel 提示词。
- *
- * 关键点（中文）
- * - channel 提示词属于强依赖资产，缺失时直接抛错，避免运行时悄悄丢失规则。
- */
-function loadChatChannelPrompt(fileUrl: URL, channelName: string): string {
-  try {
-    return readFileSync(fileUrl, "utf-8").trim();
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `failed to load ${channelName} chat channel prompt from ${fileUrl.pathname}: ${reason}`,
-    );
-  }
-}
-
-const CHAT_CHANNEL_PROMPTS: Record<"telegram" | "feishu" | "qq", string> = {
-  telegram: loadChatChannelPrompt(
-    TELEGRAM_DIRECT_PROMPT_FILE_URL,
-    "telegram-direct",
-  ),
-  feishu: loadChatChannelPrompt(FEISHU_DIRECT_PROMPT_FILE_URL, "feishu-direct"),
-  qq: loadChatChannelPrompt(QQ_DIRECT_PROMPT_FILE_URL, "qq-direct"),
-};
-
-function resolveCurrentChatPromptChannel(
-  channel: string,
-): "telegram" | "feishu" | "qq" | null {
-  if (channel === "telegram" || channel === "feishu" || channel === "qq") {
-    return channel;
-  }
-  return null;
-}
-
-/**
- * 构建当前请求所属 channel 的提示词片段。
- *
- * 关键点（中文）
- * - 仅注入当前 context 对应的 channel prompt，避免把其他平台规则混入本轮会话。
- * - 若当前 context 不是 chat channel（如 consoleui）或尚无路由元信息，则不注入 channel prompt。
- */
-export async function buildCurrentChannelPrompts(
-  context: AgentContext,
-): Promise<string[]> {
-  const chatEnvironment = await resolveCurrentChatEnvironmentPromptInput(context);
-  if (!chatEnvironment) return [];
-  const channel = resolveCurrentChatPromptChannel(
-    String(chatEnvironment.channel || "")
-      .trim()
-      .toLowerCase(),
-  );
-  if (!channel) return [];
-  return [CHAT_CHANNEL_PROMPTS[channel]].filter(Boolean);
-}
-
-/**
- * 构建 chat service 注入到 session 的 system 文本。
- */
-export async function buildChatServiceSystem(
-  context: AgentContext,
-): Promise<string> {
-  return [
-    CHAT_SERVICE_PROMPT,
-    await buildCurrentChatEnvironmentPrompt(context),
-    ...(await buildCurrentChannelPrompts(context)),
-  ]
-    .filter(Boolean)
-    .join("\n\n");
-}

package/src/services/chat/runtime/ChatSession.ts

@@ -1,125 +0,0 @@
-/**
- * ChatSession：chat 专用 Session 实现。
- *
- * 关键点（中文）
- * - ChatSession 在实例化时持有自己的 execution composer 实例。
- * - chat 当前 turn 的 step 合并/step 回发状态都绑定在 Session 自身，不再新增 `runChat` 一层入口。
- * - 外层仍只调用标准 `run(...)`；chat 语义由 ChatSession 内部收敛。
- */
-
-import { Session } from "@session/Session.js";
-import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
-import type { ChatSessionExecutionComposer } from "@services/chat/runtime/ChatSessionExecutionComposer.js";
-import type { SessionExecutor } from "@/types/session/SessionExecutor.js";
-import type { SessionAssistantStepCallback } from "@/types/session/SessionRun.js";
-import type { SessionRunResult } from "@/types/session/SessionRun.js";
-import type { ChatSessionTurnState } from "@/types/chat/ChatSession.js";
-
-type ChatSessionOptions = {
-  /**
-   * 当前会话 ID。
-   */
-  sessionId: string;
-
-  /**
-   * 当前 session 的 history composer。
-   */
-  historyComposer: SessionHistoryComposer;
-
-  /**
-   * 当前 session 绑定的 chat execution composer。
-   */
-  executionComposer: ChatSessionExecutionComposer;
-
-  /**
-   * 创建当前 session 的执行器。
-   */
-  createExecutor: (
-    historyComposer: SessionHistoryComposer,
-    executionComposer: ChatSessionExecutionComposer,
-  ) => SessionExecutor;
-
-  /**
-   * session 更新后的异步回调。
-   */
-  runAfterSessionUpdated?: (sessionId: string) => Promise<void>;
-};
-
-/**
- * Chat 专用 Session。
- */
-export class ChatSession extends Session {
-  /**
-   * ChatSession 持有的 composer 实例。
-   */
-  readonly executionComposer: ChatSessionExecutionComposer;
-
-  private activeTurnState: ChatSessionTurnState | null = null;
-
-  constructor(options: ChatSessionOptions) {
-    const executionComposer = options.executionComposer;
-    super({
-      sessionId: options.sessionId,
-      historyComposer: options.historyComposer,
-      createExecutor: (historyComposer) =>
-        options.createExecutor(historyComposer, executionComposer),
-      ...(options.runAfterSessionUpdated
-        ? { runAfterSessionUpdated: options.runAfterSessionUpdated }
-        : {}),
-    });
-    this.executionComposer = executionComposer;
-  }
-
-  /**
-   * 读取当前绑定的 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 的一次请求。
-   *
-   * 关键点（中文）
-   * - 外层继续走统一的 `session.run(...)` 入口。
-   * - 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 {
-      return await super.run({
-        query: params.query,
-        onStepCallback: params.onStepCallback,
-        onAssistantStepCallback: this.forwardAssistantStep,
-      });
-    } finally {
-      this.activeTurnState = null;
-    }
-  }
-}

package/src/services/chat/runtime/ChatSessionDelete.ts

@@ -1,95 +0,0 @@
-/**
- * ChatSessionDelete：按 sessionId 彻底删除 chat 会话数据。
- *
- * 关键点（中文）
- * - 删除路由映射（`.downcity/channel/meta.json`）
- * - 删除 chat 审计目录（`.downcity/chat/<sessionId>/`）
- * - 删除 core session 目录（`.downcity/session/<sessionId>/`）
- * - 清理运行中 agent 与队列，避免残留任务继续执行
- */
-
-import fs from "fs-extra";
-import path from "node:path";
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import { resolveChatQueueStore } from "@services/chat/runtime/ChatQueue.js";
-import { removeChatMetaBySessionId } from "@services/chat/runtime/ChatMetaStore.js";
-
-function normalizeSessionId(sessionId: string): string {
-  return String(sessionId || "").trim();
-}
-
-/**
- * 彻底删除一个 chat session。
- *
- * 关键点（中文）
- * - 幂等：目标不存在时返回 success + deleted=false，避免上层重试复杂化。
- */
-export async function deleteChatSessionById(params: {
-  context: AgentContext;
-  sessionId: string;
-}): Promise<{
-  success: boolean;
-  sessionId: string;
-  deleted: boolean;
-  removedMeta: boolean;
-  removedChatDir: boolean;
-  removedSessionDir: boolean;
-  error?: string;
-}> {
-  const sessionId = normalizeSessionId(params.sessionId);
-  if (!sessionId) {
-    return {
-      success: false,
-      sessionId: "",
-      deleted: false,
-      removedMeta: false,
-      removedChatDir: false,
-      removedSessionDir: false,
-      error: "Missing sessionId",
-    };
-  }
-
-  try {
-    // 关键点（中文）：先停执行，再删文件，避免删除过程中仍有任务写入。
-    params.context.session.get(sessionId).clearExecutor();
-    resolveChatQueueStore(params.context).clear(sessionId);
-
-    const removedMetaResult = await removeChatMetaBySessionId({
-      context: params.context,
-      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 deleted =
-      removedMetaResult.removed || hadChatDir || hadSessionDir;
-
-    return {
-      success: true,
-      sessionId,
-      deleted,
-      removedMeta: removedMetaResult.removed,
-      removedChatDir: hadChatDir,
-      removedSessionDir: hadSessionDir,
-    };
-  } catch (error) {
-    return {
-      success: false,
-      sessionId,
-      deleted: false,
-      removedMeta: false,
-      removedChatDir: false,
-      removedSessionDir: false,
-      error: String(error),
-    };
-  }
-}

package/src/services/chat/runtime/ChatSessionExecutionComposer.ts

@@ -1,106 +0,0 @@
-/**
- * ChatSessionExecutionComposer：chat 专用 execution composer。
- *
- * 关键点（中文）
- * - 由 chat 层在 Session 实例化时注入，不再依赖 run 时层层传 callback。
- * - step 合并消息读取自 ChatSession 当前绑定的 turn context。
- * - 其余能力（tools / fallback assistant）继续复用默认本地实现。
- */
-
-import type { ModelMessage, Tool } from "ai";
-import { drainInjectedUserMessages } from "@session/SessionRunScope.js";
-import { LocalSessionExecutionComposer } from "@session/composer/execution/LocalSessionExecutionComposer.js";
-import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
-import type { SessionSystemMessage } from "@/types/session/SessionPrompts.js";
-import type { ChatSessionTurnState } from "@/types/chat/ChatSession.js";
-
-type ChatSessionExecutionComposerOptions = {
-  /**
-   * 当前 session 标识。
-   */
-  sessionId: string;
-
-  /**
-   * 读取当前可用工具集合。
-   */
-  getTools: () => Record<string, Tool>;
-
-  /**
-   * 读取当前已绑定的 chat turn 状态。
-   */
-  getTurnState: () => ChatSessionTurnState | null;
-};
-
-/**
- * ChatSession 专用 execution composer。
- */
-export class ChatSessionExecutionComposer extends LocalSessionExecutionComposer {
-  private readonly getTurnState: ChatSessionExecutionComposerOptions["getTurnState"];
-
-  constructor(options: ChatSessionExecutionComposerOptions) {
-    super({
-      sessionId: options.sessionId,
-      getTools: options.getTools,
-    });
-    this.getTurnState = options.getTurnState;
-  }
-
-  createPrepareStepHandler(
-    input: {
-      system: SessionSystemMessage[];
-      appendMergedUserMessages: (
-        messages: SessionMessageV1[],
-      ) => 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 } : {}),
-      };
-    };
-  }
-}