AgentScope第1式·识势选型

AgentScope第1式·识势选型

选错方案，后面每一次需求变更都要重写一遍。

[读者] Java 后端与架构师，正把数字人从 Demo 推向生产
[痛点] 模型能调通，记忆、工具、审批、恢复却全要自己手写
[现在读] 项目刚进入长期运行阶段，选型窗口只有一次
[读完] 能用一张表说清五种方案边界，并讲清 15 个以上核心术语

[旧方案] Spring Boot 里直接调大模型 API，外面套一层 Workflow 兜底
    |
    v
[新需求] 要跨会话记忆、要查知识查客户、要办业务、要审批、要审计
    |
    v
[冲突] 这些不是模型能力，而是运行时能力，直连 API 补不上
    |
    v
[后果] 每加一个能力就多焊一坨胶水，越改越不敢上线

我是老李，做 Java 后端十几年，最近两年大半时间在做 AI 应用的落地。我见过太多项目死在同一个地方：Demo 阶段人人叫好，进生产阶段没人敢碰。

这一次的项目是企业数字人。它要挂在企业官网上，访客点开就能对话，背后连的是企业的知识库、CRM 和几张工单表。第一版 Demo 只用了一个 Spring Boot 接口加一次模型调用，两周就上线演示了。

但演示结束那天，业务方给的下一版需求，把整个技术选型问题重新翻了出来：要记住上次聊到哪、要查客户、要发起退款、敏感操作要人工确认、所有动作要能审计。

那么问题来了：到底该按什么标准判断，这个项目需不需要一个 Agent 运行时？

如果没有标准，是继续在 Spring Boot 里堆胶水，还是现在就引入一套框架、承担学习成本？

选错了又会怎样？最坏的结果不是多写几千行代码，而是两年后整个系统没人敢改。

01、故事

周一上午的架构评审会，白板上从左到右贴了四张便签。

第一张写现状：/api/chat 接口，一次模型调用，一张 conversation 表按 sessionId 存历史。第二张写需求：查知识库、查客户、发起退款、跨会话记忆、复杂任务拆解、全程审计。第三张写约束：两个月上线，团队三个 Java 后端，没人写过 Agent。第四张写着一个被圈起来的问题——用什么？

任务是：把网页上那个只会聊天的输入框，变成能查知识、能查客户、能办业务、能记住人、能管住手的数字员工。

会议室里出现了三种声音。

第一种声音来自后端组长：别引入新东西，模型 API 加个 service 层就够了，工具调用我写 if/else 路由。第二种声音来自一位做过流程引擎的同事：上 Workflow，画流程图，节点里塞 LLM，可控、能审批、能回滚。第三种声音来自刚从另一个 AI 项目回来的同事：Spring AI 或者 LangChain4j 都行，都是 Java 生态，生态成熟，社区大。

三种声音都不算错，但它们回答的其实是三个不同的问题。第一种回答的是「怎么调模型」，第二种回答的是「怎么定流程」，第三种回答的是「怎么把模型接进 Spring」。而白板上那张便签问的是第四件事：

当一个系统要长期运行、要调用真实工具、要记住人、要把任务分给别人、要让敏感操作停下来等人点确认、要在崩溃后恢复，这套东西由谁来管？

那天的会没开出结论。会后我在仓库里建了一个空目录，决定先把判断题做完，再碰代码——因为我知道，这种项目最贵的错误不是写错代码，而是选错承载方式。

一行调用易
一栈运行时难
先问价值事
再落代码行

02、问题

旧认知很朴素：Agent 就是更会聊天的模型，把 prompt 写长一点、把模型换强一点就行。

这个认知在 Demo 阶段是对的，在数字人项目上不成立。因为需求清单里那些条目，没有一条是「模型能不能答」，全都是「系统能不能管」：跨会话记忆要有人存、工具调用要有人拦、退款要有人批、崩溃要有人恢复、审计要有人记。这些东西跟模型强弱没有关系，模型再强也不会替你管住一次退款。

证据在哪里？就在 AgentScope Java 自己的模块划分里。按固定 tag v2.0.3 的仓库结构，agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java 描述的是「一个 Agent 怎么循环推理与行动」，而 agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java 所在的模块，处理的是「这套循环怎么被装配成一个能长期运行、能挂工具、能带状态、能受约束的外壳」。官方文档 docs/v2/zh/docs/harness/architecture.md 也是围绕分层与装配讲的，而不是围绕模型效果讲的。具体字段与目录结构请以该文档和固定版本源码为准。

对比一下另外两类方案就更清楚了。传统大模型 API 是「一次请求一次响应」，Spring AI / LangChain4j 的定位是「把模型集成进 Java 应用」，两者都很成熟，但它们解决的问题集中在调用、提示词、流式输出、工具回调这一层。工具回调不等于工具治理：谁允许调、调之前要不要审批、调崩了怎么办、这次调用算在谁头上——那是运行时的活儿。

风险也在这里。当这些职责没有归属，它们就会散落到业务代码的各个角落：在 service 里判断意图，在 controller 里拼历史，在定时任务里清理会话，在某处硬编码一个「退款要二次确认」。三个月后没人能说清「这个数字人一共能干什么、干过什么、谁能让它干什么」。

所以本篇的完成标准不是「跑通一个 Agent」，而是四份可交付物：一份教程 README、一份架构背景说明、一份不少于 15 个术语的术语表、一份能回答三个「为什么不」的选型决策记录。

旧识以为巧
新需方知深
边界先划清
方能少返工

03、原理

本篇真正需要的原理只有一条：把「模型能力」和「运行时能力」分开看。

可以粗略分三层。最下面一层是模型能力层，负责推理、生成、理解，这是模型厂商的事。中间一层是模型集成层，负责把模型接进 Java 应用、处理鉴权、重试、流式、结构化输出，Spring AI、LangChain4j 的主战场在这里。最上面一层是 Agent 运行时层，负责状态放哪、工具怎么注册与授权、循环怎么终止、人怎么介入、崩了怎么恢复、轨迹怎么留，AgentScope Java 的主战场在这里。

先解释三个后面反复出现的词，每个只给边界。Agent 在本系列里指一个持有状态、能调用工具、能循环决策的执行体，不是「更聪明的模型」。ReAct 是一种循环范式，把「想一步、动一下、看一眼、再想」串成可终止的循环。Harness 是把这套循环装进一个可长期运行外壳的运行时，负责把循环、工具、记忆、权限、工作区这些零件装配起来，具体分层以官方 harness 架构文档为准。

这里有两个反直觉判断。

第一个反直觉判断：Agent 项目的成败，主要不取决于模型有多聪明，而取决于状态、权限、恢复这三件事有没有人负责。模型答错一句话，用户再问一遍就行；工具调错一次退款，那是要赔钱的。

第二个反直觉判断：工具调用写起来最容易，出事也最容易。因为它把「模型输出」直接接到了「真实副作用」上，中间那层校验和授权如果没做，等于把一个概率模型直接连到了数据库写接口。

还有一个必须提前说清的边界：AgentScope Java 是 Apache-2.0 许可的开源框架，框架本身可自由使用，但这和「用起来不花钱」是两回事。模型调用、API 配额、GPU、LiveKit 这类基础设施，各自有各自的成本，跟框架许可完全是两条账。混淆这两条账，会在做预算时得出错误结论。

最后一句版本提醒：本系列基线是 v2.0.3。如果你写作当天看到的 Releases 页已经有更新版本，本篇的判断仍然可以按 v2.0.3 复现，但涉及新特性的现状，需要按当天的 Release Notes 核验，不能把 v2.0.3 的限制当成永久结论。

推理非难处
状态是关山
循环装成壳
长期才可安

04、架构

[输入] 用户在 /run/{projectId} 里说的一句话，或一段语音转成的文本
    |
    v
[模块] Web 管理/运行端 → Spring Boot 装配 → Realtime Bridge → AgentScope Java
    |
    v
[数据/状态] MySQL 存项目配置 + 会话标识 + 运行期状态与上下文
    |
    v
[处理] ReAct 循环：推理 → 选工具 → 执行 → 观察 → 再推理，中途可被人工介入打断
    |
    v
[输出] 回复文本/音频事件 + 一条完整可审计的执行轨迹

这张图不是最终架构，而是「选型的坐标系」。左边是宿主：Spring Boot 管项目配置和鉴权，MySQL 存业务数据。中间是实时通信层 WebRTC Room，只负责把音频和数据搬来搬去，不负责推理。右边才是 AgentScope Java，负责循环、工具、状态、记忆、审批这些运行时职责。后续章节会把每一段填实，第 3 式会把它冻结成一个可运行的最小数字人 Demo。

边界：LiveKit 这类实时通信组件只做媒体与数据传输；Realtime Bridge 保持最薄，只做媒体消息与 Agent 消息之间的适配，不做业务判断；STT/TTS 如果启用，只作为 Bridge 周边可插拔组件。所有业务语义都落在 AgentScope 这一侧。

收益：职责清晰之后，能力可以叠加而不是重写。加一个查询工具，是注册一个 Tool；加一次审批，是挂一个中间件；加一层记忆，是换一个 Memory 实现。这三种改动都不会动到媒体链路和业务表结构。

代价：多一层运行时，就多一份学习成本、多一份排查难度，也多一个必须纳入可观测体系的组件。对小项目来说是明显的过度设计。

适用条件：意图开放（无法预先枚举分支）、有真实副作用（要调外部系统）、需要长期运行（跨会话、要恢复、要审计），三条至少占两条。

不适用条件：只是给文档站加个问答框、流程分支可以完全枚举、一次性离线批处理、团队没有任何人可以长期维护这一层——这些情况都不该引入 Agent 运行时。

涉及内部机制时，本文的判断优先落在两处固定源码入口：agentscope-core 里的 ReActAgent，和 agentscope-harness 里的 HarnessAgent；文档层面以官方 harness 架构文档为主。第 8 式会专门建立一套源码研究方法，那时我们再把调用链一条条走通。

入口接会话
中间管状态
出口留轨迹
分层不越界

05、实战一次

本章不接模型，实战产物是四份文档。这也是最有价值的一步：把判断题写下来，比把代码写出来更能防住后面的返工。

分支从 main 创建：

git checkout main
git pull
git checkout -b chapter/01-value-scenario-terms
mkdir -p docs/ch01

预期目录结构（本章产出，均为文档，不含业务代码）：

• docs/ch01/README.md —— 教程导航与本章验收清单
• docs/ch01/architecture-background.md —— 业务背景、约束、架构分层说明
• docs/ch01/terminology.md —— 术语表
• docs/ch01/decision-record.md —— 选型决策记录

第一份是选型矩阵，放在 decision-record.md 里。它不是「哪个框架最好」的排行榜，而是「某项能力由谁负责」的归属表。

能力诉求	传统大模型 API	Spring AI / LangChain4j	固定 Workflow / BPM	AgentScope Core	AgentScope Harness
单次问答	直接支持	直接支持	需包一层节点	支持	支持
确定性多步流程	手写	手写	强项	可编排	可编排
工具调用循环	手写	有工具抽象，循环较薄	节点内调服务	ReAct 循环	循环 + 工具治理
跨会话记忆	自建表	自建表	自建表	记忆抽象	记忆 + 工作区
子任务委派	无	无	人工拆节点	支持	子 Agent
人工审批	自己写	自己写	强项	需组合	中间件拦截
隔离执行	自己搭	自己搭	通常无	需组合	沙箱
崩溃恢复	自己写	自己写	流程实例可恢复	状态序列化	会话级持久化
可观测	自己埋点	自己埋点	引擎自带	需接 OTel	需接 OTel
主要成本	胶水代码	胶水代码	流程建模	学习曲线	学习曲线 + 运行时

这张表是设计稿，不是实测结果；表中每一项的细节，都应在后续章节用官方文档和固定版本源码逐条核验。

第二份是价值链拆解，说明数字人从「聊天窗口」到「数字员工」到底加了什么：从只会答，到能查知识、能查客户、能办业务、跨会话记得住人、复杂任务能委派、敏感操作能停下来确认、全过程可审计可运营。每加一条，就是往运行时上挂一个能力，而不是往业务代码里加一个 if。

第三份是术语表，见 terminology.md。按四组组织，每组给一句话边界，不做百科展开。

术语	一句话边界
Agent	持有状态、能调工具、能循环决策的执行体
ReAct	推理与行动交替的可终止循环范式
Harness	把循环、工具、记忆、权限装配成长期运行外壳的运行时
Tool	Agent 可调用的受约束能力单元，带入参描述与权限
MCP	工具与上下文接入的标准化协议
Workspace	Agent 的文件与产物工作目录
RuntimeContext	一次运行期间的上下文载体，承载会话、用户、权限等
AgentState	可序列化的执行状态，用于恢复与续跑
Middleware	在循环关键节点插入的拦截与增强层
HITL	人在回路，敏感动作停下来等人确认
Skill	可复用的能力封装，区别于一次性工具
Plan Mode	先产出计划再执行的工作模式
Memory	跨轮次、跨会话的长期信息沉淀
Compaction	上下文压缩，把过长历史摘要化以继续运行
Filesystem	Agent 读写文件的抽象层
Sandbox	隔离执行环境，限制副作用范围
Subagent	被主 Agent 委派执行子任务的 Agent
RAG	检索增强，先取资料再生成
SSE	服务端单向事件流，常用于逐字输出
AG-UI	前端与 Agent 之间的交互协议
A2A	Agent 与 Agent 之间的协作协议
OTel	开放遥测标准，用于链路追踪与指标采集

关于几个术语的边界要特别说明：Memory 不等于把历史消息全塞进上下文，Compaction 也不等于删除历史，前者是沉淀，后者是压缩。Tool 和 Skill 的区别在于复用粒度，一个偏单次调用，一个偏成套能力。Sandbox 解决的是「跑在哪儿」，HITL 解决的是「谁点头」，两者不能互相替代。

第四份是架构背景说明，写清业务边界：注册登录、数字人项目 CRUD、项目配置（名称、标题、主题色、背景图、开场白、结束语）、最小 Agent 配置（agentName、model、systemPrompt）、运行页 /run/{projectId}。本章明确不做口型、表情、动作、复杂视频合成、直播、多租户、计费。

提交建议：

git add docs/ch01
git commit -m "docs(ch01): define AgentScope value scenarios and terminology"

本章的验收动作只有一条：合上文档，能不能用一张表说清三个「为什么不」，并且不看稿解释至少 15 个术语。做不到，就不要往下走。

不写业务码
先写决策书
术语列成表
选型有据依

06、排查

本章是认知型章节，所以「排查」排查的是判断本身，而不是代码报错。下面两条证据链，是这个星期里真实出现过的两次争论。

证据链一：「我 20 行代码就能让模型回答，为什么要引入一个框架？」

现象：同事在评审会上打开 IDE，三分钟写了一个 controller，直接调模型接口，能回答问题。全场安静，这话很难反驳。

为什么容易这么判断：因为在 Demo 场景下，这个判断 100% 正确。一次调用确实只需要 20 行。误判的地方在于，他把「回答」当成了整个需求的全部。

验证方式：把数字人的需求逐条列出来，问一句话——这条需求，一次模型调用能不能覆盖？答案会迅速分化：能覆盖的是「答一句像样的话」，不能覆盖的是「上次聊到哪儿了」「这个客户是谁」「谁批准了这次退款」「服务重启后这条会话还在不在」。后面这些都属于运行时，不属于调用。

结论：能回答 ≠ 能运行。这两件事需要分开评估，混在一起评，一定会得出「不需要框架」的错误结论。

修正做法：在做选型表时，把「调用类需求」和「运行类需求」分成两列，分别打分，不要让一次调用的简洁掩盖运行时的空缺。

证据链二：「Workflow 更可控，生产就该用流程引擎。」

现象：流程引擎能画图、能审批、能回滚、能看实例状态，每一条都是运维喜欢的。而且它确实解决了很多问题。

为什么容易这么判断：因为「确定性」在工程直觉里天然等于「安全」。看到流程图的那一刻，人会觉得一切都在掌控中。

验证方式：问一个问题——数字人的输入能不能预先穷举？用户可能说「帮我看看这个客户最近怎么样」，也可能说「上次那个事处理完了吗」，还可能说「算了，先给我讲讲你们的服务」。这些输入背后是哪条流程分支？枚举不出来。而流程引擎的前提恰恰是分支可提前定义。

结论：不是 Workflow 不行，而是它需要的前提在本场景不成立。它的强项是确定性，而数字人面对的是开放性。把开放性硬塞进确定性框架，等于给每个节点都配一条 default 分支。

修正做法：用「分支是否可穷举」作为第一判据。可穷举，用 Workflow；不可穷举且需要工具与记忆，才考虑运行时。

错误尝试： 我们真的试过一条折中路线——用流程引擎包一层，里面放一个「调用大模型」节点，再补一个 default 分支兜底所有走不通的输入。为什么错：default 分支会把所有没枚举到的意图全部吞掉，而且不报错。它不会抛异常，只会安静地给出一个答非所问的回复。这类失败最难排查，因为监控上看一切正常，只有用户觉得这个数字人「有点笨」。用确定性框架兜住不确定输入，得到的不是可控，而是静默失败。

上游贡献判断：本章以认知与选型为主，未发现可归因到 AgentScope Java 的明确上游问题。按系列规则，暂时只记录一条观察点——「Harness 与 Core 的职责边界在文档中的表述是否足够清晰」，等第 8 式建立源码研究方法、真正能对照 v2.0.3 与 main 之后再判断，现在不构成 Issue/PR 候选。

误判常因熟
证据要落源
一看便知界
再改不为迟

07、优化

证据链给出的是现象，根因只有一句话：我们把「运行时职责」错当成了「调用职责」，于是选型时比较的全是模型集成层的能力。

修正判断，落到三条规范上。

第一条，先问分支是否可穷举。可穷举且没有跨会话状态，直接 Workflow，不要引入 Agent。这一条挡掉了大量本来不该复杂的项目。

第二条，再问状态是否需要跨会话。只在单次会话内有效、重启可丢的，直连模型 API 就够；需要跨会话记住人、记住偏好、记住上次办到哪一步的，才需要 AgentState 与 Memory 这一类设施。

第三条，最后问副作用是否需要治理。只读查询可以放宽；一旦涉及写操作、退款、发消息、改客户资料，就必须有工具权限、审批节点和审计轨迹。

标准化步骤可以直接做成四步决策树：分支可穷举吗？可，用 Workflow。不可，第二轮：有跨会话状态吗？没有，用模型集成层。有，第三轮：有真实副作用吗？没有，Core 级 ReAct 就够，不必上完整 Harness。有，第四轮：副作用需要审批与审计吗？需要，上带中间件与沙箱能力的运行时，并在设计期就把 HITL 画进链路。

新行为是：从这一章开始，团队里任何一个人提出「加一个 Agent」，都必须先回答这四问，答案落进 decision-record.md，而不是落进聊天记录里。

验证方法也很朴素，就是开篇那三个问题。如果一个人能在白板上把这三个问题连成一条线，说明判断成立了：为什么不是直接调模型——因为缺的是运行不是回答；为什么不是纯 Workflow——因为分支不可穷举；为什么在这个项目选 AgentScope——因为状态、工具、审批、恢复需要一个宿主。三问能一次说清，术语能随口解释十五个以上，这一章的优化就算达标。

判断既修正
规范即落地
步骤标准化
新行有法依

08、演进

[同一输入] "帮我查一下张工这个客户的订单，超期就发个提醒"
    |
    +--[V1] 直连 LLM 或写死 Workflow
    |       行为：一次回答，或按固定分支查单、按固定模板发提醒
    |       代价：不记上下文、不能审批、崩了不能恢复、每改一次就改代码
    |
    +--[V2] AgentScope 运行时承载
    |       行为：Tool 查客户 → Memory 取上下文 → HITL 确认发提醒 → 留轨迹
    |       代价：多一层运行时、多一份学习成本、必须治理工具权限
    |
[Trade-off]
得到：能力可叠加、状态可延续、动作可审批、过程可审计
失去：一次调用的极简路径，以及「一切尽在流程图里」的确定性幻觉
边界：意图开放、有真实副作用、需长期运行，三点至少占两点才值得

放在五个维度上比较这两种承载方式。

正确性：V1 在已枚举场景下正确率极高，在未枚举场景下会静默答偏；V2 把未枚举场景交给模型决策，正确率取决于工具质量与提示约束，波动更大，但至少不会假装成功。

稳定性：V1 的稳定性来自确定性，代价是脆弱——需求一变就要动流程；V2 的稳定性来自边界治理，工具越规范越稳，前提是权限与审批真的落地了。

复杂度：V1 起步几乎零复杂度，随需求增长线性堆叠；V2 起步就有一层学习成本，但增量能力的边际成本递减。两条复杂度曲线会在某个点交叉，这个交叉点就是选型分水岭。

成本：V1 的成本主要在人力胶水；V2 的成本包括学习、运行时资源、模型调用与基础设施，必须分开记账，不能把框架许可的免费当成整体成本低。

适用范围：V1 适合意图收敛、生命周期短、以只读为主的场景；V2 适合数字员工、运维助手、审批机器人这类长期在线且带副作用的场景。

遗留问题也要摆在明面上：V2 引入了运行时，就引入了新的可观测需求、新的故障面、新的权限模型。这三样在后续章节必须逐个补齐，否则 V2 只是把胶水从业务代码搬到了运行时配置里，没有本质变化。

同一句问话
两条路殊途
得失常相伴
边界自量度

09、洞见

9.1 选型选的是「谁来持有状态」

五种方案的分界线，不在模型调用能力上，而在状态归属上。传统 API 没有状态，模型集成层给你工具但没有给你状态机，Workflow 把状态放在流程实例里，Core 把状态放在 Agent 里，Harness 把状态放在会话与工作区里。只要你开始问「重启之后这条会话还在吗」，你问的就已经不是模型问题了。

9.2 反直觉判断：模型集成层再成熟，也补不上运行时的空缺

反直觉判断：Spring AI、LangChain4j 这类框架越成熟，越容易让人误以为「Java 侧已经准备好了」。它们确实把模型接入、提示词、工具回调做得很顺，但顺的是调用路径，不是运行路径。一个团队完全可能拥有非常漂亮的模型集成层，同时完全没有记忆、审批、恢复这三样东西。这不是框架的缺陷，是两层的分工不同。

9.3 反直觉判断：Workflow 不是 Agent 的低配版，而是另一类问题的正解

反直觉判断：很多人把 Workflow 当成「还没进化到 Agent 的过渡形态」，这个排序是错的。分支可穷举、需要严格审计、需要可视化回放的场景，Workflow 就是最优解，硬上 Agent 只会把确定性换成不确定性。真正的判据是分支能否穷举，不是技术是否新潮。

同一条反过来也成立：如果一个 Agent 项目里 80% 的路径其实都是确定的，那应该把确定的部分收敛成流程，只把真正开放的部分交给运行时，而不是全盘 Agent 化。

9.4 什么时候不应该用本章这套能力

本章能力，指的是「引入 Agent 运行时并围绕它做架构设计」。不该用的情况至少有五种：只是想给帮助文档加个问答入口；流程分支完全可枚举且短期内不会变；一次性离线批处理，没有交互也没有恢复需求；团队只有一个人且明确只做三个月；以及最关键的——没有任何人愿意长期维护工具权限与审计这条线。最后一条最容易被忽略：运行时能力是有运维成本的，没人负责的运行时，比没有运行时更危险。

反直觉处见
工程判断明
能用与该用
一线之间分

10、系统落地

原来有什么：一个 Spring Boot 服务、一张会话表、一次模型调用，加上 /run/{projectId} 这个运行页的雏形。能演示，不能承重。

本篇新增了什么：没有新增一行业务代码，新增的是四份文档和一套判断标准——教程 README、架构背景说明、22 条术语表、五方案选型矩阵。以及一条团队约定：提 Agent 需求之前先过四步决策树。

现在能做什么：能向业务方解释清楚这个数字人为什么不能只靠一次模型调用；能向技术负责人解释清楚为什么这里不是纯 Workflow；能向团队解释清楚引入运行时之后，哪些能力是可以叠加而不是重写的；能用统一术语讨论 Memory、Compaction、HITL、Sandbox 这些后续一定会用到的概念，不再各说各话。

还缺什么：最小可运行的数字人骨架还没冻结，项目 CRUD、配置模型、运行页、实时会话链路全都停留在文档里；AgentScope Java 的真实 API 还没有被验证过一行；源码研究方法尚未建立，现在所有关于框架内部的判断，都还需要在后面用固定版本源码核对。

下一步如何演进：第 2 式把开发和调试环境搭起来，让「能编译、能断点、能跑测试」成为常态；第 3 式冻结最小数字人 Demo，把本章的架构图变成一个能跑起来的骨架。从那一式开始，后面所有章节都在这套骨架上增量开发，不再换场景。

开源参与点：本章未发现明确上游问题。唯一的观察点是 Harness 与 Core 的文档边界表述，但当前没有形成可复现行为、没有对照 main 分支验证，也不具备最小复现，因此不作为 Issue/PR 候选。系列规则很清楚：先有可复现行为，再有 Issue，最后才是 PR，不为了「有贡献」而制造问题。

原来只有聊
如今能办事
缺者尚可补
下一步自明

11、小结

Q1 → 为什么不是直接调 LLM：数字人缺的不是一次回答，而是可延续的运行
Q2 → 为什么不是纯 Workflow：开放式意图的分支无法预先穷举，硬塞只会静默答偏
Q3 → 为什么在这个项目选 AgentScope：状态、工具、审批、恢复、观测需要一个宿主
状态 → 五方案矩阵 + 22 条术语表 + 选型决策记录，本章可交付

本章没有产出任何可运行代码，产出的是判断力。判断力这种东西没法截图，但它决定了后面二十几章是稳步叠加，还是反复推倒。

需要提醒的是，本章结论都建立在 AgentScope Java v2.0.3 的模块划分与官方文档之上。如果你阅读时 Releases 页已有更新版本，本文的选型逻辑依然成立，但涉及具体模块与 API 的表述，请以你手上的版本为准核验。

一问定价值
二问答边界
三问验术语
状态已成篇

12、作业

12.1 理解题：用一句话说清「模型集成层」和「Agent 运行时层」的分工，并各举两个属于该层的具体职责

参考答案：模型集成层负责把模型接进应用，例如鉴权与重试、结构化输出解析；Agent 运行时层负责让 Agent 能长期运行，例如跨会话状态持久化、工具权限治理与人工审批。判据很简单：换一个模型厂商，职责是否还成立。成立的是集成层，不成立的才是运行时层。

12.2 实战题：为你手头任意一个真实项目，按本章四步决策树走一遍，产出一份三行结论

参考答案：格式可以是「分支可穷举性 → 跨会话状态 → 副作用治理 → 结论」。例如：分支不可穷举、需要跨会话记住用户、涉及写操作，结论是引入运行时并把 HITL 画进链路。如果走完发现分支完全可穷举且没有副作用，结论写「不引入 Agent，用现有流程引擎」同样是一份合格答卷——这份作业考的是判得准，不是判得新。

12.3 排障题：同事说「我加个 default 分支兜底，Workflow 就能处理所有输入了」，你怎么反驳？

参考答案：指出 default 分支会造成静默失败而非显式失败。它不抛异常、监控无告警，只是答非所问，因而最难排查。正确做法是先判断分支是否可穷举，不可穷举就说明这个场景不适合用确定性框架承载，而不是给它加一个吞掉所有意外的出口。

12.4 架构判断题：打开官方仓库，对照固定 tag v2.0.3 的 agentscope-core 与 agentscope-harness 两个模块，找出至少三处「只有 Harness 层才有、Core 层没有」的职责，并说明各自对应本章术语表中的哪个词

参考答案：本题不提供标准答案，正确答案在你的浏览器里。要求是：打开 https://github.com/agentscope-ai/agentscope-java/tree/v2.0.3 ，定位 agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java 与 agentscope-harness/src/main/java/io/agentscope/harness/agent/HarnessAgent.java，再对照官方 harness 架构文档 https://github.com/agentscope-ai/agentscope-java/blob/v2.0.3/docs/v2/zh/docs/harness/architecture.md ，自己判断哪些职责属于运行时装配、哪些属于循环本身。如果你的结论和本章术语表里的边界写法不一致，以官方文档和固定版本源码为准，并把差异记进自己的决策记录。顺手看一眼 Issues 与 Discussions，确认你想提的观察是否已经有人提过——这一步是第 15 式贡献闭环的预演。

四题各一面
理解与动手
排障与判断
做完再前行

13、思考

回到这个项目最初的冲突：一边是「一次调用就能演示」的简单路径，一边是「长期运行、会调工具、要审批、要隔离、要恢复」的真实需求。这两者之间没有中间地带可以长期骑墙——你迟早要选一条承载方式。

本章给出的答案是：先不写代码，先把「谁负责运行」这件事写清楚。因为在大模型应用里，写代码从来不是最贵的环节，选错承载方式才是。

还有一句话值得记住：「会用框架」是能把 Agent 跑起来，「能参与框架演进」是知道它在哪一层薄、哪一层厚，知道什么时候该绕开它、什么时候该给它提一个 Issue。这中间的差距，就是后面二十八式要拉平的东西。

一念辨边界
一证定根因
一择知取舍
一役见真章