@downcity/plugins 1.0.4

package/src/chat/runtime/ChatSendActionInput.ts

@@ -0,0 +1,255 @@
+/**
+ * Chat send action 输入映射。
+ *
+ * 关键点（中文）
+ * - 专门处理 `chat send` 的 CLI/API payload 标准化。
+ * - frontmatter metadata 与 `<file>` 协议在这里转换为统一正文。
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { PluginActionCommandInput } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { ChatSendActionPayload } from "@/chat/types/ChatPluginActionPayload.js";
+import {
+  buildChatMessageText,
+  parseChatMessageMarkup,
+} from "@downcity/agent/internal/executor/messages/ChatMessageMarkup.js";
+import { parseChatSendOptionsFromMetadata } from "@/chat/runtime/ChatSendMetadata.js";
+import {
+  normalizeChatSendText,
+  resolveChatKey,
+} from "@/chat/Action.js";
+import { getBooleanOpt, getStringOpt } from "./ChatActionInputSupport.js";
+
+/**
+ * 解析非负整数 option。
+ */
+function parseNonNegativeIntOptionOrThrow(
+  value: string,
+  fieldName: string,
+): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  if (!/^\d+$/.test(text)) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  const parsed = Number.parseInt(text, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  return parsed;
+}
+
+/**
+ * 判断 ISO datetime 是否缺少时区。
+ */
+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);
+}
+
+/**
+ * 解析定时发送时间。
+ *
+ * 支持格式（中文）
+ * - Unix 时间戳：秒或毫秒（纯数字）
+ * - ISO 时间字符串：例如 `2026-03-05T20:30:00+08:00`
+ */
+function parseSendTimeOptionOrThrow(value: string, fieldName: string): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+
+  if (/^\d+$/.test(text)) {
+    const parsed = Number.parseInt(text, 10);
+    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+      throw new Error(`Invalid ${fieldName}: ${value}`);
+    }
+    // 关键点（中文）：10 位通常是秒级时间戳，统一转换为毫秒。
+    return parsed < 1_000_000_000_000 ? parsed * 1000 : parsed;
+  }
+  if (looksLikeIsoDatetimeWithoutTimezone(text)) {
+    throw new Error(
+      `Invalid ${fieldName}: ${value}. ISO datetime must include timezone offset (e.g. +08:00 or Z).`,
+    );
+  }
+
+  const parsed = Date.parse(text);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(
+      `Invalid ${fieldName}: ${value}. Use Unix timestamp (seconds/ms) or ISO datetime.`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * 解析 chat send 正文协议。
+ */
+function parseChatSendTextProtocol(params: {
+  rawText: string;
+  explicitChatKey?: string;
+  explicitDelayMs?: number;
+  explicitSendAtMs?: number;
+  explicitReplyToMessage?: boolean;
+  explicitMessageId?: string;
+}): ChatSendActionPayload {
+  const parsed = parseChatMessageMarkup(normalizeChatSendText(params.rawText));
+  const metadataOptions = parseChatSendOptionsFromMetadata({
+    metadata: parsed.metadata,
+    strict: true,
+  });
+
+  const delayMs =
+    typeof params.explicitDelayMs === "number"
+      ? params.explicitDelayMs
+      : metadataOptions.delayMs;
+  const sendAtMs =
+    typeof params.explicitSendAtMs === "number"
+      ? params.explicitSendAtMs
+      : metadataOptions.sendAtMs;
+  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
+    throw new Error("`delay` and `time` cannot be used together.");
+  }
+
+  const chatKey = resolveChatKey({
+    chatKey: params.explicitChatKey || metadataOptions.chatKey,
+  });
+  const messageId = String(
+    params.explicitMessageId || metadataOptions.messageId || "",
+  ).trim();
+  const replyToMessage =
+    params.explicitReplyToMessage === true ||
+    metadataOptions.replyToMessage === true;
+
+  return {
+    text: buildChatMessageText({
+      segments: parsed.segments,
+    }),
+    ...(chatKey ? { chatKey } : {}),
+    ...(typeof delayMs === "number" ? { delayMs } : {}),
+    ...(typeof sendAtMs === "number" ? { sendAtMs } : {}),
+    ...(replyToMessage ? { replyToMessage: true } : {}),
+    ...(messageId ? { messageId } : {}),
+  };
+}
+
+/**
+ * 解析 `chat send` 的命令输入。
+ *
+ * 关键点（中文）
+ * - `--text / --stdin / --text-file` 三选一
+ * - 文本读取失败直接抛错，由上层统一输出
+ */
+export async function mapChatSendCommandInput(
+  input: PluginActionCommandInput,
+): Promise<ChatSendActionPayload> {
+  const explicitText = getStringOpt(input.opts, "text");
+  const useStdin = getBooleanOpt(input.opts, "stdin");
+  const textFile = getStringOpt(input.opts, "textFile");
+  const inputSourcesCount =
+    (explicitText ? 1 : 0) + (useStdin ? 1 : 0) + (textFile ? 1 : 0);
+
+  if (inputSourcesCount !== 1) {
+    throw new Error(
+      "Exactly one text source is required: use one of --text, --stdin, or --text-file.",
+    );
+  }
+
+  let text = explicitText;
+  if (useStdin) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    text = Buffer.concat(chunks).toString("utf8");
+  } else if (textFile) {
+    const filePath = path.resolve(process.cwd(), textFile);
+    text = await fs.readFile(filePath, "utf8");
+  }
+
+  const delayRaw = getStringOpt(input.opts, "delay");
+  const timeRaw = getStringOpt(input.opts, "time");
+  const replyToMessage = getBooleanOpt(input.opts, "reply");
+  const messageId = getStringOpt(input.opts, "messageId");
+  const delayMs = delayRaw
+    ? parseNonNegativeIntOptionOrThrow(delayRaw, "delay")
+    : undefined;
+  const sendAtMs = timeRaw ? parseSendTimeOptionOrThrow(timeRaw, "time") : undefined;
+  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
+    throw new Error("`--delay` and `--time` cannot be used together.");
+  }
+  const payload = parseChatSendTextProtocol({
+    rawText: text,
+    explicitChatKey: getStringOpt(input.opts, "chatKey"),
+    ...(typeof delayMs === "number" ? { explicitDelayMs: delayMs } : {}),
+    ...(typeof sendAtMs === "number" ? { explicitSendAtMs: sendAtMs } : {}),
+    ...(replyToMessage ? { explicitReplyToMessage: true } : {}),
+    ...(messageId ? { explicitMessageId: messageId } : {}),
+  });
+  const chatKey = resolveChatKey({
+    chatKey: payload.chatKey,
+  });
+  if (!chatKey) {
+    throw new Error(
+      "Missing chatKey. Provide --chat-key or ensure DC_CTX_CHAT_KEY is injected in current shell context.",
+    );
+  }
+
+  return {
+    text: payload.text,
+    chatKey,
+    ...(typeof payload.delayMs === "number" ? { delayMs: payload.delayMs } : {}),
+    ...(typeof payload.sendAtMs === "number" ? { sendAtMs: payload.sendAtMs } : {}),
+    ...(payload.replyToMessage === true ? { replyToMessage: true } : {}),
+    ...(payload.messageId ? { messageId: payload.messageId } : {}),
+  };
+}
+
+/**
+ * 解析 `chat send` 的 API 输入。
+ */
+export function mapChatSendApiInput(body: JsonValue): ChatSendActionPayload {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new Error("Invalid JSON body");
+  }
+  const payload = body as JsonObject;
+  const delayRaw = payload.delayMs ?? payload.delay;
+  const timeRaw = payload.sendAtMs ?? payload.sendAt ?? payload.time;
+  const replyRaw = payload.replyToMessage ?? payload.reply;
+  const delayText =
+    typeof delayRaw === "string" || typeof delayRaw === "number"
+      ? String(delayRaw).trim()
+      : "";
+  const timeText =
+    typeof timeRaw === "string" || typeof timeRaw === "number"
+      ? String(timeRaw).trim()
+      : "";
+  const delayMs = delayText
+    ? parseNonNegativeIntOptionOrThrow(delayText, "delayMs")
+    : undefined;
+  const sendAtMs = timeText
+    ? parseSendTimeOptionOrThrow(timeText, "sendAtMs")
+    : undefined;
+  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
+    throw new Error("`delayMs` and `sendAtMs` cannot be used together.");
+  }
+  return parseChatSendTextProtocol({
+    rawText: String(payload.text ?? ""),
+    explicitChatKey:
+      typeof payload.chatKey === "string" ? payload.chatKey.trim() : undefined,
+    ...(typeof delayMs === "number" ? { explicitDelayMs: delayMs } : {}),
+    ...(typeof sendAtMs === "number" ? { explicitSendAtMs: sendAtMs } : {}),
+    ...(replyRaw === true ? { explicitReplyToMessage: true } : {}),
+    ...(typeof payload.messageId === "string" || typeof payload.messageId === "number"
+      ? { explicitMessageId: String(payload.messageId).trim() }
+      : {}),
+  });
+}

package/src/chat/runtime/ChatSendMetadata.ts

@@ -0,0 +1,170 @@
+/**
+ * Chat send frontmatter metadata 解析工具。
+ *
+ * 关键点（中文）
+ * - frontmatter 中的字段语义与 `city chat send` 参数保持一致。
+ * - direct 模式也复用同一解析逻辑，避免 metadata 协议分叉。
+ */
+
+import type { ChatMessageSendOptions } from "@downcity/agent/internal/executor/messages/ChatMessageMarkupTypes.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/chat/runtime/ChatSendRegistry.ts

@@ -0,0 +1,43 @@
+/**
+ * Chat egress dispatcher registry（按 channel 路由回包能力）。
+ *
+ * 关键点（中文）
+ * - tool（如 `chat_send`）通过 dispatcher 把消息发回对应平台
+ * - dispatcher 本身不关心 chatKey/history，只关心“怎么把一段 text 发出去”
+ */
+import type {
+  ChatDispatchChannel,
+  ChatDispatcher,
+} from "@/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/chat/runtime/ChatSession.ts

@@ -0,0 +1,156 @@
+/**
+ * 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/internal/executor/Executor.js";
+import type { SessionHistoryComposer } from "@downcity/agent/internal/executor/composer/history/SessionHistoryComposer.js";
+import type { SessionHistoryStore } from "@downcity/agent/internal/executor/store/history/SessionHistoryStore.js";
+import type { SessionCompactionComposer } from "@downcity/agent/internal/executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionSystemComposer } from "@downcity/agent/internal/executor/composer/system/SessionSystemComposer.js";
+import type { ChatSessionContextComposer } from "@/chat/runtime/ChatSessionContextComposer.js";
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { SessionAssistantStepCallback } from "@downcity/agent/internal/executor/types/SessionRun.js";
+import type { SessionRunResult } from "@downcity/agent/internal/executor/types/SessionRun.js";
+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>;
+
+  /**
+   * 当前 session 绑定的 chat context composer。
+   */
+  contextComposer: ChatSessionContextComposer;
+
+  /**
+   * session 更新后的异步回调。
+   */
+  runAfterSessionUpdated?: (sessionId: string) => Promise<void>;
+};
+
+/**
+ * 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,
+      contextComposer,
+      ...(options.runAfterSessionUpdated
+        ? { runAfterSessionUpdated: options.runAfterSessionUpdated }
+        : {}),
+    });
+    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 {
+      return await super.run({
+        query: params.query,
+        onStepCallback: params.onStepCallback,
+        onAssistantStepCallback: this.forwardAssistantStep,
+      });
+    } finally {
+      this.activeTurnState = null;
+    }
+  }
+}