空缺的博客

生命不息，折腾不止。上一课解决了「上下文涨满」，这一课解决「活干到一半 Agent 失忆」：给你的 Agent 立一个跨会话、跨重启都不丢的目标，它就能自己一鼓作气续跑最多 256 轮。 一、目标不是「待办清单」，是「方向盘」先纠正一个最常见的第一反应：很多人以为 dsh 里的 goal（目标） 就是让 Agent 记一张 todo 清单，跑到一半断了重来就行。不是。goal 是一个会话里的长期完成目标：目标文本、当前阶段（phase）、已经跑了多少轮、每一次改动的修订历史，全部写进 append-only 的会话日志里。所以会话恢复（resume）、会话分叉（fork）、甚至进程重启，目标都原封不动还在。 但这里有个最容易踩、也最关键的分工，务必先记住： dsh-goal 只存状态，不调度工作。 它是「方向盘」，不是「发动机」。 真正让 Agent 一轮接一轮自动往下跑的，是另一个包 goal-round-driver（续跑驱动）。理解了「状态」和「调度」是两拨人各管一摊，整个 goal 体系就通了。整个体系一共四个包： 包 角色 一句话 dsh-goal ...

生命不息，折腾不止。上一课我们盯住了会话的事件流，这一课顺着它钻进 dsh 的上下文压缩（compaction）——长会话涨到模型窗口门口时，怎么自动把旧历史压成一段摘要，对话继续往前走、审计轨迹一点不丢。 一、先想明白：上下文是有物理上限的，没有「无限对话」这种好事不管你是用 Chat 界面还是自己跑的 Agent，都有一个绕不过去的物理事实——模型的上下文窗口是硬的，token 装满了就装不下，再发请求要么报错、要么被截断。 很多框架对这事的态度是「装不下就报错，用户自己重开一局」。这对 Agent 很致命：一个跑了半小时、追着一个目标死磕的任务，眼看要收尾了，上下文撞墙，前功尽弃。理想做法是别删历史，而是把「模型现在能看到的东西」做一次瘦身。 dsh 给的答案是 compaction：把较早的一整段对话，替换成一句摘要；最近的历史原样保留；会话从摘要那条消息继续往下走。听起来简单，但 dsh 把它做得格外讲究，下面慢慢拆。 二、它又是一层「能力 seam」：接口、后端、命令三分老读者应该熟悉这个套路了——dsh 里但凡是个可替换的能力，都照 bash 的标准拆成三层，压...

生命不息，折腾不止。上一篇教你在 Agent 动手前拦它，这一篇钻到它「记性」的底层——把一整轮对话自动压成一份带 SHA-256 防伪哈希的日报，交差、交接、审计一条龙。 上一课我们写了个钩子插件，在 tools/pre-execute 上挡在 Agent 前面当门卫。那次用的是「运行时事件」——瞬时的、只活在进程里的信号。但 dsh 真正有意思的东西藏在更底层：它的会话根本不是一条聊天记录数组，而是一条只追加、永不改写的日志。今天钻进去，顺手把「会话」炼成「交付物」。 一、先破一个成见：dsh 的「记忆」不是聊天记录，是事件流很多人第一反应是把 Harness 的会话理解成 ChatGPT 那种 messages: [...] 数组——用户一句、模型一句，堆起来就完事。dsh 不是这么干的，它走的是**事件溯源（event sourcing）**这条路： 会话状态是一份由类型化 SessionEvent 组成的仅追加日志（append-only log），是 Agent 整个交互历史的唯一真相源。模型看到的消息历史，是从这份日志派生出来的，从来不单独存第二份。 翻译成...

生命不息，折腾不止。一个框架光能「加能力」不算本事，能让你「改行为」才是真本事——这一课写个钩子插件，在 Agent 每次动手前拦它一道，把「一切皆插件」的第二层威力摸透。 上一篇《DeepSeek Harness 写第一个插件：让 Agent 调用你的工具》教的是工具插件：往 ctx.tools 上注册一个 defineTool，让模型多一个能调的函数。那是给 Agent「发装备」。 今天写的是另一种插件——钩子插件。它不新增能力，而是蹲在事件链路上，在 Agent 动手前后插一脚：拦下危险调用、改写工具结果、把每一步记进审计日志。这才是 Harness 那句「一切皆插件」真正吓人的地方——模型、工具、甚至 Agent 的主循环本身，都是能被你替换或拦截的插件。 一、工具插件是「给能力」，钩子插件是「改行为」先厘清两者的区别，免得混： 工具插件 钩子插件 干什么 往 ctx.tools 注册新工具 给事件挂监听器 效果 模型多一个可调的 defineTool 在已有流程里「插一脚」 典型场景 读文件、查库、发消息 权限门、改写结果、审计埋点 注册方...

生命不息，折腾不止。前四课攒下的三件套（工具手、落盘、审批闸门），今天一把焊成一个真的能干活的工单 Agent。 LangGraph 实战这个系列写到今天，总算可以收尾了。前面四课我们分别攒了三样硬货：第 2 课学会用 interrupt() 给 Agent 装人工审批闸门，第 3 课用 SqliteSaver 让 Agent 能落盘「倒带重来」，第 4 课用 @tool + ToolNode 给 Agent 装了会干活的「手」。 但光有零件不算本事，把它们串起来才叫 Agent。今天我们就手搓一个客服工单 Agent：用户报个订单号，它自动查单、算优惠、起草发货单，然后——重点来了——卡在发货前等人点头，人回一句「发货」才真正往下走。全程断了电、关了机，隔天开回来还能接着上次的进度继续跑。这就是把三节课焊成一个完整闭环。 一、先盘一遍手里的三件套动手之前，把三个零件各归各位，写代码的时候心里才有数： 工具手（第 4 课）：@tool 装饰器把普通 Python 函数变成模型能调的工具，bind_tools 把工具「塞给」模型，ToolNode 负责真的去执行工具并回传结果...

生命不息，折腾不止。前面几课搭的 Agent 只会「想」不会「做」——这一课用 @tool 装饰器 + ToolNode 给它装上手和脚，让模型能算数、查天气、调 API，跑通一个真正的 ReAct「想—做—再想」循环。 一、会说话的 Agent，为什么还是半个残废上一课我们给 Agent 接上了记忆和「后悔药」，但它有个硬伤：只能靠脑子（模型）里的知识回答，长不出手。你问它「42×7 等于多少」「北京今天几度」，它要么硬算（还经常算错），要么直接坦承「我不知道」。很多活儿——查实时数据、调自己写的接口、读写数据库、跑一段代码——模型天生干不了。 解决办法不是换个更强的模型，而是给它工具（tool）：把「查天气」「算乘法」这些外部能力包装成一个带说明的函数，让模型在需要的时候，主动发起一次「工具调用（tool call）」，工具跑完把结果塞回对话，模型再基于结果接着往下说。 这套「推理（想）→ 行动（做）→ 再推理」的动作，就是 ReAct 循环（Reasoning + Acting）。LangGraph 里搭这个循环，就两个主角：@tool 装饰器负责「造工具」，ToolN...

生命不息，折腾不止。上一课给 Agent 装了「人工审批」闸门，但那个 checkpointer 是放在内存里的，服务一重启就全没了——这一课我们换成落盘的 SqliteSaver，再学会 get_state / update_state 两招「时间旅行」，跑错的步骤倒回去改完再重来。 一、内存 checkpointer 为什么撑不住上一课编译图的时候，我们挂的是 InMemorySaver。它本质上就是进程内存里的一个字典：{thread_id: [checkpoint, checkpoint, ...]}。拿来演示、调 bug 很爽，但有两个致命伤： 一重启就蒸发：Agent 正暂停在「人工审批」那里等人拍板，服务器来一次重启，状态全没了，thread_id 那个「抽屉」被清空，人也恢复不了。 只能单进程用：内存里的东西没法共享给别的进程、别的机器，做不了多副本、也查不了历史。 所以真要上线，就得把 checkpoint 从内存挪到磁盘/数据库。LangGraph 官方把 checkpointer 抽象成了一个统一接口，换实现就是换一个类的事。最轻...

生命不息，折腾不止。上一篇横向对比完三家框架，这篇我们真刀真枪上手 LangGraph——手把手给 Agent 装一道「人工审批」闸门，让它该停就停，顺便把「状态契约」这四个字彻底讲透。 一、先补上一课的坑：状态契约到底是个啥上一篇我说要带你们亲手搭一个「带人工审批的多步 Agent」。动手之前，得先把 LangGraph 最容易把人绕晕的核心概念讲清楚，因为它决定你后面写图顺不顺手——状态契约（State）。 一句话：State 就是这张图里所有节点共享的一张「表格」，每个节点进来能读、出去能写，字段的格式是写死的。 节点和节点之间不直接互相传参，而是通过这张共享的表来交换数据。所以它才叫「契约」——上游写什么、下游读什么，全靠这一张表约定好。 用代码表达，State 通常是一个 TypedDict： 123456from typing import TypedDictclass DocState(TypedDict): draft: str # 生成的草稿 decision: str # 人工审批结果：approve / reje...

生命不息，折腾不止。做 Agent 前花十分钟搞清三大框架各自的定位，能帮你省下后面无数个抓狂的夜晚。 一、先别急着装：这三个其实不是一个层面的东西很多人一张嘴就问「LangGraph、Claude Code、微软 MAF 到底哪个更强」，这问题本身问岔了。它们三个虽然都叫「Agent 框架」，但站在栈的不同位置上： LangGraph：一个编排运行时（orchestration runtime）。它不在乎你的模型是谁，只管把你的工作流画成「有向图」——节点是步骤、边是走向——然后帮你管状态、管持久化、管中断恢复。 Microsoft Agent Framework（MAF）：微软的统一全家桶，AutoGen 和 Semantic Kernel 的继任者。它把「自主 Agent」和「确定性 Workflow」分成两层，想要生产级的编排、可观测、安全护栏走它就对了，Azure 生态尤其顺。 Claude Code / Claude Agent SDK：这俩其实是同一台发动机——Anthropic 把 Claude Code 的 agent loop、内置工具、权限系...

生命不息，折腾不止。前四课把 Server 造出来、挂上网、补上反问能力（MRTR）和变更通知（subscriptions/listen）；这一课啃掉最后两块硬骨头——长任务怎么异步化（Tasks 扩展），以及 Server 要面对多用户时怎么授权（OAuth 加固：RFC 9207 的 iss 校验 + DCR 到 CIMD 的迁移），最后把你手上这根链路收口成一套能交付给别人的完整服务。 上一篇结尾我把话说死了：无状态化把「会话说完了」，但代价是原来那些「搭便车」的活儿——限流、凭据、可观测——全得自己重做。今天这两块，恰好是无状态世界里最绕不开的两件：一件管**「一个活要跑很久怎么办」，一件管「谁来用我的 Server 怎么认」**。 一、为什么长任务不能赖着连接不走先回到最朴素的问题：一个 MCP 工具调用，理想状态是「你问一句，我马上答一句」，几百毫秒搞定。但真实世界不是这样——「把 500 条数据清洗一遍」「抓三个网站生成一份报告」「让模型写一篇长文」，这些活动辄几十秒到几分钟。 老做法是让客户端「傻等」：发起 tools/call，挂起连接，等 Ser...