@downcity/plugins 1.0.216 → 1.0.236

package/src/chat/types/ChatCommand.ts

@@ -7,53 +7,53 @@
  */
 
 export type ChatSessionSnapshot = {
-  sessionId?: string;
-  chatKey?: string;
+  session_id?: string;
+  chat_key?: string;
   channel?: string;
   chatId?: string;
   messageThreadId?: number;
   chatType?: string;
-  userId?: string;
-  messageId?: string;
+  user_id?: string;
+  message_id?: string;
 };
 
 export type ChatSendRequest = {
   text: string;
-  chatKey?: string;
-  delayMs?: number;
-  sendAtMs?: number;
-  replyToMessage?: boolean;
-  messageId?: string;
+  chat_key?: string;
+  delay_ms?: number;
+  send_at_ms?: number;
+  reply_to_message?: boolean;
+  message_id?: string;
 };
 
 export type ChatSendResponse = {
   success: boolean;
-  chatKey?: string;
+  chat_key?: string;
   error?: string;
 };
 
 export type ChatReactRequest = {
-  chatKey?: string;
-  messageId?: string;
+  chat_key?: string;
+  message_id?: string;
   emoji?: string;
   big?: boolean;
 };
 
 export type ChatReactResponse = {
   success: boolean;
-  chatKey?: string;
-  messageId?: string;
+  chat_key?: string;
+  message_id?: string;
   error?: string;
 };
 
 export type ChatDeleteRequest = {
-  chatKey?: string;
-  sessionId?: string;
+  chat_key?: string;
+  session_id?: string;
 };
 
 export type ChatDeleteResponse = {
   success: boolean;
-  sessionId?: string;
+  session_id?: string;
   deleted?: boolean;
   removedMeta?: boolean;
   removedChatDir?: boolean;
@@ -64,8 +64,8 @@ export type ChatDeleteResponse = {
 export type ChatHistoryDirection = "all" | "inbound" | "outbound";
 
 export type ChatHistoryRequest = {
-  chatKey?: string;
-  sessionId?: string;
+  chat_key?: string;
+  session_id?: string;
   limit?: number;
   direction?: ChatHistoryDirection;
   beforeTs?: number;
@@ -98,7 +98,7 @@ export type ChatListRequest = {
    * 关键词查询。
    *
    * 说明（中文）
-   * - 会在 `sessionId/chatId/chatTitle/actorName/actorId` 中做包含匹配（不区分大小写）。
+   * - 会在 `session_id/chatId/chatTitle/actorName/actorId` 中做包含匹配（不区分大小写）。
    */
   q?: string;
 };
@@ -108,19 +108,19 @@ export type ChatListRequest = {
  */
 export type ChatListItemV1 = {
   /**
-   * 可发送的 chatKey。
+   * 可发送的 chat_key。
    *
    * 关键点（中文）
-   * - 当前实现下 `chatKey === sessionId`。
+   * - 当前实现下 `chat_key === session_id`。
    */
-  chatKey: string;
+  chat_key: string;
   /**
-   * 对外稳定的 sessionId。
+   * 对外稳定的 session_id。
    *
    * 说明（中文）
    * - 当前内部以 session 语义统一建模。
    */
-  sessionId: string;
+  session_id: string;
   /**
    * 渠道类型（telegram/feishu/qq）。
    */
@@ -152,9 +152,9 @@ export type ChatListItemV1 = {
   /**
    * 最近更新的毫秒时间戳。
    */
-  updatedAt: number;
+  updated_at: number;
   /**
-   * `updatedAt` 的 ISO 时间字符串（UTC）。
+   * `updated_at` 的 ISO 时间字符串（UTC）。
    */
   isoUpdatedAt: string;
 };
@@ -164,11 +164,11 @@ export type ChatListItemV1 = {
  */
 export type ChatInfoRequest = {
   /**
-   * 目标 chatKey（不传则尝试读取 DC_CTX_CHAT_KEY / 当前请求上下文）。
+   * 目标 chat_key（不传则尝试读取 DC_CTX_CHAT_KEY / 当前请求上下文）。
    */
-  chatKey?: string;
+  chat_key?: string;
   /**
-   * 显式 sessionId（优先级高于 chatKey）。
+   * 显式 session_id（优先级高于 chat_key）。
    */
-  sessionId?: string;
+  session_id?: string;
 };

package/src/chat/types/ChatDispatcher.ts

@@ -15,8 +15,8 @@ export type ChatDispatchSendTextParams = {
   text: string;
   messageThreadId?: number;
   chatType?: string;
-  messageId?: string;
-  replyToMessage?: boolean;
+  message_id?: string;
+  reply_to_message?: boolean;
 };
 
 export type ChatDispatchSendActionParams = {
@@ -24,7 +24,7 @@ export type ChatDispatchSendActionParams = {
   action: ChatDispatchAction;
   messageThreadId?: number;
   chatType?: string;
-  messageId?: string;
+  message_id?: string;
   reactionEmoji?: string;
   reactionIsBig?: boolean;
 };

package/src/chat/types/ChatHistory.ts

@@ -16,13 +16,13 @@ type ChatHistoryBaseEventV1 = {
   v: 1;
   id: string;
   ts: number;
-  sessionId: string;
+  session_id: string;
   channel: ChatDispatchChannel;
   chatId: string;
   text: string;
   targetType?: string;
   threadId?: number;
-  messageId?: string;
+  message_id?: string;
   actorId?: string;
   actorName?: string;
   extra?: JsonObject;

package/src/chat/types/ChatMeta.ts

@@ -2,7 +2,7 @@
  * ChatMeta：chat plugin runtime 维护的 session 路由元信息。
  *
  * 关键点（中文）
- * - 只描述“如何把 sessionId 路由回平台 chat”
+ * - 只描述“如何把 session_id 路由回平台 chat”
  * - 由 chat plugin runtime 在接收入站消息时更新
  * - 不属于 core context message schema
  */
@@ -13,9 +13,9 @@ export type ChatMetaV1 = {
   /** schema 版本 */
   v: 1;
   /** 更新时间戳（ms） */
-  updatedAt: number;
+  updated_at: number;
   /** 会话 ID */
-  sessionId: string;
+  session_id: string;
   /** 平台通道 */
   channel: ChatDispatchChannel;
   /** 平台 chatId */
@@ -25,7 +25,7 @@ export type ChatMetaV1 = {
   /** 平台 thread/topic ID */
   threadId?: number;
   /** 平台最近消息 ID（QQ/部分平台回包依赖） */
-  messageId?: string;
+  message_id?: string;
   /** 最近发言用户 ID */
   actorId?: string;
   /** 最近发言用户昵称 */

package/src/chat/types/ChatPlugin.ts

@@ -77,11 +77,11 @@ export interface ChatInboundAugmentInput {
   /**
    * 当前 lane / context 对应键。
    */
-  chatKey?: string;
+  chat_key?: string;
   /**
    * 当前消息 ID。
    */
-  messageId?: string;
+  message_id?: string;
   /**
    * 当前工程根目录。
    */
@@ -96,7 +96,7 @@ export interface ChatInboundAugmentInput {
   /**
    * chat plugin runtime 已抽取的正文文本。
    */
-  bodyText?: string;
+  body_text?: string;
   /**
    * plugin 追加的中间文本块。
    *
@@ -121,7 +121,7 @@ export interface ChatReplyDispatchInput {
   /**
    * 当前会话 key。
    */
-  chatKey: string;
+  chat_key: string;
   /**
    * 目标会话 ID。
    */
@@ -129,7 +129,7 @@ export interface ChatReplyDispatchInput {
   /**
    * 目标消息 ID。
    */
-  messageId?: string;
+  message_id?: string;
   /**
    * 当前回复文本。
    */
@@ -155,7 +155,7 @@ export interface ChatReplyEffectInput {
   /**
    * 当前会话 key。
    */
-  chatKey: string;
+  chat_key: string;
   /**
    * 目标会话 ID。
    */
@@ -163,7 +163,7 @@ export interface ChatReplyEffectInput {
   /**
    * 目标消息 ID。
    */
-  messageId?: string;
+  message_id?: string;
   /**
    * 最终尝试发送的文本。
    */
@@ -201,7 +201,7 @@ export interface ChatEnqueuePipelineInput {
   /**
    * 当前 lane / context 键。
    */
-  chatKey: string;
+  chat_key: string;
   /**
    * 目标会话 ID。
    */
@@ -221,7 +221,7 @@ export interface ChatEnqueuePipelineInput {
   /**
    * 消息 ID。
    */
-  messageId?: string;
+  message_id?: string;
   /**
    * 发送者 ID。
    */

package/src/chat/types/ChatPluginActionPayload.ts

@@ -25,25 +25,25 @@ export type ChatSendActionPayload = {
    */
   text: string;
   /**
-   * 目标 chatKey；未显式传入时可由执行上下文补全。
+   * 目标 chat_key；未显式传入时可由执行上下文补全。
    */
-  chatKey?: string;
+  chat_key?: string;
   /**
-   * 延迟发送毫秒数；与 `sendAtMs` 互斥。
+   * 延迟发送毫秒数；与 `send_at_ms` 互斥。
    */
-  delayMs?: number;
+  delay_ms?: number;
   /**
-   * 绝对发送时间戳（毫秒）；与 `delayMs` 互斥。
+   * 绝对发送时间戳（毫秒）；与 `delay_ms` 互斥。
    */
-  sendAtMs?: number;
+  send_at_ms?: number;
   /**
    * 是否使用 reply_to_message 语义回复目标消息。
    */
-  replyToMessage?: boolean;
+  reply_to_message?: boolean;
   /**
    * 显式指定目标消息 ID；通常用于 reply/react 等场景。
    */
-  messageId?: string;
+  message_id?: string;
 };
 
 /**
@@ -51,13 +51,13 @@ export type ChatSendActionPayload = {
  */
 export type ChatSessionActionPayload = {
   /**
-   * 目标 chatKey；与 sessionId 二选一即可。
+   * 目标 chat_key；与 session_id 二选一即可。
    */
-  chatKey?: string;
+  chat_key?: string;
   /**
-   * 目标 sessionId；优先级高于 chatKey。
+   * 目标 session_id；优先级高于 chat_key。
    */
-  sessionId?: string;
+  session_id?: string;
 };
 
 /**
@@ -70,7 +70,7 @@ export type ChatHistoryActionPayload = ChatHistoryRequest;
  */
 export interface ChatHistoryClearActionPayload {
   /** 要清空 Chat 事件历史的 Session 标识。 */
-  sessionId: string;
+  session_id: string;
 }
 
 /**

package/src/chat/types/ChatPluginOptions.ts

@@ -7,10 +7,10 @@
  * - 这样 ChatPlugin 不再理解 Telegram、Feishu、QQ 的具体配置字段。
  */
 
-import type { AgentContext } from "@downcity/agent";
-import type { StoredChannelAccount } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
 import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
+import type { ChatRuntimeAccount } from "@/chat/types/ChatRuntimeAccount.js";
 
 /**
  * Chat channel 对象协议。
@@ -23,15 +23,15 @@ export interface ChatChannel {
   /**
    * 当前 channel 是否启用。
    */
-  isEnabled(context: AgentContext): boolean;
+  isEnabled(context: PluginContext): boolean;
   /**
-   * 当前 channel 绑定的账号池记录 ID。
+   * 当前 channel 来源 Resource 的稳定 ID。
    */
-  getChannelAccountId(context: AgentContext): string;
+  getResourceId(context: PluginContext): string;
   /**
    * 解析当前 channel 的运行态账号。
    */
-  getAccount(context: AgentContext): StoredChannelAccount | null;
+  getAccount(context: PluginContext): ChatRuntimeAccount | null;
 }
 
 /**

package/src/chat/types/ChatPluginResource.ts

@@ -0,0 +1,95 @@
+/**
+ * Chat Plugin Resource 类型。
+ *
+ * 关键点（中文）
+ * - Resource 是 City 解析后传给 Chat Plugin Factory 的完整配置对象。
+ * - `id` 是稳定本地身份，`type` 是渠道判别字段，`name` 等只读字段由 Resolver 写入。
+ * - 凭据仍属于完整 Resource Item，但 CLI 展示时必须根据 Schema 的 `writeOnly` 注解脱敏。
+ */
+
+/** Telegram Bot Resource。 */
+export interface TelegramPluginResource {
+  /** CLI 生成的稳定 Resource ID。 */
+  id: string;
+
+  /** Telegram Resource 判别字段。 */
+  type: "telegram";
+
+  /** Resolver 获取的 Bot 真实名称。 */
+  name: string;
+
+  /** Telegram Bot API Token。 */
+  bot_token: string;
+
+  /** Resolver 获取的 Telegram username。 */
+  username?: string;
+
+  /** Resolver 获取的 Telegram Bot 用户 ID。 */
+  bot_user_id?: string;
+}
+
+/** Feishu / Lark Bot Resource。 */
+export interface FeishuPluginResource {
+  /** CLI 生成的稳定 Resource ID。 */
+  id: string;
+
+  /** Feishu Resource 判别字段。 */
+  type: "feishu";
+
+  /** Resolver 获取的 Bot 真实名称。 */
+  name: string;
+
+  /** Feishu / Lark App ID。 */
+  app_id: string;
+
+  /** Feishu / Lark App Secret。 */
+  app_secret: string;
+
+  /** 可选 Open API Domain。 */
+  domain?: string;
+
+  /** Resolver 获取的 Bot 身份。 */
+  identity?: string;
+
+  /** Resolver 获取的所有者名称。 */
+  owner?: string;
+
+  /** Resolver 获取的创建者名称。 */
+  creator?: string;
+
+  /** Resolver 获取的 Bot 用户 ID。 */
+  bot_user_id?: string;
+}
+
+/** QQ Bot Resource。 */
+export interface QqPluginResource {
+  /** CLI 生成的稳定 Resource ID。 */
+  id: string;
+
+  /** QQ Resource 判别字段。 */
+  type: "qq";
+
+  /** Resolver 获取的 Bot 真实名称。 */
+  name: string;
+
+  /** QQ Bot App ID。 */
+  app_id: string;
+
+  /** QQ Bot App Secret。 */
+  app_secret: string;
+
+  /** 是否使用 QQ 沙箱环境。 */
+  sandbox?: boolean;
+
+  /** Resolver 获取的 Bot 身份。 */
+  identity?: string;
+
+  /** Resolver 获取的 Bot 用户 ID。 */
+  bot_user_id?: string;
+}
+
+/** Chat Plugin 支持的完整 Resource Item。 */
+export type ChatPluginResource =
+  | TelegramPluginResource
+  | FeishuPluginResource
+  | QqPluginResource;

package/src/chat/types/ChatPromptContext.ts

@@ -14,22 +14,22 @@ import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
  */
 export interface ChatEnvironmentPromptInput {
   /**
-   * 当前会话对应的 sessionId。
+   * 当前会话对应的 session_id。
    *
    * 说明（中文）
-   * - 对外统一使用 `sessionId` 语义。
+   * - 对外统一使用 `session_id` 语义。
    * - chat plugin runtime 内部统一按 session 语义路由与持久化。
    */
-  sessionId: string;
+  session_id: string;
 
   /**
-   * 当前 chatKey。
+   * 当前 chat_key。
    *
    * 说明（中文）
-   * - chat plugin runtime 里通常与 `sessionId` 一致。
+   * - chat plugin runtime 里通常与 `session_id` 一致。
    * - 保留独立字段，避免未来路由键语义调整时影响调用方。
    */
-  chatKey: string;
+  chat_key: string;
 
   /**
    * 当前消息来源渠道。
@@ -84,7 +84,7 @@ export interface QueuedUserInfoInput {
    * - 这是本次入站事件对应的平台消息标识。
    * - 保留在 user/request info 中，便于 reply/react 等操作定位本轮输入。
    */
-  messageId?: string;
+  message_id?: string;
 
   /**
    * 当前发言用户 ID。
@@ -92,7 +92,7 @@ export interface QueuedUserInfoInput {
    * 说明（中文）
    * - 来自平台侧用户标识，可能为空或不可得。
    */
-  userId?: string;
+  user_id?: string;
 
   /**
    * 当前发言用户名或昵称。

package/src/chat/types/ChatQueue.ts

@@ -20,11 +20,11 @@ export type ChatQueueItem = {
   kind: ChatQueueItemKind;
   channel: "telegram" | "feishu" | "qq";
   targetId: string;
-  sessionId: string;
+  session_id: string;
   text: string;
   targetType?: string;
   threadId?: number;
-  messageId?: string;
+  message_id?: string;
   actorId?: string;
   actorName?: string;
   extra?: JsonObject;

package/src/chat/types/ChatQueueWorker.ts

@@ -13,13 +13,13 @@ export type ChatQueueWorkerConfig = {
   /**
    * 最大并发 lane 数。
    */
-  maxConcurrency: number;
+  max_concurrency: number;
   /**
    * burst merge 防抖窗口（毫秒）。
    */
-  mergeDebounceMs: number;
+  merge_debounce_ms: number;
   /**
    * burst merge 最长等待时间（毫秒）。
    */
-  mergeMaxWaitMs: number;
+  merge_max_wait_ms: number;
 };

package/src/chat/types/ChatRuntimeAccount.ts

@@ -0,0 +1,52 @@
+/**
+ * Chat Channel 运行时账号快照。
+ *
+ * 关键点（中文）
+ * - 该类型只用于 Channel Adapter 消费宿主已解析的构造参数。
+ * - 它不表达存储、账号池或 Resource 查询能力。
+ * - 生命周期字段用于现有状态与访问控制逻辑，不是 Plugin Resource 的持久化协议。
+ */
+
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+
+/** 一个 Channel 启动所需的完整运行时账号快照。 */
+export interface ChatRuntimeAccount {
+  /** 来源 Resource 或 SDK 调用方提供的稳定 ID。 */
+  id: string;
+
+  /** 账号对应的 Chat Channel 类型。 */
+  channel: ChatChannelName;
+
+  /** 面向用户展示的名称。 */
+  name: string;
+
+  /** 可选平台身份。 */
+  identity?: string;
+
+  /** 可选平台所有者。 */
+  owner?: string;
+
+  /** 可选平台创建者。 */
+  creator?: string;
+
+  /** Telegram Bot Token。 */
+  bot_token?: string;
+
+  /** Feishu 或 QQ App ID。 */
+  app_id?: string;
+
+  /** Feishu 或 QQ App Secret。 */
+  app_secret?: string;
+
+  /** Feishu / Lark API Domain。 */
+  domain?: string;
+
+  /** QQ 是否使用 Sandbox 环境。 */
+  sandbox?: boolean;
+
+  /** 快照创建时间。 */
+  created_at: string;
+
+  /** 快照更新时间。 */
+  updated_at: string;
+}

package/src/chat/types/DirectDispatch.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 仅用于当前 chat assistant 出站解析。
- * - frontmatter metadata 语义与 `downcity chat send` 保持一致，再额外支持 `react`。
+ * - frontmatter metadata 语义与 Chat send action 保持一致，再额外支持 `react`。
  */
 
 import type {
@@ -47,40 +47,40 @@ export interface ResolvedDirectTextPayload {
   /**
    * 最终目标会话键（已回填默认值）。
    */
-  chatKey: string;
+  chat_key: string;
 
   /**
    * 是否以 reply 语义发送正文。
    *
  * 说明（中文）
- * - 语义与 `downcity chat send --reply` 一致。
- * - 当 metadata 提供 `reply: true` 或显式 `messageId` 时自动为 true。
+ * - 语义与 Chat send action 的 `reply` 字段一致。
+ * - 当 metadata 提供 `reply: true` 或显式 `message_id` 时自动为 true。
   */
-  replyToMessage: boolean;
+  reply_to_message: boolean;
 
   /**
    * 可选 reply 目标消息 ID。
    *
    * 说明（中文）
-   * - 来自 metadata 的 `messageId`，或 `reply` 的旧式 messageId 写法。
+   * - 来自 metadata 的 `message_id`，或 `reply` 的旧式 message_id 写法。
    */
-  messageId?: string;
+  message_id?: string;
 
   /**
    * 可选延迟发送毫秒数。
    *
    * 说明（中文）
-   * - 与 `downcity chat send --delay` 对齐。
+   * - 与 Chat send action 的 `delay` 字段对齐。
    */
-  delayMs?: number;
+  delay_ms?: number;
 
   /**
    * 可选定时发送毫秒时间戳。
    *
    * 说明（中文）
-   * - 与 `downcity chat send --time` 对齐。
+   * - 与 Chat send action 的 `time` 字段对齐。
    */
-  sendAtMs?: number;
+  send_at_ms?: number;
 }
 
 /**
@@ -95,7 +95,7 @@ export interface ResolvedDirectReactionPayload {
   /**
    * 最终目标会话键（已回填默认值）。
    */
-  chatKey: string;
+  chat_key: string;
 
   /**
    * 可选目标消息 ID。
@@ -103,7 +103,7 @@ export interface ResolvedDirectReactionPayload {
    * 说明（中文）
    * - 来自主文本 metadata 的 `reply`。
    */
-  messageId?: string;
+  message_id?: string;
 
   /**
    * 是否使用大表情。