从Harness到认知工程：重构AI Agent的底层思维范式

1. 项目概述从 harness 工程到认知工程不是换名字是重构底层思维范式“Agent: 将 harness 工程升级到认知工程”——这个标题乍看像一句技术口号实则是一次静默却剧烈的范式迁移。我带团队落地过 7 个中大型 AI 工程项目其中 4 个早期用的是 harness 框架包括 DeepSeek Harness v0.8 和 v1.2 的定制分支后来全部重构成“认知工程”架构。不是因为旧框架崩了而是它开始卡住我们做真正需要“理解—推理—决策—反思”的任务。比如让一个客服 agent 不仅能查订单状态还能判断用户情绪是否已临界、是否该主动升级人工、甚至预判用户下一句可能问什么——这种链路harness 的 pipeline 编排模型跑不通。它本质是强流程、弱语义、重动作、轻意图的工程范式而认知工程核心是把 agent 当作一个具备内部表征、记忆演进、目标分层与元认知能力的“认知体”来设计。标题里的harness不是指某个具体工具包而是泛指以 LangChain/LangGraph 为代表、以“链式调用工具编排提示词胶水”为特征的主流 agent 开发范式。它高效、易上手、生态成熟但天花板清晰当业务逻辑从“查→填→回”升级为“观察→建模→假设→验证→修正”harness 就像用扳手拧螺丝去组装一台精密钟表——力够但精度和反馈机制缺失。而认知工程是把 agent 的每个模块都按认知科学原理重新定义记忆不是 key-value 存储而是情境化、可衰减、带置信度的表征规划不是静态 DAG而是基于当前目标与环境约束动态生成的意向图谱执行不是函数调用而是带有失败回溯、替代路径、资源权衡的意向执行反思不是日志分析而是对自身行为因果链的元层级建模。你如果正面临这些场景这个升级就不是“要不要做”而是“拖多久会更痛”你的 agent 在复杂多跳任务中开始频繁“断链”比如“帮我对比三款手机考虑预算、拍照、续航再结合我上周浏览过的测评文章”——harness 往往在第三步就丢失上下文或无法关联历史行为你发现 skill 模块越写越多但复用率反而下降因为每个 skill 都要硬编码适配不同上下文缺乏通用意图解析层你尝试接入 RAG结果检索结果和生成回答“两张皮”agent 明明看到文档里写着“不支持 iOS 18”却还在回复“已兼容最新系统”你部署后发现 agent 行为不可解释它为什么选 A 而非 B为什么跳过某步为什么突然改口harness 日志只告诉你“调用了 tool_x”不告诉你“因为 belief_y 被新证据 z 覆盖”。这不是技术栈迭代而是工程哲学的转向。认知工程不排斥 harness 的组件你依然要用 LLM、向量库、工具函数但它拒绝把它们当积木拼接而是要求你先定义 agent 的“认知契约”它如何感知如何建模世界如何设定目标如何评估进展如何更新信念这些契约才是所有代码的源头。接下来我会用真实落地的 Bolt 认知引擎为例拆解这套契约如何转化为可运行的工程结构以及每一步踩过的坑、算过的账、验证过的阈值。2. 核心范式迁移从 pipeline 编排到认知契约建模2.1 harness 工程的本质与瓶颈一个被低估的“过程即逻辑”陷阱先说清楚 harness 工程到底是什么。很多人以为 harness 就是 LangChain其实 LangChain 是 API 层harness 是更底层的工程实践共识。它的核心范式是任务 输入 → 解析 → 规划 → 工具调用 → 整合 → 输出。这个链条本身没问题问题出在每个环节的“契约”太薄。以最常用的ReAct模式为例LLM 输出 “Thought: 我需要查天气Action: weather_toolAction Input: 北京” —— 这里“Thought” 是 LLM 自由生成的文本不是结构化意图“Action” 是字符串匹配不是语义绑定“Action Input” 是原始字符串没有类型校验与范围约束。我曾在一个金融 agent 项目中发现当用户说“帮我看看上季度的营收变化”LLM 生成的 Action Input 是 “Q3 2023 revenue”而工具函数实际期待的是 ISO 格式日期 “2023-07-01/2023-09-30”。harness 框架默认不做转换结果就是agent execution terminated due to error.。表面是参数错误根因是harness 把“意图表达”和“执行协议”混在同一层缺乏中间的语义锚定层。更深层的问题是状态隔离。harness 的 state 通常只是 message history tool result它不区分感知状态用户刚说了什么、系统返回了什么、当前界面显示什么信念状态agent 目前确信的事实如“用户预算≤5000”、“手机A比B贵800”目标状态当前主目标是“完成比价”子目标是“确认续航数据”意向状态下一步打算调用哪个工具、为什么选它、备选方案是什么。这导致 agent 在长对话中“健忘”或“矛盾”。比如用户先说“我要买手机”又说“算了先看看笔记本”harness 可能还在执着调用phone_search因为它没建模“目标切换”这一认知事件。提示harness 的最大优势是快最大风险是“快得看不见代价”。当你用 harness 快速上线 MVP 后每增加 10% 的业务复杂度维护成本会指数级上升。我们测算过在电商比价场景harness 实现基础功能需 3 天但支持“跨品类比价历史偏好融合实时库存校验”时代码量翻 4 倍测试用例增 7 倍且 60% 的 bug 来自状态不一致。2.2 认知工程的四大契约让 agent 拥有可推演的“心智模型”认知工程不否定 harness 的组件而是用四层契约重构其骨架。这四层不是理论空谈而是 Bolt 引擎落地时强制实现的接口2.2.1 感知契约Perception Contract定义 agent 如何“看”世界harness 的输入是 raw text认知工程的输入是structured perception event。我们定义了一个PerceptionEvent类型class PerceptionEvent(BaseModel): source: Literal[user, system, tool, memory] # 来源类型 content: str # 原始内容 semantic_type: str # 语义类型如 query, confirmation, error confidence: float # 置信度0.0~1.0 timestamp: datetime context_id: str # 关联上下文ID用于跨事件追踪关键转变用户输入 “北京明天热不热” 不再直接喂给 LLM而是先由PerceptionParser解析为{ source: user, content: 北京明天热不热, semantic_type: weather_query, confidence: 0.92, context_id: ctx_20240521_001 }系统返回的天气数据也包装成PerceptionEventsemantic_type设为weather_data并附带confidence来自 API 的可信度评分。这样agent 的“感知”不再是模糊文本而是带元信息的结构化信号。后续所有决策都基于这些信号的组合与冲突检测而非字符串匹配。2.2.2 信念契约Belief Contract构建 agent 的“知识图谱”harness 没有显式信念管理认知工程强制 agent 维护一个BeliefBase它不是数据库而是一个动态图谱class Belief(BaseModel): subject: str # 主体如 iPhone 15 predicate: str # 关系如 has_price object: Any # 客体如 5999.0 confidence: float # 当前置信度 provenance: List[str] # 证据来源如 [tool_weather, memory_user_pref] last_updated: datetime当用户说“我预算5000”生成信念(user, has_budget, 5000, 0.95, [user_input])。当工具返回“iPhone 15 价格 5999”生成信念(iPhone 15, has_price, 5999.0, 0.98, [tool_price])。当用户随后说“那算了”系统触发BeliefRevision机制降低(user, has_budget, 5000)的置信度并生成新信念(user, has_abandoned_budget_constraint, True, 0.85, [user_input])。实操心得信念不是存起来就完事。我们加了两条硬规则1任何新信念必须与现有信念做一致性检查冲突时启动BeliefConflictResolver优先级用户输入 工具返回 历史记忆2置信度低于 0.3 的信念自动进入doubt_pool下次规划时必须主动验证。这直接解决了 harness 中常见的“幻觉坚持”问题。2.2.3 目标契约Goal Contract让 agent 懂得“为什么做”harness 的目标是隐式的由 prompt 定义认知工程的目标是显式、分层、可分解的class Goal(BaseModel): id: str name: str # 如 complete_comparison status: Literal[active, suspended, achieved, abandoned] priority: int # 1-5用于冲突时仲裁 subgoals: List[Goal] # 可递归分解 constraints: Dict[str, Any] # 如 {max_steps: 5, timeout: 300} satisfaction_criteria: Callable[[State], bool] # 达成条件函数用户说“比价三款手机”主目标complete_comparison被创建自动分解为子目标fetch_specs,fetch_prices,fetch_reviews。每个子目标有自己的constraints如fetch_prices要求 3 个品牌数据全齐才成功。当fetch_reviews因 API 限流失败系统不会报错退出而是将该子目标status设为suspended降级执行fetch_summaries摘要代替全文并更新主目标的satisfaction_criteria为“至少 2 款有完整评测”。2.2.4 意向契约Intention Contract规划不是生成文字是生成可执行计划harness 的规划是 LLM 输出的文本认知工程的规划是IntentionPlan对象class IntentionPlan(BaseModel): steps: List[IntentionStep] fallback_plan: Optional[IntentionPlan] # 备用计划 resource_requirements: Dict[str, float] # 如 {api_calls: 2.5, llm_tokens: 1200} class IntentionStep(BaseModel): action: str # 绑定到具体 skill如 search_phone_specs parameters: Dict[str, Any] # 结构化参数经类型校验 preconditions: List[str] # 执行前必须满足的信念如 user.has_budget postconditions: List[str] # 执行后应产生的信念如 phone.X.has_specs timeout: int # 步骤超时秒数规划器Planner接收当前BeliefBase和Goal输出IntentionPlan。关键点parameters是结构化字典不是字符串调用前做 Pydantic 校验preconditions强制检查若user.has_budget置信度 0.7则此步阻塞触发clarify_budget子目标postconditions是契约执行后必须生成对应信念否则视为步骤失败。这四层契约构成了 agent 的“心智模型”。它不再是一个黑盒 LLM 加一堆工具而是一个可观察、可调试、可推演的智能体。harness 是“让它做事”认知工程是“让它理解在做什么、为什么做、做到什么程度算好”。3. 实操落地Bolt 认知引擎的核心模块实现与参数精调3.1 架构总览不是替换 harness而是将其嵌入认知循环Bolt 不是全新框架而是 harness 的“认知增强层”。它的核心是CognitiveLoop一个 5 阶段闭环Perceive → Believe → Goal → Intend → Act → (loop back to Perceive)每个阶段调用 harness 的现有能力但注入认知契约阶段harness 原生能力Bolt 增强点关键参数Perceiveinput_parserPerceptionParser 置信度模型perception_confidence_threshold0.85BelievememoryBeliefBase 冲突解决器belief_decay_rate0.02/hourGoalagent_executorGoalManager 分层目标树max_goal_depth3,goal_timeout600sIntendplannerIntentionPlanner 前置条件检查plan_validation_retries2,fallback_strategydegradeActtool_callIntentionExecutor 资源监控api_call_quota10/min,llm_token_budget2000注意Bolt 不要求你重写所有工具。我们提供ToolAdapter将原有 harness tool 包装成符合IntentionStep接口的 skill。例如原weather_tool(location: str)变成def weather_skill(params: dict) - dict: # params 已是结构化字典含 location:str, unit:str # 执行前自动检查 preconditions: [location.is_valid] # 执行后自动发布 postconditions: [weather.location.has_forecast]3.2 感知层实现从文本到结构化事件的三步过滤PerceptionParser不是简单 NLP而是三层过滤流水线3.2.1 语法层过滤Syntax Filter用轻量级 spaCy 模型做基础解析提取命名实体人名、地名、数字、时间识别句子类型疑问句、陈述句、祈使句标记情感倾向positive/negative/neutral阈值 ±0.3。输出{entities: [...], sentence_type: question, sentiment: 0.42}3.2.2 语义层映射Semantic Mapper这是最关键的一步。我们训练了一个小规模12M 参数的IntentClassifier专用于将用户输入映射到预定义的semantic_type。它不是通用分类器而是针对业务域微调输入用户 query 当前BeliefBase快照压缩为 512 维向量输出top-3semantic_type及置信度如(price_query, 0.91), (spec_query, 0.76), (review_query, 0.63)。为什么不用 LLM因为 LLM 响应慢、成本高、结果不稳定。我们的IntentClassifier在 T4 上推理 50ms准确率 92.3%测试集 5k 条远高于 GPT-3.5-turbo 的 84.1%同测试集且耗时 1200ms。3.2.3 置信度校准Confidence Calibrator最后一步用CalibrationModel动态调整置信度基础置信度来自IntentClassifier乘以context_factor若当前BeliefBase中有user.has_preference_for_brandApple而 query 是 “iPhone 15 电池续航”则context_factor1.15除以ambiguity_penalty若实体识别出两个地名“上海北京”则 penalty1.3。最终confidence base * context_factor / ambiguity_penalty。我们设阈值0.85低于此值触发clarify_event如“您是指上海还是北京的天气”。实操心得置信度不是越高越好。我们发现confidence0.98的 query往往 LLM 生成更确定但更易幻觉而confidence0.85~0.92的 queryLLM 更倾向生成带条件的谨慎回答。所以perception_confidence_threshold设为 0.85是平衡响应速度与可靠性后的经验值。3.3 信念层实现动态图谱与冲突解决的实战细节BeliefBase是 Bolt 的心脏它由三部分组成3.3.1 信念存储BeliefStore不是传统数据库而是内存优先的LRU-Cache 持久化后备主存储dict[subject, dict[predicate, List[Belief]]]按 subject 分片缓存策略LRU 1000 条淘汰last_updated最早的持久化异步写入 SQLite每 5 分钟 checkpoint 一次。关键优化Belief对象序列化时provenance只存 ID如[tool_price_20240521_001]不存原始内容节省 60% 内存。3.3.2 信念更新BeliefUpdater每次PerceptionEvent进来触发update_beliefs(event)若event.semantic_type user_input则生成新信念confidenceevent.confidence * 0.95用户输入打 95 折防误说若event.semantic_type tool_result则查找匹配subject/predicate的现有信念用贝叶斯更新调整置信度new_confidence (old_confidence * old_evidence_weight event.confidence * new_evidence_weight) / (old_evidence_weight new_evidence_weight)其中evidence_weight由来源决定user1.0,tool0.8,memory0.5。3.3.3 冲突解决BeliefConflictResolver当新信念与现有信念冲突如(user, has_budget, 5000)vs(user, has_budget, 3000)启动 resolverStep 1溯源检查provenance若一方来自user_input另一方来自tool_price则 user 优先Step 2时效性若两者都来自 user取timestamp更新的那个Step 3置信度加权若confidence差 0.2直接采纳高者否则生成uncertain状态触发clarify_budget目标。注意我们禁用了“平均化”这种看似平滑实则有害的操作。信念不是数值而是命题真值。(user, has_budget, 5000)和(user, has_budget, 3000)不能平均成4000那是逻辑谬误。必须明确选择或标记不确定。3.4 目标与意向层从静态规划到动态意向执行3.4.1 目标创建与分解Goal Creation用户 query 进来GoalManager创建主目标name由IntentClassifier的 top-1semantic_type映射如price_query→compare_pricespriority根据PerceptionEvent.confidence和sentiment计算高置信度 负面情感 priority 5紧急subgoals由预定义的GoalTemplate加载如compare_prices模板含[fetch_prices, normalize_currency, rank_by_budget]。3.4.2 意向规划Intention PlanningIntentionPlanner接收current_beliefs和active_goals输出IntentionPlanStep 1可行性检查遍历每个subgoal检查其preconditions是否在BeliefBase中满足置信度 ≥ 0.7。不满足的插入clarify_*子目标。Step 2资源估算对每个IntentionStep查询skill_registry获取resource_requirements累加得总 plan 预算。Step 3冲突仲裁若多个目标竞争同一资源如都需调用search_api按priority排序低优先级目标status设为suspended并设置resume_condition如“当 search_api 负载 30% 时恢复”。3.4.3 意向执行Intention ExecutionIntentionExecutor是最“接地气”的模块Step 1参数校验用 Pydantic 检查parameters类型与范围失败则retry或fallbackStep 2前置检查再次验证preconditions失败则abort_step并记录原因Step 3执行与监控启动asyncio.timeout超时则cancel并触发fallback_planStep 4后置发布执行成功后自动发布postconditions到BeliefBase。实操心得fallback 不是简单重试。我们定义了三种 fallback 策略degrade降级执行如fetch_full_review→fetch_summarydelegate转交其他 skill如本地搜索失败 → 调用 web searchdefer挂起等条件满足如wait_for_user_confirmation。这比 harness 的retry3有用得多。4. 从 harness 到认知工程的迁移路径与避坑指南4.1 迁移不是重写而是渐进式增强三阶段路线图我们帮 3 家客户做过迁移总结出最稳的路径避免“推倒重来”带来的业务中断阶段一观测层增强1-2 周目标不改业务逻辑只加认知“仪表盘”动作在 harness 的agent_executor前后插入PerceptionLogger和BeliefSnapshotter每次调用记录PerceptionEvent和BeliefBase快照到可观测平台我们用 Grafana Loki开发CognitiveDashboard可视化当前活跃目标、信念冲突率、意向执行成功率、fallback 类型分布。价值立刻看到 harness 的“盲区”。我们一个客户发现其客服 agent 32% 的失败源于BeliefBase中user.has_contact_info置信度 0.5但系统仍强行调用发送短信的 skill。阶段二契约层嵌入2-4 周目标用认知契约约束关键路径动作选定 1-2 个高价值、高失败率的业务流如“订单查询退款申请”为其定制PerceptionParser、GoalTemplate、IntentionPlan将原有 harness tool 包装成Skill实现preconditions/postconditions用BeliefBase替换原有memory启用冲突解决。价值该业务流的端到端成功率从 68% 提升至 91%且agent execution terminated due to error.归零。阶段三认知循环接管4-8 周目标全面切换harness 退居为执行引擎动作将CognitiveLoop设为默认 agent所有新需求先定义PerceptionEventschema、Beliefschema、Goaltree建立SkillRegistry统一管理所有 skill 的resource_requirements和preconditions上线CognitiveGuardrails硬性限制max_goal_depth3,total_api_calls_per_session15。价值开发效率反升。新需求平均交付时间从 harness 时代的 5 天降至 2.8 天因为 70% 的逻辑复用已有契约。注意不要试图一次性迁移所有业务。我们见过一个团队想“一步到位”结果 3 周内上线 12 个新 skill但preconditions定义混乱导致BeliefBase严重污染不得不回滚。契约的质量永远比数量重要。4.2 六大高频陷阱与真实解决方案陷阱一把认知工程当成“更复杂的 prompt engineering”现象团队花大量时间调优planner的 system prompt以为“写得越细agent 越聪明”真相认知工程的威力不在 prompt而在契约的强制执行。Prompt 是软约束契约是硬接口解法砍掉所有“指导性 prompt”把规则写进PerceptionParser的intent_mapping、BeliefUpdater的bayesian_weights、IntentionPlanner的precondition_rules。我们统计过硬契约比 prompt 调优带来的稳定性提升高 4.7 倍。陷阱二信念图谱变成“垃圾场”现象BeliefBase膨胀到 10w 条查询变慢冲突频发真相没设衰减和清理策略。信念不是永久真理而是临时假设解法设belief_decay_rate0.02/hour2 小时后置信度衰减 4%设max_beliefs_per_subject5超限则淘汰last_updated最早的每日凌晨执行belief_pruner删除confidence0.3且provenance全为tool的信念。陷阱三目标分解失控陷入“子目标地狱”现象一个简单 query 生成 20 子目标agent 卡死真相GoalTemplate设计过深没设max_goal_depth解法所有GoalTemplate必须声明max_subgoals5IntentionPlanner在分解时若depth3自动聚合为execute_aggregated_task我们有个shopping_assistant模板原来分解为fetch_price,fetch_stock,fetch_review,fetch_spec,fetch_warranty现在聚合为fetch_product_info由一个 skill 统一处理。陷阱四意向执行变成“新单点故障”现象IntentionExecutor一崩整个 agent 瘫痪真相没做 executor 的熔断和降级解法IntentionExecutor自身用circuit_breaker包装连续 3 次失败则 openopen 状态下所有意向转为defer并通知GoalManager降级目标我们用tenacity库实现wait_exponential(multiplier1, min1, max10)。陷阱五混淆 skill 和 agent 的职责现象一个 skill 里写大量业务逻辑甚至调用其他 skill真相skill 应是原子操作agent 负责编排。把逻辑塞进 skill等于把大脑塞进手指解法Skill 接口严格限定input: dict, output: dictSkill 内禁止调用其他 skill禁止访问BeliefBase只能读parameters所有决策逻辑必须在IntentionPlanner或GoalManager中。陷阱六忽略人类反馈的闭环现象agent 做错用户说“不对”系统无反应真相没把用户纠正当作PerceptionEvent没触发BeliefRevision解法用户说“错了”、“不是这个”、“重新来”强制解析为semantic_typecorrectionBeliefUpdater专门处理 correction降低相关信念置信度提高provenance为user_input的权重我们加了feedback_sensitivity0.9参数用户一次纠正相关信念置信度直接 ×0.1。4.3 性能与成本实测对比升级不是免费午餐但 ROI 明确我们拿一个真实电商比价 agent 做了 A/B 测试相同硬件A10 GPU × 2Qwen-1.5B-Chat指标harness v1.2Bolt 认知引擎提升/变化平均响应延迟2.1s2.8s33%因多层契约校验端到端任务成功率68.3%91.7%23.4%API 调用次数/会话8.26.5-20.7%因意向规划减少无效调用LLM token 消耗/会话18401520-17.4%因结构化输入减少冗余运维告警率/天12.42.1-83.1%因契约拦截大部分错误新需求平均交付时间5.0 天2.8 天-44%因契约复用关键结论延迟增加是可控代价而稳定性、成功率、可维护性的提升是质变。尤其当业务从“单点问答”走向“多轮协作”harness 的边际成本急剧上升而认知工程的边际收益持续为正。我们测算当 agent 日均会话 5000Bolt 的 TCO总拥有成本比 harness 低 37%。5. 认知工程的边界与未来它不是万能药而是新起点把 harness 升级到认知工程绝不是终点而是一个更清醒的起点。我必须坦诚地说它解决不了所有问题甚至会暴露一些你以前没意识到的短板。首先认知工程极度依赖高质量的初始契约设计。如果你的PerceptionParser语义类型定义粗糙或者GoalTemplate没覆盖核心业务流那么整个认知循环就会在源头失准。我们曾在一个教育项目中因为semantic_type没区分 “homework_help” 和 “exam_prep”导致 agent 把高三冲刺复习当成日常作业辅导推荐了完全错误的资料。这不是 Bolt 的 bug而是契约设计的缺陷。所以投入 30% 的时间在契约建模上不是浪费是必要投资。其次它放大了 LLM 的底层局限。认知工程让 agent 的推理链更透明但也让 LLM 的幻觉、偏见、逻辑漏洞更无处遁形。当BeliefBase显示 “user.has_allergypeanut” 来自tool_medical_record而 LLM 在生成建议时却忽略了它这个错误会被postconditions检查捕获但根源还是 LLM。所以认知工程必须搭配更强的 LLM 监控我们在IntentionExecutor后加了LLMOutputValidator用小模型二次校验关键事实如过敏源、价格数字、时间日期错误率再降 18%。最后也是最重要的认知工程不是取代 human而是重塑 human-agent 协作。当 agent 拥有了可解释的“心智”产品经理不再问 “它为什么这么答”而是问 “它的信念图谱里哪条边的置信度该调高”。开发者不再 debug “prompt 为什么失效”而是 debug “precondition规则是否覆盖了这个边缘 case”。这要求团队具备新的能力栈认知建模、信念