@downcity/plugins 1.0.254 → 1.0.280

package/src/builtin/PluginSettingsDefinitions.ts

@@ -0,0 +1,45 @@
+/** Web、Image 与 Sound Plugin 自己拥有的设置 Mainview 字段定义。 */
+
+import type { PluginSettingsDefinition } from "@/builtin/types/PluginSettings.js";
+
+/** Web Plugin Profile 设置。 */
+export const WEB_PLUGIN_SETTINGS: PluginSettingsDefinition = {
+  title: "Web",
+  description: "配置浏览器连接与页面观察默认值。未填写 CDP 地址时仍可使用搜索和文档读取。",
+  fields: [
+    {
+      key: "browser",
+      label: "Browser provider",
+      description: "当前支持 Playwright CDP 连接。",
+      type: "select",
+      options: [{ value: "playwright", label: "Playwright" }],
+    },
+    { key: "cdp_url", label: "CDP endpoint", description: "现有浏览器的 HTTP 或 WebSocket 调试地址。", type: "string" },
+    { key: "default_url", label: "Default URL", description: "浏览器 Session 没有指定地址时打开的页面。", type: "string" },
+    { key: "timeout_ms", label: "Operation timeout (ms)", type: "number", minimum: 1000, maximum: 60000 },
+    { key: "max_observation_chars", label: "Observation character limit", type: "number", minimum: 1, maximum: 100000 },
+  ],
+};
+
+/** Image Plugin Profile 设置。 */
+export const IMAGE_PLUGIN_SETTINGS: PluginSettingsDefinition = {
+  title: "Image",
+  description: "选择图像生成请求没有显式指定模型时使用的默认模型。",
+  fields: [
+    { key: "default_model", label: "Default image model", type: "string" },
+  ],
+};
+
+/** Sound Plugin Profile 设置。 */
+export const SOUND_PLUGIN_SETTINGS: PluginSettingsDefinition = {
+  title: "Sound",
+  description: "配置语音识别和语音合成的默认行为。",
+  fields: [
+    { key: "default_asr_model", label: "Default ASR model", type: "string" },
+    { key: "default_tts_model", label: "Default TTS model", type: "string" },
+    { key: "auto_asr", label: "Automatic transcription", description: "收到音频输入后自动执行语音识别。", type: "boolean" },
+    { key: "language", label: "Default language", type: "string" },
+    { key: "voice", label: "Default voice", type: "string" },
+    { key: "format", label: "Default audio format", type: "string" },
+  ],
+};

package/src/builtin/main/PluginSettingsMain.ts

@@ -0,0 +1,75 @@
+/** 官方简单设置 Plugin 的 main action 实现。 */
+
+import {
+  define_plugin_main,
+  type PluginJsonObject,
+  type PluginJsonValue,
+  type PluginMainModule,
+} from "@downcity/plugin";
+import type {
+  PluginSettingField,
+  PluginSettingsDefinition,
+} from "@/builtin/types/PluginSettings.js";
+
+/** 为一个字段集合创建 Profile 读取和保存 action。 */
+export function create_plugin_settings_main(
+  definition: PluginSettingsDefinition,
+): PluginMainModule {
+  return define_plugin_main({
+    activate({ plugin }) {
+      plugin.action({
+        id: "profile.read",
+        run: async (_input, context) => await context.config.get(),
+      });
+      plugin.action({
+        id: "profile.save",
+        run: async (input, context) => {
+          const config = normalize_settings(input, definition.fields);
+          await context.config.set(config);
+          return config;
+        },
+      });
+    },
+  });
+}
+
+/** 按 Plugin 自己声明的字段校验并规范化配置。 */
+function normalize_settings(
+  input: PluginJsonValue | undefined,
+  fields: readonly PluginSettingField[],
+): PluginJsonObject {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("Plugin Profile config must be an object");
+  }
+  const source = input as PluginJsonObject;
+  const result: PluginJsonObject = {};
+  for (const field of fields) {
+    const value = source[field.key];
+    if (value === undefined || value === "") continue;
+    if (field.type === "boolean") {
+      if (typeof value !== "boolean") throw invalid_field(field.key);
+      result[field.key] = value;
+      continue;
+    }
+    if (field.type === "number") {
+      if (typeof value !== "number" || !Number.isFinite(value)) throw invalid_field(field.key);
+      if (field.minimum !== undefined && value < field.minimum) throw invalid_field(field.key);
+      if (field.maximum !== undefined && value > field.maximum) throw invalid_field(field.key);
+      result[field.key] = value;
+      continue;
+    }
+    if (typeof value !== "string") throw invalid_field(field.key);
+    const normalized = value.trim();
+    if (!normalized) continue;
+    if (field.type === "select" && !field.options?.some((item) => item.value === normalized)) {
+      throw invalid_field(field.key);
+    }
+    result[field.key] = normalized;
+  }
+  return result;
+}
+
+/** 创建稳定的字段校验错误。 */
+function invalid_field(key: string): Error {
+  return new Error(`Invalid Plugin Profile field: ${key}`);
+}

package/src/builtin/renderer/PluginSettingsRenderer.tsx

@@ -0,0 +1,110 @@
+/** 官方简单设置 Plugin 的统一 React Mainview 生成器。 */
+
+import { useCallback, useEffect, useState } from "react";
+import type { PluginJsonObject, PluginJsonValue } from "@downcity/plugin";
+import {
+  define_plugin_renderer,
+  type PluginRendererComponent,
+  type PluginRendererUiComponents,
+} from "@downcity/plugin/react";
+import type { PluginSettingField, PluginSettingsDefinition } from "@/builtin/types/PluginSettings.js";
+
+/** 根据具体 Plugin 的字段声明创建使用宿主 UI Components 的 Mainview。 */
+export function create_plugin_settings_renderer(
+  definition: PluginSettingsDefinition,
+): PluginRendererComponent {
+  return define_plugin_renderer(function PluginSettingsRenderer({ plugin, ui }) {
+    const { Button, Callout, Group, Input, LoadingState, Page, Row, Select, Switch, Toolbar } = ui.components;
+    const [draft, set_draft] = useState<PluginJsonObject>();
+    const [loading, set_loading] = useState(true);
+    const [saving, set_saving] = useState(false);
+    const [error, set_error] = useState("");
+
+    const load = useCallback(async () => {
+      set_loading(true);
+      set_error("");
+      try {
+        set_draft(await plugin.invoke<PluginJsonObject>("profile.read"));
+      } catch (reason) {
+        set_error(to_error_message(reason));
+      } finally {
+        set_loading(false);
+      }
+    }, [plugin]);
+
+    useEffect(() => { void load(); }, [load]);
+
+    const set_field = (field: PluginSettingField, value: PluginJsonValue | undefined) => {
+      set_draft((current) => {
+        const next = { ...(current ?? {}) };
+        if (value === undefined || value === "") delete next[field.key];
+        else next[field.key] = value;
+        return next;
+      });
+    };
+
+    const save = async () => {
+      if (!draft) return;
+      set_saving(true);
+      set_error("");
+      try {
+        const saved = await plugin.invoke<PluginJsonObject>("profile.save", draft);
+        set_draft(saved);
+        ui.toast({ type: "success", message: "Profile 已保存" });
+      } catch (reason) {
+        const message = to_error_message(reason);
+        set_error(message);
+        ui.toast({ type: "error", message });
+      } finally {
+        set_saving(false);
+      }
+    };
+
+    if (loading && !draft) return <LoadingState label="正在读取 Profile…" />;
+
+    return <Page>
+      <Toolbar
+        actions={<Button variant="primary" disabled={!draft || saving} on_click={() => void save()}>{saving ? "保存中…" : "保存"}</Button>}
+      />
+      {error ? <Callout tone="danger">{error}</Callout> : null}
+      <Group>{definition.fields.map((field) => <Row
+        key={field.key}
+        label={field.label}
+        description={field.description}
+        trailing={<SettingControl field={field} value={draft?.[field.key]} set_value={(value) => set_field(field, value)} components={{ Input, Select, Switch }} />}
+      />)}</Group>
+    </Page>;
+  });
+}
+
+/** 根据字段类型选择宿主表单控件。 */
+function SettingControl({ field, value, set_value, components }: {
+  /** 当前字段定义。 */
+  readonly field: PluginSettingField;
+  /** 当前字段值。 */
+  readonly value: PluginJsonValue | undefined;
+  /** 写回字段值。 */
+  set_value(value: PluginJsonValue | undefined): void;
+  /** 当前 Mainview 使用的表单组件。 */
+  readonly components: Pick<PluginRendererUiComponents, "Input" | "Select" | "Switch">;
+}) {
+  const { Input, Select, Switch } = components;
+  if (field.type === "boolean") {
+    return <Switch checked={value === true} on_checked_change={set_value} aria_label={field.label} />;
+  }
+  if (field.type === "select") {
+    return <Select value={typeof value === "string" ? value : ""} options={field.options ?? []} on_value_change={set_value} />;
+  }
+  return <Input
+    type={field.type === "number" ? "number" : "text"}
+    value={typeof value === "string" || typeof value === "number" ? String(value) : ""}
+    minimum={field.minimum}
+    maximum={field.maximum}
+    on_value_change={(next_value) => set_value(field.type === "number" ? next_value === "" ? undefined : Number(next_value) : next_value)}
+  />;
+}
+
+/** 把未知失败转换为用户可见消息。 */
+function to_error_message(reason: unknown): string {
+  return reason instanceof Error ? reason.message : String(reason);
+}

package/src/builtin/types/PluginSettings.ts

@@ -0,0 +1,46 @@
+/** 官方 Plugin 设置 Mainview 的内部声明类型。 */
+
+/** 简单设置字段支持的值类型。 */
+export type PluginSettingFieldType = "string" | "number" | "boolean" | "select";
+
+/** 一个由具体 Plugin 声明的设置字段。 */
+export interface PluginSettingField {
+  /** Profile 配置中的稳定字段名。 */
+  readonly key: string;
+
+  /** Mainview 展示名称。 */
+  readonly label: string;
+
+  /** 可选的用户说明。 */
+  readonly description?: string;
+
+  /** 字段值类型。 */
+  readonly type: PluginSettingFieldType;
+
+  /** 数字字段允许的最小值。 */
+  readonly minimum?: number;
+
+  /** 数字字段允许的最大值。 */
+  readonly maximum?: number;
+
+  /** select 字段允许的稳定选项。 */
+  readonly options?: readonly {
+    /** 保存到配置的值。 */
+    readonly value: string;
+
+    /** Mainview 展示文本。 */
+    readonly label: string;
+  }[];
+}
+
+/** 一个简单设置 Mainview 的完整定义。 */
+export interface PluginSettingsDefinition {
+  /** Mainview 标题。 */
+  readonly title: string;
+
+  /** Mainview 说明。 */
+  readonly description: string;
+
+  /** Plugin 自己拥有的全部配置字段。 */
+  readonly fields: readonly PluginSettingField[];
+}

package/src/chat/ChatPlugin.ts

@@ -10,9 +10,12 @@
 
 import { BasePlugin } from "@downcity/agent";
 import type { PluginActions } from "@downcity/agent";
-import type { PluginContext } from "@downcity/agent";
+import type { PluginContext, AgentPluginContext } from "@downcity/agent";
 import type { PluginExecutionContext } from "@downcity/agent";
-import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
+import type {
+  ChatChannelState,
+  ChatWorkspaceRuntime,
+} from "@/chat/types/ChatRuntime.js";
 import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
 import type {
   ChatChannel,
@@ -52,28 +55,11 @@ export class ChatPlugin extends BasePlugin {
    */
   readonly name = "chat";
 
-  /**
-   * 当前实例持有的渠道状态。
-   */
-  public readonly channelState: ChatChannelState = createChatChannelState();
-
-  /**
-   * 当前实例持有的 chat queue worker。
-   *
-   * 关键点（中文）
-   * - worker 生命周期与 chat plugin 保持一致。
-   * - 这样 agent 只负责装配，不直接持有 chat 领域长期状态。
-   */
-  public queueWorker: ChatQueueWorker | null = null;
+  /** 各 Workspace 独立持有的渠道与队列运行态。 */
+  private readonly runtimes_by_workspace = new Map<string, ChatWorkspaceRuntime>();
 
-  /**
-   * 当前实例持有的 chat queue store。
-   *
-   * 关键点（中文）
-   * - 这是 chat queue 状态的实例归属起点。
-   * - 迁移完成后，入队路径也会统一走这里，而不是模块级全局 queue。
-   */
-  public readonly queueStore = new ChatQueueStore();
+  /** 各 Workspace 当前唯一的懒启动流程，避免 system/action 并发重复连接渠道。 */
+  private readonly starts_by_workspace = new Map<string, Promise<void>>();
 
   /**
    * 当前实例持有的显式 plugin 配置。
@@ -92,6 +78,7 @@ export class ChatPlugin extends BasePlugin {
     context: PluginContext,
     execution_context?: PluginExecutionContext,
   ): Promise<string> => {
+    await this.ensure_workspace_runtime(context);
     return await buildChatPluginSystem(context, execution_context);
   };
 
@@ -103,26 +90,52 @@ export class ChatPlugin extends BasePlugin {
   /**
    * 启动当前实例的 queue worker。
    */
-  private startQueueWorker(context: PluginContext): 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;
+  private async start_workspace_runtime(context: PluginContext): Promise<void> {
+    if (this.runtimes_by_workspace.has(context.workspace_id)) return;
+    const started = this.starts_by_workspace.get(context.workspace_id);
+    if (started) return await started;
+    const start_promise = (async () => {
+      const channel_state = createChatChannelState();
+      const queue_store = new ChatQueueStore();
+      const worker = new ChatQueueWorker({
+        logger: context.logger,
+        context,
+        queueStore: queue_store,
+        config: this.getQueueWorkerConfig(context),
+      });
+      worker.start();
+      this.runtimes_by_workspace.set(context.workspace_id, {
+        channel_state,
+        queue_store,
+        queue_worker: worker,
+      });
+      try {
+        await startChatChannels(channel_state, context);
+      } catch (error) {
+        this.runtimes_by_workspace.delete(context.workspace_id);
+        worker.stop();
+        await stopChatChannels(channel_state);
+        throw error;
+      }
+    })();
+    this.starts_by_workspace.set(context.workspace_id, start_promise);
+    try {
+      await start_promise;
+    } finally {
+      if (this.starts_by_workspace.get(context.workspace_id) === start_promise) {
+        this.starts_by_workspace.delete(context.workspace_id);
+      }
+    }
   }
 
-  /**
-   * 停止当前实例的 queue worker。
-   */
-  private stopQueueWorker(): void {
-    const worker = this.queueWorker;
-    this.queueWorker = null;
-    if (!worker) return;
-    worker.stop();
+  /** 按当前 Workspace Context 懒启动 chat 运行态。 */
+  private async ensure_workspace_runtime(context: PluginContext): Promise<ChatWorkspaceRuntime> {
+    const existing = this.runtimes_by_workspace.get(context.workspace_id);
+    if (existing) return existing;
+    await this.start_workspace_runtime(context);
+    const runtime = this.runtimes_by_workspace.get(context.workspace_id);
+    if (!runtime) throw new Error(`ChatPlugin failed to start Workspace runtime: ${context.workspace_id}`);
+    return runtime;
   }
 
   constructor(options?: ChatPluginOptions) {
@@ -133,22 +146,57 @@ export class ChatPlugin extends BasePlugin {
       : createDefaultChannels();
     this.actions = {
       ...createChatPluginActions({
-        channelState: this.channelState,
+        resolve_channel_state: (context) => this.resolve_channel_state(context),
       }),
       ...create_chat_access_actions(),
     };
     this.lifecycle = {
-      start: async (context) => {
-        this.startQueueWorker(context);
-        await startChatChannels(this.channelState, context);
-      },
-      stop: async () => {
-        this.stopQueueWorker();
-        await stopChatChannels(this.channelState);
+      start: async (_context: AgentPluginContext) => {},
+      stop: async (_context: AgentPluginContext) => {
+        await Promise.allSettled([...this.starts_by_workspace.values()]);
+        await Promise.all([...this.runtimes_by_workspace.values()].map(async (runtime) => {
+          runtime.queue_worker.stop();
+          await stopChatChannels(runtime.channel_state);
+        }));
+        this.runtimes_by_workspace.clear();
+        this.starts_by_workspace.clear();
       },
     };
   }
 
+  /** 读取当前 Workspace 的渠道状态。 */
+  private resolve_channel_state(context: PluginContext): ChatChannelState {
+    const runtime = this.runtimes_by_workspace.get(context.workspace_id);
+    if (!runtime) {
+      const channel_state = createChatChannelState();
+      const queue_store = new ChatQueueStore();
+      const worker = new ChatQueueWorker({
+        logger: context.logger,
+        context,
+        queueStore: queue_store,
+        config: this.getQueueWorkerConfig(context),
+      });
+      worker.start();
+      const created = { channel_state, queue_store, queue_worker: worker } satisfies ChatWorkspaceRuntime;
+      this.runtimes_by_workspace.set(context.workspace_id, created);
+      void startChatChannels(channel_state, context).catch((error) => {
+        context.logger.warn(`[chat] channel startup failed: ${String(error)}`);
+      });
+      return channel_state;
+    }
+    return runtime.channel_state;
+  }
+
+  /** 向 chat 入队路径暴露当前 Workspace 的独立队列。 */
+  queue_store(context: PluginContext): ChatQueueStore {
+    const runtime = this.runtimes_by_workspace.get(context.workspace_id);
+    if (!runtime) {
+      this.resolve_channel_state(context);
+      return this.runtimes_by_workspace.get(context.workspace_id)!.queue_store;
+    }
+    return runtime.queue_store;
+  }
+
   /**
    * 读取 queue worker 配置。
    */
@@ -169,11 +217,11 @@ export class ChatPlugin extends BasePlugin {
   /**
    * 读取指定渠道的显式账户 ID。
    */
-  getResourceId(
+  get_channel_id(
     context: PluginContext,
     channel: ChatChannelName,
   ): string {
-    return String(this.getChannel(channel)?.getResourceId(context) || "").trim();
+    return String(this.getChannel(channel)?.get_channel_id(context) || "").trim();
   }
 
   /**

package/src/chat/access/ChatAccessRuntime.ts

@@ -28,7 +28,7 @@ export function resolve_chat_access_issuer_map(
 /** 创建当前 Agent 的 ChatAccessService。 */
 export function create_chat_access_service(context: PluginContext): ChatAccessService {
   return new ChatAccessService({
-    project_root: context.workspace_path,
+    data_path: context.data_path,
   });
 }
 

package/src/chat/access/ChatAccessSchema.ts

@@ -7,7 +7,7 @@
  * - WAL 与 busy_timeout 保证 Agent runtime 和 CLI 可以并发读写。
  */
 
-import type Database from "better-sqlite3";
+import type { DatabaseSync } from "node:sqlite";
 
 /** 当前 Chat Access Schema 版本。 */
 export const CHAT_ACCESS_SCHEMA_VERSION = "1";
@@ -15,10 +15,10 @@ export const CHAT_ACCESS_SCHEMA_VERSION = "1";
 /**
  * 初始化 Chat Access Schema。
  */
-export function ensure_chat_access_schema(database: Database.Database): void {
-  database.pragma("journal_mode = WAL");
-  database.pragma("foreign_keys = ON");
-  database.pragma("busy_timeout = 5000");
+export function ensure_chat_access_schema(database: DatabaseSync): void {
+  database.exec("PRAGMA journal_mode = WAL;");
+  database.exec("PRAGMA foreign_keys = ON;");
+  database.exec("PRAGMA busy_timeout = 5000;");
 
   database.exec(`
     CREATE TABLE IF NOT EXISTS chat_access_meta (

package/src/chat/access/ChatAccessService.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 所有平台共用相同的 Principal、Grant、Request 和 Audit 业务规则。
  * - Chat Access 只做准入判定，不向 Agent Session 或其他 Plugin 传播权限。
- * - 每个方法自行打开并关闭项目级 Store，避免 Channel 生命周期遗漏连接释放。
+ * - 每个方法自行打开并关闭 Agent private runtime directory Store，避免 Channel 生命周期遗漏连接释放。
  */
 
 import path from "node:path";
@@ -63,13 +63,13 @@ export function resolve_chat_access_scope(
  * 当前 Agent 的 Chat Access 应用服务。
  */
 export class ChatAccessService {
-  private readonly project_root: string;
+  private readonly data_path: string;
   constructor(options: ChatAccessServiceOptions) {
-    this.project_root = path.resolve(normalize_text(options.project_root) || ".");
+    this.data_path = path.resolve(normalize_text(options.data_path) || ".");
   }
 
   private with_store<T>(operation: (store: ChatAccessStore) => T): T {
-    const store = new ChatAccessStore(this.project_root);
+    const store = new ChatAccessStore(this.data_path);
     try {
       return operation(store);
     } finally {

package/src/chat/access/ChatAccessStore.ts

@@ -7,7 +7,7 @@
  * - Service 负责业务编排，Store 只负责结构化读写和事务。
  */
 
-import Database from "better-sqlite3";
+import { DatabaseSync } from "node:sqlite";
 import fs from "fs-extra";
 import path from "node:path";
 import { generate_id } from "@downcity/agent";
@@ -34,10 +34,10 @@ import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
 type SqlRow = Record<string, unknown>;
 
 /**
- * 返回项目级 Chat Access 数据库路径。
+ * 返回 Agent private runtime directory Chat Access 数据库路径。
  */
-export function get_chat_access_db_path(project_root: string): string {
-  return path.join(path.resolve(project_root), ".downcity", "chat", "access.db");
+export function get_chat_access_db_path(data_path: string): string {
+  return path.join(path.resolve(data_path), "chat", "access.db");
 }
 
 function normalize_text(value: unknown): string {
@@ -126,15 +126,15 @@ function to_request(row: SqlRow | undefined): ChatAccessRequest | null {
  * 当前 Agent 的 Chat Access SQLite Store。
  */
 export class ChatAccessStore {
-  private readonly database: Database.Database;
+  private readonly database: DatabaseSync;
 
   /**
    * 打开当前项目 Chat Access 数据库。
    */
-  constructor(project_root: string) {
-    const database_path = get_chat_access_db_path(project_root);
+  constructor(data_path: string) {
+    const database_path = get_chat_access_db_path(data_path);
     fs.ensureDirSync(path.dirname(database_path), { mode: 0o700 });
-    this.database = new Database(database_path);
+    this.database = new DatabaseSync(database_path);
     ensure_chat_access_schema(this.database);
     try {
       fs.chmodSync(database_path, 0o600);
@@ -150,7 +150,15 @@ export class ChatAccessStore {
 
   /** 在单个 SQLite 事务中执行操作。 */
   transaction<T>(operation: () => T): T {
-    return this.database.transaction(operation)();
+    this.database.exec("BEGIN IMMEDIATE;");
+    try {
+      const result = operation();
+      this.database.exec("COMMIT;");
+      return result;
+    } catch (error) {
+      this.database.exec("ROLLBACK;");
+      throw error;
+    }
   }
 
   /** 读取 Store 元信息。 */

package/src/chat/channels/BaseChatChannel.ts

@@ -131,6 +131,7 @@ export abstract class BaseChatChannel {
   readonly channel: ChatDispatchChannel;
   protected readonly context: PluginContext;
   protected readonly rootPath: string;
+  protected readonly dataPath: string;
   protected readonly logger: Logger;
   private readonly access_notice_sent_at = new Map<string, number>();
 
@@ -141,6 +142,7 @@ export abstract class BaseChatChannel {
     this.channel = params.channel;
     this.context = params.context;
     this.rootPath = params.context.workspace_path;
+    this.dataPath = params.context.data_path;
     this.logger = params.context.logger;
 
     const dispatcher: ChatDispatcher = {