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

八、参考来源 (18 篇)

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 架构共识