@downcity/plugins 1.0.4

package/src/chat/types/ChatCommand.ts

@@ -0,0 +1,174 @@
+/**
+ * Chat 命令协议类型。
+ *
+ * 关键点（中文）
+ * - chat 模块自有请求/响应类型放在 chat/types
+ * - 避免所有业务类型集中堆到全局 types/
+ */
+
+export type ChatSessionSnapshot = {
+  sessionId?: string;
+  chatKey?: string;
+  channel?: string;
+  chatId?: string;
+  messageThreadId?: number;
+  chatType?: string;
+  userId?: string;
+  messageId?: string;
+};
+
+export type ChatSendRequest = {
+  text: string;
+  chatKey?: string;
+  delayMs?: number;
+  sendAtMs?: number;
+  replyToMessage?: boolean;
+  messageId?: string;
+};
+
+export type ChatSendResponse = {
+  success: boolean;
+  chatKey?: string;
+  error?: string;
+};
+
+export type ChatReactRequest = {
+  chatKey?: string;
+  messageId?: string;
+  emoji?: string;
+  big?: boolean;
+};
+
+export type ChatReactResponse = {
+  success: boolean;
+  chatKey?: string;
+  messageId?: string;
+  error?: string;
+};
+
+export type ChatDeleteRequest = {
+  chatKey?: string;
+  sessionId?: string;
+};
+
+export type ChatDeleteResponse = {
+  success: boolean;
+  sessionId?: string;
+  deleted?: boolean;
+  removedMeta?: boolean;
+  removedChatDir?: boolean;
+  removedSessionDir?: boolean;
+  error?: string;
+};
+
+export type ChatHistoryDirection = "all" | "inbound" | "outbound";
+
+export type ChatHistoryRequest = {
+  chatKey?: string;
+  sessionId?: string;
+  limit?: number;
+  direction?: ChatHistoryDirection;
+  beforeTs?: number;
+  afterTs?: number;
+};
+
+/**
+ * Chat 会话列表请求。
+ *
+ * 关键点（中文）
+ * - 仅列出当前 agent 本地已记录的 chat context（来自 `.downcity/channel/meta.json`）。
+ * - 不会向外部平台拉取“全部会话”，因为平台侧通常需要额外权限且成本高。
+ */
+export type ChatListRequest = {
+  /**
+   * 渠道过滤（telegram/feishu/qq）。
+   *
+   * 说明（中文）
+   * - 不传则返回全部渠道。
+   */
+  channel?: string;
+  /**
+   * 返回条数上限。
+   *
+   * 说明（中文）
+   * - 不传则使用默认值（由服务端决定）。
+   */
+  limit?: number;
+  /**
+   * 关键词查询。
+   *
+   * 说明（中文）
+   * - 会在 `sessionId/chatId/chatTitle/actorName/actorId` 中做包含匹配（不区分大小写）。
+   */
+  q?: string;
+};
+
+/**
+ * Chat 会话列表条目（用于展示）。
+ */
+export type ChatListItemV1 = {
+  /**
+   * 可发送的 chatKey。
+   *
+   * 关键点（中文）
+   * - 当前实现下 `chatKey === sessionId`。
+   */
+  chatKey: string;
+  /**
+   * 对外稳定的 sessionId。
+   *
+   * 说明（中文）
+   * - 当前内部以 session 语义统一建模。
+   */
+  sessionId: string;
+  /**
+   * 渠道类型（telegram/feishu/qq）。
+   */
+  channel: string;
+  /**
+   * 平台 chat 原始 ID。
+   */
+  chatId: string;
+  /**
+   * 平台 chat 类型（group/c2c/channel/p2p...）。
+   */
+  targetType?: string;
+  /**
+   * 平台 thread/topic ID（仅部分渠道存在）。
+   */
+  threadId?: number;
+  /**
+   * 会话展示名（群名/频道名/私聊对象名）。
+   */
+  chatTitle?: string;
+  /**
+   * 最近触发该会话的用户名/昵称（best-effort）。
+   */
+  actorName?: string;
+  /**
+   * 最近触发该会话的用户 ID（best-effort）。
+   */
+  actorId?: string;
+  /**
+   * 最近更新的毫秒时间戳。
+   */
+  updatedAt: number;
+  /**
+   * `updatedAt` 的 ISO 时间字符串（UTC）。
+   */
+  isoUpdatedAt: string;
+};
+
+/**
+ * Chat 会话信息请求（查看单个会话的元信息与本地路径）。
+ */
+export type ChatInfoRequest = {
+  /**
+   * 目标 chatKey（不传则尝试读取 DC_CTX_CHAT_KEY / 当前请求上下文）。
+   */
+  chatKey?: string;
+  /**
+   * 显式 sessionId（优先级高于 chatKey）。
+   */
+  sessionId?: string;
+};

package/src/chat/types/ChatDispatcher.ts

@@ -0,0 +1,42 @@
+/**
+ * Chat egress dispatcher types（对外回包能力的类型定义）。
+ *
+ * 关键点（中文）
+ * - dispatcher 只关心“怎么把消息/动作发回平台”
+ * - sendText 是必需能力；sendAction（如 typing）是可选能力
+ */
+
+export type ChatDispatchChannel = "telegram" | "feishu" | "qq";
+
+export type ChatDispatchAction = "typing" | "react";
+
+export type ChatDispatchSendTextParams = {
+  chatId: string;
+  text: string;
+  messageThreadId?: number;
+  chatType?: string;
+  messageId?: string;
+  replyToMessage?: boolean;
+};
+
+export type ChatDispatchSendActionParams = {
+  chatId: string;
+  action: ChatDispatchAction;
+  messageThreadId?: number;
+  chatType?: string;
+  messageId?: string;
+  reactionEmoji?: string;
+  reactionIsBig?: boolean;
+};
+
+export interface ChatDispatcher {
+  sendText(params: ChatDispatchSendTextParams): Promise<{
+    success: boolean;
+    error?: string;
+  }>;
+
+  sendAction?(params: ChatDispatchSendActionParams): Promise<{
+    success: boolean;
+    error?: string;
+  }>;
+}

package/src/chat/types/ChatHistory.ts

@@ -0,0 +1,42 @@
+/**
+ * ChatHistory 类型定义。
+ *
+ * 关键点（中文）
+ * - chat history 是聊天平台事件流（审计向），与 session message history 分离。
+ * - 支持入站（inbound）与出站（outbound）事件，便于完整回放对话链路。
+ */
+
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+
+export type ChatHistoryIngressKind = "audit" | "exec";
+export type ChatHistoryDirection = "inbound" | "outbound";
+
+type ChatHistoryBaseEventV1 = {
+  v: 1;
+  id: string;
+  ts: number;
+  sessionId: string;
+  channel: ChatDispatchChannel;
+  chatId: string;
+  text: string;
+  targetType?: string;
+  threadId?: number;
+  messageId?: string;
+  actorId?: string;
+  actorName?: string;
+  extra?: JsonObject;
+};
+
+export type ChatHistoryInboundEventV1 = ChatHistoryBaseEventV1 & {
+  direction: "inbound";
+  ingressKind: ChatHistoryIngressKind;
+};
+
+export type ChatHistoryOutboundEventV1 = ChatHistoryBaseEventV1 & {
+  direction: "outbound";
+};
+
+export type ChatHistoryEventV1 =
+  | ChatHistoryInboundEventV1
+  | ChatHistoryOutboundEventV1;

package/src/chat/types/ChatMeta.ts

@@ -0,0 +1,35 @@
+/**
+ * ChatMeta：chat plugin runtime 维护的 session 路由元信息。
+ *
+ * 关键点（中文）
+ * - 只描述“如何把 sessionId 路由回平台 chat”
+ * - 由 chat plugin runtime 在接收入站消息时更新
+ * - 不属于 core context message schema
+ */
+
+import type { ChatDispatchChannel } from "./ChatDispatcher.js";
+
+export type ChatMetaV1 = {
+  /** schema 版本 */
+  v: 1;
+  /** 更新时间戳（ms） */
+  updatedAt: number;
+  /** 会话 ID */
+  sessionId: string;
+  /** 平台通道 */
+  channel: ChatDispatchChannel;
+  /** 平台 chatId */
+  chatId: string;
+  /** 平台 chatType（group/private/topic/c2c/channel...） */
+  targetType?: string;
+  /** 平台 thread/topic ID */
+  threadId?: number;
+  /** 平台最近消息 ID（QQ/部分平台回包依赖） */
+  messageId?: string;
+  /** 最近发言用户 ID */
+  actorId?: string;
+  /** 最近发言用户昵称 */
+  actorName?: string;
+  /** 会话展示名（群名/频道名/私聊对象名） */
+  chatTitle?: string;
+};

package/src/chat/types/ChatPlugin.ts

@@ -0,0 +1,251 @@
+/**
+ * Chat plugin 交互类型定义。
+ *
+ * 关键点（中文）
+ * - 统一描述 chat plugin runtime 与 plugin 之间的扩展 payload。
+ * - chat plugin runtime 负责定义结构，plugin 只消费这些稳定字段。
+ * - 字段全部保持 Json 兼容，避免把函数或运行时私有对象塞进 plugin 点。
+ */
+
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+
+/**
+ * chat 入站附件类型。
+ */
+export type ChatPluginAttachmentKind =
+  | "document"
+  | "photo"
+  | "voice"
+  | "audio"
+  | "video"
+  | "unknown";
+
+/**
+ * chat plugin 可见的入站附件描述。
+ */
+export interface ChatPluginAttachment {
+  /**
+   * 当前消息来源渠道。
+   */
+  channel: ChatDispatchChannel;
+  /**
+   * 归一化后的附件类型。
+   */
+  kind: ChatPluginAttachmentKind;
+  /**
+   * 附件本地绝对路径。
+   *
+   * 说明（中文）
+   * - 若 chat plugin runtime 尚未把附件落地，则该字段可为空。
+   * - 依赖本地文件的 plugin 应在缺失时跳过处理。
+   */
+  path?: string;
+  /**
+   * 附件展示描述。
+   */
+  desc?: string;
+  /**
+   * 附件文件名。
+   */
+  fileName?: string;
+  /**
+   * MIME 类型。
+   */
+  contentType?: string;
+  /**
+   * 平台附件 ID。
+   */
+  attachmentId?: string;
+}
+
+/**
+ * chat 入站增强输入。
+ */
+export interface ChatInboundAugmentInput {
+  /**
+   * 当前消息来源渠道。
+   */
+  channel: ChatDispatchChannel;
+  /**
+   * 当前会话 ID。
+   */
+  chatId: string;
+  /**
+   * 当前消息所属会话类型。
+   */
+  chatType?: string;
+  /**
+   * 当前 lane / context 对应键。
+   */
+  chatKey?: string;
+  /**
+   * 当前消息 ID。
+   */
+  messageId?: string;
+  /**
+   * 当前工程根目录。
+   */
+  rootPath: string;
+  /**
+   * chat plugin runtime 已生成的附件文本块。
+   *
+   * 说明（中文）
+   * - 一般是 `<file ...>` 标签拼接后的结果。
+   */
+  attachmentText?: string;
+  /**
+   * chat plugin runtime 已抽取的正文文本。
+   */
+  bodyText?: string;
+  /**
+   * plugin 追加的中间文本块。
+   *
+   * 说明（中文）
+   * - pipeline 默认在这里继续追加内容，例如语音转写。
+   */
+  pluginSections?: string[];
+  /**
+   * 归一化后的附件列表。
+   */
+  attachments: ChatPluginAttachment[];
+}
+
+/**
+ * chat 回复前文本管道输入。
+ */
+export interface ChatReplyDispatchInput {
+  /**
+   * 当前消息来源渠道。
+   */
+  channel?: ChatDispatchChannel;
+  /**
+   * 当前会话 key。
+   */
+  chatKey: string;
+  /**
+   * 目标会话 ID。
+   */
+  chatId?: string;
+  /**
+   * 目标消息 ID。
+   */
+  messageId?: string;
+  /**
+   * 当前回复文本。
+   */
+  text: string;
+  /**
+   * 当前回复阶段。
+   */
+  phase: "step" | "final" | "error";
+  /**
+   * 当前分发模式。
+   */
+  mode: "direct" | "fallback";
+}
+
+/**
+ * chat 回复后事件输入。
+ */
+export interface ChatReplyEffectInput {
+  /**
+   * 当前消息来源渠道。
+   */
+  channel?: ChatDispatchChannel;
+  /**
+   * 当前会话 key。
+   */
+  chatKey: string;
+  /**
+   * 目标会话 ID。
+   */
+  chatId?: string;
+  /**
+   * 目标消息 ID。
+   */
+  messageId?: string;
+  /**
+   * 最终尝试发送的文本。
+   */
+  text: string;
+  /**
+   * 当前回复阶段。
+   */
+  phase: "step" | "final" | "error";
+  /**
+   * 当前分发模式。
+   */
+  mode: "direct" | "fallback";
+  /**
+   * 本次发送是否成功。
+   */
+  success: boolean;
+  /**
+   * 错误信息。
+   */
+  error?: string;
+}
+
+/**
+ * chat 入队前管道输入。
+ */
+export interface ChatEnqueuePipelineInput {
+  /**
+   * 入队类型。
+   */
+  kind: "exec" | "audit";
+  /**
+   * 当前消息来源渠道。
+   */
+  channel: ChatDispatchChannel;
+  /**
+   * 当前 lane / context 键。
+   */
+  chatKey: string;
+  /**
+   * 目标会话 ID。
+   */
+  chatId: string;
+  /**
+   * 当前消息文本。
+   */
+  text: string;
+  /**
+   * 会话类型。
+   */
+  chatType?: string;
+  /**
+   * 线程 ID。
+   */
+  threadId?: number;
+  /**
+   * 消息 ID。
+   */
+  messageId?: string;
+  /**
+   * 发送者 ID。
+   */
+  actorId?: string;
+  /**
+   * 发送者名称。
+   */
+  actorName?: string;
+  /**
+   * 附加元信息。
+   */
+  extra?: Record<string, unknown>;
+}
+
+/**
+ * chat 入队后事件输入。
+ */
+export interface ChatEnqueueEffectInput extends ChatEnqueuePipelineInput {
+  /**
+   * 队列项 ID。
+   */
+  itemId: string;
+  /**
+   * 当前 lane 排队位置。
+   */
+  lanePosition: number;
+}

package/src/chat/types/ChatPluginActionPayload.ts

@@ -0,0 +1,165 @@
+/**
+ * ChatPlugin action 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 chat plugin runtime action 的输入 payload。
+ * - 这些类型属于跨模块共享契约，因此统一放到 `types/` 下。
+ * - 字段命名保持与 CLI/API 参数一致，降低映射心智负担。
+ */
+
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type {
+  ChatDeleteRequest,
+  ChatHistoryRequest,
+  ChatInfoRequest,
+  ChatListRequest,
+  ChatReactRequest,
+} from "@/chat/types/ChatCommand.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+
+/**
+ * `chat.send` action 的输入载荷。
+ */
+export type ChatSendActionPayload = {
+  /**
+   * 要发送的正文文本。
+   */
+  text: string;
+  /**
+   * 目标 chatKey；未显式传入时可由执行上下文补全。
+   */
+  chatKey?: string;
+  /**
+   * 延迟发送毫秒数；与 `sendAtMs` 互斥。
+   */
+  delayMs?: number;
+  /**
+   * 绝对发送时间戳（毫秒）；与 `delayMs` 互斥。
+   */
+  sendAtMs?: number;
+  /**
+   * 是否使用 reply_to_message 语义回复目标消息。
+   */
+  replyToMessage?: boolean;
+  /**
+   * 显式指定目标消息 ID；通常用于 reply/react 等场景。
+   */
+  messageId?: string;
+};
+
+/**
+ * 读取会话上下文类 action 的输入载荷。
+ */
+export type ChatSessionActionPayload = {
+  /**
+   * 目标 chatKey；与 sessionId 二选一即可。
+   */
+  chatKey?: string;
+  /**
+   * 目标 sessionId；优先级高于 chatKey。
+   */
+  sessionId?: string;
+};
+
+/**
+ * `chat.history` action 的输入载荷。
+ */
+export type ChatHistoryActionPayload = ChatHistoryRequest;
+
+/**
+ * `chat.react` action 的输入载荷。
+ */
+export type ChatReactActionPayload = ChatReactRequest;
+
+/**
+ * `chat.delete` action 的输入载荷。
+ */
+export type ChatDeleteActionPayload = ChatDeleteRequest;
+
+/**
+ * `chat.list` action 的输入载荷。
+ */
+export type ChatListActionPayload = ChatListRequest;
+
+/**
+ * `chat.info` action 的输入载荷。
+ */
+export type ChatInfoActionPayload = ChatInfoRequest;
+
+/**
+ * `chat.status` action 的输入载荷。
+ */
+export type ChatStatusActionPayload = {
+  /**
+   * 指定目标渠道；省略时表示全部渠道。
+   */
+  channel?: ChatChannelName;
+};
+
+/**
+ * `chat.test` action 的输入载荷。
+ */
+export type ChatTestActionPayload = {
+  /**
+   * 指定目标渠道；省略时表示全部渠道。
+   */
+  channel?: ChatChannelName;
+};
+
+/**
+ * `chat.reconnect` action 的输入载荷。
+ */
+export type ChatReconnectActionPayload = {
+  /**
+   * 指定目标渠道；省略时表示全部渠道。
+   */
+  channel?: ChatChannelName;
+};
+
+/**
+ * `chat.open` action 的输入载荷。
+ */
+export type ChatOpenActionPayload = {
+  /**
+   * 指定目标渠道；省略时表示全部渠道。
+   */
+  channel?: ChatChannelName;
+};
+
+/**
+ * `chat.close` action 的输入载荷。
+ */
+export type ChatCloseActionPayload = {
+  /**
+   * 指定目标渠道；省略时表示全部渠道。
+   */
+  channel?: ChatChannelName;
+};
+
+/**
+ * `chat.configuration` action 的输入载荷。
+ */
+export type ChatConfigurationActionPayload = {
+  /**
+   * 指定目标渠道；省略时表示全部渠道。
+   */
+  channel?: ChatChannelName;
+};
+
+/**
+ * `chat.configure` action 的输入载荷。
+ */
+export type ChatConfigureActionPayload = {
+  /**
+   * 要更新的目标渠道。
+   */
+  channel: ChatChannelName;
+  /**
+   * 渠道配置 patch；值类型遵循 channel configuration 元信息。
+   */
+  config: Record<string, JsonValue>;
+  /**
+   * 配置完成后是否立即重启目标渠道；默认由上层解释为 true。
+   */
+  restart?: boolean;
+};