@downcity/plugins 1.0.56 → 1.0.59

package/src/web/runtime/Install.ts

@@ -0,0 +1,241 @@
+/**
+ * WebPlugin 安装器。
+ *
+ * 关键点（中文）
+ * - install 只负责准备联网相关 skill / CLI 依赖，不写 provider 配置。
+ * - skill 安装复用 SkillPlugin 的 `npx skills` 通道，避免 web 自建 registry。
+ * - agent-browser 额外准备 npm CLI 包，因为其 skill 需要 `agent-browser` 命令可用。
+ */
+
+import { execa } from "execa";
+import fs from "node:fs";
+import path from "node:path";
+import type {
+  JsonObject,
+  JsonValue,
+} from "@downcity/agent/internal/types/common/Json.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import { skillInstallCommand } from "@/skill/Command.js";
+import type {
+  WebPluginInstallPayload,
+  WebPluginInstallScope,
+  WebPluginInstallTarget,
+} from "@/web/types/WebPlugin.js";
+
+/**
+ * 单个安装步骤结果。
+ */
+interface WebPluginInstallStep {
+  /**
+   * 步骤名称。
+   */
+  name: string;
+  /**
+   * 步骤是否成功。
+   */
+  success: boolean;
+  /**
+   * 人类可读说明。
+   */
+  message: string;
+}
+
+/**
+ * 读取字符串字段。
+ */
+function read_string(value: JsonValue | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+/**
+ * 读取布尔字段。
+ */
+function read_boolean(value: JsonValue | undefined): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+/**
+ * 归一化安装目标。
+ */
+function resolve_install_target(value: JsonValue | undefined): WebPluginInstallTarget {
+  const target = read_string(value);
+  if (target === "web-access" || target === "agent-browser" || target === "all") {
+    return target;
+  }
+  return "web-access";
+}
+
+/**
+ * 归一化安装作用域。
+ */
+function resolve_install_scope(value: JsonValue | undefined): WebPluginInstallScope {
+  const scope = read_string(value);
+  return scope === "project" ? "project" : "user";
+}
+
+/**
+ * 判断命令是否已经可用。
+ */
+async function command_exists(command: string): Promise<boolean> {
+  try {
+    const result = await execa(command, ["--help"], {
+      reject: false,
+      timeout: 15_000,
+    });
+    return (result.exitCode ?? 1) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 执行 npm 包安装。
+ */
+async function install_npm_package(params: {
+  root_path: string;
+  package_name: string;
+  scope: WebPluginInstallScope;
+}): Promise<void> {
+  if (params.scope === "project") {
+    const package_manager = resolve_project_package_manager(params.root_path);
+    const args =
+      package_manager === "pnpm"
+        ? ["add", "-D", params.package_name]
+        : package_manager === "yarn"
+          ? ["add", "-D", params.package_name]
+          : ["install", "--save-dev", params.package_name];
+    await execa(package_manager, args, {
+      cwd: params.root_path,
+      stdio: "inherit",
+    });
+    return;
+  }
+
+  await execa("npm", ["install", "-g", params.package_name], {
+    stdio: "inherit",
+  });
+}
+
+/**
+ * 根据锁文件推断项目包管理器。
+ */
+function resolve_project_package_manager(root_path: string): "pnpm" | "yarn" | "npm" {
+  if (fs.existsSync(path.join(root_path, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(root_path, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+/**
+ * 将步骤列表转成 JSON。
+ */
+function serialize_steps(steps: WebPluginInstallStep[]): JsonValue[] {
+  return steps.map((step) => ({
+    name: step.name,
+    success: step.success,
+    message: step.message,
+  }));
+}
+
+/**
+ * 安装 skill。
+ */
+async function install_skill(params: {
+  spec: string;
+  scope: WebPluginInstallScope;
+  yes: boolean;
+  agent?: string;
+  steps: WebPluginInstallStep[];
+}): Promise<void> {
+  await skillInstallCommand(params.spec, {
+    global: params.scope === "user",
+    yes: params.yes,
+    agent: params.agent,
+  });
+  params.steps.push({
+    name: `${params.spec}:skill`,
+    success: true,
+    message:
+      params.scope === "user"
+        ? `Installed ${params.spec} skill in user scope.`
+        : `Installed ${params.spec} skill in project scope.`,
+  });
+}
+
+/**
+ * 准备 agent-browser CLI。
+ */
+async function install_agent_browser_cli(params: {
+  context: AgentContext;
+  scope: WebPluginInstallScope;
+  steps: WebPluginInstallStep[];
+}): Promise<void> {
+  if (await command_exists("agent-browser")) {
+    params.steps.push({
+      name: "agent-browser:cli",
+      success: true,
+      message: "agent-browser CLI is already available.",
+    });
+    return;
+  }
+
+  await install_npm_package({
+    root_path: params.context.rootPath,
+    package_name: "agent-browser",
+    scope: params.scope,
+  });
+
+  params.steps.push({
+    name: "agent-browser:cli",
+    success: true,
+    message:
+      params.scope === "user"
+        ? "Installed agent-browser CLI globally with npm."
+        : "Installed agent-browser as a project devDependency.",
+  });
+}
+
+/**
+ * 执行 WebPlugin install action。
+ */
+export async function installWebPluginTargets(params: {
+  context: AgentContext;
+  payload?: WebPluginInstallPayload | null;
+}): Promise<JsonObject> {
+  const payload = params.payload || {};
+  const target = resolve_install_target(payload.target);
+  const scope = resolve_install_scope(payload.scope);
+  const yes = read_boolean(payload.yes) ?? true;
+  const agent = read_string(payload.agent);
+  const targets =
+    target === "all" ? (["web-access", "agent-browser"] as const) : ([target] as const);
+  const steps: WebPluginInstallStep[] = [];
+
+  for (const item of targets) {
+    await install_skill({
+      spec: item,
+      scope,
+      yes,
+      agent,
+      steps,
+    });
+
+    if (item === "agent-browser") {
+      await install_agent_browser_cli({
+        context: params.context,
+        scope,
+        steps,
+      });
+    }
+  }
+
+  return {
+    target,
+    scope,
+    ...(agent ? { agent } : {}),
+    steps: serialize_steps(steps),
+    nextAction:
+      "Use SkillPlugin lookup/list to inspect installed skills, then let the agent choose the concrete web path during task execution.",
+  };
+}

package/src/web/types/WebPlugin.ts

@@ -1,141 +1,65 @@
 /**
- * Web Plugin 协议类型。
+ * WebPlugin 协议类型。
  *
  * 关键点（中文）
- * - `web` plugin 只负责选择 provider、管理少量配置，并注入对应项目的提示词。
- * - 联网能力本身由外部实现承担：`web-access` 或 `agent-browser`。
+ * - web plugin 只注入联网方法论，不维护 provider 运行态。
+ * - install action 仅用于准备联网相关 skill 与工具依赖。
+ * - target 表示要准备的联网能力，不表示 agent 运行时默认选择。
  */
 
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 
 /**
- * Web plugin 默认依赖仓库地址。
+ * WebPlugin 可安装目标。
  */
-export const WEB_PLUGIN_DEFAULT_REPOSITORY_URL =
-  "https://github.com/eze-is/web-access";
+export type WebPluginInstallTarget = "web-access" | "agent-browser" | "all";
 
 /**
- * Web plugin provider。
- */
-export type WebPluginProvider = "web-access" | "agent-browser";
-
-/**
- * Web plugin 安装作用域。
+ * WebPlugin 安装作用域。
  */
 export type WebPluginInstallScope = "user" | "project";
 
 /**
- * Web plugin 配置。
+ * WebPlugin install action 输入。
  */
-export interface WebPluginConfig {
-  /**
-   * 兼容统一结构化配置约束的索引签名。
-   */
-  [key: string]: JsonValue | undefined;
-  /**
-   * 当前使用的 provider。
-   */
-  provider?: WebPluginProvider;
-  /**
-   * 是否向 agent 注入 provider 提示词。
-   */
-  injectPrompt?: boolean;
+export interface WebPluginInstallPayload {
   /**
-   * provider 来源仓库地址。
+   * 要准备的联网能力。
+   *
+   * 说明（中文）
+   * - `web-access`：安装 web-access skill。
+   * - `agent-browser`：安装 agent-browser skill，并准备 agent-browser CLI 包。
+   * - `all`：同时准备以上能力。
+   * - 默认值为 `web-access`，避免默认安装额外 CLI。
    */
-  repositoryUrl?: string;
+  target?: WebPluginInstallTarget;
   /**
-   * provider 版本标签或备注。
+   * 安装作用域。
+   *
+   * 说明（中文）
+   * - `user`：安装到用户级 skill / npm 全局环境。
+   * - `project`：安装到当前项目级 skill / devDependency。
+   * - 默认值为 `user`，避免默认修改项目依赖。
    */
-  sourceVersion?: string;
+  scope?: WebPluginInstallScope;
   /**
-   * agent-browser 命令名（可选）。
+   * 是否跳过安装确认。
+   *
+   * 说明（中文）
+   * - 会透传给底层 skill installer。
+   * - 默认值为 `true`，适合 agent 自动执行。
    */
-  browserCommand?: string;
+  yes?: boolean;
   /**
-   * skill 安装作用域。
+   * skill installer 的目标 agent 名称。
+   *
+   * 说明（中文）
+   * - 留空时不向底层 skill installer 传递 `--agent`。
+   * - 只有需要显式指定 installer 目标时才传入。
    */
-  installScope?: WebPluginInstallScope;
-}
-
-/**
- * 归一化后的 web plugin 配置。
- */
-export interface ResolvedWebPluginConfig {
+  agent?: string;
   /**
-   * 当前 provider。
+   * 允许保留额外 JSON 字段，便于未来扩展安装器参数。
    */
-  provider: WebPluginProvider;
-  /**
-   * 是否注入 prompt。
-   */
-  injectPrompt: boolean;
-  /**
-   * 仓库地址。
-   */
-  repositoryUrl: string;
-  /**
-   * provider 版本标签（可选）。
-   */
-  sourceVersion?: string;
-  /**
-   * 浏览器命令。
-   */
-  browserCommand: string;
-  /**
-   * skill 安装作用域。
-   */
-  installScope: WebPluginInstallScope;
-}
-
-/**
- * web plugin setup/install 输入。
- */
-export interface WebPluginInstallInput {
-  /**
-   * provider。
-   */
-  provider?: WebPluginProvider;
-  /**
-   * 是否注入 prompt。
-   */
-  injectPrompt?: boolean;
-  /**
-   * 来源仓库地址。
-   */
-  repositoryUrl?: string;
-  /**
-   * 版本标签。
-   */
-  sourceVersion?: string;
-  /**
-   * 浏览器命令（可选）。
-   */
-  browserCommand?: string;
-  /**
-   * 安装作用域（可选）。
-   */
-  installScope?: WebPluginInstallScope;
-}
-
-/**
- * web plugin 依赖检查结果。
- */
-export interface WebPluginDependencyCheckResult {
-  /**
-   * 当前 provider 是否可用。
-   */
-  available: boolean;
-  /**
-   * 当前 provider 是否已就绪。
-   */
-  installed: boolean;
-  /**
-   * 不可用原因列表。
-   */
-  reasons: string[];
-  /**
-   * 结构化详情（可选）。
-   */
-  details?: JsonValue;
+  [key: string]: JsonValue | undefined;
 }

package/src/workboard/Plugin.ts

@@ -2,105 +2,33 @@
  * Workboard Plugin。
  *
  * 关键点（中文）
- * - workboard 是一个 runtime 观测面板插件，负责提供结构化工作快照。
- * - 当前同时通过 plugin action 与 HTTP 注入提供快照，供 Town RPC 与 Town HTTP gateway 复用。
+ * - workboard 是 runtime 观测面板插件，负责提供结构化工作快照。
+ * - plugin action 与 HTTP route 共享同一份快照读取逻辑。
+ * - 是否启用由是否注册该 plugin 决定，不再读取项目配置做二次开关。
  */
 
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
-import type { Plugin } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type {
+  PluginActions,
+  PluginHttpDefinition,
+} from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
-import { isPluginEnabled } from "@downcity/agent/internal/plugin/core/Activation.js";
 import { getWorkboardSnapshotStore } from "@/workboard/runtime/Store.js";
 import type { WorkboardSnapshotResponse } from "@/workboard/types/Workboard.js";
 
-function createWorkboardPluginDefinition(plugin: Plugin): Plugin {
+/**
+ * 读取 workboard 快照。
+ */
+async function readWorkboardSnapshot(
+  context: AgentContext,
+): Promise<WorkboardSnapshotResponse> {
+  const snapshot = await getWorkboardSnapshotStore({
+    contextResolver: () => context,
+  }).readSnapshot();
   return {
-    name: "workboard",
-    title: "Workboard Snapshot",
-    description:
-      "Collects structured runtime activity snapshots so console surfaces can show what the current agent is doing now and what it recently worked on.",
-    availability(context) {
-      if (!isPluginEnabled({ plugin, context })) {
-        return {
-          enabled: false,
-          available: false,
-          reasons: ["workboard plugin disabled in project config"],
-        };
-      }
-      return {
-        enabled: true,
-        available: true,
-        reasons: [],
-      };
-    },
-    actions: {
-      snapshot: {
-        execute: async ({ context }) => {
-          const availability = await plugin.availability?.(context);
-          if (availability && availability.available !== true) {
-            return {
-              success: false,
-              error: availability.reasons.join("; ") || "workboard unavailable",
-            };
-          }
-
-          const snapshot = await getWorkboardSnapshotStore({
-            contextResolver: () => context,
-          }).readSnapshot();
-          return {
-            success: true,
-            data: {
-              snapshot,
-            } as unknown as JsonValue,
-          };
-        },
-      },
-    },
-    http: {
-      server: {
-        authPolicies: [
-          {
-            path: "/api/workboard/*",
-            method: "GET",
-            requireAuth: true,
-            anyPermissions: ["agent.read"],
-          },
-        ],
-        register({ app, getContext }) {
-          app.get("/api/workboard/snapshot", async (c) => {
-            try {
-              const availability = await plugin.availability?.(getContext());
-              if (availability && availability.available !== true) {
-                return c.json(
-                  {
-                    success: false,
-                    error: availability.reasons.join("; ") || "workboard unavailable",
-                  },
-                  503,
-                );
-              }
-
-              const snapshot = await getWorkboardSnapshotStore({
-                contextResolver: getContext,
-              }).readSnapshot();
-              const payload: WorkboardSnapshotResponse = {
-                success: true,
-                snapshot,
-              };
-              return c.json(payload);
-            } catch (error) {
-              return c.json(
-                {
-                  success: false,
-                  error: error instanceof Error ? error.message : String(error),
-                },
-                500,
-              );
-            }
-          });
-        },
-      },
-    },
+    success: true,
+    snapshot,
   };
 }
 
@@ -108,10 +36,67 @@ function createWorkboardPluginDefinition(plugin: Plugin): Plugin {
  * WorkboardPlugin：运行态观测面板插件。
  */
 export class WorkboardPlugin extends BasePlugin {
+  /**
+   * 当前 plugin 稳定名称。
+   */
   readonly name = "workboard";
 
-  constructor() {
-    super();
-    Object.assign(this, createWorkboardPluginDefinition(this));
-  }
+  /**
+   * 插件标题。
+   */
+  readonly title = "Workboard Snapshot";
+
+  /**
+   * 插件说明。
+   */
+  readonly description =
+    "Collects structured runtime activity snapshots so console surfaces can show what the current agent is doing now and what it recently worked on.";
+
+  /**
+   * Workboard 对外 action。
+   */
+  readonly actions: PluginActions = {
+    snapshot: {
+      execute: async ({ context }) => {
+        const response = await readWorkboardSnapshot(context);
+        return {
+          success: true,
+          data: {
+            snapshot: response.snapshot,
+          } as unknown as JsonValue,
+        };
+      },
+    },
+  };
+
+  /**
+   * Workboard HTTP route。
+   */
+  readonly http: PluginHttpDefinition = {
+    server: {
+      authPolicies: [
+        {
+          path: "/api/workboard/*",
+          method: "GET",
+          requireAuth: true,
+          anyPermissions: ["agent.read"],
+        },
+      ],
+      register({ app, getContext }) {
+        app.get("/api/workboard/snapshot", async (c) => {
+          try {
+            return c.json(await readWorkboardSnapshot(getContext()));
+          } catch (error) {
+            return c.json(
+              {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+              },
+              500,
+            );
+          }
+        });
+      },
+    },
+  };
 }

package/bin/asr/Config.d.ts

@@ -1,43 +0,0 @@
-/**
- * ASR plugin 配置读写工具。
- *
- * 关键点（中文）
- * - 行为配置与转写依赖配置统一收敛到 `plugins.asr`。
- * - 写入前将输入规范化为 JSON object，避免 undefined 进入项目配置。
- */
-import type { VoicePluginConfig } from "../voice/types/VoicePlugin.js";
-import type { AgentPluginConfigRuntime } from "@downcity/agent/internal/types/agent/AgentRuntimeAssembly.js";
-import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
-/**
- * 将普通对象转为可持久化 JSON object。
- */
-export declare function toJsonObject(input: Record<string, unknown> | null | undefined): JsonObject | null;
-/**
- * 读取字符串选项。
- */
-export declare function getStringOpt(opts: Record<string, JsonValue>, key: string): string | undefined;
-/**
- * 读取布尔选项。
- */
-export declare function getBooleanOpt(opts: Record<string, JsonValue>, key: string, defaultValue: boolean): boolean;
-/**
- * 读取 ASR Plugin 配置。
- */
-export declare function readVoicePluginConfig(runtime: {
-    config: {
-        plugins?: Record<string, unknown>;
-    };
-}): VoicePluginConfig;
-/**
- * 写入完整 ASR plugin 配置。
- */
-export declare function writeVoicePluginConfig(params: {
-    agentState: {
-        config: {
-            plugins?: Record<string, unknown>;
-        };
-        pluginConfig: AgentPluginConfigRuntime;
-    };
-    value: VoicePluginConfig;
-}): Promise<void>;
-//# sourceMappingURL=Config.d.ts.map

package/bin/asr/Config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/asr/Config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8DAA8D,CAAC;AAC7G,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE3F;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAChD,UAAU,GAAG,IAAI,CAyBnB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAKpB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,OAAO,GACpB,OAAO,CAST;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,MAAM,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,CAAC;CACH,GAAG,iBAAiB,CA8BpB;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE;QACV,MAAM,EAAE;YACN,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACnC,CAAC;QACF,YAAY,EAAE,wBAAwB,CAAC;KACxC,CAAC;IACF,KAAK,EAAE,iBAAiB,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB"}