支撑 Claude Code 的那套 agent harness 被泛化成 Claude Agent SDK：同一套「能写文件、跑终端、迭代验证」的底座，不只服务写代码，也能搭 金融助理、客服、深研 这类「数字员工」。原文的抓手就一句：给 Agent 一台计算机——终端、文件、脚本、外连齐全，让它按 gather → act → verify 循环干活，而不是只在 chat 里空想。[1]
下面按原文结构走一遍，并用贯穿的 「邮件 Agent」 把模块串起来（示意级中文转述，非逐字译文）。[1]
进门三句话
- 主线：为何需要「一台电脑」（闭环）→ gather/act/verify 是什么 → SDK 能力边界 → 对工程与安全 意味着什么。
- 深度：文内
### 深度解析与 继承关系与未公开细节；文末 结论与讨论 与 延伸阅读。
一、和「理论篇」怎么配合读？
系列第 1 篇 Building effective agents 讲 workflow vs agent、模式清单、ACI；本文偏 产品化 harness：SDK 里已经替你集成 文件系统、bash、子 Agent、compaction、MCP 等「能跑起来的默认答案」。[1][2]
二、「给 Claude 一台电脑」到底指什么？
Claude Code 的设计哲学是：模型需要程序员日常同款工具——找文件、改代码、lint、跑起来、debug、再迭代。[1]
一旦通过终端拿到 bash、读写文件、搜索，Claude 也能做 非编程 活：读 CSV、搜网页、画图、解释指标——本质是 通用计算机上的数字员工。[1]
SDK 原则（归纳） ：让你的 Agent 也有「一台电脑」，按人类方式点鼠标/跑命令/落盘，而不是只在 chat 里空想。[1]
三、能造哪几类 Agent？（原文列举 + 中文一句场景）
| 类型 | 原文方向 | 中文场景一句 |
|---|---|---|
| Finance | 组合与目标理解、外部 API、落库、代码算指标 | 「按风险偏好筛一批标的并生成可复核的测算表」 |
| Personal assistant | 日历、差旅、简报、跨应用上下文 | 「订下周出差并拉齐三方会邀与材料包」 |
| Customer support | 高歧义工单、查数据、外连 API、升级人工 | 「先自动聚类工单再只把边界案例升舱」 |
| Deep research | 多文档检索、交叉验证、长报告 | 「跨 PDF/网页/内部 wiki 写可引用出处的对比结论」 |
底层都是：同一套 primitive（原语） 去拼你的工作流。[1]
四、Agent 闭环：gather → act → verify → repeat
原文给出的 Claude Code 典型节奏：收集上下文 → 行动 → 验证 → 再来一轮。[1]
邮件 Agent 贯穿线（示意） ：
- Gather：从历史会话文件夹、
fetchInbox/searchEmails、并行子 Agent 搜多路邮件摘要； - Act：按规则写回复草稿、调 MCP 查 Slack/Asana；
- Verify：规则校验地址格式、截图看 HTML 邮件排版、必要时子 Agent 审稿语气。[1]
五、Gather：别只会塞 prompt
5.1 Agentic search 与文件系统
文件系统 = 「可能被拉进上下文的信息的容器」。遇到大日志/用户上传，Claude 会用 grep/tail 等决定怎么局部加载——文件夹结构本身就是 context engineering。[1]
邮件例：把历史会话落在 Conversations/，被问及时先搜再读，而不是一次全塞进模型。[1]
5.2 Semantic search（向量检索）
更快，但维护成本、可解释性往往更差；要 chunk、embedding、向量库。[1]
原文建议：先 agentic search 起步，只有要更快或要更多变体召回再上语义检索。[1]
5.3 Subagents（子 Agent）
SDK 默认支持。价值二合一：并行多个子任务；隔离上下文——子 Agent 深搜后只把相关摘录回传给编排器，而不是整坨 thread。[1]
邮件例：并行多个「搜索子 Agent」各跑不同查询，只汇总相关片段。[1]
深度解析：子 Agent 与「上下文隔离」的代价
事实：SDK 支持子 Agent 与并行。[1]
原文观点：隔离上下文、只回摘录。[1]
本文解读：并行 N 个子任务时，编排器仍需 合并策略 与 去重，否则摘录层可能丢互信息；评测时除成功率外建议看 汇总后是否引入矛盾陈述。
5.4 Compaction（压缩）
长时运行必须维护上下文；SDK 的 compact 在接近上限时自动摘要历史消息——源自 Claude Code 的 /compact 体验。[1]
六、Act：行动层怎么设计才「好用」
6.1 Tools
工具在 Claude 上下文里很显眼，会强烈影响「下一步先想到啥」——因此工具要 token-efficient、行为边界清晰；细则见 Anthropic Writing tools for AI agents 类文章。[1][3]
邮件例：把 fetchInbox、searchEmails 设成最高频主行动。[1]
6.2 Bash 与脚本
Bash 是通用兜底：例如附件里 PDF → 下载 → 转文本 → 再搜关键词。[1]
6.3 Code generation（代码生成）
代码 精确、可组合、可复用；复杂操作（规则引擎、批处理、格式严格的 Office 文件）往往 写脚本比纯自然语言可靠。[1]
文中举例：Claude.ai 文件创建依赖生成 Python 去拼 Excel/PPT/Word，以保证版式与复杂逻辑。[1]
6.4 MCP
Model Context Protocol 把 Slack、GitHub、Drive、Asana 等标准化接入，减少自研 OAuth/胶水代码；Agent 直接调工具名即可。[1]
邮件例：search_slack_messages、get_asana_tasks 补齐「邮件之外的组织上下文」。[1]
七、Verify：没有验收的闭环不可靠
7.1 规则（Rules）
最佳反馈：清晰规则 + 指出哪条失败。Lint 是典型——原文倾向 TypeScript + lint 优于裸 JS，因为多一层结构化错误信号。[1]
邮件例：地址格式非法直接报错；若用户从未给某人发过信则 warning。[1]
7.2 视觉反馈（Visual）
UI/HTML 邮件可用截图回灌模型做版式迭代；检查布局/样式/层级/拥挤度等。[1]
可用 Playwright 类 MCP 自动截图、多视口（原文提及能力方向）。[1]
7.3 LLM as judge
可用另一个模型评「语气是否像用户」——但原文直言：鲁棒性一般、延迟成本高，仅当「再一点点性能也值」时考虑。[1]
八、测试与持续改进（原文问题清单压缩）
自问：[1]
- 误解任务 → 是否检索 API/数据结构太难用？能否改成分面搜索？
- 同类失败反复 → 能否在 tool 层加硬规则 自动纠偏？
- 不会修错 → 是否缺 更趁手的工具 或另一条路径？
- 功能迭代后抖动 → 建 代表性评测集 / eval（按真实用法采样）。
九、重要指标与工程考量（定性）
| 维度 | 关注点 |
|---|---|
| 闭环是否闭合 | gather 是否可复现、verify 是否可自动化 [1] |
| 上下文成本 | 工具是否啰嗦、子 Agent 是否只回摘要 [1] |
| 延迟 | 语义检索 vs 探索搜索；LLM judge 的额外 RTT [1] |
| 安全 | 终端/文件/MCP 权限边界（延伸） |
十、思辨延伸（非原文结论）
SDK 不是银弹：业务若只需固定 DAG，workflow + 少量工具可能更稳更便宜。
「一台电脑」= 攻击面：沙箱、白名单命令、敏感数据脱敏与审计要单独立法。
与系列第 3、4 篇衔接：工具一多就上 advanced tool use；上下文策展见 effective context engineering（见本仓库系列索引）。
继承关系与未公开细节：Claude Code 经验的泛化边界
事实：文章将 Claude Code 的 harness 能力泛化到 SDK。[1]
原文观点：gather→act→verify 闭环；终端/文件/MCP 为默认能力方向。[1]
本文解读（推断） ：非代码域落地时，verify 往往比写代码更难形式化——「规则 + 截图 + LLM judge」的权重需按域校准；安全与合规（终端白名单、数据出境）通常不在一篇博文里展开，需单独设计。
十一、上手与迁移
原文鼓励直接上手 Claude Agent SDK，并指向迁移到最新版的指南（以 Claude 开发者文档 当前页为准）。[1]
结论与讨论
技术坐标
SDK 把 「可跑的多轮工具闭环」 从 Claude Code 产品经验抽成 可编程 harness：在 Agent 谱系里，它连接 模式论文（Building effective agents）与 工具/上下文专文（writing tools、context engineering）。
批判性问题
- 你的任务 verify 是否可自动化——若不能，闭环是否在「人类接盘」处隐性断裂？
- Compaction 摘要是否丢掉关键工具 trace——是否有回归集专门测「长会话恢复」？
- 「一台电脑」带来的攻击面：是否与安全团队对齐过 MCP 与 bash 的权限模型？
独立判断（事实 / 原文观点 / 本文解读）
| 类型 | 内容 |
|---|---|
| 事实 | 原文博客 URL；与 building-effective-agents、writing-tools 的交叉引用。[1] |
| 原文观点 | 给 Agent 通用计算机能力；子 Agent、compact、MCP 集成叙事。[1] |
| 本文解读 | SDK 节省的是 脚手架时间，不节省 任务定义与评测；没有评测集的 Agent 项目仍会翻车。 |
若与 Claude 平台最新文档冲突，以官方文档为准。
参考文献与延伸阅读
- [1] Building agents with the Claude Agent SDK — 原文
- [2] Building effective agents
- [3] Writing tools for AI agents
- Effective context engineering
- 先读系列第 1 篇弄清 Workflow vs Agent，再读本篇理解 闭环四步 与邮件示例。
