@downcity/agent 1.1.25 → 1.1.35

package/src/service/builtins/chat/runtime/PluginPoints.ts

@@ -1,78 +0,0 @@
-/**
- * Chat service plugin 点定义。
- *
- * 关键点（中文）
- * - plugin 点由 chat service 定义，不由具体 plugin 定义。
- * - service 只依赖这些稳定点名，具体 plugin 负责实现其中某些点。
- * - 后续新增 chat 生命周期 plugin 点，也应统一收敛到这里。
- */
-
-/**
- * Chat service 对外暴露的 plugin 点目录。
- */
-export const CHAT_PLUGIN_POINTS = {
-  /**
-   * 增强入站消息正文。
-   *
-   * 说明（中文）
-   * - service 先构造基础 attachment/body 文本。
-   * - plugin 通过 pipeline 往 `pluginSections` 中追加中间块。
-   */
-  augmentInbound: "chat.augmentInbound",
-  /**
-   * 回复前文本增强。
-   *
-   * 说明（中文）
-   * - service 在真正回发到 channel 前调用。
-   * - plugin 可在这里做收尾改写、格式整理、签名注入等。
-   */
-  beforeReply: "chat.beforeReply",
-  /**
-   * 回复后事件通知。
-   *
-   * 说明（中文）
-   * - service 在一次回复发送完成后触发。
-   * - plugin 可在这里做审计、统计、回执同步等副作用。
-   */
-  afterReply: "chat.afterReply",
-  /**
-   * 入队前数据增强。
-   *
-   * 说明（中文）
-   * - service 在 append ingress / enqueue 之前调用。
-   * - plugin 可在这里改写入队文本或补充 extra metadata。
-   */
-  beforeEnqueue: "chat.beforeEnqueue",
-  /**
-   * 入队后事件通知。
-   *
-   * 说明（中文）
-   * - service 在消息真正入队完成后调用。
-   * - plugin 可在这里做统计、观测、调试落点。
-   */
-  afterEnqueue: "chat.afterEnqueue",
-  /**
-   * 观测入站主体信息。
-   *
-   * 说明（中文）
-   * - 仅做副作用记录，不返回值。
-   * - 典型实现方是 auth plugin。
-   */
-  observePrincipal: "chat.observePrincipal",
-  /**
-   * 判定当前入站消息是否允许执行。
-   *
-   * 说明（中文）
-   * - 由 service 在 ingress 阶段显式调用。
-   * - 典型实现方是 auth plugin。
-   */
-  authorizeIncoming: "chat.authorizeIncoming",
-  /**
-   * 解析当前用户角色。
-   *
-   * 说明（中文）
-   * - 主要用于在 history / queue metadata 中补齐授权上下文。
-   * - 典型实现方是 auth plugin。
-   */
-  resolveUserRole: "chat.resolveUserRole",
-} as const;

package/src/service/builtins/chat/runtime/QueuedUserMessage.ts

@@ -1,43 +0,0 @@
-/**
- * QueuedUserMessage：构造入队执行消息文本。
- *
- * 关键点（中文）
- * - 统一生成 `<info>...</info>` 头部，供模型读取用户与本次请求元信息。
- * - chat 路由环境不再放入 `<info>`，改由 system prompt 注入。
- * - 供 chat 入站执行与其他复用入口共用，避免重复实现。
- */
-
-import type { QueuedUserInfoInput } from "@/service/builtins/chat/types/ChatPromptContext.js";
-
-function normalizeInfoValue(value: unknown): string {
-  const text = String(value ?? "").replace(/\r?\n/g, " ").trim();
-  if (!text) return "";
-  return text.replace(/</g, "&#60;").replace(/>/g, "&#62;");
-}
-
-/**
- * 构造“入队 user message”文本。
- *
- * 说明（中文）
- * - 顶部 `<info>` 为内部语义块，仅记录 user/request 元信息。
- * - 正文为用户原始输入（可为空）。
- */
-export function buildQueuedUserMessageWithInfo(params: {
-  text: string;
-} & QueuedUserInfoInput): string {
-  const infoLines = [
-    `message_id: ${normalizeInfoValue(params.messageId || "unknown")}`,
-    `user_id: ${normalizeInfoValue(params.userId || "unknown")}`,
-    `username: ${normalizeInfoValue(params.username || "unknown")}`,
-    `role_id: ${normalizeInfoValue(params.roleId || "unknown")}`,
-    `permissions: ${normalizeInfoValue((params.permissions || []).join(",") || "none")}`,
-    `received_at: ${normalizeInfoValue(params.receivedAt || new Date().toISOString())}`,
-  ];
-  if (normalizeInfoValue(params.userTimezone)) {
-    infoLines.push(`user_timezone: ${normalizeInfoValue(params.userTimezone)}`);
-  }
-  const infoBlock = `<info>\n${infoLines.join("\n")}\n</info>`;
-  const body = String(params.text ?? "").trim();
-  if (!body) return infoBlock;
-  return `${infoBlock}\n\n${body}`;
-}

package/src/service/builtins/chat/runtime/ReplyContextFormatter.ts

@@ -1,85 +0,0 @@
-/**
- * ReplyContextFormatter：reply 引用上下文格式化工具。
- *
- * 关键点（中文）
- * - 把平台 reply 信息稳定地拼进模型输入正文。
- * - 同时提供额外 metadata，便于 history / 调试链路查看。
- */
-
-import type { JsonObject } from "@/types/common/Json.js";
-import type { InboundReplyContext } from "@/service/builtins/chat/types/ReplyContext.js";
-
-function normalizeReplyValue(value: string | undefined): string | undefined {
-  const text = String(value || "").trim();
-  return text ? text : undefined;
-}
-
-/**
- * 将 reply 上下文转换为执行输入正文。
- *
- * 说明（中文）
- * - 当前消息正文为空时，也会保留 reply block，避免“只看见 reply、看不见被引用内容”。
- * - quote 与完整正文相同则自动去重，避免重复噪声。
- */
-export function buildReplyContextInstruction(params: {
-  text: string;
-  replyContext?: InboundReplyContext;
-}): string {
-  const body = String(params.text ?? "").trim();
-  const replyContext = params.replyContext;
-  if (!replyContext) return body;
-
-  const messageId = normalizeReplyValue(replyContext.messageId);
-  const actorName = normalizeReplyValue(replyContext.actorName);
-  const quoteText = normalizeReplyValue(replyContext.quoteText);
-  const replyText = normalizeReplyValue(replyContext.text);
-  const normalizedQuote =
-    quoteText && quoteText !== replyText ? quoteText : undefined;
-
-  if (!messageId && !actorName && !normalizedQuote && !replyText) {
-    return body;
-  }
-
-  const lines: string[] = ["<reply_context>"];
-  if (messageId) lines.push(`reply_message_id: ${messageId}`);
-  if (actorName) lines.push(`reply_actor_name: ${actorName}`);
-  if (normalizedQuote) {
-    lines.push("reply_quote:");
-    lines.push(normalizedQuote);
-  }
-  if (replyText) {
-    lines.push("reply_message:");
-    lines.push(replyText);
-  }
-  lines.push("</reply_context>");
-
-  if (!body) return lines.join("\n");
-  return `${lines.join("\n")}\n\n${body}`;
-}
-
-/**
- * 将 reply 上下文转换为 ingress extra。
- *
- * 说明（中文）
- * - 仅保留稳定、短小的字段。
- * - 方便在 Console / history 中直接看到引用信息。
- */
-export function buildReplyContextExtra(
-  replyContext?: InboundReplyContext,
-): JsonObject | undefined {
-  if (!replyContext) return undefined;
-
-  const messageId = normalizeReplyValue(replyContext.messageId);
-  const actorName = normalizeReplyValue(replyContext.actorName);
-  const text = normalizeReplyValue(replyContext.text);
-  const quoteText = normalizeReplyValue(replyContext.quoteText);
-  if (!messageId && !actorName && !text && !quoteText) return undefined;
-
-  return {
-    hasReplyContext: true,
-    ...(messageId ? { replyMessageId: messageId } : {}),
-    ...(actorName ? { replyActorName: actorName } : {}),
-    ...(text ? { replyText: text } : {}),
-    ...(quoteText ? { replyQuoteText: quoteText } : {}),
-  };
-}

package/src/service/builtins/chat/runtime/ReplyDispatch.ts

@@ -1,78 +0,0 @@
-/**
- * Chat reply dispatch helper。
- *
- * 关键点（中文）
- * - 把 chat 回复前/回复后的扩展点统一收敛到这里。
- * - 仅服务 agent 执行生命周期，不覆盖手动 `chat send`。
- */
-
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ChatReplyDispatchInput, ChatReplyEffectInput } from "@/service/builtins/chat/types/ChatPlugin.js";
-import type { JsonValue } from "@/types/common/Json.js";
-import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
-import { CHAT_PLUGIN_POINTS } from "@/service/builtins/chat/runtime/PluginPoints.js";
-import { resolveDispatchTargetByChatKey } from "@/service/builtins/chat/runtime/ChatkeySend.js";
-
-function normalizeText(value: string | undefined): string {
-  return String(value || "").trim();
-}
-
-/**
- * 回复前文本增强。
- */
-export async function prepareChatReplyText(params: {
-  context: AgentContext;
-  input: ChatReplyDispatchInput;
-}): Promise<string> {
-  const input = {
-    ...params.input,
-    text: normalizeText(params.input.text),
-  };
-  if (!input.text) return "";
-
-  const next = await params.context.plugins.pipeline<JsonValue>(
-    CHAT_PLUGIN_POINTS.beforeReply,
-    input as unknown as JsonValue,
-  );
-  const record =
-    next && typeof next === "object" && !Array.isArray(next)
-      ? (next as Record<string, unknown>)
-      : {};
-  return normalizeText(typeof record.text === "string" ? record.text : input.text);
-}
-
-/**
- * 回复后事件分发。
- */
-export async function emitChatReplyEffect(params: {
-  context: AgentContext;
-  input: ChatReplyEffectInput;
-}): Promise<void> {
-  await params.context.plugins.effect(
-    CHAT_PLUGIN_POINTS.afterReply,
-    params.input as unknown as JsonValue,
-  );
-}
-
-/**
- * 基于 chatKey 补齐回复目标上下文。
- */
-export async function resolveChatReplyTarget(params: {
-  context: AgentContext;
-  chatKey: string;
-}): Promise<{
-  channel?: ChatDispatchChannel;
-  chatId?: string;
-  messageId?: string;
-}> {
-  const target = await resolveDispatchTargetByChatKey({
-    context: params.context,
-    chatKey: params.chatKey,
-  });
-  if (!target) return {};
-  return {
-    channel: target.channel,
-    chatId: target.chatId,
-    ...(target.messageId ? { messageId: target.messageId } : {}),
-  };
-}

package/src/service/builtins/chat/runtime/SystemPrompt.ts

@@ -1,84 +0,0 @@
-/**
- * Chat SystemPrompt：chat 运行时 system prompt 辅助。
- *
- * 关键点（中文）
- * - 把当前 chat 路由环境从入站 `<info>` 中剥离，改由 system prompt 注入。
- * - 仅描述当前会话环境，不承载用户身份字段。
- * - 统一从 request context + ChatMetaStore 读取当前 chat 元信息。
- */
-
-import { getSessionRunScope } from "@session/SessionRunScope.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ChatEnvironmentPromptInput } from "@/service/builtins/chat/types/ChatPromptContext.js";
-import { readChatMetaBySessionId } from "@/service/builtins/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/service/builtins/chat/runtime/UIMessageTransformer.ts

@@ -1,141 +0,0 @@
-/**
- * UIMessage 解析辅助。
- *
- * 关键点（中文）
- * - 这些能力属于 runtime 执行结果处理，不属于 prompts 组装
- * - 用于提取最终 assistant 文本与工具调用摘要
- */
-
-import {
-  getToolName,
-  isTextUIPart,
-  isToolUIPart,
-  type UIDataTypes,
-  type UIMessagePart,
-  type UITools,
-} from "ai";
-import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import type { JsonObject, JsonValue } from "@/types/common/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/service/builtins/chat/runtime/UserVisibleText.ts

@@ -1,84 +0,0 @@
-/**
- * 从 assistant message 中提取“用户可见文本”。
- *
- * 背景（中文，关键点）
- * - 在 tool-strict 模式下，模型的 `result.text` 可能为空
- * - 真实的“最终回复”往往由 `chat_send` 工具的 input.text 决定
- * - 因此需要一个稳定的、与 Agent 解耦的提取逻辑（属于 chat/egress 语义）
- */
-
-import type { SessionMessageV1 } from "@/session/types/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/service/builtins/chat/types/BotInfo.ts

@@ -1,101 +0,0 @@
-/**
- * Chat Bot 信息探测类型定义。
- *
- * 关键点（中文）
- * - 将“凭据 -> bot 基础信息”的探测输入输出结构标准化。
- * - Console、Channel Account 存储、后续自动化流程都复用该结构。
- */
-
-import type { ChatChannelName } from "@/service/builtins/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>;
-}