@downcity/agent 1.1.35 → 1.1.51

package/src/config/DowncitySchema.ts

@@ -1,5 +1,23 @@
+/**
+ * `downcity.json` Schema 定义模块。
+ *
+ * 职责说明（中文）
+ * - 提供项目初始化时写入本地的 JSON Schema 常量。
+ * - 统一维护用户可编辑配置的结构约束、字段说明与编辑器联想元数据。
+ *
+ * 边界说明（中文）
+ * - 这里是静态 schema 常量，不负责运行时配置装配或业务校验逻辑。
+ * - 当 schema 与运行时实现存在差异时，应同时更新配置解析与用户文档。
+ */
 import type { JsonObject } from "@/types/common/Json.js";
 
+/**
+ * `downcity.json` 的本地 Schema 常量。
+ *
+ * 关键点（中文）
+ * - 初始化流程会把该常量写入 `.downcity/schema/downcity.schema.json`。
+ * - 该结构主要面向 IDE 校验与用户编辑体验，不替代运行时断言。
+ */
 export const DOWNCITY_JSON_SCHEMA: JsonObject = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
   $id: "https://downcity.ai/schemas/downcity.schema.json",
@@ -12,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,
@@ -29,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",
@@ -256,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: {
@@ -351,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/EnvFile.ts

@@ -0,0 +1,99 @@
+/**
+ * Agent 配置域 Env 文件工具模块。
+ *
+ * 职责说明（中文）
+ * - 负责 `.env` / `.env.example` 这类项目配置文件的轻量解析与补齐。
+ * - 服务于 agent 项目初始化与配置维护流程，避免把文本拼接逻辑散落到业务模块。
+ *
+ * 边界说明（中文）
+ * - 这里只处理配置文件文本结构，不负责把值注入运行时 `process.env`。
+ * - 当前能力以 agent 项目配置场景为中心，不追求成为通用 shell env 解析库。
+ */
+
+import fs from "fs-extra";
+import type { EnvFileEntry } from "@/types/common/EnvFile.js";
+import { escapeRegExp } from "@/utils/string/EscapeRegExp.js";
+
+/**
+ * 解析 Env 文本中已经声明的变量键名集合。
+ *
+ * 关键点（中文）
+ * - 会忽略空行与注释行。
+ * - 仅识别 `KEY=value` 的基础形式，足够覆盖当前 agent 配置初始化流程。
+ */
+export function parseEnvKeys(content: string): Set<string> {
+  const out = new Set<string>();
+  for (const rawLine of String(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;
+}
+
+/**
+ * 仅在目标文件缺失指定键时追加 Env 条目。
+ *
+ * 关键点（中文）
+ * - 已存在的键默认保持不变，只有显式列入 `overwriteKeys` 才会覆写。
+ * - 当目标文件原本为空时，会自动补一行总标题注释，便于用户识别来源。
+ * - `entries` 中的空键名会被自动忽略，避免写入无效行。
+ * - 该函数默认服务项目初始化阶段，因此输出格式偏向“可读、可手改”。
+ */
+export async function appendMissingEnvEntries(
+  filePath: string,
+  sectionTitle: string,
+  entries: EnvFileEntry[],
+  overwriteKeys?: Set<string>,
+): Promise<void> {
+  const normalizedFilePath = String(filePath || "").trim();
+  if (!normalizedFilePath) return;
+
+  const normalizedEntries = Array.isArray(entries)
+    ? entries.filter((item) => Boolean(String(item?.key || "").trim()))
+    : [];
+  const writableOverwriteKeys = overwriteKeys || new Set<string>();
+
+  let existing = "";
+  if (await fs.pathExists(normalizedFilePath)) {
+    existing = await fs.readFile(normalizedFilePath, "utf-8");
+  }
+
+  const existingKeys = parseEnvKeys(existing);
+  let nextContent = existing;
+  const appendedEntries: EnvFileEntry[] = [];
+
+  for (const entry of normalizedEntries) {
+    if (!existingKeys.has(entry.key)) {
+      appendedEntries.push(entry);
+      continue;
+    }
+    if (!writableOverwriteKeys.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("", `# ${String(sectionTitle || "").trim()}`);
+    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(normalizedFilePath))) {
+    await fs.writeFile(normalizedFilePath, nextContent, "utf-8");
+  }
+}

package/src/config/ExecutionBinding.ts

@@ -1,10 +1,14 @@
 /**
- * ExecutionBinding：项目执行绑定解析与校验。
+ * 项目执行绑定解析与校验模块。
  *
- * 关键点（中文）
- * - 项目只有一条执行路径：`execution.type = "api"`。
- * - 所有 create / start / runtime 读写都通过这里统一解析。
- * - 避免解析逻辑散落在多个模块中。
+ * 职责说明（中文）
+ * - 统一负责从 `downcity.json` 中读取 agent 的执行目标定义。
+ * - 负责提供最小的存在性判断、主模型读取与错误断言，避免调用方重复解析结构。
+ * - 让初始化、配置装配、运行时启动都复用同一套执行目标解释规则。
+ *
+ * 边界说明（中文）
+ * - 这里只解析配置结构，不负责验证模型是否真实存在于平台模型池中。
+ * - 当前只接受 agent 包已经落地支持的执行绑定格式。
  */
 
 import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
@@ -12,6 +16,10 @@ import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js"
 
 /**
  * 读取项目执行绑定。
+ *
+ * 关键点（中文）
+ * - 当前只接受 `execution.type = "api"` 且存在非空 `modelId` 的配置。
+ * - 若结构不满足最小要求，则返回 `null`，由调用方决定是兜底还是报错。
  */
 export function readProjectExecutionBinding(
   config: DowncityConfig,
@@ -27,26 +35,15 @@ 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;
-}
-
 /**
  * 断言项目已经声明执行目标。
+ *
+ * 关键点（中文）
+ * - 适合在配置加载完成后的早期阶段调用，尽早暴露缺失执行目标的问题。
+ * - 失败时抛出稳定错误文案，便于 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/Gitignore.ts

@@ -0,0 +1,52 @@
+/**
+ * Agent 配置域 `.gitignore` 维护模块。
+ *
+ * 职责说明（中文）
+ * - 负责在 agent 项目初始化阶段把必要的忽略规则补进 `.gitignore`。
+ * - 让项目配置与运行时状态目录的忽略策略留在 `config/` 语义域内统一维护。
+ *
+ * 边界说明（中文）
+ * - 这里只做最小化补丁写入，不负责 `.gitignore` 的复杂排序、分组或格式整理。
+ * - 当前主要服务项目初始化流程，不追求抽象成通用 Git 文本编辑器。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+
+/**
+ * 确保 `.gitignore` 中存在指定规则。
+ *
+ * 关键点（中文）
+ * - 只会在末尾追加缺失规则，不会重排用户已有内容。
+ * - 返回值用于告诉调用方本次是新建、更新还是无需修改。
+ * - 设计目标是“尽量少打扰用户已有文件结构”。
+ */
+export async function ensureGitignoreEntry(
+  projectRoot: string,
+  entry: string,
+): Promise<"created" | "updated" | "unchanged"> {
+  const normalizedProjectRoot = path.resolve(String(projectRoot || "").trim() || ".");
+  const normalizedEntry = String(entry || "").trim();
+  if (!normalizedEntry) return "unchanged";
+
+  const gitignorePath = path.join(normalizedProjectRoot, ".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(normalizedEntry)) {
+    return "unchanged";
+  }
+
+  const chunks = existingContent ? [existingContent] : [];
+  if (existingContent && !existingContent.endsWith("\n")) {
+    chunks.push("\n");
+  }
+  chunks.push(`${normalizedEntry}\n`);
+  await fs.writeFile(gitignorePath, chunks.join(""), "utf-8");
+  return hasGitignore ? "updated" : "created";
+}