@downcity/plugins 1.0.216 → 1.0.233

package/src/chat/runtime/ChatChannelLifecycle.ts

@@ -7,7 +7,7 @@
  * - 本模块不处理配置持久化，也不负责 action 输入输出包装。
  */
 
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
 import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
 import { createTelegramBot } from "@/chat/channels/telegram/Bot.js";
@@ -44,7 +44,7 @@ async function createFeishuBotLazy(
      */
     domain: string;
   },
-  context: AgentContext,
+  context: PluginContext,
 ) {
   const module_value = await import("@/chat/channels/feishu/Feishu.js");
   return await module_value.createFeishuBot(options, context);
@@ -52,12 +52,12 @@ async function createFeishuBotLazy(
 
 async function startTelegramChannel(
   state: ChatChannelState,
-  context: AgentContext,
+  context: PluginContext,
 ): Promise<void> {
   if (!isChatChannelEnabled(context, "telegram")) return;
   context.logger.info("Telegram channel enabled");
   const account = resolveChannelAccount(context, "telegram");
-  const token = String(account?.botToken || "").trim();
+  const token = String(account?.bot_token || "").trim();
   if (!token) return;
   state.telegram = createTelegramBot(
     {
@@ -73,13 +73,13 @@ async function startTelegramChannel(
 
 async function startFeishuChannel(
   state: ChatChannelState,
-  context: AgentContext,
+  context: PluginContext,
 ): 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();
+  const appId = String(account?.app_id || "").trim();
+  const appSecret = String(account?.app_secret || "").trim();
   if (!appId || !appSecret) return;
   state.feishu = await createFeishuBotLazy(
     {
@@ -97,13 +97,13 @@ async function startFeishuChannel(
 
 async function startQQChannel(
   state: ChatChannelState,
-  context: AgentContext,
+  context: PluginContext,
 ): Promise<void> {
   if (!isChatChannelEnabled(context, "qq")) return;
   context.logger.info("QQ chat platform enabled");
   const account = resolveChannelAccount(context, "qq");
-  const appId = String(account?.appId || "").trim();
-  const appSecret = String(account?.appSecret || "").trim();
+  const appId = String(account?.app_id || "").trim();
+  const appSecret = String(account?.app_secret || "").trim();
   if (!appId || !appSecret) return;
   state.qq = await createQQBot(
     {
@@ -124,7 +124,7 @@ async function startQQChannel(
  */
 export async function startSingleChatChannel(
   state: ChatChannelState,
-  context: AgentContext,
+  context: PluginContext,
   channel: ChatChannelName,
 ): Promise<void> {
   if (channel === "telegram") {
@@ -169,7 +169,7 @@ export async function stopSingleChatChannel(
  */
 export async function startChatChannels(
   state: ChatChannelState,
-  context: AgentContext,
+  context: PluginContext,
 ): Promise<void> {
   if (state.telegram || state.feishu || state.qq) {
     await stopChatChannels(state);

package/src/chat/runtime/ChatHistoryStore.ts

@@ -2,15 +2,15 @@
  * ChatHistoryStore：聊天事件流持久化。
  *
  * 关键点（中文）
- * - 写入 `.downcity/chat/<sessionId>/history.jsonl`（append-only）。
+ * - 写入 `.downcity/chat/<session_id>/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";
-import type { AgentContext } from "@downcity/agent";
+import { generate_id } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import { get_chat_history_path } from "@/chat/runtime/ChatStorage.js";
 import type { JsonObject } from "@downcity/agent";
 import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
@@ -41,31 +41,31 @@ function toOptionalObject(value: JsonObject | undefined): JsonObject | undefined
 }
 
 function buildInboundEvent(params: {
-  sessionId: string;
+  session_id: string;
   channel: ChatDispatchChannel;
   chatId: string;
   ingressKind: ChatHistoryIngressKind;
   text: string;
   targetType?: string;
   threadId?: number;
-  messageId?: string;
+  message_id?: string;
   actorId?: string;
   actorName?: string;
   extra?: JsonObject;
 }): ChatHistoryInboundEventV1 {
   return {
     v: 1,
-    id: `chat:${generateId()}`,
+    id: `chat:${generate_id()}`,
     ts: Date.now(),
     direction: "inbound",
     ingressKind: params.ingressKind,
-    sessionId: params.sessionId,
+    session_id: params.session_id,
     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.message_id ? { message_id: params.message_id } : {}),
     ...(params.actorId ? { actorId: params.actorId } : {}),
     ...(params.actorName ? { actorName: params.actorName } : {}),
     ...(params.extra ? { extra: params.extra } : {}),
@@ -73,29 +73,29 @@ function buildInboundEvent(params: {
 }
 
 function buildOutboundEvent(params: {
-  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;
 }): ChatHistoryOutboundEventV1 {
   return {
     v: 1,
-    id: `chat:${generateId()}`,
+    id: `chat:${generate_id()}`,
     ts: Date.now(),
     direction: "outbound",
-    sessionId: params.sessionId,
+    session_id: params.session_id,
     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.message_id ? { message_id: params.message_id } : {}),
     ...(params.actorId ? { actorId: params.actorId } : {}),
     ...(params.actorName ? { actorName: params.actorName } : {}),
     ...(params.extra ? { extra: params.extra } : {}),
@@ -112,7 +112,7 @@ function isChatHistoryEventV1(value: unknown): value is ChatHistoryEventV1 {
   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.session_id !== "string" || !obj.session_id.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;
@@ -132,39 +132,39 @@ function isChatHistoryEventV1(value: unknown): value is ChatHistoryEventV1 {
  * - 调用方应在入队前调用，以满足“先审计后执行”链路。
  */
 export async function appendInboundChatHistory(params: {
-  context: AgentContext;
-  sessionId: string;
+  context: PluginContext;
+  session_id: string;
   channel: ChatDispatchChannel;
   chatId: string;
   ingressKind: ChatHistoryIngressKind;
   text: string;
   targetType?: string;
   threadId?: number;
-  messageId?: string;
+  message_id?: string;
   actorId?: string;
   actorName?: string;
   extra?: JsonObject;
 }): Promise<void> {
-  const rootPath = normalizeTrimmedString(params.context.rootPath);
-  const sessionId = normalizeTrimmedString(params.sessionId);
+  const rootPath = normalizeTrimmedString(params.context.workspace_path);
+  const session_id = normalizeTrimmedString(params.session_id);
   const chatId = normalizeTrimmedString(params.chatId);
-  if (!rootPath || !sessionId || !chatId) return;
+  if (!rootPath || !session_id || !chatId) return;
 
   const event = buildInboundEvent({
-    sessionId,
+    session_id,
     channel: params.channel,
     chatId,
     ingressKind: params.ingressKind,
     text: String(params.text ?? ""),
     targetType: toOptionalTrimmedString(params.targetType),
     threadId: toOptionalFiniteNumber(params.threadId),
-    messageId: toOptionalTrimmedString(params.messageId),
+    message_id: toOptionalTrimmedString(params.message_id),
     actorId: toOptionalTrimmedString(params.actorId),
     actorName: toOptionalTrimmedString(params.actorName),
     extra: toOptionalObject(params.extra),
   });
 
-  const file = get_chat_history_path(params.context.rootPath, sessionId);
+  const file = get_chat_history_path(params.context.workspace_path, session_id);
   await fs.ensureDir(path.dirname(file));
   await fs.appendFile(file, JSON.stringify(event) + "\n", "utf8");
 }
@@ -177,60 +177,60 @@ export async function appendInboundChatHistory(params: {
  * - 该函数只做落盘，不影响实际发送链路。
  */
 export async function appendOutboundChatHistory(params: {
-  context: AgentContext;
-  sessionId: string;
+  context: PluginContext;
+  session_id: string;
   channel: ChatDispatchChannel;
   chatId: string;
   text: string;
   targetType?: string;
   threadId?: number;
-  messageId?: string;
+  message_id?: string;
   actorId?: string;
   actorName?: string;
   extra?: JsonObject;
 }): Promise<void> {
-  const rootPath = normalizeTrimmedString(params.context.rootPath);
-  const sessionId = normalizeTrimmedString(params.sessionId);
+  const rootPath = normalizeTrimmedString(params.context.workspace_path);
+  const session_id = normalizeTrimmedString(params.session_id);
   const chatId = normalizeTrimmedString(params.chatId);
-  if (!rootPath || !sessionId || !chatId) return;
+  if (!rootPath || !session_id || !chatId) return;
 
   const event = buildOutboundEvent({
-    sessionId,
+    session_id,
     channel: params.channel,
     chatId,
     text: String(params.text ?? ""),
     targetType: toOptionalTrimmedString(params.targetType),
     threadId: toOptionalFiniteNumber(params.threadId),
-    messageId: toOptionalTrimmedString(params.messageId),
+    message_id: toOptionalTrimmedString(params.message_id),
     actorId: toOptionalTrimmedString(params.actorId),
     actorName: toOptionalTrimmedString(params.actorName),
     extra: toOptionalObject(params.extra),
   });
 
-  const file = get_chat_history_path(params.context.rootPath, sessionId);
+  const file = get_chat_history_path(params.context.workspace_path, session_id);
   await fs.ensureDir(path.dirname(file));
   await fs.appendFile(file, JSON.stringify(event) + "\n", "utf8");
 }
 
 /**
- * 读取 chat 历史事件（按 sessionId）。
+ * 读取 chat 历史事件（按 session_id）。
  *
  * 关键点（中文）
  * - 默认返回最近 N 条（按时间升序）。
  * - 仅做文件读取与过滤，不涉及任何业务 side-effect。
  */
 export async function readChatHistory(params: {
-  context: AgentContext;
-  sessionId: string;
+  context: PluginContext;
+  session_id: 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 = get_chat_history_path(params.context.rootPath, sessionId);
-  if (!rootPath || !sessionId) {
+  const rootPath = normalizeTrimmedString(params.context.workspace_path);
+  const session_id = normalizeTrimmedString(params.session_id);
+  const historyPath = get_chat_history_path(params.context.workspace_path, session_id);
+  if (!rootPath || !session_id) {
     return {
       historyPath,
       events: [],

package/src/chat/runtime/ChatIngressStore.ts

@@ -7,7 +7,7 @@
  * - 只有极少数非 turn 场景才允许显式补写 `session messages`
  */
 
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type { JsonObject } from "@downcity/agent";
 import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
 import { appendInboundChatHistory } from "./ChatHistoryStore.js";
@@ -38,14 +38,14 @@ export function buildExecIngressExtra(extra?: JsonObject): JsonObject {
  * - 可避免 queue / control / transport 在 session 外重复持久化 user 消息。
  */
 export async function appendExecIngress(params: {
-  context: AgentContext;
-  sessionId: string;
+  context: PluginContext;
+  session_id: string;
   channel: ChatDispatchChannel;
   chatId: string;
   text: string;
   targetType?: string;
   threadId?: number;
-  messageId?: string;
+  message_id?: string;
   actorId?: string;
   actorName?: string;
   extra?: JsonObject;
@@ -53,14 +53,14 @@ export async function appendExecIngress(params: {
   const execExtra = buildExecIngressExtra(params.extra);
   await appendInboundChatHistory({
     context: params.context,
-    sessionId: params.sessionId,
+    session_id: params.session_id,
     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.message_id ? { message_id: params.message_id } : {}),
     ...(params.actorId ? { actorId: params.actorId } : {}),
     ...(params.actorName ? { actorName: params.actorName } : {}),
     extra: execExtra,

package/src/chat/runtime/ChatMetaStore.ts

@@ -1,13 +1,13 @@
 /**
- * ChatMetaStore：按 sessionId 维护 chat 路由元信息。
+ * ChatMetaStore：按 session_id 维护 chat 路由元信息。
  *
  * 关键点（中文）
  * - 入站消息到达时由 chat plugin runtime 写入
- * - 出站按 sessionId/chatKey 发送时由 chat plugin runtime 读取
+ * - 出站按 session_id/chat_key 发送时由 chat plugin runtime 读取
  * - 底层数据落在 `.downcity/channel/meta.json`，由 ChannelContextStore 统一维护
  */
 
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type { ChatMetaV1 } from "@/chat/types/ChatMeta.js";
 import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
 import {
@@ -18,8 +18,8 @@ import {
   upsertChannelSessionRouteBySessionId,
 } from "./ChannelContextStore.js";
 
-function normalizeSessionId(sessionId: string): string {
-  return String(sessionId || "").trim();
+function normalizeSessionId(session_id: string): string {
+  return String(session_id || "").trim();
 }
 
 function normalizeChatId(chatId: string): string {
@@ -27,28 +27,28 @@ function normalizeChatId(chatId: string): string {
 }
 
 /**
- * 读取指定 sessionId 的 chat meta。
+ * 读取指定 session_id 的 chat meta。
  */
 export async function readChatMetaBySessionId(params: {
-  context: AgentContext;
-  sessionId: string;
+  context: PluginContext;
+  session_id: string;
 }): Promise<ChatMetaV1 | null> {
-  const sessionId = normalizeSessionId(params.sessionId);
-  if (!sessionId) return null;
+  const session_id = normalizeSessionId(params.session_id);
+  if (!session_id) return null;
   const route = await readChannelSessionRouteBySessionId({
     context: params.context,
-    sessionId,
+    session_id,
   });
   if (!route) return null;
   return {
     v: 1,
-    updatedAt: route.updatedAt,
-    sessionId: route.sessionId,
+    updated_at: route.updated_at,
+    session_id: route.session_id,
     channel: route.channel,
     chatId: route.chatId,
     ...(route.targetType ? { targetType: route.targetType } : {}),
     ...(typeof route.threadId === "number" ? { threadId: route.threadId } : {}),
-    ...(route.messageId ? { messageId: route.messageId } : {}),
+    ...(route.message_id ? { message_id: route.message_id } : {}),
     ...(route.actorId ? { actorId: route.actorId } : {}),
     ...(route.actorName ? { actorName: route.actorName } : {}),
     ...(route.chatTitle ? { chatTitle: route.chatTitle } : {}),
@@ -56,33 +56,33 @@ export async function readChatMetaBySessionId(params: {
 }
 
 /**
- * 更新指定 sessionId 的 chat meta（全量覆盖最近快照）。
+ * 更新指定 session_id 的 chat meta（全量覆盖最近快照）。
  */
 export async function upsertChatMetaBySessionId(params: {
-  context: AgentContext;
-  sessionId: string;
+  context: PluginContext;
+  session_id: string;
   channel: ChatDispatchChannel;
   chatId: string;
   targetType?: string;
   threadId?: number;
-  messageId?: string;
+  message_id?: string;
   actorId?: string;
   actorName?: string;
   chatTitle?: string;
 }): Promise<void> {
-  const sessionId = normalizeSessionId(params.sessionId);
+  const session_id = normalizeSessionId(params.session_id);
   const chatId = normalizeChatId(params.chatId);
-  if (!sessionId || !chatId) return;
+  if (!session_id || !chatId) return;
   await upsertChannelSessionRouteBySessionId({
     context: params.context,
-    sessionId,
+    session_id,
     target: {
       channel: params.channel,
       chatId,
       ...(typeof params.targetType === "string" ? { targetType: params.targetType } : {}),
       ...(typeof params.threadId === "number" ? { threadId: params.threadId } : {}),
     },
-    messageId: params.messageId,
+    message_id: params.message_id,
     actorId: params.actorId,
     actorName: params.actorName,
     chatTitle: params.chatTitle,
@@ -90,10 +90,10 @@ export async function upsertChatMetaBySessionId(params: {
 }
 
 /**
- * 通过渠道目标查找已有 sessionId。
+ * 通过渠道目标查找已有 session_id。
  */
 export async function resolveSessionIdByChatTarget(params: {
-  context: AgentContext;
+  context: PluginContext;
   channel: ChatDispatchChannel;
   chatId: string;
   targetType?: string;
@@ -113,10 +113,10 @@ export async function resolveSessionIdByChatTarget(params: {
 }
 
 /**
- * 通过渠道目标解析或创建 sessionId。
+ * 通过渠道目标解析或创建 session_id。
  */
 export async function resolveOrCreateSessionIdByChatTarget(params: {
-  context: AgentContext;
+  context: PluginContext;
   channel: ChatDispatchChannel;
   chatId: string;
   targetType?: string;
@@ -136,21 +136,21 @@ export async function resolveOrCreateSessionIdByChatTarget(params: {
 }
 
 /**
- * 删除指定 sessionId 的 chat meta 映射。
+ * 删除指定 session_id 的 chat meta 映射。
  *
  * 关键点（中文）
- * - 删除后该 sessionId 不再可用于 chatKey 路由发送。
- * - 若同一 target 重新收到入站消息，会创建新的 sessionId。
+ * - 删除后该 session_id 不再可用于 chat_key 路由发送。
+ * - 若同一 target 重新收到入站消息，会创建新的 session_id。
  */
 export async function removeChatMetaBySessionId(params: {
-  context: AgentContext;
-  sessionId: string;
+  context: PluginContext;
+  session_id: string;
 }): Promise<{
   removed: boolean;
   route: ChatMetaV1 | null;
 }> {
-  const sessionId = normalizeSessionId(params.sessionId);
-  if (!sessionId) {
+  const session_id = normalizeSessionId(params.session_id);
+  if (!session_id) {
     return {
       removed: false,
       route: null,
@@ -158,7 +158,7 @@ export async function removeChatMetaBySessionId(params: {
   }
   const result = await removeChannelSessionRouteBySessionId({
     context: params.context,
-    sessionId,
+    session_id,
   });
   const route = result.route;
   if (!route) {
@@ -171,13 +171,13 @@ export async function removeChatMetaBySessionId(params: {
     removed: result.removed,
     route: {
       v: 1,
-      updatedAt: route.updatedAt,
-      sessionId: route.sessionId,
+      updated_at: route.updated_at,
+      session_id: route.session_id,
       channel: route.channel,
       chatId: route.chatId,
       ...(route.targetType ? { targetType: route.targetType } : {}),
       ...(typeof route.threadId === "number" ? { threadId: route.threadId } : {}),
-      ...(route.messageId ? { messageId: route.messageId } : {}),
+      ...(route.message_id ? { message_id: route.message_id } : {}),
       ...(route.actorId ? { actorId: route.actorId } : {}),
       ...(route.actorName ? { actorName: route.actorName } : {}),
       ...(route.chatTitle ? { chatTitle: route.chatTitle } : {}),