企业官网建设流程全解析

1. 这不是一本“理论手册”，而是一份AI Native团队每天在用的作战地图

“AI Native 团队完整开发落地手册”——这标题里没有一个虚词，每个字都踩在当下工程一线的真实痛点上。我带过三支从0搭建AI产品线的团队，经历过用LangChain硬凑Agent、被Claude API限流卡在上线前夜、在生产环境里追查agent memory泄漏导致的token爆炸、也亲手重写过五版eval pipeline才让业务方真正信服“这个模型真的比上个版本好”。所谓AI Native，不是把LLM API调通就叫Native，而是整个SDLC（软件开发生命周期）的肌肉记忆都要重练：需求怎么拆？PRD里要不要写prompt版本号？测试用例里该不该包含对抗样本？上线后监控指标除了QPS和延迟，还得盯住cost-per-action和tool-call-failure-rate。这不是加个插件就能解决的事，是组织、流程、工具链、甚至工程师脑回路的系统性迁移。手册里写的每一条，都是我在晨会白板上画过、在Git commit message里骂过、在oncall值班时修过的。它不教你怎么调用Anthropic的API——那官网文档写得比谁都清楚；它只告诉你，当你的Agent在凌晨三点因为一个未处理的tool_use超时而雪崩时，你该先看哪三行日志、该立刻熔断哪个skill、以及为什么下次设计时要把timeout从30秒改成带指数退避的8秒基线+2秒增量。适合两类人：一类是技术负责人，正被老板追问“AI项目ROI怎么算”，另一类是刚转岗的工程师，手头拿着Dify文档却不知道第一行代码该写在哪个module里。它不承诺“速成”，但能让你少走六个月弯路。

2. 为什么必须重构SDLC？——从“写代码”到“编排智能体”的范式迁移

2.1 传统SDLC在AI场景下的四重失效

传统软件开发的SDLC像一条精密流水线：需求→设计→编码→测试→部署→运维。但当核心逻辑从确定性代码变成概率性推理时，这条线就处处卡顿。我拿去年一个真实电商客服Agent项目举例——它要自动处理“订单未发货但用户要求退款”的case。按传统流程：

• 需求阶段：产品经理写PRD，明确“若订单状态=待发货且用户诉求=退款，则触发退款申请+补偿券发放”。逻辑清晰，边界明确。
• 开发阶段：工程师写Java Service，调用订单/券中心API，事务控制严格，单元测试覆盖率92%。
• 测试阶段：QA跑Postman用例，覆盖正常路径、库存不足、网络超时等分支。

但换成AI Native方案后，问题来了：

1. 需求不可穷举：用户原话可能是“我等不及了，钱退回来吧”或“你们是不是把货弄丢了？我要退款！”，语义千变万化，PRD里那句“用户诉求=退款”根本无法覆盖。我们最初用规则引擎兜底，结果发现37%的退款请求因表述模糊被漏判，人工介入率飙升。

2. 设计失去确定性：工程师不再写if-else，而是设计system prompt、few-shot examples、tool schema。但prompt改一个标点，模型输出可能从“已为您申请退款”变成“请提供订单号”，这种变化无法用UML图表达，更没法做静态代码分析。

3. 测试维度爆炸：传统测试关注“输入A→输出B”，AI测试得覆盖：

   • 语义鲁棒性：同义句“我不想等了”vs“不发货就退钱”是否触发同一action；
   • 工具调用可靠性：当退款API返回503时，Agent是重试、降级还是转人工；
   • 成本敏感性：一次对话调用3次Claude Sonnet vs 1次Opus，成本差4倍，但业务效果只提升2%。

4. 运维监控失焦：传统监控看CPU、内存、HTTP 5xx。AI服务得盯：

   • tool_call_failure_rate > 15%（说明tool schema与模型理解错位）；
   • avg_tokens_per_action > 2000（提示prompt冗余或memory管理失控）；
   • human_handoff_rate（暴露Agent能力边界，需反哺训练数据）。

提示：别试图用传统CI/CD套壳AI流程。我们试过把LangChain chain塞进Jenkins pipeline，结果每次model update都得手动改pipeline脚本，两周迭代一次变成两个月。真正的AI Native SDLC，必须让“模型版本”“prompt版本”“tool schema版本”“eval dataset版本”四者联动，且能原子化发布。

2.2 AI Native SDLC的五大支柱重构

我们最终落地的框架，不是推倒重来，而是对原有SDLC进行靶向增强。核心是建立五个新支柱，每个支柱对应一个传统环节的升级：

这个框架不是理论空想。我们用它把Agent项目平均交付周期从14周压缩到6周，线上故障率下降68%。关键在于，它让每个角色都有明确抓手：产品经理用三维建模表对齐需求，工程师在Prompt Registry里提交PR，QA用DeepEval跑回归测试集，SRE盯着tool_call_failure_rate告警。所有人不再争论“模型好不好”，而是聚焦“这个版本在退款场景的cost_per_action是否低于阈值”。

2.3 Anthropic生态带来的特殊挑战与应对

Anthropic模型（尤其是Claude系列）在AI Native实践中既是利器也是陷阱。其“Constitutional AI”设计理念带来独特优势，但也引入新问题。我们踩过的坑值得深挖：

• 优势侧：Claude对长上下文（200K tokens）和结构化输出（XML tag）的支持极佳。我们做合同审核Agent时，直接喂入整份PDF解析文本（约15万字符），Claude能精准定位“违约金条款第3.2条”，而GPT-4常在长文中丢失位置信息。这让我们省去复杂的chunking+retrieval设计。

• 陷阱侧：

  1. Gateway Model Route错误："doesn't look like an anthropic model: expected a gateway model route"——这是Anthropic服务端路由策略变更导致的。根本原因不是客户端代码错，而是API endpoint未同步更新。我们解决方案：在Tool Gateway层封装endpoint discovery机制，定期调用/v1/models接口刷新可用模型列表，避免硬编码。
  2. 连接失败："unable to connect to anthropic services"常因DNS缓存或TLS版本不兼容。实测发现，Java 8默认TLS 1.2不被Anthropic新集群支持，升级到Java 17后解决。但更稳妥做法是在Gateway层添加connection pool健康检查，失败时自动fallback到备用region（如us-east-1 → us-west-2）。
  3. Token计算偏差：Anthropic的token计费方式与OpenAI不同（按input+output tokens分别计费），且count_tokensAPI返回值与实际扣费有±3%误差。我们建立token预估模型：用历史10万次调用数据训练XGBoost，输入prompt长度、tool schema复杂度、预期输出长度，预测误差<0.8%。这让我们能精确控制单次对话成本预算。

注意：别迷信“Anthropic上市”带来的技术光环。我们做过对比测试：在相同硬件、相同prompt下，Claude Opus的推理速度比GPT-4 Turbo慢40%，但幻觉率低22%。选择模型不是看谁更“大”，而是看业务场景的优先级——要速度选GPT，要安全选Claude，要长文本选Claude，要生态工具链选Llama 3。

3. 核心模块拆解：从Orchestrator到Eval，每个齿轮怎么咬合

3.1 Orchestrator：决策中枢的轻量化设计哲学

AI Native架构里，Orchestrator是大脑，但绝不能成为瓶颈。我们见过太多团队用LangChain或LlamaIndex堆出臃肿的Orchestrator，结果一个简单问答要经过7层抽象，latency飙到2.3秒。我们的原则是：Orchestrator只做三件事——状态管理、决策路由、错误熔断，其余全下沉。

以退款Agent为例，Orchestrator的伪代码只有21行：

// 状态机核心逻辑（Rust实现） fn orchestrate(state: &mut AgentState) -> Result<Action, OrchestratorError> { match state.phase { Phase::IntentRecognition => { // 调用intent classifier（轻量级微服务） let intent = classify_intent(&state.user_input)?; state.intent = intent; Ok(Action::RouteToSkill(Skill::RefundInitiate)) } Phase::RefundExecution => { // 检查tool调用结果 if state.tool_result.is_err() { return Err(OrchestratorError::ToolFailure); } // 决策下一步：成功则结束，失败则降级 if state.refund_status == "success" { Ok(Action::Respond("已为您退款，预计24小时内到账")) } else { Ok(Action::RouteToSkill(Skill::HumanHandoff)) } } _ => unreachable!(), } }

关键设计点：

• 状态机驱动：不依赖LLM维持对话状态，而是用明确phase（IntentRecognition/RefundExecution/Confirm）控制流程。LLM只负责单步决策，避免长上下文累积误差。
• Skill路由解耦：RouteToSkill不传原始prompt，而是传标准化的SkillInputstruct（含user_id, order_id, intent_confidence），Skill Layer自行组装prompt。这样换掉Claude换成本地Llama 3，Orchestrator一行代码不用改。
• 熔断机制内置：当tool_result.is_err()时，Orchestrator立即触发熔断，跳过LLM重试，直连HumanHandoff Skill。实测将雪崩故障恢复时间从47秒缩短到1.2秒。

我们放弃Python而选Rust，不是为了炫技。在压测中，Rust Orchestrator在4核8G机器上QPS达3200，而同等配置的Python版本仅1100。更重要的是，Rust的ownership模型天然防止memory leak——我们曾用Python版跑72小时后RSS内存涨到12GB，Rust版稳定在1.8GB。

3.2 Skill Layer：可插拔能力单元的工程化封装

Skill不是一段prompt，而是一个独立可测试、可部署、可监控的微服务。我们定义Skill的黄金标准：输入确定、输出契约、副作用可控、失败可降级。

以RefundInitiateSkill为例，它的接口契约是：

// refund_skill.proto message RefundRequest { string user_id = 1; string order_id = 2; float confidence_score = 3; // 来自intent classifier } message RefundResponse { enum Status { SUCCESS = 0; FAILED = 1; PENDING = 2; } Status status = 1; string refund_id = 2; string reason = 3; // 失败时必填 int32 retry_after_seconds = 4; // 需重试时指定 }

实现要点：

• 输入净化：Skill收到request后，第一件事是校验order_id格式（正则^ORD-[0-9]{8}$）和confidence_score > 0.7。低于阈值直接返回Status.FAILED，避免把模糊意图扔给下游。
• 输出契约：无论内部用Claude还是本地模型，response必须严格符合proto。我们用Protobuf生成Go SDK，强制所有Skill开发者实现RefundServiceServer接口。
• 副作用隔离：Skill内部调用退款API时，必须用retryable_http_client（带指数退避+熔断），且所有外部调用包裹在telemetry_span中，便于追踪。
• 降级策略：当退款API超时，Skill不抛异常，而是返回Status.PENDING+retry_after_seconds=30，Orchestrator据此决定是否重试或转人工。

我们用Docker Compose管理Skill集群，每个Skill独立部署、独立扩缩容。RefundInitiate因涉及支付，我们配了8实例；而OrderStatusQuery只读API，2实例足够。这种粒度让资源利用率提升57%。

3.3 Memory：对话状态的可信存储与高效检索

AI Native的Memory不是简单的key-value cache，而是带版本、带权限、带生命周期的对话状态总线。我们拒绝用Redis存原始对话历史，因为：

• 安全风险：用户隐私数据（如身份证号）明文存在Redis，审计不通过；
• 检索低效：LLM需要“上周用户投诉过物流”，但Redis里只有timestamp排序，无法语义检索；
• 版本混乱：prompt更新后，旧memory可能与新prompt逻辑冲突。

我们的Memory架构分三层：

1. Session Store（持久层）：用PostgreSQL存结构化session state，表结构：

   CREATE TABLE sessions ( id UUID PRIMARY KEY, user_id VARCHAR(64), created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ, state JSONB, -- {"last_order_id": "ORD-12345678", "refund_intent_confirmed": true} version INT DEFAULT 1 );

   所有写操作走stored procedure，自动维护version和updated_at。

2. Semantic Cache（加速层）：用ChromaDB存向量化对话摘要。每次session update时，用Sentence-BERT生成摘要embedding并入库。当LLM需要“回顾历史”，Orchestrator先查ChromaDB找top-3相关摘要，再从Session Store加载具体state。

3. Permission Gateway（安全层）：所有Memory读写请求必须经Gateway鉴权。例如RefundInitiateSkill只能读写state.refund_*字段，无权访问state.payment_card_last4。Gateway用Open Policy Agent（OPA）执行策略：

   package memory.auth default allow = false allow { input.skill == "refund_initiate" input.field == "refund_*" }

这套设计让Memory查询P99延迟稳定在87ms，且通过了金融级等保三级审计。最关键是，它让LLM专注推理，不用操心“该记什么、该忘什么”——这些由架构保证。

3.4 Tool Gateway：统一入口的智能路由与韧性保障

Tool Gateway是AI Native架构的“交通警察”，它不执行业务逻辑，但决定每个tool call的命运。我们把它设计成独立服务（Go语言），核心能力：

• 协议适配：统一接收LLM的tool call request（JSON格式），转换为下游API所需协议（REST/gRPC/GraphQL）。例如，LLM调用{"name": "get_order_status", "args": {"order_id": "ORD-123"}}，Gateway自动转成gRPCGetOrderStatusRequest。
• 智能路由：根据order_id前缀路由到不同region的订单服务（ORD-US-*→us-east-1，ORD-CN-*→cn-shanghai）。
• 韧性保障：
  • 熔断：当某API错误率>5%持续30秒，自动熔断，后续请求直接返回fallback response；
  • 降级：熔断时，用本地缓存返回30分钟前的订单状态，并标记is_cached:true；
  • 限流：按user_id维度限流（5 QPS），防止单个恶意用户拖垮全局。

Gateway的日志是故障排查第一现场。我们要求每条log必须包含：

• request_id（全链路追踪ID）
• tool_name
• upstream_service（实际调用的服务名）
• status_code（HTTP code或gRPC code）
• duration_ms
• is_fallback（是否走了降级）

当出现tool_call_failure_rate飙升时，SRE先查Gateway日志，5分钟内定位是“cn-shanghai订单服务超时”，而非在LLM日志里大海捞针。

3.5 Eval：用DeepEval构建多维质量防线

评估AI系统不能只看accuracy。我们基于DeepEval框架构建了四层Eval体系，每层对应不同风险：

DeepEval的威力在于可扩展性。我们为Functional测试开发了custom metric：

# custom_bertscore.py from deepeval.metrics import BaseMetric class RefundAccuracyMetric(BaseMetric): def __init__(self, threshold=0.85): self.threshold = threshold def measure(self, test_case: TestCase): # 提取LLM输出中的refund_amount数字 pred_amount = extract_number(test_case.actual_output) # 从golden answer提取标准金额 expected_amount = extract_number(test_case.expected_output) # 计算相对误差 error_rate = abs(pred_amount - expected_amount) / expected_amount self.score = 1.0 - error_rate self.success = self.score >= self.threshold return self.score

这套Eval体系让每次发布前，我们能生成可视化报告：
![Eval Report Screenshot]
（注：此处为文字描述，实际报告含折线图显示各维度分数趋势，红色预警条标出不达标项）

最宝贵的经验：Eval不是发布前的“验收测试”，而是日常开发的“导航仪”。工程师写完一个Skill，必须跑本地Eval suite；PR合并前，CI自动触发Full Eval；线上每小时抽样1000次对话跑实时Eval。质量不是终点，而是每个环节的呼吸。

4. 实战落地：从零启动AI Native团队的七步法

4.1 第1步：定义“最小可行智能体”（MVA）

别一上来就想做“全能Agent”。我们帮某保险客户启动时，他们CEO说“要能处理所有理赔咨询”。我们坚持先做MVA：只处理“车险定损金额争议”这一单一场景。理由很实在：

• 范围可控：该场景占理赔咨询量32%，但规则明确（交管部门定损单+保险公司核损单对比）；
• 数据可得：历史2年争议案例有1.7万条，标注质量高；
• 价值可测：人工处理平均耗时22分钟，MVA目标≤3分钟，ROI立竿见影。

MVA的交付物只有三样：

• 一个Slack bot，用户发“对定损金额有异议”，bot自动拉取两份定损单PDF，用Claude分析差异点，生成对比报告；
• 一份《争议处理SOP》PDF，bot可一键发送；
• 一个Dashboard，实时显示：今日处理量、平均耗时、人工介入率。

这个MVA上线3周后，人工介入率从68%降到21%，证明模式可行。之后才扩展到“医疗险报销材料补传”“寿险受益人变更”等场景。贪多嚼不烂，MVA是建立团队信心的基石。

4.2 第2步：搭建“Prompt-as-Code”工作流

Prompt不是写在Notepad里的文本，而是要像代码一样管理。我们强制要求：

• Git仓库结构：

  /prompts/ ├── refund/ │ ├── v1.0/ # 主干版本 │ │ ├── system.md │ │ ├── fewshot.json │ │ └── eval_dataset.json │ └── v1.1/ # 迭代版本 └── order_status/ └── v2.0/

• PR流程：修改prompt必须提PR，描述变更原因（如“v1.1：增加对方言‘俺’的识别，覆盖山东用户”），且附上eval结果对比。
• 自动化测试：CI中运行promptfoo eval --testset ./prompts/refund/v1.1/eval_dataset.json，失败则阻断合并。

我们曾因没遵守此流程吃过大亏：一位工程师直接在prod环境改system prompt，删掉一句“请用中文回答”，结果Agent开始混用中英文，客服投诉激增。现在，所有prompt变更都留痕、可回滚、可审计。

4.3 第3步：建立“技能-工具-数据”三角映射表

AI Native开发最大的混乱来自职责不清。我们用一张表厘清边界：

这张表每周站会review，确保：

• 每个Skill有明确Owner，不出现“这个应该前端做还是后端做”的扯皮；
• Tool的SLA必须满足Skill要求（如refund_initiate要求payment_api成功率≥99.95%，否则降级方案必须写入Skill代码）；
• Data源有责任人，当条款更新时，自动触发policy_explainSkill的retrain pipeline。

4.4 第4步：设计“渐进式灰度发布”策略

AI模型发布不能像代码一样“全量切流”。我们的灰度分三阶段：

1. Shadow Mode（影子模式）：新prompt版本同时跑新旧两套，只记录新版本输出，不返回给用户。监控new_vs_old_disagreement_rate，若>15%则暂停。
2. Canary Release（金丝雀）：切5%真实流量，重点监控cost_per_action和human_handoff_rate。若cost_per_action超标20%，自动回滚。
3. Phased Rollout（分阶段）：按用户分层放量——先VIP用户（高价值，容忍度低），再普通用户，最后新注册用户。每阶段间隔2小时，SRE全程值守。

这套策略让我们在一次Claude 3.5升级中，提前2小时发现新模型在“理赔材料OCR识别”场景准确率下降12%，及时切回旧版，避免大规模客诉。

4.5 第4步：构建“成本-效果”双维度监控大盘

AI服务的成本黑洞常被忽视。我们监控大盘必含两轴：

• X轴：效果指标
  success_rate（任务完成率）、first_contact_resolution（一次解决率）、csat_score（用户满意度）
• Y轴：成本指标
  cost_per_action（单次交互美元成本）、tokens_per_action（token消耗）、compute_cost_per_hour（GPU小时成本）

当cost_per_action上升但success_rate不变时，说明prompt冗余或tool调用低效；当success_rate下降但cost_per_action也降，说明模型在偷懒（如用fallback response应付）。我们用Looker构建动态仪表盘，设置智能告警：当cost_per_action连续15分钟>阈值且success_rate<基准线，自动创建Jira ticket并@Owner。

4.6 第5步：制定“AI事故响应SOP”

AI故障不是“服务宕机”，而是“行为异常”。我们的SOP分三级：

• Level 1（轻微）：tool_call_failure_rate > 10%
  动作：自动熔断该tool，切到fallback，通知Skill Owner。
• Level 2（中度）：safety_violation_rate > 0.1%（检测到越狱）
  动作：立即停用当前prompt版本，启用安全兜底prompt，SecOps团队介入审计。
• Level 3（严重）：human_handoff_rate > 40%持续10分钟
  动作：全量切回上一稳定版本，启动Root Cause Analysis（RCA），24小时内输出报告。

每次事故后，我们强制做“五问法”复盘：

1. 为什么这个prompt会越狱？（直接原因：few-shot例子包含诱导性文本）
2. 为什么没在Eval中发现？（流程漏洞：Safety测试没覆盖该类prompt）
3. 为什么流程没拦截？（机制缺失：PR检查没集成Safety scan）
4. 为什么机制缺失？（文化问题：团队认为Safety是SecOps的事，非开发责任）
5. 如何根治？（行动：将Safety scan加入CI，所有prompt PR必须通过）

4.7 第6步：启动“AI素养”全员培训计划

技术落地，人是关键。我们设计了分角色培训：

• 产品经理：学《AI需求建模三要素》，用Obsidian模板填写“意图-技能-约束”表；
• 工程师：实操《Prompt-as-Code工作流》，从fork仓库到merge PR全流程；
• QA：掌握DeepEval CLI，能编写custom metric；
• 客服：《AI辅助话术指南》，知道何时该信任Agent建议，何时该override。

培训不是讲座，而是Workshop：每人领一个真实case（如“处理用户投诉物流延误”），现场设计Skill、写prompt、跑Eval、调优。结业标准是：独立交付一个MVA并上线。

5. 常见问题与实战排障：那些文档里不会写的坑

5.1 “Agent anywhere”不是魔法，是架构选择题

“Agent anywhere”概念很酷，但落地时必须回答：Agent的执行环境在哪？我们见过三种方案，各有死穴：

• Client-side Agent（浏览器/APP内）：
  优势：隐私好，离线可用。
  坑：手机端运行Llama 3 8B需12GB RAM，iOS限制后台进程，实际不可行。我们试过WebAssembly版，但token生成速度<1 token/sec，用户体验灾难。

• Edge Agent（Cloudflare Workers等）：
  优势：低延迟，近用户。
  坑：内存限制（CF Workers max 1GB），无法加载大模型；vendor lock-in，调试困难。我们曾用CF跑Claude，但anthropic-api-key硬编码在worker里，密钥轮换时全量更新，服务中断17分钟。

• Backend Agent（自有K8s集群）：
  优势：完全可控，可水平扩展。
  坑：运维复杂，GPU成本高。
  我们的解法：混合架构——轻量Skill（如order_status_query）放Edge，重模型Skill（如policy_explain）放Backend，用统一API网关路由。既保体验，又控成本。

5.2 “Hermes Agent”与“Agent Harness”本质区别

这两个词常被混用，但技术内涵天壤之别：

• Hermes Agent：特指基于Hermes框架（Meta开源）构建的Agent，核心是强化学习驱动的自主规划。它不靠prompt chain，而是训练一个Policy Network，根据reward signal动态选择tools。适合研究场景，但生产环境难debug——你无法解释“为什么它选了这个tool”。

• Agent Harness：指工具链集成平台（如LangChain/Dify/CrewAI），本质是prompt orchestrator。它把LLM、tools、memory胶水般粘起来，开发者掌控每一步。我们选Harness，因为业务需要可解释性：当用户投诉“Agent乱退款”，我们必须能追溯到是refund_initiateSkill的prompt第3行逻辑错误。

实操心得：别被名词迷惑。评估一个框架，只问三个问题：1）出问题时，我能快速定位到哪一行代码？2）换模型时，要改几处？3）压测时，QPS瓶颈在哪儿？Hermes在第1问上得0分，Harness在第2问上得满分。

5.3 “Multi-Agent”不是银弹，是复杂度放大器

多Agent架构（如CrewAI）听起来强大，但我们的血泪教训：除非业务逻辑天然分布式，否则单Agent更稳。我们曾为“跨部门协作审批”建Multi-Agent：Sales Agent、Finance Agent、Legal Agent各司其职。结果：

• 协调开销巨大：Agents间通信用Message Queue，但一个审批要经历Sales→Finance→Legal→Sales四次消息往返，latency从800ms升到4.2秒；
• 状态不一致：Legal Agent批准后，Sales Agent因网络延迟没收到消息，重复发起审批；
• Debug地狱：日志分散在三个服务，查一次故障要切5个Kibana tab。

最终我们砍掉Multi-Agent，用单Agent + 状态机实现：Agent按顺序调用sales_approve()→finance_check()→legal_review()，失败则rollback。代码量减60%，P99 latency降至900ms。

5.4 “Agent Skill教程”最大误区：把Skill当函数写

很多教程教“写一个天气Skill”，示例代码是：

def get_weather(city): return requests.get(f"https://api.weather.com/{city}").json()

这在Demo里OK，生产中是灾难。真实Skill必须：

• 带重试与熔断：requests.get加tenacity装饰器，失败3次后熔断；
• 带Schema验证：返回JSON必须符合OpenAPI spec，用pydantic校验；
• 带Telemetry：记录latency_ms、status_code、cache_hit；
• 带Fallback：API不可用时，返回“正在获取最新天气，请稍候”，而非抛异常。

我们用Cookiecutter模板生成Skill，强制包含requirements.txt（含tenacity/pydantic）、pyproject.toml（含lint配置）、tests/（含mock测试）。新工程师第一天就能产出合规Skill。

5.5 “Eval框架选型”避坑指南

DeepEval、RAGAS、TruEra...选哪个？我们的结论：别选框架，选能力。我们用DeepEval，但只用其核心能力：

• Metric可编程：自己写RefundAccuracyMetric，不用它内置的AnswerRelevancyMetric（太泛）；
• Dataset可版本化：eval_dataset.json存Git，每次prompt更新，必须更新dataset；
• Report可集成：CLI输出JSON，Pipe到ELK做可视化。

我们弃用RAGAS，因为它的context_recallmetric在退款场景不适用——用户不需要召回“保险条款全文”，只需要“退款时效条款第2条”。TruEra太重，小团队玩不转。记住：Eval框架是锤子，你要钉的钉子是业务指标。

6. 最后一点真实体会：AI Native不是技术革命，是工程文化的重塑

带第一个AI Native团队时，我花最多时间的不是调参，而是开会。每周三下午，我和产品经理、工程师、QA围坐，不聊技术细节，只做一件事：重演一次线上故障。比如那次tool_call_failure_rate飙升，我们还原：

• 产品经理说：“我以为‘用户要求退款’就是明确意图，没料到还有‘钱不退我就投诉’这种变体。”
• 工程师说：“我按PRD写了skill，但没意识到payment API的503错误码要特殊处理。”
• QA说：“我的测试用例只覆盖了HTTP 200，忘了503。”

然后我们当场改三件事：

1. PRD模板增加“边缘意图”栏位；
2. Skill SDK强制要求handle所有HTTP status code；
3. Eval dataset加入10%的error case。

AI