@downcity/city 1.1.4 → 1.1.6

package/src/control/ControlGateway.ts

@@ -0,0 +1,463 @@
+/**
+ * 控制面网关。
+ *
+ * 关键点（中文）
+ * - UI 由控制面进程独立托管，不依赖单个 agent 启动参数。
+ * - 提供统一的多 agent 选择能力，并把 `/api/*` 代理到选中 agent。
+ */
+
+import { Hono, type Context } from "hono";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import http from "node:http";
+import fs from "fs-extra";
+import path from "node:path";
+import { fileURLToPath } from "url";
+import { registerPlatformApiRoutes } from "@/control/PlatformApiRoutes.js";
+import {
+  buildPlatformAgentsResponse,
+  buildPlatformConfigStatusResponse,
+  buildPlatformModelResponse,
+  inspectPlatformAgentDirectory,
+  listKnownPlatformAgents,
+  readPlatformConfigFileStatus,
+  readRequestedPlatformAgentId,
+  resolvePlatformAgentById,
+  resolveSelectedPlatformAgent,
+} from "@/control/gateway/AgentCatalog.js";
+import {
+  executeAgentProjectShellCommand,
+  initializePlatformAgentProject,
+  inspectManagedAgentRestartSafety,
+  pickPlatformAgentDirectoryPath,
+  restartManagedAgentByProjectRoot,
+  startManagedAgentByProjectRoot,
+  stopManagedAgentByProjectRoot,
+  updatePlatformAgentExecution,
+} from "@/control/gateway/AgentActions.js";
+import { serveControlPlaneFrontendPath } from "@/control/gateway/FrontendAssets.js";
+import {
+  buildPlatformUpstreamUrl,
+  forwardPlatformRequest,
+} from "@/control/gateway/Proxy.js";
+import type {
+  PlatformAgentOption,
+  PlatformAgentsResponse,
+  PlatformConfigFileStatusItem,
+  PlatformConfigStatusResponse,
+  PlatformAgentDirectoryInspection,
+  PlatformLocalModelsResponse,
+} from "@downcity/agent";
+import type { AgentProjectInitializationResult } from "@downcity/agent";
+import { listBuiltinPluginRuntimeAuthPolicies } from "@downcity/agent";
+import { AuthService } from "@/http/auth/AuthService.js";
+import { registerAuthRoutes } from "@/http/auth/AuthRoutes.js";
+import {
+  CONTROL_PLANE_AUTH_ROUTE_POLICIES,
+  createRouteAuthGuardMiddleware,
+} from "@/http/auth/RoutePolicy.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * 当前 DC 版本号（用于 control plane overview 显示）。
+ */
+const DC_VERSION = (() => {
+  try {
+    const pkg = fs.readJsonSync(path.join(__dirname, "../../package.json")) as {
+      version?: string;
+    };
+    const version = String(pkg?.version || "").trim();
+    return version || "unknown";
+  } catch {
+    return "unknown";
+  }
+})();
+
+/**
+ * 控制面网关启动参数。
+ */
+export interface ControlGatewayStartOptions {
+  /**
+   * UI 监听端口。
+   */
+  port: number;
+
+  /**
+   * UI 监听主机。
+   */
+  host: string;
+}
+
+/**
+ * 控制面网关。
+ */
+export class ControlGateway {
+  private app: Hono;
+  private server: ReturnType<typeof http.createServer> | null = null;
+  private readonly publicDir: string;
+  private readonly authService: AuthService;
+
+  constructor() {
+    // 关键点（中文）：旧的 ui 构建产物路径都统一回退到 packages/downcity/public。
+    this.publicDir = path.join(__dirname, "../../public");
+    this.app = new Hono();
+    this.authService = new AuthService();
+
+    this.app.use("*", logger());
+    this.app.use(
+      "*",
+      cors({
+        origin: "*",
+        allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+        allowHeaders: ["Content-Type", "Authorization", "X-DC-Agent"],
+      }),
+    );
+    this.app.use(
+      "*",
+      createRouteAuthGuardMiddleware(
+        this.authService,
+        [
+          ...CONTROL_PLANE_AUTH_ROUTE_POLICIES,
+          ...listBuiltinPluginRuntimeAuthPolicies(),
+        ],
+      ),
+    );
+
+    this.setupRoutes();
+  }
+
+  /**
+   * 注册网关路由。
+   */
+  private setupRoutes(): void {
+    registerAuthRoutes({
+      app: this.app,
+      authService: this.authService,
+    });
+    registerPlatformApiRoutes({
+      app: this.app,
+      handlers: {
+        readRequestedAgentId: (request) => this.readRequestedAgentId(request),
+        buildAgentsResponse: (requestedAgentId) => this.buildAgentsResponse(requestedAgentId),
+        initializeAgentProject: (projectRoot, initialization) =>
+          this.initializeAgentProject(projectRoot, initialization),
+        startAgentByProjectRoot: (projectRoot, options) => this.startAgentByProjectRoot(projectRoot, options),
+        updateAgentExecution: (projectRoot, input) => this.updateAgentExecution(projectRoot, input),
+        pickDirectoryPath: () => this.pickDirectoryPath(),
+        inspectAgentDirectory: (projectRoot) => this.inspectAgentDirectory(projectRoot),
+        listLocalModels: (projectRoot) => this.listLocalModels(projectRoot),
+        inspectAgentRestartSafety: (projectRoot) => this.inspectAgentRestartSafety(projectRoot),
+        restartAgentByProjectRoot: (projectRoot) => this.restartAgentByProjectRoot(projectRoot),
+        stopAgentByProjectRoot: (projectRoot) => this.stopAgentByProjectRoot(projectRoot),
+        buildConfigStatusResponse: (requestedAgentId) => this.buildConfigStatusResponse(requestedAgentId),
+        resolveAgentById: (requestedAgentId) => this.resolveAgentById(requestedAgentId),
+        executeShellCommand: (args) => this.executeShellCommand(args),
+        buildModelResponse: (requestedAgentId) => this.buildModelResponse(requestedAgentId),
+        resolveSelectedAgent: (requestedAgentId) => this.resolveSelectedAgent(requestedAgentId),
+        buildUpstreamUrl: (requestUrl, baseUrl) => this.buildUpstreamUrl(requestUrl, baseUrl),
+        forwardRequest: (request, upstreamUrl) => this.forwardRequest(request, upstreamUrl),
+        serveFrontendPath: (c, reqPath) => this.serveFrontendPath(c, reqPath),
+      },
+    });
+  }
+
+  private readRequestedAgentId(request: Request): string {
+    return readRequestedPlatformAgentId(request);
+  }
+
+  private async pickDirectoryPath(): Promise<string> {
+    return pickPlatformAgentDirectoryPath();
+  }
+
+  private async listKnownAgents(): Promise<PlatformAgentOption[]> {
+    return listKnownPlatformAgents();
+  }
+
+  private async buildAgentsResponse(
+    requestedAgentId: string,
+  ): Promise<PlatformAgentsResponse> {
+    return buildPlatformAgentsResponse({
+      requestedAgentId,
+      cityVersion: DC_VERSION,
+    });
+  }
+
+  /**
+   * 构建 Global Model 面板响应。
+   *
+   * 关键点（中文）
+   * - 模型池来自控制面全局 SQLite，而不是某个 agent。
+   * - `agentPrimaryModelId` 仅用于展示当前选中 agent 的项目绑定。
+   */
+  private async buildModelResponse(requestedAgentId: string): Promise<{
+    success: boolean;
+    model: {
+      primaryModelId: string;
+      primaryModelName: string;
+      providerKey: string;
+      providerType: string;
+      baseUrl: string;
+      agentPrimaryModelId: string;
+      availableModels: Array<{
+        id: string;
+        name: string;
+        providerKey: string;
+        providerType: string;
+        isPaused: boolean;
+      }>;
+    };
+  }> {
+    return buildPlatformModelResponse({
+      requestedAgentId,
+      cityVersion: DC_VERSION,
+    });
+  }
+
+  /**
+   * 读取单个配置文件状态。
+   *
+   * 关键点（中文）
+   * - 不抛出异常，统一返回 `status/reason` 便于 UI 汇总展示。
+   * - 使用最小探测维度：存在性、文件类型、可读性、大小、修改时间。
+   */
+  private async readConfigFileStatus(params: {
+    key: string;
+    scope: "platform" | "agent";
+    label: string;
+    filePath: string;
+  }): Promise<PlatformConfigFileStatusItem> {
+    return readPlatformConfigFileStatus(params);
+  }
+
+  /**
+   * 构建配置文件状态响应。
+   *
+   * 关键点（中文）
+   * - `platform` 维度始终返回。
+   * - `agent` 维度仅在存在选中 agent 时返回，避免误导。
+   */
+  private async buildConfigStatusResponse(
+    requestedAgentId: string,
+  ): Promise<PlatformConfigStatusResponse> {
+    return buildPlatformConfigStatusResponse({
+      requestedAgentId,
+      cityVersion: DC_VERSION,
+    });
+  }
+
+  private async resolveSelectedAgent(
+    requestedAgentId: string,
+  ): Promise<PlatformAgentOption | null> {
+    return resolveSelectedPlatformAgent(requestedAgentId, DC_VERSION);
+  }
+
+  /**
+   * 根据 id 查找 agent（允许离线 agent，用于 command 页面）。
+   */
+  private async resolveAgentById(
+    requestedAgentId: string,
+  ): Promise<PlatformAgentOption | null> {
+    return resolvePlatformAgentById(requestedAgentId);
+  }
+
+  /**
+   * 探测目录状态，用于“打开文件夹”流程。
+   */
+  private async inspectAgentDirectory(
+    projectRoot: string,
+  ): Promise<PlatformAgentDirectoryInspection> {
+    return inspectPlatformAgentDirectory(projectRoot);
+  }
+
+  /**
+   * 列出可直接用于 local executor 的本地 GGUF 模型。
+   */
+  private async listLocalModels(
+    projectRoot?: string,
+  ): Promise<PlatformLocalModelsResponse> {
+    return { success: true, modelsDir: "~/.models", models: [] };
+  }
+
+  /**
+   * 在 agent 项目目录中执行 shell 命令。
+   *
+   * 关键点（中文）
+   * - 默认 shell 使用 zsh，保持与 CLI 使用习惯一致。
+   * - 输出做大小限制，避免单次命令把 UI 网关进程内存打满。
+   */
+  private async executeShellCommand(params: {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+  }): Promise<{
+    command: string;
+    cwd: string;
+    exitCode: number | null;
+    signal: string;
+    timedOut: boolean;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+  }> {
+    return executeAgentProjectShellCommand(params);
+  }
+
+  private async initializeAgentProject(projectRoot: string, initialization: {
+    agentName?: unknown;
+    modelId?: unknown;
+    forceOverwriteShipJson?: unknown;
+  }): Promise<AgentProjectInitializationResult> {
+    return initializePlatformAgentProject({
+      projectRoot,
+      agentName: initialization.agentName,
+      modelId: initialization.modelId,
+      forceOverwriteShipJson: initialization.forceOverwriteShipJson,
+    });
+  }
+
+  private async startAgentByProjectRoot(projectRoot: string, options?: {
+    initializeIfNeeded?: boolean;
+    initialization?: {
+      agentName?: unknown;
+      modelId?: unknown;
+      forceOverwriteShipJson?: unknown;
+    };
+  }): Promise<{
+    success: boolean;
+    projectRoot: string;
+    started: boolean;
+    pid?: number;
+    logPath?: string;
+    message?: string;
+  }> {
+    return startManagedAgentByProjectRoot({
+      projectRoot,
+      cliPath: path.resolve(__dirname, "../cli/Index.js"),
+      initializeIfNeeded: options?.initializeIfNeeded,
+      initialization: options?.initialization,
+    });
+  }
+
+  private async updateAgentExecution(projectRoot: string, input: {
+    modelId?: unknown;
+  }): Promise<{
+    projectRoot: string;
+    modelId: string;
+  }> {
+    return updatePlatformAgentExecution({
+      projectRoot,
+      modelId: input.modelId,
+    });
+  }
+
+
+  private async inspectAgentRestartSafety(projectRoot: string): Promise<{
+    activeContexts: string[];
+    activeTasks: string[];
+  }> {
+    return inspectManagedAgentRestartSafety({
+      projectRoot,
+      listKnownAgents: () => this.listKnownAgents(),
+    });
+  }
+
+  private async restartAgentByProjectRoot(projectRoot: string): Promise<{
+    success: boolean;
+    projectRoot: string;
+    restarted: boolean;
+    pid?: number;
+    logPath?: string;
+    message?: string;
+  }> {
+    return restartManagedAgentByProjectRoot({
+      projectRoot,
+      cliPath: path.resolve(__dirname, "../cli/Index.js"),
+    });
+  }
+
+  private async stopAgentByProjectRoot(projectRoot: string): Promise<{
+    success: boolean;
+    projectRoot: string;
+    stopped: boolean;
+    pid?: number;
+    message?: string;
+  }> {
+    return stopManagedAgentByProjectRoot(projectRoot);
+  }
+
+  private buildUpstreamUrl(requestUrl: URL, baseUrl: string): string {
+    return buildPlatformUpstreamUrl(requestUrl, baseUrl);
+  }
+
+  private async forwardRequest(
+    request: Request,
+    upstreamUrl: string,
+  ): Promise<Response> {
+    return forwardPlatformRequest(request, upstreamUrl);
+  }
+
+  private async serveFrontendPath(c: Context, reqPath: string): Promise<Response> {
+    return serveControlPlaneFrontendPath({
+      context: c,
+      publicDir: this.publicDir,
+      requestPath: reqPath,
+    });
+  }
+
+  /**
+   * 启动 UI 网关。
+   */
+  async start(options: ControlGatewayStartOptions): Promise<void> {
+    const { port, host } = options;
+    await new Promise<void>((resolve) => {
+      const server = http.createServer(async (req, res) => {
+        try {
+          const url = new URL(req.url || "/", `http://${host}:${port}`);
+          const method = req.method || "GET";
+          const bodyBuffer = await new Promise<Buffer>((onDone, onError) => {
+            const chunks: Buffer[] = [];
+            req.on("data", (chunk) => chunks.push(chunk));
+            req.on("end", () => onDone(Buffer.concat(chunks)));
+            req.on("error", onError);
+          });
+          const request = new Request(url.toString(), {
+            method,
+            headers: new Headers(req.headers as Record<string, string>),
+            body: bodyBuffer.length > 0 ? bodyBuffer : undefined,
+          });
+          const response = await this.app.fetch(request);
+          res.statusCode = response.status;
+          for (const [key, value] of response.headers.entries()) {
+            res.setHeader(key, value);
+          }
+          const output = Buffer.from(await response.arrayBuffer());
+          res.end(output);
+        } catch {
+          res.statusCode = 500;
+          res.end("Internal Server Error");
+        }
+      });
+
+      this.server = server;
+      server.listen(port, host, () => resolve());
+    });
+  }
+
+  /**
+   * 停止 UI 网关。
+   */
+  async stop(): Promise<void> {
+    if (!this.server) return;
+    const server = this.server;
+    this.server = null;
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  }
+}
+
+export function createControlGateway(): ControlGateway {
+  return new ControlGateway();
+}

package/src/control/EnvApiRoutes.ts

@@ -0,0 +1,257 @@
+/**
+ * 平台环境变量管理路由。
+ *
+ * 关键点（中文）
+ * - 提供 control plane 级与 agent 级环境变量的统一读写接口。
+ * - 所有 value 在 DB 中以密文存储，这里的接口只负责明文读写与删除。
+ */
+
+import dotenv from "dotenv";
+import type { Hono } from "hono";
+import { PlatformStore } from "@downcity/agent";
+
+type EnvScope = "global" | "agent";
+
+function normalizeScope(input: string | undefined): EnvScope {
+  const value = String(input || "").trim().toLowerCase();
+  if (value === "agent") return "agent";
+  return "global";
+}
+
+function normalizeNonEmptyText(value: unknown, fieldName: string): string {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} cannot be empty`);
+  }
+  return text;
+}
+
+function normalizeEnvKey(value: unknown): string {
+  const key = String(value || "").trim().toUpperCase();
+  if (!/^[A-Z_][A-Z0-9_]*$/.test(key)) {
+    throw new Error(`invalid env key: ${String(value || "")}`);
+  }
+  return key;
+}
+
+function parseDotenvEntries(raw: unknown): Array<{ key: string; value: string }> {
+  const text = String(raw || "").replace(/^\uFEFF/, "").trim();
+  if (!text) {
+    throw new Error("clipboard env text cannot be empty");
+  }
+
+  /**
+   * 关键点（中文）
+   * - 兼容用户直接复制 `export KEY=value` 形式。
+   * - 仍然复用 `dotenv.parse`，保持 `.env` 解析行为一致。
+   */
+  const normalized = text
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^(\s*)export\s+/, "$1"))
+    .join("\n");
+  const parsed = dotenv.parse(normalized);
+  const entries = Object.entries(parsed).map(([key, value]) => ({
+    key: normalizeEnvKey(key),
+    value: String(value ?? ""),
+  }));
+
+  if (entries.length === 0) {
+    throw new Error("clipboard does not contain valid .env entries");
+  }
+
+  return entries;
+}
+
+/**
+ * 注册 Env 管理 API 路由。
+ */
+export function registerPlatformEnvRoutes(params: {
+  /**
+   * Hono 应用实例。
+   */
+  app: Hono;
+}): void {
+  const app = params.app;
+
+  app.get("/api/ui/env", async (c) => {
+    const scope = normalizeScope(c.req.query("scope"));
+    const agentIdRaw = c.req.query("agent");
+    const store = new PlatformStore();
+    try {
+      if (scope === "agent") {
+        const agentId = String(agentIdRaw || "").trim();
+        const rows = agentId
+          ? await store.listAgentEnvEntries(agentId)
+          : await store.listAllAgentEnvEntries();
+        return c.json({
+          success: true,
+          scope,
+          agentId: agentId || undefined,
+          items: rows.map((item) => ({
+            scope: "agent" as const,
+            agentId: item.agentId,
+            key: item.key,
+            description: item.description,
+            value: item.value,
+            createdAt: item.createdAt,
+            updatedAt: item.updatedAt,
+          })),
+        });
+      }
+
+      const rows = await store.listGlobalEnvEntries();
+      return c.json({
+        success: true,
+        scope: "global",
+        items: rows.map((item) => ({
+          scope: "global" as const,
+          key: item.key,
+          description: item.description,
+          value: item.value,
+          createdAt: item.createdAt,
+          updatedAt: item.updatedAt,
+        })),
+      });
+    } catch (error) {
+      return c.json({ success: false, error: String(error) }, 500);
+    } finally {
+      store.close();
+    }
+  });
+
+  app.post("/api/ui/env/upsert", async (c) => {
+    try {
+      const body = (await c.req.json().catch(() => ({}))) as {
+        scope?: string;
+        agentId?: string;
+        key?: string;
+        description?: string;
+        value?: string;
+      };
+      const scope = normalizeScope(body.scope);
+      const key = normalizeNonEmptyText(body.key, "env key");
+      const description = String(body.description || "").trim();
+      const value = String(body.value ?? "");
+      const store = new PlatformStore();
+      try {
+        if (scope === "agent") {
+          const agentId = normalizeNonEmptyText(body.agentId, "agentId");
+          await store.upsertAgentEnvEntry({
+            agentId,
+            key,
+            description,
+            value,
+          });
+          return c.json({
+            success: true,
+            scope,
+            agentId,
+            key,
+          });
+        }
+
+        await store.upsertGlobalEnvEntry({
+          key,
+          description,
+          value,
+        });
+        return c.json({
+          success: true,
+          scope: "global",
+          key,
+        });
+      } finally {
+        store.close();
+      }
+    } catch (error) {
+      return c.json({ success: false, error: String(error) }, 500);
+    }
+  });
+
+  app.post("/api/ui/env/remove", async (c) => {
+    try {
+      const body = (await c.req.json().catch(() => ({}))) as {
+        scope?: string;
+        agentId?: string;
+        key?: string;
+      };
+      const scope = normalizeScope(body.scope);
+      const key = normalizeNonEmptyText(body.key, "env key");
+      const store = new PlatformStore();
+      try {
+        if (scope === "agent") {
+          const agentId = normalizeNonEmptyText(body.agentId, "agentId");
+          store.removeAgentEnvEntry(agentId, key);
+          return c.json({
+            success: true,
+            scope,
+            agentId,
+            key,
+          });
+        }
+
+        store.removeGlobalEnvEntry(key);
+        return c.json({
+          success: true,
+          scope: "global",
+          key,
+        });
+      } finally {
+        store.close();
+      }
+    } catch (error) {
+      return c.json({ success: false, error: String(error) }, 500);
+    }
+  });
+
+  app.post("/api/ui/env/import", async (c) => {
+    try {
+      const body = (await c.req.json().catch(() => ({}))) as {
+        scope?: string;
+        agentId?: string;
+        raw?: string;
+      };
+      const scope = normalizeScope(body.scope);
+      const entries = parseDotenvEntries(body.raw);
+      const store = new PlatformStore();
+      try {
+        if (scope === "agent") {
+          const agentId = normalizeNonEmptyText(body.agentId, "agentId");
+          for (const entry of entries) {
+            await store.upsertAgentEnvEntry({
+              agentId,
+              key: entry.key,
+              description: "",
+              value: entry.value,
+            });
+          }
+          return c.json({
+            success: true,
+            scope,
+            agentId,
+            count: entries.length,
+            keys: entries.map((entry) => entry.key),
+          });
+        }
+
+        for (const entry of entries) {
+          await store.upsertGlobalEnvEntry({
+            key: entry.key,
+            description: "",
+            value: entry.value,
+          });
+        }
+        return c.json({
+          success: true,
+          scope: "global",
+          count: entries.length,
+          keys: entries.map((entry) => entry.key),
+        });
+      } finally {
+        store.close();
+      }
+    } catch (error) {
+      return c.json({ success: false, error: String(error) }, 500);
+    }
+  });
+}