DoneHub

如果你在构建 Agent，一定想过这个问题：怎么让 Agent 跨会话记住用户的偏好、项目的背景、之前犯过的错误？大部分人的做法是搞一个文件，把所有「需要记住的东西」往里塞。文件越来越大，token 成本越来越高，而且大部分内容跟当前对话根本没关系。Claude Code 的记忆系统给出了一个反直觉的设计原则：工程量最大的部分不是「怎么存」，也不是「怎么取」，而是「什么该存、什么不该存」。

一、核心哲学：记忆是代码的补集

这套记忆系统的设计哲学可以用一句话概括：

记忆是代码的补集。

听起来简单，但这是整个设计里最有启发性的原则。具体来说：

该存的：全部是「关于人和上下文」的信息——人的偏好、纠正、动机、外部资源指针。这些藏在代码之外，不查记忆就无从得知。

不该存的：全部是「关于代码和项目状态」的信息——代码是实时的、可查的、权威的。代码能回答的问题，不要让记忆来回答。

这个分界线一旦清晰，你会发现很多之前觉得「应该记住」的东西，其实根本不该存。

二、四种该存的记忆

2.1 用户记忆：记用户是谁

用户记忆记录的是用户的角色、技术背景、工作习惯、知识水平。

好的例子：

「这个用户是数据科学家，目前在做日志系统的调研。」

「这个用户写了十年 Go，但第一次碰 React。」

这类记忆的设计意图是让 Agent 能调整沟通方式和工作策略。面对一个资深后端工程师，Agent 不需要解释基础概念，可以直接用技术术语；面对一个初学者，Agent 需要更耐心地铺垫背景。

关键约束：记忆的目的是「怎么更好地帮这个人」，不是「给这个人画像」。不要记录对用户的负面评价，也不要记录跟工作无关的个人信息。

1
2
3

❌ 不要记：「这个用户脾气不好，经常发火」
❌ 不要记：「这个用户喜欢喝咖啡」
✅ 要记：「这个用户偏好简洁回复，不需要末尾总结」

2.2 反馈记忆：记纠正和肯定

这是四种记忆里设计最精细的一种。源码里对它有三个关键要求。

要求一：规则 + 原因 + 适用场景

每条反馈记忆必须包含三个部分：

1

规则是什么 → Why → 什么时候该应用

举个实际例子。用户说：

「测试不要 mock 数据库，上个季度我们就是因为 mock 测试通过了但生产环境迁移失败才出的事故。」

如果只记「不要 mock 数据库」，Agent 在所有测试里都不敢 mock，包括那些跟数据库迁移完全无关的单元测试。

但如果它知道原因是「mock 和生产环境行为不一致导致迁移失败」，它就能判断：集成测试不该 mock，但纯逻辑的单元测试 mock 是没问题的。

记原因，是为了让 Agent 能在新场景下做判断，而不是机械地执行规则。

要求二：不要只记纠正，也要记肯定

源码注释里说得很直白：

如果你只记录用户说「不要这样做」的时刻，它只知道什么是错的，不知道什么是对的。时间长了，它会回避一切不确定的做法，变得畏手畏脚。

但肯定信号比纠正信号更难捕捉。用户说「不要这样做」很明显，但用户说「对，就是这样」或者默默接受了一个不寻常的方案，需要主动注意这些肯定信号。

例子：

用户说：「对，这次用一个大 PR 是对的，拆开反而是无意义的工作量。」

这条记忆的价值是：下次遇到类似的重构场景，Agent 知道这个用户倾向于合并提交，而不是拆成很多小 PR。这不是纠正，是一个被验证过的判断。

要求三：区分个人偏好和项目规范

「不要在回复末尾加总结」→ 个人偏好，只对这个用户有效

「集成测试必须用真实数据库」→ 项目规范，对所有协作者有效

源码里用 scope 来区分这两种。个人偏好存在私有目录，项目规范存在团队共享目录。

2.3 项目记忆：记正在发生什么

项目记忆记录的是当前项目里正在发生的事：谁在做什么、为什么要做、截止日期是什么。

例子：

「本周四之后冻结所有非关键合并，移动端团队要切发布分支。」

「正在重写认证中间件，原因是法务团队指出旧的 token 存储方式不符合合规要求，所以做决策的时候要优先考虑合规性而不是技术优雅。」

关键规则：相对日期必须转换成绝对日期

用户说「周四冻结」，记忆里存的是具体的年月日，比如「2026-03-07」。

为什么？因为记忆是跨会话的。如果存「周四」，下周再看这条记忆就不知道是哪个周四了。

另一个特点：衰减得很快

一个月前的项目状态大概率已经过时了。所以源码要求项目记忆必须记录「为什么」。即使事实过时了，背后的动机仍然有参考价值。

1
2

事实过时：「正在重写认证中间件」→ 可能已经写完了
动机仍有效：「合规要求优先于技术优雅」→ 这个决策原则长期有效

2.4 引用记忆：记外部资源在哪里

引用记忆记录的是外部资源的位置：bug 在哪个系统里追踪、监控面板的地址是什么、设计文档在哪个平台。

例子：

「流水线相关的 bug 都在 Linear 的 INGEST 项目里追踪。」

「API 延迟的监控面板在 grafana.internal/d/api-latency，值班的时候看这个。」

这是四种里最简单的，但也是最实用的。它本质上是一个「去哪里找信息」的索引。

三、五种不该存的东西

这部分才是整个设计里最有启发性的。很多人做记忆系统的第一件事，就是把不该存的东西全存了。

3.1 代码模式、架构、文件路径、项目结构

这是最反直觉的。很多人觉得 Agent 应该记住「项目用了什么框架、目录怎么组织、哪个文件负责什么」。

Claude Code 说：不要存这些。

为什么？因为这些信息可以直接从代码里读出来。Agent 随时可以通过读代码和搜索来获取当前的项目结构。

把这些存进记忆有两个问题：

1
2
3
4
5

问题一：浪费空间
每次对话都要加载一堆本来可以实时查的信息

问题二：过时风险
代码改了但记忆没更新 → Agent 基于过时信息决策 → 很难发现

背后的原则：如果一个信息可以从当前项目状态推导出来，就不要存进记忆。记忆只存那些「看代码看不出来」的东西。

3.2 版本管理历史

谁改了什么、最近的提交记录——这些用版本管理工具查就行了。

Git 是实时的、权威的，不需要记忆来存一份可能过时的副本。

3.3 调试方案和修复方法

修复已经在代码里了，提交信息里有上下文。存「怎么修的」没有意义，因为代码本身就是最好的参考。

3.4 配置文件里已经写过的东西

如果你的项目里有 CLAUDE.md 或其他配置文件已经定义了编码规范，记忆系统不需要再存一份。

重复存储不仅浪费空间，还会在两份内容不一致的时候制造混乱。

1
2
3

配置文件说：「使用 pnpm」
记忆文件说：「使用 npm」
→ Agent 该听谁的？

3.5 临时性的任务细节

当前正在做什么、对话里的中间状态——这些是短期的，属于当前会话的上下文，不该进入长期记忆。

四、一条特别重要的规则

即使用户明确要求你记住某些东西，如果它属于上面五类，也不该记。

例子：

用户：「记住这周的 PR 列表」

Agent 不应该直接存 PR 列表，而应该反问：

「这些 PR 里有什么让你意外的或者不明显的？那个部分才值得记。」

活动日志不是记忆，从活动中提炼出的洞察才是。

用户要求存不该存的内容时，正确的做法是提炼价值点。PR 列表本身不该存，但如果某个 PR 的处理方式让用户觉得「这样做是对的」，那个判断才值得存成反馈记忆。

五、信息来源决策树

把上面的原则整理成一个判断流程：

1
2
3
4
5
6
7
8
9
10

这条信息能从代码/工具实时获取吗？
         │
         ├── 能 → 不存，实时查
         │
         └── 不能 → 属于哪种类型？
                         │
                         ├── 用户特征 → 用户记忆
                         ├── 纠正/肯定 → 反馈记忆
                         ├── 项目动态 → 项目记忆
                         └── 外部资源 → 引用记忆

六、实践中的常见错误

错误一：把记忆当成项目文档

1
2

❌ 存储：「src/auth 目录负责认证逻辑，包含 middleware.ts 和 token.ts」
✅ 实时查：Glob + Read 工具

错误二：把记忆当成聊天记录

1
2

❌ 存储：「用户昨天问怎么配置 Redis，我回答了...」
✅ 不存：这是会话上下文，不是长期记忆

错误三：记了规则但没记原因

1
2
3

❌ 存储：「不要用 forEach」
✅ 存储：「避免在 async 函数里用 forEach，原因是 forEach 不等待 Promise 完成，
         曾导致批量写入只执行了一半，适用场景是异步批量操作」

错误四：只记纠正不记肯定

1
2

❌ 只存：「不要在回复末尾加总结」
✅ 也要存：「用户确认：重构时用一个大PR是对的，拆开反而增加工作量」

七、记忆系统的质量检验清单

在写入一条记忆之前，问自己这些问题：

1
2
3
4
5
6

□ 是否存了代码可查的内容？→ 删除或反问用户
□ 是否包含「为什么」？→ 补充动机
□ 是否指定适用范围？→ 补充项目/模块边界
□ 相对时间是否转绝对时间？→ 如「明天」→「2026-03-16」
□ 是否存在相似记忆？→ 合并去重
□ 敏感信息是否过滤？→ 拒绝存储密码、密钥、PII

八、总结

Claude Code 记忆系统的核心设计可以概括为一句话：少而精。

记忆的价值不在于数量，而在于每条记忆都能在关键时刻减少认知负担。

如果你在给自己的 Agent 做记忆系统，这个分类框架可以直接拿来用：

四种该存：

• 用户是谁（角色、背景、习惯）
• 用户纠正和肯定过什么（含规则、原因、适用场景）
• 项目背后的动机和时间线（相对日期→绝对日期）
• 外部资源在哪里（索引而非内容）

五种不该存：

• 代码能告诉你的一切
• 版本历史能告诉你的一切
• 提交记录能告诉你的一切
• 配置文件已经说过的一切
• 临时性的中间状态

这样做的好处是：你的记忆文件会非常精简，每一条都是高价值的、代码里找不到的信息。模型每次加载记忆的时候，看到的全是有用的东西，没有噪声。

相关文章：

• Memory 系统：跨会话持久化知识库 — Claude Code 记忆系统的技术实现细节
• Claude Code 源码深度解析系列 — 更多 Claude Code 架构分析

背景

2026年4月24日，DeepSeek 正式发布了 V4 系列模型。这不是一次普通的版本迭代——它解决了一个困扰 AI 行业多年的根本问题：长上下文的效率瓶颈。

本文将深入解读 DeepSeek V4 的核心技术创新，帮助你理解这次发布为何值得关注。

一、模型规格：更大但不更贵

DeepSeek V4 发布了两个版本：

对比上一代 V3.2（671B 总参数，37B 激活），V4-Pro 参数量翻了 2.4 倍，但激活参数仅增加 32%。更重要的是，两者都原生支持 100万 token 上下文——这是之前任何开源模型都做不到的。

为什么”更大但不更贵”？

得益于 MoE（Mixture-of-Experts）架构，每次推理只激活一小部分参数。V4-Pro 的激活率仅为 3%（49B/1.6T），这意味着：

• 推理成本接近一个 50B 参数的稠密模型
• 但拥有 1.6T 参数的知识容量和表达能力

这是 DeepSeek 从 V2 开始就坚持的技术路线，V4 把这个策略推向了新高度。

二、核心架构创新：打破 O(n²) 的魔咒

Transformer 的标准注意力机制计算复杂度是 O(n²)——序列长度翻倍，计算量翻四倍。当上下文达到百万级别时，这变成了不可承受之重。

DeepSeek V4 用混合注意力架构彻底解决了这个问题。

2.1 CSA（Compressed Sparse Attention）

CSA 的核心思路是：压缩 + 稀疏选择。

1
2
3
4
5

原始序列：n 个 token
     ↓ 压缩（每 m 个 token 合成一个 KV entry）
压缩序列：n/m 个 compressed KV entry
     ↓ 稀疏选择（Lightning Indexer 选 top-k）
参与计算的：k 个 compressed KV entry

具体流程：

1. KV Cache 压缩：将每 m 个 token 的 KV entry 通过加权聚合压缩成一个条目，序列长度降到 1/m
2. Lightning Indexer：为每个 query token 生成 indexer queries，与压缩后的 KV 偂相似度计算，选出 top-k 个最相关的压缩块
3. Core Attention：只在选出的 k 个压缩块上做完整的 attention 计算

关键参数（V4-Pro）：

• 压缩率 m = 4（每 4 个 token 压缩成 1 个）
• Indexer head 数 = 64，head 维度 = 128
• Top-k = 1024（每个 query 只关注 1024 个压缩块）

2.2 HCA（Heavily Compressed Attention）

HCA 是更激进的压缩策略，用于处理”不需要精细关注的历史信息”：

1
2
3

压缩率 m' = 128（每 128 个 token 合成一个 KV entry）
     ↓
直接对压缩后的 KV 做完整 attention（不做稀疏选择）

HCA 的哲学是：远处的信息可以”模糊处理”，近处的信息才需要精细关注。

2.3 混合架构设计

V4 不是全用 CSA 或全用 HCA，而是交替使用：

• 前 2 层：纯滑动窗口 attention（保留近期信息的精细度）
• 后续层：CSA 和 HCA 交替，形成”粗细结合”的信息处理

这种设计让模型既能高效处理长上下文，又能保持对关键信息的精确检索能力。

2.4 效率提升有多夸张？

官方给出了硬核数据（100万 token 上下文场景）：

这意味着：以前跑不起的百万级上下文任务，现在可以在单卡上跑了。

三、mHC：残差连接的”数学升级版”

残差连接 x + F(x) 是 Transformer 的基石，但深层堆叠时会遇到问题：

• 信号可能逐层放大 → 数值爆炸
• 信号可能逐层衰减 →梯度消失

DeepSeek V4 引入了 Manifold-Constrained Hyper-Connections (mHC)，用数学约束解决这个问题。

核心思路

传统残差连接：

1

X_next = X + F(X)  // 简单加法

mHC：

1
2
3

X_next = B·X + C·F(A·X)  // A、B、C 是线性映射矩阵
         ↑
      B 约束在双随机矩阵流形上（行和=1，列和=1，元素≥0）

关键约束：B 的谱范数 ≤ 1，这意味着信号传播是”非膨胀的”，不会爆炸。

为什么叫”流形约束”？

双随机矩阵构成的空间是一个流形（Manifold）——Birkhoff Polytope。mHC 通过 Sinkhorn-Knopp 算法，把矩阵 B 投影到这个流形上：

1
2
3

1. 对 B 取 exponential（保证正元素）
2. 迭代做行归一化、列归一化
3. 收敛到一个双随机矩阵

这套数学确保了深层堆叠时的稳定性，同时保留了模型的表达能力。

四、Muon 优化器：万亿参数训练的新配方

训练万亿参数模型，AdamW 已经不够稳了。V4 引入了 Muon 优化器。

核心算法

1
2
3
4
5

G = gradient
M = momentum_buffer
M = μ·M + G  // 动量累积
O = HybridNewtonSchulz(μ·M + G)  // Nesterov trick + 正交化
W = W·(1 - ηλ) - η·O  // weight decay + update

关键步骤是 Hybrid Newton-Schulz 迭代，把梯度矩阵正交化：

1
2
3
4
5
6

# 10 步迭代，分两阶段
# Stage 1（前 8 步）：快速收敛
M_k = 3.4445·M_{k-1} - 4.7750·(M·M^T)·M + 2.0315·(M·M^T)^2·M

# Stage 2（后 2 步）：精确定位到正交矩阵
M_k = 2·M_{k-1} - 1.5·(M·M^T)·M + 0.5·(M·M^T)^2·M

正交化的好处：

• 避免”跑偏”——梯度方向更明确
• 避免”数值爆炸”——矩阵谱范数被约束
• 收敛更快——不需要 Adam 的二阶矩估计

配合稳定性技术

V4 还用了两招来防止 loss spike：

1. Anticipatory Routing：路由决策用”历史参数”而非”当前参数”，打破 MoE 路由的恶性循环
2. SwiGLU Clamping：把 SwiGLU 的线性分量 clamp 到 [-10, 10]，直接压制异常值

五、FP4 量化感知训练：天生适应低精度

以往的量化是”训练后补救”——模型在高精度下训练，推理时强行降精度，性能必然下降。

V4 的创新：训练时就让模型适应 FP4。

应用范围

• MoE 专家权重：占模型大部分参数，FP4 压缩节省大量显存
• QK 路径（Lightning Indexer 的 indexer 部分）：长上下文检索的核心计算，FP4 加速

关键技术点

FP4 → FP8 的无损反量化：

1
2
3
4

FP4 (E2M1) → FP8 (E4M3)
          ↑
FP8 多 2 个 exponent bit，动态范围更大
只要 block 内的 scale factor 差异不超过阈值，信息完全保留

这意味着：

• 训练时用 FP8 做计算（模拟 FP4）
• 推理时直接用 FP4 权重，零性能损失
• 整个 pipeline 可以复用现有的 FP8 训练框架

六、训练基础设施：工程硬核

V4 的基础设施投入展现了”长期主义”的工程思维。

6.1 TileLang：Kernel 开发的 DSL

传统 CUDA Kernel 开发效率低、难迭代。V4 用 TileLang 这个 DSL：

• 用声明式语法描述 Kernel 逻辑
• Z3 SMT Solver 做形式化分析（证明正确性）
• 自动生成高性能 CUDA 代码

开发效率 + 运行效率，两者兼得。

6.2 确定性训练

V4 的 Kernel 全程批不变（Batch-Invariant）：

• 同一 token 无论在 batch 哪个位置，输出 bitwise 一致
• 用特殊设计避免了原子加法带来的不确定性
• 训练过程可复现，调试有据可查

这对大规模训练调试、定位问题至关重要。

6.3 MoE EP 的细粒度重叠

Expert Parallelism 的通信开销大。V4 把 MoE 层拆成 4 个阶段：

1

Dispatch (通信) → Linear-1 (计算) → Activation → Linear-2 (计算) → Combine (通信)

关键洞察：计算时间 > 通信时间，所以通信可以被计算掩盖。

V4 把专家分成”wave”，每个 wave 的通信和计算流水线化，实现 1.5-1.96× 加速。

七、性能基准：开源模型的新标杆

知识任务

V4-Pro-Max 在知识任务上领先开源对手 20+ 百分点，但距离 Gemini 3.1 Pro 还有一段差距。

Agent 能力：开源最佳

这是 V4 最重要的能力跃升之一。官方披露：

• Agentic Coding：V4-Pro 达到当前开源模型最佳水平
• 内部实测：已成为 DeepSeek 公司内部员工使用的 Agentic Coding 首选模型
• 体验对比：优于 Claude Sonnet 4.5，交付质量接近 Claude Opus 4.6 非思考模式

V4 针对 Claude Code、OpenClaw、OpenCode、CodeBuddy 等主流 Agent 产品进行了专项适配优化，在代码任务、文档生成等场景表现显著提升。

推理与代码

这是开源模型首次在代码竞赛上追平闭源模型。V4-Pro-Max 在 Codeforces 排名第 23 位（人类选手中）。

长上下文

V4-Pro 在真实场景的 CorpusQA 上超越 Gemini 3.1 Pro，在 MRCR 上接近 Claude Opus 4.6。

八、V4-Flash：经济高效的选择

V4-Flash 是一个重要的补充版本，让不同需求的用户都能找到合适的方案。

与 V4-Pro 的对比

适用场景：

• V4-Flash：日常对话、简单代码任务、成本敏感场景
• V4-Pro：复杂 Agent 任务、深度推理、高质量输出需求

九、三种推理模式：灵活的推理成本

V4 支持三种推理模式，让用户按需求选择成本：

Think Max 模式会在系统 prompt 里注入特殊指令：

1
2

Reasoning Effort: Absolute maximum with no shortcuts permitted.
You MUST be very thorough in your thinking...

这让模型”把推理推到极限”，在 HLE、IMO 等高难度任务上表现最优。

十、API 使用指南

模型调用

DeepSeek API 已同步上线 V4-Pro 与 V4-Flash，支持 OpenAI ChatCompletions 接口与 Anthropic 接口：

1
2
3
4
5
6
7
8
9
10
11
12

# OpenAI 格式
from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",  # 或 deepseek-v4-flash
    messages=[{"role": "user", "content": "你好"}]
)

关键参数

思考模式

对于复杂的 Agent 场景，建议使用思考模式并设置强度为 max：

1
2
3
4
5

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "复杂任务..."}],
    reasoning_effort="max"  # 极限推理
)

⚠️ 重要提示

旧 API 模型名 deepseek-chat 和 deepseek-reasoner 将于 2026年7月24日 停止使用：

• 当前阶段 deepseek-chat → 指向 V4-Flash 非思考模式
• 当前阶段 deepseek-reasoner → 指向 V4-Flash 思考模式

请尽快迁移到新的模型名称。

十一、开源与本地部署

权重下载

本地部署建议

由于 V4-Pro 参数量达 1.6T，本地部署需要：

• 多卡推理：至少 8× A100 80GB 或同等显存
• 量化推理：FP4 量化后可显著降低显存需求
• V4-Flash：单卡 A100 80GB 可运行

技术报告

完整技术细节请参考官方技术报告：

• DeepSeek V4 技术报告（PDF）

十二、行业启示：V4 带来的新范式

12.1 长上下文不再是奢侈品

以前，百万级上下文是”理论上可行但经济上不行”。V4 把成本降到 原来的 10-30%，让以下场景变得可行：

• Test-time Scaling：推理阶段可以长时间思考，不受上下文限制
• 长 horizon Agent：复杂多轮任务（如软件工程流水线）有足够”记忆空间”
• 在线学习：持续吸收新信息，无需全量重训练

12.2 开源 vs 闭源的格局变化

V4 是一个信号：开源模型不仅追上了能力，还追上了效率性价比。

• V4-Flash 用 13B 激活参数，就能达到接近 GPT-5.2 的推理水平
• 在代码任务上，开源首次追平闭源

这意味着闭源模型的”护城河”正在缩小。

12.3 架构创新的长期价值

V4 的创新不是”刷榜技巧”，而是架构层面的根本改进：

• CSA/HCA 解决了 Transformer 的 O(n²) 瓶颈
• mHC 让残差连接更稳定、可堆叠更深
• Muon 优化器可能成为万亿参数训练的新标配

这些创新会启发更多研究，推动整个行业向前。

十三、局限与展望

官方坦承了几个局限：

1. 架构相对复杂：为了降低风险，保留了 V3 的很多验证过的组件，未来会精简
2. 训练稳定性原理未完全理解：Anticipatory Routing 和 SwiGLU Clamping 有效，但数学原理还在探索
3. 多模态尚未集成：未来版本会加入视觉能力

展望方向：

• 进一步的稀疏化探索（如稀疏 embedding）
• 低延迟架构优化（让长上下文交互更流畅）
• 长 horizon Agent 的深度优化

总结

DeepSeek V4 的意义不在于某个具体指标的提升，而在于它解决了长上下文效率这个根本问题。

通过 CSA/HCA 混合注意力、mHC 残差升级、Muon 优化器、FP4 量化训练等一系列创新，V4 让百万级上下文从”理论上可行”变成”经济上可行”。

这为 AI 的下一阶段——更深的 test-time scaling、更长的 Agent 任务、更灵活的在线学习——铺好了基础设施。

开源模型第一次在效率和能力的综合维度上，追上了闭源前沿。这是整个行业值得关注的里程碑。

参考资源：

• DeepSeek V4 技术报告（PDF）
• 模型权重（HuggingFace）

阿里云百炼 Coding Plan 官方宣称”仅限编程工具使用”，但实际上其 endpoint 基于 OpenAI 兼容协议，Java/Python 应用完全可以调用。本文分享如何用 LangChain4j 和 OpenAI SDK 突破这一限制，直接消耗 Coding Plan 额度。

一、背景：一个被”误解”的服务

阿里云百炼的 Coding Plan 是一项面向 AI 编程助手的服务套餐，提供专门的模型调用额度。官方客服的说法是：

“Coding Plan 的专属 API Key（格式为 sk-sp-xxxxx）仅限在支持的编程工具（如 Claude Code、OpenClaw 等）中使用，不能用于 Java 应用直接调用大模型。若您的 Java 应用需要调用百炼大模型，请使用百炼通用 API Key（格式为 sk-xxxxx），该 Key 支持调用包括 Coding 模型在内的所有百炼模型，并按量计费。”

这意味着如果你想在 Java 应用中使用百炼大模型，需要：

1. 额外开通百炼通用 API Key（格式为 sk-xxxxx）
2. 按量付费，产生额外费用

但实际上，Coding Plan 的额度完全可以在 Java/Python 应用中使用！ 本文将分享这个”奇技淫巧”。

二、问题发现：为什么 Coding Plan Key 在 Java 中”失效”？

2.1 错误的调用方式

很多开发者（包括我）最初使用阿里云官方的 dashscope-sdk-java 调用百炼：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// pom.xml
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>dashscope-sdk-java</artifactId>
    <version>2.22.15</version>
</dependency>

// Java 代码
Generation gen = new Generation();
GenerationParam param = GenerationParam.builder()
    .apiKey("sk-sp-xxxxx")  // Coding Plan API Key
    .model("qwen-plus")
    .messages(messages)
    .build();
GenerationResult result = gen.call(param);

结果：API 返回 InvalidApiKey 错误，或者即使调通了，消耗的是通用额度而非 Coding Plan 额度！

2.2 根本原因分析

Coding Plan 的 API Key 使用的是 OpenAI 兼容协议，endpoint 地址不同于通用百炼服务：

官方的 dashscope-sdk-java 只支持通用百炼 endpoint，无法连接 Coding Plan 的 endpoint！

三、解决方案：使用 OpenAI 兼容模式

3.1 技术原理

Coding Plan 的 endpoint 基于 OpenAI API 兼容协议，任何支持 OpenAI API 的客户端都可以调用：

1. Python: 使用 openai SDK
2. Java: 使用 LangChain4j 的 langchain4j-open-ai 模块

只要将 base_url 指向 Coding Plan 的 endpoint，API Key 就能正常工作！

四、Java 实现：LangChain4j + Coding Plan

4.1 添加依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<!-- pom.xml -->
<properties>
    <langchain4j.version>0.35.0</langchain4j.version>
</properties>

<dependencies>
    <!-- LangChain4j OpenAI 兼容模块 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
</dependencies>

4.2 配置文件

1
2
3
4
5
6

# application.properties - Coding Plan 配置
langchain4j.open-ai.chat-model.base-url=https://coding.dashscope.aliyuncs.com/v1
langchain4j.open-ai.chat-model.api-key=sk-sp-xxxxx
langchain4j.open-ai.chat-model.model-name=kimi-k2.5
langchain4j.open-ai.chat-model.temperature=0.3
langchain4j.open-ai.chat-model.max-tokens=4096

关键点：base-url 必须是 coding.dashscope.aliyuncs.com/v1，不是通用的 dashscope.aliyuncs.com！

4.3 Java 代码实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.data.message.ChatMessage;
import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.output.Response;

import java.time.Duration;
import java.util.Arrays;
import java.util.List;

public class CodingPlanExample {

    private final ChatLanguageModel chatModel;

    public CodingPlanExample(String baseUrl, String apiKey, String modelName) {
        // 使用 OpenAI 兼容模式构建 ChatModel
        this.chatModel = OpenAiChatModel.builder()
                .baseUrl(baseUrl)  // Coding Plan endpoint
                .apiKey(apiKey)    // Coding Plan API Key
                .modelName(modelName)
                .temperature(0.3)
                .maxTokens(4096)
                .timeout(Duration.ofSeconds(60))
                .build();
    }

    public String chat(String systemPrompt, String userMessage) {
        List<ChatMessage> messages = Arrays.asList(
                SystemMessage.from(systemPrompt),
                UserMessage.from(userMessage)
        );

        Response<AiMessage> response = chatModel.generate(messages);

        if (response == null || response.content() == null) {
            throw new RuntimeException("模型返回结果为空");
        }

        return response.content().text();
    }

    public static void main(String[] args) {
        CodingPlanExample example = new CodingPlanExample(
                "https://coding.dashscope.aliyuncs.com/v1",
                "sk-sp-xxxxx",
                "kimi-k2.5"
        );

        String result = example.chat(
                "你是一位专业的翻译助手",
                "将以下内容翻译为英文：你好世界"
        );

        System.out.println(result);
    }
}

4.4 Spring Boot 集成示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

@Configuration
public class LangChain4jConfig {

    @Value("${langchain4j.open-ai.chat-model.base-url}")
    private String baseUrl;

    @Value("${langchain4j.open-ai.chat-model.api-key}")
    private String apiKey;

    @Value("${langchain4j.open-ai.chat-model.model-name}")
    private String modelName;

    @Bean
    public ChatLanguageModel chatLanguageModel() {
        return OpenAiChatModel.builder()
                .baseUrl(baseUrl)
                .apiKey(apiKey)
                .modelName(modelName)
                .timeout(Duration.ofSeconds(60))
                .build();
    }
}

@Service
public class TranslationService {

    private final ChatLanguageModel chatModel;

    public TranslationService(ChatLanguageModel chatModel) {
        this.chatModel = chatModel;
    }

    public String translate(String content, String sourceLang, String targetLang) {
        String systemPrompt = String.format(
                "你是翻译专家，将内容从%s翻译为%s，直接输出结果",
                sourceLang, targetLang
        );

        List<ChatMessage> messages = Arrays.asList(
                SystemMessage.from(systemPrompt),
                UserMessage.from(content)
        );

        return chatModel.generate(messages).content().text();
    }
}

五、Python 实现：OpenAI SDK + Coding Plan

5.1 安装依赖

1

pip install openai

5.2 Python 代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

from openai import OpenAI

# 使用 Coding Plan endpoint
client = OpenAI(
    base_url="https://coding.dashscope.aliyuncs.com/v1",
    api_key="sk-sp-xxxxx"
)

response = client.chat.completions.create(
    model="kimi-k2.5",
    messages=[
        {"role": "system", "content": "你是一位专业的翻译助手"},
        {"role": "user", "content": "将以下内容翻译为英文：你好世界"}
    ],
    temperature=0.3,
    max_tokens=4096
)

print(response.choices[0].message.content)

5.3 异步调用示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

from openai import AsyncOpenAI
import asyncio

async_client = AsyncOpenAI(
    base_url="https://coding.dashscope.aliyuncs.com/v1",
    api_key="sk-sp-xxxxx"
)

async def translate_async(content: str) -> str:
    response = await async_client.chat.completions.create(
        model="kimi-k2.5",
        messages=[
            {"role": "system", "content": "你是翻译专家"},
            {"role": "user", "content": content}
        ]
    )
    return response.choices[0].message.content

# 批量翻译
async def batch_translate(contents: list[str]) -> list[str]:
    tasks = [translate_async(c) for c in contents]
    return await asyncio.gather(*tasks)

# 运行示例
async def main():
    results = await batch_translate(["你好世界", "人工智能"])
    print(results)

asyncio.run(main())

六、实际应用场景

6.1 职位内容翻译

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@Service
public class JobTranslationService {

    private final ChatLanguageModel chatModel;

    public String translateJobDescription(String content, String sourceLang, String targetLang) {
        String systemPrompt = buildTranslationPrompt(sourceLang, targetLang);

        List<ChatMessage> messages = Arrays.asList(
                SystemMessage.from(systemPrompt),
                UserMessage.from(content)
        );

        return chatModel.generate(messages).content().text();
    }

    private String buildTranslationPrompt(String sourceLang, String targetLang) {
        return String.format("""
            你是一位专业的职位内容翻译专家。
            请将用户输入的职位描述从%s翻译为%s。

            翻译要求：
            1. 保持原文的段落结构和格式
            2. 专业术语使用行业标准翻译
            3. 直接输出翻译结果
            """, sourceLang, targetLang);
    }
}

6.2 文档内容生成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

public String generateDocumentOutline(String topic) {
    String prompt = """
        根据以下主题，生成一份技术文档大纲：
        主题：%s

        要求：
        1. 结构清晰，层次分明
        2. 每个章节要有简要说明
        3. 使用 Markdown 格式输出
        """.formatted(topic);

    List<ChatMessage> messages = Arrays.asList(
        SystemMessage.from("你是技术文档撰写专家"),
        UserMessage.from(prompt)
    );

    return chatModel.generate(messages).content().text();
}

6.3 智能客服对话

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@Service
public class CustomerServiceBot {

    private final ChatLanguageModel chatModel;

    public String handleUserMessage(String userMessage, List<String> history) {
        List<ChatMessage> messages = new ArrayList<>();

        // 系统提示词
        messages.add(SystemMessage.from("""
            你是专业的客服助手，帮助用户解答产品相关问题。
            回答要求：
            1. 语气友好专业
            2. 回答简洁明了
            3. 如果无法回答，引导用户联系人工客服
            """));

        // 添加历史对话
        for (String h : history) {
            messages.add(UserMessage.from(h));
        }

        // 当前消息
        messages.add(UserMessage.from(userMessage));

        return chatModel.generate(messages).content().text();
    }
}

七、关键注意事项

7.1 Endpoint 不要混用

混用会导致 InvalidApiKey 错误或消耗错误的额度！

7.2 模型名称差异

Coding Plan 支持的模型可能与通用百炼不同：

• Coding Plan: kimi-k2.5 等
• 通用百炼: qwen-plus, qwen-max, qwen-turbo

请根据实际账号支持的模型选择。

7.3 Token 消耗监控

虽然使用了 Coding Plan 额度，但仍需关注：

• 单次调用 Token 数量
• Coding Plan 额度剩余
• 设置合理的 max_tokens 防止超限

7.4 超时设置

Coding Plan 响应时间可能与通用服务不同，建议设置较长超时：

1

.timeout(Duration.ofSeconds(60))  // 或更长

八、总结

8.1 官方说法 vs 实际实践

8.2 核心原理

Coding Plan 的 endpoint 基于 OpenAI API 兼容协议，这是业界通用的 LLM API 标准。任何支持 OpenAI 协议的客户端都可以调用，不受编程工具限制。

8.3 适用场景

• ✅ Java 后端服务调用 LLM
• ✅ Python 应用调用 LLM
• ✅ Spring Boot / LangChain4j 集成
• ✅ 翻译、生成、对话等各类 NLP 任务
• ❌ 直接使用 dashscope-sdk-java（不支持 Coding Plan endpoint）

九、参考资料

• LangChain4j 官方文档
• OpenAI API 兼容协议
• 阿里百炼 Coding Plan

如果你最近关注 AI Agent 领域，可能会注意到一个新名字——Hermes Agent。它来自 Nous Research，在短短两个月内从一个小型内部项目成长为功能完备的 AI Agent 平台。这篇文章聊聊它到底有什么不一样，以及为什么值得你花时间了解。

一、Hermes Agent 是什么？

简单说，它是一个可以自我进化的 AI Agent 框架。

市面上大多数 Agent 工具，你用完一次，下次还要重新教它。你说”帮我整理今天的 Git 提交记录”，它执行了。第二天你再说同样的话，它又从头开始理解。对话结束后，一切归零。

Hermes Agent 不一样。它有个叫”技能系统”的东西。第一次你教它做某件事，完成后它会问自己：这件事我以后是不是经常要做？如果答案是肯定的，它会把整个过程打包成一个技能。下次你只需要说”整理提交”，它就能直接调用这个技能。

这不是预设好的模板，是 Agent 自己判断、自己创建、自己优化的。用久了，它会越来越懂你的工作习惯。

二、为什么突然火了？

翻一下 Hermes Agent 的版本历史，你会发现一个有意思的时间线：

从2月底到4月中旬，不到两个月，发布了10个大版本。平均每三四天一个版本。这不是营销驱动的节奏，是真实需求驱动的迭代速度。

看看 v0.2.0 的发布说明：”In just over two weeks, Hermes Agent went from a small internal project to a full-featured AI agent platform — thanks to an explosion of community contributions.”

这句话翻译过来：两个星期，从内部小项目变成完整平台，原因是社区贡献爆发。

为什么爆发？因为 Hermes Agent 解决了一个长期痛点——Agent 的记忆和学习能力。之前大家做 Agent，要么接受”每次对话归零”的现实，要么自己写一套复杂的持久化逻辑。Hermes Agent 把这套逻辑内置了，而且是真正意义上的”学习”，不只是”存储”。

三、核心特质

3.1 闭环学习，不是单次执行

这点前面说了，展开讲一下细节。

Hermes Agent 的学习机制包含几个层次：

技能自动创建：完成复杂任务后，Agent 会分析这个任务是否有重复价值。有，就创建技能。技能里包含了执行步骤、需要的工具、注意事项。

技能自我改进：你用某个技能的时候如果给了反馈，比如”这次格式不对”或”下次加上这个字段”，Agent 会把这些反馈写进技能描述里。下一次执行会自动应用。

定期提醒：Agent 有个机制叫”periodic nudges”，会周期性地提醒自己把重要信息持久化。不是被动等待你要求，是主动思考”这个信息值得记住吗”。

跨会话搜索：你问”上次我们讨论的那个方案是什么”，它会搜索历史对话，用 LLM 做摘要，然后告诉你。这不是简单的关键词搜索，是语义层面的召回。

3.2 Honcho 用户建模

Hermes Agent 内置了一个叫 Honcho 的用户建模系统。这个名字来自 plastic-labs 的 Honcho 项目，是一个专门做”AI 理解用户”的框架。

它的作用是：Agent 会持续观察你的偏好、习惯、工作方式，然后建立一个用户模型。你喜欢简洁回复，它记住；你讨厌某种操作方式，它记住；你对某个项目有特殊约定，它跨会话保持。

这不是简单的”记住你说过的话”，是”理解你是什么样的人”。

3.3 多平台统一接入

这点对实际使用很重要。

你可以在 Telegram、Discord、Slack、WhatsApp、Signal 这些平台跟 Hermes Agent 对话，也可以在终端用 CLI。同一个 Agent，不同入口，记忆和技能是共享的。

这意味着你早上在公司电脑用 CLI 让它整理日报，晚上回家用 Telegram 继续讨论，它记得你白天说了什么。

3.4 定时任务，原生支持

大多数 Agent 框架没有内置的定时任务系统。你想让 Agent 每天早上自动发日报，要么写外部脚本触发，要么依赖某个外部调度器。

Hermes Agent 内置了 cron 调度。你用自然语言描述：”每天早上9点，汇总昨天的 Git 提交并发到 Telegram”，它会自动解析、创建任务、按时执行。

这对于”Agent 作为助手”的场景很重要。真正的助手不只是你叫它才动，是会主动做事情。

3.5 云端部署，不是本地绑定

这点是 Hermes Agent 相比很多同类产品的优势。

它支持六种终端后端：本地、Docker、SSH、Daytona、Singularity、Modal。其中 Modal 和 Daytona 是”无服务器”模式——你的 Agent 环境在云端，空闲时几乎不花钱，有请求时自动唤醒。

这意味着你可以把 Hermes Agent 部署到云端，然后从 Telegram 发消息触发。不在电脑前的时候，Agent 依然在工作。这对于”随时随地操作”的需求很关键。

3.6 多模型，随时切换

Hermes Agent 支持大量 LLM 提供商：

• Nous Portal（官方订阅服务）
• OpenRouter（200+模型）
• Anthropic（Claude 系列）
• OpenAI（GPT 系列）
• Google AI Studio（Gemini）
• 阿里云百炼（DashScope）
• 智谱 AI（GLM）
• Moonshot（Kimi）
• MiniMax
• 小米 MiMo
• NVIDIA NIM
• DeepSeek
• xAI（Grok）
• Hugging Face
• AWS Bedrock
• 还有更多…

切换模型用一个命令：hermes model。不需要改代码，不需要重新部署，运行时切换。

这对于实际使用很重要。不同的任务适合不同的模型，你可能写代码用 Claude，快速问答用 GPT-mini，中文内容用 Qwen。Hermes Agent 让这种切换变得零成本。

四、对 OpenClaw 用户的意义

如果你正在用 OpenClaw，听到 Hermes Agent 可能会想：又一个类似的工具，有必要换吗？

这里有个事实你可能不知道：Hermes Agent 是 OpenClaw 的官方进化版本。

翻 Hermes Agent 的文档，你会发现专门的迁移章节：

1
2
3

## Migrating from OpenClaw

If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.

迁移命令很简单：

1
2

hermes claw migrate --dry-run    # 先预览会迁移什么
hermes claw migrate              # 执行迁移

迁移内容包括：

• SOUL.md（人格设定）
• 已有技能
• 命令白名单
• 消息平台配置
• API 密钥（Telegram、OpenRouter、OpenAI、Anthropic 等）
• 工作空间说明（AGENTS.md）

这说明 Hermes Agent 的开发团队明确知道 OpenClaw 用户群体，并且专门做了兼容路径。

那为什么要从 OpenClaw 换到 Hermes Agent？几个实际理由：

如果你需要定时任务、云端部署、Agent 学习能力，Hermes Agent 提供了这些 OpenClaw 没有的东西。

五、安装和使用指南

5.1 Mac 用户

Mac 上安装最简单，一行命令：

1

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后：

1
2

source ~/.zshrc   # 或者 source ~/.bashrc
hermes            # 启动

首次运行会引导你配置。按照提示选择 LLM 提供商、设置 API Key 就可以开始使用。

5.2 Windows 用户

Windows 原生不支持，需要通过 WSL2。

先安装 WSL2：

1

wsl --install

然后进入 WSL2 的 Linux 环境，运行和 Mac 一样的安装命令。

这步对不熟悉 Linux 的用户可能有点门槛，但设置好后使用体验和 Mac 一样。

5.3 常用命令

1
2
3
4
5
6
7

hermes              # 启动交互式 CLI
hermes model        # 选择模型提供商和具体模型
hermes tools        # 配置启用的工具
hermes gateway      # 启动消息平台网关（Telegram、Discord 等）
hermes setup        # 完整设置向导
hermes doctor       # 检查配置是否有问题
hermes update       # 更新到最新版本

在对话中使用的斜杠命令：

1
2
3
4
5
6
7

/new              # 开始新对话
/model            # 切换模型
/skills           # 浏览可用技能
/retry            # 重试上一轮
/undo             #撤销上一轮
/compress         # 压缩上下文
/usage            # 查看用量

5.4 配置阿里云百炼

如果你之前用 OpenClaw 配了阿里云百炼的 Coding Plan，在 Hermes Agent 里可以直接用：

1
2
3
4
5

# 设置环境变量
export DASHSCOPE_API_KEY=你的API密钥

# 如果用国内版，额外设置
export DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

或者在 ~/.hermes/.env 文件里写：

1

DASHSCOPE_API_KEY=sk-xxxxxxxx

然后用命令切换提供商：

1
2

hermes model alibaba
hermes model qwen3-coder-plus

六、OpenClaw 用户迁移指南

如果你已经有 OpenClaw 的配置，迁移步骤：

1. 安装 Hermes Agent

1
2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc

2. 运行迁移命令

1

hermes setup

Setup 向导会自动检测 ~/.openclaw 目录，提示你是否迁移。

或者任何时候手动运行：

1
2

hermes claw migrate --dry-run    # 预览会迁移什么
hermes claw migrate              # 执行迁移

3. 检查迁移结果

1

hermes doctor    # 检查配置是否正确

4. 开始使用

1

hermes    # 启动 CLI

迁移后，你的 SOUL.md（人格设定）、已有技能、命令白名单、消息平台配置都会保留。API 密钥会自动迁移到 ~/.hermes/.env。

注意：OpenClaw 支持 Telegram、飞书等平台，这些配置会直接迁移。

七、适合什么人用？

如果你的需求是：

• 写代码为主 → 继续用 Claude Code，它在代码理解上更强
• 操作电脑、整理文件 → Hermes Agent 或 OpenClaw 都能胜任
• 重复性任务多 → Hermes Agent，技能系统会帮你省时间
• 需要定时自动化 → Hermes Agent，内置 cron
• 离开电脑时也想用 → Hermes Agent，云端部署 + Telegram
• 飞书/Telegram 是核心场景 → Hermes Agent 或 OpenClaw 都能胜任

如果你已经在用 OpenClaw，不需要立即换。两个工具核心功能重叠约 70%，Hermes Agent 新增的是学习能力、定时任务和云端部署。这些对你有没有价值，看你的实际需求。

但如果你想尝试 Hermes Agent，迁移成本很低。一条命令就能把 OpenClaw 的配置全部导过去，不存在”从头设置”的问题。

八、总结

Hermes Agent 的价值不在”功能更多”，在”设计思路不同”。

大多数 Agent 工具的设计假设是：用户发起对话 → Agent 执行 → 结束。下一次对话从零开始。

Hermes Agent 的设计假设是：Agent 和用户是长期关系，Agent 应该越来越懂用户，而不是每次都从陌生人开始。

这个假设的差异，导致了功能设计的差异：技能自动创建、技能自我改进、Honcho 用户建模、跨会话搜索、定期提醒持久化。

这些功能单独看都不复杂，组合起来形成一个闭环：Agent 做事 → Agent 学习 → Agent 下次做得更好。

这个闭环是 Hermes Agent 和其他 Agent 工具的本质区别。

如果你对”Agent 可以学习和进化”这个概念感兴趣，值得花半小时安装试试。不需要完全替换你现有的工具，先体验一下它的学习机制，看看是否符合你的预期。

九、相关资源

• Hermes Agent GitHub：https://github.com/NousResearch/hermes-agent
• 官方文档：https://hermes-agent.nousresearch.com/docs/
• Skills Hub：https://agentskills.io
• Nous Research Discord：https://discord.gg/NousResearch
• HermesClaw（微信桥接）：https://github.com/AaronWong1999/hermesclaw

LangChain 和 LangGraph 是当下最流行的 Agent 开发框架，但 Anthropic 的 Claude Code 却完全不用它们。这不是傲慢，而是基于技术本质、产品体验、API 特性和工程可控性的四重考量。本文从多个层面剖析 Claude Code 的自研架构选择，以及它用什么技术替代了 LangChain/LangGraph 的能力。

一、先说结论

Claude Code 不用 LangChain/LangGraph，原因有四个：

一句话概括：LangChain/LangGraph 是”通用框架”，Claude Code 是”专用系统”。通用框架追求易用，专用系统追求极致体验。

二、架构层面：为什么放弃 ReAct

2.1 ReAct 模式的根本缺陷

LangChain 和 LangGraph 的核心都是 ReAct 模式（Reasoning + Acting）：

1

思考(Thought) → 行动(Action) → 观察(Observation) → 思考 → ...

这个模式直观易懂，但存在三个根本缺陷：

缺陷一：串行瓶颈

1
2
3
4
5
6
7
8
9
10
11

┌─────────────────────────────────────────────────────────────┐
│                    ReAct 串行流程                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  用户输入 → 等待完整响应 → 解析工具调用 → 执行工具 → 等待 →  │
│            └───────────────────────────────────┘            │
│                        用户感知到的延迟                       │
│                                                             │
│  问题：用户要等模型生成完整响应后才能看到工具执行             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

在 CLI 交互场景中，这种延迟是致命的——用户盯着屏幕等待，不知道发生了什么。

缺陷二：无法利用流式传输

现代 LLM API 都支持流式输出（SSE），但 ReAct 模式下流式的价值被大大削弱：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# LangChain 的 Agent 执行
agent.run("帮我分析这个项目")

# 内部流程：
# 1. LLM 生成完整响应（即使流式，也要等 action 完整）
# 2. OutputParser 解析响应文本
# 3. 提取工具名称和参数
# 4. 执行工具
# 5. 工具结果返回给 LLM
# 6. 重复...

# 流式输出的价值：实时看到模型"在想什么"
# 但工具执行：必须等完整响应后才能开始
# 两者冲突，流式体验被割裂

缺陷三：状态恢复困难

ReAct 模式没有统一的状态表示，每一步都是独立的：

1
2
3
4
5
6
7
8

Step 1: Thought → Action → Observation  (无状态记忆)
Step 2: Thought → Action → Observation  (重新开始)
Step 3: ...

当 API 超时、Token 溢出时：
- LangChain：抛出异常，用户需手动处理
- LangGraph：需要显式定义 checkpoint，复杂度高
- Claude Code：State 对象统一承载，自动恢复

2.2 Claude Code 的替代方案：Async Generator 状态机

Claude Code 用一个 while(true) 循环 + State 赋值 替代 ReAct：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/query.ts 核心（简化版）
export async function* query(params: QueryParams): AsyncGenerator<QueryUpdate> {
  let state: State = {
    messages: [...],
    toolUseContext: {...},
    turnCount: 0,
    transition: undefined,
  }

  while (true) {
    // 阶段1: 消息压缩（自动处理 Token 溢出）
    // 阶段2: 流式 API 调用（工具即时执行）
    // 阶段3: 决策点（继续还是结束）
    // 阶段4: 工具编排（并行只读，串行写入）
    // 阶段5: 状态更新
    
    state = next  // 通过赋值驱动循环
    continue
  }
}

核心优势对比：

2.3 流式即时执行：StreamingToolExecutor

Claude Code 的关键创新是 工具在模型生成过程中就开始执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

┌─────────────────────────────────────────────────────────────┐
│                 Claude Code 流式执行流程                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  模型流式输出：                                              │
│    "我来帮你分析这个项目..."                                 │
│    "首先读取 README..."                                     │
│    [生成 tool_use 块: Read { path: "README.md" }]           │
│                                                             │
│                    ↓ 立即执行                                │
│                                                             │
│  StreamingToolExecutor:                                     │
│    检测到 tool_use → 立即调用 Read 工具                     │
│    工具结果实时返回                                          │
│                                                             │
│  用户感知：                                                  │
│    实时看到模型思考                                          │
│    实时看到工具执行                                          │
│    无需等待完整响应                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

对比 LangChain：

1
2
3
4
5
6
7

LangChain 流程：
  用户输入 → 等待(模型完整响应) → 解析 → 执行工具 → 等待 → ...
  总延迟 = 模型生成时间 + 解析时间 + 工具执行时间

Claude Code 流程：
  用户输入 → 流式生成(工具即时执行) → 流式输出 → ...
  总延迟 = max(模型生成时间, 工具执行时间)

三、API 层面：原生特性的充分利用

3.1 LangChain 的”框架税”

LangChain 作为通用框架，需要在多种模型 API 之间保持一致性。这意味着：

1
2
3

Anthropic API 特性          → LangChain 抽象层 → 用户代码
                                    ↓
                          被抹平或延迟支持

Anthropic 独有的 API 特性：

3.2 Claude Code 的原生集成

Claude Code 直接使用 Anthropic SDK，充分利用所有原生特性：

示例：Prompt Caching 的利用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// Claude Code 的提示词组装（src/constants/prompts.ts）

// 静态可缓存区域（scope: 'global'）
const systemPrompt = {
  type: 'text',
  text: `
    ## 角色定义
    Claude Code 是一个...
    
    ## 系统规则
    你必须遵守...
    
    ## 工具说明
    以下工具可用...
  `,
  cache_control: { type: 'ephemeral' }  // 缓存标记
}

// 动态不可缓存区域（scope: 'ephemeral'）
const dynamicPrompt = {
  type: 'text',
  text: `
    ## 当前环境
    工作目录: ${cwd}
    
    ## 用户记忆
    ${claudeMdContent}
  `,
  cache_control: { type: 'ephemeral' }  // 独立缓存
}

缓存效果：

• 第一次调用：完整 token 计费
• 后续调用：静态部分缓存命中，降本约 90%

LangChain 也支持 Prompt Caching，但需要用户手动配置，且无法像 Claude Code 这样精细划分缓存边界。

示例：原生 tool_use 块

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// Anthropic API 响应格式
{
  content: [
    { type: 'text', text: '我来帮你...' },
    {
      type: 'tool_use',
      id: 'toolu_01...',
      name: 'Read',
      input: { file_path: '/path/to/file' }
    }
  ]
}

// Claude Code 直接处理
for (const block of response.content) {
  if (block.type === 'tool_use') {
    // 立即执行，无需解析文本
    await executeTool(block.name, block.input)
  }
}

对比 LangChain：

1
2
3
4
5
6
7
8
9
10
11

# LangChain 的工具调用
response = llm.invoke(prompt)

# OutputParser 解析文本
parsed = output_parser.parse(response.content)
# 解析可能失败，格式不固定

if parsed['action']:
    tool_name = parsed['action']['tool']
    tool_input = parsed['action']['input']
    result = tools[tool_name].run(tool_input)

LangChain 需要 OutputParser 解析模型输出的文本，这是脆弱的——模型格式不固定时解析会失败。

四、性能层面：零抽象的流式优先

4.1 LangChain 的抽象层堆叠

LangChain 的抽象层结构：

1
2
3
4
5
6
7
8

用户代码
  → Chain
    → AgentExecutor
      → LLM
        → Memory
          → Tools
            → OutputParser
              → 实际 API 调用

每一层都增加处理开销。对于 Web 应用，这些开销可以忽略；但对于 CLI 交互工具，延迟是致命的。

4.2 Claude Code 的零抽象设计

Claude Code 的结构：

1
2
3
4

用户输入
  → query() AsyncGenerator
    → Anthropic SDK（直接调用）
      → 工具执行（流式即时）

没有中间抽象层，API 响应直接流式传递给用户。

4.3 工具编排的性能优化

Claude Code 的工具编排策略：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

工具调用列表
  │
  ├─ 分类：只读 vs 写入
  │
  ├─ 只读工具 ──→ 并行执行（最多 10 个并发）
  │   ├─ Read      ──→ 同时开始
  │   ├─ Grep      ──→ 同时开始
  │   ├─ Glob      ──→ 同时开始
  │   └─ WebFetch  ──→ 同时开始
  │
  └─ 写入工具 ──→ 串行执行（保证顺序）
      ├─ FileEdit  ──→ 等待上一个完成
      ├─ Write     ──→ 等待上一个完成
      └─ Bash      ──→ 等待上一个完成

LangChain 的工具执行：

1
2
3

# LangChain Agent 默认串行执行
for tool_call in parsed_tool_calls:
    result = tool.run(tool_call.input)  # 一个一个执行

LangChain 需要显式配置并行，且配置复杂；Claude Code 自动分析工具性质，智能编排。

五、可控层面：全栈自研的精准控制

5.1 框架黑盒问题

使用 LangChain/LangGraph 时，你无法精准控制：

5.2 Claude Code 的精准控制

Claude Code 自研每一层，可以精确控制：

控制一：工具执行权限

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// Claude Code 的权限系统（src/utils/permissions）

type PermissionResult = {
  behavior: 'allow' | 'deny' | 'ask'
  message?: string
  suggestions?: string[]
}

// 精细的权限检查
async function checkPermissions(tool, input, context) {
  // 1. deny 规则最高优先级
  if (matchesDenyRule(tool.name)) {
    return { behavior: 'deny', message: 'Blocked by deny rule' }
  }
  
  // 2. 工具自定义检查
  if (tool.checkPermissions) {
    const result = await tool.checkPermissions(input, context)
    if (result.behavior !== 'passthrough') {
      return result
    }
  }
  
  // 3. allow 规则
  if (matchesAllowRule(tool.name, input)) {
    return { behavior: 'allow' }
  }
  
  // 4. 默认询问用户
  return { behavior: 'ask', message: 'Do you want to allow?' }
}

控制二：自动压缩策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Claude Code 的四级压缩（src/query）

// Level 1: Snip — 删除旧消息中的冗余 token
messages = snipMessages(messages)

// Level 2: Micro — 修改已缓存消息的内容
messages = microCompact(messages)

// Level 3: Collapse — 分阶段摘要历史消息
messages = collapseMessages(messages)

// Level 4: Auto Compact — 通过 Claude 生成完整摘要
messages = await autoCompact(messages)

// LangChain 的处理方式：
// messages = messages.slice(-max_tokens)  // 简单截断

控制三：钩子扩展系统

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "security-check.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "FileEdit",
        "hooks": [
          {
            "type": "command",
            "command": "run-tests.sh"
          }
        ]
      }
    ]
  }
}

用户可以在工具执行的任意阶段注入自定义逻辑，LangChain 需要继承类或修改源码才能实现类似功能。

六、能力映射：Claude Code 用什么替代 LangChain/LangGraph

6.1 LangChain 能力 → Claude Code 替代方案

6.2 LangGraph 能力 → Claude Code 替代方案

6.3 核心代码映射

LangChain Agent → Claude Code query()

1
2
3

# LangChain
agent = AgentExecutor.from_agent_and_tools(agent, tools)
result = agent.invoke({"input": "do something"})

1
2
3
4

// Claude Code
for await (const update of query({ messages, tools, systemPrompt })) {
  console.log(update)  // 实时输出
}

LangGraph StateGraph → Claude Code while 循环

1
2
3
4
5
6
7

# LangGraph
graph = StateGraph(AgentState)
graph.add_node("agent", agent_node)
graph.add_node("tool", tool_node)
graph.add_conditional_edges("agent", should_continue, 
    {"continue": "tool", "end": END})
app = graph.compile()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// Claude Code（src/query.ts）
while (true) {
  // 阶段 2: 流式 API 调用
  const response = await callModel(state)
  
  // 阶段 3: 决策点（条件分支）
  if (hasToolUse(response)) {
    // 阶段 4: 工具执行
    const results = await executeTools(response.tool_use_blocks)
    state = { ...state, messages: [...messages, results] }
    continue  // 继续循环
  } else {
    // 结束
    yield finalResult
    return
  }
}

七、什么时候该用 LangChain/LangGraph

Claude Code 的自研架构不是所有人的最优解。它们的选择基于：

1. 顶级工程团队：有能力自研高性能架构
2. 单一模型依赖：只需要支持 Anthropic API
3. 极致体验追求：CLI 交互需要零延迟感知
4. 深度定制需求：权限、压缩、钩子都需要精准控制

如果你不具备这些条件，LangChain/LangGraph 仍然是好选择：

八、总结

Claude Code 不用 LangChain/LangGraph，不是傲慢，而是基于产品定位的理性选择：

1
2
3
4
5
6
7
8
9
10
11

LangChain/LangGraph 定位：通用框架
  → 易用性优先
  → 支持多种模型
  → 抽象层统一
  → 适合快速原型和通用应用

Claude Code 定位：专用系统
  → 性能优先
  → 单一模型极致利用
  → 零抽象流式处理
  → 适合 CLI 交互和专业场景

Claude Code 用什么替代了 LangChain/LangGraph：

核心启示：框架不是必须的，适合自己的才是最好的。LangChain/LangGraph 解决了”怎么快速搭建 Agent”的问题；Claude Code 解决了”怎么搭建极致体验的 Agent”的问题。

参考资料

• Claude Code 源码揭秘：整体架构概览
• 打破 ReAct 迷思：Async Generator 状态机
• 工具系统设计：从定义到执行的七步管道
• Anthropic API 文档
• LangChain 官方文档
• LangGraph 官方文档

2026年3月31日，Anthropic 的 Claude Code 源码意外泄露。这个全球最流行的 AI 编程助手，其背后的架构设计远超外界想象——它不是简单的 Prompt 包装，而是一个精心设计的流式状态机系统。本文将从整体架构视角，为你揭开 Claude Code 的神秘面纱。

当大多数人谈论 AI Agent 架构时，ReAct（Reasoning + Acting）几乎是唯一的答案。但 Claude Code 选择了一条不同的路——Async Generator 状态机。这个设计决策背后有着深刻的思考，它解决了 ReAct 的根本性限制，为流式交互和优雅恢复奠定了基础。

让 Claude Code 跨会话记住你是谁、你偏好什么、项目正在发生什么——这是 Memory 系统的核心目标。它不是简单的聊天记录持久化，而是一个结构化的知识管理系统，通过四种记忆类型、自动提取机制、团队同步等功能，让 AI 真正”理解”你。

Computer Use 是 Claude Code 最具争议也最强大的能力——AI 可以直接操控你的桌面，点击按钮、输入文字、截图分析。这听起来像科幻电影，但 Claude Code 实现了一个九层安全关卡系统，确保每一步操作都在可控范围内。更关键的是，它通过 Python Bridge 实现跨语言通信，让 TypeScript 代理驱动 Python 执行器。

Claude Code 的多 Agent 系统可能是其最被低估的设计之一。它不是简单的”子代理调用”，而是一个完整的协作框架：四种 Agent 类型（Subagent、Fork、Teammate、Remote）、Teams 邮箱通信、权限同步、Worktree 隔离。这个设计让 Claude Code 能够处理单 Agent 无法完成的复杂任务。