AI 工程小册

主题

44-实证与验收总报告 ​

一句话：验收的说服力来自复跑而非自述：结论给场景、期望值给实测、改动给清单、坑位给定位，于是“4.5/5”能指到唯一 P0 和已实证的绕行方案；边界是上游缺陷的修复权不在平台手里，平台只给规避与回归，且结论只在钉死的版本上成立，升级后必须重跑 S1–S9。

合并声明：本篇合并原 44（复核验证手册）、45（上游 Issue 草稿）、46（主线验收总结与生产落地建议）三篇精华，作为 07 主战场（agentscope-service）的唯一验收出口。环境重建命令级细节见 31-环境重建与自动化部署手册（本篇不重复）；原始复现日志与脚本仍在 D:\build\。 复核对象：开源栈 agentscope-service 2.1.0-SNAPSHOT（agentscope-java 仓库）构建的百炼同类企业智能体平台底座；compose 栈 6 容器 + Redis 后端 + token-plan 网关（qwen3.8-max）。 验收口径（全程坚持）：所有结论来自实机运行；每项能力跑后讲透“存什么数据、怎么存、为什么这么设计”；全部可复核（S1–S9 支持第二人独立走查）；源码 7 处改动全部明示；坑位 K1–K18 全量台账化（D:\build\agentscope_routeB_pitfalls.md）。

一、复核环境搭建（关键步骤） ​

1.1 前置依赖 ​

依赖版本用途
Docker Desktop4.x（WSL2 backend）跑 compose 栈（redis/control/data/scheduler/gateway/postgres）
JDK / Maven17+ / 3.9+构建 agentscope-java
Python3.13观测脚本 / py-openjudge / redis 直连
Node18+mermaid 校验（check.mjs）
模型网关token-plan（qwen3.8-max，OpenAI 兼容协议）agent 执行 + OpenJudge judge

1.2 构建与部署（命令级全量步骤见 31 手册，此处只列主干） ​

powershell
git clone <agentscope-java 仓库> D:\build\agentscope-java
cd D:\build\agentscope-java
mvn clean install -DskipTests
cd agentscope-service
mvn clean package -pl service-dataplane -am -DskipTests "-Dmaven.test.skip=true"

cd deploy
# .env 关键项（真实 key 勿入库）：
#   BUILDER_MODEL_PROVIDER=openai · BUILDER_MODEL_NAME=qwen3.8-max
#   BUILDER_MODEL_BASE_URL=<token-plan 兼容端点> · BUILDER_MODEL_API_KEY=<.env 原文>
#   BUILDER_STORE_BACKEND=redis · BUILDER_AGENT_API_LEGACY_HISTORY=false
#   DATAPLANE_JAR=D:/build/.../service-dataplane-2.1.0-SNAPSHOT.jar
docker compose up -d --force-recreate data   # jar/env 变更后必须 force-recreate（K12）
docker ps   # 期望：redis/control/data/scheduler/gateway/postgres 全 healthy

登录 gateway（127.0.0.1:18080）取 JWT 存盘（Python 读取必须 utf-8-sig 防 BOM）；复核工具 python -m pip install py-openjudge==0.2.4 redis。

1.3 本方案对源码的 7 处改动（沿用/扩散时必须随文声明） ​

#文件改动
1HarnessAgentBuildService.java解析会话 overrides 的 legacyHistory 键 + @Value("${builder.agent-api.legacy-history:false}") 默认值 + b.legacySessionHistory(true) 透传
2RedisStore.javasupportsAtomicSessionStorage() 先删后恢复，当前返回 true（Lua 原子导出）
3RedisBackendConfig.java新建：Redis 后端装配（条件注解，backend=redis 激活）
4DataPlaneConfig.javabackend=jdbc 条件注解补 matchIfMissing，与 redis 配置互斥
5dataplane/pom.xml+agentscope-extensions-redis 依赖
6deploy/compose.yamlredis 服务+端口映射；data 三项 env（backend/redis-url/legacy-history）+ DATAPLANE_JAR 挂载
7deploy/.envBUILDER_STORE_BACKEND=redis、BUILDER_AGENT_API_LEGACY_HISTORY=true→false

改动后的关键代码片段（实际构建版本核对件）见下文 §1.4；复核时若本地代码与片段不符，即未应用本方案改动。

1.4 改动证据（实际代码片段，2026-10-26 本机构建版本实时提取） ​

以下代码从 D:\build\agentscope-java 本机构建版本提取（行号=提取时点）；复核环境与本文不一致时以本地源码为准。

改动 1-3：HarnessAgentBuildService.java（service-dataplane src\main\java\io\agentscope\builder\web\catalog\）

legacyHistory 默认开关（L119-120）：

java
@org.springframework.beans.factory.annotation.Value("${builder.agent-api.legacy-history:false}")
private boolean legacyHistoryDefault;

overrides 解析并合并默认值（L377-381）：

java
if (overrides.get("legacyHistory") instanceof Boolean lh) {
    legacyHistory = lh;
}
...
legacyHistory = legacyHistoryDefault || legacyHistory;

builder 透传（L388-390）：

java
if (legacyHistory) {
    b.legacySessionHistory(true);
}

改动 4：RedisStore.java（agentscope-extensions-redis ...\extensions\redis\store\）——supportsAtomicSessionStorage() 恢复为 true（L148-151，Lua 原子导出前提）：

java
@Override
public boolean supportsAtomicSessionStorage() {
    return true;
}

改动 5：RedisBackendConfig.java（service-dataplane ...\web\config\，新建文件）——条件注解 backend=redis 激活；UnifiedJedis 默认 redis://localhost:6379；keyPrefix agentscope:store: / agentscope:session:：

java
@Configuration
@ConditionalOnProperty(name = "builder.store.backend", havingValue = "redis")
public class RedisBackendConfig {

    @Bean
    public UnifiedJedis unifiedJedis(
            @Value("${builder.store.redis.url:redis://localhost:6379}") String url) {
        return new UnifiedJedis(url);
    }

    /** Distributed KV filesystem backend (remote filesystem routes). */
    @Bean
    public BaseStore baseStore(UnifiedJedis jedis) {
        return new RedisStore(jedis, "agentscope:store:");
    }

    /** Distributed session state (session slots, versions, list state). */
    @Bean
    public AgentStateStore agentStateStore(UnifiedJedis jedis) {
        return RedisAgentStateStore.builder()
                .jedisClient(jedis)
                .keyPrefix("agentscope:session:")
                .build();
    }
}

改动 6：DataPlaneConfig.java——jdbc 默认 beans 补 matchIfMissing = true，与 RedisBackendConfig 互斥装配（L121-132 baseStore / L143-150 agentStateStore）：

java
@Bean
@ConditionalOnProperty(name = "builder.store.backend", havingValue = "jdbc", matchIfMissing = true)
@ConditionalOnMissingBean(BaseStore.class)
public BaseStore baseStore(DataSource dataSource) { ... }

@Bean
@ConditionalOnProperty(name = "builder.store.backend", havingValue = "jdbc", matchIfMissing = true)
@ConditionalOnMissingBean(AgentStateStore.class)
public AgentStateStore agentStateStore(DataSource dataSource) { ... }

改动 7：dataplane/pom.xml——新增 Redis 扩展依赖（L87-91）：

xml
<!-- Redis-backed distributed store (remote drill): RedisStore + RedisAgentStateStore -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-redis</artifactId>
</dependency>

改动 8：deploy/compose.yaml——新增 redis 服务（L66-78）+ data 服务三项 env 与本地 jar 挂载（L112-125）：

yaml
redis:
  image: redis:7-alpine
  restart: unless-stopped
  command: [redis-server, --appendonly, 'yes']
  ports:
    - '${BIND_ADDRESS:-127.0.0.1}:${REDIS_PORT:-6379}:6379'
  volumes:
    - redis-data:/data

data:
  ...
  environment:
    BUILDER_STORE_BACKEND: ${BUILDER_STORE_BACKEND:-jdbc}
    BUILDER_STORE_REDIS_URL: ${BUILDER_STORE_REDIS_URL:-redis://redis:6379}
    BUILDER_AGENT_API_LEGACY_HISTORY: ${BUILDER_AGENT_API_LEGACY_HISTORY:-false}
  volumes:
    - ${DATAPLANE_JAR:-/dev/null}:/app.jar:ro

改动 9：deploy/.env（L21-25）：

dotenv
DATAPLANE_JAR=D:/build/agentscope-java/agentscope-service/service-dataplane/target/service-dataplane-2.1.0-SNAPSHOT.jar
BUILDER_STORE_BACKEND=redis
BUILDER_AGENT_API_LEGACY_HISTORY=false

二、S1–S9 验证矩阵（第二人独立复跑） ​

公共三件套：Authorization: Bearer <token> + X-AgentScope-Tenant: default + X-AgentScope-Namespace: personal-2fc9756ccf936edc09a1；脚本在 D:\build\ 下，期望值全部来自实跑。

#场景判定标准实测基准结论
S1平台就绪6 服务 healthy + agents API 200 非空agentKey=opencode-coding（version 5）✅
S2会话与 turn 生命周期ENCODING_OK=True（会话/turn/观测三链通）+ 评分存在（评测链通）SESSION/TURN_ACCEPTED/中文完整读回/RELEVANCE 3.0；附录：teams/automations/inbox/issues 200 空列表、orchestration-definitions 200、channels 404（发布渠道缺口）✅
S3观测契约 17 端点8 个 200 + trace 404 即契约全貌通过events cursor base64、snapshot 一致水位、usage model_calls≥1（estimated_cost 不在 usage）、budget 自愈、checkpoints、export NDJSON、hands/status✅
S4Redis 数据面结构键族可枚举、可解释来源会话日志/checkpoint/usage/work items/memory 键族；Redis 存数据不存进程（sandbox 在 worker 侧）✅
S5中文编码往返（K16）修复链路读回无 ?根因 PowerShell -Body 按 GBK 发送；修复=显式 encode("utf-8")✅
S6OpenJudge 评测闭环评分+reason 输出即闭环（judge ±0.5 波动允许，reason 语义为硬判定）Relevance 5.0（乱码例：judge 自主识别编码事故）/3.0（点名“未遵守简短回复”）；TrajectoryGrader 0.0=已知 schema 适配缺口（预期行为）✅
S7LEGACY 键族只读复现，不要复现 LEGACY turn（必失败，K17）agentscope:session:{userId}/{sessId}:agent_state 为装配初始化写入，非 turn 写入⚠️ K17
S8数据面执行细节类型与字段结构匹配观测契约usage qwen3.8-max input 6698/output 233/total 6931/6.519s；tool.requested/dispatched/completed 各 2（memory_search 真实轨迹）✅
S9flow 编排层实证列表 200 + draftSpec 含 nodes/edges + 设计器节点类型齐全orchestration-definitions DAG（节点 agent/team/condition/join/approval）；UI /agent-center/workflows Draft→Validate→Publish→Run→Activity；标本 probe-wf 留存（无 DELETE API）✅

能力结论矩阵：flow 执行内核 ✅ · teams ✅ · automations ✅ · flow 可视化编排 ✅（与百炼 flow 画布同构）· channels 发布 ❌（P0 缺口）· 观测契约 ✅ · Redis 结构 ✅ · OpenJudge ✅ · 中文链路 ✅ · HITL inbox ✅ · memory ✅。

期望值核对表（复核人速查）：

项期望实测基准
compose 服务6 服务 healthyredis/control/data/scheduler/gateway/postgres
agents API200 + items 非空agentKey=opencode-coding（version 5）
workflowsorchestration-definitions 200 + 设计器S9 实建 probe-wf
channels404发布渠道缺口判定
automations/teams/inbox/issues200 空列表API 存在性
events454 条、17 类型、cursor base64d57377bc 会话
usagemodel_calls 4、total 6931/次、scope session_onlyqwen3.8-max
budgetrevision 8、enforcement before_model_call、limits {}GET 自愈
exportNDJSON、Content-Dispositionsession-events.jsonl
trace404（默认关）trace-enabled=false
Redis dbsize72→77（LEGACY 实证）/ 结构可枚举redis_drill_observe
中文往返ENCODING_OK TrueK16 修复后
OpenJudgeRelevance 5.0（乱码例）/3.0（简短指令例）token-plan judge

三、上游缺陷台账与 issue 草稿（K17/K18/K19；可提交全文见 §3.1–§3.3） ​

K17：LEGACY 历史模式下所有 turn 抛 SessionRecorder is null NPE ​

  • 组件：service-dataplane / harness（AgentTraceMiddleware + SessionTurnRunner）；
  • 复现：BUILDER_AGENT_API_LEGACY_HISTORY=true 启动 data 容器 → 任意 turn → NullPointerException: Cannot invoke "SessionRecorder.acceptedMessageIds()" because "recorder" is null（首 turn 与后续 turn、新旧会话均复现）；
  • 定性：trace 中间件无条件访问未初始化的 recorder；LEGACY 键族“写入侧可用、执行侧不可用”（agent_state 键是装配初始化产物）；
  • 上游修复建议：LEGACY 装配路径初始化 SessionRecorder（或复用 AgentStateStore 快照做 accepted 追踪）；AgentTraceMiddleware 对 recorder == null 判空降级；
  • 平台侧规避：生产默认 EVENT_LOG 模式（LEGACY=false），不复现 LEGACY turn；等上游修复后该开关才可用于生产历史迁移。

K18：会话事件 append 控制面/数据面并发写入连续 (session_id, seq) 唯一冲突，turn 事件流卡死 ​

  • 组件：service-common / SessionEventLog.appendOnce()（seq 分配）+ control/data 双平面并发 append；
  • 复现：对已有多轮历史的会话发新消息 → data 日志 duplicate key ... ux_builder_session_event_seq（实测 seq 295–302 连续 8+ 次冲突）→ turn 执行本身正常，但事件写冲突持续 → SSE/UI 永久 working；
  • 根因：seq = maxSeq(sessionId) + 1 非原子（读水位再 INSERT，无锁）；高吞吐流式事件（item.delta 单 turn 数百条）下两平面同刻读水位→同刻 INSERT→冲突，MAX_SEQ_RETRIES=16 内每次皆撞（重试疑似复用旧水位，未刷新）；
  • 上游修复建议：按 session_id 串行化 append（per-session 锁+跨进程行锁）/原子序列（PG sequence 或 Redis INCR）/重试时重新读 maxSeq；
  • 平台侧规避（按优先级）：
    1. 监控先行：对 ux_builder_session_event_seq 冲突（HHH000247 WARN 连续 N 次）设实时告警，冲突即暴露；
    2. 会话重建兜底：检测“事件流超时 60s 无新 seq”→ 引导新建会话（chat API 链路已实证可立即接续），污染会话标记不可续；
    3. DB 层清理（运维动作）：确认会话废弃后 DELETE FROM builder_session_event WHERE session_id=… 清污染 seq；
    4. 单平面降级（待评估）：若冲突主因确为双平面并发，评估 chat 高频流量单平面写事件（配置项非源码改动，不确定时保持 1+2 即可，不阻塞业务）。

提交建议：仓库 agentscope-ai/agentscope-java 三 issue 独立提交；可提交级草稿全文见 §3.1–§3.3（K17/K18 重建、K19 新发现归位），复现日志原文在 D:\build\ 与台账 K1–K19。

三.1 K17 issue 草稿全文（可提交） ​

Title: LEGACY 历史模式下所有 turn 抛 SessionRecorder is null NPE（agentscope-service harness 装配缺陷）

Component: agentscope-service/service-dataplane — harness 装配路径（AgentTraceMiddleware 无条件访问 SessionRecorder；SessionTurnRunner 执行 turn）。

Environment: agentscope-service 2.1.0-SNAPSHOT（本地构建）；BUILDER_AGENT_API_LEGACY_HISTORY=true + Redis 后端；token-plan 网关（qwen3.8-max）。

Summary: 开关 LEGACY 历史模式后，任意 turn（首 turn/后续 turn、新会话/旧会话）必抛：

NullPointerException: Cannot invoke "SessionRecorder.acceptedMessageIds()" because "recorder" is null

LEGACY 装配不初始化 SessionRecorder，但 AgentTraceMiddleware 无条件访问它。LEGACY 键族（agentscope:session:{userId}/{sessId}:agent_state 等，Redis dbsize 72→77）是装配初始化写入（stateStore.saveIfVersion(expected=0)），不是 turn 执行写入——"写入侧可用、执行侧不可用"。

Reproduction:

  1. .env 设 BUILDER_AGENT_API_LEGACY_HISTORY=true，docker compose up -d --force-recreate data；
  2. 对任意会话发一个 turn（chat API 或 UI）；
  3. data 日志出现上述 NPE，turn 失败；会话/事件链全断。

Root cause: LEGACY 装配路径未初始化 SessionRecorder（走 AgentStateStore 槽位），AgentTraceMiddleware 对 recorder 无判空。

Suggested fix（二选一）:

  • LEGACY 装配路径初始化 SessionRecorder（或复用 AgentStateStore 快照做 accepted 追踪）；
  • AgentTraceMiddleware 对 recorder == null 判空降级（EVENT_LOG 之外的模式不崩）。

Impact: LEGACY 历史模式整体不可用；生产当前默认 EVENT_LOG（LEGACY=false），该开关修复前不能用于生产历史迁移。

三.2 K18 issue 草稿全文（可提交） ​

Title: 会话事件 append 控制面/数据面并发写入连续 (session_id, seq) 唯一冲突，turn 事件流卡死（UI 永久 working）

Component: agentscope-service/service-common — SessionEventLog.appendOnce()（seq 分配）+ control/data 双平面并发 append。

Environment: agentscope-service 2.1.0-SNAPSHOT 全 compose 栈（control/data/gateway/scheduler/db/redis）+ Redis 后端。

Summary/Reproduction: 对已有多轮历史的会话发新消息 → data 日志批量：

WARN HHH000247 | ERROR: duplicate key value violates unique constraint "ux_builder_session_event_seq"
Detail: Key (session_id, seq)=(sess_a0005a9abd96, 295) already exists.   # seq 295–302 连续 8+ 次

turn 执行本身正常（HarnessAgent built 成功），但事件写冲突持续 → SSE/UI 永久 working（>3 分钟无回复）。

Root cause: seq = maxSeq(sessionId) + 1 非原子（读水位再 INSERT，无锁）；高吞吐流式事件（item.delta 单 turn 数百条）下控制面/数据面同刻读水位→同刻 INSERT→冲突；MAX_SEQ_RETRIES=16 内每次皆撞（重试复用旧水位，未刷新）。

Suggested fix（按成本排序）:

  1. 按 session_id 串行化 append（per-session 锁 + 跨进程行锁）；
  2. 原子序列（PG sequence 或 Redis INCR）；
  3. 重试时重新读 maxSeq（当前疑似复用旧水位）。

Impact: chat UI/SSE/checkpoint 受影响（UI 卡死）；API turn 链路不受影响（S2/S5/S6 已实证）；平台侧规避=监控告警 + 污染会话重建 + 自建前端直连 chat API。

三.3 K19 issue 草稿全文（可提交，2026-10-26 归位） ​

Title: verifyEnvironmentKey 在 Reactor 线程上调用 Mono.block() → self-hosted worker 全部路由 401

Component: agentscope-service/service-dataplane — io.agentscope.builder.control.ControlPlaneClient#verifyEnvironmentKey，调用方 io.agentscope.builder.web.auth.EnvironmentKeyAuthFilter（WebFlux WebFilter，运行于 reactor-http-epoll-N）。

Environment: agentscope-service 2.1.0-BETA1（image as-dataplane:2.1.0-BETA1）全 compose 栈；Java 21、Spring Boot 4.0.4 / Spring 7.0.6、WebFlux（Reactor Netty）。

Summary: self-hosted worker 认证（X-Builder-Environment-Key）恒 401，即使：

  1. data 面确实把 key 转发给 control 面（POST /api/internal/environments/{id}/verify-key），
  2. control 面返回 200 {"ok":true}（手工同 key 同 token 验证通过），
  3. 存储 hash 与 sha256(key) 完全一致。 原因是非阻塞线程上的阻塞调用：
DEBUG ControlPlaneClient : verifyEnvironmentKey failed for env_<id>: block()/blockFirst()/blockLast() are blocking, which is not supported in thread reactor-http-epoll-2

verifyEnvironmentKey 内部 webClient.post()...bodyToMono(Map.class).block() → Reactor 抛 IllegalStateException → catch(Exception) 吞掉返回 false → 匿名路径 → 401。JWT 认证不受影响（本地校验），故 poll 带用户 JWT 返回 204、带环境 key 返回 401。

Reproduction:

  1. 部署全栈；POST /api/environments 建 self_hosted 环境（admin JWT）→ 得 apiKey（ek_...）；
  2. curl -i -H "X-Builder-Environment-Key: ek_<key>" "http://localhost:18080/api/environments/env_<id>/work/poll?workerId=w1&timeoutMs=1000" → 401；
  3. 同请求换 Authorization: Bearer <userJWT> → 204。

Evidence: data 面 DEBUG 日志（block() 异常）；control 面每请求 200；容器内 wget 手工调用 {"ok":true}；cp.environments.api_key_hash == sha256(key)；javap -c 反编译确认 bodyToMono(Map.class).block() 无 subscribeOn。类 javadoc 自述契约"callers on WebFlux handlers must schedule onto Schedulers.boundedElastic()"——实现未遵守。

Suggested fix（首选）:

java
.retrieve()
.bodyToMono(Map.class)
.subscribeOn(Schedulers.boundedElastic())
.block();

已本地验证：改后同 poll 返回 204，完整 worker 协议（poll→ack→pending-tools→tool-results）可用。备选：EnvironmentKeyAuthFilter 全响应式（Mono<Boolean> + contextWrite）。

Impact: 2.1.0-BETA1 中全部 self-hosted worker 流（/work/poll、ack|heartbeat|stop、pending-tools、tool-results、skills）无法用环境 key 认证；官方 HandsWorkerMain 无法连接。

附注（候选后续 issue）: agentscope-bom:2.1.0-SNAPSHOT 非聚合 POM 模块导致干净构建失败；Windows 非 ASCII 路径下 protobuf-maven-plugin（protoc）失败。

四、能力验收矩阵（主线 5 条，4.5/5） ​

#主线能力状态关键证据交付归属
1上层展示层：himarket vs 百炼✅ 确认差距市场=Skill/MCP/模型配置，展示层为后续定制点32/38 篇（38 留档）
2知识库能力✅ 确认补齐RAGFlow 起栈 + API 全链（建库/解析/检索/问答）+ 权限 + 水平扩展06 专栏
3agentscope-service：智能体/opencode/chatbot/workflow/harness/长任务/隔离/下沉⚠️ 4.5/5（chat UI 一条转上游）智能体定义执行、opencode 工具、workflow 画布、harness 资源独占、三层隔离41 篇 + 本篇 §二
4数字分身✅ 基本落地QwenPaw 多实例 + Pod 管理 + IM 渠道聚合08 产品线（接缝见 36 摘要篇）
5AI 网关三类✅ 确认Higress + Nacos 接线、统一入口03/32 篇

结论：能力实证 4.5/5 确认 OK；产品可用性维度，Chat UI 为 P0 阻塞项（K18 上游缺陷，已转 issue）。唯一未闭环=chatbot UI 回复；临时替代=自建前端直连 chat API（chat API turn 链路已实证：中文提交/读回/评测/观测全通）——UI 卡死只影响官方界面，不阻塞 API 层业务接入。

已闭环明细：41 篇（领域模型 §10.1-10.16 讲透资源抽象/执行语义/存储设计/编排层）· 评测闭环（OpenJudge 可当质量门禁）· 观测契约（17 端点实跑）· 复核（S1–S9）· 上游 issue 草稿（K17/K18 证据齐备）。

剩余风险与处置：

风险状态影响面处置责任方
K17 LEGACY turn NPE已定位+已备 issueLEGACY 历史模式不可用生产默认 EVENT_LOG；等上游修复上游
K18 事件 seq 双写冲突已定位+已备 issuechat UI 卡死、SSE/checkpoint 受影响§三规避方案 + 自建前端直连 API上游+平台层
opencode 容器节点持久化机制已设计长任务多轮回同一执行节点生产前真实长任务验证 workspace 复用平台层
TrajectoryGrader schema 对齐实现期工作评测门禁广度读 grader 源码或换 ToolSelectionGrader平台层
himarket 展示层差距需求已梳理产品完整度后续主攻（统一入口/接入层建设）平台层

五、生产落地建议 ​

5.1 分层架构（三层各归其位） ​

  • 产品层：HiMarket 市场（Skill/MCP/模型配置）+ 知识库 + 数字分身 + 评测门禁——面向用户；
  • 平台层：统一入口/接入层（Higress 网关、SSO 对接）+ 观测（43 契约，现并入 14 篇）+ 容错兜底——面向运维与治理；
  • 引擎层：agentscope-service（资源抽象 + 智能体执行 + 编排）——下沉，对用户隐藏。

5.2 平台层容错兜底清单（针对引擎 beta 性，上线前逐条核对） ​

  1. 事件写入监控：对 builder_session_event 冲突/堆积设告警（K18 场景秒级发现，不等用户感知）；
  2. turn 超时兜底：长任务超时后按观测契约查快照水位，决定重试或会话重建；
  3. 会话重建策略：污染会话（seq 冲突堆积）自动标记并引导新建，不阻塞业务；
  4. 上游 issue 治理：K17/K18 提 issue 跟踪，版本升级后用 §二 S1–S9 回归验证吸收情况。

5.3 锁定已验证子集先行 ​

chat API 链路（S2/S5/S6）、评测门禁、workflow 编排、harness 执行、观测契约——已实证闭环，可作为首期生产范围；UI chat 等依赖上游修复后再纳入。

5.4 里程碑与后续路线（乐高拼装视角） ​

已拼装积木：06 知识库 → 07 主战场（41–44 篇）→ 08 数字分身 → 38 市场——每块有可运行产出与文档闭环。 后续候选：① HiMarket 平台层落地（对标百炼需求已梳理，32 §1.2 差距表）；② 生产化加固推演（高可用/监控/多副本）；③ 上游 issue 提交与版本升级回归。

六、主战场验收全景 ​

一句话讲清验收结论：引擎层三条主线（资源抽象、智能体执行、编排画布）全部实证可用且可复核；平台层以“观测契约 + 容错兜底”承接引擎的 beta 性；产品层四块积木均已落地，唯一 P0 是 K18 导致的 chat UI 卡死——API 层绕行方案已实证，不阻塞首期生产。

把 AI 工程讲到既懂也会用

AI 工程小册 · 持续更新