AI 极客实战案例日报

01 ｜ 案例是什么？

一个叫 dream-scope 的开源项目，用阿里 ModelScope 出品的 AgentScope Java 2.0 当内核，加 Spring Boot 3.5 做外壳，搭出了一套"模块化单体"的 Agent 运行时。它对外只暴露两个 HTTP 接口（同步 POST /api/agents/invoke 和流式 SSE POST /api/agents/stream），对内把模型、消息编解码、分布式会话（Redis）、长期记忆压缩、混合检索（向量 + 关键词 RRF 融合）、MCP 工具、文件声明的子 Agent 全部装配好。同一时间，掘金上出现了两条独立的中文实战连载——一条来自项目作者「宋哥转AI」的逐层拆解（02/03 篇），一条来自公众号「栈知见」的 16 篇系列开篇——把"Java 怎么写生产级 Agent"这件事第一次讲成了可复制的操作手册。

02 ｜ 为什么今天值得关注？

• 为什么是现在：AgentScope Java 2.0 于 2026 年 7 月 GA（此前 5–6 月连发 RC1–RC5），到 9 月社区才真正沉淀出"照着做能跑"的中文工程样本。09-28（02 篇 Harness 层）、09-29（03 篇知识工具层）、09-30（另一条系列的开篇）三天连续输出，说明学习曲线刚被趟平。
• 为什么以前不容易：过去把 Agent 接进 Java 系统，要么用 HTTP 桥一层 Python 网关（多一跳、难排障），要么用偏"链式编排"的 Java 框架（分布式会话、多租户隔离、沙箱、压缩要自己造）。
• 为什么现在变容易：框架把"上线前看不见、上线后绕不开"的坑做成了内核一等公民——分布式会话、多租户隔离、沙箱、OpenTelemetry 观测、A2A 协议；而国产模型（DashScope / DeepSeek）已经是内置 provider，不需要改代码就能切换。
• 对谁最有价值：中国有海量 Java 后端团队和存量 Spring Boot 系统。这批人"想接 AI 却不想推倒技术栈"的需求，长期缺配套基础设施——今天它出现了。

03 ｜ 案例的前世今生

前世。AgentScope 最早是阿里通义实验室开源的 Python 多智能体框架，解决的是"多 Agent 之间的消息通信、编排、记忆、工具调用每次都要手写"的问题。同期 Java 侧只能用 LangChain4j / Spring AI 这类"以链和流程编排为主"的框架，Agent 的自主推理循环、分布式运行设施都要自己拼。

发展。Java 版从 1.0 的 ReActAgent 内核起步；2026-05 发 v2.0.0-RC1，重做了事件流、消息模型、中间件与 HITL；RC2–RC5 陆续补上无状态 Agent、一行式 DistributedBackend、Channel IM 集成（钉钉 / 飞书 / 企业微信）、A2A / AG-UI 协议、异步工具执行、模型 provider 模块化、原生结构化输出、腾讯云 COS 状态持久化；2026-07 v2.0.0 正式 GA；2026-08 又给出 AgentScope Service（Agent 控制平面 + Dashboard，兼容 LangChain / ADK / Claude / Qoder）。当前稳定线为 2.0.3。

今生。框架能力齐了，缺的是"别人怎么用"。09-28 到 09-30 三天里，中文社区同时补上了这一环：dream-scope 作者把 Harness 工程层、三层检索链路、MCP 三传输、子 Agent 两路声明逐层写出（含真实源码路径），另一位作者则给出 16 篇的大纲总览。再加上 dream-scope 本身在 GitHub 开源（Apache-2.0）、Dream-SaaS 站点已上线可注册体验，这个案例从"框架文档"变成了"可对照复现的工程样本"。

下一步可能怎么发展（分析 / 推演，非事实）：① AgentScope Java 很可能成为国内"企业 Agent 中台"的默认选型之一，与 Spring AI Alibaba 形成互补；② dream-scope 这类"参考实现"会演化成可售卖的行业模板（金融 / 制造 / 政企）；③ Java Agent 交付能力会变成外包与咨询市场的硬通货。

04 ｜ 原始资料

• 实战长文《AgentScope Java 实战 03：知识与工具层——给 Agent 装上手和书架》（作者：宋哥转AI，2026-09-29）
• 实战长文《AgentScope Java 实战 02：Harness 工程层，把内核装进生产边界》（作者：宋哥转AI，2026-09-28）
• 系列开篇《01-开篇-AgentScope-Java 是什么》（作者：公众号「栈知见」，2026-09-30）
• 开源项目github.com/logosssss/dream-scope —— 基于 AgentScope Java 2.0 的模块化单体 Agent 运行时（Apache-2.0）
• 开源项目github.com/logosssss/dream-ai —— Agent 运行时核心（Java 模块化单体，Apache-2.0）
• 在线产品dream-saas.com —— Dream-SaaS，作者已上线的多 Agent 实战平台
• 官方仓库github.com/agentscope-ai/agentscope-java —— AgentScope Java 官方仓库

05 ｜ 作者是谁？

dream-scope / Dream-SaaS 作者：掘金用户「宋哥转AI」（对应公众号「Java宋转AI」，GitHub 账号 logosssss）。从文章内容判断为一线 Java 后端 / 架构实践者，独立完成了从框架选型、六模块拆分、Redis 会话、三层检索到上线部署的完整链路，并自建 Dream-SaaS 站点做验证。其真实姓名与所在公司未公开，不做猜测。

另一条系列的作者：公众号「栈知见」，2026-09-30 起发布 16 篇 AgentScope Java 连载开篇，自述面向"有 Spring Boot 经验的 Java 工程师"。身份未进一步披露。

06 ｜ 解决了什么真实问题？

从需求说起，而不是从技术说起。中国大量企业的核心业务系统跑在 Java / Spring Boot 上，这些团队想上 AI 时会撞上五堵墙：

• 会话活不下来：Agent 的对话状态放在内存里，进程一重启全丢，多副本部署直接串号。
• 多租户隔离靠自觉：同一进程服务多个用户 / 部门时，谁的数据谁能看，靠业务代码自己记得写。
• 上下文越聊越炸：多轮对话只增不减，早晚撞模型窗口，成本一路涨。
• 知识检索答不准：专有名词、产品型号这类强字面信号，纯向量检索拉不开距离，答案缺引用来源。
• 工具能把主机搞坏：Agent 拿到文件读写和 Shell，HTTP 进程里跑一条命令就可能毁掉开发机。

dream-scope 的价值在于：它把上面五件事都给出了有源码位置的具体答案（Redis 分布式会话、(userId, sessionId) 寻址、Compaction 按条数压缩、向量+BM25+RRF 混合检索、运行期禁用 stdio 并关闭文件/Shell 工具），而不是停在"建议你这么设计"。

07 ｜ 完整技术栈

模型	默认 dashscope:qwen-plus（通义千问）；支持 deepseek: / openai: / anthropic: / gemini: / ollama: 前缀切换；视觉场景可换 qwen-vl-plus
Agent 框架	AgentScope Java 2.0.3（core + harness + extensions-redis + extensions-model-dashscope）
语言 / 构建	Java 21，Maven 3.9+
应用框架	Spring Boot 3.5.5（Jakarta），Spring Cloud Alibaba 2025.0.0.0（Nacos Config + Discovery，默认关闭）
协议 / 接口	REST（/api/agents/invoke）、SSE（/api/agents/stream）、MCP（streamableHttp / sse）、A2A（Agent Card + /a2a）
数据 / 中间件	Redis 7（分布式会话，必选，Docker Compose 一键起）；PostgreSQL + pgvector（可选，生产检索）；Nacos 3.x（可选，需 gRPC 9848）；Jedis
观测	Actuator（health / info / metrics / prometheus）+ OpenTelemetry（OtelTracingMiddleware）+ 自定义 LoggingMiddleware
前端	dream-scope-ui：Vue + Vite（开发端口 5173）
部署	Docker Compose；默认端口 8091（主路径） / 8092（官方 starter 对照入口） / 8093（内置演示 MCP）
许可证	Apache License 2.0

08 ｜ 完整 Workflow

09 ｜ 它到底是怎么实现的？

• ReAct + Harness 双层，只叠加不替换。底层 ReActAgent 只管"推理—行动—回填"循环；上层 HarnessAgent 是一层薄包装，用 builder 挂点把 workspace、分布式存储、记忆压缩、子 Agent、中间件、计划模式叠在循环外围。业务从 ReActAgent 起步，需要长期运行时可无缝迁到 HarnessAgent。
• 三个共享对象 = 全部衔接面。RuntimeContext（本次调用的身份）、Workspace（约定文件读写）、AgentStateStore / DistributedStore（跨调用状态恢复）。Harness 的各项能力互不依赖，只通过这三个对象通信。
• 六边形边界靠构建期强制。模块拆成 bom / domain / adapter / knowledge / web / boot / ui；dream-scope-domain 禁止 import io.agentscope.*，检索逻辑因此可以脱离框架单测。
• 只有装配点做条件分支。"用 distributedStore 还是 stateStore"的二选一只出现在 ScopeChatAgent 构造器里；运行期不散落 if-else。
• 失败路径全部有归宿。Redis 连接启动即 ping，失败直接抛错让进程起不来（fail fast）；检索 provider 分 auto / pg / simple / keyword 四档，auto 档的降级链是 pg → 内存向量 → 关键词。

10 ｜ 手把手复现

1. Step 1 · 环境：JDK 21、Maven 3.9+、Docker（Redis 必选）；Node 20+（只在跑前端时需要）。
2. Step 2 · 拉代码：git clone https://github.com/logosssss/dream-scope.git && cd dream-scope，并 cp .env.example .env（进程不会自动加载 .env）。
3. Step 3 · 起 Redis：docker compose up -d redis。
4. Step 4 · 配 Key：设置 DASHSCOPE_API_KEY；可选 DREAM_SCOPE_MODEL_CHAT=dashscope:qwen-plus。
5. Step 5 · 跑测试再启动：mvn -q test → mvn -pl dream-scope-web -am spring-boot:run（默认 8091）。
6. Step 6 · 冒烟调用：curl -s http://localhost:8091/api/agents/invoke -H "Content-Type: application/json" -d '{"input":"你好"}'。
7. Step 7 · 起前端（可选）：cd dream-scope-ui && npm install && npm run dev，浏览器开 http://127.0.0.1:5173。
8. Step 8 · 对照实验（强烈建议）：mvn -pl dream-scope-boot -am spring-boot:run 起 8092 端口，这是官方 starter 装配的 ReActAgent（内存 Memory、空 Toolkit、无 Redis / 无子 Agent）。同一台机器上对比 8091 与 8092，能直观理解"Harness 层到底加了什么"。

11 ｜ Prompt / Code / Config（原文公开的部分）

Maven 依赖（官方 README 公开）：

<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-harness</artifactId>
  <version>2.0.3</version>
</dependency>
<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-extensions-model-dashscope</artifactId>
  <version>2.0.3</version>
</dependency>

官方最小 Agent（README 公开，Java 21）：

HarnessAgent agent = HarnessAgent.builder()
    .name("assistant")
    .sysPrompt("You are a helpful AI assistant.")
    .model("dashscope:qwen-plus")     // 自动读 DASHSCOPE_API_KEY
    .workspace(Paths.get(".agentscope/workspace"))
    .build();

RuntimeContext ctx = RuntimeContext.builder()
    .sessionId("demo").userId("alice").build();

工具定义与"业务上下文不过模型手"（作者 03 篇公开）：

public record UserContext(String tenantId, String userId) {}

@Tool(name = "list_my_orders", description = "查询当前用户的订单")
public String listOrders(UserContext ctx,        // 无 @ToolParam → 框架从 RuntimeContext 注入
                         @ToolParam(name = "status", required = false) String status) {
    return query(ctx.tenantId(), ctx.userId(), status);
}

Compaction 配置（作者 02 篇公开）：

CompactionConfig.builder()
    .triggerMessages(30)   // 30 条触发压缩
    .keepMessages(10)      // 保留最近 10 条原文
    .keepTokens(0)         // 显式关闭 token 阈值，避免两个阈值互相打架
    .build();

12 ｜ 踩坑（来自作者原文与 README）

13 ｜ 中国用户能不能直接做？

国内访问	✅ 完全可用。模型走阿里云百炼 DashScope；依赖全部来自 Maven 中央仓，可配国内镜像加速。
注册	阿里云账号 + 百炼开通，国内手机号即可；无需海外信用卡。
API	DASHSCOPE_API_KEY 一个环境变量即可跑通；换 DeepSeek 只需改 model 前缀 + 对应 Key。
成本	开源项目本身 0 元；主要成本是模型 token。可选本地 Ollama 把推理成本压到电费。
技术门槛	开发者级 需要 JDK 21、Maven、Docker、Redis，以及能读懂 Spring Boot 与依赖注入。有 Java 后端经验的人 1–2 天可跑通。

14 ｜ 中国企业可以怎么用？

• 存量 Java 系统的"AI 入口"。银行、制造、政企的大量核心系统是 Spring Boot。直接在既有工程里引 agentscope-harness，把 Agent 做成一个 Bean，通过 /api/agents/invoke 暴露给前端；会话状态接公司已有的 Redis。
• 企业内部知识助手（带引用）。把制度文档、产品手册、接口约定灌进 pgvector，用 retrieve 工具做向量 + 关键词混合检索 + 精排，答案带 [1][2] 编号可溯源。
• 多租户 AI 中台。用 (userId, sessionId) 贯通工作区路径、存储命名空间与沙箱，让一条业务线一个租户，数据隔离由框架强制而非靠代码自觉。
• 遗留系统 SOP 自动化。用 Markdown 写 subagents/xxx.md 声明专职子 Agent，把"售后政策问答""报价草稿""日志初筛"等固定流程固化，不写 Java 就能加一个子 Agent。

15 ｜ 如何迁移到其他行业

16 ｜ 培训课程设计

17 ｜ 培训师点评

18 ｜ 最终判断

01 ｜ 案例是什么？

LangChain 1.0 把 Agent 的重心从"链"改成了"钩子"：核心入口只剩一个 create_agent，其余能力通过 middleware（中间件）在 Agent 生命周期上打点。2026-09-30，掘金作者「码农悟道」发了一篇实战文章，用六大钩子写出完整可运行代码，并明确适配阿里百炼新版模型 qwen3.7-flash：任务前置拦截（权限）、模型调用前预处理（压缩上下文/切换大小模型）、模型调用包装（重试/熔断/耗时/Token 统计）、工具调用包装（重试/入参校验/脱敏/审计）、输出后置审核（内容安全/格式修复）、任务收尾统计（全链路 Token 与工具次数归集）。它解决的是一个非常具体的工程问题：Agent 业务代码正在被通用基建代码淹没。

02 ｜ 为什么今天值得关注？

• 为什么是现在：LangChain 1.0 于 2025-10 正式 GA（GA 当晚同时推出 LangGraph 1.0），把 create_react_agent 换成 create_agent、把中间件抬为一等公民。到 2026 年 9 月，官方已内置 PIIMiddleware / SummarizationMiddleware / HumanInTheLoopMiddleware 等预置中间件——意味着"切面治理"已经是官方推荐范式，而中文实战内容才刚刚跟上。
• 为什么以前不容易：1.0 之前想控制 Agent 执行的中间过程，只能用 callback handler、继承子类或 fork 预置图；企业上线时只能把权限、脱敏、计费硬塞进业务逻辑。
• 为什么现在变容易：钩子把"在哪一刀切"变成声明式配置；同时国产模型的兼容性已被社区跑通——文章里百炼走的是 OpenAI 兼容端点 dashscope.aliyuncs.com/compatible-mode/v1，模型名直接用 qwen3.7-flash-2026-07-15。

03 ｜ 原始资料

• 原文《LangChain Agent 切面钩子实战：解耦业务，一键复用通用能力》（作者：码农悟道，2026-09-30）
• 官方文档LangChain v1 官方发布说明（Python）：create_agent、middleware 六大钩子、预置中间件
• 模型侧阿里云百炼 OpenAI 兼容端点：https://dashscope.aliyuncs.com/compatible-mode/v1

04 ｜ 解决了什么真实问题？

从企业侧的需求讲：一个 Agent 上线前，技术负责人一定会问五个问题——谁能用？聊久了会不会爆上下文？模型接口抖动会不会让流程挂掉？工具返回的手机号会不会漏？这个月谁花了多少钱？原文的痛点描述很直白："每新建一个 Agent 就重复写一遍，不仅代码臃肿冗余，各个项目的规则还参差不齐，后期维护简直是噩梦。"

05 ｜ 完整技术栈

模型	阿里百炼 qwen3.7-flash-2026-07-15（走 OpenAI 兼容端点）
框架	LangChain 1.0（langchain.agents.create_agent + langchain.agents.middleware）
语言	Python（langchain_openai.ChatOpenAI 作为统一客户端）
依赖	langchain、langchain-openai、langchain-core、python-dotenv
关键参数	stream_usage=True（流式下拿 Token 用量）、temperature=0、max_tokens=2048

06 ｜ 完整 Workflow

07 ｜ 它到底是怎么实现的？

• 核心机制是"洋葱包裹 + next 短路"。每个钩子拿到本次的 request 和一个 handler（next）。调用 handler(request) 才会继续往下走；不调用就是短路——这正是中间件能"拦截"的原因。
• 官方钩子语义：before_agent（调 Agent 前，载入记忆 / 校验输入）、before_model（每次 LLM 调用前，改提示词 / 裁剪消息）、wrap_model_call（包裹每次 LLM 调用）、wrap_tool_call（包裹每次工具调用）、after_model（每次 LLM 响应后，校验输出 / 加护栏）、after_agent（Agent 完成后，保存结果 / 清理）。
• 为什么能省 Token：入口拦截无效请求（一次 LLM 都不调），以及调用前压缩上下文（长会话不再把全部历史带过去）。
• 为什么脱敏要放在工具出口：数据是在工具返回值里出现的，不是在模型输出里生成的。在 wrap_tool_call 拦截返回内容，能在数据进入上下文之前就把它改掉。
• 为什么计费要放在收尾：不管 Agent 正常结束还是中途异常终止，收尾钩子都会百分百触发，保证"每一次调用都有账可查"。

08 ｜ Prompt / Code / Config

from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
from langchain.agents.middleware import (wrap_model_call, wrap_tool_call,
                                        before_model, ModelRequest, ToolCallRequest)

llm = ChatOpenAI(
    model="qwen3.7-flash-2026-07-15",
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="你的API_KEY",
    temperature=0, stream_usage=True, max_tokens=2048,
)

@before_model                                   # ① 权限拦截（原文示例）
def before_agent_permission(state, runtime):
    if runtime.context.get("user_id") != "admin_001":
        raise Exception("【权限拦截】无企业数据查询权限")
    return state

@before_model                                   # ② 上下文精简
def model_trim_middleware(state, runtime):
    msgs = state.get("messages", [])
    if len(msgs) > 5: state["messages"] = msgs[-3:]
    return state

@wrap_model_call                                # ③ 重试 / 熔断 / 耗时
def model_retry_middleware(request, handler):
    ...  # max_retry=2，失败 sleep(1) 后重试

@wrap_tool_call                                 # ④ 工具脱敏 + 审计
def tool_secure_middleware(request, handler):
    result = handler(request)
    if isinstance(result, ToolMessage) and "13800138000" in result.content:
        result.content = result.content.replace("13800138000", "*******")
    return result

agent = create_agent(
    model=llm, tools=tools,
    middleware=[before_agent_permission, model_trim_middleware,
                model_retry_middleware, tool_secure_middleware, ...],
    system_prompt="简洁准确回答用户问题",
)

Token 统计的关键一行（原文强调的国产模型适配点）：百炼新版 qwen3.7-flash 在 response_metadata["token_usage"] 里只返回总 Token、没有输入/输出细分字段，作者用 total_tokens 采集并加了防重复统计标记。

09 ｜ 踩坑

10 ｜ 中国用户能不能直接做？

国内访问	✅ 可用。百炼端点在境内；pip 安装可用清华等镜像加速。
注册	阿里云账号 + 百炼开通，国内手机号即可，无需海外支付方式。
成本	0 元可试 代码本身 0 成本，用免费额度即可跑通全部六个钩子；转生产后按 token 计费。
技术门槛	有一定门槛 需要会 Python、理解 Agent 循环与装饰器；不需要 GPU、不需要 Docker、不需要服务器。

11 ｜ 企业场景

• 内部数据查询助手的权限门禁。不同部门查不同库。用 before_agent 做入口拦截（一次 LLM 都不调就拒绝），用 before_model 按角色动态改提示词与可用工具。
• 数据脱敏与合规输出。在 wrap_tool_call 统一对返回内容做脱敏（手机号、身份证、地址），在 after_model 做输出侧敏感词拦截。形成"进也拦、出也拦"的双层合规。
• Agent 成本核算与部门分摊。把收尾钩子采集的 Token 数与工具次数写进日志系统，按 user_id 归集——这是"AI 成本能不能说清楚"的问题。
• 多 Agent 复用同一套规范。新做一个 Agent 时，直接挂上同一组中间件，天然继承权限、脱敏、计费规则。

12 ｜ 如何迁移到其他行业

13 ｜ 培训师点评

14 ｜ 最终判断