项目动机

做这个项目的动机很简单，作为一名Java佬，想转型做 AI Agent。

但我不想学完 Python 再开始，我想用我最熟悉的语言直接上手。

一步一步去拆解AI Agent标准的开发范式

于是我边学边做，把这个过程做成了开源项目，如果你也是 Java 背景、也想搞清楚 AI Agent 到底是怎么构建的，这个项目就是为你做的

⭐ 如果对你有帮助，欢迎 Star。

https://github.com/xieqiyong/agentscope-coding-agent

github

项目方式

边学边做，把学习 AI Agent 的过程沉淀成一个开源项目。

适合谁看

• 你有 Java 背景；
• 你想理解 AI Agent 到底是怎么构建的；
• 你希望通过项目实践来学习，而不是只停留在概念层面。

本路线面向希望从零构建生产级 Coding Agent Runtime 的工程师。主线是：能跑通 → 能治理 → 能上生产。每个阶段都可独立实践，再逐步组合成完整系统。

阶段	主题	核心目标
1	Agent Loop 基础	理解 ReAct 循环、工具调用与事件流
2	RAG 与记忆基础	文档检索、短期记忆、摘要与长期记忆候选
3	工具调用可观测	通过结构化事件和 SSE 实时展示运行过程
4	文件级沙箱	限制 workspace 内读写，拦截路径逃逸、敏感文件和 symlink
5	SessionKey / AgentState	区分外部上下文恢复与内部 checkpoint 恢复
6	运行状态机	建模 Agent 生命周期和合法流转
7	记忆系统产品化	长期记忆审核、冲突处理与注入治理
8	权限治理	建立 allow / ask / deny 策略
9	命令级沙箱	安全执行 Bash，支持流式输出、超时和危险命令拦截
10	Checkpoint + Pending Action	用户确认后恢复挂起执行，断线后恢复现场
11	回滚与补偿	文件快照、多文件事务与失败恢复
12	多 Agent / 计划型 Agent	Plan、Observe、Execute、Review 等 Agent 编排
13	产品化治理	审计、限流、fallback、workspace 管理与前端体验

二、阶段 1-3：先跑通 Agent Loop

阶段 1：Agent Loop 基础

**Agent Loop = 模型推理 → 工具调用 → 工具结果 → 再次模型推理。**这是 Coding Agent 的心脏，后续能力都建立在它之上。

• 理解 ReAct：Reasoning 与 Acting 交替执行。
• 掌握工具注册：schema、description、parameters、tools 注入方式。
• 设计事件流：模型开始、token 增量、工具调用、工具结果、最终回答。
• 用 SSE 将运行过程实时推送给前端。

**实践目标：**实现最小 ReActAgent，注册 2～3 个测试工具，并通过 SSE 展示完整过程。

阶段 2：RAG 与记忆基础

短期记忆解决当前会话上下文，摘要压缩解决 token 限制，长期记忆解决跨会话稳定事实存储。

• 搭建文档处理流水线：上传、解析、切分、embedding、向量入库。
• 实现检索系统：向量检索、关键词检索、混合检索与 rerank。
• 评估检索效果：关注召回率与准确率。
• 实现短期记忆、滑动窗口、摘要记忆和长期记忆候选提炼。

阶段 3：工具调用可观测

模型不负责渲染 UI，模型只触发工具；Runtime 产生结构化事件，前端根据事件稳定渲染。

• 定义事件：TOOL_CALL_START、TOOL_CALL_DELTA、TOOL_RESULT_DELTA、TOOL_CALL_DONE、MODEL_DELTA、RUN_DONE、RUN_ERROR。
• 前端展示工具轨迹、文件变更摘要和可恢复 timeline。
• 为每个工具调用分配 trace ID，记录耗时、入参、返回值，形成调用链。

三、阶段 4-6：建立安全边界和可恢复运行

阶段 4：文件级沙箱

沙箱不是信任模型，而是限制爆炸半径。核心是最小权限原则的工程实现。

• 文件工具：LS、Read、Glob、Grep、Write、Edit、WebSearch。
• 路径安全：绑定 workspace root，规范化路径，拦截路径逃逸。
• symlink 防护：跟踪并阻断通过软链接跳出沙箱。
• 敏感文件保护：.env、私钥、系统配置等黑名单与审计告警。
• 变更管理：unified diff、单文件最小回滚、文件操作审计日志。

阶段 5：SessionKey / AgentState

恢复方式	适用场景	特点
外部上下文恢复	聊天续聊、记忆注入	简单、可审计、可控，但不能恢复 loop 内部现场
内部 checkpoint 恢复	中断后继续、用户确认后恢复	接近 runtime snapshot，但要避免恢复到非法状态

• 外部上下文包括 conversation_messages、conversation_summaries、memory_entries。
• AgentState 可保存 curIter、context、toolContext、permissionContext、pendingToolRecovery。
• 需要设计序列化字段、JSON / Protobuf 格式和 checkpoint 版本兼容。

阶段 6：运行状态机

状态机判断“现在能否继续、暂停、失败、超时、取消”；checkpoint 判断“如果能继续，要从哪里恢复”。两者缺一不可。

状态	含义
PENDING	已创建，等待调度
RUNNING	正在执行 Agent loop
WAITING_APPROVAL	等待用户确认高危操作
COMPLETED / FAILED / TIMEOUT / CANCELLED	终态，不可继续流转

• 合法流转必须由矩阵控制，不能任意改状态。
• 超时计时器、取消信号、工具调用中止都要可控。
• 状态变更要保证原子性，处理取消和超时等并发请求。

四、阶段 7-9：把治理能力补齐

阶段 7：记忆系统产品化

长期记忆一旦注入 system prompt，就会持续影响 Agent 行为。必须像管理代码一样管理记忆：审核、版本和冲突解决。

• 生命周期：候选提炼、审核、入库、更新、失效。
• 冲突检测：写入时或注入时发现矛盾记忆。
• 解决策略：最新优先、置信度优先、人工仲裁。
• 注入治理：格式、注入量、相关性过滤、项目级约束优先级。
• Coding Agent 专属记忆：代码风格、架构约束、用户工作习惯。

阶段 8：权限治理

每个工具操作都要明确：allow 直接执行，ask 暂停确认，deny 直接拒绝并说明原因。

• 权限维度：文件、命令、网络、工具级别。
• 策略配置：静态策略、动态策略、策略继承。
• 确认流程：APPROVAL_REQUIRED → WAITING_APPROVAL → 用户确认或拒绝。
• 防绕过：工具执行前强制校验，不依赖模型自律。

阶段 9：命令级沙箱

命令执行是 Coding Agent 中风险最高的能力。必须在沙箱内执行，不能直接暴露宿主机环境。

• Bash 工具：白名单、黑名单、工作目录限制、环境变量控制、低权限执行。
• 危险命令拦截：识别 rm -rf /、chmod 777、curl … | bash、系统路径重定向等。
• 流式输出：stdout / stderr 实时返回，限制输出大小，处理 ANSI 转义码。
• 超时控制：命令级、会话级超时，以及 SIGTERM → SIGKILL 清理。
• 后台任务：管理长运行进程生命周期并持续推送输出。
• 进阶隔离：Docker / gVisor、镜像缓存、容器网络限制。

五、阶段 10-11：补齐可靠性

阶段 10：Checkpoint + Pending Action

挂起点是工具执行前的安全暂停位置；恢复是从挂起点继续，而不是从头重跑。

• 触发时机：高危工具调用前、权限不足时。
• pendingAction 保存工具名、参数、调用 ID、触发原因。
• 用户确认后恢复执行；拒绝时将拒绝结果注入上下文，由 Agent 继续决策。
• 断线恢复要检查工具是否已执行，并用 operation ID 保证幂等。

阶段 11：回滚与补偿

一次 run 可能修改多个文件。任何一步失败都不应留下半成品：要么全部成功，要么回到执行前。

• 文件快照：写操作前备份原始内容，设计存储位置、命名和清理策略。
• 单文件回滚：工具失败时恢复到执行前状态。
• 多文件事务：用 Saga 记录补偿操作，失败时逆序补偿。
• Git 级隔离：独立分支、成功合并、失败丢弃、worktree 并发隔离。
• 补偿策略：自动回滚、半自动选择、手动回滚工具。

六、阶段 12-13：扩展为生产系统

阶段 12：多 Agent / 计划型 Agent

单 Agent 适合线性任务，多 Agent 适合可并行、需要专业分工的复杂任务。关键挑战是上下文隔离、结果合并和协调一致性。

Agent	职责
Plan Agent	拆解用户目标为子任务列表
Observe Agent	收集信息，理解代码库现状
Execute Agent	执行具体代码修改
Review Agent	验证变更，发现问题
Coordinator	调度各 Agent 并汇总结果

• 每个子 Agent 拥有独立上下文和独立权限。
• Plan Agent 输出结构化任务图，明确并行和串行依赖。
• 结果合并要处理冲突检测、Review 反馈和最终报告。
• 失败处理要支持局部重试和整体回滚范围控制。

阶段 13：产品化治理

• 审计：记录工具调用、状态变更、权限决策，并支持 run 回放。
• 限流与配额：限制并发 run、工具调用次数、Token 消耗，并处理超限降级。
• 模型 Fallback：主模型不可用时切换备用模型，并向用户提示。
• Workspace 管理：创建、挂载、销毁、多租户隔离、配额、快照与恢复。
• 错误诊断：结构化错误码、友好错误展示、运行报告。
• 前端体验：实时进度、工具时间线、追加指令、diff 展示和一键回滚。

七、推荐学习节奏

阶段	重点	建议周期
1-3	先跑通，理解核心机制	2-3 周
4-6	补牢基础，建立安全边界	2-3 周
7-9	治理提升，向生产靠近	3-4 周
10-11	可靠性保障，处理异常场景	2-3 周
12	能力扩展，解决复杂任务	2-3 周
13	产品化打磨，持续迭代	持续进行

**阶段总结：**不要等前一个阶段“完美”才进入下一阶段。每个阶段先完成基础实现，形成可运行闭环，再回头迭代安全、治理和体验。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】