@downcity/plugins 1.0.4

package/src/chat/runtime/ChatChannelCore.ts

@@ -0,0 +1,148 @@
+/**
+ * ChatChannelCore：chat 渠道状态的核心共享辅助模块。
+ *
+ * 关键点（中文）
+ * - 这里只放最基础的渠道状态/名称/account 解析能力。
+ * - 生命周期、配置写入、action 执行分别放到更细的模块中。
+ * - 目标是让 chat channel 子模块共享同一套最小公共基元。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { StoredChannelAccount } from "@downcity/agent/internal/types/runtime/host/Store.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
+import { getStoredChannelAccountSync } from "@/chat/accounts/Store.js";
+
+const CHAT_CHANNEL_NAMES: ChatChannelName[] = ["telegram", "feishu", "qq"];
+
+type ChatRuntimeBindings = {
+  getChannelAccountId?(context: AgentContext, channel: ChatChannelName): string;
+  resolveChannelAccount?(
+    context: AgentContext,
+    channel: ChatChannelName,
+  ): StoredChannelAccount | null;
+  isChannelEnabled?(context: AgentContext, channel: ChatChannelName): boolean;
+};
+
+function resolveChatPluginBindings(
+  context: AgentContext,
+): ChatRuntimeBindings | null {
+  const candidate = context.agent?.pluginInstances?.get?.("chat") as
+    | ChatRuntimeBindings
+    | undefined;
+  return candidate || null;
+}
+
+/**
+ * 创建 chat 渠道状态对象。
+ */
+export function createChatChannelState(): ChatChannelState {
+  return {
+    telegram: null,
+    feishu: null,
+    qq: null,
+  };
+}
+
+/**
+ * 解析并校验渠道名。
+ */
+export function resolveChatChannelNameOrThrow(value: string): ChatChannelName {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (
+    normalized === "telegram" ||
+    normalized === "feishu" ||
+    normalized === "qq"
+  ) {
+    return normalized;
+  }
+  throw new Error(`Invalid channel: ${value}. Use telegram|feishu|qq.`);
+}
+
+/**
+ * 解析目标渠道列表。
+ */
+export function resolveTargetChannels(channel?: ChatChannelName): ChatChannelName[] {
+  return channel ? [channel] : [...CHAT_CHANNEL_NAMES];
+}
+
+/**
+ * 读取渠道绑定的 bot account id。
+ */
+export function resolveChannelAccountId(
+  context: AgentContext,
+  channel: ChatChannelName,
+): string {
+  const plugin = resolveChatPluginBindings(context);
+  const explicit = String(plugin?.getChannelAccountId?.(context, channel) || "").trim();
+  if (explicit) return explicit;
+  const config = context.config.plugins?.chat?.channels?.[channel] as
+    | { channelAccountId?: unknown }
+    | undefined;
+  return String(config?.channelAccountId || "").trim();
+}
+
+/**
+ * 解析渠道 account。
+ *
+ * 关键点（中文）
+ * - 优先使用 ChatPlugin 实例上的显式解析逻辑。
+ * - 若未命中，再回退到默认全局账号池 `~/.downcity/downcity.db`。
+ */
+export function resolveChannelAccount(
+  context: AgentContext,
+  channel: ChatChannelName,
+): StoredChannelAccount | null {
+  const plugin = resolveChatPluginBindings(context);
+  const explicit = plugin?.resolveChannelAccount?.(context, channel);
+  if (explicit) return explicit;
+  const channelAccountId = resolveChannelAccountId(context, channel);
+  const account = channelAccountId
+    ? getStoredChannelAccountSync(channelAccountId)
+    : null;
+  if (!account) return null;
+  if (account.channel !== channel) return null;
+  return account;
+}
+
+/**
+ * 判断渠道 credentials 是否已经配置完整。
+ */
+export function isChannelAccountConfigured(
+  channel: ChatChannelName,
+  account: StoredChannelAccount | null,
+): boolean {
+  if (!account) return false;
+  if (channel === "telegram") {
+    return !!String(account.botToken || "").trim();
+  }
+  return !!String(account.appId || "").trim() && !!String(account.appSecret || "").trim();
+}
+
+/**
+ * 判断指定渠道当前是否启用。
+ */
+export function isChatChannelEnabled(
+  context: AgentContext,
+  channel: ChatChannelName,
+): boolean {
+  const plugin = resolveChatPluginBindings(context);
+  if (typeof plugin?.isChannelEnabled === "function") {
+    return plugin.isChannelEnabled(context, channel);
+  }
+  return context.config.plugins?.chat?.channels?.[channel]?.enabled === true;
+}
+
+/**
+ * 读取当前渠道 bot 实例。
+ */
+export function getChatChannelBot(
+  state: ChatChannelState,
+  channel: ChatChannelName,
+) {
+  if (channel === "telegram") return state.telegram;
+  if (channel === "feishu") return state.feishu;
+  return state.qq;
+}

package/src/chat/runtime/ChatChannelFacade.ts

@@ -0,0 +1,23 @@
+/**
+ * ChatChannelFacade：chat 渠道子模块门面。
+ *
+ * 关键点（中文）
+ * - 这里只负责把 channel 相关子模块重新聚合为一个稳定入口。
+ * - 内部实现已经拆为 core / lifecycle / config / actions 四层。
+ * - 这样可以在不影响 `ChatPlugin` 与 action 调用方的前提下，持续收敛复杂度。
+ */
+
+export {
+  createChatChannelState,
+  resolveChatChannelNameOrThrow,
+} from "./ChatChannelCore.js";
+export { startChatChannels, stopChatChannels } from "./ChatChannelLifecycle.js";
+export {
+  executeChatStatusAction,
+  executeChatTestAction,
+  executeChatReconnectAction,
+  executeChatOpenAction,
+  executeChatCloseAction,
+  executeChatConfigurationAction,
+  executeChatConfigureAction,
+} from "./ChatChannelActions.js";

package/src/chat/runtime/ChatChannelLifecycle.ts

@@ -0,0 +1,169 @@
+/**
+ * ChatChannelLifecycle：chat 渠道生命周期模块。
+ *
+ * 关键点（中文）
+ * - 渠道 bot 的创建、启动、停止逻辑统一收敛在这里。
+ * - 渠道 bot 状态归属于 chat plugin runtime 实例持有的 `ChatChannelState`。
+ * - 本模块不处理 downcity.json 写入，也不负责 action 输入输出包装。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+import { createTelegramBot } from "@/chat/channels/telegram/Bot.js";
+import { createFeishuBot } from "@/chat/channels/feishu/Feishu.js";
+import { createQQBot } from "@/chat/channels/qq/QQ.js";
+import {
+  isChatChannelEnabled,
+  resolveChannelAccount,
+  resolveTargetChannels,
+} from "./ChatChannelCore.js";
+
+async function startTelegramChannel(
+  state: ChatChannelState,
+  context: AgentContext,
+): Promise<void> {
+  if (!isChatChannelEnabled(context, "telegram")) return;
+  context.logger.info("Telegram channel enabled");
+  const account = resolveChannelAccount(context, "telegram");
+  const token = String(account?.botToken || "").trim();
+  if (!token) return;
+  state.telegram = createTelegramBot(
+    {
+      enabled: true,
+      botToken: token,
+    },
+    context,
+  );
+  if (state.telegram) {
+    await state.telegram.start();
+  }
+}
+
+async function startFeishuChannel(
+  state: ChatChannelState,
+  context: AgentContext,
+): Promise<void> {
+  if (!isChatChannelEnabled(context, "feishu")) return;
+  context.logger.info("Feishu channel enabled");
+  const account = resolveChannelAccount(context, "feishu");
+  const appId = String(account?.appId || "").trim();
+  const appSecret = String(account?.appSecret || "").trim();
+  if (!appId || !appSecret) return;
+  state.feishu = await createFeishuBot(
+    {
+      enabled: true,
+      appId,
+      appSecret,
+      domain: String(account?.domain || "").trim() || "https://open.feishu.cn",
+    },
+    context,
+  );
+  if (state.feishu) {
+    await state.feishu.start();
+  }
+}
+
+async function startQQChannel(
+  state: ChatChannelState,
+  context: AgentContext,
+): Promise<void> {
+  if (!isChatChannelEnabled(context, "qq")) return;
+  context.logger.info("QQ channel enabled");
+  const account = resolveChannelAccount(context, "qq");
+  const appId = String(account?.appId || "").trim();
+  const appSecret = String(account?.appSecret || "").trim();
+  if (!appId || !appSecret) return;
+  state.qq = await createQQBot(
+    {
+      enabled: true,
+      appId,
+      appSecret,
+      sandbox: account?.sandbox === true,
+    },
+    context,
+  );
+  if (state.qq) {
+    await state.qq.start();
+  }
+}
+
+/**
+ * 启动单个渠道。
+ */
+export async function startSingleChatChannel(
+  state: ChatChannelState,
+  context: AgentContext,
+  channel: ChatChannelName,
+): Promise<void> {
+  if (channel === "telegram") {
+    await startTelegramChannel(state, context);
+    return;
+  }
+  if (channel === "feishu") {
+    await startFeishuChannel(state, context);
+    return;
+  }
+  await startQQChannel(state, context);
+}
+
+/**
+ * 停止单个渠道。
+ */
+export async function stopSingleChatChannel(
+  state: ChatChannelState,
+  channel: ChatChannelName,
+): Promise<void> {
+  if (channel === "telegram" && state.telegram) {
+    const bot = state.telegram;
+    state.telegram = null;
+    await bot.stop();
+    return;
+  }
+  if (channel === "feishu" && state.feishu) {
+    const bot = state.feishu;
+    state.feishu = null;
+    await bot.stop();
+    return;
+  }
+  if (channel === "qq" && state.qq) {
+    const bot = state.qq;
+    state.qq = null;
+    await bot.stop();
+  }
+}
+
+/**
+ * 启动全部已启用的 chat 渠道。
+ */
+export async function startChatChannels(
+  state: ChatChannelState,
+  context: AgentContext,
+): Promise<void> {
+  if (state.telegram || state.feishu || state.qq) {
+    await stopChatChannels(state);
+  }
+  for (const channel of resolveTargetChannels()) {
+    await startSingleChatChannel(state, context, channel);
+  }
+}
+
+/**
+ * 停止全部 chat 渠道。
+ */
+export async function stopChatChannels(state: ChatChannelState): Promise<void> {
+  const current = { ...state };
+  state.telegram = null;
+  state.feishu = null;
+  state.qq = null;
+
+  if (current.telegram) {
+    await current.telegram.stop();
+  }
+  if (current.feishu) {
+    await current.feishu.stop();
+  }
+  if (current.qq) {
+    await current.qq.stop();
+  }
+}

package/src/chat/runtime/ChatHistoryStore.ts

@@ -0,0 +1,289 @@
+/**
+ * ChatHistoryStore：聊天事件流持久化。
+ *
+ * 关键点（中文）
+ * - 写入 `.downcity/chat/<sessionId>/history.jsonl`（append-only）。
+ * - 记录 inbound（audit/exec）与 outbound 事件。
+ * - 与 session message history 分离，避免审计噪声进入模型上下文。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { generateId } from "@downcity/agent/internal/utils/Id.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+import type {
+  ChatHistoryDirection,
+  ChatHistoryInboundEventV1,
+  ChatHistoryEventV1,
+  ChatHistoryOutboundEventV1,
+  ChatHistoryIngressKind,
+} from "@/chat/types/ChatHistory.js";
+
+function normalizeTrimmedString(value: string | undefined): string {
+  return String(value || "").trim();
+}
+
+function toOptionalTrimmedString(value: string | undefined): string | undefined {
+  const out = normalizeTrimmedString(value);
+  return out ? out : undefined;
+}
+
+function toOptionalFiniteNumber(value: number | undefined): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function toOptionalObject(value: JsonObject | undefined): JsonObject | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value;
+}
+
+function buildInboundEvent(params: {
+  sessionId: string;
+  channel: ChatDispatchChannel;
+  chatId: string;
+  ingressKind: ChatHistoryIngressKind;
+  text: string;
+  targetType?: string;
+  threadId?: number;
+  messageId?: string;
+  actorId?: string;
+  actorName?: string;
+  extra?: JsonObject;
+}): ChatHistoryInboundEventV1 {
+  return {
+    v: 1,
+    id: `chat:${generateId()}`,
+    ts: Date.now(),
+    direction: "inbound",
+    ingressKind: params.ingressKind,
+    sessionId: params.sessionId,
+    channel: params.channel,
+    chatId: params.chatId,
+    text: params.text,
+    ...(params.targetType ? { targetType: params.targetType } : {}),
+    ...(typeof params.threadId === "number" ? { threadId: params.threadId } : {}),
+    ...(params.messageId ? { messageId: params.messageId } : {}),
+    ...(params.actorId ? { actorId: params.actorId } : {}),
+    ...(params.actorName ? { actorName: params.actorName } : {}),
+    ...(params.extra ? { extra: params.extra } : {}),
+  };
+}
+
+function buildOutboundEvent(params: {
+  sessionId: string;
+  channel: ChatDispatchChannel;
+  chatId: string;
+  text: string;
+  targetType?: string;
+  threadId?: number;
+  messageId?: string;
+  actorId?: string;
+  actorName?: string;
+  extra?: JsonObject;
+}): ChatHistoryOutboundEventV1 {
+  return {
+    v: 1,
+    id: `chat:${generateId()}`,
+    ts: Date.now(),
+    direction: "outbound",
+    sessionId: params.sessionId,
+    channel: params.channel,
+    chatId: params.chatId,
+    text: params.text,
+    ...(params.targetType ? { targetType: params.targetType } : {}),
+    ...(typeof params.threadId === "number" ? { threadId: params.threadId } : {}),
+    ...(params.messageId ? { messageId: params.messageId } : {}),
+    ...(params.actorId ? { actorId: params.actorId } : {}),
+    ...(params.actorName ? { actorName: params.actorName } : {}),
+    ...(params.extra ? { extra: params.extra } : {}),
+  };
+}
+
+function isValidHistoryDirection(value: unknown): value is ChatHistoryDirection {
+  return value === "inbound" || value === "outbound";
+}
+
+function isChatHistoryEventV1(value: unknown): value is ChatHistoryEventV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const obj = value as Record<string, unknown>;
+  if (obj.v !== 1) return false;
+  if (!isValidHistoryDirection(obj.direction)) return false;
+  if (typeof obj.id !== "string" || !obj.id.trim()) return false;
+  if (typeof obj.sessionId !== "string" || !obj.sessionId.trim()) return false;
+  if (typeof obj.channel !== "string" || !obj.channel.trim()) return false;
+  if (typeof obj.chatId !== "string" || !obj.chatId.trim()) return false;
+  if (typeof obj.text !== "string") return false;
+  if (typeof obj.ts !== "number" || !Number.isFinite(obj.ts)) return false;
+  if (obj.direction === "inbound") {
+    const ingressKind = obj.ingressKind;
+    if (ingressKind !== "audit" && ingressKind !== "exec") return false;
+  }
+  return true;
+}
+
+/**
+ * 追加一条入站 chat 事件。
+ *
+ * 关键点（中文）
+ * - 该函数只做落盘，不做业务判定。
+ * - 调用方应在入队前调用，以满足“先审计后执行”链路。
+ */
+export async function appendInboundChatHistory(params: {
+  context: AgentContext;
+  sessionId: string;
+  channel: ChatDispatchChannel;
+  chatId: string;
+  ingressKind: ChatHistoryIngressKind;
+  text: string;
+  targetType?: string;
+  threadId?: number;
+  messageId?: string;
+  actorId?: string;
+  actorName?: string;
+  extra?: JsonObject;
+}): Promise<void> {
+  const rootPath = normalizeTrimmedString(params.context.rootPath);
+  const sessionId = normalizeTrimmedString(params.sessionId);
+  const chatId = normalizeTrimmedString(params.chatId);
+  if (!rootPath || !sessionId || !chatId) return;
+
+  const event = buildInboundEvent({
+    sessionId,
+    channel: params.channel,
+    chatId,
+    ingressKind: params.ingressKind,
+    text: String(params.text ?? ""),
+    targetType: toOptionalTrimmedString(params.targetType),
+    threadId: toOptionalFiniteNumber(params.threadId),
+    messageId: toOptionalTrimmedString(params.messageId),
+    actorId: toOptionalTrimmedString(params.actorId),
+    actorName: toOptionalTrimmedString(params.actorName),
+    extra: toOptionalObject(params.extra),
+  });
+
+  const file = params.context.paths.getDowncityChatHistoryPath(sessionId);
+  await fs.ensureDir(path.dirname(file));
+  await fs.appendFile(file, JSON.stringify(event) + "\n", "utf8");
+}
+
+/**
+ * 追加一条出站 chat 事件。
+ *
+ * 关键点（中文）
+ * - 用于记录机器人主动发出的消息，便于后续审计与回放。
+ * - 该函数只做落盘，不影响实际发送链路。
+ */
+export async function appendOutboundChatHistory(params: {
+  context: AgentContext;
+  sessionId: string;
+  channel: ChatDispatchChannel;
+  chatId: string;
+  text: string;
+  targetType?: string;
+  threadId?: number;
+  messageId?: string;
+  actorId?: string;
+  actorName?: string;
+  extra?: JsonObject;
+}): Promise<void> {
+  const rootPath = normalizeTrimmedString(params.context.rootPath);
+  const sessionId = normalizeTrimmedString(params.sessionId);
+  const chatId = normalizeTrimmedString(params.chatId);
+  if (!rootPath || !sessionId || !chatId) return;
+
+  const event = buildOutboundEvent({
+    sessionId,
+    channel: params.channel,
+    chatId,
+    text: String(params.text ?? ""),
+    targetType: toOptionalTrimmedString(params.targetType),
+    threadId: toOptionalFiniteNumber(params.threadId),
+    messageId: toOptionalTrimmedString(params.messageId),
+    actorId: toOptionalTrimmedString(params.actorId),
+    actorName: toOptionalTrimmedString(params.actorName),
+    extra: toOptionalObject(params.extra),
+  });
+
+  const file = params.context.paths.getDowncityChatHistoryPath(sessionId);
+  await fs.ensureDir(path.dirname(file));
+  await fs.appendFile(file, JSON.stringify(event) + "\n", "utf8");
+}
+
+/**
+ * 读取 chat 历史事件（按 sessionId）。
+ *
+ * 关键点（中文）
+ * - 默认返回最近 N 条（按时间升序）。
+ * - 仅做文件读取与过滤，不涉及任何业务 side-effect。
+ */
+export async function readChatHistory(params: {
+  context: AgentContext;
+  sessionId: string;
+  limit?: number;
+  direction?: ChatHistoryDirection | "all";
+  beforeTs?: number;
+  afterTs?: number;
+}): Promise<{ historyPath: string; events: ChatHistoryEventV1[] }> {
+  const rootPath = normalizeTrimmedString(params.context.rootPath);
+  const sessionId = normalizeTrimmedString(params.sessionId);
+  const historyPath = params.context.paths.getDowncityChatHistoryPath(sessionId);
+  if (!rootPath || !sessionId) {
+    return {
+      historyPath,
+      events: [],
+    };
+  }
+
+  const exists = await fs.pathExists(historyPath);
+  if (!exists) {
+    return {
+      historyPath,
+      events: [],
+    };
+  }
+
+  const limitRaw =
+    typeof params.limit === "number" && Number.isFinite(params.limit)
+      ? Math.floor(params.limit)
+      : 30;
+  const limit = Math.max(1, Math.min(limitRaw, 500));
+  const direction =
+    params.direction === "inbound" || params.direction === "outbound"
+      ? params.direction
+      : "all";
+  const beforeTs =
+    typeof params.beforeTs === "number" && Number.isFinite(params.beforeTs)
+      ? params.beforeTs
+      : undefined;
+  const afterTs =
+    typeof params.afterTs === "number" && Number.isFinite(params.afterTs)
+      ? params.afterTs
+      : undefined;
+
+  const content = await fs.readFile(historyPath, "utf8");
+  const out: ChatHistoryEventV1[] = [];
+  const lines = content.split("\n");
+  for (const rawLine of lines) {
+    const line = String(rawLine || "").trim();
+    if (!line) continue;
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isChatHistoryEventV1(parsed)) continue;
+    if (direction !== "all" && parsed.direction !== direction) continue;
+    if (typeof beforeTs === "number" && parsed.ts >= beforeTs) continue;
+    if (typeof afterTs === "number" && parsed.ts <= afterTs) continue;
+    out.push(parsed);
+  }
+
+  return {
+    historyPath,
+    events: out.slice(-limit),
+  };
+}

package/src/chat/runtime/ChatIngressStore.ts

@@ -0,0 +1,68 @@
+/**
+ * ChatIngressStore：统一处理 chat 入站消息的持久化。
+ *
+ * 关键点（中文）
+ * - `exec` 入站的审计记录写到 `chat history`
+ * - 正常 turn 的 session history 落盘统一交给 `session.prompt()`
+ * - 只有极少数非 turn 场景才允许显式补写 `session messages`
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+import { appendInboundChatHistory } from "./ChatHistoryStore.js";
+
+/**
+ * 统一补齐 exec 入站的 context extra。
+ *
+ * 关键点（中文）
+ * - `ingressKind=exec` 是模型上下文需要的最小语义标记
+ * - 调用方原有 extra 保持透传
+ */
+export function buildExecIngressExtra(extra?: JsonObject): JsonObject {
+  return {
+    ...(extra && typeof extra === "object" ? extra : {}),
+    ingressKind: "exec",
+  };
+}
+
+/**
+ * 写入完整 exec 入站记录。
+ *
+ * 流程（中文）
+ * 1. 写 `chat history` 审计流
+ * 2. 不在 ingress 边界提前写 `session messages`
+ *
+ * 说明（中文）
+ * - 这样正常对话 history 会统一在 `session.prompt()` 内部完成落盘。
+ * - 可避免 queue / control / transport 在 session 外重复持久化 user 消息。
+ */
+export async function appendExecIngress(params: {
+  context: AgentContext;
+  sessionId: string;
+  channel: ChatDispatchChannel;
+  chatId: string;
+  text: string;
+  targetType?: string;
+  threadId?: number;
+  messageId?: string;
+  actorId?: string;
+  actorName?: string;
+  extra?: JsonObject;
+}): Promise<void> {
+  const execExtra = buildExecIngressExtra(params.extra);
+  await appendInboundChatHistory({
+    context: params.context,
+    sessionId: params.sessionId,
+    channel: params.channel,
+    chatId: params.chatId,
+    ingressKind: "exec",
+    text: params.text,
+    ...(params.targetType ? { targetType: params.targetType } : {}),
+    ...(typeof params.threadId === "number" ? { threadId: params.threadId } : {}),
+    ...(params.messageId ? { messageId: params.messageId } : {}),
+    ...(params.actorId ? { actorId: params.actorId } : {}),
+    ...(params.actorName ? { actorName: params.actorName } : {}),
+    extra: execExtra,
+  });
+}