@downcity/agent 1.1.35 → 1.1.51

package/src/config/Paths.ts

@@ -1,10 +1,14 @@
 /**
- * City Env Paths：项目与运行目录路径规则模块。
+ * Agent 项目路径规则模块。
  *
- * 关键点（中文）
- * - 统一管理单个 agent 项目内 `.downcity` 及其子目录/文件路径规则。
- * - 避免路径字符串在不同模块重复拼接，降低维护成本。
- * - 这里描述的是“项目级路径约定”，与 city 包中的全局运行态路径约定分开。
+ * 职责说明（中文）
+ * - 统一管理单个 agent 项目根目录下的静态文件、`.downcity` 目录与运行时状态文件路径。
+ * - 负责把“路径协议”集中到一个模块，避免各领域模块自行拼接字符串。
+ * - 为初始化、会话存储、聊天路由、调试文件等子系统提供一致的路径入口。
+ *
+ * 边界说明（中文）
+ * - 这里只负责路径计算，不负责目录创建、文件读写或存在性校验。
+ * - 这里描述的是单项目约定，不涉及平台级全局目录布局。
  */
 import path from "path";
 
@@ -17,10 +21,24 @@ import path from "path";
  */
 export const PROFILE_MD_FILE_CANDIDATES = ["PROFILE.md"] as const;
 
+/**
+ * 返回项目主 `PROFILE.md` 的标准路径。
+ *
+ * 关键点（中文）
+ * - 当前始终返回候选列表中的第一优先级文件。
+ * - 调用方可把该路径视为初始化时默认写入位置。
+ */
 export function getProfileMdPath(cwd: string): string {
   return path.join(cwd, PROFILE_MD_FILE_CANDIDATES[0]);
 }
 
+/**
+ * 返回 `PROFILE.md` 的全部候选路径。
+ *
+ * 关键点（中文）
+ * - 便于后续扩展多候选命名时保持调用方逻辑不变。
+ * - 当前虽然只有一个候选值，仍统一暴露数组接口。
+ */
 export function getProfileMdCandidatePaths(cwd: string): string[] {
   return PROFILE_MD_FILE_CANDIDATES.map((filename) => path.join(cwd, filename));
 }
@@ -34,46 +52,106 @@ export function getProfileMdCandidatePaths(cwd: string): string[] {
  */
 export const SOUL_MD_FILE_CANDIDATES = ["SOUL.md"] as const;
 
+/**
+ * 返回项目主 `SOUL.md` 的标准路径。
+ *
+ * 关键点（中文）
+ * - 当前始终返回候选列表中的第一优先级文件。
+ * - 与 `PROFILE.md` 一样，属于静态 system prompt 入口文件。
+ */
 export function getSoulMdPath(cwd: string): string {
   return path.join(cwd, SOUL_MD_FILE_CANDIDATES[0]);
 }
 
+/**
+ * 返回 `SOUL.md` 的全部候选路径。
+ *
+ * 关键点（中文）
+ * - 供探测逻辑统一遍历候选文件名。
+ * - 保留数组形式便于后续新增兼容命名。
+ */
 export function getSoulMdCandidatePaths(cwd: string): string[] {
   return SOUL_MD_FILE_CANDIDATES.map((filename) => path.join(cwd, filename));
 }
 
+/**
+ * 返回项目主配置文件 `downcity.json` 的路径。
+ */
 export function getDowncityJsonPath(cwd: string): string {
   return path.join(cwd, "downcity.json");
 }
 
+/**
+ * 返回项目运行时状态根目录 `.downcity` 的路径。
+ */
 export function getDowncityDirPath(cwd: string): string {
   return path.join(cwd, ".downcity");
 }
 
+/**
+ * 返回项目内 schema 快照文件路径。
+ *
+ * 关键点（中文）
+ * - 初始化流程会把本地 schema 副本写到这里，供编辑器联想与校验。
+ */
 export function getDowncitySchemaPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "schema", "downcity.schema.json");
 }
 
+/**
+ * 返回 `.downcity/config` 目录路径。
+ *
+ * 关键点（中文）
+ * - 用于存放项目级额外配置快照或未来扩展的辅助配置文件。
+ */
 export function getDowncityConfigDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "config");
 }
 
+/**
+ * 返回项目日志目录路径。
+ */
 export function getLogsDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "logs");
 }
 
+/**
+ * 返回项目缓存目录路径。
+ *
+ * 关键点（中文）
+ * - 当前使用隐藏命名 `.cache`，避免与用户业务目录混淆。
+ */
 export function getCacheDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), ".cache");
 }
 
+/**
+ * 返回 profile 运行态目录路径。
+ *
+ * 关键点（中文）
+ * - 初始化流程会统一创建该目录，并在其中写入 profile 相关文件。
+ * - 单独保留目录级 API，避免调用方散落 `path.join(..., "profile")`。
+ */
 export function getDowncityProfileDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "profile");
 }
 
+/**
+ * 返回 profile 主记忆文件路径。
+ *
+ * 关键点（中文）
+ * - 该文件通常承载主画像或核心长期 profile 信息。
+ */
 export function getDowncityProfilePrimaryPath(cwd: string): string {
   return path.join(getDowncityProfileDirPath(cwd), "Primary.md");
 }
 
+/**
+ * 返回 profile 补充记忆文件路径。
+ *
+ * 关键点（中文）
+ * - 该文件用于存放不适合进入主 profile 的补充材料。
+ */
 export function getDowncityProfileOtherPath(cwd: string): string {
   return path.join(getDowncityProfileDirPath(cwd), "other.md");
 }
@@ -83,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");
 }
 
@@ -120,21 +199,40 @@ export function getDowncityScheduleDbPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "schedule.jsonl");
 }
 
+/**
+ * 返回项目运行时数据目录路径。
+ */
 export function getDowncityDataDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "data");
 }
 
+/**
+ * 返回项目内全部 agent 实例目录的根路径。
+ *
+ * 关键点（中文）
+ * - 单项目虽然通常只有一个 agent 入口，但底层仍按 agentId 分层组织。
+ */
 export function getDowncityAgentsRootDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "agents");
 }
 
-export function getDowncityAgentDirPath(cwd: string, agentId: string): string {
+/**
+ * 返回指定 agent 的运行态目录路径。
+ *
+ * 关键点（中文）
+ * - `agentId` 会做 URL 编码，避免特殊字符污染文件系统结构。
+ * - 当前仅供本模块内部拼接 session 根目录使用。
+ */
+function getDowncityAgentDirPath(cwd: string, agentId: string): string {
   return path.join(
     getDowncityAgentsRootDirPath(cwd),
     encodeURIComponent(String(agentId || "").trim()),
   );
 }
 
+/**
+ * 返回指定 agent 的 session 根目录路径。
+ */
 export function getDowncitySessionRootDirPath(
   cwd: string,
   agentId: string,
@@ -142,6 +240,12 @@ export function getDowncitySessionRootDirPath(
   return path.join(getDowncityAgentDirPath(cwd, agentId), "sessions");
 }
 
+/**
+ * 返回指定 session 的运行态目录路径。
+ *
+ * 关键点（中文）
+ * - `sessionId` 同样会做 URL 编码，保证路径可安全持久化。
+ */
 export function getDowncitySessionDirPath(
   cwd: string,
   agentId: string,
@@ -168,6 +272,12 @@ export function getDowncitySessionMessagesDirPath(
   return path.join(getDowncitySessionDirPath(cwd, agentId, sessionId), "messages");
 }
 
+/**
+ * 返回 session 消息事实源文件路径。
+ *
+ * 关键点（中文）
+ * - 当前唯一事实源是 `messages.jsonl`，所有历史组装都应基于它。
+ */
 export function getDowncitySessionMessagesPath(
   cwd: string,
   agentId: string,
@@ -179,17 +289,12 @@ export function getDowncitySessionMessagesPath(
   );
 }
 
-export function getDowncitySessionHistoryMetaPath(
-  cwd: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getDowncitySessionMessagesDirPath(cwd, agentId, sessionId),
-    "meta.json",
-  );
-}
-
+/**
+ * 返回 session 消息归档目录路径。
+ *
+ * 关键点（中文）
+ * - compaction 时被折叠的原始消息段会写入该目录，便于审计和回溯。
+ */
 export function getDowncitySessionMessagesArchiveDirPath(
   cwd: string,
   agentId: string,
@@ -201,6 +306,12 @@ export function getDowncitySessionMessagesArchiveDirPath(
   );
 }
 
+/**
+ * 返回指定归档文件的完整路径。
+ *
+ * 关键点（中文）
+ * - `archiveId` 会做 URL 编码，避免 compaction 生成的标识污染文件名。
+ */
 export function getDowncitySessionMessagesArchivePath(
   cwd: string,
   agentId: string,
@@ -213,14 +324,29 @@ export function getDowncitySessionMessagesArchivePath(
   );
 }
 
+/**
+ * 返回项目公开静态资源目录路径。
+ */
 export function getDowncityPublicDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "public");
 }
 
+/**
+ * 返回项目任务目录路径。
+ *
+ * 关键点（中文）
+ * - 该目录用于存放任务相关的本地文件与运行时数据。
+ */
 export function getDowncityTasksDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), "task");
 }
 
+/**
+ * 返回项目调试目录路径。
+ *
+ * 关键点（中文）
+ * - 当前使用隐藏目录 `.debug`，避免与用户显式业务目录冲突。
+ */
 export function getDowncityDebugDirPath(cwd: string): string {
   return path.join(getDowncityDirPath(cwd), ".debug");
 }
@@ -231,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");
 }
 
@@ -257,17 +384,6 @@ export function getDowncityChannelMetaPath(cwd: string): string {
   return path.join(getDowncityChannelDirPath(cwd), "meta.json");
 }
 
-export function getDowncityChatMetaDirPath(cwd: string): string {
-  return path.join(getDowncityChatDirPath(cwd), "meta");
-}
-
-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

@@ -0,0 +1,57 @@
+/**
+ * 平台级全局路径规则。
+ *
+ * 职责说明（中文）
+ * - 统一描述用户级 `~/.downcity` 根目录及其关键子路径。
+ * - 让 `agent` 在不依赖 `city` 实现细节的前提下，也能复用同一套默认全局存储位置。
+ *
+ * 边界说明（中文）
+ * - 这里只定义“路径约定”，不负责任何数据库、密钥或业务读写逻辑。
+ * - 如需更换根目录，只能通过 `DC_PLATFORM_ROOT` 环境变量覆盖。
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * 返回 Downcity 平台级全局根目录。
+ *
+ * 关键点（中文）
+ * - 默认固定为 `~/.downcity`。
+ * - 测试或隔离运行场景可通过 `DC_PLATFORM_ROOT` 覆盖。
+ */
+export function getPlatformRootDirPath(): string {
+  const explicitRoot = String(process.env.DC_PLATFORM_ROOT || "").trim();
+  if (explicitRoot) {
+    return path.resolve(explicitRoot);
+  }
+  return path.join(os.homedir(), ".downcity");
+}
+
+/**
+ * 返回平台级运行目录。
+ *
+ * 关键点（中文）
+ * - 当前仅供本模块内部拼接平台级派生路径使用。
+ * - 不再对外导出，避免暴露未被实际消费的路径 API。
+ */
+function getPlatformRuntimeDirPath(): string {
+  return path.join(getPlatformRootDirPath(), "main");
+}
+
+/**
+ * 返回平台级全局 SQLite 数据库路径。
+ */
+export function getPlatformStoreDbPath(): string {
+  return path.join(getPlatformRootDirPath(), "downcity.db");
+}
+
+/**
+ * 返回平台级数据库密钥文件路径。
+ *
+ * 关键点（中文）
+ * - 这里沿用现有 `city` 的默认密钥位置，保证账号密钥读写格式一致。
+ */
+export function getPlatformStoreKeyPath(): string {
+  return path.join(getPlatformRuntimeDirPath(), "model-db.key");
+}

package/src/executor/Executor.ts

@@ -717,7 +717,7 @@ export class Executor implements SessionExecutor {
     const model = this.getModel();
     if (!model) {
       throw new Error(
-        `Executor for session "${this.sessionId}" requires a configured model. Pass model to new Agent({ model }), call session.set({ model }), or let the host configure the session before execution.`,
+        `Executor for session "${this.sessionId}" requires a configured model. Pass model to new Agent({ model }) or call session.set({ model }) before execution.`,
       );
     }
     return model;

package/src/executor/composer/system/default/DefaultSessionSystemComposer.ts

@@ -10,7 +10,7 @@ import type {
   SessionSystemComposer,
 } from "@executor/composer/system/SessionSystemComposer.js";
 import { getSessionRunScope } from "@executor/SessionRunScope.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import {
   resolveSessionSystemMessages,
   type SystemProfile,

package/src/executor/composer/system/default/SystemDomain.ts

@@ -9,9 +9,7 @@
 import type { SystemModelMessage } from "ai";
 import { transformPromptsIntoSystemMessages } from "@executor/composer/system/default/PromptRenderer.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
-import { listLocalPlugins } from "@/plugin/core/PluginClassRegistry.js";
-import { PLUGIN_SYSTEM_PROVIDERS } from "@/plugin/core/PluginSystemProviders.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import { buildRuntimeClockSystemPrompt } from "@executor/composer/system/default/variables/VariableReplacer.js";
 import {
   CORE_SYSTEM_PROMPT,
@@ -175,9 +173,15 @@ export async function loadManagedPluginSystemPrompts(input: {
       .filter(Boolean),
   );
 
-  for (const plugin of PLUGIN_SYSTEM_PROVIDERS) {
+  for (const plugin of input.context.agent.pluginInstances.values()) {
     if (disabledPluginNames.has(plugin.name)) continue;
+    if (typeof plugin.system !== "function") continue;
     try {
+      if (!isPluginEnabled({ plugin, context: input.context })) continue;
+      if (typeof plugin.availability === "function") {
+        const availability = await plugin.availability(input.context);
+        if (!availability.available) continue;
+      }
       const text = normalizeSystemText(await plugin.system(input.context));
       if (!text) continue;
       out.push(text);
@@ -203,32 +207,8 @@ export async function loadLocalPluginSystemPrompts(input: {
    */
   context: AgentContext;
 }): Promise<string[]> {
-  const out: string[] = [];
-
-  for (const plugin of listLocalPlugins()) {
-    if (typeof plugin.system !== "function") continue;
-    try {
-      if (
-        !isPluginEnabled({
-          plugin,
-          context: input.context,
-        })
-      ) {
-        continue;
-      }
-      if (typeof plugin.availability === "function") {
-        const availability = await plugin.availability(input.context);
-        if (!availability.available) continue;
-      }
-      const text = normalizeSystemText(await plugin.system(input.context));
-      if (!text) continue;
-      out.push(text);
-    } catch {
-      // fail-open
-    }
-  }
-
-  return out;
+  void input;
+  return [];
 }
 
 /**

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/composer/system/default/assets/plugin.prompt.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/executor/composer/system/default/assets/plugin.prompt.ts.txt
-const TEXT_MODULE_CONTENT = "# Plugin State\n\n你正在一个基于 plugin 的执行环境中工作。\n\n## 可用命令总览\n- plugin 状态管理（统一使用 `city plugin`）：\n  - `city plugin list`\n  - `city plugin status <pluginName>`\n  - `city plugin start <pluginName>`\n  - `city plugin stop <pluginName>`\n  - `city plugin restart <pluginName>`\n  - `city plugin command <pluginName> <command> [--payload '<json>']`\n  - `city plugin schedule list`\n  - `city plugin schedule info <jobId>`\n  - `city plugin schedule cancel <jobId>`\n- 当前内建托管 plugin：`shell` / `chat` / `task` / `memory` / `contact` / `schedule`。\n- 当前内建本地 plugin：`auth` / `skill` / `asr` / `tts`。\n- 模块级 action 命令：\n  - `city shell <action> ...`\n  - `city chat <action> ...`\n  - `city task <action> ...`\n  - `city memory <action> ...`\n  - `city plugin action <plugin> <action> ...`\n  - `city skill <action> ...`\n  - `city asr <action> ...`\n  - `city tts <action> ...`\n\n具体 plugin 的执行参考对应文档。\n";
+const TEXT_MODULE_CONTENT = "# Plugin State\n\n你正在一个基于 plugin 的执行环境中工作。\n\n## 可用命令总览\n- plugin 状态管理（统一使用 `city plugin`）：\n  - `city plugin list`\n  - `city plugin status <pluginName>`\n  - `city plugin start <pluginName>`\n  - `city plugin stop <pluginName>`\n  - `city plugin restart <pluginName>`\n  - `city plugin command <pluginName> <command> [--payload '<json>']`\n  - `city plugin schedule list`\n  - `city plugin schedule info <jobId>`\n  - `city plugin schedule cancel <jobId>`\n- ActionSchedule 管理命令用于查看/取消延迟执行的 plugin action，不是独立 plugin。\n- 当前内建托管 plugin：`shell` / `chat` / `task` / `memory` / `contact`。\n- 当前内建本地 plugin：`auth` / `skill` / `asr` / `tts`。\n- 模块级 action 命令：\n  - `city shell <action> ...`\n  - `city chat <action> ...`\n  - `city task <action> ...`\n  - `city memory <action> ...`\n  - `city plugin action <plugin> <action> ...`\n  - `city skill <action> ...`\n  - `city asr <action> ...`\n  - `city tts <action> ...`\n\n具体 plugin 的执行参考对应文档。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/executor/composer/system/default/assets/plugin.prompt.ts.txt

@@ -13,7 +13,8 @@
   - `city plugin schedule list`
   - `city plugin schedule info <jobId>`
   - `city plugin schedule cancel <jobId>`
-- 当前内建托管 plugin：`shell` / `chat` / `task` / `memory` / `contact` / `schedule`。
+- ActionSchedule 管理命令用于查看/取消延迟执行的 plugin action，不是独立 plugin。
+- 当前内建托管 plugin：`shell` / `chat` / `task` / `memory` / `contact`。
 - 当前内建本地 plugin：`auth` / `skill` / `asr` / `tts`。
 - 模块级 action 命令：
   - `city shell <action> ...`

package/src/executor/messages/AssistantResultPersistence.ts

@@ -11,7 +11,7 @@ import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import {
   hasPersistedAssistantSteps,
   resolveAssistantMessageForPersistence,
-} from "@/plugin/builtins/chat/runtime/UserVisibleText.js";
+} from "@/executor/messages/UserVisibleText.js";
 
 /**
  * assistant 写入端口。