书接上回我在之前的一篇文章中深入分析了 OpenClaw 及其背后的 Harness Engineering 实践同时构想了一套“Harness Framework”来讲解如何将这套理念应用到企业级智能体开发中。好消息是AgentScope Java 1.1.0 版本正式发布了在这个里程碑版本中我们完整的实现了这套“Harness Framework”规划。开发者可以基于 1.1 版本快速实践 Harness开发面向个人提效的 XxxClaw、Coding Agent 等本地应用也可以开发面向分布式场景的 DataAgent、SRE Agent 等企业级应用。AgentScope Java 1.1.0 在这个版本中交付了四项核心能力工作区驱动的 Agent 运行环境Agent 的人格、知识、技能、记忆、子 Agent 规格统一沉淀在一个结构化工作区里每次运行自动从工作区加载上下文、结束后自动回写记忆Agent 的能力随时间持续演化可插拔的抽象文件系统工作区的物理存储可以自由切换——本机磁盘、远端共享存储、隔离沙箱均通过同一套接口操作同一份 Agent 逻辑无需修改即可适配个人开发环境与企业分布式部署开箱即用的上下文管理内置对话压缩、双层记忆沉淀与全文检索解决长对话上下文膨胀和跨会话记忆丢失两个顽固问题并通过后台维护机制保证记忆库不随时间失控增长子 Agent 编排与隔离执行支持声明式定义子 Agent、同步或异步委派子任务工具执行可配置在隔离沙箱内完成并在多轮对话间保持沙箱状态可恢复兼顾多租户场景的会话与用户维度隔离。OpenClaw/Hermes 很好但在企业级智能体场景却用不起来过去一年OpenClaw、Hermes、Claude Code 等智能体产品掀起了一波热潮也带火了这些产品背后的 Harness Engineering 理念——用结构化的工作区、上下文管理与工具约定替代“每次对话各自为战”的原始使用方式。越来越多的团队开始把这套思路搬进自己的 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 的抽象接口具体实现还是要自己来。这五个问题的根源是同一件事个人助手型 Agent 和企业级 Agent 是两种不同的工程形态用同一套假设去应对两种场景必然碰壁。从部署形态看个人助手是单用户单进程所有状态都可以放在一台机器上企业级 Agent 要水平扩容、要多租户、要服务不中断状态必须能分布式存储和恢复。从安全边界看本机工具执行没有风险生产环境上任意 Shell 执行则是一个严重的攻击面沙箱和权限边界不是“可选的优化”而是“上线的前提”。从运维可观测性看个人工具出了问题自己看日志就行企业服务要求记忆落盘、会话可审计、状态变更可追踪。从Token 经济看个人用户对延迟和费用不敏感企业场景每一次无效的上下文重推都是真实的成本开销。那么有没有一款框架能让你“写一套逻辑按需切换形态”AgentScope Java 1.1.0 的 Harness 模块入口类HarnessAgent就是围绕这个目标设计的它不替换ReActAgent的推理循环而是在循环的关键时机插入 Hook补齐一组工具与工作区约定把上面五个问题的工程答案打包进来让你专注于 Agent 的业务逻辑而不是基础设施。AgentScope Harness 设计理念凭什么它能解决以上问题AgentScope Java Harness 的设计哲学可以用一句话概括把“下一轮怎么办、下一天怎么办、上下文爆了怎么办、状态丢了怎么办”的工程答案打包进来而不是让每个 Agent 项目各自发明一遍。具体到实现层面有两个核心支柱支撑起整个框架。核心支柱一Workspace 作为唯一事实来源Harness 为每个 Agent 引入了workspace 工作空间的概念——一个结构化目录用于承载 Agent 运行所需的一切持久化内容人格定义AGENTS.md、长期记忆MEMORY.md、领域知识knowledge/、可复用技能skills/、子 Agent 规格subagents/以及会话历史agents/agentId/。这并不是一个新想法——OpenClaw、Hermes 在实践中都发现让 Agent 有一个稳定的“工作台”比每次重新初始化有效得多。Harness 把这个直觉系统化了工作区是 Agent 的唯一事实来源Source of Truth所有状态的读写都围绕工作区展开而不是散落在代码、数据库和内存的各个角落。实际运行中每次推理开始前WorkspaceContextHook会把AGENTS.md、MEMORY.md、knowledge/等关键文件自动注入到 system prompt 里确保 Agent 的人格和知识在每一轮都完整呈现。Agent 运行结束后MemoryFlushHook会提炼本次对话的新事实写入记忆文件后台的MemoryConsolidator再周期性地把流水账合并成精炼的长期记忆。工作区在对话中持续演化每一次运行都比上一次“更了解”用户和任务。核心支柱二AbstractFilesystem 让工作区可以运行在任何环境工作区的理念很美好但有一个现实约束本地磁盘目录在分布式场景下行不通。多个 Pod 各有一块本地磁盘MEMORY.md写到哪里哪个副本的版本才是“真”的AgentScope Java Harness 用 AbstractFilesystem 抽象层来解决这个问题。对上层而言Agent 只需要调用统一的read/write/ls/grep等接口不关心“文件”实际落在哪对下层而言可以适配到本机磁盘、远端对象存储OSS、KV 数据库Redis、沙箱文件系统等任意介质甚至通过CompositeFilesystem把不同路径路由到不同后端。如上图所示基于 AbstractFilesystem 接口AgentScope Java 内置提供了三种拓展实现对应三种使用模式。待详细展开三种实现与模式。在 AgentScope Java 1.1 版本中workspace 是 agent 的核心抽象我们 AbstractFilesystem 作为 workspace 的物理实现载体所有文件操作、命令执行、记忆管理工具都以 AbstractFilesystem 为标准操作入口。基于这一层文件系统抽象AgentScope Java 框架直接为智能体开发带来了三大工程能力安全与隔离Shell/Code/Skill 的执行通过沙箱后端隔离用户输入驱动的命令不再直接在宿主机上运行工作区本身也可以运行在沙箱内实现文件读写层面的隔离工具的注册与暴露由框架统一管理execute工具仅在后端实现了沙箱接口时才出现。分布式部署Agent 可以多副本对等部署MEMORY.md、会话日志等关键文件通过 Remote 后端路由到共享存储天然实现跨节点同步通过IsolationScopeSESSION / USER / AGENT / GLOBAL与RuntimeContext组合在代码不变的前提下实现 session 级隔离、用户级共享等多种租户策略。Subagent 与异步任务子 Agent 的工作区、文件系统、会话状态都从父 Agent 继承或独立配置编排策略由规格声明不需要手工拼装异步任务的状态机PENDING/RUNNING/COMPLETED/FAILED/CANCELLED与结果回收机制开箱即用支持替换为跨进程实现。将 AgentScope Harness 快速映射到你的应用场景下面三个场景覆盖了从个人到企业的典型开发形态。它们并不是非此即彼的选项而是代表了三条不同的复杂度路径——你可以从最简单的一条开始随着需求演化逐步迁移。个人代理 Agent — 典型如 OpenClaw 类应用这类场景的特点单用户、本机运行、需要操作本地文件或执行脚本典型产品是个人助理、笔记机器人、本地 Coding Agent。这类场景的核心诉求是“让 Agent 真正了解我、记住我”而不只是一个无状态的问答机器。Harness 在这里的价值是工作区里的AGENTS.md定义了 Agent 的人格和行为偏好对话结束后会自动提炼新的事实写入记忆下次打开时 Agent 依然认识你、记得上次的进度。技能skills和领域知识也都住在工作区里随时可以编辑调整不需要动代码。本机部署下还可以开放 Shell 执行能力让 Agent 直接运行脚本、操作文件系统这也是 OpenClaw 类产品最有吸引力的地方。而 Harness 在此之上补上了“持续演化”的那一层工作区就像 Agent 的大脑随着每次对话变得更有经验。AgentScope Java Harness 在此场景提供的核心能力持续记忆对话结束后自动将新事实提炼写入工作区下次启动无需重新“告知”Agent 背景长期记忆随使用积累本地 Shell 执行在本机可信环境下Agent 可直接运行脚本、操作文件复现 OpenClaw 类产品的核心体验工作区即配置修改 AGENTS.md 调整人格在 skills/ 目录里新增技能改一个文件等于升级一次 Agent不需要重新编译部署会话跨进程恢复关闭再打开只要 sessionId 不变上次对话的状态全部还原不是从零开始。企业级数据服务 — 典型如 DataAgent这类场景的特点服务多个用户、需要执行 SQL / Python / Shell、任务耗时较长、输入来自不可信的外部用户同时要求多轮对话状态可恢复、多副本部署时用户体验一致。这类场景最大的风险是执行安全——用户驱动的代码不能在服务器上无限制地跑。Harness 的沙箱机制把 Agent 的文件操作和命令执行都限定在隔离环境里服务器进程本身不受影响。更关键的是沙箱不是“用完即毁”的每轮对话结束后沙箱的状态会被持久化下一轮拿回来继续用户不会因为服务重启或切换节点就丢失工作进度。多副本部署时用户的长期记忆Agent 对这个用户积累的了解可以存放在共享存储里无论请求落到哪个节点Agent 看到的都是同一份记忆。长分析任务可以拆成多个子 Agent 并行执行主 Agent 只负责协调和汇总不必一直阻塞等待。AgentScope Java Harness 在此场景提供的核心能力隔离沙箱执行所有代码与命令在隔离环境内运行宿主服务进程不受用户输入影响安全边界清晰多轮沙箱状态恢复每轮对话结束后自动保存沙箱状态下轮或下次服务启动时原位恢复用户的工作现场不丢失分布式记忆共享用户的长期记忆存放在共享存储多节点部署下所有副本读到同一份“对这个用户的了解”体验一致子 Agent 并行编排长任务可拆解为多个子 Agent 并发执行主 Agent 只做协调整体效率更高也更易管理超时与失败多租户隔离按会话或用户维度隔离工作区与执行环境多用户同时在线互不干扰。企业在线服务 — 典型如淘天交易 Agent这类场景的特点主要通过调用业务 API 完成任务下单、查询、审批等不需要在服务器上执行 Shell但需要多实例运行、会话状态可持久、跨用户的知识共享。这类场景的核心诉求是稳定与安全——在线服务不能因为 Agent 调用了一个不该调用的 Shell 命令而出事。Harness 在这里的价值是不配置沙箱执行能力时框架默认就不会暴露 Shell 工具Agent 只能通过明确定义的业务工具与外部交互安全边界由配置决定而不是靠开发者自律。会话状态和记忆可以落到远端存储多个服务实例共享同一套用户记忆用户换一个入口重新对话Agent 仍然能接续上次的上下文。需要并行处理多个子任务时比如同时查库存、计算优惠、生成摘要子 Agent 机制同样适用可以对接外部任务队列实现跨进程的任务管理。AgentScope Java Harness 在此场景提供的核心能力默认安全边界不开启沙箱执行时框架不暴露 Shell 工具Agent 只能通过你明确注册的业务工具与外部交互安全策略由配置决定多实例共享记忆会话状态与用户记忆落到远端存储任意服务实例都能读到同一份上下文用户无感知地在多实例间切换会话跨请求连续每次请求携带相同的用户标识Agent 自动恢复上次的对话状态实现真正的多轮连续对话体验并行子任务支持需要同时处理多个业务步骤时可将子任务委派给子 Agent 并行执行结果汇总后统一回复不影响主流程响应速度。AgentScope Harness 详解花点时间了解更多框架详情吧本节将从使用者视角讲清楚 AgentScope Java Harness 的核心能力它是什么、怎么工作、配置时应该怎么想。快速开始 - Quick Start上手 Harness 只需三步引入依赖、准备工作区、构建并调用 Agent。1. 引入依赖dependency groupIdio.agentscope/groupId artifactIdagentscope-harness/artifactId version${agentscope.version}/version /dependencyDust2. 准备工作区在磁盘上选一个目录作为workspace并在其中创建AGENTS.md。这不是“可选的初始化步骤”而是 Harness 的核心入口——Agent 的人格、记忆、技能、子 Agent 规格全部围绕这个目录展开。AGENTS.md内容简单写几行约定就够后续随使用不断演化。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();X86asm运行后检查工作区目录AGENTS.md、memory/、agents/agentId/三个路径都应该存在这说明 Agent 已经在正常写入记忆和持久化会话状态了。完整可运行示例见agentscope-examples/harness-example中的QuickstartExample。核心概念 - Concepts理解下面六个概念基本就掌握了 Harness 的运行逻辑。概念定义解决的问题使用建议HarnessAgent基于ReActAgent的工程化封装入口build()时装配 Hook、内置工具、技能与会话持久化不想从零拼装压缩、记忆、会话、子任务、文件系统业务代码只与HarnessAgent.builder()和agent.call(msg, ctx)打交道workspaceAgent 的工作目录承载AGENTS.md、MEMORY.md、skills/、subagents/、会话历史等全部持久化内容人格、知识、记忆、状态放哪、如何持续演化先规划工作区结构再写 prompt把工作区当作可版本化的资产filesystem文件读写的统一接口是 Agent 工具层与物理存储之间的抽象层支持本地磁盘、远端存储、沙箱等多种后端同一套 Agent 逻辑如何在本地、共享存储、沙箱间切换优先从三种声明式模式选型Local / Remote / SandboxRuntimeContext单次call()的身份上下文包含sessionId、userId等每次调用重新传入不持久化这一轮是谁、状态读写到哪、多租户如何隔离必须稳定传sessionId多租户场景必须传userIdsandbox隔离执行环境文件操作与命令在沙箱侧运行每轮对话结束后持久化状态、下轮恢复如何在不信任输入下安全执行工具与脚本并保持多轮状态连续有代码执行需求时优先启用根据业务选择隔离粒度memory双层记忆系统每轮对话后自动提炼写入流水账后台周期性合并成可注入的长期记忆配合全文检索长对话不丢事实、上下文不爆、历史可检索开启对话压缩并观察记忆文件变化旧事实用搜索工具回捞总纲HarnessAgent负责编排workspace负责沉淀filesystem负责落点RuntimeContext负责身份sandbox负责边界memory负责长期演化。功能详情 - Features工作区WorkspaceAgent 的唯一事实来源工作区是 Harness 区别于普通 Agent 框架最重要的设计。它不是一个临时存储目录而是 Agent 的“大脑外化”——所有需要跨会话保留的内容都住在这里。工作区的标准目录结构如下workspace/ ├── AGENTS.md ← Agent 人格与行为约定每次推理前自动注入 system prompt ├── MEMORY.md ← 精炼的长期记忆由后台自动维护随使用积累 ├── knowledge/ ← 领域知识随 AGENTS.md 一起注入 ├── skills/ ← 可复用技能自动装配到 Agent 的工具集 ├── subagents/ ← 子 Agent 规格声明自动被发现和加载 └── agents/agentId/ ├── context/ ← 会话状态快照进程重启后恢复用 ├── sessions/ ← 对话 JSONL 与压缩上下文供审计与检索 └── memory/ ← 每日记忆流水账Nix工作区在每次推理中如何工作推理开始前Harness 把AGENTS.md、MEMORY.md、knowledge/等关键文件拼入 system prompt推理结束后把本次对话中出现的新事实提炼出来追加到当日的记忆流水账。工作区随每次对话持续演化Agent 随时间变得“更了解”它面对的业务和用户。为什么工作区优于把 prompt 写死在代码里人格、知识、技能和子 Agent 规格都在工作区的文件里调整行为只需要改文件不需要重新编译和部署。对于有复杂业务知识的 Agent这一点尤其关键——业务规则随时在变更新应该轻量。会话持久化Session跨请求、跨进程的状态连续Harness 把会话状态落盘分成两条并行的路径它们各自解决不同的问题状态快照context/每次call()结束后Agent 的运行状态当前的对话记忆、工具执行上下文等序列化为 JSON 文件存到工作区的agents/agentId/context/sessionId/下。下次用相同sessionId发起调用时框架在推理开始前自动加载这份快照恢复到上次结束的位置。这是“关掉再打开仍然记得上次”的技术保障。对话日志sessions/完整的对话历史以 JSONL 格式追加写入sessionId.log.jsonl这个文件永远不会被压缩供审计和session_search工具使用。另有一份sessionId.jsonl存放压缩后的 LLM 上下文是模型实际“看到”的版本。两条路径都由框架自动维护开发者唯一需要做的是每次调用时稳定传入相同的sessionId。记忆管理Memory从对话到长期知识的自动沉淀这是 Harness 最有工程价值的能力之一。很多 Agent 框架的“记忆”本质是把历史消息堆进上下文迟早会撑爆AgentScope Java 当前版本的做法是双层分离第一层——每日流水账每次对话结束后框架用 LLM 从当次对话中提炼“新增事实”以 bullet point 形式追加到当日的记忆文件memory/YYYY-MM-DD.md。这一层只追加、不修改保证任何新事实都不会丢失。第二层——长期记忆后台有一个调度器会周期性地读取近期的日流水账文件用 LLM 把它们与现有的MEMORY.md合并、去重、精炼输出一份在 Token 预算内的可注入版写回MEMORY.md。这一层是被每轮推理注入到 system prompt 的“事实摘要”质量高、体积受控。两层之间的关系第一层保证不丢第二层保证可用。新事实先落在流水账等积累够了由后台搬进长期记忆推理时模型优先看长期记忆找不到时用memory_search工具做全文检索基于 SQLite FTS5。对话压缩是记忆管理的另一面当对话消息数或 Token 数超过阈值Harness 用 LLM 把之前的对话压缩成一段摘要保留最近的若干条消息其余的卸载到 JSONL 文件。压缩会在提炼长期记忆之后进行确保有价值的信息先沉淀再压缩。如果模型返回了 context overflow 错误框架还会捕获异常、强制压缩、自动重试整个过程对调用方透明。配置建议.compaction(CompactionConfig.builder() .triggerMessages(50) // 消息数超过 50 触发压缩 .keepMessages(20) // 保留最近 20 条 .flushBeforeCompact(true) // 压缩前先提炼记忆默认已开启 .build())Stylus子 Agent 编排Subagent复杂任务的分解与委派当主 Agent 遇到耗时长、上下文重或可并行的子任务时可以把它委派给子 Agent 执行。子 Agent 是独立的 Agent 实例有自己的 system prompt 和 Memory不共享主 Agent 的对话历史执行结果作为一条工具结果返回给主 Agent。子 Agent 的声明方式有四种灵活度从低到高1. 内置的general-purposeAgent镜像主 Agent 的配置适合临时委派任意子任务2. 工作区文件驱动在workspace/subagents/下放 Markdown 文件YAML front matter 定义名称、描述、工具body 是 system prompt框架自动发现并加载3. 代码声明用builder.subagent(spec)编程式指定4. 自定义工厂完全控制子 Agent 的构建逻辑。工作区驱动的方式是最推荐的——子 Agent 的定义随工作区版本化不需要动代码就能调整委派策略。调用方式分同步和异步两种同步调用主 Agent 阻塞等待子 Agent 完成再继续适合必须拿到结果才能下一步的场景异步调用主 Agent 提交任务后立即拿到一个任务 ID可以继续做其他事后续用task_output工具轮询结果。对于耗时超过几秒的任务强烈建议用异步避免主 Agent 白白阻塞消耗时间与 Token。防无限递归子 Agent 默认是“叶子”形态本身不能再 spawn 子 Agent框架也有最大深度限制作为兜底。内置工具Builtin ToolsHarnessAgent构建时会自动注册一套覆盖“闭环所需”的工具无需手动配置值得注意的是在“远端共享存储”模式下框架默认不注册Shell 工具——这是一个有意的安全设计不是遗漏。如果你的业务 Agent 不需要执行命令用这个模式可以消除一整类执行安全风险。文件系统Filesystem三种模式按需选型文件系统是 Harness 连通“Agent 逻辑”与“基础设施”的关键一层。框架提供三种声明式模式选型时从业务约束出发模式一本机 Shell默认不配置filesystem或显式写filesystem(new LocalFilesystemSpec())工作区就是本机上的一个目录可以执行 Shell 命令。适合个人本机应用和开发测试环境最简单没有任何额外依赖。模式二远端共享存储配置filesystem(new RemoteFilesystemSpec(store))记忆、会话日志等关键数据路由到远端 KV如 Redis本地文件系统只存放不需要共享的内容。默认不注册 Shell 工具适合多副本在线服务、需要跨节点共享用户记忆但不需要代码执行的场景。模式三沙箱执行配置filesystem(sandboxSpec)文件读写和命令执行全部在隔离的沙箱环境里完成宿主进程不受影响。适合需要执行不可信代码的场景如 DataAgent、Coding Agent。三种模式的核心区别在于谁来执行命令、数据落在哪、隔离粒度是多少。同一套 Agent 代码逻辑切换filesystem配置就能在三种模式间迁移。沙箱Sandbox隔离执行 状态可恢复沙箱模式解决的不只是“隔离执行”更是“多轮对话中隔离环境的连续性”——这两点合在一起才真正有价值。执行边界在沙箱模式下Agent 调用的 Shell 命令、文件读写都发生在沙箱侧宿主进程只起协调作用。用户输入的任意命令不会直接影响服务器。状态可恢复每次call()结束沙箱当前的文件系统状态会被持久化快照机制。下次调用开始时框架按sessionId或userId找到对应的快照把沙箱恢复到上次结束的位置。用户不会因为服务重启或请求漂移到其他节点而丢失工作进度。工作区投影AGENTS.md、skills/、subagents/、knowledge/等宿主工作区内容在每次call()开始时会被同步到沙箱内保证沙箱里的 Agent 能看到完整的配置和技能定义。隔离粒度按需选择会话级每个会话有独立的沙箱状态互不干扰适合多用户 SaaS用户级同一用户的多个会话共享同一沙箱状态适合“用户长期工作台”类场景全局共享整个 Agent 共用一个沙箱适合工具型、只读型 Agent。真正应用于生产环境中的 Sandbox 沙箱还有更多要考虑的因素可以参考官网文档了解更多沙箱生命周期如何管理agent 内置管理、用户自行管理哪些流程需要运行在沙箱中Tool In Sandbox、Subagent in Sandbox沙箱内部状态如何管理state、snapshot 恢复。Skills工作区驱动的可复用技能Skills 是把“可复用的操作流程”结构化的方式。在工作区的skills/skill-name/目录下放一个SKILL.md框架启动时自动发现并装配进 Agent 的能力库。Agent 在推理时可以调用这些技能技能本身描述了“做这件事的步骤和规范”。这种设计的工程价值在于技能是文件可以和代码一起进 Git 版本控制、可以 Code Review、可以在不重新部署的情况下更新。当团队有大量 SOP 和操作规范需要注入 Agent 时这比把所有内容堆进 system prompt 要清晰得多。在沙箱模式下技能文件会随工作区投影同步到沙箱内技能中涉及的命令在隔离环境执行不会影响宿主。总结AgentScope Java 1.1 把 Harness Engineering 里大家最想要、却最难自己拼装的一组能力收敛成了HarnessAgent 工作区约定 可插拔文件系统 Hook 管线个人场景下它是“带记忆、带压缩、带子任务”的加强版 ReAct Agent企业场景下它是能把隔离、多租户、分布式记忆与子 Agent 编排变成配置项的基础设施。若你正在评估从个人助手原型演进到可上线的企业智能体建议从 Harness 概览[** **1]的快速开始跑通再按 Filesystem[** **2]选择一种声明式模式然后按需打开压缩、沙箱与子 Agent——每一步都有对应文档与示例模块可对照而不必从零发明一套“工作区即真理”的运行时。 
长河君 · 2026/8/6 13:26:52 · 阅读 1.2k 解决 Agent 工程化五大难题：AgentScope Java 1.1.0 交付 Harness 工程框架
书接上回我在之前的一篇文章中深入分析了 OpenClaw 及其背后的 Harness Engineering 实践同时构想了一套“Harness Framework”来讲解如何将这套理念应用到企业级智能体开发中。好消息是AgentScope Java 1.1.0 版本正式发布了在这个里程碑版本中我们完整的实现了这套“Harness Framework”规划。开发者可以基于 1.1 版本快速实践 Harness开发面向个人提效的 XxxClaw、Coding Agent 等本地应用也可以开发面向分布式场景的 DataAgent、SRE Agent 等企业级应用。AgentScope Java 1.1.0 在这个版本中交付了四项核心能力工作区驱动的 Agent 运行环境Agent 的人格、知识、技能、记忆、子 Agent 规格统一沉淀在一个结构化工作区里每次运行自动从工作区加载上下文、结束后自动回写记忆Agent 的能力随时间持续演化可插拔的抽象文件系统工作区的物理存储可以自由切换——本机磁盘、远端共享存储、隔离沙箱均通过同一套接口操作同一份 Agent 逻辑无需修改即可适配个人开发环境与企业分布式部署开箱即用的上下文管理内置对话压缩、双层记忆沉淀与全文检索解决长对话上下文膨胀和跨会话记忆丢失两个顽固问题并通过后台维护机制保证记忆库不随时间失控增长子 Agent 编排与隔离执行支持声明式定义子 Agent、同步或异步委派子任务工具执行可配置在隔离沙箱内完成并在多轮对话间保持沙箱状态可恢复兼顾多租户场景的会话与用户维度隔离。OpenClaw/Hermes 很好但在企业级智能体场景却用不起来过去一年OpenClaw、Hermes、Claude Code 等智能体产品掀起了一波热潮也带火了这些产品背后的 Harness Engineering 理念——用结构化的工作区、上下文管理与工具约定替代“每次对话各自为战”的原始使用方式。越来越多的团队开始把这套思路搬进自己的 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 的抽象接口具体实现还是要自己来。这五个问题的根源是同一件事个人助手型 Agent 和企业级 Agent 是两种不同的工程形态用同一套假设去应对两种场景必然碰壁。从部署形态看个人助手是单用户单进程所有状态都可以放在一台机器上企业级 Agent 要水平扩容、要多租户、要服务不中断状态必须能分布式存储和恢复。从安全边界看本机工具执行没有风险生产环境上任意 Shell 执行则是一个严重的攻击面沙箱和权限边界不是“可选的优化”而是“上线的前提”。从运维可观测性看个人工具出了问题自己看日志就行企业服务要求记忆落盘、会话可审计、状态变更可追踪。从Token 经济看个人用户对延迟和费用不敏感企业场景每一次无效的上下文重推都是真实的成本开销。那么有没有一款框架能让你“写一套逻辑按需切换形态”AgentScope Java 1.1.0 的 Harness 模块入口类HarnessAgent就是围绕这个目标设计的它不替换ReActAgent的推理循环而是在循环的关键时机插入 Hook补齐一组工具与工作区约定把上面五个问题的工程答案打包进来让你专注于 Agent 的业务逻辑而不是基础设施。AgentScope Harness 设计理念凭什么它能解决以上问题AgentScope Java Harness 的设计哲学可以用一句话概括把“下一轮怎么办、下一天怎么办、上下文爆了怎么办、状态丢了怎么办”的工程答案打包进来而不是让每个 Agent 项目各自发明一遍。具体到实现层面有两个核心支柱支撑起整个框架。核心支柱一Workspace 作为唯一事实来源Harness 为每个 Agent 引入了workspace 工作空间的概念——一个结构化目录用于承载 Agent 运行所需的一切持久化内容人格定义AGENTS.md、长期记忆MEMORY.md、领域知识knowledge/、可复用技能skills/、子 Agent 规格subagents/以及会话历史agents/agentId/。这并不是一个新想法——OpenClaw、Hermes 在实践中都发现让 Agent 有一个稳定的“工作台”比每次重新初始化有效得多。Harness 把这个直觉系统化了工作区是 Agent 的唯一事实来源Source of Truth所有状态的读写都围绕工作区展开而不是散落在代码、数据库和内存的各个角落。实际运行中每次推理开始前WorkspaceContextHook会把AGENTS.md、MEMORY.md、knowledge/等关键文件自动注入到 system prompt 里确保 Agent 的人格和知识在每一轮都完整呈现。Agent 运行结束后MemoryFlushHook会提炼本次对话的新事实写入记忆文件后台的MemoryConsolidator再周期性地把流水账合并成精炼的长期记忆。工作区在对话中持续演化每一次运行都比上一次“更了解”用户和任务。核心支柱二AbstractFilesystem 让工作区可以运行在任何环境工作区的理念很美好但有一个现实约束本地磁盘目录在分布式场景下行不通。多个 Pod 各有一块本地磁盘MEMORY.md写到哪里哪个副本的版本才是“真”的AgentScope Java Harness 用 AbstractFilesystem 抽象层来解决这个问题。对上层而言Agent 只需要调用统一的read/write/ls/grep等接口不关心“文件”实际落在哪对下层而言可以适配到本机磁盘、远端对象存储OSS、KV 数据库Redis、沙箱文件系统等任意介质甚至通过CompositeFilesystem把不同路径路由到不同后端。如上图所示基于 AbstractFilesystem 接口AgentScope Java 内置提供了三种拓展实现对应三种使用模式。待详细展开三种实现与模式。在 AgentScope Java 1.1 版本中workspace 是 agent 的核心抽象我们 AbstractFilesystem 作为 workspace 的物理实现载体所有文件操作、命令执行、记忆管理工具都以 AbstractFilesystem 为标准操作入口。基于这一层文件系统抽象AgentScope Java 框架直接为智能体开发带来了三大工程能力安全与隔离Shell/Code/Skill 的执行通过沙箱后端隔离用户输入驱动的命令不再直接在宿主机上运行工作区本身也可以运行在沙箱内实现文件读写层面的隔离工具的注册与暴露由框架统一管理execute工具仅在后端实现了沙箱接口时才出现。分布式部署Agent 可以多副本对等部署MEMORY.md、会话日志等关键文件通过 Remote 后端路由到共享存储天然实现跨节点同步通过IsolationScopeSESSION / USER / AGENT / GLOBAL与RuntimeContext组合在代码不变的前提下实现 session 级隔离、用户级共享等多种租户策略。Subagent 与异步任务子 Agent 的工作区、文件系统、会话状态都从父 Agent 继承或独立配置编排策略由规格声明不需要手工拼装异步任务的状态机PENDING/RUNNING/COMPLETED/FAILED/CANCELLED与结果回收机制开箱即用支持替换为跨进程实现。将 AgentScope Harness 快速映射到你的应用场景下面三个场景覆盖了从个人到企业的典型开发形态。它们并不是非此即彼的选项而是代表了三条不同的复杂度路径——你可以从最简单的一条开始随着需求演化逐步迁移。个人代理 Agent — 典型如 OpenClaw 类应用这类场景的特点单用户、本机运行、需要操作本地文件或执行脚本典型产品是个人助理、笔记机器人、本地 Coding Agent。这类场景的核心诉求是“让 Agent 真正了解我、记住我”而不只是一个无状态的问答机器。Harness 在这里的价值是工作区里的AGENTS.md定义了 Agent 的人格和行为偏好对话结束后会自动提炼新的事实写入记忆下次打开时 Agent 依然认识你、记得上次的进度。技能skills和领域知识也都住在工作区里随时可以编辑调整不需要动代码。本机部署下还可以开放 Shell 执行能力让 Agent 直接运行脚本、操作文件系统这也是 OpenClaw 类产品最有吸引力的地方。而 Harness 在此之上补上了“持续演化”的那一层工作区就像 Agent 的大脑随着每次对话变得更有经验。AgentScope Java Harness 在此场景提供的核心能力持续记忆对话结束后自动将新事实提炼写入工作区下次启动无需重新“告知”Agent 背景长期记忆随使用积累本地 Shell 执行在本机可信环境下Agent 可直接运行脚本、操作文件复现 OpenClaw 类产品的核心体验工作区即配置修改 AGENTS.md 调整人格在 skills/ 目录里新增技能改一个文件等于升级一次 Agent不需要重新编译部署会话跨进程恢复关闭再打开只要 sessionId 不变上次对话的状态全部还原不是从零开始。企业级数据服务 — 典型如 DataAgent这类场景的特点服务多个用户、需要执行 SQL / Python / Shell、任务耗时较长、输入来自不可信的外部用户同时要求多轮对话状态可恢复、多副本部署时用户体验一致。这类场景最大的风险是执行安全——用户驱动的代码不能在服务器上无限制地跑。Harness 的沙箱机制把 Agent 的文件操作和命令执行都限定在隔离环境里服务器进程本身不受影响。更关键的是沙箱不是“用完即毁”的每轮对话结束后沙箱的状态会被持久化下一轮拿回来继续用户不会因为服务重启或切换节点就丢失工作进度。多副本部署时用户的长期记忆Agent 对这个用户积累的了解可以存放在共享存储里无论请求落到哪个节点Agent 看到的都是同一份记忆。长分析任务可以拆成多个子 Agent 并行执行主 Agent 只负责协调和汇总不必一直阻塞等待。AgentScope Java Harness 在此场景提供的核心能力隔离沙箱执行所有代码与命令在隔离环境内运行宿主服务进程不受用户输入影响安全边界清晰多轮沙箱状态恢复每轮对话结束后自动保存沙箱状态下轮或下次服务启动时原位恢复用户的工作现场不丢失分布式记忆共享用户的长期记忆存放在共享存储多节点部署下所有副本读到同一份“对这个用户的了解”体验一致子 Agent 并行编排长任务可拆解为多个子 Agent 并发执行主 Agent 只做协调整体效率更高也更易管理超时与失败多租户隔离按会话或用户维度隔离工作区与执行环境多用户同时在线互不干扰。企业在线服务 — 典型如淘天交易 Agent这类场景的特点主要通过调用业务 API 完成任务下单、查询、审批等不需要在服务器上执行 Shell但需要多实例运行、会话状态可持久、跨用户的知识共享。这类场景的核心诉求是稳定与安全——在线服务不能因为 Agent 调用了一个不该调用的 Shell 命令而出事。Harness 在这里的价值是不配置沙箱执行能力时框架默认就不会暴露 Shell 工具Agent 只能通过明确定义的业务工具与外部交互安全边界由配置决定而不是靠开发者自律。会话状态和记忆可以落到远端存储多个服务实例共享同一套用户记忆用户换一个入口重新对话Agent 仍然能接续上次的上下文。需要并行处理多个子任务时比如同时查库存、计算优惠、生成摘要子 Agent 机制同样适用可以对接外部任务队列实现跨进程的任务管理。AgentScope Java Harness 在此场景提供的核心能力默认安全边界不开启沙箱执行时框架不暴露 Shell 工具Agent 只能通过你明确注册的业务工具与外部交互安全策略由配置决定多实例共享记忆会话状态与用户记忆落到远端存储任意服务实例都能读到同一份上下文用户无感知地在多实例间切换会话跨请求连续每次请求携带相同的用户标识Agent 自动恢复上次的对话状态实现真正的多轮连续对话体验并行子任务支持需要同时处理多个业务步骤时可将子任务委派给子 Agent 并行执行结果汇总后统一回复不影响主流程响应速度。AgentScope Harness 详解花点时间了解更多框架详情吧本节将从使用者视角讲清楚 AgentScope Java Harness 的核心能力它是什么、怎么工作、配置时应该怎么想。快速开始 - Quick Start上手 Harness 只需三步引入依赖、准备工作区、构建并调用 Agent。1. 引入依赖dependency groupIdio.agentscope/groupId artifactIdagentscope-harness/artifactId version${agentscope.version}/version /dependencyDust2. 准备工作区在磁盘上选一个目录作为workspace并在其中创建AGENTS.md。这不是“可选的初始化步骤”而是 Harness 的核心入口——Agent 的人格、记忆、技能、子 Agent 规格全部围绕这个目录展开。AGENTS.md内容简单写几行约定就够后续随使用不断演化。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();X86asm运行后检查工作区目录AGENTS.md、memory/、agents/agentId/三个路径都应该存在这说明 Agent 已经在正常写入记忆和持久化会话状态了。完整可运行示例见agentscope-examples/harness-example中的QuickstartExample。核心概念 - Concepts理解下面六个概念基本就掌握了 Harness 的运行逻辑。概念定义解决的问题使用建议HarnessAgent基于ReActAgent的工程化封装入口build()时装配 Hook、内置工具、技能与会话持久化不想从零拼装压缩、记忆、会话、子任务、文件系统业务代码只与HarnessAgent.builder()和agent.call(msg, ctx)打交道workspaceAgent 的工作目录承载AGENTS.md、MEMORY.md、skills/、subagents/、会话历史等全部持久化内容人格、知识、记忆、状态放哪、如何持续演化先规划工作区结构再写 prompt把工作区当作可版本化的资产filesystem文件读写的统一接口是 Agent 工具层与物理存储之间的抽象层支持本地磁盘、远端存储、沙箱等多种后端同一套 Agent 逻辑如何在本地、共享存储、沙箱间切换优先从三种声明式模式选型Local / Remote / SandboxRuntimeContext单次call()的身份上下文包含sessionId、userId等每次调用重新传入不持久化这一轮是谁、状态读写到哪、多租户如何隔离必须稳定传sessionId多租户场景必须传userIdsandbox隔离执行环境文件操作与命令在沙箱侧运行每轮对话结束后持久化状态、下轮恢复如何在不信任输入下安全执行工具与脚本并保持多轮状态连续有代码执行需求时优先启用根据业务选择隔离粒度memory双层记忆系统每轮对话后自动提炼写入流水账后台周期性合并成可注入的长期记忆配合全文检索长对话不丢事实、上下文不爆、历史可检索开启对话压缩并观察记忆文件变化旧事实用搜索工具回捞总纲HarnessAgent负责编排workspace负责沉淀filesystem负责落点RuntimeContext负责身份sandbox负责边界memory负责长期演化。功能详情 - Features工作区WorkspaceAgent 的唯一事实来源工作区是 Harness 区别于普通 Agent 框架最重要的设计。它不是一个临时存储目录而是 Agent 的“大脑外化”——所有需要跨会话保留的内容都住在这里。工作区的标准目录结构如下workspace/ ├── AGENTS.md ← Agent 人格与行为约定每次推理前自动注入 system prompt ├── MEMORY.md ← 精炼的长期记忆由后台自动维护随使用积累 ├── knowledge/ ← 领域知识随 AGENTS.md 一起注入 ├── skills/ ← 可复用技能自动装配到 Agent 的工具集 ├── subagents/ ← 子 Agent 规格声明自动被发现和加载 └── agents/agentId/ ├── context/ ← 会话状态快照进程重启后恢复用 ├── sessions/ ← 对话 JSONL 与压缩上下文供审计与检索 └── memory/ ← 每日记忆流水账Nix工作区在每次推理中如何工作推理开始前Harness 把AGENTS.md、MEMORY.md、knowledge/等关键文件拼入 system prompt推理结束后把本次对话中出现的新事实提炼出来追加到当日的记忆流水账。工作区随每次对话持续演化Agent 随时间变得“更了解”它面对的业务和用户。为什么工作区优于把 prompt 写死在代码里人格、知识、技能和子 Agent 规格都在工作区的文件里调整行为只需要改文件不需要重新编译和部署。对于有复杂业务知识的 Agent这一点尤其关键——业务规则随时在变更新应该轻量。会话持久化Session跨请求、跨进程的状态连续Harness 把会话状态落盘分成两条并行的路径它们各自解决不同的问题状态快照context/每次call()结束后Agent 的运行状态当前的对话记忆、工具执行上下文等序列化为 JSON 文件存到工作区的agents/agentId/context/sessionId/下。下次用相同sessionId发起调用时框架在推理开始前自动加载这份快照恢复到上次结束的位置。这是“关掉再打开仍然记得上次”的技术保障。对话日志sessions/完整的对话历史以 JSONL 格式追加写入sessionId.log.jsonl这个文件永远不会被压缩供审计和session_search工具使用。另有一份sessionId.jsonl存放压缩后的 LLM 上下文是模型实际“看到”的版本。两条路径都由框架自动维护开发者唯一需要做的是每次调用时稳定传入相同的sessionId。记忆管理Memory从对话到长期知识的自动沉淀这是 Harness 最有工程价值的能力之一。很多 Agent 框架的“记忆”本质是把历史消息堆进上下文迟早会撑爆AgentScope Java 当前版本的做法是双层分离第一层——每日流水账每次对话结束后框架用 LLM 从当次对话中提炼“新增事实”以 bullet point 形式追加到当日的记忆文件memory/YYYY-MM-DD.md。这一层只追加、不修改保证任何新事实都不会丢失。第二层——长期记忆后台有一个调度器会周期性地读取近期的日流水账文件用 LLM 把它们与现有的MEMORY.md合并、去重、精炼输出一份在 Token 预算内的可注入版写回MEMORY.md。这一层是被每轮推理注入到 system prompt 的“事实摘要”质量高、体积受控。两层之间的关系第一层保证不丢第二层保证可用。新事实先落在流水账等积累够了由后台搬进长期记忆推理时模型优先看长期记忆找不到时用memory_search工具做全文检索基于 SQLite FTS5。对话压缩是记忆管理的另一面当对话消息数或 Token 数超过阈值Harness 用 LLM 把之前的对话压缩成一段摘要保留最近的若干条消息其余的卸载到 JSONL 文件。压缩会在提炼长期记忆之后进行确保有价值的信息先沉淀再压缩。如果模型返回了 context overflow 错误框架还会捕获异常、强制压缩、自动重试整个过程对调用方透明。配置建议.compaction(CompactionConfig.builder() .triggerMessages(50) // 消息数超过 50 触发压缩 .keepMessages(20) // 保留最近 20 条 .flushBeforeCompact(true) // 压缩前先提炼记忆默认已开启 .build())Stylus子 Agent 编排Subagent复杂任务的分解与委派当主 Agent 遇到耗时长、上下文重或可并行的子任务时可以把它委派给子 Agent 执行。子 Agent 是独立的 Agent 实例有自己的 system prompt 和 Memory不共享主 Agent 的对话历史执行结果作为一条工具结果返回给主 Agent。子 Agent 的声明方式有四种灵活度从低到高1. 内置的general-purposeAgent镜像主 Agent 的配置适合临时委派任意子任务2. 工作区文件驱动在workspace/subagents/下放 Markdown 文件YAML front matter 定义名称、描述、工具body 是 system prompt框架自动发现并加载3. 代码声明用builder.subagent(spec)编程式指定4. 自定义工厂完全控制子 Agent 的构建逻辑。工作区驱动的方式是最推荐的——子 Agent 的定义随工作区版本化不需要动代码就能调整委派策略。调用方式分同步和异步两种同步调用主 Agent 阻塞等待子 Agent 完成再继续适合必须拿到结果才能下一步的场景异步调用主 Agent 提交任务后立即拿到一个任务 ID可以继续做其他事后续用task_output工具轮询结果。对于耗时超过几秒的任务强烈建议用异步避免主 Agent 白白阻塞消耗时间与 Token。防无限递归子 Agent 默认是“叶子”形态本身不能再 spawn 子 Agent框架也有最大深度限制作为兜底。内置工具Builtin ToolsHarnessAgent构建时会自动注册一套覆盖“闭环所需”的工具无需手动配置值得注意的是在“远端共享存储”模式下框架默认不注册Shell 工具——这是一个有意的安全设计不是遗漏。如果你的业务 Agent 不需要执行命令用这个模式可以消除一整类执行安全风险。文件系统Filesystem三种模式按需选型文件系统是 Harness 连通“Agent 逻辑”与“基础设施”的关键一层。框架提供三种声明式模式选型时从业务约束出发模式一本机 Shell默认不配置filesystem或显式写filesystem(new LocalFilesystemSpec())工作区就是本机上的一个目录可以执行 Shell 命令。适合个人本机应用和开发测试环境最简单没有任何额外依赖。模式二远端共享存储配置filesystem(new RemoteFilesystemSpec(store))记忆、会话日志等关键数据路由到远端 KV如 Redis本地文件系统只存放不需要共享的内容。默认不注册 Shell 工具适合多副本在线服务、需要跨节点共享用户记忆但不需要代码执行的场景。模式三沙箱执行配置filesystem(sandboxSpec)文件读写和命令执行全部在隔离的沙箱环境里完成宿主进程不受影响。适合需要执行不可信代码的场景如 DataAgent、Coding Agent。三种模式的核心区别在于谁来执行命令、数据落在哪、隔离粒度是多少。同一套 Agent 代码逻辑切换filesystem配置就能在三种模式间迁移。沙箱Sandbox隔离执行 状态可恢复沙箱模式解决的不只是“隔离执行”更是“多轮对话中隔离环境的连续性”——这两点合在一起才真正有价值。执行边界在沙箱模式下Agent 调用的 Shell 命令、文件读写都发生在沙箱侧宿主进程只起协调作用。用户输入的任意命令不会直接影响服务器。状态可恢复每次call()结束沙箱当前的文件系统状态会被持久化快照机制。下次调用开始时框架按sessionId或userId找到对应的快照把沙箱恢复到上次结束的位置。用户不会因为服务重启或请求漂移到其他节点而丢失工作进度。工作区投影AGENTS.md、skills/、subagents/、knowledge/等宿主工作区内容在每次call()开始时会被同步到沙箱内保证沙箱里的 Agent 能看到完整的配置和技能定义。隔离粒度按需选择会话级每个会话有独立的沙箱状态互不干扰适合多用户 SaaS用户级同一用户的多个会话共享同一沙箱状态适合“用户长期工作台”类场景全局共享整个 Agent 共用一个沙箱适合工具型、只读型 Agent。真正应用于生产环境中的 Sandbox 沙箱还有更多要考虑的因素可以参考官网文档了解更多沙箱生命周期如何管理agent 内置管理、用户自行管理哪些流程需要运行在沙箱中Tool In Sandbox、Subagent in Sandbox沙箱内部状态如何管理state、snapshot 恢复。Skills工作区驱动的可复用技能Skills 是把“可复用的操作流程”结构化的方式。在工作区的skills/skill-name/目录下放一个SKILL.md框架启动时自动发现并装配进 Agent 的能力库。Agent 在推理时可以调用这些技能技能本身描述了“做这件事的步骤和规范”。这种设计的工程价值在于技能是文件可以和代码一起进 Git 版本控制、可以 Code Review、可以在不重新部署的情况下更新。当团队有大量 SOP 和操作规范需要注入 Agent 时这比把所有内容堆进 system prompt 要清晰得多。在沙箱模式下技能文件会随工作区投影同步到沙箱内技能中涉及的命令在隔离环境执行不会影响宿主。总结AgentScope Java 1.1 把 Harness Engineering 里大家最想要、却最难自己拼装的一组能力收敛成了HarnessAgent 工作区约定 可插拔文件系统 Hook 管线个人场景下它是“带记忆、带压缩、带子任务”的加强版 ReAct Agent企业场景下它是能把隔离、多租户、分布式记忆与子 Agent 编排变成配置项的基础设施。若你正在评估从个人助手原型演进到可上线的企业智能体建议从 Harness 概览[** **1]的快速开始跑通再按 Filesystem[** **2]选择一种声明式模式然后按需打开压缩、沙箱与子 Agent——每一步都有对应文档与示例模块可对照而不必从零发明一套“工作区即真理”的运行时。