第1章  3重防线：Harness如何决定Agent的生死	1
1.1  一次真实的AI编码任务	2
1.2  使用3种Harness得到3个不同的结果	3
1.2.1  Claude Code：5步闭环，一气呵成	4
1.2.2  Codex：沙箱隔离，另辟蹊径	5
1.2.3  Claw Code：上下文溢出崩溃	6
1.2.4  成败之间：一张表看懂差距	7
1.3  3类典型的失败模式：Harness对Agent运行的影响	9
1.4  3道防线为何全部失守	10
1.5  Agent=Compose（Model, Harness）	14
1.6  Harness Engineering：AI工程的第三次跃迁	16
1.6.1  从Prompt Engineering到Harness Engineering	16
1.6.2  从零构建Harness：要代价，更要可解释性	16
第2章  Harness Engineering方法论	18
2.1  Harness的5个设计原则及它们之间的关系	19
2.1.1  约束：3条红线	19
2.1.2  告知：缩短试错路径	20
2.1.3  验证：闭环反馈	21
2.1.4  纠正：4级恢复阶梯	21
2.1.5  人在环中：分级授权	22
2.1.6  5个设计原则的递进关系	23
2.2  Harness的6层参考架构	25
2.2.1  全景与协作关系	25
2.2.2  Harness的架构为什么划分为6层	25
2.2.3  代码模块映射	26
2.2.4  业界公开实践与参考架构的对应关系	27
2.2.5  可观测性	28
2.3  补偿面：Harness的动态演化	29
2.3.1  模型能力不足与组件补偿	29
2.3.2  构建—观测—移除的迭代循环	31
2.4  3类Harness实现方案的设计哲学	32
2.4.1  3类Harness实现方案的信任假设	32
2.4.2  开源Harness的可行性	33
2.5  常见的Harness能力检查清单	34
2.5.1  清单结构	34
2.5.2  清单应用示例	35
2.6  渐进式构建路径	37
第3章  Agent循环与约束层	39
3.1  最小可用的Agent循环	40
3.1.1  Agent循环的5个步骤	40
3.1.2  从Harness骨架到生产级框架	42
3.2  约束层的3项核心机制	44
3.2.1  路径安全检查	44
3.2.2  危险命令拦截	45
3.2.3  危险内容检测	45
3.3  渐进式安全实验	47
3.3.1  无防护运行	47
3.3.2  单层绕过	47
3.3.3  多层拦截	48
3.3.4  实验总结	49
3.4  沙箱隔离机制	50
3.4.1  3层防御模型	50
3.4.2  进程内策略沙箱	51
3.4.3  网络访问控制	53
3.4.4  敏感路径保护	55
3.4.5  容器级隔离	56
3.5  权限模式与运行时守卫	58
3.5.1  权限模式	59
3.5.2  工具调用Hook（钩子）	61
3.5.3  预算熔断	62
3.5.4  LoopGuard	64
3.6  约束陷阱与进阶	67
3.6.1  约束与效率	67
3.6.2  Harness与提示词约束	68
3.6.3  规则拦截与沙箱防护	68
3.6.4  从拦截率到行为收敛度	69
第4章  工具系统与MCP	72
4.1  工具接口的设计原则	73
4.1.1  设计工具的4个标准	73
4.1.2  工具描述的精度对工具选择的影响	74
4.2  基础工具的实现	75
4.2.1  文件操作工具	76
4.2.2  文件与内容搜索工具	79
4.2.3  命令执行工具与超时控制	81
4.3  工具注册与动态管控	82
4.3.1  注册与分发机制	82
4.3.2  接口描述与模型协商	84
4.3.3  分阶段动态加载	85
4.4  MCP与外部能力接入	86
4.4.1  传输机制与工具发现	87
4.4.2  数据库接入示例	88
4.4.3  工具集规模的权衡	91
4.5  常见的问题与调优实践	93
4.5.1  工具误用的排查方法	93
4.5.2  工具数量膨胀的上下文开销	94
4.5.3  接口描述的隐性消耗	95
4.6  工具描述的实验评估	96
4.6.1  工具描述评测方法	96
4.6.2  工具描述提示词的对照实验	97
4.6.3  工具描述长度的最优区间	99
4.6.4  系统提示词的边界效应	101
4.6.5  评测基础设施优化	102
第5章  上下文工程与Prompt Cache	103
5.1  仓库即现实：Agent的操作目录	104
5.1.1  环境线索决定行为质量	104
5.1.2  精简AGENTS.md文件的4类关键信息	104
5.1.3  负向与正向措辞的对比	107
5.1.4  文档瘦身与维护策略	108
5.2  3层文档架构	109
5.2.1  3层发现机制	110
5.2.2  辅助配置	112
5.2.3  分层实践	112
5.2.4  Express.js项目案例	113
5.3  系统提示词的组装与注入	115
5.3.1  拼接顺序：base+project+rules	115
5.3.2  按工作目录和任务类型条件注入	118
5.3.3  动态信息与静态前缀的分离	120
5.4  Prompt Cache原理与成本优化	122
5.4.1  前缀匹配与KV缓存机制	122
5.4.2  静态前缀最大化与动态后缀分离	123
5.4.3  命中率实测与调优实践	124
5.4.4  长间隔会话与边界控制	126
5.4.5  缓存策略对长会话Token累积量的影响	127
5.4.6  无原生缓存时的替代方案	128
第6章  记忆管理与上下文压缩	130
6.1  上下文腐烂	131
6.1.1  长会话后的信噪比塌陷	131
6.1.2  有效窗口萎缩的症状	133
6.2  渐进式有损压缩	134
6.2.1  L0级压缩：工具返回结果的即时裁剪	136
6.2.2  L1级压缩：将旧工具返回结果替换为摘要	137
6.2.3  L2级压缩：模型生成全局上下文摘要	139
6.2.4  紧凑指令防止目标丢失	141
6.2.5  L3级压缩：窗口溢出时的紧急截断	142
6.2.6  压缩后工具调用的配对修复	143
6.2.7  压缩机制在长会话中的实际效果	144
6.3  压缩触发与分级响应	145
6.3.1  压缩触发与预算约束	146
6.3.2  4级压力响应	148
6.4  跨会话的长期记忆	150
6.4.1  6层记忆架构	150
6.4.2  自动记忆读/写机制	151
6.4.3  离线去重与整理	154
6.5  会话持久化与断点续传	157
6.5.1  JSONL格式保存	157
6.5.2  中断恢复	159
6.5.3  3步唤醒流程	161
第7章  验证与对抗评估	163
7.1  自评偏差与验证层	164
7.1.1  自评偏差：从个案到业界共识	164
7.1.2  双Bug实验：假阳性量化	166
7.1.3  验证层在6层参考架构中的位置	167
7.2  验证闭环	168
7.2.1  计算性验证与推理性验证	168
7.2.2  验证职责的归属实验	170
7.2.3  Harness框架强制验证的最小实现	172
7.3  最佳实践评估者	174
7.3.1  为什么需要独立Evaluator	174
7.3.2  Evaluator的系统性偏差	176
7.3.3  评估判定的5个维度	178
7.3.4  验收清单与Sprint Contract	180
7.3.5  从伪对抗到真对抗	181
7.4  循环守卫	182
7.4.1  工程定位	182
7.4.2  4层防御实验	183
7.4.3  检测机制	185
7.4.4  适用边界	187
7.5  事前验证	188
7.5.1  4种实现方式的对比	188
7.5.2  机械式只读阶段的反模式	189
7.5.3  Plan Mode 与 Plan Artifact	191
7.5.4  适用边界与决策依据	192
7.6  验证层的整体设计	193
7.6.1  验证层整体结构：4个防御机制的时间轴排列	193
7.6.2  组件激活策略	195
7.6.3  验证粒度与反馈回路	196
7.6.4  其他5层的耦合	198
7.6.5  失败模式与缓解	199
第8章  反馈调节：让Harness自我演化	201
8.1  为什么需要反馈	202
8.1.1  静态 Harness的退化曲线	202
8.1.2  控制论视角：Plant与Controller	203
8.1.3  控制器状态机	204
8.1.4  6层补偿面的退化映射	207
8.2  反馈信号与信号仲裁	208
8.2.1  离线信号	208
8.2.2  在线信号	209
8.2.3  对抗信号	209
8.2.4  信号仲裁规则	210
8.3  离线评估基础设施	210
8.3.1  Subject-Task-Runner抽象	211
8.3.2  Capture-only Runner	213
8.3.3  双轨指标与统计显著性	214
8.3.4  跨层对照实测	214
8.4  在线观测	216
8.4.1  会话日志结构化	216
8.4.2  聚合指标	217
8.4.3  异常检测与漂移告警	218
8.4.4  LLM行为指标：Agent系统的特有维度	218
8.5  失败挖掘与规则沉淀	220
8.5.1  失败挖掘	220
8.5.2  半自动生成CLAUDE.md规则	221
8.5.3  失败分诊规则	223
8.5.4  技能自主进化	224
8.5.5  Dream 记忆整理	224
8.6  安全发布与灰度控制	225
8.6.1  候选变更契约	225
8.6.2  影子测试	226
8.6.3  灰度发布策略	227
8.6.4  发布门禁、多目标权衡与停止条件	228
8.6.5  反馈闭环的运营成本与执行节奏	230
8.7  安全反馈	231
8.7.1  安全防御的4层机制	231
8.7.2  Red Team对抗评估	233
8.7.3  编排层反馈特例	235
8.7.4  失败复盘	236
8.8  元评估与闭环进化	237
第9章  实战一：遗留系统重构	240
9.1  万行级Java临床路径管理系统的技术债务	241
9.2  重构任务的Harness配置设计	245
9.2.1  任务边界与约束层	246
9.2.2  工具层与上下文策略	248
9.2.3  CLAUDE.md文件与验证层	250
9.2.4  配置代码与运行入口	252
9.3  执行过程、结果与关键发现	254
9.3.1  执行概况与工具调用分布	254
9.3.2  God Service的职责拆分与Facade模式	254
9.3.3  从验收失败到成功的反馈闭环	256
9.3.4  Hook与只读路径的物理约束	257
9.3.5  自动化重构的关键工程结论	257
9.4  从实践到生产级重构的迁移	258
9.4.1  迁移3步法	258
9.4.2  多语言项目的验收适配	259
9.4.3  大规模项目的分模块策略	259
9.4.4  常见的失败模式与检查清单	260
第10章  实战二：医疗数据服务的合规加固	263
10.1  医疗数据服务的合规漏洞	264
10.1.1  3类系统性漏洞模式	264
10.1.2  10个漏洞的分类与风险等级	265
10.2  《网络安全等级保护基本要求》与《数据安全法》的工程化
 解读	267
10.2.1  从法规条款到代码检查项的解读	267
10.2.2  漏洞与法规违反项的交叉对照	268
10.3  沙箱-Hook-CLAUDE.md文件3层防御设计	269
10.3.1  禁止外网与数据目录隔离	270
10.3.2  PII检测与自动脱敏Hook	272
10.3.3  在医疗场景中CLAUDE.md文件的修复边界	276
10.4  SQL参数化、PII脱敏与审计日志修复	277
10.4.1  查询层的参数化改造	277
10.4.2  响应层的PII脱敏	281
10.4.3  审计日志的结构化增强	282
10.4.4  硬编码路径与调试开关的清理	284
10.5  验收通过与完整的审计证据链	285
10.5.1  verify.py文件的离线验收框架	285
10.5.2  从Hook拦截到日志归档的审计证据链	288
10.5.3  结构化合规日志的JSONL格式	288
10.6  合规改造的常见失败模式与设计权衡	290
10.6.1  沙箱开口过大与Hook正则表达式漏匹配	290
10.6.2  Schema偷换与规则稀释	291
10.6.3  检测强度、脱敏位置与日志持久化的权衡	292
10.6.4  效率问题的本质：把流程变成框架行为	294
10.7  3层防御架构的跨行业迁移	296
10.7.1  不同行业的PII正则模式替换	296
10.7.2  金融场景的网络白名单与加密要求	296
10.7.3  跨行业不变的3层防御架构	297
第11章  实战三：跨语言系统集成的多Agent协作	299
11.1  编排层：从单Agent到多Agent的治理跃迁	300
11.1.1  跨系统协作的复杂度跃迁	300
11.1.2  临床路径管理系统中智能预警的双端需求	301
11.1.3  为什么需要角色隔离而非更大的上下文窗口	302
11.1.4  编排层的设计原则	302
11.1.5  编排层的对象模型	304
 
11.2  角色设计与权限边界	306
11.2.1  Architect：制订全局计划，只读业务代码	306
11.2.2  两个Developer：对称权限，隔离目录	307
11.2.3  QAEngineer：跨端验证，独立报告	308
11.2.4  角色边界的设计方法	309
11.3  编排方式：计划、并行开发、验收闭环	311
11.3.1  轮次计划与协作顺序	311
11.3.2  并行开发的前提：契约与边界	312
11.3.3  文件作为协作接口	313
11.3.4  状态机与收敛判断	314
11.3.5  契约漂移与防御机制	315
11.4  验收设计：从基线失败到完整通过	315
11.4.1  基线运行与预期失败	315
11.4.2  verify.py的8项检查	316
11.4.3  收敛条件与机器可读报告	317
11.5  交付物与契约映射	318
11.5.1  Java端：Python服务客户端的封装	318
11.5.2  Python端：Java规则服务的异步封装	319
11.5.3  QAEngineer端：跨端验收与测试覆盖	319
11.5.4  契约到代码的映射关系	320
11.6  日志审计与成本分析	322
11.6.1  JSONL日志的证据链	322
11.6.2  Hook和LoopGuard的拦截价值	323
11.6.3  多Agent链路的成本结构	324
11.7  编排层设计的教训	325
11.8  多Agent架构的适用边界与迁移路径	327
11.8.1  3个适用标准	327
11.8.2  单Agent仍更优的场景	327
11.8.3  向生产团队迁移的4项原则	328
 
第12章  生产部署与成本治理	329
12.1  Token消耗与结构化观测	330
12.1.1  5个独立预算区段的成本分布	331
12.1.2  Token估算与日志结构	334
12.1.3  生产指标与链路追踪	335
12.1.4  缓存命中与成本预测	337
12.2  成本熔断与模型路由	337
12.2.1  3级预算熔断	337
12.2.2  分层模型路由	339
12.2.3  路由接口设计	341
12.3  环境隔离与数据合规	343
12.3.1  3层防御模型	343
12.3.2  容器沙箱与资源限制	344
12.3.3  敏感数据过滤	346
12.3.4  数据不出域方案	347
12.3.5  多租户资源隔离	347
12.4  生产运营与检查清单	348
12.4.1  安全检查清单	348
12.4.2  生产失败模式	350
12.4.3  生产指标看板设计	351
12.4.4  架构决策要点	352
12.4.5  CI门禁	352
12.4.6  版本发布与回滚	353
12.4.7  事件响应机制	355
12.4.8  内核一致性验证	356
12.5  业界实践与Harness演进	357
12.5.1  企业安全实践	357
12.5.2  补偿面的动态演化	357
12.5.3  模型进步与工程韧性	359
12.5.4  从实践到生产的路径	360