@downcity/agent 1.1.287 → 1.1.310

package/bin/utils/string/EscapeRegExp.js.map

@@ -1 +1 @@
-{"version":3,"file":"EscapeRegExp.js","sourceRoot":"","sources":["../../../src/utils/string/EscapeRegExp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC"}
+{"version":3,"file":"EscapeRegExp.js","sourceRoot":"","sources":["../../../src/utils/string/EscapeRegExp.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC"}

package/bin/workspace/LocalFileSystem.d.ts

@@ -0,0 +1,44 @@
+/**
+ * LocalFileSystem：基于 Node.js 的本地 Workspace 文件能力。
+ *
+ * 职责说明（中文）
+ * - 为 File/Search Tool 提供单一 rooted 文件边界。
+ * - 复用统一路径策略、原子写入、符号链接校验与有界搜索实现。
+ * - 不执行任意 Shell 命令，也不感知 Agent、Session 或 Store。
+ */
+import type { FileSystem, WorkspaceDirectoryEntry } from "../types/workspace/FileSystem.js";
+import type { FileToolActionRequest, FileToolActionResult } from "../types/workspace/FileTool.js";
+import type { SearchToolActionRequest, SearchToolActionResult } from "../types/workspace/SearchTool.js";
+/** Node.js 本地文件系统实现。 */
+export declare class LocalFileSystem implements FileSystem {
+    /** 已解析且不可变的项目根目录。 */
+    readonly root_path: string;
+    constructor(root_path: string);
+    /** 将相对路径安全解析到当前 Workspace 根目录。 */
+    resolve_path(...segments: string[]): string;
+    /** 判断 Workspace 路径是否存在。 */
+    path_exists(file_path: string): Promise<boolean>;
+    /** 读取 Workspace 文件的完整字节内容。 */
+    read_file(file_path: string): Promise<Buffer>;
+    /** 读取普通文件的字节大小。 */
+    file_size(file_path: string): Promise<number>;
+    /** 创建目录及缺失的父目录。 */
+    ensure_directory(directory_path: string): Promise<void>;
+    /** 递归删除文件或目录；不存在时保持幂等。 */
+    remove_path(target_path: string): Promise<void>;
+    /** 使用同一 Workspace 文件系统内的 rename 原子移动路径。 */
+    move_path(source_path: string, target_path: string): Promise<void>;
+    /** 返回目录直接子项的最小稳定结构。 */
+    read_directory(directory_path: string): Promise<WorkspaceDirectoryEntry[]>;
+    /** 使用同目录临时文件与 fsync 原子覆盖 Workspace 文件。 */
+    write_file_atomically(file_path: string, content: string | Buffer): Promise<void>;
+    /** 串行调用方可使用的文件追加能力。 */
+    append_file(file_path: string, content: string | Buffer): Promise<void>;
+    /** 使用跨进程锁文件串行执行 Workspace 文件事务。 */
+    with_file_lock<T>(lock_path: string, action: () => Promise<T>): Promise<T>;
+    /** 执行一次结构化文件操作。 */
+    run_file_action(request: FileToolActionRequest): Promise<FileToolActionResult>;
+    /** 执行一次结构化搜索操作。 */
+    run_search_action(request: SearchToolActionRequest): Promise<SearchToolActionResult>;
+}
+//# sourceMappingURL=LocalFileSystem.d.ts.map

package/bin/workspace/LocalFileSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalFileSystem.d.ts","sourceRoot":"","sources":["../../src/workspace/LocalFileSystem.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,uBAAuB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AA6BzC,wBAAwB;AACxB,qBAAa,eAAgB,YAAW,UAAU;IAChD,qBAAqB;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;IAI7B,kCAAkC;IAClC,YAAY,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM;IAa3C,2BAA2B;IACrB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD,8BAA8B;IACxB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD,mBAAmB;IACb,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAInD,mBAAmB;IACb,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D,0BAA0B;IACpB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,2CAA2C;IACrC,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxE,uBAAuB;IACjB,cAAc,CAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAWrC,0CAA0C;IACpC,qBAAqB,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC;IAchB,uBAAuB;IACjB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7E,mCAAmC;IAC7B,cAAc,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC;IA0Cb,mBAAmB;IACb,eAAe,CACnB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC;IAIhC,mBAAmB;IACb,iBAAiB,CACrB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC;CAGnC"}

package/bin/workspace/LocalFileSystem.js

@@ -0,0 +1,153 @@
+/**
+ * LocalFileSystem：基于 Node.js 的本地 Workspace 文件能力。
+ *
+ * 职责说明（中文）
+ * - 为 File/Search Tool 提供单一 rooted 文件边界。
+ * - 复用统一路径策略、原子写入、符号链接校验与有界搜索实现。
+ * - 不执行任意 Shell 命令，也不感知 Agent、Session 或 Store。
+ */
+import { run_file_action } from "../workspace/file/FileActionRuntime.js";
+import { run_search_action } from "../workspace/search/SearchActionRuntime.js";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { access, appendFile, mkdir, open, readFile, readdir, rename, rm, stat, } from "node:fs/promises";
+import { write_file_atomically } from "../workspace/file/FileAtomicWriter.js";
+const FILE_LOCK_STALE_MS = 120_000;
+const FILE_LOCK_TIMEOUT_MS = FILE_LOCK_STALE_MS * 2;
+const FILE_LOCK_RETRY_MS = 40;
+/** 等待指定毫秒数，避免争锁循环持续占用事件循环。 */
+async function wait_for_lock_retry() {
+    await new Promise((resolve) => {
+        setTimeout(resolve, FILE_LOCK_RETRY_MS);
+    });
+}
+/** Node.js 本地文件系统实现。 */
+export class LocalFileSystem {
+    /** 已解析且不可变的项目根目录。 */
+    root_path;
+    constructor(root_path) {
+        this.root_path = root_path;
+    }
+    /** 将相对路径安全解析到当前 Workspace 根目录。 */
+    resolve_path(...segments) {
+        const resolved_path = path.resolve(this.root_path, ...segments);
+        const relative_path = path.relative(this.root_path, resolved_path);
+        if (relative_path === ".." ||
+            relative_path.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative_path)) {
+            throw new Error(`Path escapes Workspace: ${segments.join(path.sep)}`);
+        }
+        return resolved_path;
+    }
+    /** 判断 Workspace 路径是否存在。 */
+    async path_exists(file_path) {
+        return await access(this.resolve_path(file_path))
+            .then(() => true)
+            .catch(() => false);
+    }
+    /** 读取 Workspace 文件的完整字节内容。 */
+    async read_file(file_path) {
+        return await readFile(this.resolve_path(file_path));
+    }
+    /** 读取普通文件的字节大小。 */
+    async file_size(file_path) {
+        return (await stat(this.resolve_path(file_path))).size;
+    }
+    /** 创建目录及缺失的父目录。 */
+    async ensure_directory(directory_path) {
+        await mkdir(this.resolve_path(directory_path), { recursive: true });
+    }
+    /** 递归删除文件或目录；不存在时保持幂等。 */
+    async remove_path(target_path) {
+        await rm(this.resolve_path(target_path), { recursive: true, force: true });
+    }
+    /** 使用同一 Workspace 文件系统内的 rename 原子移动路径。 */
+    async move_path(source_path, target_path) {
+        await rename(this.resolve_path(source_path), this.resolve_path(target_path));
+    }
+    /** 返回目录直接子项的最小稳定结构。 */
+    async read_directory(directory_path) {
+        const entries = await readdir(this.resolve_path(directory_path), {
+            withFileTypes: true,
+        });
+        return entries.map((entry) => ({
+            name: entry.name,
+            is_directory: entry.isDirectory(),
+            is_file: entry.isFile(),
+        }));
+    }
+    /** 使用同目录临时文件与 fsync 原子覆盖 Workspace 文件。 */
+    async write_file_atomically(file_path, content) {
+        const resolved_path = this.resolve_path(file_path);
+        await mkdir(path.dirname(resolved_path), { recursive: true });
+        const mode = await stat(resolved_path)
+            .then((value) => value.mode)
+            .catch(() => undefined);
+        await write_file_atomically({
+            file_path: resolved_path,
+            content: Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8"),
+            overwrite: true,
+            ...(typeof mode === "number" ? { mode } : {}),
+        });
+    }
+    /** 串行调用方可使用的文件追加能力。 */
+    async append_file(file_path, content) {
+        const resolved_path = this.resolve_path(file_path);
+        await mkdir(path.dirname(resolved_path), { recursive: true });
+        await appendFile(resolved_path, Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8"));
+    }
+    /** 使用跨进程锁文件串行执行 Workspace 文件事务。 */
+    async with_file_lock(lock_path, action) {
+        const resolved_lock_path = this.resolve_path(lock_path);
+        await mkdir(path.dirname(resolved_lock_path), { recursive: true });
+        const token = `${process.pid}:${Date.now()}:${randomUUID()}`;
+        const started_at = Date.now();
+        while (true) {
+            try {
+                const lock_file = await open(resolved_lock_path, "wx");
+                await lock_file.writeFile(token, "utf8");
+                await lock_file.close();
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                try {
+                    const lock_stat = await stat(resolved_lock_path);
+                    if (Date.now() - lock_stat.mtimeMs > FILE_LOCK_STALE_MS) {
+                        await rm(resolved_lock_path, { force: true });
+                    }
+                }
+                catch {
+                    // 锁可能已由持有者释放，下一轮直接重新竞争。
+                }
+                if (Date.now() - started_at > FILE_LOCK_TIMEOUT_MS) {
+                    throw new Error(`Workspace file lock timeout: ${resolved_lock_path}`);
+                }
+                await wait_for_lock_retry();
+            }
+        }
+        try {
+            return await action();
+        }
+        finally {
+            try {
+                if ((await readFile(resolved_lock_path, "utf8")).trim() === token) {
+                    await rm(resolved_lock_path, { force: true });
+                }
+            }
+            catch {
+                // 锁已被清理时无需再次处理。
+            }
+        }
+    }
+    /** 执行一次结构化文件操作。 */
+    async run_file_action(request) {
+        return await run_file_action({ rootPath: this.root_path }, request);
+    }
+    /** 执行一次结构化搜索操作。 */
+    async run_search_action(request) {
+        return await run_search_action({ rootPath: this.root_path }, request);
+    }
+}
+//# sourceMappingURL=LocalFileSystem.js.map

package/bin/workspace/LocalFileSystem.js.map

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

package/bin/workspace/Workspace.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Workspace：本地项目资源与安全作用域。
+ *
+ * 职责说明（中文）
+ * - 只解析一次项目根目录，并将 Store、Tool 与可选 Shell 绑定到同一资源容器。
+ * - AgentStore 与 WorkspaceTools 共用同一个 FileSystem 和目录访问范围。
+ * - 每个 Workspace 实例只绑定一个 Agent；同一物理目录可创建多个独立实例。
+ */
+import type { FileSystem } from "../types/workspace/FileSystem.js";
+import type { WorkspaceOptions } from "../types/workspace/Workspace.js";
+import type { AgentStore } from "../types/store/AgentStore.js";
+import type { WorkspaceTools } from "../types/workspace/WorkspaceTools.js";
+import type { WorkspaceEnvPatch, WorkspaceEnvSubscriber, WorkspaceEnvUnsubscribe } from "../types/workspace/WorkspaceEnv.js";
+/** 本地 Workspace。 */
+export declare class Workspace {
+    /** 已解析且不可变的项目根目录。 */
+    readonly path: string;
+    /** Workspace 根目录内统一的受控文件与搜索能力。 */
+    readonly files: FileSystem;
+    /** Workspace 内可用的文件、搜索与可选命令工具。 */
+    readonly tools: WorkspaceTools;
+    /** Workspace 内可选的受控命令执行能力。 */
+    readonly shell?: WorkspaceOptions["shell"];
+    /** Workspace 首次释放产生的稳定 Promise，保证重复释放不会重复关闭资源。 */
+    private dispose_promise?;
+    /** 当前 Workspace 已绑定的 Agent 标识；未绑定时为空。 */
+    private bound_agent_id?;
+    /** 当前 Workspace 为唯一 Agent 创建的结构化 Store。 */
+    private bound_store?;
+    /** 当前 Workspace configured env 的唯一可变状态。 */
+    private readonly env;
+    /** Workspace env 变化订阅器。 */
+    private readonly env_subscribers;
+    constructor(options: WorkspaceOptions);
+    /** 返回当前 Workspace env 的浅拷贝快照。 */
+    get_env(): Record<string, string>;
+    /** 整体覆盖 Workspace env，并通知已绑定的 Agent。 */
+    set_env(next: WorkspaceEnvPatch): void;
+    /** 增量修改 Workspace env，并通知已绑定的 Agent。 */
+    patch_env(patch: WorkspaceEnvPatch): void;
+    /** 订阅 Workspace env 的后续变化。 */
+    subscribe_env(subscriber: WorkspaceEnvSubscriber): WorkspaceEnvUnsubscribe;
+    /** 将当前 Workspace 唯一绑定到 Agent，并创建结构化状态入口。 */
+    bind_agent(agent_id: string): AgentStore;
+    /** 关闭 Workspace 持有的 Store、命令进程与平台 Sandbox 资源。 */
+    dispose(): Promise<void>;
+    /** 原地应用一次 env patch。 */
+    private apply_env_patch;
+    /** 只在内容真实变化时发布完整 env 快照。 */
+    private publish_env_if_changed;
+}
+//# sourceMappingURL=Workspace.d.ts.map

package/bin/workspace/Workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Workspace.d.ts","sourceRoot":"","sources":["../../src/workspace/Workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,mCAAmC,CAAC;AAiB3C,oBAAoB;AACpB,qBAAa,SAAS;IACpB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAE/B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAE3C,kDAAkD;IAClD,OAAO,CAAC,eAAe,CAAC,CAAgB;IAExC,yCAAyC;IACzC,OAAO,CAAC,cAAc,CAAC,CAAS;IAEhC,2CAA2C;IAC3C,OAAO,CAAC,WAAW,CAAC,CAAa;IAEjC,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAE7C,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;gBAEzD,OAAO,EAAE,gBAAgB;IAarC,iCAAiC;IACjC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIjC,wCAAwC;IACxC,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAOtC,wCAAwC;IACxC,SAAS,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAMzC,8BAA8B;IAC9B,aAAa,CAAC,UAAU,EAAE,sBAAsB,GAAG,uBAAuB;IAO1E,4CAA4C;IAC5C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAqBxC,iDAAiD;IAC3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B,wBAAwB;IACxB,OAAO,CAAC,eAAe;IAavB,4BAA4B;IAC5B,OAAO,CAAC,sBAAsB;CAiB/B"}

package/bin/workspace/Workspace.js

@@ -0,0 +1,153 @@
+/**
+ * Workspace：本地项目资源与安全作用域。
+ *
+ * 职责说明（中文）
+ * - 只解析一次项目根目录，并将 Store、Tool 与可选 Shell 绑定到同一资源容器。
+ * - AgentStore 与 WorkspaceTools 共用同一个 FileSystem 和目录访问范围。
+ * - 每个 Workspace 实例只绑定一个 Agent；同一物理目录可创建多个独立实例。
+ */
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { LocalFileSystem } from "../workspace/LocalFileSystem.js";
+import { LocalAgentStore } from "../workspace/store/LocalAgentStore.js";
+import { resolve_workspace_env } from "../workspace/WorkspaceEnv.js";
+import { create_workspace_tools } from "../workspace/tool/WorkspaceTools.js";
+/** 将调用方路径解析为稳定、真实的本地目录。 */
+function resolve_workspace_path(input) {
+    const requested_path = String(input || "").trim();
+    if (!requested_path) {
+        throw new Error("Workspace requires a non-empty path");
+    }
+    const resolved_path = realpathSync.native(path.resolve(requested_path));
+    if (!statSync(resolved_path).isDirectory()) {
+        throw new Error(`Workspace path must be a directory: ${resolved_path}`);
+    }
+    return resolved_path;
+}
+/** 本地 Workspace。 */
+export class Workspace {
+    /** 已解析且不可变的项目根目录。 */
+    path;
+    /** Workspace 根目录内统一的受控文件与搜索能力。 */
+    files;
+    /** Workspace 内可用的文件、搜索与可选命令工具。 */
+    tools;
+    /** Workspace 内可选的受控命令执行能力。 */
+    shell;
+    /** Workspace 首次释放产生的稳定 Promise，保证重复释放不会重复关闭资源。 */
+    dispose_promise;
+    /** 当前 Workspace 已绑定的 Agent 标识；未绑定时为空。 */
+    bound_agent_id;
+    /** 当前 Workspace 为唯一 Agent 创建的结构化 Store。 */
+    bound_store;
+    /** 当前 Workspace configured env 的唯一可变状态。 */
+    env;
+    /** Workspace env 变化订阅器。 */
+    env_subscribers = new Set();
+    constructor(options) {
+        this.path = resolve_workspace_path(options.path);
+        this.files = new LocalFileSystem(this.path);
+        this.env = resolve_workspace_env(this.path, options.env);
+        this.shell = options.shell;
+        this.shell?.bind(this.path);
+        this.shell?.set_env(this.env);
+        this.tools = create_workspace_tools({
+            files: this.files,
+            ...(this.shell ? { shell: this.shell } : {}),
+        });
+    }
+    /** 返回当前 Workspace env 的浅拷贝快照。 */
+    get_env() {
+        return { ...this.env };
+    }
+    /** 整体覆盖 Workspace env，并通知已绑定的 Agent。 */
+    set_env(next) {
+        const previous = this.get_env();
+        for (const key of Object.keys(this.env))
+            delete this.env[key];
+        this.apply_env_patch(next);
+        this.publish_env_if_changed(previous);
+    }
+    /** 增量修改 Workspace env，并通知已绑定的 Agent。 */
+    patch_env(patch) {
+        const previous = this.get_env();
+        this.apply_env_patch(patch);
+        this.publish_env_if_changed(previous);
+    }
+    /** 订阅 Workspace env 的后续变化。 */
+    subscribe_env(subscriber) {
+        this.env_subscribers.add(subscriber);
+        return () => {
+            this.env_subscribers.delete(subscriber);
+        };
+    }
+    /** 将当前 Workspace 唯一绑定到 Agent，并创建结构化状态入口。 */
+    bind_agent(agent_id) {
+        const resolved_agent_id = String(agent_id || "").trim();
+        if (!resolved_agent_id) {
+            throw new Error("Workspace.bind_agent requires a non-empty agent_id");
+        }
+        if (this.dispose_promise) {
+            throw new Error("Cannot bind a disposed Workspace");
+        }
+        if (this.bound_agent_id) {
+            throw new Error(`Workspace is already bound to Agent "${this.bound_agent_id}"`);
+        }
+        this.bound_agent_id = resolved_agent_id;
+        this.bound_store = new LocalAgentStore({
+            files: this.files,
+            agent_id: resolved_agent_id,
+        });
+        return this.bound_store;
+    }
+    /** 关闭 Workspace 持有的 Store、命令进程与平台 Sandbox 资源。 */
+    async dispose() {
+        this.dispose_promise ??= (async () => {
+            const results = await Promise.allSettled([
+                this.bound_store?.dispose() ?? Promise.resolve(),
+                this.shell?.dispose() ?? Promise.resolve(),
+            ]);
+            const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (errors.length > 0) {
+                throw new AggregateError(errors, "Workspace dispose failed");
+            }
+        })();
+        await this.dispose_promise;
+    }
+    /** 原地应用一次 env patch。 */
+    apply_env_patch(patch) {
+        if (!patch || typeof patch !== "object")
+            return;
+        for (const [raw_key, raw_value] of Object.entries(patch)) {
+            const key = String(raw_key || "").trim();
+            if (!key)
+                continue;
+            if (raw_value === null || raw_value === undefined) {
+                delete this.env[key];
+                continue;
+            }
+            this.env[key] = String(raw_value);
+        }
+    }
+    /** 只在内容真实变化时发布完整 env 快照。 */
+    publish_env_if_changed(previous) {
+        const current = this.get_env();
+        const previous_keys = Object.keys(previous);
+        const current_keys = Object.keys(current);
+        const changed = previous_keys.length !== current_keys.length ||
+            current_keys.some((key) => previous[key] !== current[key]);
+        if (!changed)
+            return;
+        const snapshot = Object.freeze(current);
+        this.shell?.set_env(snapshot);
+        for (const subscriber of this.env_subscribers) {
+            try {
+                subscriber(snapshot);
+            }
+            catch {
+                // 观察者失败不能回滚已经完成的 Workspace env 修改。
+            }
+        }
+    }
+}
+//# sourceMappingURL=Workspace.js.map

package/bin/workspace/Workspace.js.map

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

package/bin/workspace/WorkspaceEnv.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Workspace 环境变量装配模块。
+ *
+ * 关键点（中文）
+ * - 只读取当前 Workspace 根目录的 `.env`，不读取全局配置文件。
+ * - 合并优先级固定为：项目 `.env` < 宿主显式 env。
+ * - 返回独立快照，不修改 `process.env`。
+ */
+/** 读取 Workspace 根目录的 `.env` 快照。 */
+export declare function load_project_dotenv(workspace_path: string): Record<string, string>;
+/**
+ * 解析 Workspace 最终环境变量。
+ *
+ * 关键点（中文）
+ * - 显式 env 的优先级高于项目 `.env`，符合构造参数覆盖项目默认值的语义。
+ * - `undefined` 字段不会进入最终快照。
+ */
+export declare function resolve_workspace_env(workspace_path: string, explicit_env?: NodeJS.ProcessEnv | Record<string, string | undefined>): Record<string, string>;
+//# sourceMappingURL=WorkspaceEnv.d.ts.map

package/bin/workspace/WorkspaceEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceEnv.d.ts","sourceRoot":"","sources":["../../src/workspace/WorkspaceEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,mCAAmC;AACnC,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBxB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,EACtB,YAAY,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACpE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB"}

package/bin/workspace/WorkspaceEnv.js

@@ -0,0 +1,50 @@
+/**
+ * Workspace 环境变量装配模块。
+ *
+ * 关键点（中文）
+ * - 只读取当前 Workspace 根目录的 `.env`，不读取全局配置文件。
+ * - 合并优先级固定为：项目 `.env` < 宿主显式 env。
+ * - 返回独立快照，不修改 `process.env`。
+ */
+import dotenv from "dotenv";
+import fs from "fs-extra";
+import path from "node:path";
+/** 读取 Workspace 根目录的 `.env` 快照。 */
+export function load_project_dotenv(workspace_path) {
+    const project_env_path = path.join(workspace_path, ".env");
+    if (!fs.existsSync(project_env_path))
+        return {};
+    try {
+        const parsed = dotenv.parse(fs.readFileSync(project_env_path, "utf-8"));
+        const result = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            const normalized_key = String(key || "").trim();
+            if (!normalized_key)
+                continue;
+            result[normalized_key] = String(value || "").trim();
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 解析 Workspace 最终环境变量。
+ *
+ * 关键点（中文）
+ * - 显式 env 的优先级高于项目 `.env`，符合构造参数覆盖项目默认值的语义。
+ * - `undefined` 字段不会进入最终快照。
+ */
+export function resolve_workspace_env(workspace_path, explicit_env) {
+    const normalized_explicit_env = {};
+    for (const [key, value] of Object.entries(explicit_env || {})) {
+        if (typeof value === "string")
+            normalized_explicit_env[key] = value;
+    }
+    return {
+        ...load_project_dotenv(workspace_path),
+        ...normalized_explicit_env,
+    };
+}
+//# sourceMappingURL=WorkspaceEnv.js.map

package/bin/workspace/WorkspaceEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspaceEnv.js","sourceRoot":"","sources":["../../src/workspace/WorkspaceEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,mCAAmC;AACnC,MAAM,UAAU,mBAAmB,CACjC,cAAsB;IAEtB,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC;QAAE,OAAO,EAAE,CAAC;IAEhD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC,CAAC;QACxE,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAChD,IAAI,CAAC,cAAc;gBAAE,SAAS;YAC9B,MAAM,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACtD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,cAAsB,EACtB,YAAqE;IAErE,MAAM,uBAAuB,GAA2B,EAAE,CAAC;IAC3D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,uBAAuB,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACtE,CAAC;IACD,OAAO;QACL,GAAG,mBAAmB,CAAC,cAAc,CAAC;QACtC,GAAG,uBAAuB;KAC3B,CAAC;AACJ,CAAC"}

package/bin/workspace/WorkspacePaths.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 返回项目运行时状态根目录 `.downcity` 的路径。
+ */
+export declare function get_downcity_dir_path(cwd: string): string;
+/**
+ * 返回项目日志目录路径。
+ */
+export declare function get_logs_dir_path(cwd: string): string;
+/**
+ * 返回项目缓存目录路径。
+ *
+ * 关键点（中文）
+ * - 当前使用隐藏命名 `.cache`，避免与用户业务目录混淆。
+ */
+export declare function get_cache_dir_path(cwd: string): string;
+/**
+ * 返回 profile 运行态目录路径。
+ *
+ * 关键点（中文）
+ * - 初始化流程会统一创建该目录，并在其中写入 profile 相关文件。
+ * - 单独保留目录级 API，避免调用方散落 `path.join(..., "profile")`。
+ */
+export declare function get_downcity_profile_dir_path(cwd: string): string;
+/**
+ * 返回 profile 主记忆文件路径。
+ *
+ * 关键点（中文）
+ * - 该文件通常承载主画像或核心长期 profile 信息。
+ */
+export declare function get_downcity_profile_primary_path(cwd: string): string;
+/**
+ * 返回 profile 补充记忆文件路径。
+ *
+ * 关键点（中文）
+ * - 该文件用于存放不适合进入主 profile 的补充材料。
+ */
+export declare function get_downcity_profile_other_path(cwd: string): string;
+/**
+ * Plugin Schedule JSONL 路径。
+ *
+ * 关键点（中文）
+ * - 调度任务属于项目 runtime 本地状态，因此放在项目 `.downcity/` 下。
+ */
+export declare function get_downcity_schedule_db_path(cwd: string): string;
+/**
+ * 返回项目运行时数据目录路径。
+ */
+export declare function get_downcity_data_dir_path(cwd: string): string;
+/**
+ * 返回项目公开静态资源目录路径。
+ */
+export declare function get_downcity_public_dir_path(cwd: string): string;
+/**
+ * 返回项目任务目录路径。
+ *
+ * 关键点（中文）
+ * - 该目录用于存放任务相关的本地文件与运行时数据。
+ */
+export declare function get_downcity_tasks_dir_path(cwd: string): string;
+/**
+ * 返回项目调试目录路径。
+ *
+ * 关键点（中文）
+ * - 当前使用隐藏目录 `.debug`，避免与用户显式业务目录冲突。
+ */
+export declare function get_downcity_debug_dir_path(cwd: string): string;
+//# sourceMappingURL=WorkspacePaths.d.ts.map

package/bin/workspace/WorkspacePaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkspacePaths.d.ts","sourceRoot":"","sources":["../../src/workspace/WorkspacePaths.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/D"}