• 工作区驱动的 Agent 运行环境：Agent 的人格、知识、技能、记忆、子 Agent 规格统一沉淀在一个结构化工作区里，每次运行自动从工作区加载上下文、结束后自动回写记忆，Agent 的能力随时间持续演化。

• 可插拔的抽象文件系统：工作区的物理存储可以自由切换——本机磁盘、远端共享存储、隔离沙箱均通过同一套接口操作，同一份 Agent 逻辑无需修改即可适配个人开发环境与企业分布式部署。

• 开箱即用的上下文管理：内置对话压缩、双层记忆沉淀与全文检索，解决长对话上下文膨胀和跨会话记忆丢失两个顽固问题，并通过后台维护机制保证记忆库不随时间失控增长。

• 子 Agent 编排与隔离执行：支持声明式定义子 Agent、同步或异步委派子任务；工具执行可配置在隔离沙箱内完成，并在多轮对话间保持沙箱状态可恢复，兼顾多租户场景的会话与用户维度隔离。

1. 多用户、多副本，工作区怎么办？OpenClaw 用一个本地目录做工作区，单机单用户完全没问题。但服务要对外，多个用户的工作空间要隔离，Agent 水平扩容到多台机器后，同一用户的工作区又要在副本间共享——本地目录这套假设直接崩掉了。

2. Tool 和 Skill Script 不能在宿主机上跑，怎么隔离执行？Agent 调用 Shell 或运行用户提供的代码，放在本地可信开发机上无所谓，一旦上服务，把任意用户输入的命令直接在宿主机上执行就是安全漏洞。沙箱是必须的，但"有沙箱"只是第一步：沙箱里的 Tool 还需要看到完整的上下文，多轮对话中同一个沙箱实例要可恢复，而不是每次都从零开始。

3. "workspace + 文件系统"的组合如何搬到分布式环境？文件系统驱动的工作区是 Harness Engineering 里最直觉、也最有效的模式，但这套模式的前提是"文件系统"。分布式场景下没有统一的本地磁盘，远端存储、KV 服务、对象存储各有各的接口，重写一遍等于把 Agent 逻辑和基础设施耦合死了。

4. Multi-Agent 怎么做才对？子任务分发、上下文隔离、异步执行、结果回收、超时取消——每一项单独做都不难，但要拼成一个可管理的编排层，代码复杂度会快速上升，而且大多数框架只提供原语，工程上的"怎么声明子 Agent、什么时候 spawn、怎么管理状态"全靠自己摸索。

5. 上下文压缩和分层记忆有没有开箱即用的实现？Harness Engineering 把这两件事讲得很清楚，但真正做起来要处理的细节非常多：压缩时机、压缩策略、压缩前的事实提取、历史的可检索性、跨进程重启后的恢复……大多数框架只给了 short/long memory 的抽象接口，具体实现还是要自己来。

待详细展开三种实现与模式。

• Shell/Code/Skill 的执行通过沙箱后端隔离，用户输入驱动的命令不再直接在宿主机上运行；
• 工作区本身也可以运行在沙箱内，实现文件读写层面的隔离；
• 工具的注册与暴露由框架统一管理，execute工具仅在后端实现了沙箱接口时才出现；

分布式部署

• Agent 可以多副本对等部署，MEMORY.md、会话日志等关键文件通过 Remote 后端路由到共享存储，天然实现跨节点同步；
• 通过IsolationScope（SESSION / USER / AGENT / GLOBAL）与RuntimeContext组合，在代码不变的前提下实现 session 级隔离、用户级共享等多种租户策略；

Subagent 与异步任务

• 子 Agent 的工作区、文件系统、会话状态都从父 Agent 继承或独立配置，编排策略由规格声明，不需要手工拼装；
• 异步任务的状态机（PENDING/RUNNING/COMPLETED/FAILED/CANCELLED）与结果回收机制开箱即用，支持替换为跨进程实现；

• 持续记忆：对话结束后自动将新事实提炼写入工作区，下次启动无需重新"告知"Agent 背景，长期记忆随使用积累。

• 本地 Shell 执行：在本机可信环境下，Agent 可直接运行脚本、操作文件，复现 OpenClaw 类产品的核心体验。

• 工作区即配置：修改AGENTS.md调整人格，在skills/目录里新增技能，改一个文件等于升级一次 Agent，不需要重新编译部署。

• 会话跨进程恢复：关闭再打开，只要 sessionId 不变，上次对话的状态全部还原，不是从零开始。

• 隔离沙箱执行：所有代码与命令在隔离环境内运行，宿主服务进程不受用户输入影响，安全边界清晰。

• 多轮沙箱状态恢复：每轮对话结束后自动保存沙箱状态，下轮或下次服务启动时原位恢复，用户的工作现场不丢失。

• 分布式记忆共享：用户的长期记忆存放在共享存储，多节点部署下所有副本读到同一份"对这个用户的了解"，体验一致。

• 子 Agent 并行编排：长任务可拆解为多个子 Agent 并发执行，主 Agent 只做协调，整体效率更高，也更易管理超时与失败。

• 多租户隔离：按会话或用户维度隔离工作区与执行环境，多用户同时在线互不干扰。

• 默认安全边界：不开启沙箱执行时框架不暴露 Shell 工具，Agent 只能通过你明确注册的业务工具与外部交互，安全策略由配置决定。

• 多实例共享记忆：会话状态与用户记忆落到远端存储，任意服务实例都能读到同一份上下文，用户无感知地在多实例间切换。

• 会话跨请求连续：每次请求携带相同的用户标识，Agent 自动恢复上次的对话状态，实现真正的多轮连续对话体验。

• 并行子任务支持：需要同时处理多个业务步骤时，可将子任务委派给子 Agent 并行执行，结果汇总后统一回复，不影响主流程响应速度。

1. 引入依赖

<dependency>    <groupId>io.agentscope</groupId>    <artifactId>agentscope-harness</artifactId>    <version>${agentscope.version}</version></dependency>

2. 准备工作区

3. 构建HarnessAgent并调用

HarnessAgent agent = HarnessAgent.builder()    .name("my-agent")    .model(model)    .workspace(Paths.get(".agentscope/workspace"))    .compaction(CompactionConfig.builder()     // 建议一开始就配，避免线上 context overflow        .triggerMessages(50)        .keepMessages(20)        .build())    .build();RuntimeContext ctx = RuntimeContext.builder()    .sessionId("user-session-001")   // 相同 sessionId 的多次 call 自动续接上下文    .userId("alice")                 // 多用户场景必传，用于命名空间隔离    .build();Msg reply = agent.call(userMessage, ctx).block();

工作区（Workspace）：Agent 的唯一事实来源

workspace/├── AGENTS.md              ← Agent 人格与行为约定，每次推理前自动注入 system prompt├── MEMORY.md              ← 精炼的长期记忆，由后台自动维护，随使用积累├── knowledge/             ← 领域知识，随 AGENTS.md 一起注入├── skills/                ← 可复用技能，自动装配到 Agent 的工具集├── subagents/             ← 子 Agent 规格声明，自动被发现和加载└── agents/<agentId>/    ├── context/           ← 会话状态快照（进程重启后恢复用）    ├── sessions/          ← 对话 JSONL 与压缩上下文，供审计与检索    └── memory/            ← 每日记忆流水账

会话持久化（Session）：跨请求、跨进程的状态连续

• 状态快照（context/）：每次call()结束后，Agent 的运行状态（当前的对话记忆、工具执行上下文等）序列化为 JSON 文件，存到工作区的agents/<agentId>/context/sessionId/下。下次用相同sessionId发起调用时，框架在推理开始前自动加载这份快照，恢复到上次结束的位置。这是"关掉再打开仍然记得上次"的技术保障。
• 对话日志（sessions/）：完整的对话历史以 JSONL 格式追加写入<sessionId>.log.jsonl，这个文件永远不会被压缩，供审计和session_search工具使用。另有一份<sessionId>.jsonl存放压缩后的 LLM 上下文，是模型实际"看到"的版本。

记忆管理（Memory）：从对话到长期知识的自动沉淀

.compaction(CompactionConfig.builder()    .triggerMessages(50)    // 消息数超过 50 触发压缩    .keepMessages(20)       // 保留最近 20 条    .flushBeforeCompact(true) // 压缩前先提炼记忆（默认已开启）    .build())

子 Agent 编排（Subagent）：复杂任务的分解与委派

1. 内置的general-purposeAgent：镜像主 Agent 的配置，适合临时委派任意子任务；
2. 工作区文件驱动：在workspace/subagents/下放 Markdown 文件（YAML front matter 定义名称、描述、工具；body 是 system prompt），框架自动发现并加载；
3. 代码声明：用builder.subagent(spec)编程式指定；
4. 自定义工厂：完全控制子 Agent 的构建逻辑。

• 同步调用：主 Agent 阻塞等待子 Agent 完成再继续，适合必须拿到结果才能下一步的场景；
• 异步调用：主 Agent 提交任务后立即拿到一个任务 ID，可以继续做其他事，后续用task_output工具轮询结果。对于耗时超过几秒的任务，强烈建议用异步，避免主 Agent 白白阻塞消耗时间与 Token。

内置工具（Builtin Tools）

文件系统（Filesystem）：三种模式，按需选型

模式一：本机 + Shell（默认）

模式二：远端共享存储

模式三：沙箱执行

沙箱（Sandbox）：隔离执行 + 状态可恢复

• 会话级：每个会话有独立的沙箱状态，互不干扰，适合多用户 SaaS；
• 用户级：同一用户的多个会话共享同一沙箱状态，适合"用户长期工作台"类场景；
• 全局共享：整个 Agent 共用一个沙箱，适合工具型、只读型 Agent。

• 沙箱生命周期如何管理：agent 内置管理、用户自行管理；
• 哪些流程需要运行在沙箱中：Tool In Sandbox、Subagent in Sandbox；
• 沙箱内部状态如何管理：state、snapshot 恢复；

Skills：工作区驱动的可复用技能