@downcity/plugins 1.0.246 → 1.0.252

package/scripts/web-plugin.test.mjs

@@ -1,85 +1,223 @@
 /**
- * WebPlugin 纯提示 install action 回归测试。
+ * WebPlugin provider-neutral action 回归测试。
  *
  * 关键点（中文）
- * - install action 只返回 Agent 操作提示，不能执行命令或写入文件。
- * - Skill 安装必须委托给 skill.install，避免 WebPlugin 重复维护扫描根规则。
- * - agent-browser CLI 提示需要根据 user / project 作用域生成。
+ * - Plugin 必须显式注入 provider，不能只注册一段方法论。
+ * - 浏览器 action 保持结构化输入输出，并在 lifecycle.stop 时释放 provider。
+ * - 缺少某项 provider 时只让对应 action 返回明确失败。
  */
 
 import assert from "node:assert/strict";
-import fs from "node:fs";
-import path from "node:path";
 import test from "node:test";
-import { WebPlugin } from "../bin/index.js";
+import {
+  ComputerUseBrowserProviderAdapter,
+  SemanticBrowserProviderAdapter,
+  WebPlugin,
+} from "../bin/index.js";
 
-test("WebPlugin 仅暴露纯提示 install action", () => {
-  const plugin = new WebPlugin();
+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;
+    },
+  };
+}
 
-  assert.deepEqual(Object.keys(plugin.actions), ["install"]);
-  assert.equal(plugin.setup, undefined);
-  assert.match(plugin.actions.install.description, /does not install anything/);
+test("WebPlugin 拒绝没有真实能力的空配置", () => {
+  assert.throws(() => new WebPlugin({}), /requires at least one provider/);
 });
 
-test("install action 默认返回 web-access 安装工作流", async () => {
-  const project_root = path.resolve("fixtures/web-install-instructions");
-  const plugin = new WebPlugin();
+test("WebPlugin 暴露结构化联网与浏览器 actions", () => {
+  const plugin = new WebPlugin({ browser: create_browser_provider() });
+  assert.deepEqual(Object.keys(plugin.actions), [
+    "search",
+    "open",
+    "browser_create_session",
+    "browser_observe",
+    "browser_act",
+    "browser_semantic_act",
+    "browser_extract",
+    "browser_semantic_extract",
+    "browser_close_session",
+  ]);
+  assert.equal(plugin.actions.install, undefined);
+  assert.match(plugin.system(), /deterministic CSS-selector operations/);
+});
 
-  assert.equal(fs.existsSync(project_root), false);
+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",
+    }),
+  });
 
-  const result = await plugin.actions.install.execute({
-    context: { workspace_path: project_root },
-    input: {},
+  const search_result = await plugin.actions.search.execute({
+    context: {},
+    input: { query: "official docs" },
+  });
+  const open_result = await plugin.actions.open.execute({
+    context: {},
+    input: { url: "https://example.com" },
   });
 
-  assert.equal(result.success, true);
-  assert.equal(result.data.kind, "instructions");
-  assert.equal(result.data.target, "web-access");
-  assert.equal(result.data.scope, "user");
-  assert.match(result.data.prompt, /plugin: "skill", action: "install"/);
-  assert.match(result.data.prompt, /spec: "web-access"/);
-  assert.match(result.data.prompt, /has not executed commands/);
-  assert.match(result.data.prompt, /action: "list"/);
-  assert.equal(fs.existsSync(project_root), false);
+  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("agent-browser project 提示包含 Skill 与项目 CLI 安装步骤", async () => {
-  const plugin = new WebPlugin();
-  const result = await plugin.actions.install.execute({
-    context: { workspace_path: path.resolve("fixtures/web-agent-browser-instructions") },
-    input: { target: "agent-browser", scope: "project" },
+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;
 
-  assert.equal(result.success, true);
-  assert.equal(result.data.target, "agent-browser");
-  assert.equal(result.data.scope, "project");
-  assert.match(result.data.prompt, /spec: "agent-browser"/);
-  assert.match(result.data.prompt, /pnpm add -D agent-browser/);
-  assert.match(result.data.prompt, /npm install -D agent-browser/);
-  assert.match(result.data.prompt, /yarn add -D agent-browser/);
-  assert.match(result.data.prompt, /skill\.lookup/);
+  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("all 目标返回两个 Skill 和用户级 CLI 提示", async () => {
-  const plugin = new WebPlugin();
-  const result = await plugin.actions.install.execute({
-    context: { workspace_path: path.resolve("fixtures/web-all-instructions") },
-    input: { target: "all", scope: "user" },
+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({
+    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",
+    }),
+  });
+  const plugin = new WebPlugin({ browser });
+  const created = 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.match(result.data.prompt, /spec: "web-access"/);
-  assert.match(result.data.prompt, /spec: "agent-browser"/);
-  assert.match(result.data.prompt, /npm install -g agent-browser/);
-  assert.match(result.data.prompt, /no files were changed|changed files/i);
+  assert.equal(result.data.text, "computer-use:drag the map");
+  assert.match(result.data.screenshot_data_url, /^data:image\/png;base64/);
 });
 
-test("system prompt 明确 install 只返回提示", () => {
-  const plugin = new WebPlugin();
-  const prompt = plugin.system({ workspace_path: process.cwd() });
+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(prompt, /return installation instructions/);
-  assert.match(prompt, /never executes commands/);
-  assert.match(prompt, /skill\.install/);
-  assert.match(prompt, /skill\.list/);
+  await plugin.lifecycle.stop({});
+  assert.equal(browser.disposed, true);
 });

package/src/image/ImagePlugin.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 对 Agent 暴露 `image_create` / `image_result` 两步式任务 action。
  * - City / provider 的图片能力通过 image_create / image_result 任务函数注入。
- * - 成功结果返回本地文件 UI Parts，Plugin Action 直接声明应写入的 Assistant Message。
+ * - 成功结果中的远程图片会写入 Workspace，并同时保留本地引用与在线来源地址。
  */
 
 import fs from "node:fs/promises";
@@ -31,6 +31,7 @@ import type {
   ImagePluginResolvedInput,
   ImagePluginResult,
 } from "@/image/types/ImagePlugin.js";
+import { localize_image_result } from "@/image/runtime/ImageResultStorage.js";
 
 const DEFAULT_IMAGE_PLUGIN_NAME = "image";
 const DEFAULT_IMAGE_PLUGIN_TITLE = "Image";
@@ -386,6 +387,9 @@ function normalize_image_result_payload(
 
 /**
  * 校验 image 函数返回的 UIMessage。
+ *
+ * 本函数只校验 provider / City 返回的 UIMessage 结构；
+ * 远程资源下载由 action 成功分支中的 ImageResultStorage 统一处理。
  */
 function normalize_image_result(result: ImagePluginResult): ImagePluginResult {
   const record = to_record(result);
@@ -396,11 +400,7 @@ function normalize_image_result(result: ImagePluginResult): ImagePluginResult {
     const part_record = to_record(part);
     if (part_record?.type !== "file") continue;
     const url = String(part_record.url || "").trim();
-    if (!url || url.startsWith("data:") || HTTP_URL_RE.test(url)) {
-      throw new TypeError(
-        "ImagePlugin result file parts must be saved locally before returning",
-      );
-    }
+    if (!url) throw new TypeError("ImagePlugin result file parts must include a url");
   }
   return result;
 }
@@ -792,7 +792,7 @@ export class ImagePlugin extends BasePlugin {
           },
         },
       ],
-      execute: async ({ input }: { input: JsonValue }) => {
+      execute: async ({ context, execution_context, input }) => {
         try {
           const normalized_input = normalize_image_result_payload(input);
           const current = await this.read_image_result(normalized_input);
@@ -804,19 +804,32 @@ export class ImagePlugin extends BasePlugin {
               message: current.error ?? current.message ?? "image job failed",
             };
           }
-          const { result, ...job } = current;
+          const localized = current.status === "succeeded" && current.result
+            ? await localize_image_result({
+                context,
+                job_id: current.job_id,
+                result: current.result,
+                abort_signal: execution_context?.abort_signal,
+              })
+            : undefined;
+          const output = localized
+            ? { ...current, result: localized.result }
+            : current;
+          const localization_warning = localized?.errors.length
+            ? `; ${localized.errors.length} image result(s) kept as remote URLs because local storage failed: ${localized.errors.join("; ")}`
+            : "";
           return {
             success: true,
-            data: job as unknown as JsonObject,
+            data: output as unknown as JsonObject,
             message:
               current.status === "succeeded"
-                ? "image generated"
+                ? `image generated${localization_warning}`
                 : `image job ${current.status}`,
-            ...(current.status === "succeeded" && result
+            ...(output.status === "succeeded" && output.result
               ? {
                   messages: [{
                     role: "assistant" as const,
-                    parts: result.parts,
+                    parts: output.result.parts,
                   }],
                 }
               : {}),

package/src/image/runtime/ImageResultStorage.ts

@@ -0,0 +1,198 @@
+/**
+ * ImagePlugin 生成结果本地化。
+ *
+ * 关键点（中文）
+ * - City / provider 返回的远程图片先落到当前 Workspace，再交给 Agent Session。
+ * - File Part 的 `url` 使用稳定的本地相对路径，原始在线地址写入 provider metadata。
+ * - 单张图片下载失败时保留远程地址，并返回可观察错误，不丢弃已经生成成功的结果。
+ */
+
+import path from "node:path";
+import type {
+  ImagePluginResultStorageInput,
+  ImagePluginResultStorageResult,
+} from "@/image/types/ImagePlugin.js";
+
+const HTTP_URL_RE = /^https?:\/\//i;
+const MAX_IMAGE_RESULT_BYTES = 50 * 1024 * 1024;
+
+const MEDIA_TYPE_EXTENSIONS: Record<string, string> = {
+  "image/apng": ".apng",
+  "image/avif": ".avif",
+  "image/gif": ".gif",
+  "image/jpeg": ".jpg",
+  "image/png": ".png",
+  "image/webp": ".webp",
+};
+
+/** 判断未知值是否为普通对象。 */
+function to_record(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+/** 把外部标识压缩为单个安全路径片段。 */
+function to_safe_segment(value: string, fallback: string): string {
+  const normalized = String(value || "")
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 120);
+  return normalized || fallback;
+}
+
+/** 从 URL 中提取安全的文件扩展名。 */
+function extension_from_url(url: string): string {
+  try {
+    const extension = path.extname(new URL(url).pathname).toLowerCase();
+    return /^\.[a-z0-9]{1,10}$/.test(extension) ? extension : "";
+  } catch {
+    return "";
+  }
+}
+
+/** 解析落盘文件扩展名。 */
+function resolve_extension(input: {
+  media_type: string;
+  filename?: string;
+  source_url: string;
+}): string {
+  const known = MEDIA_TYPE_EXTENSIONS[input.media_type.toLowerCase()];
+  if (known) return known;
+  const filename_extension = path.extname(String(input.filename || "")).toLowerCase();
+  if (/^\.[a-z0-9]{1,10}$/.test(filename_extension)) return filename_extension;
+  return extension_from_url(input.source_url) || ".bin";
+}
+
+/** 给 File Part 合并 Downcity 来源元数据。 */
+function with_source_metadata(
+  part: Record<string, unknown>,
+  source_url: string,
+  localization_error?: string,
+): Record<string, unknown> {
+  const provider_metadata = to_record(part.providerMetadata) ?? {};
+  const downcity_metadata = to_record(provider_metadata.downcity) ?? {};
+  return {
+    ...part,
+    providerMetadata: {
+      ...provider_metadata,
+      downcity: {
+        ...downcity_metadata,
+        source_url,
+        ...(localization_error ? { localization_error } : {}),
+      },
+    },
+  };
+}
+
+/** 受大小上限保护地读取远程响应。 */
+async function read_response_bytes(response: Response): Promise<Buffer> {
+  const declared_length = Number(response.headers.get("content-length") || 0);
+  if (declared_length > MAX_IMAGE_RESULT_BYTES) {
+    throw new Error(`image result exceeds ${MAX_IMAGE_RESULT_BYTES} bytes`);
+  }
+  if (!response.body) return Buffer.from(await response.arrayBuffer());
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total_bytes = 0;
+  while (true) {
+    const chunk = await reader.read();
+    if (chunk.done) break;
+    total_bytes += chunk.value.byteLength;
+    if (total_bytes > MAX_IMAGE_RESULT_BYTES) {
+      await reader.cancel();
+      throw new Error(`image result exceeds ${MAX_IMAGE_RESULT_BYTES} bytes`);
+    }
+    chunks.push(chunk.value);
+  }
+  return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total_bytes);
+}
+
+/** 下载一张远程图片并返回 Workspace 相对路径。 */
+async function persist_remote_image(input: {
+  context: ImagePluginResultStorageInput["context"];
+  job_id: string;
+  part: Record<string, unknown>;
+  source_url: string;
+  part_index: number;
+  abort_signal?: AbortSignal;
+}): Promise<string> {
+  const response = await fetch(input.source_url, {
+    signal: input.abort_signal,
+  });
+  if (!response.ok) {
+    throw new Error(`image download failed with HTTP ${response.status}`);
+  }
+
+  const declared_media_type = String(input.part.mediaType || "").trim();
+  const response_media_type = String(response.headers.get("content-type") || "")
+    .split(";", 1)[0]
+    .trim();
+  const media_type = declared_media_type || response_media_type || "application/octet-stream";
+  const extension = resolve_extension({
+    media_type,
+    filename: typeof input.part.filename === "string" ? input.part.filename : undefined,
+    source_url: input.source_url,
+  });
+  const job_segment = to_safe_segment(input.job_id, "job");
+  const filename = `image_${String(input.part_index + 1).padStart(2, "0")}${extension}`;
+  const relative_path = path.posix.join(
+    ".downcity",
+    "image",
+    "results",
+    job_segment,
+    filename,
+  );
+  const absolute_path = input.context.files.resolve_path(...relative_path.split("/"));
+  if (!(await input.context.files.path_exists(absolute_path))) {
+    const bytes = await read_response_bytes(response);
+    await input.context.files.ensure_directory(path.dirname(absolute_path));
+    await input.context.files.write_file_atomically(absolute_path, bytes);
+  } else {
+    await response.body?.cancel();
+  }
+  return relative_path;
+}
+
+/**
+ * 把图片结果中的远程 File Parts 本地化，并保留原始在线地址。
+ */
+export async function localize_image_result(
+  input: ImagePluginResultStorageInput,
+): Promise<ImagePluginResultStorageResult> {
+  const errors: string[] = [];
+  const parts = await Promise.all(input.result.parts.map(async (part, part_index) => {
+    const record = to_record(part);
+    if (record?.type !== "file") return part;
+    const source_url = String(record.url || "").trim();
+    if (!HTTP_URL_RE.test(source_url)) return part;
+
+    try {
+      const local_url = await persist_remote_image({
+        context: input.context,
+        job_id: input.job_id,
+        part: record,
+        source_url,
+        part_index,
+        abort_signal: input.abort_signal,
+      });
+      return {
+        ...with_source_metadata(record, source_url),
+        url: local_url,
+      } as typeof part;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      errors.push(`part ${part_index + 1}: ${message}`);
+      return with_source_metadata(record, source_url, message) as typeof part;
+    }
+  }));
+
+  return {
+    result: {
+      ...input.result,
+      parts,
+    },
+    errors,
+  };
+}

package/src/image/types/ImagePlugin.ts

@@ -141,6 +141,30 @@ export interface ImagePluginResolvedInput {
  */
 export type ImagePluginResult = UIMessage;
 
+/**
+ * 图片结果本地存储输入。
+ */
+export interface ImagePluginResultStorageInput {
+  /** 当前 Agent Plugin Context，用于访问 Workspace 文件能力。 */
+  context: PluginContext;
+  /** 当前图片任务 ID，用于划分稳定的本地结果目录。 */
+  job_id: string;
+  /** City 或 provider 返回的原始图片 UIMessage。 */
+  result: ImagePluginResult;
+  /** 当前 Session Turn 的可选取消信号。 */
+  abort_signal?: AbortSignal;
+}
+
+/**
+ * 图片结果本地存储输出。
+ */
+export interface ImagePluginResultStorageResult {
+  /** 已将可下载远程图片替换为本地 Workspace 路径的 UIMessage。 */
+  result: ImagePluginResult;
+  /** 未能完成本地化的图片错误；对应 File Part 会保留远程 URL。 */
+  errors: string[];
+}
+
 /**
  * 图片生成任务状态。
  */