空缺的博客

生命不息，折腾不止。前面三课我们都在终端里敲 claude，今天换个玩法——把 Claude Code 变成你 Python / TypeScript 程序里的一个函数，随叫随到，想造啥自动化流水线都行。 前面我们讲过无头模式（claude -p），那已经能让 CI 里跑 Claude 了。但 -p 有个别扭的地方：它是「一个命令起一个进程、跑完就退」，消息是拼在 stdout 里当文本处理的，真要做到「程序里调用 Claude、拿到结构化的结果、还能传自定义工具」就得费劲 parse。Claude Agent SDK 就是官方把这件事做干净的答案——它把 Claude Code 那套 Agent 引擎（能读文件、跑命令、用工具、多轮思考）包装成了普通函数调用，一条 async for 就能流式拿到结构化的消息。 这一课我们就把它接起来，看完你就能写「程序化 Agent 流水线」。 一、先搞清 SDK 到底是个啥Claude Agent SDK 是 Anthropic 官方出的库，就干一件事：用代码驱动 Claude Code。它有两个语言版本、两个包名： 1234...

生命不息，折腾不止。前两课教 Claude Code 怎么「原地把活干漂亮」，这一课教它怎么「没人盯着也照干」——无头模式，让它在 CI 流水线、定时任务里 24 小时自己打工。 Claude Code 实战系列开到第三课了。先给新来的朋友补个课：开篇那篇《从安装到命令行自动化搭子》已经把 claude -p 的梗概带过一嘴，第一课用 MCP 给它装「手脚」，第二课用 Hooks 立「规矩」；至于装机和接中转站这些基本盘，早在 8 月那篇《Claude Code 国内配置教程》里就铺好了，今儿不重复。 这课把「无头模式」（Headless）彻底讲透——从开篇里的「能用」讲到「上生产可靠地用」：权限白名单、三种输出格式、CI 流水线、常见踩坑一次收全。它把 Claude Code 从「一个你坐在终端前聊天的工具」，变成「一个能被脚本、定时任务、CI 流水线按需调用的正经编程接口」。跨过这一步，你才算真的把 AI 接进了自己的自动化世界。 一、为什么交互模式不够用先说明白「无头」到底无的什么头。你平时敲 claude 进去的那个是交互式 TUI——有界面、会等你打字、动不动追着你...

生命不息，折腾不止。前面六篇攒下的钩子、事件流、压缩、目标、后台任务、子代理，今天全串成一支会自己分工干活的队伍。 进阶系列写了六篇，从写钩子插件拦截 Agent，到监听事件流出日报，再到上下文压缩、目标续跑、后台任务，最后是 subagent 招「手下」。眼尖的朋友可能发现了：subagent 那一套是父子关系——你派一个子代理出去，它干完汇报，仅此而已，子代理之间互不搭话，也没有一块共享的记工板。 今天收尾，我们把牌桌上最后一副牌翻开：Agent Teams。这是 DeepSeek Harness 官方仓库 packages/experimental/ 里一个实验性多智能体协作模块——一个会话变成一个「主编」，它能招几个有名字的「研究员」队友，互相发消息、共用一块任务板，还能崩溃重启后接着干。前面六件套，在这里各就各位。 一、前六篇攒下的六块积木先回头看我们攒了什么，不然组队就是空中楼阁： 积木 文章 在队伍里干什么 钩子插件 第 1 篇 主编/研究员动手前统一拦截、审批 事件流 第 2 篇 干活全程留痕，收工时自动出日报 上下文压缩 第 3...

生命不息，折腾不止。主对话上下文越堆越贵，今天教你用 subagent 把独立的脏活拆给一群「手下」，自己只收结果。 一、为什么要把活拆给「手下」前面几期我们把一个 Agent 折腾得挺明白：装钩子拦截、监听事件流、上下文压缩、立 goal 自动续跑、长任务丢后台。但有个问题一直没正面解决——上下文是稀缺资源，什么都往主对话里塞，既费 token 又容易把模型带偏。 打个比方：你让一个 Agent「把仓库里所有 Markdown 文档里的 API 地址中文改英文，并给每个文件写一段英文摘要」。它得先把几十个文件读进上下文，再逐个改、逐个翻译。这活儿干到一半，主对话已经撑满 100K，前面的关键指令早被挤出去了。 subagent 就是来干这个的——把一件「自包含」的小任务丢给一个只干这一件事的「手下」，它干完只回你一个最终结果，中间过程完全不占主对话。几个关键点先记住： 子代理在自己的独立上下文里干活，只把最终答案交回来，不吐中间步骤； 一个父 Agent 可以同时挂好几个子代理，各干各的； 子代理想干就干、干完就散，也可以「常驻」下来，后面继续给它发消息。 二、四个包，...

生命不息，折腾不止。让 Agent 把耗时命令丢进后台，既不傻等也不被超时打断，边干别的边回收结果——dsh 的后台任务三件套一次讲透。 上一课我们给 Agent 立了个「goal」，它能自己续跑 256 轮把目标干完。但干到一半有个尴尬：很多活是慢工出细活，比如 npm run build 一跑三分钟、压测要挂半小时、批量下载几千个文件——你要是让 Agent 用前台命令死等，要么撞上超时被砍，要么它就对着转圈啥也不干。今天这一课，就把 dsh 的**后台任务（background job）**机制讲清楚：怎么丢后台、怎么盯进度、怎么喊停，以及它背后那套「通知识别」的设计。 一、为什么 Agent 非得会「丢后台」默认情况下，dsh 里的命令工具（bash、终端）都是前台同步执行：Agent 发一条命令，就得死等它跑完拿输出，期间它什么也干不了。这对短命令没问题，对长任务就两个坑： 撞超时：前台命令有超时上限，跑不完就被打断，Agent 还以为是命令失败了。 干等：任务跑着，Agent 只能原地转圈，纯浪费一轮又一轮。 后台任务就是来解决这个的。dsh 的设计里，把「后...

生命不息，折腾不止。上一课解决了「上下文涨满」，这一课解决「活干到一半 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 负责真的去执行工具并回传结果...