@downcity/agent 1.1.35 → 1.1.51

package/bin/config/Paths.d.ts

@@ -6,7 +6,21 @@
  * - 与 SOUL 一起作为静态 prompt 入口。
  */
 export declare const PROFILE_MD_FILE_CANDIDATES: readonly ["PROFILE.md"];
+/**
+ * 返回项目主 `PROFILE.md` 的标准路径。
+ *
+ * 关键点（中文）
+ * - 当前始终返回候选列表中的第一优先级文件。
+ * - 调用方可把该路径视为初始化时默认写入位置。
+ */
 export declare function getProfileMdPath(cwd: string): string;
+/**
+ * 返回 `PROFILE.md` 的全部候选路径。
+ *
+ * 关键点（中文）
+ * - 便于后续扩展多候选命名时保持调用方逻辑不变。
+ * - 当前虽然只有一个候选值，仍统一暴露数组接口。
+ */
 export declare function getProfileMdCandidatePaths(cwd: string): string[];
 /**
  * SOUL.md 候选文件名（按优先级从高到低）。
@@ -16,24 +30,77 @@ export declare function getProfileMdCandidatePaths(cwd: string): string[];
  * - 统一由 Paths 模块暴露，避免调用方散落硬编码。
  */
 export declare const SOUL_MD_FILE_CANDIDATES: readonly ["SOUL.md"];
+/**
+ * 返回项目主 `SOUL.md` 的标准路径。
+ *
+ * 关键点（中文）
+ * - 当前始终返回候选列表中的第一优先级文件。
+ * - 与 `PROFILE.md` 一样，属于静态 system prompt 入口文件。
+ */
 export declare function getSoulMdPath(cwd: string): string;
+/**
+ * 返回 `SOUL.md` 的全部候选路径。
+ *
+ * 关键点（中文）
+ * - 供探测逻辑统一遍历候选文件名。
+ * - 保留数组形式便于后续新增兼容命名。
+ */
 export declare function getSoulMdCandidatePaths(cwd: string): string[];
+/**
+ * 返回项目主配置文件 `downcity.json` 的路径。
+ */
 export declare function getDowncityJsonPath(cwd: string): string;
+/**
+ * 返回项目运行时状态根目录 `.downcity` 的路径。
+ */
 export declare function getDowncityDirPath(cwd: string): string;
+/**
+ * 返回项目内 schema 快照文件路径。
+ *
+ * 关键点（中文）
+ * - 初始化流程会把本地 schema 副本写到这里，供编辑器联想与校验。
+ */
 export declare function getDowncitySchemaPath(cwd: string): string;
+/**
+ * 返回 `.downcity/config` 目录路径。
+ *
+ * 关键点（中文）
+ * - 用于存放项目级额外配置快照或未来扩展的辅助配置文件。
+ */
 export declare function getDowncityConfigDirPath(cwd: string): string;
+/**
+ * 返回项目日志目录路径。
+ */
 export declare function getLogsDirPath(cwd: string): string;
+/**
+ * 返回项目缓存目录路径。
+ *
+ * 关键点（中文）
+ * - 当前使用隐藏命名 `.cache`，避免与用户业务目录混淆。
+ */
 export declare function getCacheDirPath(cwd: string): string;
+/**
+ * 返回 profile 运行态目录路径。
+ *
+ * 关键点（中文）
+ * - 初始化流程会统一创建该目录，并在其中写入 profile 相关文件。
+ * - 单独保留目录级 API，避免调用方散落 `path.join(..., "profile")`。
+ */
 export declare function getDowncityProfileDirPath(cwd: string): string;
+/**
+ * 返回 profile 主记忆文件路径。
+ *
+ * 关键点（中文）
+ * - 该文件通常承载主画像或核心长期 profile 信息。
+ */
 export declare function getDowncityProfilePrimaryPath(cwd: string): string;
-export declare function getDowncityProfileOtherPath(cwd: string): string;
 /**
- * Memory 根目录（V2）。
+ * 返回 profile 补充记忆文件路径。
  *
  * 关键点（中文）
- * - `.downcity/memory` 为跨会话记忆目录。
+ * - 该文件用于存放不适合进入主 profile 的补充材料。
  */
-export declare function getDowncityMemoryDirPath(cwd: string): string;
+export declare function getDowncityProfileOtherPath(cwd: string): string;
 /**
  * 长期记忆文件路径（V2）。
  */
@@ -53,10 +120,27 @@ export declare function getDowncityMemoryDailyPath(cwd: string, date: string): s
  * - 调度任务属于项目 runtime 本地状态，因此放在项目 `.downcity/` 下。
  */
 export declare function getDowncityScheduleDbPath(cwd: string): string;
+/**
+ * 返回项目运行时数据目录路径。
+ */
 export declare function getDowncityDataDirPath(cwd: string): string;
+/**
+ * 返回项目内全部 agent 实例目录的根路径。
+ *
+ * 关键点（中文）
+ * - 单项目虽然通常只有一个 agent 入口，但底层仍按 agentId 分层组织。
+ */
 export declare function getDowncityAgentsRootDirPath(cwd: string): string;
-export declare function getDowncityAgentDirPath(cwd: string, agentId: string): string;
+/**
+ * 返回指定 agent 的 session 根目录路径。
+ */
 export declare function getDowncitySessionRootDirPath(cwd: string, agentId: string): string;
+/**
+ * 返回指定 session 的运行态目录路径。
+ *
+ * 关键点（中文）
+ * - `sessionId` 同样会做 URL 编码，保证路径可安全持久化。
+ */
 export declare function getDowncitySessionDirPath(cwd: string, agentId: string, sessionId: string): string;
 /**
  * Session Messages（会话消息，唯一事实源）。
@@ -66,21 +150,45 @@ export declare function getDowncitySessionDirPath(cwd: string, agentId: string,
  * - compact 会把被折叠的原始段写入 `messages/archive/*`（可审计）
  */
 export declare function getDowncitySessionMessagesDirPath(cwd: string, agentId: string, sessionId: string): string;
+/**
+ * 返回 session 消息事实源文件路径。
+ *
+ * 关键点（中文）
+ * - 当前唯一事实源是 `messages.jsonl`，所有历史组装都应基于它。
+ */
 export declare function getDowncitySessionMessagesPath(cwd: string, agentId: string, sessionId: string): string;
-export declare function getDowncitySessionHistoryMetaPath(cwd: string, agentId: string, sessionId: string): string;
+/**
+ * 返回 session 消息归档目录路径。
+ *
+ * 关键点（中文）
+ * - compaction 时被折叠的原始消息段会写入该目录，便于审计和回溯。
+ */
 export declare function getDowncitySessionMessagesArchiveDirPath(cwd: string, agentId: string, sessionId: string): string;
+/**
+ * 返回指定归档文件的完整路径。
+ *
+ * 关键点（中文）
+ * - `archiveId` 会做 URL 编码，避免 compaction 生成的标识污染文件名。
+ */
 export declare function getDowncitySessionMessagesArchivePath(cwd: string, agentId: string, sessionId: string, archiveId: string): string;
+/**
+ * 返回项目公开静态资源目录路径。
+ */
 export declare function getDowncityPublicDirPath(cwd: string): string;
+/**
+ * 返回项目任务目录路径。
+ *
+ * 关键点（中文）
+ * - 该目录用于存放任务相关的本地文件与运行时数据。
+ */
 export declare function getDowncityTasksDirPath(cwd: string): string;
-export declare function getDowncityDebugDirPath(cwd: string): string;
 /**
- * Chat 元信息目录（由 chat plugin runtime 维护）。
+ * 返回项目调试目录路径。
  *
  * 关键点（中文）
- * - 该目录存放 `sessionId -> chat` 的最近映射快照
- * - 与 core session messages 分离，避免把平台路由细节耦合进 core
+ * - 当前使用隐藏目录 `.debug`，避免与用户显式业务目录冲突。
  */
-export declare function getDowncityChatDirPath(cwd: string): string;
+export declare function getDowncityDebugDirPath(cwd: string): string;
 /**
  * Channel 目录（channel -> sessionId 映射）。
  *
@@ -96,8 +204,6 @@ export declare function getDowncityChannelDirPath(cwd: string): string;
  * - 采用单文件 JSON（`meta.json`）存储映射表与最近路由信息。
  */
 export declare function getDowncityChannelMetaPath(cwd: string): string;
-export declare function getDowncityChatMetaDirPath(cwd: string): string;
-export declare function getDowncityChatMetaPath(cwd: string, sessionId: string): string;
 /**
  * Chat 会话目录（按 sessionId 组织）。
  *

package/bin/config/Paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Paths.d.ts","sourceRoot":"","sources":["../../src/config/Paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Paths.d.ts","sourceRoot":"","sources":["../../src/config/Paths.ts"],"names":[],"mappings":"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"}

package/bin/config/Paths.js

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

package/bin/config/Paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"Paths.js","sourceRoot":"","sources":["../../src/config/Paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Paths.js","sourceRoot":"","sources":["../../src/config/Paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,YAAY,CAAU,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,SAAS,CAAU,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,OAAO,uBAAuB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,sBAAsB,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAW;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAW;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAW;IACrD,OAAO,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,wBAAwB,CAAC,GAAW;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAW;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAW;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW,EAAE,IAAY;IAClE,MAAM,QAAQ,GAAG,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,cAAc,KAAK,CAAC;IACrE,OAAO,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAC,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,GAAW;IACtD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,uBAAuB,CAAC,GAAW,EAAE,OAAe;IAC3D,OAAO,IAAI,CAAC,IAAI,CACd,4BAA4B,CAAC,GAAG,CAAC,EACjC,kBAAkB,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CACjD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAC3C,GAAW,EACX,OAAe;IAEf,OAAO,IAAI,CAAC,IAAI,CAAC,uBAAuB,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,GAAW,EACX,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,6BAA6B,CAAC,GAAG,EAAE,OAAO,CAAC,EAC3C,kBAAkB,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CACnD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iCAAiC,CAC/C,GAAW,EACX,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC;AACnF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAC5C,GAAW,EACX,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,EAC1D,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wCAAwC,CACtD,GAAW,EACX,OAAe,EACf,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,iCAAiC,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,EAC1D,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qCAAqC,CACnD,GAAW,EACX,OAAe,EACf,SAAiB,EACjB,SAAiB;IAEjB,OAAO,IAAI,CAAC,IAAI,CACd,wCAAwC,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,EACjE,GAAG,kBAAkB,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAC7D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAW;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,sBAAsB,CAAC,GAAW;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,OAAO,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAW,EAAE,SAAiB;IAC1E,OAAO,IAAI,CAAC,IAAI,CACd,sBAAsB,CAAC,GAAG,CAAC,EAC3B,kBAAkB,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CACnD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAW,EAAE,SAAiB;IACvE,OAAO,IAAI,CAAC,IAAI,CAAC,6BAA6B,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC;AACnF,CAAC"}

package/bin/config/PlatformPaths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 平台级全局路径规则。
+ *
+ * 职责说明（中文）
+ * - 统一描述用户级 `~/.downcity` 根目录及其关键子路径。
+ * - 让 `agent` 在不依赖 `city` 实现细节的前提下，也能复用同一套默认全局存储位置。
+ *
+ * 边界说明（中文）
+ * - 这里只定义“路径约定”，不负责任何数据库、密钥或业务读写逻辑。
+ * - 如需更换根目录，只能通过 `DC_PLATFORM_ROOT` 环境变量覆盖。
+ */
+/**
+ * 返回 Downcity 平台级全局根目录。
+ *
+ * 关键点（中文）
+ * - 默认固定为 `~/.downcity`。
+ * - 测试或隔离运行场景可通过 `DC_PLATFORM_ROOT` 覆盖。
+ */
+export declare function getPlatformRootDirPath(): string;
+/**
+ * 返回平台级全局 SQLite 数据库路径。
+ */
+export declare function getPlatformStoreDbPath(): string;
+/**
+ * 返回平台级数据库密钥文件路径。
+ *
+ * 关键点（中文）
+ * - 这里沿用现有 `city` 的默认密钥位置，保证账号密钥读写格式一致。
+ */
+export declare function getPlatformStoreKeyPath(): string;
+//# sourceMappingURL=PlatformPaths.d.ts.map

package/bin/config/PlatformPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformPaths.d.ts","sourceRoot":"","sources":["../../src/config/PlatformPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAM/C;AAaD;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD"}

package/bin/config/PlatformPaths.js

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

package/bin/config/PlatformPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformPaths.js","sourceRoot":"","sources":["../../src/config/PlatformPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvE,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,yBAAyB;IAChC,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,MAAM,CAAC,CAAC;AACrD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,aAAa,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,cAAc,CAAC,CAAC;AAChE,CAAC"}

package/bin/executor/Executor.js

@@ -519,7 +519,7 @@ export class Executor {
     resolveModelOrThrow() {
         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.`);
+            throw new Error(`Executor for session "${this.sessionId}" requires a configured model. Pass model to new Agent({ model }) or call session.set({ model }) before execution.`);
         }
         return model;
     }