@downcity/plugins 1.0.254 → 1.0.280

package/scripts/sound-plugin.test.mjs

@@ -15,6 +15,18 @@ import path from "node:path";
 
 import { SoundPlugin } from "../bin/index.js";
 
+function create_sound_plugin(options = {}) {
+  const { list_models, asr, tts, ...profile } = options;
+  return new SoundPlugin({
+    ...profile,
+    sound_ai: {
+      catalog: async () => ({ all: () => (list_models ? list_models() : []) }),
+      asr,
+      tts,
+    },
+  });
+}
+
 function create_context(root_path) {
   return {
     workspace_path: root_path,
@@ -37,7 +49,7 @@ function create_tts_message(url = "/workspace/speech.mp3") {
     parts: [
       {
         type: "file",
-        mediaType: "audio/mpeg",
+        media_type: "audio/mpeg",
         filename: "speech.mp3",
         url,
       },
@@ -46,7 +58,7 @@ function create_tts_message(url = "/workspace/speech.mp3") {
 }
 
 test("sound.models 只返回 FED 中支持 ASR 或 TTS 的模型", async () => {
-  const plugin = new SoundPlugin({
+  const plugin = create_sound_plugin({
     list_models: () => [
       { id: "asr", name: "ASR", modalities: ["asr"] },
       { id: "tts", name: "TTS", modalities: ["tts"] },
@@ -76,7 +88,7 @@ test("sound.asr 把本地音频转为 data URL 后直接调用 FED", async () =>
   const audio_path = path.join(root_path, "voice.wav");
   await fs.writeFile(audio_path, Buffer.from("audio-test"));
   let received_input;
-  const plugin = new SoundPlugin({
+  const plugin = create_sound_plugin({
     default_asr_model: "fed-asr",
     asr: async (input) => {
       received_input = input;
@@ -117,7 +129,7 @@ test("sound.asr 把本地音频转为 data URL 后直接调用 FED", async () =>
 test("sound.tts 使用默认参数并返回 AI SDK UIMessage", async () => {
   let received_input;
   const message = create_tts_message();
-  const plugin = new SoundPlugin({
+  const plugin = create_sound_plugin({
     default_tts_model: "fed-tts",
     language: "zh",
     voice: "alloy",
@@ -151,7 +163,7 @@ test("sound.tts 使用默认参数并返回 AI SDK UIMessage", async () => {
 });
 
 test("sound action 不会隐式选择模型或接受非 UIMessage TTS 结果", async () => {
-  const plugin = new SoundPlugin({
+  const plugin = create_sound_plugin({
     asr: async () => ({ text: "ok" }),
     tts: async () => ({ url: "https://example.com/speech.mp3" }),
   });
@@ -172,7 +184,7 @@ test("sound action 不会隐式选择模型或接受非 UIMessage TTS 结果", a
 });
 
 test("sound.asr 只接受一种音频来源", async () => {
-  const plugin = new SoundPlugin({
+  const plugin = create_sound_plugin({
     asr: async () => ({ text: "ok" }),
     tts: async () => create_tts_message(),
   });
@@ -186,7 +198,7 @@ test("sound.asr 只接受一种音频来源", async () => {
 });
 
 test("sound.tts 要求 UIMessage 包含音频 file part", async () => {
-  const plugin = new SoundPlugin({
+  const plugin = create_sound_plugin({
     asr: async () => ({ text: "ok" }),
     tts: async () => ({
       id: "sound:text-only",
@@ -204,7 +216,7 @@ test("sound.tts 要求 UIMessage 包含音频 file part", async () => {
 
 test("auto_asr 必须配置默认 ASR 模型", () => {
   assert.throws(
-    () => new SoundPlugin({
+    () => create_sound_plugin({
       auto_asr: true,
       asr: async () => ({ text: "ok" }),
       tts: async () => create_tts_message(),
@@ -217,7 +229,7 @@ test("auto_asr 把 chat 语音附件转写追加到正文", async () => {
   const root_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-sound-auto-"));
   const audio_path = path.join(root_path, "message.ogg");
   await fs.writeFile(audio_path, Buffer.from("voice"));
-  const plugin = new SoundPlugin({
+  const plugin = create_sound_plugin({
     auto_asr: true,
     default_asr_model: "fed-asr",
     asr: async () => ({ text: "hello <world>" }),

package/scripts/unrestricted-sandbox-approval.test.mjs

@@ -22,7 +22,7 @@ import {
   setShellApprovalModeView,
   startShellSession,
   writeShellSession,
-} from "@downcity/shell/session/ShellActionRuntime.js";
+} from "@downcity/workspace/shell/session/ShellActionRuntime.js";
 
 async function create_fixture() {
   const root_path = await fs.mkdtemp(path.join(os.tmpdir(), "downcity-unrestricted-"));

package/scripts/web-plugin.test.mjs

@@ -1,76 +1,11 @@
-/**
- * WebPlugin provider-neutral action 回归测试。
- *
- * 关键点（中文）
- * - Plugin 必须显式注入 provider，不能只注册一段方法论。
- * - 浏览器 action 保持结构化输入输出，并在 lifecycle.stop 时释放 provider。
- * - 缺少某项 provider 时只让对应 action 返回明确失败。
- */
+/** WebPlugin 配置与运行时上下文能力回归测试。 */
 
 import assert from "node:assert/strict";
 import test from "node:test";
-import {
-  ComputerUseBrowserProviderAdapter,
-  SemanticBrowserProviderAdapter,
-  WebPlugin,
-} from "../bin/index.js";
+import { WebPlugin } from "../bin/index.js";
 
-function create_browser_provider() {
-  const sessions = new Map();
-  let disposed = false;
-  return {
-    name: "mock-browser",
-    get disposed() { return disposed; },
-    async create_session(input) {
-      const session_id = "browser-session-1";
-      const state = {
-        provider: this.name,
-        session_id,
-        url: input.url || "about:blank",
-        title: "Mock page",
-        text: "Initial page",
-      };
-      sessions.set(session_id, state);
-      return state;
-    },
-    async observe(input) {
-      const state = sessions.get(input.session_id);
-      if (!state) throw new Error(`Browser session not found: ${input.session_id}`);
-      return state;
-    },
-    async act(input) {
-      const state = sessions.get(input.session_id);
-      if (!state) throw new Error(`Browser session not found: ${input.session_id}`);
-      const next = { ...state, text: `acted:${input.action.type}` };
-      sessions.set(input.session_id, next);
-      return next;
-    },
-    async extract(input) {
-      const state = sessions.get(input.session_id);
-      if (!state) throw new Error(`Browser session not found: ${input.session_id}`);
-      return {
-        provider: this.name,
-        session_id: input.session_id,
-        url: state.url,
-        content: state.text,
-      };
-    },
-    async close_session(input) {
-      sessions.delete(input.session_id);
-    },
-    async dispose() {
-      sessions.clear();
-      disposed = true;
-    },
-  };
-}
-
-test("WebPlugin 拒绝没有真实能力的空配置", () => {
-  assert.throws(() => new WebPlugin({}), /requires at least one provider/);
-});
-
-test("WebPlugin 暴露结构化联网与浏览器 actions", () => {
-  const plugin = new WebPlugin({ browser: create_browser_provider() });
+test("WebPlugin 允许空配置并暴露稳定 actions", () => {
+  const plugin = new WebPlugin();
   assert.deepEqual(Object.keys(plugin.actions), [
     "search",
     "open",
@@ -82,142 +17,64 @@ test("WebPlugin 暴露结构化联网与浏览器 actions", () => {
     "browser_semantic_extract",
     "browser_close_session",
   ]);
-  assert.equal(plugin.actions.install, undefined);
-  assert.match(plugin.system(), /deterministic CSS-selector operations/);
+  assert.match(plugin.system(), /direct search or document reading/u);
 });
 
-test("search 与 open 委托给独立 provider", async () => {
-  const plugin = new WebPlugin({
-    search: async (input) => ({
-      provider: "mock-search",
-      items: [{ url: "https://example.com", title: input.query }],
-    }),
-    open: async (input) => ({
-      provider: "mock-reader",
-      url: input.url,
-      title: "Example",
-      content: "Example content",
-    }),
-  });
-
+test("search 与 open 从 PluginContext 读取宿主 Web 能力", async () => {
+  const plugin = new WebPlugin();
+  const context = {
+    web: {
+      async search(input) {
+        return {
+          provider: "mock-search",
+          items: [{ url: "https://example.com", title: input.query }],
+        };
+      },
+      async open(input) {
+        return {
+          provider: "mock-reader",
+          url: input.url,
+          title: "Example",
+          content: "Example content",
+        };
+      },
+    },
+  };
   const search_result = await plugin.actions.search.execute({
-    context: {},
+    context,
     input: { query: "official docs" },
   });
   const open_result = await plugin.actions.open.execute({
-    context: {},
+    context,
     input: { url: "https://example.com" },
   });
-
   assert.equal(search_result.success, true);
   assert.equal(search_result.data.provider, "mock-search");
   assert.equal(open_result.success, true);
   assert.equal(open_result.data.content, "Example content");
 });
 
-test("浏览器 session 完整执行 create、act、extract 与 close", async () => {
-  const browser = create_browser_provider();
-  const plugin = new WebPlugin({ browser });
-  const created = await plugin.actions.browser_create_session.execute({
-    context: {},
-    input: { url: "https://example.com" },
-  });
-  const session_id = created.data.session_id;
-
-  const acted = await plugin.actions.browser_act.execute({
-    context: {},
-    input: { session_id, action: { type: "click", selector: "a" } },
-  });
-  const extracted = await plugin.actions.browser_extract.execute({
-    context: {},
-    input: { session_id },
-  });
-  const closed = await plugin.actions.browser_close_session.execute({
-    context: {},
-    input: { session_id },
-  });
-
-  assert.equal(created.success, true);
-  assert.equal(acted.data.text, "acted:click");
-  assert.equal(extracted.data.content, "acted:click");
-  assert.deepEqual(closed.data, { session_id, closed: true });
-});
-
-test("语义 adapter 复用基础 session 并暴露语义 actions", async () => {
-  const base_browser = create_browser_provider();
-  const browser = new SemanticBrowserProviderAdapter({
-    name: "mock-semantic",
-    browser: base_browser,
-    semantic_act: async (input) => ({
-      ...(await base_browser.observe({ session_id: input.session_id })),
-      text: `semantic:${input.instruction}`,
-    }),
-    semantic_extract: async (input) => ({
-      provider: "mock-semantic",
-      session_id: input.session_id,
-      url: "https://example.com",
-      content: `semantic-extract:${input.instruction}`,
-    }),
-  });
-  const plugin = new WebPlugin({ browser });
-  const created = await plugin.actions.browser_create_session.execute({
-    context: {},
-    input: { url: "https://example.com" },
-  });
-  const session_id = created.data.session_id;
-  const acted = await plugin.actions.browser_semantic_act.execute({
-    context: {},
-    input: { session_id, instruction: "click the login button" },
-  });
-  const extracted = await plugin.actions.browser_semantic_extract.execute({
+test("缺少运行时能力或 CDP 配置时只让对应 action 失败", async () => {
+  const plugin = new WebPlugin();
+  const search_result = await plugin.actions.search.execute({
     context: {},
-    input: { session_id, instruction: "extract the account name" },
-  });
-
-  assert.equal(acted.success, true);
-  assert.equal(acted.data.text, "semantic:click the login button");
-  assert.equal(extracted.data.content, "semantic-extract:extract the account name");
-});
-
-test("Computer Use adapter 先获取截图观察再委托模型循环", async () => {
-  const base_browser = create_browser_provider();
-  const browser = new ComputerUseBrowserProviderAdapter({
-    name: "mock-computer-use",
-    browser: base_browser,
-    run: async ({ instruction, observation }) => ({
-      ...observation,
-      text: `computer-use:${instruction}`,
-      screenshot_data_url: observation.screenshot_data_url ?? "data:image/png;base64,mock",
-    }),
+    input: { query: "test" },
   });
-  const plugin = new WebPlugin({ browser });
-  const created = await plugin.actions.browser_create_session.execute({
+  const browser_result = await plugin.actions.browser_create_session.execute({
     context: {},
     input: { url: "https://example.com" },
   });
-  const result = await plugin.actions.browser_semantic_act.execute({
-    context: {},
-    input: {
-      session_id: created.data.session_id,
-      instruction: "drag the map",
-    },
-  });
-
-  assert.equal(result.success, true);
-  assert.equal(result.data.text, "computer-use:drag the map");
-  assert.match(result.data.screenshot_data_url, /^data:image\/png;base64/);
-});
-
-test("未配置的 action 返回明确失败，lifecycle.stop 释放浏览器", async () => {
-  const browser = create_browser_provider();
-  const plugin = new WebPlugin({ browser });
-  const search_result = await plugin.actions.search.execute({
-    context: {},
-    input: { query: "test" },
-  });
   assert.equal(search_result.success, false);
-  assert.match(search_result.error, /not configured/);
+  assert.match(search_result.error, /not configured/u);
+  assert.equal(browser_result.success, false);
+  assert.match(browser_result.error, /not configured/u);
+  await plugin.lifecycle.stop();
+});
 
-  await plugin.lifecycle.stop({});
-  assert.equal(browser.disposed, true);
+test("WebPlugin 只接受公开的浏览器 provider 枚举", () => {
+  assert.doesNotThrow(() => new WebPlugin({ browser: "playwright" }));
+  assert.throws(
+    () => new WebPlugin({ browser: "unknown" }),
+    /Unsupported Web browser provider/u,
+  );
 });

package/src/builtin/BuiltinPluginReadmes.ts

@@ -0,0 +1,58 @@
+/** Downcity 官方 Plugin 的用户说明内容。 */
+
+/** 官方 Plugin 在宿主 Overview 中展示的 Markdown 说明。 */
+export const BUILTIN_PLUGIN_READMES = {
+  skill: `# Skill Catalog And Loader
+
+Discovers skills available to the Agent, reads their instructions, and adds guidance for selecting the right skill during a task.
+
+## What it provides
+
+- Lists and inspects installed skills.
+- Loads skill instructions only when they are relevant.
+- Keeps skill discovery separate from the Agent definition.`,
+  workboard: `# Workboard Snapshot
+
+Collects structured snapshots of Agent runtime activity so work can be inspected and presented consistently.
+
+The Plugin owns snapshot collection and normalization; it does not change how an Agent executes a task.`,
+  contact: `# Contact
+
+Manages trusted relationships with remote Agents and provides the actions required to exchange messages and shared information.
+
+Contact state is stored in the current Agent's private Plugin data directory.`,
+  task: `# Task
+
+Creates and manages reusable Agent tasks, trigger definitions, and execution records.
+
+Tasks remain Agent-owned runtime resources and can be scheduled or invoked through the Plugin's actions.`,
+  chat: `# Chat
+
+Connects an Agent to external conversations through Telegram, Feishu / Lark, and QQ.
+
+## Profiles and Channels
+
+- Each Profile contains one complete Chat configuration.
+- A Channel type can appear once in the same Profile.
+- Credentials stay in Plugin configuration and are not copied into \`agent.json\`.`,
+  memory: `# Memory
+
+Provides provider-neutral long-term memory with recall, revision, and deletion capabilities.
+
+Memory data belongs to the current Agent and is stored in that Agent's private Plugin runtime directory.`,
+  web: `# Web
+
+Provides web search, document reading, and optional browser sessions to an Agent.
+
+Use Profiles to isolate provider endpoints, credentials, and browser settings for different environments.`,
+  image: `# Image
+
+Discovers available image models, generates images, and returns structured result metadata.
+
+Use Profiles to keep image service endpoints and credentials separate between environments.`,
+  sound: `# Sound
+
+Discovers speech models and provides automatic speech recognition and text-to-speech actions.
+
+Use Profiles to isolate speech service endpoints, models, and credentials.`,
+} as const;

package/src/builtin/BuiltinPluginTypes.ts

@@ -0,0 +1,260 @@
+/**
+ * Downcity 官方 Plugin 注册集合。
+ *
+ * 本模块负责把官方 Plugin 按应用配置装配成 Agent 独享实例。应用提供
+ * Embassy 服务，Plugin 自身只持有明确的服务接口。
+ */
+
+import type { Plugin } from "@downcity/agent";
+import type { PluginHostContext } from "@downcity/agent";
+import type { PluginMainModule } from "@downcity/plugin";
+import { CHAT_PLUGIN_MAIN } from "@/chat/main/ChatPluginMain.js";
+import {
+  IMAGE_PLUGIN_SETTINGS,
+  SOUND_PLUGIN_SETTINGS,
+  WEB_PLUGIN_SETTINGS,
+} from "@/builtin/PluginSettingsDefinitions.js";
+import { create_plugin_settings_main } from "@/builtin/main/PluginSettingsMain.js";
+import { BUILTIN_PLUGIN_READMES } from "@/builtin/BuiltinPluginReadmes.js";
+import {
+  ChatPlugin,
+  type ChatPluginConfig,
+  type ChatPluginChannelConfig,
+} from "@/chat.js";
+import { FeishuChannel, QqChannel, TelegramChannel } from "@/chat.js";
+import { ContactPlugin } from "@/contact.js";
+import { ImagePlugin } from "@/image.js";
+import {
+  MemoryPlugin,
+} from "@/memory.js";
+import { SkillPlugin } from "@/skill.js";
+import { SoundPlugin } from "@/sound.js";
+import { TaskPlugin } from "@/task.js";
+import {
+  WebPlugin,
+  type WebPluginOptions,
+} from "@/web.js";
+import { WorkboardPlugin } from "@/workboard.js";
+
+/** 官方 Plugin definition 的最小结构协议。 */
+export interface BuiltinPluginDefinition {
+  /** Plugin 的稳定 ID。 */
+  id: string;
+
+  /** Plugin 的用户可见标题。 */
+  title: string;
+
+  /** Plugin 的用途说明。 */
+  description: string;
+
+  /** 宿主 Overview 展示的完整 Markdown 用户说明。 */
+  readme: string;
+
+  /** 官方 Plugin 是否提供 Agent 能力。 */
+  has_agent: boolean;
+
+  /** 官方 Plugin 是否提供宿主 main。 */
+  has_main: boolean;
+
+  /** 官方 Plugin 是否提供唯一 Mainview。 */
+  has_renderer: boolean;
+}
+
+/** 官方 Plugin 注册协议。 */
+export interface BuiltinPluginRegistration {
+  /** Plugin 的唯一静态定义。 */
+  readonly definition: BuiltinPluginDefinition;
+  /** 使用 City 读取的 Profile 创建一个 Agent 独享的 Plugin 实例。 */
+  create_agent(context: PluginHostContext): Plugin | Promise<Plugin>;
+
+  /** 可选的宿主 main 生命周期对象。 */
+  main?: PluginMainModule;
+
+}
+
+/** 创建官方 Plugin 注册集合所需的宿主能力。 */
+export interface BuiltinPluginRegistrationsOptions {
+  /** Contact Plugin 对外报告的 HTTP 地址。 */
+  contact_http?: {
+    /** HTTP 监听地址。 */
+    host?: string;
+    /** HTTP 监听端口。 */
+    port?: number;
+  };
+
+}
+
+/** 创建 Downcity 官方 Plugin 注册集合。 */
+export function create_builtin_plugin_registrations(
+  options: BuiltinPluginRegistrationsOptions,
+): BuiltinPluginRegistration[] {
+  return [
+    simple_registration(
+      "skill",
+      "Skill Catalog And Loader",
+      "Lists and reads local skills, and injects discovery guidance.",
+      BUILTIN_PLUGIN_READMES.skill,
+      () => new SkillPlugin(),
+    ),
+    simple_registration(
+      "workboard",
+      "Workboard Snapshot",
+      "Collects structured Agent runtime activity snapshots.",
+      BUILTIN_PLUGIN_READMES.workboard,
+      () => new WorkboardPlugin(),
+    ),
+    simple_registration(
+      "contact",
+      "Contact",
+      "Manages trusted relationships and exchanges with remote Agents.",
+      BUILTIN_PLUGIN_READMES.contact,
+      () => new ContactPlugin({
+        host: options.contact_http?.host,
+        port: options.contact_http?.port,
+      }),
+    ),
+    simple_registration(
+      "task",
+      "Task",
+      "Manages reusable tasks and their trigger runtime.",
+      BUILTIN_PLUGIN_READMES.task,
+      () => new TaskPlugin(),
+    ),
+    {
+      definition: {
+        id: "chat",
+        title: "Chat",
+        description: "Connects Agents to Telegram, Feishu, and QQ channels.",
+        readme: BUILTIN_PLUGIN_READMES.chat,
+        has_agent: true,
+        has_main: true,
+        has_renderer: true,
+      },
+      main: CHAT_PLUGIN_MAIN,
+      create_agent(context) {
+        const config = context.profile as unknown as ChatPluginConfig;
+        return new ChatPlugin({
+          queue: config.queue,
+          channels: create_chat_channels(config.channels ?? []),
+        });
+      },
+    },
+    {
+      definition: {
+        id: "memory",
+        title: "Memory",
+        description: "Provides provider-neutral long-term memory, recall, revision, and deletion.",
+        readme: BUILTIN_PLUGIN_READMES.memory,
+        has_agent: true,
+        has_main: false,
+        has_renderer: false,
+      },
+      create_agent(context) {
+        return new MemoryPlugin({ root_path: context.data_path });
+      },
+    },
+    {
+      definition: {
+        id: "web",
+        title: "Web",
+        description: "Provides web search, document reading, and optional browser sessions.",
+        readme: BUILTIN_PLUGIN_READMES.web,
+        has_agent: true,
+        has_main: true,
+        has_renderer: true,
+      },
+      main: create_plugin_settings_main(WEB_PLUGIN_SETTINGS),
+      create_agent(context) {
+        const config = context.profile as unknown as WebPluginOptions;
+        return new WebPlugin(config);
+      },
+    },
+    {
+      definition: {
+        id: "image",
+        title: "Image",
+        description: "Discovers image models, generates images, and reads results.",
+        readme: BUILTIN_PLUGIN_READMES.image,
+        has_agent: true,
+        has_main: true,
+        has_renderer: true,
+      },
+      main: create_plugin_settings_main(IMAGE_PLUGIN_SETTINGS),
+      create_agent: (context) => new ImagePlugin({
+        ...context.profile,
+      }),
+    },
+    {
+      definition: {
+        id: "sound",
+        title: "Sound",
+        description: "Discovers speech models and provides ASR and TTS.",
+        readme: BUILTIN_PLUGIN_READMES.sound,
+        has_agent: true,
+        has_main: true,
+        has_renderer: true,
+      },
+      main: create_plugin_settings_main(SOUND_PLUGIN_SETTINGS),
+      create_agent: (context) => new SoundPlugin({
+        ...context.profile,
+      }),
+    },
+  ];
+}
+
+/** 获取并适配官方 ImagePlugin 所需的 Embassy 图片服务。 */
+/** 创建没有配置协议的简单注册。 */
+function simple_registration(
+  id: string,
+  title: string,
+  description: string,
+  readme: string,
+  create_agent: () => Plugin,
+): BuiltinPluginRegistration {
+  return {
+    definition: {
+      id,
+      title,
+      description,
+      readme,
+      has_agent: true,
+      has_main: false,
+      has_renderer: false,
+    },
+    create_agent,
+  };
+}
+
+/** 创建 Chat Resource 对应的运行渠道。 */
+function create_chat_channels(configs: ChatPluginChannelConfig[]) {
+  const channel_types = new Set<string>();
+  return configs.map((config) => {
+    if (channel_types.has(config.type)) {
+      throw new Error(`Chat Plugin channel type is duplicated: ${config.type}`);
+    }
+    channel_types.add(config.type);
+    if (config.type === "telegram") {
+      return new TelegramChannel({
+        id: config.id,
+        name: config.name,
+        bot_token: config.bot_token,
+      });
+    }
+    if (config.type === "feishu") {
+      return new FeishuChannel({
+        id: config.id,
+        name: config.name,
+        app_id: config.app_id,
+        app_secret: config.app_secret,
+        domain: config.domain,
+      });
+    }
+    return new QqChannel({
+      id: config.id,
+      name: config.name,
+      app_id: config.app_id,
+      app_secret: config.app_secret,
+      sandbox: config.sandbox,
+    });
+  });
+}