@downcity/plugins 1.0.4

package/src/web/Plugin.ts

@@ -0,0 +1,523 @@
+/**
+ * Web Plugin。
+ *
+ * 关键点（中文）
+ * - `web` plugin 不再自实现联网与浏览器能力，只负责 provider 选择、状态检查与提示词注入。
+ * - 真正的联网逻辑直接交给外部实现：`web-access` 或 `agent-browser`。
+ */
+import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
+import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { WebPluginConfig, WebPluginInstallInput } from "@/web/types/WebPlugin.js";
+import { WEB_PLUGIN_DEFAULT_REPOSITORY_URL } from "@/web/types/WebPlugin.js";
+import { isPluginEnabled } from "@downcity/agent/internal/plugin/core/Activation.js";
+import { writeProjectPluginEnabled } from "@downcity/agent/internal/plugin/core/ProjectConfigStore.js";
+import {
+  doctorWebPluginDependency,
+  inspectWebPluginDependency,
+  installWebPluginDependency,
+  readWebPluginConfig,
+  writeWebPluginConfig,
+} from "@/web/Dependency.js";
+import {
+  AGENT_BROWSER_PROMPT,
+  WEB_ACCESS_PROMPT,
+  WEB_PLUGIN_PROMPT,
+} from "@/web/WebPromptAssets.js";
+
+function toJsonObject(input: Record<string, unknown> | null | undefined): JsonObject {
+  const out: JsonObject = {};
+  if (!input) return out;
+  for (const [key, value] of Object.entries(input)) {
+    if (
+      value === null ||
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function getStringOpt(
+  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;
+}
+
+function getBooleanOpt(
+  opts: Record<string, JsonValue>,
+  key: string,
+  defaultValue: boolean,
+): boolean {
+  const value = opts[key];
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "y", "on"].includes(normalized)) return true;
+    if (["0", "false", "no", "n", "off"].includes(normalized)) return false;
+  }
+  return defaultValue;
+}
+
+function getWebProviderOpt(
+  opts: Record<string, JsonValue>,
+  key: string,
+): "web-access" | "agent-browser" | undefined {
+  const value = getStringOpt(opts, key);
+  if (value === "web-access" || value === "agent-browser") return value;
+  return undefined;
+}
+
+function getInstallScopeOpt(
+  opts: Record<string, JsonValue>,
+  key: string,
+): "user" | "project" | undefined {
+  const value = getStringOpt(opts, key);
+  if (value === "user" || value === "project") return value;
+  return undefined;
+}
+
+function createWebPluginDefinition(plugin: Plugin): Plugin {
+  return {
+    name: "web",
+  title: "Web Access",
+  description:
+    "Connects the agent to either web-access or agent-browser, checks provider readiness, and injects the matching guidance into the runtime prompt.",
+  config: {
+    plugin: "web",
+    scope: "project",
+    defaultValue: {
+      provider: "web-access",
+      injectPrompt: true,
+      repositoryUrl: WEB_PLUGIN_DEFAULT_REPOSITORY_URL,
+      sourceVersion: "2.4.1",
+      browserCommand: "agent-browser",
+      installScope: "user",
+    },
+  },
+  setup: {
+    mode: "install-configure",
+    title: "安装联网 Provider",
+    description: "把 provider 安装到统一 skill 目录，并同步当前配置。",
+    fields: [
+      {
+        key: "provider",
+        label: "联网方法",
+        type: "select",
+        required: true,
+        sourceAction: "providers",
+      },
+      {
+        key: "installScope",
+        label: "安装位置",
+        type: "select",
+        required: true,
+        options: [
+          { label: "用户目录", value: "user", hint: "~/.agents/skills" },
+          { label: "项目目录", value: "project", hint: "PROJECT/.agents/skills" },
+        ],
+      },
+      {
+        key: "injectPrompt",
+        label: "注入 provider 提示词",
+        type: "checkbox",
+      },
+    ],
+    primaryAction: "install",
+    statusAction: "status",
+  },
+  usage: {
+    title: "配置联网方式",
+    description: "选择当前 agent 默认使用的联网 provider 与提示词注入策略。",
+    fields: [
+      {
+        key: "provider",
+        label: "当前 Provider",
+        type: "select",
+        required: true,
+        sourceAction: "providers",
+      },
+      {
+        key: "injectPrompt",
+        label: "注入 Provider 提示词",
+        type: "boolean",
+        trueLabel: "开启",
+        falseLabel: "关闭",
+        description: "开启后，agent system prompt 会自动注入当前 provider 的使用约束。",
+      },
+      {
+        key: "browserCommand",
+        label: "Browser 命令",
+        type: "string",
+        placeholder: "agent-browser",
+        description: "仅在 provider 为 agent-browser 时生效。",
+      },
+    ],
+    saveAction: "configure",
+    statusAction: "status",
+  },
+  async availability(context) {
+    if (!isPluginEnabled({ plugin, context })) {
+      return {
+        enabled: false,
+        available: false,
+        reasons: ["web plugin disabled in project config"],
+      };
+    }
+    const dependency = await inspectWebPluginDependency(context);
+    return {
+      enabled: true,
+      available: dependency.available,
+      reasons: dependency.reasons,
+    };
+  },
+  actions: {
+    status: {
+      allowWhenDisabled: true,
+      command: {
+        description: "查看 web plugin 当前状态",
+        mapInput() {
+          return {};
+        },
+      },
+      execute: async ({ context }) => {
+        const config = readWebPluginConfig(context);
+        const availability = await plugin.availability!(context);
+        const source = await inspectWebPluginDependency(context);
+        return {
+          success: true,
+          data: {
+            plugin: toJsonObject(config as unknown as Record<string, unknown>),
+            availability: {
+              enabled: availability.enabled,
+              available: availability.available,
+              reasons: availability.reasons,
+            },
+            provider: source.details || null,
+          },
+        };
+      },
+    },
+    providers: {
+      allowWhenDisabled: true,
+      command: {
+        description: "列出 web plugin 支持的 provider",
+        mapInput() {
+          return {};
+        },
+      },
+      execute: async () => {
+        return {
+          success: true,
+          data: {
+            options: [
+              {
+                value: "web-access",
+                title: "web-access",
+                description: "适合网页搜索、信息查证与策略型联网任务",
+              },
+              {
+                value: "agent-browser",
+                title: "agent-browser",
+                description: "适合动态页面、登录态页面与真实浏览器操作",
+              },
+            ],
+            providers: [
+              {
+                value: "web-access",
+                title: "web-access",
+                description: "适合网页搜索、信息查证与策略型联网任务",
+              },
+              {
+                value: "agent-browser",
+                title: "agent-browser",
+                description: "适合动态页面、登录态页面与真实浏览器操作",
+              },
+            ],
+          },
+        };
+      },
+    },
+    configure: {
+      allowWhenDisabled: true,
+      execute: async ({ context, payload }) => {
+        const payloadObject =
+          payload && typeof payload === "object" && !Array.isArray(payload)
+            ? (payload as Record<string, unknown>)
+            : {};
+        const { enabled: _ignoredEnabled, enable: _ignoredEnable, ...patch } =
+          payloadObject;
+        const nextConfig = await writeWebPluginConfig({
+          context,
+          value: patch as Partial<WebPluginConfig>,
+        });
+        return {
+          success: true,
+          data: {
+            plugin: toJsonObject(nextConfig as unknown as Record<string, unknown>),
+          },
+        };
+      },
+    },
+    install: {
+      allowWhenDisabled: true,
+      command: {
+        description: "安装当前 provider 对应的 skill，并写入配置",
+        configure(command) {
+          command
+            .option("--provider <provider>", "web-access 或 agent-browser")
+            .option("--repo <url>", "记录来源仓库地址")
+            .option("--version <version>", "记录来源版本")
+            .option("--browser-command <command>", "agent-browser 命令名")
+            .option("--scope <scope>", "安装位置：user 或 project")
+            .option("--no-inject-prompt", "关闭 provider 提示词注入");
+        },
+        mapInput({ opts }): JsonValue {
+          return {
+            ...(getWebProviderOpt(opts, "provider")
+              ? { provider: getWebProviderOpt(opts, "provider") }
+              : {}),
+            ...(getStringOpt(opts, "repo")
+              ? { repositoryUrl: getStringOpt(opts, "repo") }
+              : {}),
+            ...(getStringOpt(opts, "version")
+              ? { sourceVersion: getStringOpt(opts, "version") }
+              : {}),
+            ...(getStringOpt(opts, "browserCommand")
+              ? { browserCommand: getStringOpt(opts, "browserCommand") }
+              : {}),
+            ...(getInstallScopeOpt(opts, "scope")
+              ? { installScope: getInstallScopeOpt(opts, "scope") }
+              : {}),
+            injectPrompt: getBooleanOpt(opts, "injectPrompt", true),
+          } as JsonObject;
+        },
+      },
+      execute: async ({ context, payload }) => {
+        const result = await installWebPluginDependency({
+          context,
+          input:
+            payload && typeof payload === "object" && !Array.isArray(payload)
+              ? (payload as WebPluginInstallInput)
+              : undefined,
+        });
+        return {
+          success: result.success,
+          ...(result.details ? { data: result.details } : {}),
+          ...(result.message ? { message: result.message } : {}),
+        };
+      },
+    },
+    on: {
+      allowWhenDisabled: true,
+      command: {
+        description: "启用 web plugin，并可选设置 provider",
+        configure(command) {
+          command
+            .option("--provider <provider>", "web-access 或 agent-browser")
+            .option("--repo <url>", "记录来源仓库地址")
+            .option("--version <version>", "记录来源版本")
+            .option("--browser-command <command>", "agent-browser 命令名")
+            .option("--no-inject-prompt", "关闭 provider 提示词注入");
+        },
+        mapInput({ opts }): JsonValue {
+          return {
+            ...(getWebProviderOpt(opts, "provider")
+              ? { provider: getWebProviderOpt(opts, "provider") }
+              : {}),
+            ...(getStringOpt(opts, "repo")
+              ? { repositoryUrl: getStringOpt(opts, "repo") }
+              : {}),
+            ...(getStringOpt(opts, "version")
+              ? { sourceVersion: getStringOpt(opts, "version") }
+              : {}),
+            ...(getStringOpt(opts, "browserCommand")
+              ? { browserCommand: getStringOpt(opts, "browserCommand") }
+              : {}),
+            injectPrompt: getBooleanOpt(opts, "injectPrompt", true),
+          } as JsonObject;
+        },
+      },
+      execute: async ({ context, payload }) => {
+        await writeProjectPluginEnabled({
+          pluginName: "web",
+          enabled: true,
+          context,
+        });
+        const providerRaw = String((payload as { provider?: unknown }).provider || "").trim();
+        const provider =
+          providerRaw === "web-access" || providerRaw === "agent-browser"
+            ? providerRaw
+            : undefined;
+        const nextConfig = await writeWebPluginConfig({
+          context,
+          value: {
+            ...readWebPluginConfig(context),
+            ...(provider ? { provider } : {}),
+            injectPrompt:
+              typeof (payload as { injectPrompt?: unknown }).injectPrompt === "boolean"
+                ? Boolean((payload as { injectPrompt?: unknown }).injectPrompt)
+                : true,
+            ...(typeof (payload as { repositoryUrl?: unknown }).repositoryUrl === "string"
+              ? { repositoryUrl: String((payload as { repositoryUrl?: unknown }).repositoryUrl) }
+              : {}),
+            ...(typeof (payload as { sourceVersion?: unknown }).sourceVersion === "string"
+              ? { sourceVersion: String((payload as { sourceVersion?: unknown }).sourceVersion) }
+              : {}),
+            ...(typeof (payload as { browserCommand?: unknown }).browserCommand === "string"
+              ? { browserCommand: String((payload as { browserCommand?: unknown }).browserCommand) }
+              : {}),
+          },
+        });
+        return {
+          success: true,
+          data: {
+            plugin: toJsonObject(nextConfig as unknown as Record<string, unknown>),
+          },
+        };
+      },
+    },
+    off: {
+      command: {
+        description: "关闭 web plugin",
+        mapInput() {
+          return {};
+        },
+      },
+      execute: async ({ context }) => {
+        await writeProjectPluginEnabled({
+          pluginName: "web",
+          enabled: false,
+          context,
+        });
+        return {
+          success: true,
+          data: {
+            plugin: toJsonObject(
+              readWebPluginConfig(context) as unknown as Record<string, unknown>,
+            ),
+          },
+        };
+      },
+    },
+    use: {
+      allowWhenDisabled: true,
+      command: {
+        description: "切换 web plugin 当前 provider",
+        configure(command) {
+          command
+            .argument("<provider>")
+            .option("--browser-command <command>", "agent-browser 命令名")
+            .option("--no-inject-prompt", "关闭 provider 提示词注入");
+        },
+        mapInput({ args, opts }): JsonValue {
+          const provider = String(args[0] || "").trim();
+          if (!provider) throw new Error("provider is required");
+          return {
+            provider,
+            ...(getStringOpt(opts, "browserCommand")
+              ? { browserCommand: getStringOpt(opts, "browserCommand") }
+              : {}),
+            injectPrompt: getBooleanOpt(opts, "injectPrompt", true),
+          } as JsonObject;
+        },
+      },
+      execute: async ({ context, payload }) => {
+        const provider = String((payload as { provider?: unknown }).provider || "").trim();
+        if (provider !== "web-access" && provider !== "agent-browser") {
+          return {
+            success: false,
+            error: `Unsupported web provider: ${provider}`,
+            message: `Unsupported web provider: ${provider}`,
+          };
+        }
+        const nextConfig = await writeWebPluginConfig({
+          context,
+          value: {
+            ...readWebPluginConfig(context),
+            provider,
+            injectPrompt:
+              typeof (payload as { injectPrompt?: unknown }).injectPrompt === "boolean"
+                ? Boolean((payload as { injectPrompt?: unknown }).injectPrompt)
+                : true,
+            ...(typeof (payload as { browserCommand?: unknown }).browserCommand === "string"
+              ? { browserCommand: String((payload as { browserCommand?: unknown }).browserCommand) }
+              : {}),
+          },
+        });
+        return {
+          success: true,
+          data: {
+            plugin: toJsonObject(nextConfig as unknown as Record<string, unknown>),
+          },
+        };
+      },
+    },
+    doctor: {
+      allowWhenDisabled: true,
+      command: {
+        description: "检查当前 provider 是否已就绪",
+        mapInput() {
+          return {};
+        },
+      },
+      execute: async ({ context }) => {
+        const availability = await plugin.availability!(context);
+        const dependency = await doctorWebPluginDependency(context);
+        return {
+          success: true,
+          data: {
+            availability: {
+              enabled: availability.enabled,
+              available: availability.available,
+              reasons: availability.reasons,
+            },
+            provider: dependency.details || null,
+          },
+          message: dependency.available
+            ? "web provider is available"
+            : dependency.reasons.join("; ") || "web provider is not available",
+        };
+      },
+    },
+  },
+  system(context) {
+    const config = readWebPluginConfig(context);
+    if (!isPluginEnabled({ plugin, context }) || !config.injectPrompt) {
+      return "";
+    }
+    const providerPrompt =
+      config.provider === "agent-browser" ? AGENT_BROWSER_PROMPT : WEB_ACCESS_PROMPT;
+    return [
+      `Current web provider: ${config.provider}`,
+      config.provider === "agent-browser"
+        ? `Use external CLI command: ${config.browserCommand}`
+        : "Use the installed external web-access skill/project.",
+      "",
+      WEB_PLUGIN_PROMPT,
+      "",
+      providerPrompt,
+    ].join("\n");
+  },
+  };
+}
+
+/**
+ * WebPlugin：provider 选择器与提示词适配层。
+ */
+export class WebPlugin extends BasePlugin {
+  readonly name = "web";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createWebPluginDefinition(this));
+  }
+}

package/src/web/WebPromptAssets.ts

@@ -0,0 +1,26 @@
+/**
+ * WebPromptAssets：web plugin 静态提示词资产。
+ *
+ * 关键点（中文）
+ * - prompt 文本真实来源是 `*.ts.txt` 文本文件。
+ * - `agent-browser` prompt 仍会被安装流程复用为默认 SKILL.md 内容。
+ */
+
+import agentBrowserPromptText from "@/web/PROMPT.agent-browser.js";
+import webPluginPromptText from "@/web/PROMPT.js";
+import webAccessPromptText from "@/web/PROMPT.web-access.js";
+
+/**
+ * web plugin 基础 prompt。
+ */
+export const WEB_PLUGIN_PROMPT = webPluginPromptText.trim();
+
+/**
+ * web-access provider prompt。
+ */
+export const WEB_ACCESS_PROMPT = webAccessPromptText.trim();
+
+/**
+ * agent-browser provider prompt。
+ */
+export const AGENT_BROWSER_PROMPT = agentBrowserPromptText.trim();

package/src/web/runtime/Config.ts

@@ -0,0 +1,105 @@
+/**
+ * Web Plugin 配置读写。
+ *
+ * 关键点（中文）
+ * - `web` 默认启用，不要求用户先在 `downcity.json` 写配置。
+ * - 只有当用户显式改动时，才把 `plugins.web` 持久化到项目配置。
+ */
+
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { PluginCommandContext } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { ResolvedWebPluginConfig, WebPluginConfig } from "@/web/types/WebPlugin.js";
+import { WEB_PLUGIN_DEFAULT_REPOSITORY_URL } from "@/web/types/WebPlugin.js";
+
+function toJsonObject(input: Record<string, unknown> | null | undefined): JsonObject {
+  const out: JsonObject = {};
+  if (!input) return out;
+  for (const [key, value] of Object.entries(input)) {
+    if (
+      value === null ||
+      typeof value === "string" ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      out[key] = value;
+      continue;
+    }
+    if (Array.isArray(value)) {
+      out[key] = value.filter((item) => item !== undefined) as never;
+      continue;
+    }
+    if (value && typeof value === "object") {
+      out[key] = toJsonObject(value as Record<string, unknown>);
+    }
+  }
+  return out;
+}
+
+function readWebPluginRecord(context: PluginCommandContext): Record<string, unknown> {
+  const current = context.config.plugins?.web;
+  if (!current || typeof current !== "object" || Array.isArray(current)) {
+    return {};
+  }
+  return current as Record<string, unknown>;
+}
+
+/**
+ * 读取并归一化 web plugin 配置。
+ */
+export function readWebPluginConfig(
+  context: PluginCommandContext,
+): ResolvedWebPluginConfig {
+  const { enabled: _ignoredEnabled, ...current } = readWebPluginRecord(
+    context,
+  ) as WebPluginConfig & {
+    enabled?: boolean;
+  };
+  return {
+    provider:
+      current.provider === "agent-browser" || current.provider === "web-access"
+        ? current.provider
+        : "web-access",
+    injectPrompt:
+      typeof current.injectPrompt === "boolean" ? current.injectPrompt : true,
+    repositoryUrl:
+      typeof current.repositoryUrl === "string" && current.repositoryUrl.trim()
+        ? current.repositoryUrl.trim()
+        : WEB_PLUGIN_DEFAULT_REPOSITORY_URL,
+    ...(typeof current.sourceVersion === "string" && current.sourceVersion.trim()
+      ? { sourceVersion: current.sourceVersion.trim() }
+      : {}),
+    browserCommand:
+      typeof current.browserCommand === "string" && current.browserCommand.trim()
+        ? current.browserCommand.trim()
+        : "agent-browser",
+    installScope:
+      current.installScope === "project" || current.installScope === "user"
+        ? current.installScope
+        : "user",
+  };
+}
+
+/**
+ * 写入 web plugin 配置。
+ */
+export async function writeWebPluginConfig(params: {
+  context: PluginCommandContext;
+  value: Partial<WebPluginConfig>;
+}): Promise<ResolvedWebPluginConfig> {
+  if (!params.context.config.plugins) {
+    params.context.config.plugins = {};
+  }
+  const current = readWebPluginConfig(params.context);
+  const next: WebPluginConfig & {
+    enabled?: boolean;
+  } = {
+    ...current,
+    ...params.value,
+  };
+  delete next.enabled;
+  params.context.config.plugins.web = toJsonObject(
+    next as unknown as Record<string, unknown>,
+  );
+  await params.context.pluginConfig.persistProjectPlugins(params.context.config.plugins);
+  return readWebPluginConfig(params.context);
+}