@downcity/agent 1.1.8 → 1.1.11

package/scripts/agent-compiler.mjs

@@ -0,0 +1,253 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Agent compiler：统一处理 text module 生成、build、typecheck 与 dev watch。
+ *
+ * 关键点（中文）
+ * - `*.ts.txt` 是 prompt 文本源码；生成后得到同路径的 `*.ts` 模块。
+ * - runtime / bundler 只依赖生成后的 TS 模块，不再读取文本文件。
+ * - build / typecheck / dev 全部收敛到一个脚本入口，减少流程分叉。
+ */
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const srcRoot = path.join(packageRoot, "src");
+const generatedHeader = [
+  "/**",
+  " * 自动生成文件，请勿手改。",
+  " * 源文件：由同路径 `*.ts.txt` 生成。",
+  " */",
+  "",
+].join("\n");
+
+function toPosixRelative(filePath) {
+  return path.relative(packageRoot, filePath).split(path.sep).join("/");
+}
+
+async function collectTextModuleSources(rootDir) {
+  const out = [];
+
+  async function walk(currentDir) {
+    const entries = await fsp.readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const absPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absPath);
+        continue;
+      }
+      if (entry.isFile() && absPath.endsWith(".ts.txt")) {
+        out.push(absPath);
+      }
+    }
+  }
+
+  await walk(rootDir);
+  return out.sort();
+}
+
+function renderGeneratedTextModule(params) {
+  const { sourcePath, rawText } = params;
+  return [
+    generatedHeader,
+    `// Source: ${toPosixRelative(sourcePath)}`,
+    `const TEXT_MODULE_CONTENT = ${JSON.stringify(rawText)};`,
+    "",
+    "export default TEXT_MODULE_CONTENT;",
+    "",
+  ].join("\n");
+}
+
+async function writeGeneratedModule(sourcePath) {
+  const targetPath = sourcePath.slice(0, -4);
+  const rawText = await fsp.readFile(sourcePath, "utf-8");
+  const rendered = renderGeneratedTextModule({
+    sourcePath,
+    rawText,
+  });
+  await fsp.mkdir(path.dirname(targetPath), { recursive: true });
+  const previous = await fsp.readFile(targetPath, "utf-8").catch(() => null);
+  if (previous === rendered) return false;
+  await fsp.writeFile(targetPath, rendered, "utf-8");
+  return true;
+}
+
+async function generateTextModules() {
+  const sourceFiles = await collectTextModuleSources(srcRoot);
+  let updatedCount = 0;
+  for (const sourcePath of sourceFiles) {
+    const changed = await writeGeneratedModule(sourcePath);
+    if (changed) updatedCount += 1;
+  }
+  return {
+    sourceCount: sourceFiles.length,
+    updatedCount,
+  };
+}
+
+function spawnCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: packageRoot,
+      stdio: "inherit",
+      env: process.env,
+      ...options,
+    });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`${command} exited with signal ${signal}`));
+        return;
+      }
+      if (code !== 0) {
+        reject(new Error(`${command} exited with code ${String(code)}`));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+async function runBuild() {
+  await generateTextModules();
+  await spawnCommand("rm", ["-rf", "bin", "tsconfig.tsbuildinfo"]);
+  await spawnCommand("tsc", []);
+  await spawnCommand("tsc-alias", ["-f"]);
+}
+
+async function runTypecheck() {
+  await generateTextModules();
+  await spawnCommand("tsc", ["--noEmit"]);
+}
+
+async function runDev() {
+  await generateTextModules();
+
+  const watchers = [];
+  const watchedDirs = new Set();
+  let regenerateTimer = null;
+  let generating = Promise.resolve();
+  let rerunRequested = false;
+
+  async function collectDirectories(rootDir) {
+    const directories = [];
+    async function walk(currentDir) {
+      directories.push(currentDir);
+      const entries = await fsp.readdir(currentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        await walk(path.join(currentDir, entry.name));
+      }
+    }
+    await walk(rootDir);
+    return directories;
+  }
+
+  async function attachWatchers() {
+    const directories = await collectDirectories(srcRoot);
+    for (const dirPath of directories) {
+      if (watchedDirs.has(dirPath)) continue;
+      const watcher = fs.watch(dirPath, (_eventType, filename) => {
+        const normalized = filename
+          ? Buffer.isBuffer(filename)
+            ? filename.toString("utf-8")
+            : String(filename)
+          : "";
+        if (!normalized.endsWith(".ts.txt")) return;
+        scheduleGenerate();
+      });
+      watchers.push(watcher);
+      watchedDirs.add(dirPath);
+    }
+  }
+
+  async function regenerate() {
+    try {
+      const result = await generateTextModules();
+      if (result.updatedCount > 0) {
+        console.log(
+          `[agent-compiler] regenerated ${String(result.updatedCount)} of ${String(result.sourceCount)} text module(s)`,
+        );
+      }
+      await attachWatchers();
+    } catch (error) {
+      console.error("[agent-compiler] regenerate failed");
+      console.error(error);
+    }
+  }
+
+  function runRegenerateQueue() {
+    generating = generating.finally(async () => {
+      await regenerate();
+      if (!rerunRequested) return;
+      rerunRequested = false;
+      runRegenerateQueue();
+    });
+  }
+
+  function scheduleGenerate() {
+    if (regenerateTimer) clearTimeout(regenerateTimer);
+    regenerateTimer = setTimeout(() => {
+      regenerateTimer = null;
+      if (generating && generating !== Promise.resolve()) {
+        rerunRequested = true;
+      }
+      runRegenerateQueue();
+    }, 120);
+  }
+
+  await attachWatchers();
+  const tscWatch = spawn("tsc", ["--watch"], {
+    cwd: packageRoot,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  const shutdown = () => {
+    for (const watcher of watchers) watcher.close();
+    if (!tscWatch.killed) {
+      tscWatch.kill("SIGINT");
+    }
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  await new Promise((resolve, reject) => {
+    tscWatch.on("error", reject);
+    tscWatch.on("exit", (code, signal) => {
+      shutdown();
+      if (signal && signal !== "SIGINT" && signal !== "SIGTERM") {
+        reject(new Error(`tsc --watch exited with signal ${signal}`));
+        return;
+      }
+      if (code && code !== 0) {
+        reject(new Error(`tsc --watch exited with code ${String(code)}`));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+const mode = String(process.argv[2] || "build").trim().toLowerCase();
+
+if (mode === "build") {
+  await runBuild();
+} else if (mode === "typecheck") {
+  await runTypecheck();
+} else if (mode === "dev") {
+  await runDev();
+} else if (mode === "generate") {
+  const result = await generateTextModules();
+  console.log(
+    `[agent-compiler] generated ${String(result.sourceCount)} text module(s), updated ${String(result.updatedCount)}`,
+  );
+} else {
+  console.error(`Unknown mode: ${mode}`);
+  process.exit(1);
+}

package/src/config/Config.ts

@@ -1,17 +1,16 @@
 /**
- * City Env Config：city 级环境与配置读取模块。
+ * Config：agent 项目环境与配置读取模块。
  *
  * 关键点（中文）
- * - `main/city/env/*` 放的是 city 全局运行态依赖的配置基础设施，不是通用小工具目录。
- * - 这里统一处理 `downcity.json`、项目 `.env`、全局 env store 三类配置来源。
- * - agent 运行时和 control plane 都通过这里读取配置，避免各处重复拼装规则。
+ * - 这里统一处理 `downcity.json`、项目 `.env`、全局 env 快照三类配置来源。
+ * - agent 运行时通过这里读取项目配置，避免各处重复拼装规则。
  */
 import dotenv from "dotenv";
 import fs from "fs-extra";
 import path from "path";
-import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
-import type { JsonObject, JsonValue } from "@/shared/types/Json.js";
-import { assertProjectExecutionTarget } from "@/agent/project/ProjectExecutionBinding.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import { assertProjectExecutionTarget } from "@/project/ProjectExecutionBinding.js";
 
 export type { DowncityConfig };
 

package/src/config/DowncityDefault.ts

@@ -0,0 +1,38 @@
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+
+export const DEFAULT_DOWNCITY_JSON: DowncityConfig = {
+  $schema: "./.downcity/schema/downcity.schema.json",
+  name: "downcity",
+  version: "1.0.0",
+  start: {
+    port: 5314,
+    host: "0.0.0.0",
+  },
+  execution: {
+    type: "api",
+    modelId: "default",
+  },
+  context: {
+    messages: {
+      keepLastMessages: 30,
+      maxInputTokensApprox: 128000,
+      archiveOnCompact: true,
+      compactRatio: 0.5,
+    },
+  },
+  services: {
+    chat: {
+      queue: {
+        maxConcurrency: 2,
+        mergeDebounceMs: 600,
+        mergeMaxWaitMs: 2000,
+      },
+      channels: {
+        telegram: {
+          enabled: false,
+          channelAccountId: undefined,
+        },
+      },
+    },
+  },
+};

package/src/config/DowncitySchema.ts

@@ -0,0 +1,377 @@
+import type { JsonObject } from "@/types/common/Json.js";
+
+export const DOWNCITY_JSON_SCHEMA: JsonObject = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://downcity.ai/schemas/downcity.schema.json",
+  title: "Downcity downcity.json",
+  type: "object",
+  additionalProperties: true,
+  properties: {
+    $schema: {
+      type: "string",
+      description:
+        "JSON Schema reference for editor/IDE validation (e.g. ./.downcity/schema/downcity.schema.json).",
+    },
+    name: { type: "string" },
+    version: { type: "string" },
+    description: { type: "string" },
+    start: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        port: { type: "integer", minimum: 1, maximum: 65535 },
+        host: { type: "string" },
+      },
+    },
+    execution: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        type: {
+          type: "string",
+          enum: ["api", "acp", "local"],
+        },
+        modelId: {
+          type: "string",
+          description:
+            "API 执行模式下绑定的平台全局模型 ID。",
+        },
+        agent: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            type: {
+              type: "string",
+              enum: ["codex", "claude", "kimi"],
+            },
+            command: { type: "string" },
+            args: {
+              type: "array",
+              items: { type: "string" },
+            },
+            env: {
+              type: "object",
+              additionalProperties: { type: "string" },
+            },
+          },
+          required: ["type"],
+        },
+        local: {
+          type: "null",
+          description:
+            "本地执行模式不再从 execution.local 读取配置；请改为使用 plugins.lmp。",
+        },
+      },
+      required: ["type"],
+      allOf: [
+        {
+          if: {
+            properties: {
+              type: { const: "api" },
+            },
+          },
+          then: {
+            required: ["modelId"],
+          },
+        },
+        {
+          if: {
+            properties: {
+              type: { const: "acp" },
+            },
+          },
+          then: {
+            required: ["agent"],
+          },
+        },
+        {
+          if: {
+            properties: {
+              type: { const: "local" },
+            },
+          },
+          then: true,
+        },
+      ],
+    },
+    sandbox: {
+      type: "object",
+      additionalProperties: true,
+      description:
+        "Shell / CLI sandbox boundary configuration for local command execution. Sandbox is always required for shell execution.",
+      properties: {
+        envAllowlist: {
+          type: "array",
+          description:
+            "Environment variable names that may be exported into the sandbox.",
+          items: { type: "string" },
+        },
+        writablePaths: {
+          type: "array",
+          description:
+            "Writable paths, absolute or relative to the project root.",
+          items: { type: "string" },
+        },
+        networkMode: {
+          type: "string",
+          enum: ["off", "restricted", "full"],
+          description:
+            "Network boundary for sandboxed shell execution.",
+        },
+      },
+    },
+    services: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        skills: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            paths: { type: "array", items: { type: "string" } },
+            allowExternalPaths: { type: "boolean" },
+          },
+        },
+        chat: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            queue: {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                maxConcurrency: { type: "integer", minimum: 1, maximum: 32 },
+                mergeDebounceMs: { type: "integer", minimum: 0, maximum: 60000 },
+                mergeMaxWaitMs: { type: "integer", minimum: 0, maximum: 120000 },
+              },
+            },
+            egress: {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                chatSendMaxCallsPerRun: { type: "integer", minimum: 1, maximum: 500 },
+                chatSendIdempotency: { type: "boolean" },
+              },
+            },
+            channels: {
+              type: "object",
+              additionalProperties: true,
+              description:
+                "Chat platform channels (Telegram / Feishu / QQ...).",
+              properties: {
+                telegram: {
+                  type: "object",
+                  additionalProperties: true,
+                  properties: {
+                    enabled: { type: "boolean" },
+                    channelAccountId: { type: "string" },
+                  },
+                },
+                feishu: {
+                  type: "object",
+                  additionalProperties: true,
+                  properties: {
+                    enabled: { type: "boolean" },
+                    channelAccountId: { type: "string" },
+                  },
+                },
+                qq: {
+                  type: "object",
+                  additionalProperties: true,
+                  properties: {
+                    enabled: { type: "boolean" },
+                    channelAccountId: { type: "string" },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    plugins: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        asr: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            injectPrompt: { type: "boolean" },
+            augmentMessage: { type: "boolean" },
+            provider: { type: "string", enum: ["local", "command"] },
+            modelId: {
+              type: "string",
+              enum: [
+                "SenseVoiceSmall",
+                "paraformer-zh-streaming",
+                "whisper-large-v3-turbo",
+              ],
+            },
+            modelsDir: { type: "string" },
+            pythonBin: { type: "string" },
+            command: { type: "string" },
+            language: { type: "string" },
+            timeoutMs: { type: "integer", minimum: 1000, maximum: 600000 },
+            strategy: {
+              type: "string",
+              enum: ["auto", "funasr", "transformers-whisper", "command"],
+            },
+            installedModels: {
+              type: "array",
+              items: {
+                type: "string",
+                enum: [
+                  "SenseVoiceSmall",
+                  "paraformer-zh-streaming",
+                  "whisper-large-v3-turbo",
+                ],
+              },
+            },
+          },
+        },
+        tts: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            provider: {
+              type: "string",
+              enum: ["local"],
+            },
+            modelId: {
+              type: "string",
+              enum: ["qwen3-tts-0.6b", "kokoro-82m", "qwen3-tts-1.7b"],
+            },
+            modelsDir: { type: "string" },
+            pythonBin: { type: "string" },
+            language: { type: "string" },
+            voice: { type: "string" },
+            format: {
+              type: "string",
+              enum: ["wav", "flac"],
+            },
+            speed: { type: "number", minimum: 0.5, maximum: 2 },
+            outputDir: { type: "string" },
+            timeoutMs: { type: "integer", minimum: 5000, maximum: 900000 },
+            installedModels: {
+              type: "array",
+              items: {
+                type: "string",
+                enum: ["qwen3-tts-0.6b", "kokoro-82m", "qwen3-tts-1.7b"],
+              },
+            },
+          },
+        },
+        lmp: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            provider: {
+              type: "string",
+              enum: ["llama"],
+            },
+            model: {
+              type: "string",
+              description:
+                "当前激活的本地模型文件名或绝对路径；相对路径默认相对 plugins.lmp.modelsDir。",
+            },
+            modelsDir: {
+              type: "string",
+              description: "本地模型目录，默认 ~/.models。",
+            },
+            command: {
+              type: "string",
+              description: "llama-server 可执行命令，默认 llama-server。",
+            },
+            args: {
+              type: "array",
+              items: { type: "string" },
+            },
+            host: { type: "string" },
+            port: { type: "integer", minimum: 1, maximum: 65535 },
+            contextSize: { type: "integer", minimum: 512, maximum: 1048576 },
+            gpuLayers: { type: "integer", minimum: -1, maximum: 65535 },
+            autoStart: { type: "boolean" },
+            installedModels: {
+              type: "array",
+              items: {
+                type: "string",
+              },
+            },
+          },
+        },
+      },
+    },
+    llm: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        providers: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            additionalProperties: true,
+            properties: {
+              type: {
+                type: "string",
+                enum: [
+                  "anthropic",
+                  "openai",
+                  "deepseek",
+                  "gemini",
+                  "open-compatible",
+                  "open-responses",
+                  "moonshot-cn",
+                  "moonshot-ai",
+                  "kimi-code",
+                  "xai",
+                  "huggingface",
+                  "openrouter",
+                ],
+              },
+              baseUrl: { type: "string" },
+              apiKey: { type: "string" },
+            },
+            required: ["type"],
+          },
+        },
+        models: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            additionalProperties: true,
+            properties: {
+              provider: { type: "string" },
+              name: { type: "string" },
+              temperature: { type: "number" },
+              maxTokens: { type: "number" },
+              topP: { type: "number" },
+              frequencyPenalty: { type: "number" },
+              presencePenalty: { type: "number" },
+              anthropicVersion: { type: "string" },
+            },
+            required: ["provider", "name"],
+          },
+        },
+        logMessages: { type: "boolean" },
+      },
+      required: ["providers", "models"],
+    },
+    context: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        messages: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            keepLastMessages: { type: "integer", minimum: 6, maximum: 5000 },
+            maxInputTokensApprox: { type: "integer", minimum: 2000, maximum: 200000 },
+            archiveOnCompact: { type: "boolean" },
+            compactRatio: { type: "number", minimum: 0.1, maximum: 0.9 },
+          },
+        },
+      },
+    },
+  },
+};

package/src/config/Paths.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 统一管理单个 agent 项目内 `.downcity` 及其子目录/文件路径规则。
  * - 避免路径字符串在不同模块重复拼接，降低维护成本。
- * - 这里描述的是“项目级路径约定”，与 `main/city/runtime/CityPaths.ts` 的全局路径约定分开。
+ * - 这里描述的是“项目级路径约定”，与 city 包中的全局运行态路径约定分开。
  */
 import path from "path";
 
@@ -185,7 +185,7 @@ export function getDowncityDebugDirPath(cwd: string): string {
 }
 
 /**
- * Chat 元信息目录（由 services/chat 维护）。
+ * Chat 元信息目录（由 service/builtins/chat 维护）。
  *
  * 关键点（中文）
  * - 该目录存放 `sessionId -> chat` 的最近映射快照