AI 工程小册

主题

AgentScope 运行时体系 ​

定位：引擎层核心——控制面 + 数据面 + 状态存储的统一视图。

一句话：agentscope-service 不是一组接口，而是“控制面管期望状态、数据面管实际执行、存储层管可恢复性”的三层运行时；接入层（统一体验层 / HiMarket 产品壳）要包住它，前提是用同一张图看懂组件链路、状态语义与成熟度边界。

版本适用：AgentScope Service 2.1.0-BETA1 / AgentScope Java 2.0.x。

整合说明：本篇合并吸收旧 06 篇（内核概念设计）、07 篇（组件分工）、12 篇（存储分层）、35 篇（接口清单），并以 41 篇源码实证（D:\build\agentscope-java\agentscope-service 本地源码 + 本机运行实证）为主线重写。全文用两套标记区分语义：✅ 实证＝源码坐实或本机实机闭环；🔧 平台层补充＝原生无对应物、由平台侧（产品壳/缝合层）新增的设计。引擎保持原版，🔧 项全部落在平台侧，不侵入引擎。

为什么需要统一视图 ​

单看任何一篇旧文档都会遇到同一个问题：组件、状态、接口分散在五份资料里，口径还不一致。内核篇讲 HarnessAgent 循环但不讲端口；分工篇讲控制面/数据面但不讲落到哪张表；存储篇讲 Redis 键族但不知道默认路径根本不写它；接口篇列了 38 个 Controller 但不标哪些路由实测可用、哪些是 beta 坑。真正开工时会连续撞上四类故障：

  1. 按“内核能跑”理解平台，结果发现会话状态默认不在 AgentStateStore 而在 journal——恢复语义理解错误；
  2. 按接口清单直调，结果踩中 LEGACY 模式必 NPE、channels 404、definition 嵌套 body 400 这类 beta 坑；
  3. 按“全放 Redis 就完事”设计存储，结果发现 lease、workDir、子进程、SSE 连接这些执行亲和性 Redis 存不了；
  4. 把概念设计当原生能力做产品承诺，结果 ContextManifest、十项检查点字段在源码里不存在。

所以需要一篇文档把“有哪些组件、各管什么、状态在哪、接口怎么调、哪里是坑”收进同一张视图，并逐条标实证/设计。以下按 组件全景 → 控制面 → 数据面内核 → 状态与存储 → 接口速查 → 场景链路 六段展开。

§一 组件全景 ​

四层结构：入口与外部依赖 → 控制面（期望状态权威）→ 数据面（执行语义权威）→ 存储层（可恢复性底座）。网关是唯一入口，UI 和 API 都经它；控制面管“该有哪些 Agent、资源怎么挂”，数据面管“turn 怎么跑、在哪跑”；所有执行状态、凭据、工作区落 Postgres + 命名卷，容器销毁后不丢。✅

组件分工表（✅，源码 + 运行实证）：

组件职责不负责
Gateway统一入口、认证、租户/命名空间路由、公共 API、SSE 代理模型循环、任务状态
Control（Go）Agent 目录、Team、编排定义、Namespace、Binding/Policy、审计执行 Turn
SchedulerChannel、Cron、出站任务、Hosted Worker 协调模型能力
Dataplane（Java）Managed Agent 的推理循环、会话 Brain、Worker 协议服务端跨租户治理、计费
PostgreSQL控制面/运行面权威状态（dp.* 29 表）大对象存储
Redis（可选后端）分布式 journal、文件内容、视图物化、预算账本进程与执行现场
workspaces 命名卷工作区与产物持久化，data+control 共享并发锁
Console/UIChat、Issue、目录与运行观察业务逻辑

判断控制面与数据面是否真分开，看三条：控制面发布是否影响运行中的会话；Dataplane 重启后会话能否恢复；一次执行能否按事件流还原用了哪个定义版本。✅ 三条在本机均闭环（会话恢复走 journal 重放，见 §四）。

§二 控制面 ​

2.1 领域模型：授权边界 → 逻辑身份 → 资源三层解耦 ✅ ​

一句话读法：Tenant→Namespace 是授权边界（谁能用）；Agent 是逻辑身份（是什么）；Binding 决定挂哪种资源；Policy 决定选哪个候选；Environment/Worker 决定在哪执行、怎么钉节点；Workspace/Memory/Vault 是状态与凭据的持久化归属。Agent 只声明三件套引用（default_environment_id / default_vault_ids / default_memory_store_ids），会话创建时可覆盖，控制面把引用解析成真实配置注入数据面。✅

生命周期状态机 ✅（坑 K3 实证）：

2.2 五种接入模式 ​

模式资源形态谁运行模型循环适用成熟度
Managedbinding.kind=managed，definition 存 dp.builder_agentDataplane零代码托管、平台负责生命周期；当前主力路径✅ 全链实证
Externalbinding.kind=external-application，resolver selectExternal + instanceSelector自己的应用进程已有代码与部署，保留框架控制权源码坐实；注册接口不校验调用者身份，信任边界必须放网关层
Hostedbinding.kind=hosted-runtime + RuntimeProfile/Pool/Host（opencode 池、qwenpaw 池）你主机上的 daemon（编码 Agent）复用 opencode、qwenpaw 等编码 Harness；容量 capacity≤50 + hostSelector源码坐实，协议链路与 §三 Worker 协议同构
SelfHostedWorkerEnvironment type=self_hosted + Worker 协议（poll/ack/heartbeat），principal=env:{envId}Worker 本地执行工具（Brain 不持有沙箱）Claude 式自持执行；企业数据不出域；opencode 代理管控的落点✅ 源码坐实 + 协议链路部分实证
Channel渠道适配器（企业 IM 等入口收口，ChannelsHubPage）外部平台触发、会话仍由上述四模式执行消息平台入口🔶 beta 限制：channels 面实测 404（K3 契约滞后），入口收口由平台侧网关承接

五种模式的共同点是“统一目录 + 统一会话入口”，不同点是信任边界：Managed 把代码与状态交给平台；External 只登记身份与路由；Hosted/SelfHosted 把执行留在你机器，平台只调度与协调。三者（及模式间）的能力承诺不可混用，尤其是恢复、审批与产物管理。

调度裁决 ✅（resolver.go）：优先级 task/node 显式指定 > Team member 策略 candidates[0] > Agent 策略 candidates[0]，selectionMode=ordered 取策略列表第一个，不做运行时负载感知均衡；跨租户实例选择被 resolver 拒绝；按 binding.kind 三路分派（managed → data plane 直接执行；hosted → enqueueWork 等 worker 认领；external → 外部执行体）。

2.3 端口与协议 ✅ ​

端口/通道协议内容
:18080HTTP（Gateway 唯一入口）登录 JWT、公共 API 路由、UI 静态资源、SSE 代理
control → dataplane内部 REST（/api/internal/*）期望状态下发、vault 凭据解析注入、attempt/session mirror；接入层不直接依赖其语义
Worker ↔ dataplaneHTTP 长轮询 pullclaimWork(timeoutMs)、ack(workId, workDir)、heartbeat、pending-tools / tool-results
:3002MCP（Streamable HTTP/SSE/STDIO 协商）opencode 桥等外部执行体，docker run 一次性容器，产物落宿主 workdir
PostgresTCPdp.* 29 张表：agent / env / worker / work / lease / session / memory / vault
Redis :6379（可选）RESPbuilder.store.backend=redis 装配 RedisStore + RedisAgentStateStore，Lua EVAL + hash tag
模型经 compose K4 六件套 env 注入qwen3.8-max 实证生效（budgets ledger settle 记录）

2.4 版本与发布语义 ​

资源版本规则落地含义
Agent 定义正整数 version，PATCH 乐观锁并发修改冲突 409
Workspace草稿可编辑，HeadVersion + revisions 发布改草稿不等于改已发布
编排（Workflow）draftSpec 可编辑，发布后 revision 不可变Run 固定一个 revision
Session创建时固定 Agent 定义与运行配置已有会话不自动升级
Memory 文档每次 PUT 生成新 headVersion乐观锁 + 历史保留 ✅（builder_memory / builder_memory_version）

核心是发布与运行解耦：发布产生不可变 revision，运行中会话绑定旧 revision；回滚是把入口指回旧版本，不是改定义。🔧 Release 六要素冻结（模型/Harness/上下文/能力/运行时/评测 → release_id + manifest_sha256）为平台层补充设计——原生按资源各自版本化，无跨要素聚合的发布单元；漏冻结的后果（“代码没变、行为变了”）由平台壳在发布校验时兜。

2.5 成熟度标注（beta 级，实证后定稿）🔶 ​

agentscope-service 当前为 beta 级，实测问题密度高，生产姿势是“引擎做底层、平台做容错、上游提 issue 跟踪”：

坑现象处置
channels 404渠道面契约滞后（K3）入口收口走平台网关，不依赖原生 channels API
LEGACY 模式任何 turn 必 NPEAgentTraceMiddleware 无条件访问未初始化的 SessionRecorder → turn 执行侧不可用保持 LEGACY_HISTORY=false（默认 EVENT_LOG）；LEGACY 键族仅装配初始化产物
UI Chat 缺陷会话未进执行管线 / 历史读空 / events 403（台账 #9/#10）接入层绕开官方 main 的 UI 路径，直接走公共 API
PG 事件 seq 双写冲突上游 K18事件读走 journal/SSE 公共面
HITL 无超时回收requires_action 工单悬挂（K3 缺口）平台侧加超时巡检与人工兜底
MCP 桥挂 → turn 永久卡死坑 K8，终态 TERMINATED桥健康检查 + 断桥降级
definition 请求体形态嵌套 {definition:{}} → 400；PATCH 平铺 body 生效接入层固定平铺 body + 乐观锁 409 重读
ownerRef 非法显式传 tenant/namespace=default 导致 agentId 非法（K3-b）创建时不带租户头，owner 自动等于 userId

§三 数据面内核 ​

3.1 HarnessAgent 循环 ✅ ​

内核把一轮执行拆成可拦截、可持久化、可恢复的阶段，而不是“帮你调模型的库”：

两个容易看错的落点：权限检查在工具执行之前、不在模型之前；压缩发生在工具结果回填之后、下一次推理之前。Agent 是无状态执行引擎：会话状态按 (userId, sessionId) 寻址，同一会话的 turn 由执行门（turn lease）串行，不同会话并行；推荐共享 Builder + 每请求构建 + 用完关闭，不把实例当全局单例、不把会话状态塞实例字段。数据面侧还有执行面状态机 ✅（SessionTurnRunner）：QUEUED → RUNNING → REQUIRES_ACTION ⇄ RUNNING → IDLE/TERMINATED，取消与恢复都带 fence 令牌（agentTaskId+attemptId+dispatchGeneration+turnId 的 SHA-256），旧请求永远杀不掉新 turn；挂起时保留 work-lease，让 worker 干完 pending tools 后回填恢复。

真实 API（源码实证，ReActAgent.java:1409）：

java
// 入口签名：prepareRun(List<Msg>, RuntimeContext)，返回 AgentRun（AutoCloseable）
AgentRun<String> run = agent.prepareRun(List.of(new Msg("user", question)), runtimeContext);
try (run) {
    String answer = run.call();   // 执行一轮：装配 → 推理 → 工具 → 回填 → 输出事件
}
// RuntimeContext 承载 (userId, sessionId, 冻结版本)；Dataplane 传入，内核按槽位寻址状态

3.2 Toolkit 与工具策略 ​

  • 工具三种写法：实现 AgentTool、@Tool / @ToolParam 注解方法、内置工具；Toolkit 统一注册、暴露 JSON Schema 并分发调用。✅
  • 三层权限模型：平台访问权限（谁能改 Agent、用 Environment、挂 Vault）→ 工具集 enabled（能否选）→ permissionPolicy（能否执行），三档 always_allow / always_ask / deny；未配置时内置工具默认允许、MCP 工具默认询问。✅
  • MCP：STDIO / SSE / Streamable HTTP 三传输自动协商与工具发现，命名 mcp__{server}__{tool}；带 readOnlyHint 的工具可自动放行。✅
  • 技能以 SKILL.md 表达、按路径加载；ToolGroup 把工具分命名集合整体启停。装配原则是按任务收窄，不全量挂载——工具越多选错概率越高、权限面越大。
  • 目录 ≠ 注册 ≠ 授权：模型在工具目录里看到某工具，不等于 Toolkit 注册了它，更不等于当前任务被授权调用它；三层任一层缺失都应在执行前拒绝。这是内核只提供拦截点、授权结论来自策略层的边界共识。
  • deny 必须返回机读 reason code 与可替代动作，不把拒绝伪装成“工具执行失败”——否则模型换参数反复重试，一次越权变十次。🔧 该动作语义（Action Request、Preview→Approve→Commit→Verify、params_digest 绑定审批、幂等键）为平台层补充：原生提供 turn 级 fence、tool_confirmation 通道与 action 观测记录（LEGACY 下 action_{id}_started/_settled CAS 防重放 ✅），完整动作契约由平台壳在工具网关上补齐。

三路判定与审批回路（前三道闸门全绿才谈策略分支；always_ask 走的是原生 requires_action + tool_confirmation 链路 ✅）：

三点读法：被拒也要有记录（否则越权尝试在观测面是空白，与 14 篇“拒绝也要留 span”同一条纪律）；询问态不释放 work-lease，工具执行权仍归原 Worker，审批回来后不换执行现场；未配置策略时的默认值不同——内置工具默认允许、MCP 工具默认询问，把 MCP 默认改成允许等于把外部服务的执行权交给模型自选。

3.3 上下文装配机制（平台层补充） ​

原生装配行为 ✅：每轮请求模型前重新准备上下文，顺序 System → 对话历史（含摘要）→ 当前状态 → 参考材料；大工具结果超 80,000 字符落盘、首尾各留 2,000 字符预览；约 50 条消息或达预算时触发压缩检查；压缩不切断工具调用与结果的配对；模型未报窗口时按 64,000 token 预算回退。

🔧 ContextManifest 为平台层补充：内核概念稿中的“每次装配生成清单（callId、用途、token 数、条目、变换、校验结果）”在源码中无对应实体。原生可解释性由三件套承担 ✅：journal 事件流（item.* / tool.requested / tool.completed / usage.recorded，454 事件实测聚类）、views/sess_{id}/v2 物化会话视图、默认关闭的 trace 敏感面（GET .../trace，游标读 journal 原文）。平台壳做上下文审计时，应从 journal 派生 Manifest 视图，而不是要求引擎新增装配对象。

3.4 执行体与 Worker 协议：钉同一节点 ✅ ​

机制答案：一个 Environment 对应的 Worker 持续 poll 同一 session 的工作队列，ack 携带固定 workDir（${java.io.tmpdir}/agentscope-hands/{sessionId}），配合 workspaces 命名卷持久化——容器可销毁重建，但工作区与队列归属不变，迭代自动续接。

任务型负载算法 ✅：无中心调度器 push，靠 worker 主动拉取 + 数据库原子认领（@Lock(PESSIMISTIC_WRITE)，条件 QUEUED 或 (STARTING/ACTIVE 且过 stale 阈值)，ORDER BY createdAt ASC——FIFO + 故障回收，双 worker 不认领同一任务）；容量 = worker 数量（每 worker 串行 1 任务，扩容即加 worker）；负载均衡的“均衡”发生在认领竞争而非分派计算。

耗时工具两段式 ✅：AsyncToolMiddleware 超过 offloadTimeout 未完成 → 发占位事件、turn 先返回不阻塞，真实执行转入后台，完成写 AsyncToolRegistry，后续回合经 inbox/messageBus（默认 workspace 文件队列，RemoteFilesystem 多副本共享）在下一轮推理前注入结果——队列即状态，连接不是状态载体。

执行体生命周期 ✅：Brain 不持有 live sandbox——hands 工具 schema-only、turn 挂起，由 Environment Worker 认领 work、本地执行工具、回填 user.tool_result 恢复 turn；沙箱（E2B 微VM、容器、本地进程）的生命周期所有权全在 worker 侧，dataplane 只有引用与调度语义，扩执行体即扩 worker。

连接模型 ✅（四种形态，不是“都是长连接”）：提交 turn 是 REST 202 + Idempotency-Key；进度是 SSE 只读事件流（15s keepalive、游标回放，SessionEventCursor 编码不透明游标）；worker 是 HTTP 长轮询 pull；工具执行是事件驱动两段式（pending → results）。

§四 状态与存储 ​

4.1 五类数据五种存储 🔧（选型原则）+ 后端对位 ✅ ​

平台数据至少五种，生命周期、访问模式、一致性要求各不相同——根因是把“状态”当成一种东西：

数据特征推荐存储不该用什么
会话状态小、频繁、按会话寻址Redis / MySQL / MongoDB（带版本 CAS）进程内存、对象存储
长期记忆追加写、周期合并、按用户隔离远端文件系统 / 对象存储 + 索引只放向量库
工作区文件目录语义、随机读写、沙箱挂载远端文件系统 / NAS·CephFS纯对象存储
产物与快照大、一次写多次读、按版本归档S3 兼容对象存储关系库大字段
分布式锁极短、强互斥Redis（SET NX PX）/ MySQL / MongoDB对象存储

按访问模式而非“哪种更快”选，六个问题依次问完就落位：

读法：先问“是不是进程现场”——这类东西任何 KV 都存不了，只能靠 lease 与 workDir 做归属；再按读写模式分流（大对象→S3，目录语义→NAS），最后才按一致性要求分流（强一致权威→PG，小对象高频→Redis）。决策树的叶子可以换后端，但 DistributedStore 接口不变——这正是“统一的是接口，不是存储”的可操作版本。

后端能力不对等：Redis/MySQL/Mongo 有版本 CAS 与原子锁；JSON 文件、OSS、JPA 是最后写入者胜。统一的是接口，不是存储——AgentScope Java 用 DistributedStore 一行把状态（AgentStateStore）、键值与文件（BaseStore）、快照（SandboxSnapshotSpec）、并发锁（SandboxExecutionGuard）切到同一后端，底层仍是不同存储。硬约束 ✅：远端文件系统没配 stateStore/distributedStore 则 build() 直接抛 IllegalStateException；沙箱配本地存储在多副本下快照与锁都不成立——状态外置不是优化项，是分布式部署的前置条件。

agentscope-service 侧的本机实证对位 ✅：builder.store.backend=redis 装配 RedisStore（Lua EVAL 原子 + hash tag 同槽）+ RedisAgentStateStore，Postgres（JPA）承载 CoordinationStore 三表与定义/会话元数据；两套后端（Redis / JDBC）操作语义等价（写文件 = HSET+ZADD / INSERT，CAS = putIfVersion 返回冲突）。

4.2 原生 journal / event-log 机制 ✅（本体系最重要的实证修正） ​

默认 SessionHistoryMode.EVENT_LOG（HarnessAgent.Builder 默认）下，会话状态全部由追加式日志 journal 承载；AgentStateStore 只在显式 LEGACY 模式或 sandbox 基础设施元数据时挂载（源码 HarnessAgent.java:2644-2707，注释原话：native sessions restore only from their journal）。

Redis 落库快照（68 键实证，remote 环境全链闭环） ✅：

命名空间（\0 分隔）结构内容
runtime\0sessions\0__agentscope_session_log_v1__ZSET + 61 成员版本化会话日志：commits/{sha}.json（base64 批次 + parent 链）/ head.json（seq=410，epoch=3，journal 自身乐观版本）/ exports/{id}.json（导出水位）/ session.json（formatVersion、replayCoverage）
runtime\0agent-api\0views\0sess_{id}\0v2HASH会话视图物化（sequence + turns），API/UI 一次读不重放
runtime\0agent-api\0budgets\0sess_{id}\0ledgerHASH模型调用预算账本（qwen3.8-max，input 6698 / output 233 实证 settle）
harness\0task-scopes\0{ns}\0{key}HASH任务作用域注册
agentscope:session:*（LEGACY 键族，实测 dbsize 72→77）STRING + SET{user}:{session}:agent_state 整包快照 JSON（summary/context/permission_context/tool_context/tasks_context/plan_mode_context）+ :ver 版本 + _keys 槽位注册表

由此得出三条运行语义 ✅：恢复 = journal 按 parent 链回溯重放（新实例无需独立状态槽）；supportsAtomicSessionStorage() 决定导出走原子路径还是幂等重试（Redis 声明支持）；计量（budgets ledger）与事实（journal）解耦，reserve→settle→reconcile 三步自愈，预算是准入型（下一次模型调用前拦，进行中的调用不打断）。

存储可恢复 ≠ 执行亲和 ✅：Redis 解决“数据可恢复”（任意节点能重建会话现场），但运行中的 HarnessAgent 实例、工具子进程、沙箱微VM、SSE 连接绑定具体节点，Redis 存不了进程。架构是三条腿：存储层（Redis/JPA）供可恢复性，协调层（lease/work/SandboxReadyRecord，含 instanceId 归属）供执行亲和，节点层承载进程。节点宕机 → lease 超时回收 → 新实例 journal 重放，数据不丢、执行现场丢（任务需续跑）；所以任务型负载（opencode 长任务）必须配 workspace 持久化 + 节点亲和。

4.3 Environment 四类型与沙箱后端 ✅ ​

类型执行形态依赖适合场景状态
localLocalFilesystemSpec，宿主目录 hands，isolationScope 默认 SESSIONcompose 开关 BUILDER_ALLOW_LOCAL_ENVIRONMENT开发调试、内部可信工具链（managed 现状兜底）✅ 默认兜底路径实证
sandboxE2bFilesystemSpec（templateId / persistenceMode），E2B 云沙箱E2B API key 四级回退（config → builder.e2b.api-key → BUILDER_E2B_API_KEY → E2B_API_KEY）不可信代码执行、强隔离合规源码坐实；本地化三路径清晰：E2B 云 key、E2B Embed 自托管（Linux x86-64 + KVM，Firecracker 微VM）、InMemorySandboxFilesystemSpec 语义模拟；e2b 扩展为双地址架构（apiBaseUrl 控制面 + envdSandboxUrl 数据面）
remoteRemoteFilesystemSpec + AgentStateStore，共享前缀 activity/，无宿主 shellBaseStore + AgentStateStore（RedisStore / JdbcStore，一行式 distributedBackend）多副本共享 MEMORY.md / memory / session logs、跨实例产物✅ 全链实证（env_dfa8f0137120 → 会话 → turn 完成 → 68 键落库）
self_hosted禁本地 fs/shell + SelfHostedToolSchemas 外部工具 schema → Worker 执行Worker 协议（poll/ack/heartbeat，principal=env:{envId}）企业自托管执行池（opencode 池 / 数字分身）、长任务钉节点✅ 源码坐实 + 协议链路部分实证

沙箱后端家族（内核侧）✅：Docker、Kubernetes（agent-sandbox）、Daytona、E2B、AgentRun；选择维度是隔离强度（容器共享内核 vs 微VM/独立节点）、冷启动速度（热池缓解）、文件持久化能力、快照与恢复、出网控制。快照是沙箱的分布式生命线：工作区打包 tar 持久化，换节点再水合；大快照放对象存储不塞 Redis，同一沙箱并发恢复必须分布式锁挡住。E2B 另有一条持久化路线：沙箱文件系统本身作持久化层（无宿主 workdir），带 workspace_id，重启由 manager 列表找回——与 self_hosted 的 workDir 命名卷机制是两条路线。🔧 沙箱网络默认拒绝、出口白名单、凭据 TTL、数据保留期等 Environment Contract 九项为平台层补充（原生提供沙箱后端与挂载语义，策略性约束由平台侧模板下发）。

4.4 三种状态表示与检查点设计 ​

表示写什么回答的问题权威性
事件日志 Event Log追加事实 + 单调 seq发生过什么、按什么顺序事实权威，不可改；原生 journal 即此 ✅
快照 Snapshot某时刻完整物化状态当时整体是什么样派生物，可由日志重建
检查点 Checkpoint任务继续所需最小语义事实从哪里接着做恢复依据，不是事实全集

原生对应 ✅：会话级 checkpoint API 已存在——GET /api/v1/agent-sessions/{id}/checkpoints、POST .../checkpoints/restore（body 带 checkpoint_id + reason，需 Idempotency-Key）、POST .../fork；journal 的 commits/head/exports 三元组就是事件日志 + 水位快照的原生实现。

🔧 检查点十项字段契约为平台层补充（任务级恢复，原生无对应物）：checkpoint_seq / phase+step_no / completed_steps / unfinished_steps / confirmed_facts_ref / tool_result_refs / workspace_version+snapshot_id / subtask_states / wait_condition / budget_snapshot / state_version。纪律：检查点不是内存转储、不是把 AgentState 原样存一份，上下文与工具结果原文只放引用；工具在途不拍“已完成”，标 in_flight_uncertain 带幂等键；用 lease_epoch 栅栏拒绝旧执行者覆盖。

压缩契约与原生对齐 ✅：记忆摘要版本化直落原生 memory 版本链——builder_memory（head_version）+ builder_memory_version + builder_memory_store（owner 隔离）；🔧 平台层补充的仅剩：压缩触发点（checkpoint_seq + 窗口水位）、摘要低信任层注入标注 source=compaction、失败回退上一组 Lock。原始上下文不可改（journal 权威不可变），摘要只作为新的运行视图。

4.5 记忆与隔离 ​

双层记忆 ✅：memory/YYYY-MM-DD.md 只追加流水 + MEMORY.md 周期合并去重、每轮注入系统提示；触发点三处（轮末 flush、压缩前预提取、溢出兜底），后台合并有最小间隔（默认 30 分钟），流水保留 90 天、会话文件 180 天。取舍是用后台成本换前台稳定。记忆不是知识：它记“经历过什么”，不担“组织规定是什么”。

Memory Stores（跨会话共享知识库） ✅：builder_memory_store（owner+name 唯一）→ 会话 memoryStoreIds 经 MemoryMountService 挂到 harness 文件系统 memory-stores/{storeName}/ 路由，默认 read_write、可按 store 只读；直读 JPA store 无宿主磁盘物化，跨并发 turn 天然一致；挂载清单写进 system prompt appendix。

外部记忆 mem0 的分工：内置记忆管“经历流水”，mem0 管“经确认的长期事实”（add/search/update/delete，user/agent/run 三作用域）——同一类事实只能有一个写入口；会话短、已有带 ACL 知识库、事实需强一致三类场景不接。🔧 mem0 接入属平台层扩展（原生无对应组件）。

隔离三层 ✅：IsolationScope 四粒度（SESSION/USER/AGENT/GLOBAL，AGENT 与 GLOBAL 引入跨副本共享写、必须配分布式锁）；状态按 userId/sessionId 分槽（空 userId 归 __anon__，Redis v1 布局 hash tag 同槽）；凭据 Vault secret 只写不回读，resolveVaultCredentials 注入 definition（运行时可见、API 不可读）。装配自检：个人记忆没落到 USER 以下粒度、公共技能没被写到 AGENT 以上可写位置。

4.6 工作区分区与产物状态机 🔧（平台层约定，基于原生挂载语义） ​

工作区按用途分六区，各有写权限与保留期：instructions/（发布流程写、只读挂载）、skills/（运行时只读）、memory/（Agent 运行时写、按保留期清理）、artifacts/（提交后不可变）、scratch/（任务结束清理、不入交付）、shared/（独立审批后写入、带来源与 ACL）。三条硬约束：路径解析防 .. 与符号链接逃逸；每区独立配额（scratch 写满不能拖垮 artifacts）；shared 默认只读、Agent 不能自行扩大共享。远端文件系统命名空间映射：memory/、skills/ 直接复用，knowledge/ 只读挂 shared/，sessions/、tasks/ 归状态层与账本、工作区只挂只读视图。✅ 其中 activity/ 共享前缀、runtime/sessions 日志命名空间为原生实证布局；六区分权为平台层补充。

产物生命周期 🔧 状态机（提交后不可变、扫描 fail-closed、删除追派生数据；原生 artifacts API 面 ✅ 提供读写与列表）：

§五 接口速查（38 Controller 压缩） ​

公共三件套 ✅：每个请求带 Authorization: Bearer <JWT>（POST /api/auth/login 换取）+ X-AgentScope-Tenant + X-AgentScope-Namespace；身份必须来自网关认证结果，不能由客户端自报。企业 SSO 路径实证：向 cp.users 直插用户 + HS256 JWT（accountVersion=0、jti 必填、B64Url 去尾 =）。内部面 /api/internal/* 供 control↔data 协作，接入层不直接依赖其语义。

域端点关键语义成熟度
认证POST /api/auth/loginJWT，401 重登✅ 实证
Agent 定义PATCH /api/v1/agents/{id}/definition平铺 body（嵌套 400）、全量替换、乐观锁 409；mcpServers 数组声明✅ 实证
Skill 注入PUT /api/agents/{id}/skills/workspace/{name}body {markdown, resources}✅ 实证
Agent 目录POST/GET /api/v1/agentsbinding+definition 创建；状态机见 §二.1✅ 实证（坑 K3/K3-b）
会话POST /api/v1/agent-sessions创建即冻结定义与运行配置✅ 实证
TurnPOST /api/v1/agent-sessions/{sid}/turns202 queued；路径必须是 agent-sessions 下（非 /api/sessions）；Idempotency-Key 必带✅ 实证
事件观测GET .../events、GET .../events/stream游标分页（limit≤1000，游标超前 409）、SSE 15s keepalive + Last-Event-ID 续读✅ 实证（454 事件）
快照/用量GET .../snapshot、GET .../usage?include_children、GET|PUT .../budgetviews+session+usage；budget GET 先 reconcile 自愈✅ / 源码坐实
检查点GET .../checkpoints、POST .../checkpoints/restore、POST .../forkrestore 带 checkpoint_id+reason+幂等键源码坐实
子会话GET .../subagents、.../subagents/{child}/snapshot|resource|events|stream多 Agent 事件 subagent/spawned→started→completed源码坐实
会话资源.../inputs、/files、/artifacts、/webhooks、/trace输入队列、文件、产物、回调；trace 默认 404（trace-enabled + admin 角色）源码坐实 / 🔶
审批 HITLPOST /api/sessions/{sid}/eventsuser.tool_confirmation（tool_use_id + allow）；events 必须非空数组✅ 实证
EnvironmentPOST/GET /api/environments四类型；remote 实证 env_dfa8f0137120✅ 实证（sandbox 源码坐实）
Worker/api/environments/{id}/sessions/{sessionId}（SelfHostedWorker）pending-tools / tool-results / skills；事件驱动两段式源码坐实 + 协议链路部分实证
观测（执行体）GET /api/hands/statusbrainInstanceId / pendingWorkItems / workerHeartbeats / sessionHandsMetrics源码坐实
调度出站POST /api/outboundScheduler 出站任务（定时/事件驱动）源码坐实
编排GET /api/v1/orchestration-definitions(/{id}、/revisions) + publish/rundraftSpec=DAG；无 DELETE；节点 agent/team/condition/join/approval✅ UI 实建实证
Workspace/api/workspaces + publish/revisions/files/skills/subagents应用包：tools+mcp+skills+files+版本；产物取回通道源码坐实
Memory/api/memory-stores（builder_memory_store 面）owner+name 唯一，挂载与只读控制源码坐实
Vault/api/vaults + /credentials + /oauth-connectionssecret 只写不回读；按引用解析注入源码坐实
兼容/agentscopeAgentScope 契约兼容面源码坐实
Channelchannels 管理面渠道注册/凭证/启停🔶 实测 404（K3），平台网关承接

调用映射（接入层业务 → 接口）：应用管理→definition PATCH + Skill PUT + 乐观锁；任务中心→会话 + turns(202) + 事件流 snapshot；审批→tool_confirmation；编码任务→Hosted Worker + outbound；观测→events/stream + hands + trace；通知→webhooks（至少一次投递 + HMAC-SHA256 验签 + 事件 ID 去重）；验收→artifacts/files + 任务账本 completion_evidence。幂等纪律：创建、提交、回答 action、cancel/resume 全带 Idempotency-Key，同键不同内容 409；超时后先查状态再决定，不换键重试。

§六 已支持场景链路 ​

6.1 用户对话（chat API）✅ ​

6.2 工具调用 + 审批（HITL）✅ ​

6.3 Workflow 编排执行 ✅（UI 实建 probe-wf 实证） ​

编排是图的壳、执行落在 agent 会话：failurePolicy 三档 fail_fast / continue / partial_success；跨节点复用 turn lease 与 journal 恢复语义，不存在独立于会话体系的第二执行内核。

6.4 定时任务触发（Automations cron → Hosted 池）✅ ​

边界（引擎不做什么） ​

  • 内核不是平台：租户、计费、审批工作流、市场在 Service 与接入层；Higress 管模型路由/限流/计费，不在本体系内。
  • Service 不是任务账本：目录、版本、会话、工作项在 Service；任务 phase、预算、等待原因、完成证据的权威在平台任务账本，以 task_id / task_run_id 关联，互不复制状态。
  • 记忆不是知识：记忆可被推测污染，知识要有来源与生效期；两者不进同一索引。
  • 恢复≠亲和：Redis 保证“能重建”，lease/work 保证“尽量不重建”；不要把“能取消”当成“能恢复”。
  • 审批≠验收、调用权≠审批权：应用 scope（invoke/read/interact/cancel/webhooks:write）不包含审批语义。
  • 默认值不是生产值：maxIters、压缩阈值 50 条、卸载 80K 字符、capacity≤50 都要按模型窗口与任务画像校准；Helm 默认单副本 Recreate，不是 HA。

配套阅读：34 篇（opencode 执行体接入与资源池）、42 篇（OpenJudge 评测闭环，消费 §五 事件契约）、46 篇（上游 issue 跟踪）；坑位台账 D:\build\agentscope_routeB_pitfalls.md（K1-K13）。

判断引擎与壳的接缝是否干净，看五条：所有 ✅ 项能在原版引擎上复现；所有 🔧 项不侵入引擎、由平台壳承接；beta 坑有容错路径而非绕过接口；场景链路四条端到端全绿；组件图与接口表可被源码逐条追溯。

适用：AgentScope Service 2.1.0-BETA1 / AgentScope Java 2.0.x | 合并重写自 06 / 07 / 12 / 35 / 41 五篇 | 定稿 2026-10-26

把 AI 工程讲到既懂也会用

AI 工程小册 · 持续更新