@downcity/city/workspace

项目资源、文件工具、环境变量与 Shell。

@downcity/city/workspace 提供 Agent 执行任务时使用的 Workspace 实现；常用构造器也从 @downcity/city 根入口导出。Workspace 拥有项目路径、rooted 文件 能力、文件与搜索工具、环境变量和可选 Shell，但不拥有 Agent 身份、Plugin、Session、存储 或模型调用。

pnpm add @downcity/city @downcity/sandbox-microsandbox
import { Agent, City, Shell, Workspace } from "@downcity/city";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";

const workspace = new Workspace({
  id: "project",
  path: process.cwd(),
  env: { NODE_ENV: "development" },
  shell: new Shell({
    sandbox_provider: new MicrosandboxProvider(),
  }),
});

const city = new City({
  workspaces: [workspace],
});
const agent = new Agent({ id: "repo-helper", model });
city.agents.add(agent);
const session = await agent.sessions.create({ workspace });

所有权

  • Workspace 拥有项目资源与可选 Shell。
  • Shell 持有 Sandbox Provider、当前 Workspace 的持久 Sandbox 与 Shell Sessions。
  • City 持有登记的 Workspace，但不理解其执行后端。
  • Agent 拥有身份、指令、模型、自定义工具和 Session；City 拥有 Plugin。
  • AgentSessions 拥有 Session。Workspace 只是 Session 可以使用的一种资源。
  • Shell 是 Workspace 能力，不再存在独立的 @downcity/shell 包。

一个 Agent 可以在多个 Workspace 资源中创建 Session。Workspace 可以登记在 City 内，也可以由 宿主在 City 外管理；Agent 私有 Session 与 City 分配的 Agent/Plugin 执行数据始终隔离。

结构化 write、edit 工具会在文件原子提交后，通过 WorkspaceToolActionResult.effects 报告 workspace.file_mutation。Effect 不会作为 Tool output 发送给模型；Agent Session 只在当前 Turn 中按顺序收集，并在收口时将文件修改投影为 Assistant data part。Shell 与外部编辑不会产生该 Effect。

存储

City 提供不理解业务的底层 Storage Provider，默认实现是内存存储；需要持久化时由宿主注入本地 文件存储。使用本地存储时，运行状态集中保存在项目目录之外：

~/.downcity/agents/<agent_id>/
├── sessions/
└── plugins/

StorageProvider 不理解任何 Agent 领域语义。Agent runtime 解释 Session 数据，City Plugin runtime 解释 Plugin 数据；Workspace 不创建或拥有这份存储。项目 File/Search 工具始终限制在真实项目目录内。

Edge Adapter 应从 @downcity/type/workspace 导入 WorkspaceRuntime 与协议类型，避免加载 Node.js 文件系统、PTY 和本地 Shell 实现。

目录

所有权存储