@downcity/agent 1.1.1

package/src/agent/project/AgentInitializer.ts

@@ -0,0 +1,382 @@
+/**
+ * AgentInitializer：创建/初始化 agent 项目的复用模块。
+ *
+ * 关键点（中文）
+ * - CLI `city agent create` 与 Console 共用同一套初始化逻辑，避免模板与目录结构分叉。
+ * - 只负责项目骨架与配置文件，不处理 daemon 启停。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import {
+  getCacheDirPath,
+  getLogsDirPath,
+  getProfileMdPath,
+  getDowncityConfigDirPath,
+  getDowncityDataDirPath,
+  getDowncityDebugDirPath,
+  getDowncityDirPath,
+  getDowncityJsonPath,
+  getDowncityProfileDirPath,
+  getDowncityProfileOtherPath,
+  getDowncityProfilePrimaryPath,
+  getDowncityPublicDirPath,
+  getDowncitySchemaPath,
+  getDowncitySessionRootDirPath,
+  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 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 { ConsoleStore } from "@/shared/utils/store/index.js";
+import type {
+  AgentProjectChannel,
+  AgentProjectInitializationInput,
+  AgentProjectInitializationResult,
+} from "@/shared/types/AgentProject.js";
+import { assertProjectExecutionTarget } from "@/agent/project/ProjectExecutionBinding.js";
+import type { ExecutionBindingConfig } from "@/shared/types/ExecutionBinding.js";
+
+/**
+ * Console 模型选项。
+ */
+export interface ConsoleModelChoice {
+  /**
+   * 下拉展示文案。
+   */
+  title: string;
+
+  /**
+   * 模型 ID。
+   */
+  value: string;
+}
+
+type EnvEntry = {
+  key: string;
+  value: string;
+};
+
+/**
+ * 规范化默认 Agent 名称。
+ */
+export function normalizeDefaultAgentName(input: string): string {
+  return String(input || "")
+    .trim()
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * 读取 console 全局模型选项。
+ */
+export async function listConsoleModelChoices(): Promise<ConsoleModelChoice[]> {
+  const store = new ConsoleStore();
+  try {
+    const models = store.listModels();
+    const providers = await store.listProviders();
+    const providerMap = new Map(providers.map((item) => [item.id, item] as const));
+    return models
+      .map((item) => {
+        const id = String(item.id || "").trim();
+        if (!id) return null;
+        const providerId = String(item.providerId || "").trim();
+        const providerType = String(providerMap.get(providerId)?.type || "").trim();
+        const providerLabel = providerId
+          ? providerType
+            ? `${providerId} (${providerType})`
+            : providerId
+          : "-";
+        return {
+          title: `${id} · ${providerLabel}`,
+          value: id,
+        };
+      })
+      .filter((item): item is ConsoleModelChoice => item !== null);
+  } finally {
+    store.close();
+  }
+}
+
+function parseEnvKeys(content: string): Set<string> {
+  const out = new Set<string>();
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = String(rawLine || "").trim();
+    if (!line || line.startsWith("#")) continue;
+    const matched = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (!matched) continue;
+    out.add(matched[1]);
+  }
+  return out;
+}
+
+function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * 仅追加缺失 env 项。
+ */
+async function appendMissingEnvEntries(params: {
+  filePath: string;
+  sectionTitle: string;
+  entries: EnvEntry[];
+  overwriteKeys?: Set<string>;
+}): Promise<void> {
+  const filePath = String(params.filePath || "").trim();
+  if (!filePath) return;
+  const entries = Array.isArray(params.entries)
+    ? params.entries.filter((item) => Boolean(String(item?.key || "").trim()))
+    : [];
+  const overwriteKeys = params.overwriteKeys || new Set<string>();
+
+  let existing = "";
+  if (await fs.pathExists(filePath)) {
+    existing = await fs.readFile(filePath, "utf-8");
+  }
+  const existingKeys = parseEnvKeys(existing);
+  let nextContent = existing;
+  const appendedEntries: EnvEntry[] = [];
+
+  for (const entry of entries) {
+    if (!existingKeys.has(entry.key)) {
+      appendedEntries.push(entry);
+      continue;
+    }
+    if (!overwriteKeys.has(entry.key)) continue;
+    const linePattern = new RegExp(`^${escapeRegExp(entry.key)}\\s*=.*$`, "gm");
+    if (linePattern.test(nextContent)) {
+      nextContent = nextContent.replace(linePattern, `${entry.key}=${entry.value}`);
+    }
+  }
+
+  if (appendedEntries.length > 0) {
+    const lines: string[] = [];
+    if (!nextContent.trim()) {
+      lines.push("# Downcity 环境变量");
+    }
+    lines.push("", `# ${params.sectionTitle}`);
+    for (const entry of appendedEntries) {
+      lines.push(`${entry.key}=${entry.value}`);
+    }
+    let chunk = lines.join("\n");
+    if (nextContent && !nextContent.endsWith("\n")) {
+      chunk = `\n${chunk}`;
+    }
+    nextContent = `${nextContent}${chunk}\n`;
+  }
+
+  if (appendedEntries.length > 0 || !(await fs.pathExists(filePath))) {
+    await fs.writeFile(filePath, nextContent, "utf-8");
+  }
+}
+
+/**
+ * 校验 API 主模型可用。
+ */
+function assertApiPrimaryModelReady(primaryModelId: string): void {
+  const normalizedModelId = String(primaryModelId || "").trim();
+  if (!normalizedModelId) {
+    throw new Error("execution.modelId is required");
+  }
+
+  const store = new ConsoleStore();
+  try {
+    const model = store.getModel(normalizedModelId);
+    if (!model) {
+      throw new Error(`Model not found in console model pool: ${normalizedModelId}`);
+    }
+    if (model.isPaused === true) {
+      throw new Error(`Model is paused: ${normalizedModelId}`);
+    }
+  } finally {
+    store.close();
+  }
+}
+
+function normalizeChannels(input: AgentProjectChannel[] | undefined): AgentProjectChannel[] {
+  const allowed = new Set<AgentProjectChannel>(["telegram", "feishu", "qq"]);
+  const seen = new Set<AgentProjectChannel>();
+  for (const item of Array.isArray(input) ? input : []) {
+    const value = String(item || "").trim().toLowerCase() as AgentProjectChannel;
+    if (!allowed.has(value)) continue;
+    seen.add(value);
+  }
+  return [...seen];
+}
+
+/**
+ * 判断项目是否已经具备最小初始化文件。
+ */
+export async function isAgentProjectInitialized(projectRoot: string): Promise<boolean> {
+  const normalizedRoot = path.resolve(String(projectRoot || "").trim() || ".");
+  const profileReady = await fs.pathExists(getProfileMdPath(normalizedRoot));
+  const shipReady = await fs.pathExists(getDowncityJsonPath(normalizedRoot));
+  return profileReady && shipReady;
+}
+
+/**
+ * 初始化 agent 项目骨架。
+ */
+export async function initializeAgentProject(
+  input: AgentProjectInitializationInput,
+): Promise<AgentProjectInitializationResult> {
+  const projectRoot = path.resolve(String(input.projectRoot || "").trim() || ".");
+  const projectBaseName = path.basename(projectRoot);
+  const fallbackAgentName = normalizeDefaultAgentName(projectBaseName) || projectBaseName;
+  const agentName = String(input.agentName || "").trim() || fallbackAgentName;
+  const execution = input.execution as ExecutionBindingConfig;
+  const primaryModelId = String(execution?.modelId || "").trim();
+
+  const channels = normalizeChannels(input.channels);
+  const dotEnvPath = path.join(projectRoot, ".env");
+  const dotEnvExamplePath = path.join(projectRoot, ".env.example");
+  const createdFiles: string[] = [];
+  const skippedFiles: string[] = [];
+
+  assertProjectExecutionTarget({
+    name: agentName,
+    version: "1.0.0",
+    execution,
+  });
+  if (primaryModelId) {
+    const consoleModelChoices = await listConsoleModelChoices();
+    if (consoleModelChoices.length === 0) {
+      throw new Error("Console model pool is empty. Please configure at least one model first.");
+    }
+    assertApiPrimaryModelReady(primaryModelId);
+  }
+
+  await ensureDir(projectRoot);
+
+  const profileMdPath = getProfileMdPath(projectRoot);
+  const soulMdPath = getSoulMdPath(projectRoot);
+  const shipJsonPath = getDowncityJsonPath(projectRoot);
+  const existingShipJson = await fs.pathExists(shipJsonPath);
+  if (existingShipJson && input.forceOverwriteShipJson !== true) {
+    throw new Error(`downcity.json already exists: ${shipJsonPath}`);
+  }
+
+  const initTemplateVariables = {
+    agent_name: agentName,
+  };
+  const staticPromptFiles = [
+    {
+      filename: "PROFILE.md",
+      filePath: profileMdPath,
+      content: renderTemplateVariables(DEFAULT_PROFILE_MD_TEMPLATE, initTemplateVariables),
+    },
+    {
+      filename: "SOUL.md",
+      filePath: soulMdPath,
+      content: renderTemplateVariables(DEFAULT_SOUL_MD_TEMPLATE, initTemplateVariables),
+    },
+  ] as const;
+
+  for (const file of staticPromptFiles) {
+    if (await fs.pathExists(file.filePath)) {
+      skippedFiles.push(file.filename);
+      continue;
+    }
+    await fs.writeFile(file.filePath, file.content, "utf-8");
+    createdFiles.push(file.filename);
+  }
+
+  const channelsConfig: NonNullable<
+    NonNullable<NonNullable<DowncityConfig["services"]>["chat"]>["channels"]
+  > = {};
+  if (channels.includes("telegram")) {
+    channelsConfig.telegram = { enabled: true };
+  }
+  if (channels.includes("feishu")) {
+    channelsConfig.feishu = { enabled: true };
+  }
+  if (channels.includes("qq")) {
+    channelsConfig.qq = { enabled: true };
+  }
+
+  const shipConfig: DowncityConfig = {
+    $schema: DEFAULT_DOWNCITY_JSON.$schema,
+    name: agentName,
+    version: "1.0.0",
+    execution,
+    plugins: {
+      skill: {
+        enabled: true,
+        paths: [".agents/skills"],
+        allowExternalPaths: false,
+      },
+      ...(input.plugins || {}),
+    },
+    ...(Object.keys(channelsConfig).length > 0
+      ? {
+          services: {
+            chat: {
+              channels: channelsConfig,
+            },
+          },
+        }
+      : {}),
+  };
+  await saveJson(shipJsonPath, shipConfig);
+  createdFiles.push("downcity.json");
+
+  await appendMissingEnvEntries({
+    filePath: dotEnvPath,
+    sectionTitle: "Downcity Create",
+    entries: [],
+  });
+  await appendMissingEnvEntries({
+    filePath: dotEnvExamplePath,
+    sectionTitle: "Downcity Create Example",
+    entries: [],
+  });
+
+  const dirs = [
+    getDowncityDirPath(projectRoot),
+    getDowncityTasksDirPath(projectRoot),
+    getLogsDirPath(projectRoot),
+    getCacheDirPath(projectRoot),
+    getDowncityProfileDirPath(projectRoot),
+    getDowncityDataDirPath(projectRoot),
+    getDowncitySessionRootDirPath(projectRoot),
+    getDowncityPublicDirPath(projectRoot),
+    getDowncityConfigDirPath(projectRoot),
+    path.join(projectRoot, ".agents", "skills"),
+    path.join(getDowncityDirPath(projectRoot), "schema"),
+    getDowncityDebugDirPath(projectRoot),
+  ];
+  for (const dir of dirs) {
+    await ensureDir(dir);
+  }
+
+  const shipSchemaPath = getDowncitySchemaPath(projectRoot);
+  await ensureDir(path.dirname(shipSchemaPath));
+  await saveJson(shipSchemaPath, DOWNCITY_JSON_SCHEMA);
+  createdFiles.push(".downcity/schema/downcity.schema.json");
+
+  try {
+    await ensureDir(getDowncityProfileDirPath(projectRoot));
+    await fs.ensureFile(getDowncityProfilePrimaryPath(projectRoot));
+    await fs.ensureFile(getDowncityProfileOtherPath(projectRoot));
+  } catch {
+    // ignore optional profile memory bootstrap errors
+  }
+
+  return {
+    projectRoot,
+    agentName,
+    ...(primaryModelId ? { modelId: primaryModelId } : {}),
+    channels,
+    createdFiles,
+    skippedFiles,
+  };
+}

package/src/agent/project/ProjectExecutionBinding.ts

@@ -0,0 +1,53 @@
+/**
+ * ProjectExecutionBinding：项目执行绑定解析与校验。
+ *
+ * 关键点（中文）
+ * - 项目只有一条执行路径：`execution.type = "api"`。
+ * - 所有 create / start / runtime 读写都通过这里统一解析。
+ * - 避免解析逻辑散落在多个模块中。
+ */
+
+import type { DowncityConfig } from "@/shared/types/DowncityConfig.js";
+import type { ExecutionBindingConfig } from "@/shared/types/ExecutionBinding.js";
+
+/**
+ * 读取项目执行绑定。
+ */
+export function readProjectExecutionBinding(
+  config: DowncityConfig,
+): ExecutionBindingConfig | null {
+  const execution = config.execution;
+  if (!execution || typeof execution !== "object") return null;
+  if (execution.type !== "api") return null;
+  const modelId = String(execution.modelId || "").trim();
+  if (!modelId) return null;
+  return {
+    type: "api",
+    modelId,
+  };
+}
+
+/**
+ * 读取项目绑定的主模型 ID。
+ */
+export function readProjectPrimaryModelId(config: DowncityConfig): string {
+  const execution = readProjectExecutionBinding(config);
+  return execution ? execution.modelId : "";
+}
+
+/**
+ * 判断项目是否存在执行目标。
+ */
+export function hasProjectExecutionTarget(config: DowncityConfig): boolean {
+  return readProjectExecutionBinding(config) !== null;
+}
+
+/**
+ * 断言项目已经声明执行目标。
+ */
+export function assertProjectExecutionTarget(config: DowncityConfig): void {
+  if (hasProjectExecutionTarget(config)) return;
+  throw new Error(
+    'Invalid downcity.json: "execution" is required and must be { "type": "api", "modelId": "..." }',
+  );
+}

package/src/config/Config.ts

@@ -0,0 +1,251 @@
+/**
+ * City Env Config：city 级环境与配置读取模块。
+ *
+ * 关键点（中文）
+ * - `main/city/env/*` 放的是 city 全局运行态依赖的配置基础设施，不是通用小工具目录。
+ * - 这里统一处理 `downcity.json`、项目 `.env`、全局 env store 三类配置来源。
+ * - agent 运行时和 Console 模块都通过这里读取配置，避免各处重复拼装规则。
+ */
+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 { ConsoleStore } from "@/shared/utils/store/index.js";
+import { assertProjectExecutionTarget } from "@/agent/project/ProjectExecutionBinding.js";
+
+export type { DowncityConfig };
+
+/**
+ * 读取 console 共享环境变量（`env_entries.scope=global`）。
+ */
+export function loadGlobalEnvFromStore(): Record<string, string> {
+  const store = new ConsoleStore();
+  try {
+    return store.getGlobalEnvMapSync();
+  } catch {
+    return {};
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 读取 agent 私有环境变量（`env_entries.scope=agent`）。
+ */
+export function loadAgentEnvFromStore(agentId: string): Record<string, string> {
+  const normalizedAgentId = String(agentId || "").trim();
+  if (!normalizedAgentId) return {};
+  const store = new ConsoleStore();
+  try {
+    return store.getAgentEnvMapSync(normalizedAgentId);
+  } catch {
+    return {};
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * 读取 agent 最终环境变量快照。
+ *
+ * 关键点（中文）
+ * - 来源：agent scope env（DB） + `<agent>/.env`（用户文件）。
+ * - 冲突时 `.env` 优先，满足用户可在本地即时覆盖。
+ */
+export function loadAgentEnvSnapshot(projectRoot: string): Record<string, string> {
+  const agentFromDb = loadAgentEnvFromStore(projectRoot);
+  const projectDotenv = loadProjectDotenv(projectRoot);
+  return {
+    ...agentFromDb,
+    ...projectDotenv,
+  };
+}
+
+/**
+ * 读取项目 `.env` 快照（不污染全局 process.env）。
+ *
+ * 关键点（中文）
+ * - 只返回当前 agent 项目自己的 env 映射，供 runtime 局部使用。
+ * - 不再把 agent env 注入全局，避免多个 agent 在同一 console 进程里互相污染。
+ */
+export function loadProjectDotenv(projectRoot: string): Record<string, string> {
+  // 关键点（中文）
+  // - console 级配置不再走 `~/.downcity/.env`（统一迁移到 downcity.db）
+  // - 仅解析项目 `.env`（agent 级）
+  const projectEnvPath = path.join(projectRoot, ".env");
+  if (!fs.existsSync(projectEnvPath)) {
+    return {};
+  }
+  try {
+    const raw = fs.readFileSync(projectEnvPath, "utf-8");
+    const parsed = dotenv.parse(raw);
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      const normalizedKey = String(key || "").trim();
+      if (!normalizedKey) continue;
+      result[normalizedKey] = String(value || "").trim();
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+type ResolvedConfigValue =
+  | JsonValue
+  | undefined
+  | { [key: string]: ResolvedConfigValue }
+  | ResolvedConfigValue[];
+
+function resolveEnvPlaceholdersDeep(
+  value: ResolvedConfigValue,
+  resolveEnvVar: (name: string) => string | undefined,
+): ResolvedConfigValue {
+  if (typeof value === "string") {
+    const match = value.match(/^\$\{([A-Z0-9_]+)\}$/);
+    if (!match) return value;
+    const envVar = match[1];
+    return resolveEnvVar(envVar);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveEnvPlaceholdersDeep(item, resolveEnvVar));
+  }
+
+  if (value && typeof value === "object") {
+    const obj = value as JsonObject;
+    const out: { [key: string]: ResolvedConfigValue } = {};
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = resolveEnvPlaceholdersDeep(v as ResolvedConfigValue, resolveEnvVar);
+    }
+    return out;
+  }
+
+  return value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * 深合并：对象递归合并，数组与标量以 override 为准。
+ *
+ * 关键点（中文）
+ * - downcity.json 的“继承/覆盖”语义：越靠近 agent 项目的配置优先级越高。
+ * - 数组不做 concat，避免出现重复 paths / models。
+ */
+function deepMerge(base: unknown, override: unknown): unknown {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override === undefined ? base : override;
+  }
+
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, overrideValue] of Object.entries(override)) {
+    const baseValue = (base as Record<string, unknown>)[key];
+    if (Array.isArray(overrideValue)) {
+      out[key] = overrideValue;
+      continue;
+    }
+    if (isPlainObject(overrideValue) && isPlainObject(baseValue)) {
+      out[key] = deepMerge(baseValue, overrideValue);
+      continue;
+    }
+    out[key] = overrideValue === undefined ? baseValue : overrideValue;
+  }
+  return out;
+}
+
+function readShipJsonLayer(
+  filePath: string,
+  resolveEnvVar: (name: string) => string | undefined,
+): ResolvedConfigValue {
+  const raw = fs.readJsonSync(filePath) as ResolvedConfigValue;
+  return resolveEnvPlaceholdersDeep(raw, resolveEnvVar);
+}
+
+/**
+ * 校验项目层是否误配废弃的 `extensions` 字段。
+ *
+ * 关键点（中文）
+ * - 新版本统一使用 `plugins`。
+ * - 发现旧字段时直接报错，避免继续沿用已删除方案。
+ */
+function assertNoProjectExtensionsLayer(
+  filePath: string,
+  layer: ResolvedConfigValue,
+): void {
+  if (!isPlainObject(layer)) return;
+  if (!Object.prototype.hasOwnProperty.call(layer, "extensions")) return;
+  throw new Error(
+    `Invalid downcity.json: legacy "extensions" config is no longer supported. Use "plugins" instead (${filePath})`,
+  );
+}
+
+function collectAncestorShipJsonPaths(projectRoot: string): string[] {
+  const paths: string[] = [];
+  const resolvedRoot = path.resolve(projectRoot);
+  let dir = resolvedRoot;
+  while (true) {
+    const candidate = path.join(dir, "downcity.json");
+    if (fs.existsSync(candidate)) paths.push(candidate);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // root -> leaf
+  return paths.reverse();
+}
+
+export function loadDowncityConfig(
+  projectRoot: string,
+  options?: {
+    projectEnv?: Record<string, string>;
+    agentEnv?: Record<string, string>;
+    globalEnv?: Record<string, string>;
+  },
+): DowncityConfig {
+  const projectDotenv = options?.projectEnv ?? loadProjectDotenv(projectRoot);
+  const agentEnv = options?.agentEnv ?? loadAgentEnvFromStore(projectRoot);
+  const globalEnv = options?.globalEnv ?? loadGlobalEnvFromStore();
+  const runtimeAgentEnv = {
+    ...agentEnv,
+    ...projectDotenv,
+  };
+  /**
+   * 读取 agent 项目私有环境变量（services）。
+   *
+   * 关键点（中文）
+   * - project 层只读当前项目 .env，不再回退到共享 env。
+   * - 从根上杜绝跨 agent 的服务凭据串用。
+   */
+  const resolveProjectEnvVar = (name: string): string | undefined => {
+    const projectValue = String(runtimeAgentEnv[name] || "").trim();
+    return projectValue || undefined;
+  };
+
+  const ancestorShipJsonPaths = collectAncestorShipJsonPaths(projectRoot);
+  if (ancestorShipJsonPaths.length === 0) {
+    throw new Error("downcity.json not found in project directory");
+  }
+
+  let merged: unknown = undefined;
+  for (const p of ancestorShipJsonPaths) {
+    const layer = readShipJsonLayer(p, resolveProjectEnvVar);
+    assertNoProjectExtensionsLayer(p, layer);
+    merged = deepMerge(merged, layer);
+  }
+
+  if (!merged || typeof merged !== "object" || Array.isArray(merged)) {
+    throw new Error("Invalid downcity.json: expected object");
+  }
+
+  const candidate = merged as Partial<DowncityConfig>;
+  if (typeof candidate.name !== "string" || typeof candidate.version !== "string") {
+    throw new Error("Invalid downcity.json: missing required fields name/version");
+  }
+  const config = candidate as DowncityConfig;
+  assertProjectExecutionTarget(config);
+  return config;
+}