@downcity/agent 1.1.8 → 1.1.10

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/agent/AgentContext.ts

@@ -13,15 +13,15 @@ import type {
   InvokeServicePort,
   SessionCollectionPort,
 } from "@/agent/AgentContextTypes.js";
-import type { JsonValue } from "@/shared/types/Json.js";
+import type { JsonValue } from "@/utils/types/Json.js";
 import type {
   PluginAvailability,
   PluginPort,
   PluginView,
-} from "@/shared/types/Plugin.js";
+} from "@/plugin/types/Plugin.js";
 import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
 import { runServiceCommand } from "@/service/core/Manager.js";
-import { getPluginManager } from "@/plugin/PluginManager.js";
+import { getPluginManager } from "@/plugin/core/PluginManager.js";
 import { getAgentRuntime } from "@/agent/AgentRuntimeState.js";
 import { appendExecSessionMessage } from "@/service/builtins/chat/runtime/ChatIngressStore.js";
 import { readChatMetaBySessionId } from "@/service/builtins/chat/runtime/ChatMetaStore.js";

package/src/agent/AgentContextTypes.ts

@@ -8,16 +8,16 @@
  */
 
 import type { LanguageModel } from "ai";
-import type { Logger } from "@shared/utils/logger/Logger.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
 import type {
   AgentPathRuntime,
   AgentPlatformRuntime,
   AgentPluginConfigRuntime,
-} from "@/shared/types/AgentHost.js";
-import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
-import type { JsonObject, JsonValue } from "@/shared/types/Json.js";
-import type { PluginPort } from "@/shared/types/Plugin.js";
+} from "@/host/types/AgentHost.js";
+import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
+import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { PluginPort } from "@/plugin/types/Plugin.js";
 import type { ChatMetaV1 } from "@/service/builtins/chat/types/ChatMeta.js";
 import type {
   ChatQueueEnqueueParams,
@@ -27,12 +27,12 @@ import type {
   SessionMetadataV1,
   SessionMessageV1,
   SessionUserMessageV1,
-} from "@/types/session/SessionMessages.js";
+} from "@/session/types/SessionMessages.js";
 import type {
   SessionAssistantStepCallback,
   SessionRunInput,
   SessionRunResult,
-} from "@/types/session/SessionRun.js";
+} from "@/session/types/SessionRun.js";
 
 /**
  * 跨 service 调用参数。

package/src/agent/AgentRuntime.ts

@@ -10,7 +10,7 @@
 
 import path from "path";
 import fs from "fs";
-import { logger as defaultLogger } from "@shared/utils/logger/Logger.js";
+import { logger as defaultLogger } from "@/utils/logger/Logger.js";
 import { LocalSessionExecutor } from "@session/executors/local/LocalSessionExecutor.js";
 import { ensureRuntimeProjectReady } from "@/host/daemon/ProjectSetup.js";
 import { createModel } from "@/model/CreateModel.js";
@@ -48,7 +48,7 @@ import {
 } from "@/agent/AgentRuntimeState.js";
 import { createRegisteredServiceInstances } from "@/service/core/ServiceClassRegistry.js";
 import { readProjectPrimaryModelId } from "@/agent/project/ProjectExecutionBinding.js";
-import { initializePluginManager, resetPluginManager } from "@/plugin/PluginManager.js";
+import { initializePluginManager, resetPluginManager } from "@/plugin/core/PluginManager.js";
 import {
   clearPluginRuntimeContextResolver,
   setPluginRuntimeContextResolver,
@@ -58,7 +58,7 @@ import {
   createAgentPluginConfigRuntime,
 } from "@/host/runtime/AgentHostRuntime.js";
 import { updateAgentRuntimeConfig } from "@/agent/AgentRuntimeState.js";
-import type { AgentPlatformRuntime } from "@/shared/types/AgentHost.js";
+import type { AgentPlatformRuntime } from "@/host/types/AgentHost.js";
 
 export type { AgentRuntimeBase, AgentRuntime } from "@/agent/AgentRuntimeState.js";
 export {

package/src/agent/AgentRuntimeState.ts

@@ -12,12 +12,12 @@ import type {
   AgentRuntime,
   AgentRuntimeBase,
 } from "@/agent/AgentRuntimeTypes.js";
-import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
+import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
 import type {
   AgentPathRuntime,
   AgentPlatformRuntime,
   AgentPluginConfigRuntime,
-} from "@/shared/types/AgentHost.js";
+} from "@/host/types/AgentHost.js";
 import type { ChatChannelName } from "@/service/builtins/chat/types/ChannelStatus.js";
 export type { AgentRuntime, AgentRuntimeBase } from "@/agent/AgentRuntimeTypes.js";
 

package/src/agent/AgentRuntimeTypes.ts

@@ -8,13 +8,13 @@
  */
 
 import type { LanguageModel } from "ai";
-import type { Logger } from "@shared/utils/logger/Logger.js";
-import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
 import type {
   AgentPathRuntime,
   AgentPlatformRuntime,
   AgentPluginConfigRuntime,
-} from "@/shared/types/AgentHost.js";
+} from "@/host/types/AgentHost.js";
 import type { BaseService } from "@/service/builtins/BaseService.js";
 import type { Session } from "@session/Session.js";
 

package/src/agent/project/AgentInitializer.ts

@@ -26,23 +26,23 @@ import {
   getDowncityTasksDirPath,
   getSoulMdPath,
 } from "@/config/Paths.js";
-import { DEFAULT_DOWNCITY_JSON } from "@/shared/constants/DowncityDefault.js";
-import { DOWNCITY_JSON_SCHEMA } from "@/shared/constants/DowncitySchema.js";
+import { DEFAULT_DOWNCITY_JSON } from "@/config/DowncityDefault.js";
+import { DOWNCITY_JSON_SCHEMA } from "@/config/DowncitySchema.js";
 import type { DowncityConfig } from "@/config/Config.js";
 import {
   DEFAULT_PROFILE_MD_TEMPLATE,
   DEFAULT_SOUL_MD_TEMPLATE,
 } from "@session/composer/system/default/InitPrompts.js";
-import { renderTemplateVariables } from "@/shared/utils/Template.js";
-import { ensureDir, saveJson } from "@/shared/utils/storage/index.js";
+import { renderTemplateVariables } from "@/utils/Template.js";
+import { ensureDir, saveJson } from "@/utils/storage/index.js";
 import type {
   AgentProjectChannel,
   AgentProjectInitializationInput,
   AgentProjectInitializationResult,
-} from "@/shared/types/AgentProject.js";
+} from "@/agent/project/types/AgentProject.js";
 import { assertProjectExecutionTarget } from "@/agent/project/ProjectExecutionBinding.js";
-import type { ExecutionBindingConfig } from "@/shared/types/ExecutionBinding.js";
-import type { AgentPlatformRuntime } from "@/shared/types/AgentHost.js";
+import type { ExecutionBindingConfig } from "@/config/types/ExecutionBinding.js";
+import type { AgentPlatformRuntime } from "@/host/types/AgentHost.js";
 
 /**
  * 平台模型选项。
@@ -64,6 +64,43 @@ type EnvEntry = {
   value: string;
 };
 
+/**
+ * 确保 `.gitignore` 包含指定条目。
+ *
+ * 关键点（中文）
+ * - 只做最小追加，不重排用户已有内容。
+ * - 已存在同名规则时不重复写入，避免污染版本库。
+ */
+async function ensureGitignoreEntry(params: {
+  projectRoot: string;
+  entry: string;
+}): Promise<"created" | "updated" | "unchanged"> {
+  const projectRoot = path.resolve(String(params.projectRoot || "").trim() || ".");
+  const entry = String(params.entry || "").trim();
+  if (!entry) return "unchanged";
+
+  const gitignorePath = path.join(projectRoot, ".gitignore");
+  const hasGitignore = await fs.pathExists(gitignorePath);
+  const existingContent = hasGitignore
+    ? await fs.readFile(gitignorePath, "utf-8")
+    : "";
+  const normalizedLines = existingContent
+    .split(/\r?\n/)
+    .map((line) => String(line || "").trim());
+
+  if (normalizedLines.includes(entry)) {
+    return "unchanged";
+  }
+
+  const lines = existingContent ? [existingContent] : [];
+  if (existingContent && !existingContent.endsWith("\n")) {
+    lines.push("\n");
+  }
+  lines.push(`${entry}\n`);
+  await fs.writeFile(gitignorePath, lines.join(""), "utf-8");
+  return hasGitignore ? "updated" : "created";
+}
+
 /**
  * 规范化默认 Agent 名称。
  */
@@ -338,6 +375,16 @@ export async function initializeAgentProject(
     entries: [],
   });
 
+  const gitignoreStatus = await ensureGitignoreEntry({
+    projectRoot,
+    entry: ".downcity",
+  });
+  if (gitignoreStatus === "created" || gitignoreStatus === "updated") {
+    createdFiles.push(".gitignore");
+  } else {
+    skippedFiles.push(".gitignore");
+  }
+
   const dirs = [
     getDowncityDirPath(projectRoot),
     getDowncityTasksDirPath(projectRoot),

package/src/agent/project/ProjectExecutionBinding.ts

@@ -7,8 +7,8 @@
  * - 避免解析逻辑散落在多个模块中。
  */
 
-import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
-import type { ExecutionBindingConfig } from "@/shared/types/ExecutionBinding.js";
+import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
+import type { ExecutionBindingConfig } from "@/config/types/ExecutionBinding.js";
 
 /**
  * 读取项目执行绑定。

package/src/agent/project/types/AgentProject.ts

@@ -0,0 +1,92 @@
+/**
+ * Agent 项目初始化相关类型定义。
+ *
+ * 关键点（中文）
+ * - 统一承载 CLI 与 control plane 共用的初始化输入/输出结构。
+ * - 所有字段都面向"项目骨架创建"语义，不掺杂 runtime 状态。
+ */
+
+import type { ExecutionBindingConfig } from "@/config/types/ExecutionBinding.js";
+import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
+
+/**
+ * 可选的 chat channel 标识。
+ */
+export type AgentProjectChannel = "telegram" | "feishu" | "qq";
+
+/**
+ * 初始化 agent 项目的输入参数。
+ */
+export interface AgentProjectInitializationInput {
+  /**
+   * agent 项目根目录（绝对路径或可解析相对路径）。
+   */
+  projectRoot: string;
+
+  /**
+   * agent 展示名。
+   *
+   * 关键点（中文）
+   * - 为空时会自动回退到目录名推导出的默认名称。
+   */
+  agentName?: string;
+
+  /**
+   * 项目执行绑定配置。
+   *
+   * 说明（中文）
+   * - 绑定平台全局模型池中的模型 ID。
+   */
+  execution: ExecutionBindingConfig;
+
+  /**
+   * 需要一并写入项目的 plugin 配置补丁。
+   *
+   * 说明（中文）
+   * - 这里只承载初始化时的最小配置，不负责 city 级 plugin lifecycle。
+   */
+  plugins?: DowncityConfig["plugins"];
+
+  /**
+   * 需要启用的 chat channels。
+   *
+   * 关键点（中文）
+   * - 仅写入用户选择的渠道，未选择的渠道不会写入 `downcity.json`。
+   */
+  channels?: AgentProjectChannel[];
+
+  /**
+   * 是否允许覆盖已存在的 `downcity.json`。
+   */
+  forceOverwriteShipJson?: boolean;
+}
+
+/**
+ * 初始化完成后的摘要结果。
+ */
+export interface AgentProjectInitializationResult {
+  /**
+   * 已解析后的 agent 项目根目录（绝对路径）。
+   */
+  projectRoot: string;
+
+  /**
+   * 最终写入的 agent 名称。
+   */
+  agentName: string;
+
+  /**
+   * 最终启用的 chat channels。
+   */
+  channels: AgentProjectChannel[];
+
+  /**
+   * 本次实际创建/写入的文件列表。
+   */
+  createdFiles: string[];
+
+  /**
+   * 因已存在而跳过的文件列表。
+   */
+  skippedFiles: string[];
+}

package/src/config/Config.ts

@@ -9,8 +9,8 @@
 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 type { DowncityConfig } from "@/config/types/DowncityConfig.js";
+import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
 import { assertProjectExecutionTarget } from "@/agent/project/ProjectExecutionBinding.js";
 
 export type { DowncityConfig };

package/src/config/DowncityDefault.ts

@@ -0,0 +1,38 @@
+import type { DowncityConfig } from "@/config/types/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,
+        },
+      },
+    },
+  },
+};