@downcity/agent 1.1.25 → 1.1.35

package/src/sdk/session/RuntimeSessionPort.ts

@@ -0,0 +1,107 @@
+/**
+ * SDK Session plugin runtime 端口构造器。
+ *
+ * 关键点（中文）
+ * - 把 SDK 本地 session 适配成 runtime / plugin runtime 依赖的 `SessionPort`。
+ * - SDK 公开面只保留 `prompt()` / `subscribe()`；runtime/service 若要 one-shot 等待结果，也统一委托给 `prompt()`。
+ */
+
+import type { SessionPort } from "@/core/AgentContextTypes.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type {
+  AgentSessionSubscriber,
+  AgentSessionUnsubscribe,
+} from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+
+/**
+ * 构造 SDK SessionPort 的参数。
+ */
+export interface CreateRuntimeSessionPortParams {
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+  /**
+   * 读取当前 session 底层执行端口。
+   */
+  getExecutor: SessionPort["getExecutor"];
+  /**
+   * 追加一条新的 session prompt。
+   */
+  prompt: (input: AgentSessionPromptInput) => Promise<AgentSessionTurnHandle>;
+  /**
+   * 订阅当前 session 的 future 事件。
+   */
+  subscribe: (
+    subscriber: AgentSessionSubscriber,
+  ) => AgentSessionUnsubscribe;
+  /**
+   * 清理当前 session executor 状态。
+   */
+  clearExecutor: () => void;
+  /**
+   * session 更新后的异步通知回调。
+   */
+  afterSessionUpdatedAsync: () => Promise<void>;
+  /**
+   * 追加 user 消息到底层历史。
+   */
+  appendUserMessage: SessionPort["appendUserMessage"];
+  /**
+   * 追加 assistant 消息到底层历史。
+   */
+  appendAssistantMessage: SessionPort["appendAssistantMessage"];
+  /**
+   * 返回当前 session 是否正在执行。
+   */
+  isExecuting: () => boolean;
+  /**
+   * 当前 session 历史持久化端口。
+   */
+  historyStore: SessionHistoryStore;
+  /**
+   * 在执行前确保当前 session 已完成初始化与宿主级配置。
+   */
+  ensureReadyForExecution: () => Promise<void>;
+  /**
+   * session 更新后需要同步执行的持久化回调。
+   */
+  touchMetadata: () => Promise<void>;
+}
+
+/**
+ * 创建供 plugin runtime 使用的 session 端口。
+ */
+export function createRuntimeSessionPort(
+  params: CreateRuntimeSessionPortParams,
+): SessionPort {
+  return {
+    sessionId: params.sessionId,
+    getExecutor: () => params.getExecutor(),
+    getHistoryStore: () => params.historyStore,
+    prompt: async (input) => {
+      await params.ensureReadyForExecution();
+      return await params.prompt(input);
+    },
+    subscribe: (subscriber) => {
+      return params.subscribe(subscriber);
+    },
+    clearExecutor: () => {
+      params.clearExecutor();
+    },
+    afterSessionUpdatedAsync: async () => {
+      await params.afterSessionUpdatedAsync();
+    },
+    appendUserMessage: async (messageParams) => {
+      await params.appendUserMessage(messageParams);
+      await params.touchMetadata();
+    },
+    appendAssistantMessage: async (messageParams) => {
+      await params.appendAssistantMessage(messageParams);
+      await params.touchMetadata();
+    },
+    isExecuting: () => params.isExecuting(),
+  };
+}

package/src/sdk/session/index.ts

@@ -2,7 +2,7 @@
  * SDK Session 辅助模块聚合入口。
  *
  * 关键点（中文）
- * - 这里收口 `Session.ts` 依赖的路径、元数据、持久化与 service 端口适配能力。
+ * - 这里收口 `Session.ts` 依赖的路径、元数据、持久化与 plugin runtime 端口适配能力。
  * - 避免这些实现继续平铺在 `sdk/` 顶层，提升目录语义清晰度。
  */
 
@@ -30,5 +30,14 @@ export {
   touchSessionMetadata,
 } from "./Persistence.js";
 export {
-  createSessionServicePort,
-} from "./ServicePort.js";
+  createRuntimeSessionPort,
+} from "./RuntimeSessionPort.js";
+export {
+  buildSessionHistoryPage,
+  buildSessionInfo,
+  listAgentSessionSummaryPage,
+  loadSessionMessagesFromPath,
+  resolveSessionMessagePreview,
+  resolveSessionTitle,
+  toSessionTimelineEvents,
+} from "./Browse.js";

package/src/sdk/session/runtime/SessionPromptRuntime.ts

@@ -8,8 +8,10 @@
  */
 
 import { nanoid } from "nanoid";
-import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   AgentSessionTurnHandle,
   AgentSessionTurnResult,
@@ -17,9 +19,9 @@ import type {
 
 type QueuedPrompt = {
   /**
-   * 当前排队中的用户文本。
+   * 当前排队中的 prompt 输入。
    */
-  query: string;
+  input: AgentSessionPromptInput;
 
   /**
    * 当前 prompt 对应的 turn handle Promise 控制器。
@@ -79,18 +81,21 @@ export interface SessionPromptRuntimeOptions {
   /**
    * 构造并持久化一条 user 消息。
    */
-  createAndPersistUserMessage: (query: string) => Promise<SessionUserMessageV1>;
+  createAndPersistUserMessage: (
+    input: AgentSessionPromptInput,
+  ) => Promise<SessionUserMessageV1>;
 
   /**
    * 执行单轮 turn。
    */
   executeTurn: (input: {
     turnId: string;
-    query: string;
+    promptInput: AgentSessionPromptInput;
     onStepMerge: () => Promise<SessionUserMessageV1[]>;
   }) => Promise<{
     text: string;
     success: boolean;
+    assistantMessage: SessionMessageV1;
     error?: string;
   }>;
 }
@@ -119,10 +124,12 @@ export class SessionPromptRuntime {
   /**
    * 追加一条新的 prompt。
    */
-  prompt(query: string): Promise<AgentSessionTurnHandle> {
+  prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
     const deferredHandle = createDeferred<AgentSessionTurnHandle>();
     this.queue.push({
-      query: String(query || "").trim(),
+      input: {
+        query: String(input.query || "").trim(),
+      },
       deferredHandle,
     });
     this.ensureProcessing();
@@ -164,10 +171,10 @@ export class SessionPromptRuntime {
       current.deferredHandle.resolve(createTurnHandle(activeTurn));
 
       try {
-        await this.createAndPersistUserMessage(current.query);
+        await this.createAndPersistUserMessage(current.input);
         const result = await this.executeTurn({
           turnId,
-          query: current.query,
+          promptInput: current.input,
           onStepMerge: async () => {
             return await this.drainQueuedPromptsAsMessages(activeTurn);
           },
@@ -176,6 +183,7 @@ export class SessionPromptRuntime {
           turnId,
           text: result.text,
           success: result.success,
+          assistantMessage: result.assistantMessage,
           ...(result.error ? { error: result.error } : {}),
         };
         activeTurn.result = finalResult;
@@ -193,6 +201,10 @@ export class SessionPromptRuntime {
           turnId,
           text: "",
           success: false,
+          assistantMessage: buildPromptRuntimeErrorAssistantMessage({
+            sessionId: this.sessionId,
+            message,
+          }),
           error: message,
         };
         activeTurn.result = finalResult;
@@ -220,12 +232,12 @@ export class SessionPromptRuntime {
     const merged: SessionUserMessageV1[] = [];
 
     for (let index = 0; index < drained.length; index += 1) {
-      const item = drained[index];
-      try {
-        const message = await this.createAndPersistUserMessage(item.query);
-        item.deferredHandle.resolve(createTurnHandle(activeTurn));
-        merged.push(message);
-      } catch {
+        const item = drained[index];
+        try {
+          const message = await this.createAndPersistUserMessage(item.input);
+          item.deferredHandle.resolve(createTurnHandle(activeTurn));
+          merged.push(message);
+        } catch {
         // 关键点（中文）：若某条消息持久化失败，把未处理部分重新放回队列头部，避免静默丢失。
         const remaining = drained.slice(index);
         this.queue.unshift(...remaining);
@@ -237,6 +249,27 @@ export class SessionPromptRuntime {
   }
 }
 
+function buildPromptRuntimeErrorAssistantMessage(input: {
+  sessionId: string;
+  message: string;
+}): SessionMessageV1 {
+  return {
+    id: `a:${input.sessionId}:${Date.now()}:${nanoid(6)}`,
+    role: "assistant",
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: input.sessionId,
+      source: "egress",
+      kind: "normal",
+      extra: {
+        note: "session_prompt_runtime_error",
+      },
+    },
+    parts: [{ type: "text", text: input.message }],
+  };
+}
+
 function createDeferred<T>(): Deferred<T> {
   let resolve!: (value: T) => void;
   const promise = new Promise<T>((innerResolve) => {

package/src/types/config/DowncityConfig.ts

@@ -3,13 +3,150 @@
  *
  * 关键点（中文）
  * - 作为全局共享类型，不挂在 console 目录下。
- * - 供 agent、services、control plane 宿主层多处复用，避免反向类型依赖。
+ * - 供 agent、plugin、control plane 宿主层多处复用，避免反向类型依赖。
  */
 import type { LlmConfig } from "@/types/config/LlmConfig.js";
 import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
 import type { JsonObject } from "@/types/common/Json.js";
 import type { SandboxProjectConfig } from "@/runtime/sandbox/types/Sandbox.js";
 
+/**
+ * 单个聊天渠道配置。
+ */
+export interface DowncityChatChannelConfig {
+  /**
+   * 当前渠道是否启用。
+   */
+  enabled?: boolean;
+  /**
+   * 绑定的渠道账户 ID。
+   */
+  channelAccountId?: string;
+}
+
+/**
+ * 聊天插件渠道配置集合。
+ */
+export interface DowncityChatPluginChannelsConfig {
+  /**
+   * Telegram 渠道配置。
+   */
+  telegram?: DowncityChatChannelConfig;
+  /**
+   * Feishu 渠道配置。
+   */
+  feishu?: DowncityChatChannelConfig;
+  /**
+   * QQ 渠道配置。
+   */
+  qq?: DowncityChatChannelConfig;
+}
+
+/**
+ * 聊天插件队列配置。
+ */
+export interface DowncityChatPluginQueueConfig {
+  /**
+   * 全局最大并发（不同 chatKey 之间）。
+   * 默认：2
+   */
+  maxConcurrency?: number;
+  /**
+   * 入站消息合并的防抖窗口（毫秒）。
+   *
+   * 关键点（中文）
+   * - 同一 chatKey 在该窗口内连续到达的多条消息，会在一次 run 前一起并入上下文。
+   * - 典型场景：用户先发一句话，再紧接着转发链接/卡片。
+   * - 设为 `0` 或负数可关闭该能力（立即执行首条消息）。
+   *
+   * 默认：600
+   */
+  mergeDebounceMs?: number;
+  /**
+   * 入站消息合并的最长等待时间（毫秒）。
+   *
+   * 关键点（中文）
+   * - 即使用户持续发送新消息，也不会无限延期；达到该上限后会立刻启动 run。
+   * - 用于平衡“尽量合并上下文”与“响应时延可控”。
+   * - 当 `mergeDebounceMs <= 0` 时该字段不会生效。
+   *
+   * 默认：2000
+   */
+  mergeMaxWaitMs?: number;
+}
+
+/**
+ * 聊天插件出站控制配置。
+ */
+export interface DowncityChatPluginEgressConfig {
+  /**
+   * 单次 agent run 内，`chat_send` 允许调用的最大次数。
+   */
+  chatSendMaxCallsPerRun?: number;
+  /**
+   * 是否启用 `chat_send` 幂等去重（基于 inbound messageId + 回复内容 hash）。
+   */
+  chatSendIdempotency?: boolean;
+}
+
+/**
+ * 聊天插件配置。
+ */
+export interface DowncityChatPluginConfig {
+  /**
+   * Chat 调度队列（按 chatKey 分 lane）。
+   */
+  queue?: DowncityChatPluginQueueConfig;
+  /**
+   * 出站（egress）控制：用于限制工具发送、避免重复与无限循环刷屏。
+   */
+  egress?: DowncityChatPluginEgressConfig;
+  /**
+   * 消息平台 channel 配置。
+   */
+  channels?: DowncityChatPluginChannelsConfig;
+}
+
+/**
+ * skill 插件配置。
+ */
+export interface DowncitySkillPluginConfig {
+  /**
+   * 当前插件是否启用。
+   */
+  enabled?: boolean;
+  /**
+   * 技能目录列表。
+   */
+  paths?: string[];
+  /**
+   * 是否允许读取项目外部技能目录。
+   */
+  allowExternalPaths?: boolean;
+}
+
+/**
+ * downcity.json 中的插件配置映射。
+ */
+export interface DowncityPluginConfigMap {
+  /**
+   * chat 插件配置。
+   */
+  chat?: DowncityChatPluginConfig;
+  /**
+   * skill 插件配置。
+   */
+  skill?: DowncitySkillPluginConfig;
+  /**
+   * 其他插件配置。
+   */
+  [pluginName: string]:
+    | JsonObject
+    | DowncityChatPluginConfig
+    | DowncitySkillPluginConfig
+    | undefined;
+}
+
 export interface DowncityConfig {
   $schema?: string;
   name: string;
@@ -23,106 +160,16 @@ export interface DowncityConfig {
     port?: number;
     host?: string;
   };
-  /**
-   * services 配置。
-   *
-   * 关键点（中文）
-   * - 所有服务相关配置统一收敛到 `services` 下，避免顶层散落字段。
-   * - 例如：`services.chat.channels`、`services.chat.queue`。
-   */
-  services?: {
-    /**
-     * Chat service 配置。
-     */
-    chat?: {
-      /**
-       * Chat 调度队列（按 chatKey 分 lane）。
-       */
-      queue?: {
-        /**
-         * 全局最大并发（不同 chatKey 之间）。
-         * 默认：2
-         */
-        maxConcurrency?: number;
-        /**
-         * 入站消息合并的防抖窗口（毫秒）。
-         *
-         * 关键点（中文）
-         * - 同一 chatKey 在该窗口内连续到达的多条消息，会在一次 run 前一起并入上下文。
-         * - 典型场景：用户先发一句话，再紧接着转发链接/卡片。
-         * - 设为 `0` 或负数可关闭该能力（立即执行首条消息）。
-         *
-         * 默认：600
-         */
-        mergeDebounceMs?: number;
-        /**
-         * 入站消息合并的最长等待时间（毫秒）。
-         *
-         * 关键点（中文）
-         * - 即使用户持续发送新消息，也不会无限延期；达到该上限后会立刻启动 run。
-         * - 用于平衡“尽量合并上下文”与“响应时延可控”。
-         * - 当 `mergeDebounceMs <= 0` 时该字段不会生效。
-         *
-         * 默认：2000
-         */
-        mergeMaxWaitMs?: number;
-      };
-      /**
-       * 出站（egress）控制：用于限制工具发送、避免重复与无限循环刷屏。
-       */
-      egress?: {
-        /**
-         * 单次 agent run 内，`chat_send` 允许调用的最大次数。
-         */
-        chatSendMaxCallsPerRun?: number;
-        /**
-         * 是否启用 `chat_send` 幂等去重（基于 inbound messageId + 回复内容 hash）。
-         */
-        chatSendIdempotency?: boolean;
-      };
-      /**
-       * 消息平台 channel 配置。
-       */
-      channels?: {
-        telegram?: {
-          enabled: boolean;
-          /**
-           * 绑定的 channel account id（来源：平台全局 `~/.downcity/downcity.db`）。
-           */
-          channelAccountId?: string;
-        };
-        feishu?: {
-          enabled: boolean;
-          /**
-           * 绑定的 channel account id（来源：平台全局 `~/.downcity/downcity.db`）。
-           */
-          channelAccountId?: string;
-        };
-        qq?: {
-          enabled: boolean;
-          /**
-           * 绑定的 channel account id（来源：平台全局 `~/.downcity/downcity.db`）。
-           */
-          channelAccountId?: string;
-        };
-      };
-    };
-  };
   /**
    * plugins 配置。
    *
    * 关键点（中文）
-   * - 新插件体系的行为配置统一收敛到该字段。
-   * - plugin 私有配置（例如 `plugins.skill.paths`）也放在这里。
+   * - 所有可配置能力统一收敛到 `plugins`，不再保留独立 `services` 域。
+   * - plugin 私有配置（例如 `plugins.skill.paths`、`plugins.chat.channels`）也放在这里。
    * - key 为 plugin 名称，value 为对应插件的结构化配置对象。
    * - 当前阶段允许各 plugin 自定义字段，但必须保持 JSON 可序列化。
    */
-  plugins?: {
-    /**
-     * 插件配置对象映射。
-     */
-    [pluginName: string]: JsonObject;
-  };
+  plugins?: DowncityPluginConfigMap;
   /**
    * 项目执行绑定配置。
    *
@@ -135,7 +182,7 @@ export interface DowncityConfig {
    * shell / CLI 执行 sandbox 配置。
    *
    * 关键点（中文）
-   * - 当前只作用于 shell service 这条命令执行链。
+   * - 当前只作用于 shell plugin 这条命令执行链。
    * - 这里不表达审批、用户授权与复杂策略系统，只表达最小边界。
    */
   sandbox?: SandboxProjectConfig;
@@ -152,7 +199,7 @@ export interface DowncityConfig {
    * 上下文管理（工程向配置）。
    *
    * 说明
-   * - 对话消息以 UIMessage[] 为唯一事实源（`.downcity/session/<sessionId>/messages/messages.jsonl`）。
+   * - 对话消息以 UIMessage[] 为唯一事实源（`.downcity/agents/<agentId>/sessions/<sessionId>/messages/messages.jsonl`）。
    * - Agent 每次执行直接把 UIMessage[] 转成 ModelMessage[] 作为 messages 输入。
    * - 超出上下文窗口时会自动 compact（更早段压缩为摘要 + 保留最近窗口）。
    */
@@ -208,7 +255,7 @@ export interface DowncityConfig {
      */
     memory?: {
       /**
-       * 是否启用 memory service。
+       * 是否启用 memory plugin。
        */
       enabled?: boolean;
     };

package/src/types/runtime/auth/AuthPermission.ts

@@ -13,8 +13,6 @@ export const AUTH_PERMISSION_KEYS = [
   "agent.read",
   "agent.write",
   "agent.execute",
-  "service.read",
-  "service.write",
   "task.read",
   "task.run",
   "model.read",
@@ -44,8 +42,6 @@ export const AUTH_PERMISSION_DESCRIPTIONS: Record<AuthPermissionKey, string> = {
   "agent.read": "读取 agent 基础信息与运行状态。",
   "agent.write": "修改 agent 配置与元信息。",
   "agent.execute": "触发 agent 执行与会话运行。",
-  "service.read": "查看 service 状态与元数据。",
-  "service.write": "启动、停止或修改 service。",
   "task.read": "查看 task 定义与运行结果。",
   "task.run": "创建或手动执行 task。",
   "model.read": "查看模型池与模型绑定。",
@@ -112,7 +108,6 @@ export const AUTH_DEFAULT_ROLES: AuthDefaultRoleDefinition[] = [
     description: "只读角色，可查看状态但不能执行高危变更。",
     permissions: [
       "agent.read",
-      "service.read",
       "task.read",
       "model.read",
       "env.read",
@@ -123,4 +118,3 @@ export const AUTH_DEFAULT_ROLES: AuthDefaultRoleDefinition[] = [
     ],
   },
 ];
-

package/src/types/runtime/host/AgentHost.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里统一描述由 agent runtime 装配、再挂入 AgentRuntime 的宿主能力。
- * - service / session / plugin 只能消费这些稳定能力，不应直接依赖具体宿主实现。
+ * - plugin runtime / session / plugin 作者 API 只能消费这些稳定能力，不应直接依赖具体宿主实现。
  * - 当前先收敛路径、认证、plugin 配置持久化三类高频能力。
  */
 
@@ -17,13 +17,13 @@ import type {
   ChatChannelAccountListItem,
   ChatChannelAccountProbeResult,
   ChatChannelAccountUpsertInput,
-} from "@/service/builtins/chat/types/ChannelAccount.js";
+} from "@/plugin/builtins/chat/types/ChannelAccount.js";
 import type {
   StoredChannelAccount,
   StoredModel,
   StoredModelProvider,
 } from "@/types/runtime/host/Store.js";
-import type { ChatChannelName } from "@/service/builtins/chat/types/ChannelStatus.js";
+import type { ChatChannelName } from "@/plugin/builtins/chat/types/ChannelStatus.js";
 import type { AgentProjectInitializationInput } from "@/config/project/types/AgentProject.js";
 import type { PlatformModelChoice } from "@/config/project/AgentInitializer.js";
 
@@ -35,6 +35,10 @@ export interface AgentPathRuntime {
    * 当前项目根目录。
    */
   projectRoot: string;
+  /**
+   * 当前 agent 的稳定标识。
+   */
+  agentId: string;
   /**
    * `.downcity` 根目录路径。
    */
@@ -68,11 +72,11 @@ export interface AgentPathRuntime {
    */
   getDowncityMemoryDailyPath(date: string): string;
   /**
-   * `.downcity/session` 根目录路径。
+   * `.downcity/agents/<agentId>/sessions` 根目录路径。
    */
   getDowncitySessionRootDirPath(): string;
   /**
-   * `.downcity/session/<sessionId>` 目录路径。
+   * `.downcity/agents/<agentId>/sessions/<sessionId>` 目录路径。
    */
   getDowncitySessionDirPath(sessionId: string): string;
 }

package/src/types/runtime/http/InlineInstant.ts

@@ -84,9 +84,9 @@ export interface PlatformInlineInstantRunResult {
 }
 
 /**
- * 平台 Inline 即时执行服务端口。
+ * 平台 Inline 即时执行运行端口。
  */
-export interface PlatformInlineInstantService {
+export interface PlatformInlineInstantRunner {
   /**
    * 运行一次即时执行请求。
    */