@downcity/agent 1.1.337 → 1.1.399

package/src/workspace/Workspace.ts

@@ -1,178 +0,0 @@
-/**
- * Workspace：本地项目资源与安全作用域。
- *
- * 职责说明（中文）
- * - 只解析一次项目根目录，并将 Store、Tool 与可选 Shell 绑定到同一资源容器。
- * - AgentStore 与 WorkspaceTools 共用同一个 FileSystem 和目录访问范围。
- * - 每个 Workspace 实例只绑定一个 Agent；同一物理目录可创建多个独立实例。
- */
-
-import { realpathSync, statSync } from "node:fs";
-import path from "node:path";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
-import { LocalFileSystem } from "@/workspace/LocalFileSystem.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";
-import { resolve_workspace_env } from "@/workspace/WorkspaceEnv.js";
-import { create_workspace_tools } from "@/workspace/tool/WorkspaceTools.js";
-import { WorkspaceBase } from "@/workspace/WorkspaceBase.js";
-
-/** 将调用方路径解析为稳定、真实的本地目录。 */
-function resolve_workspace_path(input: string): string {
-  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 extends WorkspaceBase {
-  /** 已解析且不可变的项目根目录。 */
-  readonly path: string;
-
-  /** Workspace 根目录内统一的受控文件与搜索能力。 */
-  readonly files: FileSystem;
-
-  /** Workspace 内可用的文件、搜索与可选命令工具。 */
-  readonly tools: WorkspaceTools;
-
-  /** Workspace 内可选的受控命令执行能力。 */
-  readonly shell?: WorkspaceOptions["shell"];
-
-  /** Workspace 首次释放产生的稳定 Promise，保证重复释放不会重复关闭资源。 */
-  private dispose_promise?: Promise<void>;
-
-  /** 当前 Workspace 已绑定的 Agent 标识；未绑定时为空。 */
-  private bound_agent_id?: string;
-
-  /** 当前 Workspace 为唯一 Agent 创建的结构化 Store。 */
-  private bound_store?: AgentStore;
-
-  /** 当前 Workspace configured env 的唯一可变状态。 */
-  private readonly env: Record<string, string>;
-
-  /** Workspace env 变化订阅器。 */
-  private readonly env_subscribers = new Set<WorkspaceEnvSubscriber>();
-
-  constructor(options: WorkspaceOptions) {
-    super();
-    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(): Record<string, string> {
-    return { ...this.env };
-  }
-
-  /** 整体覆盖 Workspace env，并通知已绑定的 Agent。 */
-  set_env(next: WorkspaceEnvPatch): void {
-    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: WorkspaceEnvPatch): void {
-    const previous = this.get_env();
-    this.apply_env_patch(patch);
-    this.publish_env_if_changed(previous);
-  }
-
-  /** 订阅 Workspace env 的后续变化。 */
-  subscribe_env(subscriber: WorkspaceEnvSubscriber): WorkspaceEnvUnsubscribe {
-    this.env_subscribers.add(subscriber);
-    return () => {
-      this.env_subscribers.delete(subscriber);
-    };
-  }
-
-  /** 将当前 Workspace 唯一绑定到 Agent，并创建结构化状态入口。 */
-  bind_agent(agent_id: string): AgentStore {
-    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 = this.create_agent_store(resolved_agent_id);
-    return this.bound_store;
-  }
-
-  /** 关闭 Workspace 持有的 Store、命令进程与平台 Sandbox 资源。 */
-  async dispose(): Promise<void> {
-    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。 */
-  private apply_env_patch(patch: WorkspaceEnvPatch): void {
-    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 快照。 */
-  private publish_env_if_changed(previous: Record<string, string>): void {
-    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 修改。
-      }
-    }
-  }
-}

package/src/workspace/WorkspaceBase.ts

@@ -1,62 +0,0 @@
-/**
- * Workspace 可扩展基类。
- *
- * 职责说明（中文）
- * - 定义 Agent 依赖的 Workspace 资源契约与环境变量生命周期。
- * - 不绑定本地文件系统、远程文件系统或具体执行后端。
- * - 本地 Workspace 与 Cloudflare Computer Workspace 均通过该基类接入 Agent。
- */
-
-import type { Shell } from "@downcity/shell";
-import type { AgentStore } from "@/types/store/AgentStore.js";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
-import { LocalAgentStore } from "@/workspace/store/LocalAgentStore.js";
-import type { WorkspaceTools } from "@/types/workspace/WorkspaceTools.js";
-import type {
-  WorkspaceEnvPatch,
-  WorkspaceEnvSubscriber,
-  WorkspaceEnvUnsubscribe,
-} from "@/types/workspace/WorkspaceEnv.js";
-
-/** Agent 所需的可扩展 Workspace 基类。 */
-export abstract class WorkspaceBase {
-  /** 子类完成自身资源装配前调用的无状态基类构造函数。 */
-  protected constructor() {}
-
-  /** Workspace 的稳定逻辑根路径；远程实现可以使用虚拟路径。 */
-  abstract readonly path: string;
-
-  /** Workspace 内统一的文件与搜索能力。 */
-  abstract readonly files: FileSystem;
-
-  /** Workspace 提供给 Agent 的模型工具。 */
-  abstract readonly tools: WorkspaceTools;
-
-  /** Workspace 提供的可选命令执行能力。 */
-  abstract readonly shell?: Shell;
-
-  /** 返回当前 Workspace 环境变量快照。 */
-  abstract get_env(): Record<string, string>;
-
-  /** 整体替换 Workspace 环境变量。 */
-  abstract set_env(next: WorkspaceEnvPatch): void;
-
-  /** 增量修改 Workspace 环境变量。 */
-  abstract patch_env(patch: WorkspaceEnvPatch): void;
-
-  /** 订阅 Workspace 环境变量变化。 */
-  abstract subscribe_env(
-    subscriber: WorkspaceEnvSubscriber,
-  ): WorkspaceEnvUnsubscribe;
-
-  /** 将 Workspace 绑定到唯一 Agent，并返回该 Agent 的 Store。 */
-  abstract bind_agent(agent_id: string): AgentStore;
-
-  /** 使用当前 Workspace FileSystem 创建默认结构化 AgentStore。 */
-  protected create_agent_store(agent_id: string): AgentStore {
-    return new LocalAgentStore({ files: this.files, agent_id });
-  }
-
-  /** 释放 Workspace 持有的资源。 */
-  abstract dispose(): Promise<void>;
-}

package/src/workspace/WorkspaceEnv.ts

@@ -1,54 +0,0 @@
-/**
- * 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: string,
-): Record<string, string> {
-  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: Record<string, string> = {};
-    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: string,
-  explicit_env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
-): Record<string, string> {
-  const normalized_explicit_env: Record<string, string> = {};
-  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,
-  };
-}