@downcity/agent 1.1.1

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

@@ -0,0 +1,84 @@
+/**
+ * Chat SystemPrompt：chat 运行时 system prompt 辅助。
+ *
+ * 关键点（中文）
+ * - 把当前 chat 路由环境从入站 `<info>` 中剥离，改由 system prompt 注入。
+ * - 仅描述当前会话环境，不承载用户身份字段。
+ * - 统一从 request context + ChatMetaStore 读取当前 chat 元信息。
+ */
+
+import { getSessionRunScope } from "@session/SessionRunScope.js";
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { ChatEnvironmentPromptInput } from "@/shared/types/ChatPromptContext.js";
+import { readChatMetaBySessionId } from "@services/chat/runtime/ChatMetaStore.js";
+
+function normalizePromptValue(value: unknown, fallback: string): string {
+  const text = String(value ?? "").trim();
+  return text || fallback;
+}
+
+/**
+ * 解析当前请求的 chat 环境输入。
+ *
+ * 说明（中文）
+ * - 非 chat session 或尚未建立 chat route 时返回 `null`。
+ */
+export async function resolveCurrentChatEnvironmentPromptInput(
+  context: AgentContext,
+): Promise<ChatEnvironmentPromptInput | null> {
+  const sessionId = String(getSessionRunScope()?.sessionId || "").trim();
+  if (!sessionId) return null;
+
+  const meta = await readChatMetaBySessionId({
+    context,
+    sessionId,
+  }).catch(() => null);
+  if (!meta?.channel || !meta.chatId) return null;
+
+  return {
+    sessionId: meta.sessionId,
+    chatKey: meta.sessionId,
+    channel: meta.channel,
+    chatId: meta.chatId,
+    ...(meta.targetType ? { chatType: meta.targetType } : {}),
+    ...(typeof meta.threadId === "number" ? { threadId: meta.threadId } : {}),
+    ...(meta.chatTitle ? { chatTitle: meta.chatTitle } : {}),
+  };
+}
+
+/**
+ * 构造当前 chat 环境说明文本。
+ */
+export function buildChatEnvironmentPrompt(input: ChatEnvironmentPromptInput): string {
+  const lines = [
+    "# Current Chat Environment",
+    "以下字段只描述当前 chat 会话环境与路由，不是用户身份信息：",
+    `- channel: ${normalizePromptValue(input.channel, "unknown")}`,
+    `- session_id: ${normalizePromptValue(input.sessionId, "unknown")}`,
+    `- chat_key: ${normalizePromptValue(input.chatKey, "unknown")}`,
+    `- chat_id: ${normalizePromptValue(input.chatId, "unknown")}`,
+    `- chat_type: ${normalizePromptValue(input.chatType, "unknown")}`,
+    `- thread_id: ${normalizePromptValue(
+      typeof input.threadId === "number" ? String(input.threadId) : "",
+      "none",
+    )}`,
+  ];
+
+  const chatTitle = normalizePromptValue(input.chatTitle, "");
+  if (chatTitle) {
+    lines.push(`- chat_title: ${chatTitle}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 读取并渲染当前请求的 chat 环境 prompt。
+ */
+export async function buildCurrentChatEnvironmentPrompt(
+  context: AgentContext,
+): Promise<string> {
+  const input = await resolveCurrentChatEnvironmentPromptInput(context);
+  if (!input) return "";
+  return buildChatEnvironmentPrompt(input);
+}

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

@@ -0,0 +1,141 @@
+/**
+ * UIMessage 解析辅助。
+ *
+ * 关键点（中文）
+ * - 这些能力属于 runtime 执行结果处理，不属于 prompts 组装
+ * - 用于提取最终 assistant 文本与工具调用摘要
+ */
+
+import {
+  getToolName,
+  isTextUIPart,
+  isToolUIPart,
+  type UIDataTypes,
+  type UIMessagePart,
+  type UITools,
+} from "ai";
+import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
+import type { JsonObject, JsonValue } from "@/shared/types/Json.js";
+
+type AnyUiMessagePart = UIMessagePart<UIDataTypes, UITools>;
+type ToolNameReadablePart = Parameters<typeof getToolName>[0];
+type ToolCallSummary = {
+  tool: string;
+  input: JsonObject;
+  output: string;
+};
+
+type ToolPartCompatShape = {
+  type?: string;
+  state?: string;
+  input?: JsonValue;
+  output?: unknown;
+  errorText?: unknown;
+  error?: unknown;
+  approval?: {
+    reason?: unknown;
+  };
+};
+
+function toUiParts(message: SessionMessageV1 | null | undefined): AnyUiMessagePart[] {
+  return Array.isArray(message?.parts) ? message.parts : [];
+}
+
+function normalizeJsonValue(value: JsonValue | object | undefined): JsonValue {
+  if (value === undefined) return null;
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value)) as JsonValue;
+  } catch {
+    return String(value);
+  }
+}
+
+function toToolInput(rawInput: JsonValue | object | undefined): JsonObject {
+  const normalized = normalizeJsonValue(rawInput);
+  if (normalized && typeof normalized === "object" && !Array.isArray(normalized)) {
+    return normalized as JsonObject;
+  }
+  return { value: normalized };
+}
+
+function resolveToolName(part: ToolPartCompatShape, aiToolName?: string): string {
+  const fromAi = String(aiToolName || "").trim();
+  if (fromAi) return fromAi;
+
+  const rawType = typeof part.type === "string" ? part.type.trim() : "";
+  if (rawType.startsWith("tool-")) return rawType.slice("tool-".length);
+
+  return "";
+}
+
+function tryReadAiToolName(part: AnyUiMessagePart): string {
+  if (!isToolUIPart(part)) return "";
+  return String(getToolName(part as ToolNameReadablePart) || "").trim();
+}
+
+function extractToolOutput(part: ToolPartCompatShape): string {
+  const state = typeof part.state === "string" ? part.state.trim() : "";
+  const outputObj =
+    state === "output-available"
+      ? part.output
+      : state === "output-error"
+        ? { error: part.errorText ?? part.error ?? "tool_error" }
+        : state === "output-denied"
+          ? { error: "tool_denied", reason: part.approval?.reason }
+          : undefined;
+  if (outputObj === undefined) return "";
+  try {
+    return JSON.stringify(outputObj);
+  } catch {
+    return String(outputObj);
+  }
+}
+
+/**
+ * 从 UIMessage 中提取纯文本。
+ */
+export function extractTextFromUiMessage(
+  message: SessionMessageV1 | null | undefined,
+): string {
+  const parts = toUiParts(message);
+  return parts
+    .filter(isTextUIPart)
+    .map((part) => String(part.text ?? ""))
+    .join("\n")
+    .trim();
+}
+
+/**
+ * 从 UIMessage 中提取 tool 调用记录。
+ */
+export function extractToolCallsFromUiMessage(
+  message: SessionMessageV1 | null | undefined,
+): ToolCallSummary[] {
+  const parts = toUiParts(message);
+  const out: ToolCallSummary[] = [];
+
+  for (const part of parts) {
+    const partObject = part as ToolPartCompatShape;
+    const toolUiPart = isToolUIPart(part) ? part : null;
+    if (!toolUiPart) continue;
+
+    const toolName = resolveToolName(partObject, tryReadAiToolName(part));
+    if (!toolName) continue;
+
+    const rawInput = (part as { input?: JsonValue }).input;
+    const input = toToolInput(rawInput);
+    const output = extractToolOutput(partObject);
+
+    out.push({
+      tool: toolName,
+      input,
+      output,
+    });
+  }
+
+  return out;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * 从 assistant message 中提取“用户可见文本”。
+ *
+ * 背景（中文，关键点）
+ * - 在 tool-strict 模式下，模型的 `result.text` 可能为空
+ * - 真实的“最终回复”往往由 `chat_send` 工具的 input.text 决定
+ * - 因此需要一个稳定的、与 Agent 解耦的提取逻辑（属于 chat/egress 语义）
+ */
+
+import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
+import {
+  extractTextFromUiMessage,
+  extractToolCallsFromUiMessage,
+} from "./UIMessageTransformer.js";
+
+/**
+ * 生成真正应该落盘到 session 的 assistant message。
+ *
+ * 关键点（中文）
+ * - 没有 step 持久化时，直接保留完整 assistant message。
+ * - 一旦 step 已单独落盘，最终 merged assistant 不再重复写入。
+ */
+export function resolveAssistantMessageForPersistence(
+  message: SessionMessageV1 | null | undefined,
+): SessionMessageV1 | null {
+  if (!message || typeof message !== "object") return null;
+  return hasPersistedAssistantSteps(message) ? null : message;
+}
+
+/**
+ * 判断 assistant message 是否声明“本轮 step 消息已单独持久化”。
+ *
+ * 关键点（中文）
+ * - 该标记只用于避免在 run 结束时把最终 merged assistant 再重复写入 context。
+ * - 不影响 channel 发送；只影响 context messages 的最终 append 策略。
+ */
+export function hasPersistedAssistantSteps(
+  message: SessionMessageV1 | null | undefined,
+): boolean {
+  const extra = message?.metadata?.extra;
+  if (!extra || typeof extra !== "object" || Array.isArray(extra)) return false;
+  return extra.assistantStepMessagesPersisted === true;
+}
+
+/**
+ * 提取策略（中文）
+ * - 倒序扫描：优先使用最后一次 `chat_send`，与最终用户感知一致。
+ * - 优先使用 chat_send 的 input.text（需结合 tool output 判断成功）。
+ * - 若 tool output 为空/非 JSON，走 best-effort 采用 input.text。
+ * - 若无 tool call，则回退到 message 文本内容。
+ */
+export function pickLastSuccessfulChatSendText(
+  message: SessionMessageV1 | null | undefined,
+): string {
+  const toolCalls = extractToolCallsFromUiMessage(message);
+  // 关键点（中文）：优先从 chat_send 的 input.text 还原"用户可见回复"。
+  for (let i = toolCalls.length - 1; i >= 0; i -= 1) {
+    const tc = toolCalls[i];
+    if (!tc) continue;
+    if (String(tc.tool || "") !== "chat_send") continue;
+
+    const inputText = tc.input ? tc.input.text : undefined;
+    const text = (typeof inputText === "string" ? inputText : "").trim();
+    if (!text) continue;
+
+    const raw = String(tc.output || "").trim();
+    if (!raw) return text; // 无输出时 best-effort 认为成功
+
+    try {
+      const parsed = JSON.parse(raw);
+      if (
+        parsed &&
+        typeof parsed === "object" &&
+        (parsed as { success?: boolean }).success === true
+      ) {
+        return text;
+      }
+    } catch {
+      // unknown format：best-effort 使用 text
+      return text;
+    }
+  }
+  return extractTextFromUiMessage(message);
+}

package/src/services/chat/types/BotInfo.ts

@@ -0,0 +1,101 @@
+/**
+ * Chat Bot 信息探测类型定义。
+ *
+ * 关键点（中文）
+ * - 将“凭据 -> bot 基础信息”的探测输入输出结构标准化。
+ * - Console、Channel Account 存储、后续自动化流程都复用该结构。
+ */
+
+import type { ChatChannelName } from "@services/chat/types/ChannelStatus.js";
+
+/**
+ * Bot 信息探测凭据。
+ */
+export interface ChatBotInfoCredentialInput {
+  /**
+   * Telegram 机器人 token（仅 Telegram 渠道使用）。
+   */
+  botToken?: string;
+  /**
+   * 应用 ID（Feishu/QQ 使用）。
+   */
+  appId?: string;
+  /**
+   * 应用密钥（Feishu/QQ 使用）。
+   */
+  appSecret?: string;
+  /**
+   * 平台域名（可选，主要用于 Feishu 私有部署或特殊网关）。
+   */
+  domain?: string;
+  /**
+   * 是否使用沙箱环境（QQ 使用）。
+   */
+  sandbox?: boolean;
+}
+
+/**
+ * Bot 信息探测请求。
+ */
+export interface ChatBotInfoResolveInput {
+  /**
+   * 目标渠道名称。
+   */
+  channel: ChatChannelName;
+  /**
+   * 渠道对应的认证凭据。
+   */
+  credentials: ChatBotInfoCredentialInput;
+}
+
+/**
+ * Bot 信息探测结果。
+ */
+export interface ChatBotInfoResult {
+  /**
+   * 渠道名称。
+   */
+  channel: ChatChannelName;
+  /**
+   * Bot 展示名称（用于 Console 列表展示和默认命名）。
+   */
+  name: string;
+  /**
+   * Bot 身份标识（通常是用户名/open_id/appId 等）。
+   */
+  identity?: string;
+  /**
+   * Bot 所有者信息（可选；平台可获取时返回）。
+   */
+  owner?: string;
+  /**
+   * Bot 创建者信息（可选；平台可获取时返回）。
+   */
+  creator?: string;
+  /**
+   * 平台返回的 bot 用户唯一 ID（若可获取）。
+   */
+  botUserId?: string;
+  /**
+   * 建议用于生成 channel account id 的稳定种子。
+   */
+  idSeed?: string;
+  /**
+   * 探测结果描述。
+   */
+  message: string;
+}
+
+/**
+ * 渠道级 Bot 信息探测器接口。
+ */
+export interface ChatChannelBotInfoProvider {
+  /**
+   * 当前探测器对应渠道。
+   */
+  readonly channel: ChatChannelName;
+  /**
+   * 使用凭据探测并返回标准化 bot 信息。
+   */
+  resolve(credentials: ChatBotInfoCredentialInput): Promise<ChatBotInfoResult>;
+}

package/src/services/chat/types/ChannelConfiguration.ts

@@ -0,0 +1,161 @@
+/**
+ * Chat 渠道配置元信息类型。
+ *
+ * 关键点（中文）
+ * - 每个 channel 通过统一结构声明“需要哪些参数、类型、描述、来源”。
+ * - 该结构用于 Console / DB / CLI 直接消费，不依赖硬编码字段。
+ */
+
+import type { ChatChannelName } from "@services/chat/types/ChannelStatus.js";
+
+/**
+ * 配置字段基础值类型。
+ */
+export type ChatChannelConfigurationPrimitive = string | number | boolean | null;
+
+/**
+ * 配置字段类型枚举。
+ */
+export type ChatChannelConfigurationFieldType =
+  | "string"
+  | "boolean"
+  | "number"
+  | "secret"
+  | "enum";
+
+/**
+ * 配置字段来源枚举。
+ */
+export type ChatChannelConfigurationFieldSource =
+  | "ship_json"
+  | "bot_account"
+  | "env_fallback";
+
+/**
+ * 枚举型字段可选项。
+ */
+export interface ChatChannelConfigurationFieldOption {
+  /**
+   * 枚举值（真实写入值）。
+   */
+  value: string;
+  /**
+   * 展示标签（用于 UI 下拉选项）。
+   */
+  label: string;
+  /**
+   * 选项说明（用于帮助用户理解差异）。
+   */
+  description: string;
+}
+
+/**
+ * 单个配置字段描述。
+ */
+export interface ChatChannelConfigurationField {
+  /**
+   * 字段键名（例如 `channelAccountId`、`enabled`）。
+   */
+  key: string;
+  /**
+   * 字段展示名。
+   */
+  label: string;
+  /**
+   * 字段用途说明。
+   */
+  description: string;
+  /**
+   * 字段值类型。
+   */
+  type: ChatChannelConfigurationFieldType;
+  /**
+   * 字段值来源（downcity.json / channel account / env fallback）。
+   */
+  source: ChatChannelConfigurationFieldSource;
+  /**
+   * 该字段是否必填。
+   */
+  required: boolean;
+  /**
+   * 字段是否允许 `null`（用于清空）。
+   */
+  nullable: boolean;
+  /**
+   * 是否允许通过 `chat.configure` 写入。
+   */
+  writable: boolean;
+  /**
+   * 修改该字段后是否建议重载 channel。
+   */
+  restartRequired: boolean;
+  /**
+   * 默认值（可选）。
+   */
+  defaultValue?: ChatChannelConfigurationPrimitive;
+  /**
+   * 示例值（可选）。
+   */
+  example?: ChatChannelConfigurationPrimitive;
+  /**
+   * 枚举选项（仅 `type=enum` 时使用）。
+   */
+  options?: ChatChannelConfigurationFieldOption[];
+}
+
+/**
+ * 单个渠道配置说明。
+ */
+export interface ChatChannelConfigurationDescriptor {
+  /**
+   * 渠道名称。
+   */
+  channel: ChatChannelName;
+  /**
+   * 配置卡片标题。
+   */
+  title: string;
+  /**
+   * 配置说明（面向用户）。
+   */
+  description: string;
+  /**
+   * 描述器版本号（便于 UI 做兼容升级）。
+   */
+  version: string;
+  /**
+   * 该渠道支持的写入动作能力。
+   */
+  capabilities: {
+    /**
+     * 是否支持启用/禁用开关。
+     */
+    canToggleEnabled: boolean;
+    /**
+     * 是否支持 channel account 绑定。
+     */
+    canBindChannelAccount: boolean;
+    /**
+     * 是否支持 `chat.configure`。
+     */
+    canConfigure: boolean;
+  };
+  /**
+   * 渠道配置字段集合（按来源分组）。
+   */
+  fields: {
+    /**
+     * `downcity.json` 可声明字段。
+     */
+    ship: ChatChannelConfigurationField[];
+    /**
+     * `channel_accounts` 字段。
+     */
+    channelAccount: ChatChannelConfigurationField[];
+    /**
+     * 环境变量回退字段。
+     */
+    envFallback: ChatChannelConfigurationField[];
+  };
+}
+

package/src/services/chat/types/ChannelContext.ts

@@ -0,0 +1,110 @@
+/**
+ * ChannelContext 类型定义。
+ *
+ * 关键点（中文）
+ * - 描述渠道目标（platform target）与内部 sessionId 的映射结构。
+ * - 映射由 chat service 维护，sessionId 对外保持稳定但不可推导。
+ */
+
+import type { ChatDispatchChannel } from "./ChatDispatcher.js";
+
+/**
+ * 渠道目标标识输入。
+ */
+export type ChannelContextTarget = {
+  /**
+   * 渠道类型（telegram/feishu/qq）。
+   */
+  channel: ChatDispatchChannel;
+  /**
+   * 平台 chat 原始 ID。
+   */
+  chatId: string;
+  /**
+   * 平台 chat 类型（如 group/c2c/channel/p2p）。
+   */
+  targetType?: string;
+  /**
+   * 平台 thread/topic ID（仅部分渠道存在）。
+   */
+  threadId?: number;
+};
+
+/**
+ * `sessionId -> 渠道目标` 路由条目。
+ */
+export type ChannelContextRouteV1 = {
+  /**
+   * schema 版本。
+   */
+  v: 1;
+  /**
+   * 内部 sessionId（随机生成，不可推导）。
+   */
+  sessionId: string;
+  /**
+   * 渠道类型（telegram/feishu/qq）。
+   */
+  channel: ChatDispatchChannel;
+  /**
+   * 平台 chat 原始 ID。
+   */
+  chatId: string;
+  /**
+   * 平台 chat 类型（group/c2c/channel/p2p...）。
+   */
+  targetType?: string;
+  /**
+   * 平台 thread/topic ID。
+   */
+  threadId?: number;
+  /**
+   * 最近入站/出站相关 messageId（用于回复语义补全）。
+   */
+  messageId?: string;
+  /**
+   * 最近触发该会话的用户 ID。
+   */
+  actorId?: string;
+  /**
+   * 最近触发该会话的用户名/昵称。
+   */
+  actorName?: string;
+  /**
+   * 会话展示名（群名/频道名/私聊对象名）。
+   *
+   * 说明（中文）
+   * - 由各渠道在入站时 best-effort 提供。
+   * - 用于 Console 展示，不参与路由键计算。
+   */
+  chatTitle?: string;
+  /**
+   * 路由条目更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+};
+
+/**
+ * Channel 映射文件结构。
+ */
+export type ChannelContextMetaFileV1 = {
+  /**
+   * schema 版本。
+   */
+  v: 1;
+  /**
+   * 文件更新时间（毫秒时间戳）。
+   */
+  updatedAt: number;
+  /**
+   * 目标键 -> sessionId 映射索引。
+   *
+   * 说明（中文）
+   * - 目标键由 `channel/chatId/targetType/threadId` 归一化后拼接。
+   */
+  sessionIdByTargetKey: Record<string, string>;
+  /**
+   * sessionId -> 路由信息映射索引。
+   */
+  routesBySessionId: Record<string, ChannelContextRouteV1>;
+};