AgentScope Java Harness Framework：把 OpenClaw 带到企业分布式场景

核心观点

AgentScope Java 1.1.0 正式实现了完整的 Harness Framework——解决 OpenClaw/Hermes 等个人 Agent 在企业级场景"用不起来"的五大障碍：多用户工作区隔离、工具安全执行、分布式文件系统、Multi-Agent 编排、上下文压缩与分层记忆。核心设计哲学：写一套逻辑，按需切换形态（个人→企业→在线服务）。

四项核心交付能力：

1. 工作区驱动的 Agent 运行环境
2. 可插拔的抽象文件系统
3. 开箱即用的上下文管理（压缩+双层记忆+全文检索）
4. 子 Agent 编排与隔离执行

个人 Agent vs 企业 Agent 的五大障碍

根源：个人助手和企业级 Agent 是两种不同的工程形态——部署形态、安全边界、运维可观测性、Token 经济四个维度的要求完全不同。

两大核心支柱

支柱一：Workspace 作为唯一事实来源

workspace/
├── AGENTS.md              ← 人格与行为约定，每次推理前注入 system prompt
├── MEMORY.md              ← 精炼长期记忆，后台自动维护
├── knowledge/             ← 领域知识
├── skills/                ← 可复用技能（文件即配置）
├── subagents/             ← 子 Agent 规格声明
└── agents//
    ├── context/           ← 会话状态快照（跨进程恢复）
    ├── sessions/          ← 对话 JSONL + 压缩上下文
    └── memory/            ← 每日记忆流水账

运行时 Hook 机制：

• 推理前：WorkspaceContextHook 注入 AGENTS.md/MEMORY.md/knowledge 到 system prompt
• 推理后：MemoryFlushHook 提炼新事实写入记忆
• 后台：MemoryConsolidator 周期性合并流水账为精炼长期记忆

支柱二：AbstractFilesystem 抽象文件系统

统一 read/write/ls/grep 接口，底层适配：

• 本机磁盘
• 远端对象存储（OSS）
• KV 数据库（Redis）
• 沙箱文件系统
• CompositeFilesystem（不同路径路由不同后端）

六大核心概念

总纲：HarnessAgent 编排，workspace 沉淀，filesystem 落点，RuntimeContext 身份，sandbox 边界，memory 演化。

记忆管理：双层分离

架构

对话结束
  → MemoryFlushHook 提炼新事实
    → 追加到 memory/YYYY-MM-DD.md（第一层：只追加不修改）
      → 后台 MemoryConsolidator 定期触发
        → 读取近期流水账 + 现有 MEMORY.md
          → LLM 合并/去重/精炼（Token 预算内）
            → 写回 MEMORY.md（第二层：可注入版）

第一层——每日流水账：对话结束后 LLM 从当次对话中提炼"新增事实"，以 bullet point 形式追加到 memory/YYYY-MM-DD.md。只追加不修改，保证任何新事实不丢失。

第二层——长期记忆：后台调度器周期性读取近期流水账 → 与 MEMORY.md 合并/去重/精炼 → 输出一份 Token 预算内的"可注入版"写回 MEMORY.md。这是每轮推理注入到 system prompt 的"事实摘要"。

两层关系：第一层保证不丢，第二层保证可用。新事实先落在流水账，积累够了由后台搬进长期记忆。

检索：memory_search 工具基于 SQLite FTS5 全文检索。推理时模型优先看长期记忆，找不到时用 memory_search 回捞历史。

对话压缩：消息数或 Token 超阈值 → LLM 压缩历史为摘要 → 保留最近 N 条 → 旧消息卸载到 JSONL。压缩在提炼记忆之后执行，确保有价值信息先沉淀再压缩。如果模型返回 context overflow 错误，框架捕获异常、强制压缩、自动重试，对调用方透明。

配置示例

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

三种文件系统模式

远端共享存储模式的安全设计

不配置沙箱时框架默认不暴露 Shell 工具——这是有意的安全设计。Agent 只能通过明确定义的业务工具与外部交互，安全边界由配置决定而不是靠开发者自律。

沙箱模式详细

沙箱解决两个问题：隔离执行 + 多轮状态连续。

• 执行边界：Shell/文件读写都在沙箱侧，宿主进程只协调，用户输入不直接影响服务器
• 状态可恢复：每次 call() 结束后沙箱状态持久化（快照），下次按 sessionId/userId 恢复到上次位置
• 工作区投影：AGENTS.md/skills/subagents/knowledge 在每次 call() 开始时同步到沙箱内
• 隔离粒度（按需选择）：
  • 会话级：每个会话独立沙箱，互不干扰（多用户 SaaS）
  • 用户级：同一用户多会话共享沙箱（用户长期工作台）
  • 全局共享：整个 Agent 共用一个沙箱（只读/工具型 Agent）

子 Agent 编排

四种声明方式（灵活度从低到高）

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

调用方式

• 同步：主 Agent 阻塞等待结果，适合必须拿到结果才能下一步的场景
• 异步：提交任务拿到 task ID → 主 Agent 继续做其他事 → 用 task_output 轮询结果。耗时超几秒的任务强烈推荐异步

状态机

异步任务状态：PENDING → RUNNING → COMPLETED / FAILED / CANCELLED

安全约束

• 子 Agent 默认是"叶子"形态，不能再 spawn 子 Agent
• 框架有最大深度限制兜底
• 子 Agent 的工作区/文件系统/会话状态从父 Agent 继承或独立配置

三种典型场景

场景一：个人代理 Agent（OpenClaw 类）

单用户、本机运行、操作本地文件/执行脚本。核心诉求："让 Agent 真正了解我、记住我"。

提供能力：

• 持续记忆：对话结束自动提炼写入，下次启动无需重新告知背景
• 本地 Shell 执行：直接运行脚本/操作文件
• 工作区即配置：改 AGENTS.md 调人格，skills/ 加技能，不需要编译部署
• 会话跨进程恢复：关闭再打开，sessionId 不变状态全部还原

场景二：企业数据服务（DataAgent）

多用户、执行 SQL/Python/Shell、任务耗时长、输入不可信。

提供能力：

• 沙箱隔离执行：代码和命令在隔离环境运行，宿主不受影响
• 多轮沙箱状态恢复：每轮结束保存状态，下轮原位恢复，不因重启/切节点丢进度
• 分布式记忆共享：用户长期记忆在共享存储，多节点看到同一份
• 子 Agent 并行编排：长任务拆解为子 Agent 并发执行
• 多租户隔离：按会话或用户维度隔离

场景三：企业在线服务（淘天交易 Agent）

通过业务 API 完成任务（下单/查询/审批），不执行 Shell，多实例运行。

提供能力：

• 默认安全边界：不开沙箱时不暴露 Shell，Agent 只能用明确注册的业务工具
• 多实例共享记忆：会话状态和记忆落远端存储，实例间无感切换
• 会话跨请求连续：携带相同用户标识，自动恢复对话状态
• 并行子任务：多个业务步骤委派子 Agent 并行，不阻塞主流程

会话持久化

两条并行路径：

状态快照（context/）：每次 call() 结束后，Agent 运行状态序列化为 JSON → 存到 agents//context/sessionId/。下次相同 sessionId 调用时自动加载恢复。

对话日志（sessions/）：

• .log.jsonl：完整对话历史，永不压缩，供审计和 session_search
• .jsonl：压缩后的 LLM 上下文，是模型实际"看到"的版本

开发者唯一需做：每次调用稳定传入相同 sessionId。

内置工具

HarnessAgent 构建时自动注册覆盖"闭环所需"的工具集：

远端共享存储模式默认不注册 Shell 工具——有意的安全设计。

Quick Start

HarnessAgent agent = HarnessAgent.builder()
    .name("my-agent")
    .model(model)
    .workspace(Paths.get(".agentscope/workspace"))
    .compaction(CompactionConfig.builder()
        .triggerMessages(50)
        .keepMessages(20)
        .build())
    .build();

RuntimeContext ctx = RuntimeContext.builder()
    .sessionId("user-session-001")
    .userId("alice")
    .build();

Msg reply = agent.call(userMessage, ctx).block();

关键概念

• Harness Engineering
• OpenClaw
• Agent
• Context Engineering

关联页面

• 深入源码：Hermes Agent 如何实现 Self-Improving — 个人 Agent 的记忆/技能自演化
• 从零设计生产级Multi-Agent Harness全拆解 — Harness 五大模块设计
• Harness Engineering-耗时一周AI Coding率提升至90 — 企业 Harness 实战
• Agent时代的生产力悖论-当协作本身成为最大的瓶颈 — 组织结构需适配 Agent