Agent 经验技术参考站

Claude Code 泄露事件: 2026.3.31 Anthropic 意外将 512,000 行 TypeScript 源码泄露到 npm。Garry Tan 读完结论: "秘密不在模型，在包裹模型的 Harness。" Harness 只做四件事: 运行模型循环 → 读写文件 → 管理上下文 → 执行安全约束。

Thin Harness, Fat Skills 架构

层	职责	说明
Harness (薄)	4 件事	loop · file I/O · context mgmt · safety
Skills (厚)	领域知识	结构化 Markdown，包含规则/反例/边界/顺序
Resolver (路由器)	上下文加载	Task X → 加载 Skill Y。描述即路由
Deterministic (执行)	确定性代码	SQL·编译·算术。隐空间做大模型，确定空间做代码

Garry Tan 原话: "The bottleneck is never the model's intelligence. They fail because they don't understand your data."

YC·Garry TanClaude Code

Skill 文件模式


/investigate (Skill): 7 steps

  scope → timeline → diarize → synthesize → argue → cite → conclude

  Parameters: TARGET, QUESTION, DATASET



用同一个 Skill，传入不同参数 = 完全不同的能力

  TARGET=safety scientist, DATASET=2.1M emails → 医学研究分析

  TARGET=shell company, DATASET=FEC filings → 法务调查

Skill as Method CallReusable

二、记忆系统

四大架构对决

系统	存储	延迟	最佳场景	评分
Letta (MemGPT)	OS 式三层 (Core/Recall/Archival)	中	长时间会话 · 自管理记忆	74% LoCoMo
Mem0	向量 + 图扩展	低	高密度用户事实	94.4% LongMemEval
Zep (Graphiti)	时序知识图谱	低	CRM · 合规 · 医疗	71.2% LongMemEval
pgvector 自建	PostgreSQL	最低	最大控制力	—

异步 Memory 管线

User→Agent→Response(inline) └→Queue→Worker→Extract Facts→Update Graph→Upsert Vector

记忆抽取不阻塞主请求。p95 延迟可预测。

CallSphere 模式

记忆遗忘三策略

策略	实现
TTL on Episodic	原始事件 30-90 天清理。语义存储保留精华
Provenance on Semantic	每条事实标注来源 Episode ID。LLM Judge 裁决合并
Confidence Decrement	技能版本化，失败扣分，低于阈值退役

三、评估体系

六维轨迹评估

维度	失败模式
1. Tool Selection	选错 / 该用没用 / 虚构工具
2. Argument Extraction	Schema OK 但语义错 / 边界漏
3. Result Utilization	工具返回了但 Agent 用模型知识替代
4. Error Recovery	重复不变的参数 / 不重试 / 无限重试
5. Plan Coherence	死循环 / 规划偏移 / 遗忘初始目标
6. Task Completion	答案对但路径错 / 路径对但没完成

四类测试集

类型	测什么
Simple	单工具基础选择
Multi-Step	多工具链推理整合
Adversarial	注入失败测试恢复
Open-Ended	多路径测试效率

DeepRails

四、生产工程

四大护栏

层	作用
1. Input Guards	验证输入 · 注入检测
2. Tool Gating	low=读 · medium=写 · high=执行(审批)
3. Output Guards	过滤不安全 · PII 检测
4. Eval Loop	Golden Set 50-200 条 CI 回归

工具五要素

#	要素
1	JSON Schema 严格输入
2	Idempotency Key
3	Risk Rating (low/med/high)
4	Structured Error Response
5	Version History + Migration

Tools = 80% of engineering

错误恢复四类

失败	策略
Model	重试 + 降级更简单模型
Tool	退避重试 + 备选工具
Logic	循环检测 + 计划重聚焦
Resource	优雅降级 + Checkpoint

7 大生产错误

#	错误	修复
1	无 Token 限制	硬限制 input/output
2	同步一切	异步任务队列
3	无 Fallback 模型	降级链
4	记录完整 Prompt	只记录 metadata
5	无断路器	熔断模式
6	无 Eval 基线部署	部署前跑 evals
7	无条件信任 Agent	破坏性操作需审批

TheOperatorCollective

五、Simon Willison 的 8 个工程模式

8 Patterns for AI Coding Agents

#	模式	一句话
1	Writing code is cheap	生成代码零成本，但好代码仍然贵。直觉说不值就试试看
2	Hoard known techniques	囤积所有解决过的问题。AI 理解一次就能查阅/复用/重组
3	Red-Green TDD	先写测试(红)，确认失败，再写实现(绿)。防幻觉代码
4	First run the tests	每次新会话第一句话: "先跑测试"。让 AI 进入测试心态
5	Linear walkthroughs	让 Agent 生成结构化代码走查文档。AI 变成学习加速器
6	Interactive explanations	文字讲不清 → Agent 生成动画/可视化。真正理解原理
7	Agentic manual testing	让 Agent 自己用 curl/python -c/Playwright 手动测试
8	Never inflict unreviewed code	不要提交你没审查过的 PR。附测试证据

核心概念: Cognitive Debt — 代码能跑但你不理解原理。用 Walkthrough + Interactive 偿还。

Simon Willison2026

YC 七步构建 AI 原生组织

步	行动
1	选窄而具体的业务目标
2	先接可观测性和评估体系
3	单 Agent 循环起步
4	真实故障出现再加复杂度
5	无聊的基础设施 (Postgres + MCP + E2B)
6	每季度评估一次模型（别每周追新）
7	盯紧单位经济模型（PoC $0.50 × 100x = $50K/月）

YC 共识: "底层工程能力远重于框架追新。先做 eval、工具、沙盒、Harness，别追新框架。"

YC · Garry Tan

六、安全护栏

Harness 安全评估

威胁	防御
Prompt Injection	架构级隔离，不靠 Prompt 指令
Over-tooling	工具定义占半个 context → 精简到 7 个以内
Timeouts	每个工具独立超时 + 全局超时
Data Exfiltration	沙箱隔离 · 网络 egress 白名单
Runaway Loops	max_turns · 断路器 · 成本上限

agents-best-practicesHarness Pattern

Shadow → Assist → Autonomous

阶段	行为	风险
Shadow	后台运行，与人工对比，不执行	零
Assist	生成草稿，人工确认后执行	低
Autonomous	自主执行	需护栏

七、实施清单

🔴 今日 2h

#	经验	来源	行数
1	Tool Idempotency Key	SensusSoft	40
2	工具风险三级分级	eCorpIT	30
3	异步 Memory 管线	CallSphere	50
4	Memory 时效字段	Zep	20
5	Cost/Quality 数据追踪	Pento	30
6	循环检测 + 熔断	DevPick	40
7	四种失败恢复策略	DevPick	60

🟡 本周

#	经验	来源
8	interrupt() + resume() 原语	LangGraph
9	Shadow Mode 灰度对比	Pento
10	Golden Set 50 条 + CI 回归	Pento
11	LLM-as-Judge 六维评估	Future AGI
12	记忆遗忘机制 (TTL+provenance)	Mem0
13	工具版本化 migration	SensusSoft
14	Skill 文件系统	Thin Harness

七、Prompt Caching (成本杠杆)

Static-First 排序规则

字节级严格匹配: 一个空格不同=缓存全失效

System Prompt → Tool Defs → Few-shot → History → User Message
(静态在前 · 动态只在最后 · 从不打破顺序)

Zylos Research90%折扣

三大Provider对比

Provider	方式	折扣	最少tokens	TTL
Anthropic	显式 breakpoint (4个)	90%	无	5min/1hr
OpenAI	自动前缀	50%	1024	自动
Google	命名缓存对象	—	无	可配置

常见缓存破坏

错误	后果
动态时间戳插入system prompt	缓存全失效
工具定义JSON key顺序变化	缓存失效
多replica随机分发请求	命中率→0
retrieval结果注入静态区前	之后全部失效

八、Aider 技术细节

Repo-Map (杀手功能)

tree-sitter解析AST → 提取函数签名/类定义 → PageRank排序 → 压缩上下文。不扫描全文件，只给骨架。

Aider44K stars

Architect/Editor 双模型

推理模型(Claude Opus/DeepSeek R1)做规划 + 便宜模型(Llama/GPT Mini)做编辑 = +10分 Polyglot benchmark · 成本降低50%

Aider

4种编辑格式

whole(全文) · diff(SEARCH/REPLACE) · udiff(unified-diff) · diff-fenced
自动按模型选择最佳格式

九、Replit Agent 架构

决策时引导

在Agent决策点注入微指令(不占上下文)。False positive无代价。

Replit

DSL工具调用

不用JSON function calling → 生成Python受限DSL调用工具。比传统tool calling更可靠。

三Agent分工

Agent	职责
Manager	监督工作流 · 分配任务
Editor	执行编码任务
Verifier	检查代码 · 回退到用户

十、Devin/OpenHands 状态管理

TASK_STATE.md (核心创新)

外化Agent工作记忆为文件。记录: 目标分解 · 已完成 · 当前步骤 · 阻塞问题。每次调用模型时注入到context最前面。

OpenHands可观测·可恢复

Planner/Executor 分离

规划用一次LLM调用 → 结构化状态 → 执行器分步执行。失败时Planner收到结构化"step X failed because Y"事件。

Devin

十一、金融Agent 生产经验

JPMorgan 六步法

步	行动
1	先建统一治理数据层
2	内部优先→员工→客户(降低风险)
3	Agent身份框架(RBAC)
4	低风险·高量域先试点
5	Human-in-the-loop内置设计
6	实时可观测性+异常检测

JPMorgan500+用例

十二、OpenHands 生产实战

80%成功率公式

指定要修改的文件 · 定义精确行为 · 'done'用可运行命令 · 一个PR一个焦点任务

差: "修改接口" → 好: "编辑 src/api/users.ts 返回 400/500"成功率 80%

沙箱最小权限原则

只挂载当前目录,不给整个HOME。Agent就是不可信代码。

SANDBOX_VOLUMES=$PWD:/workspace:rw ← 最小写权限OpenHands v1.7

Planning Mode (v1.6+)

Agent先写实施计划→暂停→用户确认→再touch代码。非trivial任务成功率大幅提升。

Human-in-the-loop

Headless 使用条件

可以Headless	必须Interactive
交互验证3次以上	新类型任务
测试完全约束	高风险任务
爆炸半径小	模糊需求

GitHub Issue自动化

60%积压bug一次修好 · 12/20自动修复 · 5/20需补充提示 · 3/20太模糊

OpenHands + GitHub Actions

SWE-bench 排行

工具	得分	特点
Claude Code	87.6%	最强 · Anthropic only
OpenHands+Claude4.5	72-77%	开源·模型灵活·自部署
Devin 2.0	45.8%	闭源·企业

SWE-bench Verified

十三、自进化 Agent

Gödel Agent — Monkey Patching

运行时读取自身代码 → LLM分析失败 → 生成补丁 → exec()注入 → 自动回滚。数学推理 +11% vs Meta Agent Search。

arXiv 2026递归自进化

Autogenesis 协议

版本化资源生命周期: Create→Activate→Suspend→Terminate。闭环: Monitor→Diagnose→Propose→Evaluate→Commit。

ICLR 2026

HYPERAGENTS — 教练+运动员

meta-process 观察→实验→改写策略。SWE-bench 20%→50%，跨模型迁移。

Meta · ICLR 2026+30%

十四、A2A 协议 (Agent 互联网)

150+组织 · 22K Stars · v1.0 稳定

Agent-to-Agent 开放标准。Linux Foundation 治理。5语言 SDK。

Google 2026

核心概念

AgentCard(自动发现) · Task(生命周期) · Message(多模态) · Artifact(版本化输出) · Signed Cards(密码学身份 v1.0)

AP2 — Agent 支付协议

60+组织支持。Agent 自主交易、密码学购买凭证。

经济层

MCP vs A2A

MCP=Agent↔Tools(垂直) | A2A=Agent↔Agent(水平) — 互补不竞争

十五、Agent 安全 (2026 实战)

攻击向量: 间接注入38% · 工具输出21% · 直接17%

平均攻击成功率56%，最佳模型仍有32%。解决方案在架构层。

Zylos 2026

五层防御栈

输入守卫 → 工具权限 → 输出过滤 → 出站白名单 → 持续红队

ASR 应和延迟/准确率并列为一级指标

四类不可检测攻击

混淆攻击(Base64) · Crescendo(多轮渐进) · 载荷拆分 · ANSI 不可见字符

十六、参考来源 (46 篇)

1	Garry Tan — Thin Harness, Fat Skills (70万+ 阅读)	2026-04
2	DevPick — Building Production AI Agents: What Actually Works	2026-01
3	eCorpIT — 5 Hard-Won Lessons from Shipping Production AI Agents	2026
4	Pento — Shipping AI Agents to Production: Context Engineering Recipe Book	2026
5	SensusSoft — AI Agents Production Engineering Playbook	2026
6	AgentMarketCap — Agent Memory Architecture Showdown 2026	2026-04
7	CallSphere — Agent Memory Patterns: Episodic, Semantic, Procedural	2026
8	Future AGI — Agent Metrics Frameworks: Three Approaches	2026
9	Confident AI — LLM Agent Evaluation Complete Guide	2026
10	DeepRails — Agent Evaluation: Beyond Single-Turn Metrics	2026
11	LayerLens — How to Evaluate AI Agents	2026-03
12	AppScale — Durable Execution: LangGraph Checkpointers	2026
13	Simon Willison — 8 Agentic Engineering Patterns	2026-02
14	Zooz Engineering — Harness Engineering 2026 Guide	2026
15	TheOperatorCollective — Deploy AI Agents to Production	2026
16	AgentMelt — AI Agent Pilot to Production Checklist	2026
17	Neon — Six Principles for Production AI Agents	2026
18	Nir Diamant — Agents Towards Production (GitHub)	2026

🧠 Agent 经验技术参考站 v2

一、Thin Harness, Fat Skills — 2026 架构共识