@downcity/plugins 1.0.248 → 1.0.253

package/src/web/Plugin.ts

@@ -1,151 +1,315 @@
 /**
- * WebPlugin：联网方法论注入插件。
+ * WebPlugin：provider-neutral 的联网与浏览器能力边界。
  *
  * 关键点（中文）
- * - web plugin 不选择 provider，也不持久化 provider 运行态。
- * - install action 只返回联网能力安装提示，不执行命令或修改文件。
- * - 它只通过 `system()` 注入联网研究与浏览器使用方法论。
- * - 具体执行能力由当前 agent 已注册的 tools、skills 或外部 plugin 决定。
+ * - Plugin 只编排已显式注入的 provider，不选择云厂商或模型。
+ * - 搜索、文档读取与浏览器 session 是三个独立能力。
+ * - 浏览器长期资源由 provider 拥有，并在 Plugin lifecycle.stop 时统一释放。
  */
 
-import { BasePlugin } from "@downcity/agent";
-import { create_action } from "@downcity/agent";
+import { BasePlugin, create_action } from "@downcity/agent";
+import type { JsonObject, PluginActionResult } from "@downcity/agent";
 import { z } from "zod";
-import type { PluginContext } from "@downcity/agent";
-import type { JsonObject, JsonValue, PluginActionResult } from "@downcity/agent";
-import { WEB_PLUGIN_PROMPT } from "@/web/WebPromptAssets.js";
-import { render_web_install_prompt } from "@/web/runtime/Prompt.js";
-import type { WebPluginInstallPayload } from "@/web/types/WebPlugin.js";
+import type {
+  BrowserActInput,
+  BrowserCloseSessionInput,
+  BrowserCreateSessionInput,
+  BrowserExtractInput,
+  BrowserObserveInput,
+  BrowserSemanticActInput,
+  BrowserSemanticExtractInput,
+  WebOpenInput,
+  WebPluginOptions,
+  WebSearchInput,
+} from "@/web/types/WebPlugin.js";
 import { WEB_PLUGIN_ACTIONS } from "@/web/types/WebPlugin.js";
 
-/**
- * 读取字符串选项。
- */
-function get_string_opt(
-  opts: Record<string, JsonValue>,
-  key: string,
-): string | undefined {
-  const value = opts[key];
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed || undefined;
-}
+const URL_SCHEMA = z.string().url();
+const SESSION_ID_SCHEMA = z.string().trim().min(1);
+const MAX_CHARS_SCHEMA = z.number().int().min(1).max(100_000).optional();
 
-/**
- * 读取安装目标。
- */
-function get_install_target_opt(
-  opts: Record<string, JsonValue>,
-): "web-access" | "agent-browser" | "all" | undefined {
-  const value = get_string_opt(opts, "target");
-  if (value === "web-access" || value === "agent-browser" || value === "all") {
-    return value;
-  }
-  return undefined;
-}
+const BROWSER_ACTION_SCHEMA = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("goto"), url: URL_SCHEMA }),
+  z.object({ type: z.literal("click"), selector: z.string().trim().min(1) }),
+  z.object({
+    type: z.literal("fill"),
+    selector: z.string().trim().min(1),
+    value: z.string(),
+  }),
+  z.object({
+    type: z.literal("press"),
+    selector: z.string().trim().min(1),
+    key: z.string().trim().min(1),
+  }),
+  z.object({
+    type: z.literal("scroll"),
+    x: z.number().optional(),
+    y: z.number().optional(),
+  }),
+  z.object({
+    type: z.literal("wait"),
+    milliseconds: z.number().int().min(0).max(60_000).optional(),
+  }),
+]);
 
-/**
- * 读取安装作用域。
- */
-function get_install_scope_opt(
-  opts: Record<string, JsonValue>,
-): "user" | "project" | undefined {
-  const value = get_string_opt(opts, "scope");
-  if (value === "user" || value === "project") return value;
-  return undefined;
+/** 把异常转换为 action 的稳定失败结果。 */
+function failure_result(error: unknown): PluginActionResult<JsonObject> {
+  const message = error instanceof Error ? error.message : String(error);
+  return { success: false, error: message, message };
 }
 
-/**
- * WebPlugin：为 agent 注入联网任务的方法论。
- */
+/** WebPlugin：组合显式注入的 Web provider。 */
 export class WebPlugin extends BasePlugin {
-  /**
-   * 当前 plugin 稳定名称。
-   */
+  /** 当前 plugin 稳定名称。 */
   readonly name = "web";
 
-  /**
-   * 插件标题。
-   */
-  readonly title = "Web Methodology";
+  /** 插件标题。 */
+  readonly title = "Web";
 
-  /**
-   * 插件说明。
-   */
+  /** 插件说明。 */
   readonly description =
-    "Injects web research and browser-use methodology for agents.";
+    "Provides structured web search, document reading, and browser sessions through configured providers.";
+
+  /** 搜索 provider。 */
+  private readonly search_provider?: WebPluginOptions["search"];
 
-  /**
-   * WebPlugin 对外 action。
-   */
+  /** 文档读取 provider。 */
+  private readonly open_provider?: WebPluginOptions["open"];
+
+  /** 浏览器 provider。 */
+  private readonly browser_provider?: WebPluginOptions["browser"];
+
+  constructor(options: WebPluginOptions) {
+    super();
+    if (!options.search && !options.open && !options.browser) {
+      throw new TypeError("WebPlugin requires at least one provider");
+    }
+    this.search_provider = options.search;
+    this.open_provider = options.open;
+    this.browser_provider = options.browser;
+  }
+
+  /** Agent 释放或卸载 plugin 时关闭全部浏览器资源。 */
+  readonly lifecycle = {
+    stop: async () => {
+      await this.browser_provider?.dispose();
+    },
+  };
+
+  /** 给模型注入最小且与实际 actions 一致的使用说明。 */
+  system(): string {
+    return [
+      "# Web Plugin",
+      "",
+      "Use direct search or document reading before starting a browser session.",
+      "Use browser actions only for dynamic pages, navigation, or interaction.",
+      "Browser actions are deterministic CSS-selector operations; inspect the page before acting.",
+      "Do not perform consequential actions such as submitting, sending, purchasing, uploading, or deleting without host approval.",
+      "Close every browser session created for the task when it is no longer needed.",
+    ].join("\n");
+  }
+
+  /** WebPlugin 结构化 actions。 */
   readonly actions = {
-    [WEB_PLUGIN_ACTIONS.install]: create_action({
-      description:
-        "Return instructions for installing web-related Skills and CLIs. This action does not install anything.",
-      input_schema: {
-        zod: z.object({
-          target: z.enum(["web-access", "agent-browser", "all"]).optional(),
-          scope: z.enum(["user", "project"]).optional(),
-        }),
-        json_schema: {
-          type: "object",
-          properties: {
-            target: {
-              type: "string",
-              enum: ["web-access", "agent-browser", "all"],
-              description: "Web capability to receive installation instructions for.",
-            },
-            scope: {
-              type: "string",
-              enum: ["user", "project"],
-              description: "Installation scope for the agent-browser CLI.",
-            },
-          },
-        },
+    [WEB_PLUGIN_ACTIONS.search]: create_action({
+      description: "Search the web with the configured search provider.",
+      input_schema: z.object({
+        query: z.string().trim().min(1),
+        limit: z.number().int().min(1).max(100).optional(),
+        domains: z.array(z.string().trim().min(1)).max(50).optional(),
+      }),
+      examples: [{ title: "Search official sources", payload: { query: "Playwright CDP documentation", limit: 5 } }],
+      execute: async ({ input }) => {
+        if (!this.search_provider) {
+          return failure_result("WebPlugin search provider is not configured");
+        }
+        try {
+          const result = await this.search_provider(input as WebSearchInput);
+          return { success: true, data: result, message: "web search completed" };
+        } catch (error) {
+          return failure_result(error);
+        }
       },
-      examples: [
-        {
-          title: "Get user-level installation instructions for all web capabilities",
-          payload: { target: "all", scope: "user" },
-        },
-      ],
-      command: {
-        description:
-          "Return web capability installation instructions without executing them.",
-        configure(command) {
-          command
-            .option("--target <target>", "web-access、agent-browser 或 all")
-            .option("--scope <scope>", "agent-browser CLI 安装位置：user 或 project");
-        },
-        map_input({ opts }): JsonObject {
-          return {
-            ...(get_install_target_opt(opts)
-              ? { target: get_install_target_opt(opts) }
-              : {}),
-            ...(get_install_scope_opt(opts)
-              ? { scope: get_install_scope_opt(opts) }
-              : {}),
-          } satisfies JsonObject;
+    }),
+
+    [WEB_PLUGIN_ACTIONS.open]: create_action({
+      description: "Read a known URL with the configured document provider.",
+      input_schema: z.object({ url: URL_SCHEMA, max_chars: MAX_CHARS_SCHEMA }),
+      examples: [{ title: "Read official documentation", payload: { url: "https://playwright.dev/docs/api/class-playwright" } }],
+      execute: async ({ input }) => {
+        if (!this.open_provider) {
+          return failure_result("WebPlugin document provider is not configured");
+        }
+        try {
+          const result = await this.open_provider(input as WebOpenInput);
+          return { success: true, data: result, message: "web document opened" };
+        } catch (error) {
+          return failure_result(error);
+        }
+      },
+    }),
+
+    [WEB_PLUGIN_ACTIONS.browser_create_session]: create_action({
+      description: "Create a browser session with an optional initial URL.",
+      input_schema: z.object({
+        url: URL_SCHEMA.optional(),
+        include_screenshot: z.boolean().optional(),
+      }),
+      examples: [{ title: "Open a page", payload: { url: "https://example.com" } }],
+      execute: async ({ input }) => {
+        if (!this.browser_provider) {
+          return failure_result("WebPlugin browser provider is not configured");
+        }
+        try {
+          const result = await this.browser_provider.create_session(
+            input as BrowserCreateSessionInput,
+          );
+          return { success: true, data: result, message: "browser session created" };
+        } catch (error) {
+          return failure_result(error);
+        }
+      },
+    }),
+
+    [WEB_PLUGIN_ACTIONS.browser_observe]: create_action({
+      description: "Observe the current browser page as text and an optional screenshot.",
+      input_schema: z.object({
+        session_id: SESSION_ID_SCHEMA,
+        include_screenshot: z.boolean().optional(),
+      }),
+      execute: async ({ input }) => {
+        if (!this.browser_provider) {
+          return failure_result("WebPlugin browser provider is not configured");
+        }
+        try {
+          const result = await this.browser_provider.observe(
+            input as BrowserObserveInput,
+          );
+          return { success: true, data: result, message: "browser observed" };
+        } catch (error) {
+          return failure_result(error);
+        }
+      },
+    }),
+
+    [WEB_PLUGIN_ACTIONS.browser_act]: create_action({
+      description: "Execute one deterministic browser action and return the resulting observation.",
+      input_schema: z.object({
+        session_id: SESSION_ID_SCHEMA,
+        action: BROWSER_ACTION_SCHEMA,
+        include_screenshot: z.boolean().optional(),
+      }),
+      examples: [{ title: "Click a link", payload: { session_id: "session-id", action: { type: "click", selector: "a" } } }],
+      execute: async ({ input }) => {
+        if (!this.browser_provider) {
+          return failure_result("WebPlugin browser provider is not configured");
+        }
+        try {
+          const result = await this.browser_provider.act(input as BrowserActInput);
+          return { success: true, data: result, message: "browser action completed" };
+        } catch (error) {
+          return failure_result(error);
+        }
+      },
+    }),
+
+    [WEB_PLUGIN_ACTIONS.browser_semantic_act]: create_action({
+      description: "Execute one natural-language browser action through a semantic provider.",
+      input_schema: z.object({
+        session_id: SESSION_ID_SCHEMA,
+        instruction: z.string().trim().min(1),
+        include_screenshot: z.boolean().optional(),
+      }),
+      examples: [{
+        title: "Use a semantic browser action",
+        payload: {
+          session_id: "session-id",
+          instruction: "Click the sign in button",
         },
+      }],
+      execute: async ({ input }) => {
+        if (!this.browser_provider?.semantic_act) {
+          return failure_result(
+            "WebPlugin semantic browser action provider is not configured",
+          );
+        }
+        try {
+          const result = await this.browser_provider.semantic_act(
+            input as BrowserSemanticActInput,
+          );
+          return { success: true, data: result, message: "semantic browser action completed" };
+        } catch (error) {
+          return failure_result(error);
+        }
       },
-      execute({ input }): PluginActionResult<JsonObject> {
-        const result = render_web_install_prompt(
-          input as WebPluginInstallPayload | undefined,
-        );
-        return {
-          success: true,
-          data: result,
-          message:
-            "Web capability installation instructions ready; no commands were executed and no files were changed.",
-        };
+    }),
+
+    [WEB_PLUGIN_ACTIONS.browser_extract]: create_action({
+      description: "Extract text from the page body or a CSS selector.",
+      input_schema: z.object({
+        session_id: SESSION_ID_SCHEMA,
+        selector: z.string().trim().min(1).optional(),
+        max_chars: MAX_CHARS_SCHEMA,
+      }),
+      execute: async ({ input }) => {
+        if (!this.browser_provider) {
+          return failure_result("WebPlugin browser provider is not configured");
+        }
+        try {
+          const result = await this.browser_provider.extract(
+            input as BrowserExtractInput,
+          );
+          return { success: true, data: result, message: "browser content extracted" };
+        } catch (error) {
+          return failure_result(error);
+        }
       },
     }),
-  };
 
-  /**
-   * 注入联网方法论提示词。
-   */
-  system(_context: PluginContext): string {
-    return WEB_PLUGIN_PROMPT;
-  }
+    [WEB_PLUGIN_ACTIONS.browser_semantic_extract]: create_action({
+      description: "Extract page content through a semantic provider.",
+      input_schema: z.object({
+        session_id: SESSION_ID_SCHEMA,
+        instruction: z.string().trim().min(1),
+        max_chars: MAX_CHARS_SCHEMA,
+      }),
+      execute: async ({ input }) => {
+        if (!this.browser_provider?.semantic_extract) {
+          return failure_result(
+            "WebPlugin semantic browser extract provider is not configured",
+          );
+        }
+        try {
+          const result = await this.browser_provider.semantic_extract(
+            input as BrowserSemanticExtractInput,
+          );
+          return { success: true, data: result, message: "semantic browser content extracted" };
+        } catch (error) {
+          return failure_result(error);
+        }
+      },
+    }),
+
+    [WEB_PLUGIN_ACTIONS.browser_close_session]: create_action({
+      description: "Close a browser session and release its page resources.",
+      input_schema: z.object({ session_id: SESSION_ID_SCHEMA }),
+      execute: async ({ input }) => {
+        if (!this.browser_provider) {
+          return failure_result("WebPlugin browser provider is not configured");
+        }
+        try {
+          await this.browser_provider.close_session(
+            input as BrowserCloseSessionInput,
+          );
+          return {
+            success: true,
+            data: { session_id: input.session_id, closed: true },
+            message: "browser session closed",
+          };
+        } catch (error) {
+          return failure_result(error);
+        }
+      },
+    }),
+  } as unknown as BasePlugin["actions"];
 }

package/src/web/providers/ComputerUseBrowserProviderAdapter.ts

@@ -0,0 +1,93 @@
+/**
+ * Provider-neutral Computer Use 浏览器 adapter。
+ *
+ * 关键点（中文）
+ * - adapter 不依赖 OpenAI、Anthropic 或 Google SDK。
+ * - 每次语义动作先获取带截图的当前状态，再交给宿主模型循环。
+ * - 模型回调不能直接接触 Playwright 对象，只能返回 JSON observation。
+ */
+
+import type {
+  BrowserActInput,
+  BrowserCloseSessionInput,
+  BrowserCreateSessionInput,
+  BrowserExtractInput,
+  BrowserExtractResult,
+  BrowserObservation,
+  BrowserObserveInput,
+  BrowserProvider,
+  BrowserSemanticActInput,
+} from "@/web/types/WebPlugin.js";
+import type {
+  ComputerUseBrowserProviderAdapterOptions,
+  ComputerUseBrowserProviderMethods,
+} from "@/web/types/ComputerUseBrowserProviderAdapter.js";
+
+/** 为基础浏览器组合 Computer Use 视觉回退。 */
+export class ComputerUseBrowserProviderAdapter
+  implements ComputerUseBrowserProviderMethods
+{
+  /** adapter 稳定名称。 */
+  readonly name: string;
+
+  /** 拥有 session 的基础浏览器 provider。 */
+  private readonly browser: BrowserProvider;
+
+  /** Computer Use 模型回调。 */
+  private readonly run_callback: ComputerUseBrowserProviderAdapterOptions["run"];
+
+  constructor(options: ComputerUseBrowserProviderAdapterOptions) {
+    const name = String(options.name || "").trim();
+    if (!name) throw new TypeError("ComputerUseBrowserProviderAdapter requires name");
+    this.name = name;
+    this.browser = options.browser;
+    this.run_callback = options.run;
+  }
+
+  /** 委托创建浏览器 session。 */
+  async create_session(
+    input: BrowserCreateSessionInput,
+  ): Promise<BrowserObservation> {
+    return await this.browser.create_session(input);
+  }
+
+  /** 委托观察页面。 */
+  async observe(input: BrowserObserveInput): Promise<BrowserObservation> {
+    return await this.browser.observe(input);
+  }
+
+  /** 委托确定性动作。 */
+  async act(input: BrowserActInput): Promise<BrowserObservation> {
+    return await this.browser.act(input);
+  }
+
+  /** 获取截图并运行一次 Computer Use 模型循环。 */
+  async semantic_act(
+    input: BrowserSemanticActInput,
+  ): Promise<BrowserObservation> {
+    const observation = await this.browser.observe({
+      session_id: input.session_id,
+      include_screenshot: true,
+    });
+    return await this.run_callback({
+      instruction: input.instruction,
+      session_id: input.session_id,
+      observation,
+    });
+  }
+
+  /** 委托页面文本抽取。 */
+  async extract(input: BrowserExtractInput): Promise<BrowserExtractResult> {
+    return await this.browser.extract(input);
+  }
+
+  /** Computer Use adapter 不提供结构化语义抽取。 */
+  async close_session(input: BrowserCloseSessionInput): Promise<void> {
+    await this.browser.close_session(input);
+  }
+
+  /** 释放基础浏览器资源。 */
+  async dispose(): Promise<void> {
+    await this.browser.dispose();
+  }
+}