1. 项目概述：Harness-Zero 不是“给模型加插件”，而是让模型自己长出工具手

最近在多个技术社区和内部分享会上，我反复被问到一个问题：“Harness-Zero 到底是不是又一个智能体框架？它和 Dify、LangChain、AutoGen 有什么区别？”我的回答一直很直接：它根本不是框架，而是一次权重层面的范式迁移——我们不再教模型“怎么调用工具”，而是让它“天然具备调用能力”。这个标题里最关键的三个词，“Agent-as-Harness”、“蒸馏”、“Harness”，每一个都不是修辞，而是实打实的技术动作。Harness-Zero 的核心目标非常朴素：把原本依赖外部运行时（比如 Python 解释器、插件加载器、API 网关）才能完成的复杂行为——比如解析 PDF 表格、执行 SQL 查询、调用天气 API、甚至控制本地 Excel 文件——全部压缩、固化、内化进模型自身的参数空间里。不是靠 prompt 工程绕开限制，也不是靠 runtime 注入临时能力，而是让模型在推理时，仅凭自身权重，就能生成结构正确、语义精准、可直接执行的工具调用指令序列。

这背后解决的是当前智能体落地中最顽固的“能力断层”问题。你用 Dify 搭建一个销售助手，它能调用 CRM 接口；但一旦脱离 Dify 运行环境，模型本身立刻退化成一个普通文本生成器。Harness-Zero 要打破的就是这个“环境依赖锁”。它不追求通用性，恰恰相反，它极度聚焦于“专用性”——为某一个具体业务场景（比如银行信贷审批、电商售后工单分派、医疗报告结构化提取），把该场景下所有必需的外部交互逻辑，通过一种新型的蒸馏协议，从一个“带 Harness 的教师智能体”中，精准地迁移到一个更小、更快、更易部署的学生模型中。我试过用它把一个原本需要 8GB 显存、依赖 5 个 Python 插件的客服智能体，蒸馏成一个 3B 参数的本地模型，部署在 24GB 显存的 A10 上，响应延迟从平均 1.8 秒压到 320ms，且不再需要任何外部服务进程。这不是性能优化，这是能力重构。

关键词“Harness”在这里不是“马具”或“吊带”的字面意思，而是一个工程隐喻：它指代一套可插拔、可验证、可组合的外部行为契约。一个 Harness 就像一个标准化的“能力接口卡”，定义了输入格式（如 JSON Schema）、输出约束（如正则校验）、失败重试策略（如指数退避）、以及最重要的——行为语义锚点（Behavioral Semantic Anchor）。这个锚点确保蒸馏后的模型权重，在生成“调用天气 API”时，不会混淆成“搜索网页”或“生成天气描述”，而是稳定地输出符合 OpenAPI 规范的、带正确 query 参数的 curl 命令片段。所以，“Harness-Zero”这个名字里的 “Zero”，指的不是“零代码”或“零配置”，而是“Zero Runtime Dependency”——零运行时依赖。它要达成的终极状态是：模型权重即能力，部署即可用，无需额外的 harness runtime、plugin manager 或 agent orchestration layer。这对边缘设备、私有化交付、高合规要求的金融/政务场景，价值几乎是颠覆性的。

2. 核心设计思路：为什么放弃传统智能体架构，选择“蒸馏 Harness”这条路？

2.1 传统智能体架构的三大硬伤，是 Harness-Zero 的出发原点

我在过去三年里主导过 7 个企业级智能体项目，从制造业设备故障诊断到保险理赔自动化，踩过的坑足够写一本《智能体落地避坑指南》。所有项目最终都撞上同一堵墙：能力与模型的物理分离。这种分离不是设计缺陷，而是现有技术栈的必然结果。我们来拆解一下：

第一，调度层与模型层的语义鸿沟。LangChain 的 Chain、LlamaIndex 的 QueryEngine、Dify 的 Workflow，它们本质上都是“决策路由器”。模型输出一段自然语言，调度层再用正则或 LLM 分类器去识别意图、提取参数、匹配工具。这个过程引入了至少两层误差：模型生成的文本可能模糊（“查一下张三的保单” vs “查询客户ID为ZS2024001的最新保单状态”），而调度层的解析器又可能误判（把“更新地址”当成“查询地址”）。我做过一组对比实验：同一个保险问答数据集，纯 prompt 方案准确率 68%，加 LangChain 调度后反而降到 61%——因为调度器把 23% 的“地址变更请求”错误归类为“信息查询”。

第二，插件生态的脆弱性与黑盒性。所谓“Harnessed Agent”，其核心是插件（Plugin）。但插件本身就是一个黑盒：它的输入校验逻辑、错误处理策略、重试机制、甚至返回字段的命名规范，都由开发者自由定义。当一个插件升级了 API 版本，或者更换了认证方式，整个智能体就可能 silent fail。我们曾遇到一个案例：某政务平台的“户籍信息查询”插件，因上游公安系统升级，将返回字段id_card_no改为idCardNo，导致下游所有依赖该字段的流程全部中断，而日志里只显示“JSON decode error”，排查耗时 17 小时。Harness-Zero 的设计哲学就是：拒绝黑盒，拥抱契约。它要求每个 Harness 必须提供机器可读的、形式化的契约描述（我们用扩展版 OpenAPI 3.1 + 自定义 x-harness-* 字段），包括字段语义标签、业务约束（如“身份证号必须为18位数字”）、以及失败模式分类（如 network_timeout, auth_failed, data_not_found）。

第三，部署与运维的爆炸式复杂度。一个典型的生产级智能体，往往需要同时维护：LLM 推理服务（vLLM/Triton）、向量数据库（Milvus/Weaviate）、插件服务集群（FastAPI/Flask）、调度协调器（Celery/K8s Job）、监控告警（Prometheus/Grafana）。光是服务间 TLS 证书轮换，就足以让 SRE 团队崩溃。而 Harness-Zero 的目标是“单模型、单服务、单镜像”。它把所有这些外部依赖，通过蒸馏，变成模型权重的一部分。部署时，你只需要一个支持 vLLM 的 GPU 实例，加载一个.safetensors文件，即可对外提供完整能力。没有插件服务要启，没有向量库要连，没有调度器要配。这不仅降低了运维成本，更重要的是，它让“能力交付”回归到最原始的形态：交付一个文件，而不是交付一套基础设施。

2.2 “Agent-as-Harness”：不是让模型当代理，而是让模型成为契约的原生实现者

这里必须澄清一个常见误解：“Agent-as-Harness” 并非指“把模型当作一个 Harness 来用”。恰恰相反，它的意思是：Harness 是一个独立的、可验证的行为契约实体；而 Agent（智能体）只是这个契约的一个参考实现；Harness-Zero 的目标，是让学生模型成为该契约的、更轻量的、权重级的原生实现。这就像编译器原理里的“中间表示（IR）”：Harness 就是那个 IR，它定义了“应该做什么”，而不规定“怎么做”。教师 Agent（比如一个基于 DeepSeek-VL 的多模态智能体）是用 Python + 插件实现这个 IR 的一个具体版本；而学生模型（比如一个 3B 的 Qwen-Chat 微调版）则是用神经网络参数实现同一个 IR 的另一个版本。

这个设计带来了两个关键优势。其一，契约与实现彻底解耦。你可以用任意技术栈实现一个 Harness 的教师 Agent：它可以是基于 Claude 的云端服务，也可以是本地部署的 Ollama + Shell 插件组合，甚至可以是一个人工标注员组成的“人肉 Harness”。只要它能稳定地、按契约要求输出正确的工具调用序列，它就可以作为蒸馏的教师。我们在一个医疗项目中，就用医生手工标注的 2000 条“检查报告结构化”样本，构建了一个“人肉 Harness”，然后用它蒸馏出一个能直接输出 FHIR 格式 JSON 的小模型。其二，蒸馏目标高度可控。传统知识蒸馏（Knowledge Distillation）通常蒸馏 logits 或 hidden states，目标模糊。而 Harness-Zero 蒸馏的是“契约遵守度（Contract Compliance Score）”。我们定义了一个损失函数：L = α * L_task + β * L_contract。其中L_task是常规的指令微调损失（如 SFT），而L_contract是一个复合损失，包含：① 输出 JSON Schema 的结构合规性（用 Pydantic 模型验证）；② 关键字段值的业务约束满足度（如日期格式、数值范围）；③ 失败模式预测的准确性（模型需预测本次调用最可能失败的原因）。这个设计让蒸馏过程不再是“学得像”，而是“做得对”。

2.3 为什么选择“蒸馏”而非“微调”或“RAG”？

有人会问：既然目标是让模型具备外部能力，为什么不直接用 RAG（检索增强生成）？或者用更激进的“全参数微调（Full Fine-tuning）”？答案在于精度、可控性与泛化性的三角平衡。

RAG 的本质是“查表+改写”。它把外部知识存在向量库里，模型负责检索和组织语言。但 RAG 对“行为”无能为力。它无法教会模型“如何构造一个符合 Swagger 规范的 POST 请求体”，也无法保证模型在生成 SQL 时，永远使用WHERE而不是HAVING来过滤行。RAG 只能告诉你“某条记录是什么”，而 Harness-Zero 要教会模型“如何精确地获取那条记录”。

全参数微调则面临“灾难性遗忘”和“过拟合”的双重风险。我们曾尝试用 5000 条“CRM 数据查询”样本，对一个 7B 模型进行全参微调。结果是：模型在测试集上准确率提升到 92%，但在未见过的“ERP 库存查询”任务上，准确率暴跌至 38%，且生成的 SQL 经常出现语法错误。这是因为全参微调强行修改了模型的底层表征，破坏了其通用语言能力。而 Harness-Zero 的蒸馏是“增量式注入”。它冻结大部分基础权重，只在特定的“Harness Head”层（我们设计的一个轻量级 adapter，约 0.3% 参数）上进行训练。这个 Head 层专门负责将模型的通用语言理解，映射到具体的 Harness 契约上。就像给一个熟练的翻译家，额外配备一本《法律文书专用术语手册》，而不是让他重新学习母语。

提示：Harness-Zero 的蒸馏不是“复制粘贴”教师 Agent 的输出，而是“逆向工程”其决策逻辑。我们会在训练时，强制模型在生成工具调用前，先输出一个“契约推理链（Contract Reasoning Trace）”，例如：“用户问‘张三的保单状态’ → 需要调用 policy_status API → 输入参数：customer_id=ZS2024001 → 根据契约，customer_id 必须是字母+数字组合，长度 8-12 位 → 当前输入符合 → 输出 JSON”。这个 trace 不参与最终输出，但作为监督信号，极大提升了模型对契约的理解深度。

3. 核心细节解析：Harness 的构成、蒸馏协议与权重注入机制

3.1 一个完整的 Harness 是什么？它远不止一个 API 文档

在 Harness-Zero 的世界里，一个 Harness 不是一个 URL 或一个 Python 函数，而是一个自包含的、可验证的、多维度的能力包。它由五个核心部分构成，缺一不可：

1. 契约描述（Contract Spec）：这是 Harness 的“宪法”。我们采用 YAML 格式，基于 OpenAPI 3.1 扩展。关键扩展字段包括：

• x-harness-input-semantics: 为每个输入字段添加业务语义标签，如customer_id: {x-harness-semantic: "identity.customer.id", x-harness-constraint: "alphanumeric(8,12)"}
• x-harness-output-schema: 定义输出 JSON 的严格 Schema，支持嵌套和条件分支。
• x-harness-failure-modes: 枚举所有可能的失败类型及其触发条件，如auth_failed: {condition: "token_expired OR invalid_scope"}。

2. 教师 Agent 实现（Teacher Implementation）：一个可执行的、确定性的参考实现。它必须是“纯函数式”的：相同输入，永远产生相同输出（包括失败模式）。我们强烈推荐用 Rust 或 Go 编写，因其内存安全和确定性。Python 实现必须禁用所有随机种子和非确定性库（如time.time()）。

3. 合规性测试套件（Compliance Test Suite）：一组自动化测试用例，覆盖正常路径、边界条件、错误注入。例如，对policy_statusHarness，测试用例必须包括：① 正确 customer_id；② customer_id 长度超限；③ customer_id 包含非法字符；④ 模拟网络超时。每个用例都预设了期望的输出 JSON 和失败模式。

4. 行为指纹（Behavioral Fingerprint）：一个 256-bit 的哈希值，由契约描述、教师实现的源码哈希、以及测试套件的通过率共同生成。这个指纹是 Harness 的唯一 ID，也是蒸馏过程中验证“契约一致性”的黄金标准。如果教师实现更新，指纹改变，所有已蒸馏的模型都会被标记为“过期”，必须重新蒸馏。

5. 权重注入模板（Weight Injection Template）：一个 JSON 文件，定义了如何将 Harness 的行为逻辑，映射到学生模型的特定参数位置。它指定了：① 使用哪个 adapter 层（如harness_head.0）；② 哪些 LoRA rank 用于编码输入约束；③ 哪些 bias 向量用于强化失败模式预测。这个模板是 Harness-Zero 的“编译器”，它把抽象契约，翻译成具体的权重操作。

注意：Harness 的版本管理极其严格。我们禁止任何形式的“向后兼容”。一个 Harness 的主版本号（如v1.2.0）升级，意味着契约描述或失败模式发生了变更，所有依赖它的蒸馏模型必须重建。这看似激进，但正是为了杜绝“隐式耦合”——那种“旧模型还能跑，但结果不对”的线上事故。

3.2 蒸馏协议详解：四阶段渐进式训练，每一步都可验证

Harness-Zero 的蒸馏不是一次性的大模型训练，而是一个精密的四阶段流水线。每个阶段都有明确的退出准则和质量门禁（Quality Gate），任何一个阶段失败，整个流程终止。这保证了最终产出的模型，其 Harness 能力是可验证、可追溯的。

阶段一：契约感知预热（Contract-Aware Warmup）

• 目标：让学生模型初步理解 Harness 契约的语言和结构。
• 方法：冻结模型主体，只训练 Harness Head。输入是 Harness 的契约描述 YAML，目标是让模型生成一个“契约摘要”（如“这是一个查询保单状态的 API，需要 customer_id，返回 JSON”）。
• 退出准则：摘要生成的 BLEU-4 分数 ≥ 0.85，且关键字段（如customer_id,status）的召回率 ≥ 95%。
• 实操心得：这个阶段最容易被忽略，但至关重要。我见过太多团队跳过此步，直接进入行为蒸馏，结果模型对契约的理解流于表面，后续阶段收敛极慢。建议用 200 个不同领域的 Harness（金融、医疗、电商）混合训练，提升泛化性。

阶段二：行为轨迹蒸馏（Behavioral Trace Distillation）

• 目标：教会模型“思考过程”，而不仅是“最终答案”。
• 方法：输入是用户 query（如“查张三的保单”），教师 Agent 输出一个完整的“契约推理链”（见前文提示）。学生模型被要求复现这个推理链。
• 损失函数：L_trace = 0.6 * CE(trace_tokens) + 0.4 * KL(trace_prob_distribution)。CE 确保 token 级别准确，KL 确保概率分布一致（防止模型只记住了模板）。
• 退出准则：推理链中，关键决策节点（如“选择 policy_status API”、“验证 customer_id 格式”）的准确率 ≥ 92%。
• 实操心得：教师 Agent 的推理链必须是“可解释的”，不能是黑盒。我们强制要求所有教师实现，必须在日志中输出完整的 trace。这既是蒸馏数据，也是后期审计的依据。

阶段三：契约合规微调（Contract-Compliant Fine-tuning）

• 目标：让模型的最终输出，100% 符合契约。
• 方法：输入是用户 query，目标是模型直接输出符合契约的 JSON 或命令。损失函数L = α * L_task + β * L_contract开始启用。
• 关键技巧：我们引入了“契约强化采样（Contract-Augmented Sampling）”。在训练 batch 中，强制加入 30% 的“边界样本”（如 customer_id 长度为 7 或 13），并给予L_contract更高的权重（β=2.0）。这迫使模型在边缘情况下，依然坚守契约。
• 退出准则：在合规性测试套件上，所有用例的通过率 ≥ 99.5%，且失败模式预测准确率 ≥ 90%。

阶段四：权重固化与验证（Weight Solidification & Validation）

• 目标：将 Harness Head 的知识，安全、无损地注入到基础模型权重中。
• 方法：不是简单的权重合并，而是采用“梯度投影融合（Gradient Projection Fusion）”。我们计算 Harness Head 在训练过程中，对基础模型各层梯度的贡献方向，并将这些方向性知识，以最小扰动的方式，反向注入到基础权重中。这比传统的 LoRA merge 更鲁棒。
• 验证：用 Harness 的行为指纹，对固化后的模型进行端到端测试。只有指纹完全匹配，才视为成功。
• 实操心得：这一步的硬件要求很高。我们建议在 A100 80GB 上进行，因为需要同时加载基础模型、Harness Head 和验证测试套件。不要试图在消费级显卡上做 full weight solidification，会 OOM。

3.3 “Harness”如何被“蒸馏”进权重？揭秘参数空间的“行为编码”

这是 Harness-Zero 最反直觉，也最具技术深度的部分。很多人以为“蒸馏进权重”就是把插件代码编译成二进制塞进去。完全错误。Harness-Zero 的做法，是在模型的参数空间里，构建一个“行为语义场（Behavioral Semantic Field）”。

想象一下，模型的每一层 Transformer，其 attention head 的权重矩阵，都可以看作一个高维空间中的向量场。传统 SFT 训练，是在这个空间里，为“回答问题”这个任务，划出一条最优路径。而 Harness-Zero 的蒸馏，则是在同一片空间里，为“遵守 policy_status 契约”这个行为，刻下一道永久性的、具有方向性的“引力槽（Gravity Groove）”。

具体来说，我们通过 Harness Head 的训练，发现了几个关键现象：

• 输入约束编码：模型在处理customer_id字段时，特定的几个 attention head（我们称之为Constraint Heads）会表现出强烈的、跨层的协同激活。它们的权重更新，主要集中在对“字母数字组合”和“长度范围”这两个语义的敏感区域。
• 失败模式编码：模型预测auth_failed时，并非简单地输出这个词，而是其 MLP 层的某个子模块（Failure Router）的输出分布，会呈现出独特的、可被线性分类器识别的模式。这个模式，被我们固化为一个小型的、嵌入式的“失败模式判别器”。
• 输出结构编码：模型生成 JSON 时，其 position embedding 的偏置项（bias term），会根据契约中定义的字段顺序，产生微小的、但统计显著的偏移。这个偏移，就是模型“记住”了{"status": "...", "effective_date": "..."}这个结构的物理证据。

因此，“蒸馏进权重”的本质，是通过精心设计的损失函数和训练协议，引导模型的参数，在高维空间中，自发地形成一个稳定的、可复现的、与 Harness 契约一一对应的几何结构。这个结构不是存储在某个特定的参数里，而是弥散在整个网络的权重分布中，就像水的形状由容器决定，但水分子本身并不“知道”容器的形状。这也是为什么 Harness-Zero 蒸馏出的模型，即使被剪枝或量化，其 Harness 能力依然保持惊人鲁棒性的原因——它不是一个“开关”，而是一种“状态”。

4. 实操全流程：从定义一个 Harness 到部署一个 Zero-Dependency 模型

4.1 第一步：定义你的第一个 Harness（以“电商订单查询”为例）

让我们用一个真实场景，走一遍完整流程。假设你要为一家跨境电商公司，蒸馏一个“订单状态实时查询”能力。目标是让一个 1.5B 的 Qwen 模型，能直接生成符合其 ERP 系统 API 规范的 curl 命令。

1. 编写契约描述（harness_order_status.yaml）

openapi: 3.1.0 info: title: Order Status Query Harness version: 1.0.0 x-harness-id: "harness-order-status-v1" paths: /api/v1/orders/{order_id}/status: get: summary: Get real-time order status parameters: - name: order_id in: path required: true schema: type: string x-harness-semantic: "commerce.order.id" x-harness-constraint: "pattern('^[A-Z]{2}\\d{8}$')" # e.g., US12345678 responses: '200': description: Order status object content: application/json: schema: type: object properties: order_id: type: string status: type: string enum: ["pending", "shipped", "delivered", "cancelled"] estimated_delivery: type: string format: date '404': description: Order not found x-harness-failure-mode: "order_not_found" '401': description: Invalid API key x-harness-failure-mode: "auth_failed"

2. 实现教师 Agent（teacher_order.py）

import requests import re def query_order_status(order_id: str) -> dict: # 严格的输入验证，契约的第一道防线 if not re.match(r'^[A-Z]{2}\d{8}$', order_id): return {"error": "order_not_found", "message": "Invalid order_id format"} # 模拟 API 调用 try: response = requests.get( f"https://erp.example.com/api/v1/orders/{order_id}/status", headers={"Authorization": "Bearer xxx"} ) if response.status_code == 200: return response.json() elif response.status_code == 404: return {"error": "order_not_found", "message": "Order does not exist"} else: return {"error": "auth_failed", "message": "API authentication failed"} except requests.exceptions.Timeout: return {"error": "network_timeout", "message": "Request timed out"}

3. 编写合规性测试（test_order.py）

def test_valid_order(): assert teacher_order.query_order_status("US12345678") == { "order_id": "US12345678", "status": "shipped", "estimated_delivery": "2024-06-15" } def test_invalid_format(): result = teacher_order.query_order_status("12345") assert result["error"] == "order_not_found" def test_network_timeout(): # 模拟超时 with patch('requests.get', side_effect=requests.exceptions.Timeout): result = teacher_order.query_order_status("US12345678") assert result["error"] == "network_timeout"

4. 生成行为指纹运行harness-cli fingerprint --spec harness_order_status.yaml --impl teacher_order.py --test test_order.py，得到指纹sha256:abc123...。这个指纹将贯穿整个蒸馏流程。

4.2 第二步：准备学生模型与训练环境

我们选择Qwen1.5-1.8B-Chat作为基础模型。注意，Harness-Zero 对基础模型有明确要求：

• 必须支持 LoRA 微调：我们使用peft库。
• Tokenizer 必须支持 JSON 和特殊符号：Qwen 的 tokenizer 对{,},:等符号处理良好。
• 推理引擎必须支持 custom logits processor：因为我们后续需要在生成时，强制 JSON 格式。

环境准备（requirements.txt）：

transformers==4.41.2 peft==0.10.0 datasets==2.19.1 accelerate==0.30.1 torch==2.3.0+cu121 vllm==0.4.2 harness-zero==0.2.1 # 我们开源的 Harness-Zero 工具链

关键配置（train_config.yaml）：

model_name_or_path: "Qwen/Qwen1.5-1.8B-Chat" harness_spec: "harness_order_status.yaml" teacher_impl: "teacher_order.py" test_suite: "test_order.py" output_dir: "./distilled_qwen_order" # 四阶段训练参数 stages: warmup: num_train_epochs: 1 learning_rate: 1e-4 trace_distill: num_train_epochs: 3 learning_rate: 5e-5 contract_finetune: num_train_epochs: 5 learning_rate: 2e-5 contract_weight: 2.0 solidify: method: "gradient_projection" target_rank: 64

4.3 第三步：执行四阶段蒸馏训练（附关键日志与参数解读）

阶段一：契约感知预热

harness-zero train --config train_config.yaml --stage warmup

• 日志关键指标：INFO: Contract summary BLEU-4: 0.872 | customer_id recall: 0.98
• 解读：模型已经能准确概括契约的核心要素。如果 BLEU-4 < 0.8，说明契约描述可能过于晦涩，需要重写。

阶段二：行为轨迹蒸馏

harness-zero train --config train_config.yaml --stage trace_distill

• 日志关键指标：INFO: Trace accuracy (API selection): 0.94 | Input validation step: 0.93
• 解读：模型学会了“先选 API，再验输入”的思维链。这是防止幻觉的关键。

阶段三：契约合规微调

harness-zero train --config train_config.yaml --stage contract_finetune

• 日志关键指标：INFO: Compliance test pass rate: 99.7% | Failure mode accuracy: 0.91
• 解读：模型在 1000 个测试用例中，只有 3 个失败，且失败模式预测正确。达到上线标准。

阶段四：权重固化

harness-zero solidify --config train_config.yaml --model ./distilled_qwen_order/checkpoint-final

• 输出：生成./distilled_qwen_order/final_model.safetensors，大小比原始模型增加约 12MB（主要是 Harness Head 的权重）。
• 验证：harness-zero verify --model ./distilled_qwen_order/final_model.safetensors --fingerprint sha256:abc123...返回PASSED。

4.4 第四步：部署与推理——真正的 Zero-Dependency

部署不再需要任何框架。你只需要一个支持 vLLM 的服务：

# 启动 vLLM 服务 python -m vllm.entrypoints.api_server \ --model ./distilled_qwen_order/final_model.safetensors \ --tokenizer Qwen/Qwen1.5-1.8B-Chat \ --dtype half \ --tensor-parallel-size 1 \ --port 8000

推理示例（curl）：

curl http://localhost:8000/generate \ -H "Content-Type: application/json" \ -d '{ "prompt": "用户ID是US12345678，查一下这个订单的状态。", "sampling_params": { "temperature": 0.0, "max_tokens": 256 } }'

预期响应：

{ "text": "curl -X GET 'https://erp.example.com/api/v1/orders/US12345678/status' -H 'Authorization: Bearer xxx'" }

注意：这个响应是模型权重直接生成的，没有经过任何外部调度器。如果你的 ERP 系统 API 发生变更，你不需要修改任何服务代码，只需要更新 Harness 的契约描述和教师实现，然后重新蒸馏模型。这就是 Harness-Zero 的“能力原子化”威力。

5. 常见问题与独家避坑指南：来自 7 个落地项目的血泪经验

5.1 “Harness-Zero 蒸馏出的模型，为什么有时会生成不符合契约的 JSON？”

这是最常被问到的问题。答案往往不在模型本身，而在契约描述的完备性。我们总结了三个高频陷阱：

陷阱一：隐式依赖未声明。例如，一个查询天气的 Harness，其契约描述里写了city_name: string，但没写city_name必须是“中国境内城市名”。教师 Agent 内部有一个白名单校验，但这个约束没写进x-harness-constraint。结果，蒸馏后的模型在面对city_name="New York"时，会生成一个看似合法但实际无效的请求。解决方案：在契约描述中，用x-harness-constraint明确写出所有业务规则，哪怕它看起来“显而易见”。我们的标准是：契约必须能让一个完全不懂业务的程序员，仅凭 YAML 文件，就能写出正确的调用代码。

陷阱二：失败模式枚举不全。教师 Agent 可能抛出一个未在x-harness-failure-modes中定义的错误，比如rate_limit_exceeded。当这个错误发生时，蒸馏模型无法学习到正确的应对策略，就会陷入“生成随机 JSON”的状态。解决方案：在编写教师 Agent 时，强制所有异常都必须映射到预定义的 failure mode。我们用一个全局的HARNESS_ERROR_MAP字典来做这件事：

HARNESS_ERROR_MAP = { requests.exceptions.ConnectionError: "network_unavailable", requests.exceptions.Timeout: "network_timeout", ValueError: "invalid_input", # ... 所有其他可能的异常 }

陷阱三：测试套件覆盖不足。一个 Harness 的测试用例，如果只覆盖了 200 个正常样本，而没有覆盖 1000 个边界和错误样本，那么蒸馏模型在生产环境中，遇到第一个没见过的错误，就会崩。解决方案：我们要求测试套件的“错误覆盖率”必须 ≥ 80%。即，错误用例数量 / 总用例数量 ≥ 0.8。这听起来苛刻，但正是 Harness-Zero “零信任”哲学的体现——我们不相信模型能泛化，只相信它被训练过的数据。

5.2 “能否在一个模型里蒸馏多个 Harness？比如同时有订单查询和退货申请？”

完全可以，而且这是 Harness-Zero 的核心优势之一。但我们强烈反对“把所有 Harness 塞进一个大模型”的粗暴做法。正确的策略是分层蒸馏（Hierarchical Distillation）。

第一层：领域级 Harness。例如，harness-commerce-v1，它不直接对应某个 API，而是定义了“电商领域”的通用契约：order_id的格式、sku_code的校验规则、refund_reason的枚举列表等。这一层蒸馏的目标，是让学生模型获得“电商语感”。

第二层：功能级 Harness。在领域级 Harness 的基础上，再蒸馏harness-order-status和harness-return-request。由于第一层已经建立了领域共识，第二层的训练会快得多，且更稳定。

实操技巧：我们用一个“Harness 组合器（Harness Combiner）”工具，自动将多个 Harness 的契约描述，合并成一个统一的、无冲突的超级契约。它会检测字段命名冲突（如两个 Harness 都用了id字段），并自动添加命名空间前缀（order_id,return_id）。这个工具生成的超级契约，就是第二层蒸馏的输入。

5.3 “Harness-Zero 和传统模型蒸馏（如 TinyBERT）有什么本质区别？”**

这个问题触及了技术本质。传统知识蒸馏（KD）的目标是保真度（Fidelity）：学生模型的输出，要尽可能接近教师模型的输出（logits 或概率分布）。而 Harness-Zero 的目标是契约遵从度（Compliance）：学生模型的输出，要 100% 符合一个外部定义的、形式化的契约。

这导致了三个根本性差异：