@downcity/agent 1.1.43 → 1.1.51

package/src/config/AgentInitializer.ts

@@ -53,17 +53,19 @@ import { assertProjectExecutionTarget } from "@/config/ExecutionBinding.js";
 import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
 
 /**
- * 规范化默认 Agent 名称。
+ * 规范化默认 Agent ID。
  *
  * 关键点（中文）
- * - 把目录名中的 `_` / `-` 统一折叠为空格，产出更适合作为展示名的默认值。
- * - 这里只做轻量字符串清洗，不负责长度限制或唯一性处理。
+ * - 把目录名清洗为稳定、可重复的 snake_case 标识，避免展示名语义混入 SDK。
+ * - 这里只做最小格式规整，不负责跨项目唯一性分配。
  */
-export function normalizeDefaultAgentName(input: string): string {
+export function normalizeDefaultAgentId(input: string): string {
   return String(input || "")
     .trim()
-    .replace(/[_-]+/g, " ")
-    .replace(/\s+/g, " ")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .replace(/_{2,}/g, "_")
     .trim();
 }
 
@@ -112,8 +114,8 @@ export async function initializeAgentProject(
 ): 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 fallback_agent_id = normalizeDefaultAgentId(projectBaseName) || projectBaseName;
+  const agent_id = String(input.id || "").trim() || fallback_agent_id;
   const execution = input.execution as ExecutionBindingConfig;
 
   const channels = normalizeChannels(input.channels);
@@ -123,7 +125,7 @@ export async function initializeAgentProject(
   const skippedFiles: string[] = [];
 
   assertProjectExecutionTarget({
-    name: agentName,
+    id: agent_id,
     version: "1.0.0",
     execution,
   });
@@ -139,7 +141,7 @@ export async function initializeAgentProject(
   }
 
   const initTemplateVariables = {
-    agent_name: agentName,
+    agent_id,
   };
   const staticPromptFiles = [
     {
@@ -176,7 +178,7 @@ export async function initializeAgentProject(
 
   const shipConfig: DowncityConfig = {
     $schema: DEFAULT_DOWNCITY_JSON.$schema,
-    name: agentName,
+    id: agent_id,
     version: "1.0.0",
     execution,
     plugins: {
@@ -251,7 +253,7 @@ export async function initializeAgentProject(
 
   return {
     projectRoot,
-    agentName,
+    id: agent_id,
     ...(execution?.type === "api" && String(execution.modelId || "").trim()
       ? { modelId: String(execution.modelId || "").trim() }
       : {}),

package/src/config/Config.ts

@@ -2,9 +2,9 @@
  * Agent 项目配置读取与装配模块。
  *
  * 职责说明（中文）
- * - 统一负责读取 `downcity.json`、项目 `.env` 与外部注入的环境变量快照。
+ * - 统一负责读取 `downcity.json`、项目 `.env` 与宿主显式注入的基础 env。
  * - 负责把祖先目录中的多个 `downcity.json` 逐层合并成当前项目的最终配置。
- * - 负责在配置读取阶段完成 `${ENV_NAME}` 占位符替换与最小结构校验。
+ * - 负责在配置读取阶段完成最小结构校验。
  *
  * 边界说明（中文）
  * - 这里只做“配置文件 -> 运行时配置对象”的装配，不负责项目初始化写文件。
@@ -14,61 +14,18 @@ import dotenv from "dotenv";
 import fs from "fs-extra";
 import path from "path";
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { ResolvedConfigValue } from "@/types/common/ResolvedConfigValue.js";
 import { assertProjectExecutionTarget } from "@/config/ExecutionBinding.js";
-import { resolveEnvPlaceholdersDeep } from "@/config/ConfigEnvResolver.js";
 import { deepMerge } from "@/utils/object/DeepMerge.js";
 import { isPlainObject } from "@/utils/object/ObjectGuards.js";
 import { collectAncestorNamedFilePaths } from "@/utils/path/AncestorFiles.js";
 
 export type { DowncityConfig };
 
-/**
- * 读取平台共享环境变量（`env_entries.scope=global`）。
- *
- * 关键点（中文）
- * - 当前 agent 包内仍保留空实现占位，等待后续接入平台级持久化存储。
- * - 保持独立函数是为了让配置读取逻辑不依赖具体存储后端。
- */
-export function loadGlobalEnvFromStore(): Record<string, string> {
-  return {};
-}
-
-/**
- * 读取 agent 私有环境变量（`env_entries.scope=agent`）。
- *
- * 关键点（中文）
- * - 当前 agent 包内仍保留空实现占位，避免把平台存储细节耦合进运行时。
- * - 当 `agentId` 为空时直接返回空对象，表示没有可用私有环境变量。
- */
-export function loadAgentEnvFromStore(agentId: string): Record<string, string> {
-  const normalizedAgentId = String(agentId || "").trim();
-  if (!normalizedAgentId) return {};
-  return {};
-}
-
-/**
- * 读取 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 在同一 control plane 进程里互相污染。
  */
 export function loadProjectDotenv(projectRoot: string): Record<string, string> {
   // 关键点（中文）
@@ -94,18 +51,31 @@ export function loadProjectDotenv(projectRoot: string): Record<string, string> {
 }
 
 /**
- * 读取单层 `downcity.json` 并完成环境变量占位符替换。
+ * 解析当前 agent 最终用户环境变量。
+ *
+ * 关键点（中文）
+ * - 合并顺序固定为：宿主显式 `env` < 项目 `.env`。
+ * - `@downcity/agent` 不再自动读取当前进程 `process.env`。
+ * - 这里返回的是“用户可感知”的最终 env，不包含 session/server 运行时元信息。
+ */
+export function resolveAgentEnv(
+  projectRoot: string,
+  hostEnv?: Record<string, string>,
+): Record<string, string> {
+  return {
+    ...(hostEnv ? { ...hostEnv } : {}),
+    ...loadProjectDotenv(projectRoot),
+  };
+}
+
+/**
+ * 读取单层 `downcity.json`。
  *
  * 关键点（中文）
  * - 单层读取不做字段语义校验，便于后续统一合并后再做最终断言。
- * - 环境变量解析策略由调用方注入，保持该函数只负责“遍历 + 替换”。
  */
-function readShipJsonLayer(
-  filePath: string,
-  resolveEnvVar: (name: string) => string | undefined,
-): ResolvedConfigValue {
-  const raw = fs.readJsonSync(filePath) as ResolvedConfigValue;
-  return resolveEnvPlaceholdersDeep(raw, resolveEnvVar);
+function readShipJsonLayer(filePath: string): unknown {
+  return fs.readJsonSync(filePath) as unknown;
 }
 
 /**
@@ -117,7 +87,7 @@ function readShipJsonLayer(
  */
 function assertNoProjectExtensionsLayer(
   filePath: string,
-  layer: ResolvedConfigValue,
+  layer: unknown,
 ): void {
   if (!isPlainObject(layer)) return;
   if (!Object.prototype.hasOwnProperty.call(layer, "extensions")) return;
@@ -131,36 +101,9 @@ function assertNoProjectExtensionsLayer(
  *
  * 关键点（中文）
  * - 读取顺序为“祖先目录 -> 当前项目目录”，后层配置覆盖前层配置。
- * - `.env` 只影响占位符解析，不会把值写回配置文件。
  * - 返回前会断言最小执行目标，保证 agent 至少知道该如何执行。
  */
-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;
-  };
-
+export function loadDowncityConfig(projectRoot: string): DowncityConfig {
   const ancestorShipJsonPaths = collectAncestorNamedFilePaths(
     projectRoot,
     "downcity.json",
@@ -171,7 +114,7 @@ export function loadDowncityConfig(
 
   let merged: unknown = undefined;
   for (const p of ancestorShipJsonPaths) {
-    const layer = readShipJsonLayer(p, resolveProjectEnvVar);
+    const layer = readShipJsonLayer(p);
     assertNoProjectExtensionsLayer(p, layer);
     merged = deepMerge(merged, layer);
   }
@@ -181,8 +124,8 @@ export function loadDowncityConfig(
   }
 
   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");
+  if (typeof candidate.id !== "string" || typeof candidate.version !== "string") {
+    throw new Error("Invalid downcity.json: missing required fields id/version");
   }
   const config = candidate as DowncityConfig;
   assertProjectExecutionTarget(config);

package/src/config/Defaults.ts

@@ -21,7 +21,7 @@ import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
  */
 export const DEFAULT_DOWNCITY_JSON: DowncityConfig = {
   $schema: "./.downcity/schema/downcity.schema.json",
-  name: "downcity",
+  id: "downcity",
   version: "1.0.0",
   start: {
     port: 5314,
@@ -31,14 +31,6 @@ export const DEFAULT_DOWNCITY_JSON: DowncityConfig = {
     type: "api",
     modelId: "default",
   },
-  context: {
-    messages: {
-      keepLastMessages: 30,
-      maxInputTokensApprox: 128000,
-      archiveOnCompact: true,
-      compactRatio: 0.5,
-    },
-  },
   plugins: {
     chat: {
       queue: {

package/src/config/DowncitySchema.ts

@@ -30,9 +30,8 @@ export const DOWNCITY_JSON_SCHEMA: JsonObject = {
       description:
         "JSON Schema reference for editor/IDE validation (e.g. ./.downcity/schema/downcity.schema.json).",
     },
-    name: { type: "string" },
+    id: { type: "string" },
     version: { type: "string" },
-    description: { type: "string" },
     start: {
       type: "object",
       additionalProperties: true,
@@ -47,70 +46,15 @@ export const DOWNCITY_JSON_SCHEMA: JsonObject = {
       properties: {
         type: {
           type: "string",
-          enum: ["api", "acp", "local"],
+          enum: ["api"],
         },
         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,
-        },
-      ],
+      required: ["type", "modelId"],
     },
     sandbox: {
       type: "object",
@@ -274,44 +218,6 @@ export const DOWNCITY_JSON_SCHEMA: JsonObject = {
             },
           },
         },
-        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: {
@@ -369,21 +275,5 @@ export const DOWNCITY_JSON_SCHEMA: JsonObject = {
       },
       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/ExecutionBinding.ts

@@ -35,28 +35,6 @@ export function readProjectExecutionBinding(
   };
 }
 
-/**
- * 读取项目绑定的主模型 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;
-}
-
 /**
  * 断言项目已经声明执行目标。
  *
@@ -65,7 +43,7 @@ export function hasProjectExecutionTarget(config: DowncityConfig): boolean {
  * - 失败时抛出稳定错误文案，便于 CLI 和上层界面直接展示。
  */
 export function assertProjectExecutionTarget(config: DowncityConfig): void {
-  if (hasProjectExecutionTarget(config)) return;
+  if (readProjectExecutionBinding(config) !== null) return;
   throw new Error(
     'Invalid downcity.json: "execution" is required and must be { "type": "api", "modelId": "..." }',
   );

package/src/config/Paths.ts

@@ -127,6 +127,10 @@ export function getCacheDirPath(cwd: string): string {
 
 /**
  * 返回 profile 运行态目录路径。
+ *
+ * 关键点（中文）
+ * - 初始化流程会统一创建该目录，并在其中写入 profile 相关文件。
+ * - 单独保留目录级 API，避免调用方散落 `path.join(..., "profile")`。
  */
 export function getDowncityProfileDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "profile");
@@ -157,8 +161,9 @@ export function getDowncityProfileOtherPath(cwd: string): string {
  *
  * 关键点（中文）
  * - `.downcity/memory` 为跨会话记忆目录。
+ * - 当前仅供本模块内部继续拼接长期记忆与每日记忆路径。
  */
-export function getDowncityMemoryDirPath(cwd: string): string {
+function getDowncityMemoryDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "memory");
 }
 
@@ -216,8 +221,9 @@ export function getDowncityAgentsRootDirPath(cwd: string): string {
  *
  * 关键点（中文）
  * - `agentId` 会做 URL 编码，避免特殊字符污染文件系统结构。
+ * - 当前仅供本模块内部拼接 session 根目录使用。
  */
-export function getDowncityAgentDirPath(cwd: string, agentId: string): string {
+function getDowncityAgentDirPath(cwd: string, agentId: string): string {
   return path.join(
     getDowncityAgentsRootDirPath(cwd),
     encodeURIComponent(String(agentId || "").trim()),
@@ -283,23 +289,6 @@ export function getDowncitySessionMessagesPath(
   );
 }
 
-/**
- * 返回 session 历史元信息文件路径。
- *
- * 关键点（中文）
- * - 该文件保存 compaction、更新时间、SDK 配置等附加元信息。
- */
-export function getDowncitySessionHistoryMetaPath(
-  cwd: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getDowncitySessionMessagesDirPath(cwd, agentId, sessionId),
-    "meta.json",
-  );
-}
-
 /**
  * 返回 session 消息归档目录路径。
  *
@@ -368,8 +357,9 @@ export function getDowncityDebugDirPath(cwd: string): string {
  * 关键点（中文）
  * - 该目录存放 `sessionId -> chat` 的最近映射快照
  * - 与 core session messages 分离，避免把平台路由细节耦合进 core
+ * - 当前仅供本模块内部继续拼接 chat 会话与 meta 子目录。
  */
-export function getDowncityChatDirPath(cwd: string): string {
+function getDowncityChatDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "chat");
 }
 
@@ -394,29 +384,6 @@ export function getDowncityChannelMetaPath(cwd: string): string {
   return path.join(getDowncityChannelDirPath(cwd), "meta.json");
 }
 
-/**
- * 返回 chat 元信息目录路径。
- *
- * 关键点（中文）
- * - 用于按 sessionId 存放最近聊天路由快照与附加索引信息。
- */
-export function getDowncityChatMetaDirPath(cwd: string): string {
-  return path.join(getDowncityChatDirPath(cwd), "meta");
-}
-
-/**
- * 返回指定 session 的 chat 元信息文件路径。
- *
- * 关键点（中文）
- * - 文件名按 `sessionId` 编码，避免不同会话之间互相覆盖。
- */
-export function getDowncityChatMetaPath(cwd: string, sessionId: string): string {
-  return path.join(
-    getDowncityChatMetaDirPath(cwd),
-    `${encodeURIComponent(String(sessionId || "").trim())}.json`,
-  );
-}
-
 /**
  * Chat 会话目录（按 sessionId 组织）。
  *

package/src/config/PlatformPaths.ts

@@ -30,8 +30,12 @@ export function getPlatformRootDirPath(): string {
 
 /**
  * 返回平台级运行目录。
+ *
+ * 关键点（中文）
+ * - 当前仅供本模块内部拼接平台级派生路径使用。
+ * - 不再对外导出，避免暴露未被实际消费的路径 API。
  */
-export function getPlatformRuntimeDirPath(): string {
+function getPlatformRuntimeDirPath(): string {
   return path.join(getPlatformRootDirPath(), "main");
 }
 

package/src/executor/composer/system/default/assets/init/PROFILE.md.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/executor/composer/system/default/assets/init/PROFILE.md.ts.txt
-const TEXT_MODULE_CONTENT = "# 档案\n\n## 基本信息\n\n- 名字：`{{agent_name}}`\n- 身份：长期协作型助手\n- 关系：用户的合作者，不是用户的替身\n\n## 角色定位\n\n- 你负责理解目标、拆解问题、推动落地。\n\n## 身份边界\n\n- 可访问的信息不等于可传播的信息，隐私默认保密。\n- 坚持真实与可验证，不伪造结论、不编造事实。\n\n\n";
+const TEXT_MODULE_CONTENT = "# 档案\n\n## 基本信息\n\n- ID：`{{agent_id}}`\n- 身份：长期协作型助手\n- 关系：用户的合作者，不是用户的替身\n\n## 角色定位\n\n- 你负责理解目标、拆解问题、推动落地。\n\n## 身份边界\n\n- 可访问的信息不等于可传播的信息，隐私默认保密。\n- 坚持真实与可验证，不伪造结论、不编造事实。\n\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/executor/composer/system/default/assets/init/PROFILE.md.ts.txt

@@ -2,7 +2,7 @@
 
 ## 基本信息
 
-- 名字：`{{agent_name}}`
+- ID：`{{agent_id}}`
 - 身份：长期协作型助手
 - 关系：用户的合作者，不是用户的替身
 
@@ -15,4 +15,3 @@
 - 可访问的信息不等于可传播的信息，隐私默认保密。
 - 坚持真实与可验证，不伪造结论、不编造事实。
 
-

package/src/executor/tools/shell/ShellToolFormatting.ts

@@ -75,8 +75,8 @@ export function buildShellContextEnv(
 
   applyEnvMap(env, injected);
   setEnvString(env, "DC_SESSION_ID", contextCtx?.sessionId);
-  setEnvString(env, "DC_CTX_SERVER_HOST", process.env.DC_SERVER_HOST);
-  setEnvString(env, "DC_CTX_SERVER_PORT", process.env.DC_SERVER_PORT);
+  setEnvString(env, "DC_CITY_HOST", process.env.DC_CITY_HOST);
+  setEnvString(env, "DC_CITY_PORT", process.env.DC_CITY_PORT);
   stripInvocationAuthEnv(env);
 
   return env;

package/src/executor/types/SessionRun.ts

@@ -65,7 +65,7 @@ export type SessionAssistantStepCallback = (
  *
  * 关键点（中文）
  * - 这里直接复用 AI SDK 的 `UIMessageChunk` 结构，避免在 session 内核层再复制一套协议。
- * - SDK / HTTP / RPC 若需要自己的事件模型，应在更上层做映射。
+ * - SDK / HTTP 若需要自己的事件模型，应在更上层做映射。
  */
 export type SessionUiMessageChunk = UIMessageChunk;