@downcity/plugins 1.0.4

package/src/web/runtime/Source.ts

@@ -0,0 +1,257 @@
+/**
+ * Web Plugin 来源信息与兼容安装动作。
+ *
+ * 关键点（中文）
+ * - 这里不自建联网实现，只检查外部 provider 是否就绪，并记录少量配置。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import fsp from "node:fs/promises";
+import { execa } from "execa";
+import fse from "fs-extra";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { PluginCommandContext } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type {
+  WebPluginDependencyCheckResult,
+  WebPluginInstallInput,
+} from "@/web/types/WebPlugin.js";
+import { readWebPluginConfig, writeWebPluginConfig } from "@/web/runtime/Config.js";
+import { AGENT_BROWSER_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 resolveWebAccessSkillCandidates(projectRoot: string): string[] {
+  const home = process.env.HOME || "";
+  return [
+    path.join(projectRoot, ".agents", "skills", "web-access", "SKILL.md"),
+    path.join(home, ".agents", "skills", "web-access", "SKILL.md"),
+    path.join(projectRoot, ".claude", "skills", "web-access", "SKILL.md"),
+    path.join(home, ".claude", "skills", "web-access", "SKILL.md"),
+  ].filter(Boolean);
+}
+
+function resolveManagedSkillRoot(projectRoot: string, scope: "user" | "project"): string {
+  if (scope === "project") {
+    return path.join(projectRoot, ".agents", "skills");
+  }
+  return path.join(process.env.HOME || os.homedir(), ".agents", "skills");
+}
+
+function resolveManagedSkillDir(params: {
+  projectRoot: string;
+  scope: "user" | "project";
+  provider: "web-access" | "agent-browser";
+}): string {
+  return path.join(resolveManagedSkillRoot(params.projectRoot, params.scope), params.provider);
+}
+
+function loadBundledAgentBrowserSkillText(): string {
+  return AGENT_BROWSER_PROMPT || "# agent-browser";
+}
+
+async function ensureAgentBrowserSkillInstalled(params: {
+  projectRoot: string;
+  scope: "user" | "project";
+}): Promise<string> {
+  const targetDir = resolveManagedSkillDir({
+    projectRoot: params.projectRoot,
+    scope: params.scope,
+    provider: "agent-browser",
+  });
+  const skillPath = path.join(targetDir, "SKILL.md");
+  if (fs.existsSync(skillPath)) {
+    return skillPath;
+  }
+  await fsp.mkdir(targetDir, { recursive: true });
+  await fsp.writeFile(`${skillPath}`, `${loadBundledAgentBrowserSkillText()}\n`, "utf-8");
+  return skillPath;
+}
+
+async function ensureWebAccessSkillInstalled(params: {
+  projectRoot: string;
+  scope: "user" | "project";
+  source?: string;
+}): Promise<string> {
+  const targetDir = resolveManagedSkillDir({
+    projectRoot: params.projectRoot,
+    scope: params.scope,
+    provider: "web-access",
+  });
+  const skillPath = path.join(targetDir, "SKILL.md");
+  if (fs.existsSync(skillPath)) {
+    return skillPath;
+  }
+
+  const source = String(params.source || "").trim();
+  if (source && fs.existsSync(source)) {
+    await fse.copy(path.resolve(source), targetDir, {
+      overwrite: true,
+      errorOnExist: false,
+    });
+    return skillPath;
+  }
+
+  await fsp.mkdir(path.dirname(targetDir), { recursive: true });
+  await execa("git", ["clone", "--depth=1", "https://github.com/eze-is/web-access", targetDir], {
+    reject: true,
+  });
+  return skillPath;
+}
+
+async function checkAgentBrowserCommand(command: string): Promise<boolean> {
+  try {
+    await execa(command, ["--help"], {
+      reject: false,
+      timeout: 15_000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 返回当前来源快照。
+ */
+export async function inspectWebPluginDependency(
+  context: PluginCommandContext,
+): Promise<WebPluginDependencyCheckResult> {
+  const config = readWebPluginConfig(context);
+  if (config.provider === "agent-browser") {
+    const available = await checkAgentBrowserCommand(config.browserCommand);
+    return {
+      available,
+      installed: available,
+      reasons: available
+        ? []
+        : [
+            `agent-browser command is not available: ${config.browserCommand}`,
+            "Install or expose the agent-browser CLI before using this provider.",
+          ],
+      details: {
+        provider: config.provider,
+        browserCommand: config.browserCommand,
+        source: "external-project",
+        installScope: config.installScope,
+      },
+    };
+  }
+
+  const candidates = resolveWebAccessSkillCandidates(context.rootPath);
+  const skillPath = candidates.find((item) => fs.existsSync(item));
+  const available = Boolean(skillPath);
+  return {
+    available,
+    installed: available,
+    reasons: available
+      ? []
+      : [
+          "web-access skill is not found.",
+          "Install https://github.com/eze-is/web-access into ~/.agents/skills/web-access or project .agents/skills/web-access.",
+        ],
+    details: {
+      provider: config.provider,
+      source: "external-project",
+      repositoryUrl: config.repositoryUrl,
+      installScope: config.installScope,
+      ...(config.sourceVersion ? { sourceVersion: config.sourceVersion } : {}),
+      ...(skillPath ? { skillPath } : { checkedPaths: candidates }),
+    },
+  };
+}
+
+/**
+ * 兼容 install 动作。
+ */
+export async function installWebPluginDependency(params: {
+  context: PluginCommandContext;
+  input?: WebPluginInstallInput;
+}): Promise<{
+  success: boolean;
+  message?: string;
+  details?: JsonObject;
+}> {
+  const currentConfig = readWebPluginConfig(params.context);
+  const installScope =
+    params.input?.installScope === "project" || params.input?.installScope === "user"
+      ? params.input.installScope
+      : currentConfig.installScope;
+  const provider =
+    params.input?.provider === "agent-browser" || params.input?.provider === "web-access"
+      ? params.input.provider
+      : currentConfig.provider;
+
+  const installedSkillPath =
+    provider === "agent-browser"
+      ? await ensureAgentBrowserSkillInstalled({
+          projectRoot: params.context.rootPath,
+          scope: installScope,
+        })
+      : await ensureWebAccessSkillInstalled({
+          projectRoot: params.context.rootPath,
+          scope: installScope,
+          source: params.input?.repositoryUrl,
+        });
+
+  const nextConfig = await writeWebPluginConfig({
+    context: params.context,
+    value: {
+      provider,
+      injectPrompt:
+        typeof params.input?.injectPrompt === "boolean"
+          ? params.input.injectPrompt
+          : true,
+      ...(typeof params.input?.repositoryUrl === "string" &&
+      params.input.repositoryUrl.trim()
+        ? { repositoryUrl: params.input.repositoryUrl.trim() }
+        : {}),
+      ...(typeof params.input?.sourceVersion === "string" &&
+      params.input.sourceVersion.trim()
+        ? { sourceVersion: params.input.sourceVersion.trim() }
+        : {}),
+      ...(typeof params.input?.browserCommand === "string" &&
+      params.input.browserCommand.trim()
+        ? { browserCommand: params.input.browserCommand.trim() }
+        : {}),
+      installScope,
+    },
+  });
+  return {
+    success: true,
+    message: "web provider installed and configured",
+    details: toJsonObject({
+      provider: nextConfig.provider,
+      injectPrompt: nextConfig.injectPrompt,
+      repositoryUrl: nextConfig.repositoryUrl,
+      sourceVersion: nextConfig.sourceVersion || "",
+      browserCommand: nextConfig.browserCommand,
+      installScope: nextConfig.installScope,
+      skillPath: installedSkillPath,
+    }),
+  };
+}
+
+/**
+ * doctor 结果与 inspect 一致。
+ */
+export async function doctorWebPluginDependency(
+  context: PluginCommandContext,
+): Promise<WebPluginDependencyCheckResult> {
+  return inspectWebPluginDependency(context);
+}

package/src/web/types/WebPlugin.ts

@@ -0,0 +1,141 @@
+/**
+ * Web Plugin 协议类型。
+ *
+ * 关键点（中文）
+ * - `web` plugin 只负责选择 provider、管理少量配置，并注入对应项目的提示词。
+ * - 联网能力本身由外部实现承担：`web-access` 或 `agent-browser`。
+ */
+
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+
+/**
+ * Web plugin 默认依赖仓库地址。
+ */
+export const WEB_PLUGIN_DEFAULT_REPOSITORY_URL =
+  "https://github.com/eze-is/web-access";
+
+/**
+ * Web plugin provider。
+ */
+export type WebPluginProvider = "web-access" | "agent-browser";
+
+/**
+ * Web plugin 安装作用域。
+ */
+export type WebPluginInstallScope = "user" | "project";
+
+/**
+ * Web plugin 配置。
+ */
+export interface WebPluginConfig {
+  /**
+   * 兼容统一结构化配置约束的索引签名。
+   */
+  [key: string]: JsonValue | undefined;
+  /**
+   * 当前使用的 provider。
+   */
+  provider?: WebPluginProvider;
+  /**
+   * 是否向 agent 注入 provider 提示词。
+   */
+  injectPrompt?: boolean;
+  /**
+   * provider 来源仓库地址。
+   */
+  repositoryUrl?: string;
+  /**
+   * provider 版本标签或备注。
+   */
+  sourceVersion?: string;
+  /**
+   * agent-browser 命令名（可选）。
+   */
+  browserCommand?: string;
+  /**
+   * skill 安装作用域。
+   */
+  installScope?: WebPluginInstallScope;
+}
+
+/**
+ * 归一化后的 web plugin 配置。
+ */
+export interface ResolvedWebPluginConfig {
+  /**
+   * 当前 provider。
+   */
+  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;
+}

package/src/workboard/Plugin.ts

@@ -0,0 +1,94 @@
+/**
+ * Workboard Plugin。
+ *
+ * 关键点（中文）
+ * - workboard 是一个 runtime 观测面板插件，负责提供结构化工作快照。
+ * - 当前通过 plugin HTTP 注入暴露 `/api/workboard/snapshot`，供 console 代理与 UI 消费。
+ */
+
+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 { 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 {
+  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: [],
+      };
+    },
+    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,
+              );
+            }
+          });
+        },
+      },
+    },
+  };
+}
+
+/**
+ * WorkboardPlugin：运行态观测面板插件。
+ */
+export class WorkboardPlugin extends BasePlugin {
+  readonly name = "workboard";
+
+  constructor(agent: AgentRuntime | null = null) {
+    super(agent);
+    Object.assign(this, createWorkboardPluginDefinition(this));
+  }
+}

package/src/workboard/runtime/Collector.ts

@@ -0,0 +1,79 @@
+/**
+ * Workboard 快照采集器。
+ *
+ * 关键点（中文）
+ * - 这里只做确定性采集，不引入 LLM 推理。
+ * - 内部仍聚合 session、task、plugin runtime 三类运行事实，但最终只输出对外安全的模糊状态。
+ */
+
+import { listTaskDefinitions } from "@/task/Action.js";
+import { listPluginStates } from "@downcity/agent/internal/plugin/core/Manager.js";
+import { listControlSessionSummaries } from "@downcity/agent/internal/runtime/server/http/control/SessionSummaryStore.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { WorkboardSnapshot } from "@/workboard/types/Workboard.js";
+import {
+  buildIdleActivity,
+  toRecentActivity,
+  toRunningActivity,
+  toWorkboardAgentSummary,
+  toWorkboardSignals,
+  toWorkboardSummary,
+} from "@/workboard/runtime/Normalizer.js";
+
+const WORKBOARD_RECENT_LIMIT = 8;
+
+/**
+ * 采集当前 workboard 快照。
+ */
+export async function collectWorkboardSnapshot(
+  context: AgentContext,
+): Promise<WorkboardSnapshot> {
+  const collectedAt = new Date().toISOString();
+  const executingSessionIds = new Set(context.session.listExecutingSessionIds());
+  const sessions = await listControlSessionSummaries({
+    projectRoot: context.rootPath,
+    agentId: context.paths.agentId,
+    executionContext: context,
+    limit: WORKBOARD_RECENT_LIMIT + Math.max(executingSessionIds.size, 1),
+    executingSessionIds,
+  });
+  const runtimePlugins = listPluginStates({ context });
+  const taskResult = await listTaskDefinitions({ projectRoot: context.rootPath });
+  const degradedCount = runtimePlugins.filter((item) => item.state !== "running").length;
+
+  const current = sessions
+    .filter((item) => item.executing === true)
+    .slice(0, 4)
+    .map((item, index) => toRunningActivity({ item, index }));
+  const recent = sessions
+    .filter((item) => item.executing !== true)
+    .slice(0, WORKBOARD_RECENT_LIMIT)
+    .map((item, index) => toRecentActivity({ item, index }));
+
+  const safeCurrent = current.length > 0
+    ? current
+    : [buildIdleActivity({ updatedAt: collectedAt, recentCount: recent.length })];
+
+  return {
+    agent: toWorkboardAgentSummary({
+      context,
+      collectedAt,
+      currentCount: current.length,
+      recentCount: recent.length,
+      degradedCount,
+    }),
+    summary: toWorkboardSummary({
+      currentCount: current.length,
+      recentCount: recent.length,
+      degradedCount,
+    }),
+    current: safeCurrent,
+    recent,
+    signals: toWorkboardSignals({
+      currentCount: current.length,
+      recentCount: recent.length,
+      plugins: runtimePlugins,
+      taskResult,
+    }),
+  };
+}