@downcity/plugins 1.0.4

package/src/chat/ChatPlugin.ts

@@ -0,0 +1,249 @@
+/**
+ * ChatPlugin：chat plugin 的类实现。
+ *
+ * 关键点（中文）
+ * - chat 的渠道 bot 状态归属于 ChatPlugin 实例。
+ * - chat 的 queue worker 也归属于 ChatPlugin 实例，而不是 agent 入口。
+ * - Index 只保留静态导出入口，这里承接真正的 plugin class 实现。
+ * - action 注册表已经拆到独立模块，当前文件只保留实例骨架。
+ */
+
+import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
+import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
+import type { StoredChannelAccount } from "@downcity/agent/internal/types/runtime/host/Store.js";
+import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
+import type {
+  ChatPluginFeishuOptions,
+  ChatPluginOptions,
+  ChatPluginQqOptions,
+  ChatPluginTelegramOptions,
+} from "@/chat/ChatPluginTypes.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+import {
+  createChatChannelState,
+  startChatChannels,
+  stopChatChannels,
+} from "./runtime/ChatChannelFacade.js";
+import { getStoredChannelAccountSync } from "./accounts/Store.js";
+import { createChatPluginActions } from "./runtime/ChatPluginActions.js";
+import { ChatQueueWorker } from "./runtime/ChatQueueWorker.js";
+import { buildChatPluginSystem } from "./runtime/ChatPluginSystem.js";
+import { ChatQueueStore } from "./runtime/ChatQueueStore.js";
+
+/**
+ * Chat plugin 类实现。
+ */
+export class ChatPlugin extends BasePlugin {
+  /**
+   * plugin 名称。
+   */
+  readonly name = "chat";
+
+  /**
+   * 当前实例持有的渠道状态。
+   */
+  public readonly channelState: ChatChannelState = createChatChannelState();
+
+  /**
+   * 当前实例持有的 chat queue worker。
+   *
+   * 关键点（中文）
+   * - worker 生命周期与 chat plugin 保持一致。
+   * - 这样 agent 只负责装配，不直接持有 chat 领域长期状态。
+   */
+  public queueWorker: ChatQueueWorker | null = null;
+
+  /**
+   * 当前实例持有的 chat queue store。
+   *
+   * 关键点（中文）
+   * - 这是 chat queue 状态的实例归属起点。
+   * - 迁移完成后，入队路径也会统一走这里，而不是模块级全局 queue。
+   */
+  public readonly queueStore = new ChatQueueStore();
+
+  /**
+   * 当前实例持有的显式 plugin 配置。
+   */
+  public readonly options: ChatPluginOptions;
+
+  /**
+   * 当前 plugin 的 system 文本构建器。
+   */
+  readonly system = async (context: AgentContext): Promise<string> => {
+    return await buildChatPluginSystem(context);
+  };
+
+  /**
+   * 当前 plugin 的 action 定义表。
+   */
+  readonly actions: PluginActions;
+
+  /**
+   * 启动当前实例的 queue worker。
+   */
+  private startQueueWorker(context: AgentContext): void {
+    if (this.queueWorker) return;
+    const worker = new ChatQueueWorker({
+      logger: context.logger,
+      context,
+      queueStore: this.queueStore,
+      config: this.getQueueWorkerConfig(context),
+    });
+    worker.start();
+    this.queueWorker = worker;
+  }
+
+  /**
+   * 停止当前实例的 queue worker。
+   */
+  private stopQueueWorker(): void {
+    const worker = this.queueWorker;
+    this.queueWorker = null;
+    if (!worker) return;
+    worker.stop();
+  }
+
+  constructor(optionsOrAgent?: ChatPluginOptions | AgentRuntime | null) {
+    super(isAgentRuntimeInput(optionsOrAgent) ? optionsOrAgent : null);
+    this.options = isAgentRuntimeInput(optionsOrAgent)
+      ? {}
+      : (optionsOrAgent || {});
+    this.actions = createChatPluginActions({
+      channelState: this.channelState,
+    });
+    this.lifecycle = {
+      start: async (context) => {
+        this.startQueueWorker(context);
+        await startChatChannels(this.channelState, context);
+      },
+      stop: async () => {
+        this.stopQueueWorker();
+        await stopChatChannels(this.channelState);
+      },
+    };
+  }
+
+  /**
+   * 读取 queue worker 配置。
+   */
+  getQueueWorkerConfig(
+    context: AgentContext,
+  ): Partial<ChatQueueWorkerConfig> | undefined {
+    return this.options.queue || context.config.plugins?.chat?.queue;
+  }
+
+  /**
+   * 判断指定渠道是否启用。
+   */
+  isChannelEnabled(context: AgentContext, channel: ChatChannelName): boolean {
+    const explicit = this.getExplicitChannelOptions(channel);
+    if (explicit) {
+      return explicit.enabled !== false;
+    }
+    return context.config.plugins?.chat?.channels?.[channel]?.enabled === true;
+  }
+
+  /**
+   * 读取指定渠道的显式账户 ID。
+   */
+  getChannelAccountId(
+    context: AgentContext,
+    channel: ChatChannelName,
+  ): string {
+    const explicit = this.getExplicitChannelOptions(channel);
+    const explicitAccountId = String(explicit?.channelAccountId || "").trim();
+    if (explicitAccountId) return explicitAccountId;
+    const config = context.config.plugins?.chat?.channels?.[channel] as
+      | { channelAccountId?: unknown }
+      | undefined;
+    return String(config?.channelAccountId || "").trim();
+  }
+
+  /**
+   * 解析指定渠道当前应使用的账户。
+   */
+  resolveChannelAccount(
+    context: AgentContext,
+    channel: ChatChannelName,
+  ): StoredChannelAccount | null {
+    const explicit = this.buildExplicitChannelAccount(channel);
+    if (explicit) return explicit;
+    const channelAccountId = this.getChannelAccountId(context, channel);
+    if (!channelAccountId) return null;
+    return getStoredChannelAccountSync(channelAccountId);
+  }
+
+  private getExplicitChannelOptions(
+    channel: ChatChannelName,
+  ): ChatPluginTelegramOptions | ChatPluginFeishuOptions | ChatPluginQqOptions | undefined {
+    if (channel === "telegram") return this.options.telegram;
+    if (channel === "feishu") return this.options.feishu;
+    return this.options.qq;
+  }
+
+  private buildExplicitChannelAccount(
+    channel: ChatChannelName,
+  ): StoredChannelAccount | null {
+    const now = new Date().toISOString();
+
+    if (channel === "telegram") {
+      const config = this.options.telegram;
+      const botToken = String(config?.botToken || "").trim();
+      if (!botToken) return null;
+      return {
+        id: String(config?.channelAccountId || `chat-sdk-${channel}`).trim(),
+        channel,
+        name: String(config?.name || "telegram").trim() || "telegram",
+        botToken,
+        createdAt: now,
+        updatedAt: now,
+      };
+    }
+
+    if (channel === "feishu") {
+      const config = this.options.feishu;
+      const appId = String(config?.appId || "").trim();
+      const appSecret = String(config?.appSecret || "").trim();
+      if (!appId || !appSecret) return null;
+      return {
+        id: String(config?.channelAccountId || `chat-sdk-${channel}`).trim(),
+        channel,
+        name: String(config?.name || "feishu").trim() || "feishu",
+        appId,
+        appSecret,
+        ...(String(config?.domain || "").trim()
+          ? { domain: String(config?.domain || "").trim() }
+          : {}),
+        createdAt: now,
+        updatedAt: now,
+      };
+    }
+
+    const config = this.options.qq;
+    const appId = String(config?.appId || "").trim();
+    const appSecret = String(config?.appSecret || "").trim();
+    if (!appId || !appSecret) return null;
+    return {
+      id: String(config?.channelAccountId || `chat-sdk-${channel}`).trim(),
+      channel,
+      name: String(config?.name || "qq").trim() || "qq",
+      appId,
+      appSecret,
+      ...(config?.sandbox === true ? { sandbox: true } : {}),
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+}
+
+function isAgentRuntimeInput(
+  input: ChatPluginOptions | AgentRuntime | null | undefined,
+): input is AgentRuntime | null {
+  if (input === null) return true;
+  if (!input || typeof input !== "object") return false;
+  return typeof (input as AgentRuntime).getSession === "function";
+}

package/src/chat/ChatPluginTypes.ts

@@ -0,0 +1,126 @@
+/**
+ * ChatPlugin SDK / runtime 配置类型。
+ *
+ * 关键点（中文）
+ * - 这里定义 `new ChatPlugin({...})` 的显式注入接口。
+ * - 构造参数只承载显式渠道配置与 queue 行为，不再承载自定义存储/解析器注入。
+ * - 若未显式提供渠道凭据，ChatPlugin 会直接回退到默认全局账号池 `~/.downcity/downcity.db`。
+ */
+
+import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
+
+/**
+ * Telegram 显式渠道配置。
+ */
+export interface ChatPluginTelegramOptions {
+  /**
+   * 是否启用当前渠道。
+   *
+   * 说明（中文）
+   * - 省略时，若显式提供了 `botToken`，默认视为启用。
+   * - 传入 `false` 时会强制关闭，即使提供了凭据也不会启动。
+   */
+  enabled?: boolean;
+  /**
+   * Telegram Bot Token。
+   */
+  botToken: string;
+  /**
+   * 可选的显式账户 ID。
+   *
+   * 说明（中文）
+   * - 主要用于让上层产品把 runtime 渠道与自己的 account 池关联起来。
+   * - 省略时会使用 runtime 合成的临时 ID。
+   */
+  channelAccountId?: string;
+  /**
+   * 渠道展示名。
+   */
+  name?: string;
+}
+
+/**
+ * Feishu 显式渠道配置。
+ */
+export interface ChatPluginFeishuOptions {
+  /**
+   * 是否启用当前渠道。
+   */
+  enabled?: boolean;
+  /**
+   * Feishu / Lark App ID。
+   */
+  appId: string;
+  /**
+   * Feishu / Lark App Secret。
+   */
+  appSecret: string;
+  /**
+   * 可选的 Open API 域名。
+   */
+  domain?: string;
+  /**
+   * 可选的显式账户 ID。
+   */
+  channelAccountId?: string;
+  /**
+   * 渠道展示名。
+   */
+  name?: string;
+}
+
+/**
+ * QQ 显式渠道配置。
+ */
+export interface ChatPluginQqOptions {
+  /**
+   * 是否启用当前渠道。
+   */
+  enabled?: boolean;
+  /**
+   * QQ Bot App ID。
+   */
+  appId: string;
+  /**
+   * QQ Bot App Secret。
+   */
+  appSecret: string;
+  /**
+   * 是否使用 QQ 沙箱模式。
+   */
+  sandbox?: boolean;
+  /**
+   * 可选的显式账户 ID。
+   */
+  channelAccountId?: string;
+  /**
+   * 渠道展示名。
+   */
+  name?: string;
+}
+
+/**
+ * ChatPlugin 显式构造参数。
+ */
+export interface ChatPluginOptions {
+  /**
+   * Chat queue worker 运行配置。
+   *
+   * 说明（中文）
+   * - 显式传入时优先级高于 `downcity.json.plugins.chat.queue`。
+   * - 可用于不同 client 定制并发、突发合并等行为。
+   */
+  queue?: Partial<ChatQueueWorkerConfig>;
+  /**
+   * Telegram 渠道显式配置。
+   */
+  telegram?: ChatPluginTelegramOptions;
+  /**
+   * Feishu 渠道显式配置。
+   */
+  feishu?: ChatPluginFeishuOptions;
+  /**
+   * QQ 渠道显式配置。
+   */
+  qq?: ChatPluginQqOptions;
+}

package/src/chat/Index.ts

@@ -0,0 +1,8 @@
+/**
+ * Chat Plugin 导出入口。
+ *
+ * 关键点（中文）
+ * - Index 只负责导出类实现。
+ * - 真正的类实现位于 `ChatPlugin.ts`。
+ */
+export { ChatPlugin } from "./ChatPlugin.js";

package/src/chat/PROMPT.direct.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/chat/PROMPT.direct.ts.txt
+const TEXT_MODULE_CONTENT = "# Chat Plugin 使用说明\n\n## 用户可见回复规则\n\n- 当前模式下，直接输出，即会发送消息给到用户对应的channel\n\n## 输出协议\n\n- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 `city chat send` 保持一致：\n\n- `delay` / `delayMs`：延迟发送毫秒数。\n- `time` / `sendAt` / `sendAtMs`：定时发送时间。\n- `reply`：是否使用 reply 语义发送。\n- `messageId`：目标 `message_id`（群聊推荐）。\n- `react`：发送表情反应。\n  - 单个字符串：`react: \"👍\"`\n  - 或对象/数组：`emoji/big`\n  - 设置 `messageId` 时，`react` 会优先复用该消息作为目标消息。\n- 附件使用 `<file type=\"...\">path</file>`（支持 `document/photo/voice/audio/video`）。\n- 附件路径必须是项目内可访问的相对路径。多附件可输出多个 `<file>` 标签。\n\n### 示例\n\n```text\n---\nreply: true\nmessageId: \"128\"\nreact:\n  - emoji: \"✅\"\n---\n这是今天的报告。\n<file type=\"document\">reports/daily.md</file>\n```\n\n### 协议约束\n\n- frontmatter 必须位于文本最开头（`---` 包裹）。\n- 除 `<file>` 附件标签外，不要使用尖括号格式做控制参数。\n\n## 跨协议/跨平台操作\n\n- 当任务需要跨会话、跨平台或复杂路由，必须使用 `city chat send` / `city chat react`。\n- metadata 只适用于当前会话内的 direct 出站，不要拿 metadata 做跨 chat 路由。\n- 如果需要跨 chat 发送，或者不清楚怎么发送，直接先调用 `city chat --help` 查看方法。\n- 如不确定参数或正文协议，先自行调用：\n  - `city chat --help`\n  - `city chat send --help`\n  - `city chat react --help`\n\n## 入站消息结构（仅供内部理解）\n\n- 每条入队用户消息包含 `<info>...</info>` 元信息块 + 用户正文。\n- `<info>` 仅保留 user/request 元信息，例如 `user_id`、`username`、`message_id`、`permissions`、`received_at`。\n- 当前 chat 路由环境（例如 `channel`、`session_id`、`chat_key`、`chat_id`）会通过 system prompt 单独注入，不再混在 `<info>` 里。\n- `<info>` 不要原样回传给用户。\n";
+
+export default TEXT_MODULE_CONTENT;

package/src/chat/PROMPT.direct.ts.txt

@@ -0,0 +1,55 @@
+# Chat Plugin 使用说明
+
+## 用户可见回复规则
+
+- 当前模式下，直接输出，即会发送消息给到用户对应的channel
+
+## 输出协议
+
+- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 `city chat send` 保持一致：
+
+- `delay` / `delayMs`：延迟发送毫秒数。
+- `time` / `sendAt` / `sendAtMs`：定时发送时间。
+- `reply`：是否使用 reply 语义发送。
+- `messageId`：目标 `message_id`（群聊推荐）。
+- `react`：发送表情反应。
+  - 单个字符串：`react: "👍"`
+  - 或对象/数组：`emoji/big`
+  - 设置 `messageId` 时，`react` 会优先复用该消息作为目标消息。
+- 附件使用 `<file type="...">path</file>`（支持 `document/photo/voice/audio/video`）。
+- 附件路径必须是项目内可访问的相对路径。多附件可输出多个 `<file>` 标签。
+
+### 示例
+
+```text
+---
+reply: true
+messageId: "128"
+react:
+  - emoji: "✅"
+---
+这是今天的报告。
+<file type="document">reports/daily.md</file>
+```
+
+### 协议约束
+
+- frontmatter 必须位于文本最开头（`---` 包裹）。
+- 除 `<file>` 附件标签外，不要使用尖括号格式做控制参数。
+
+## 跨协议/跨平台操作
+
+- 当任务需要跨会话、跨平台或复杂路由，必须使用 `city chat send` / `city chat react`。
+- metadata 只适用于当前会话内的 direct 出站，不要拿 metadata 做跨 chat 路由。
+- 如果需要跨 chat 发送，或者不清楚怎么发送，直接先调用 `city chat --help` 查看方法。
+- 如不确定参数或正文协议，先自行调用：
+  - `city chat --help`
+  - `city chat send --help`
+  - `city chat react --help`
+
+## 入站消息结构（仅供内部理解）
+
+- 每条入队用户消息包含 `<info>...</info>` 元信息块 + 用户正文。
+- `<info>` 仅保留 user/request 元信息，例如 `user_id`、`username`、`message_id`、`permissions`、`received_at`。
+- 当前 chat 路由环境（例如 `channel`、`session_id`、`chat_key`、`chat_id`）会通过 system prompt 单独注入，不再混在 `<info>` 里。
+- `<info>` 不要原样回传给用户。