目录

●第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