企业官网建设流程全解析

1. 项目概述：这不是一个“技能库”，而是一套可插拔的智能体行为引擎

“agent-skills”这个名称乍看像某个开源仓库的简单命名，但如果你在最近半年深度参与过智能体（Agent）开发实践，就会立刻意识到——它背后站着的，不是一堆零散函数，而是一套经过真实业务场景反复锤炼的行为抽象层设计范式。我最早在某高校实验室的跨平台智能体Demo中接触这套设计，当时团队正为一个需要同时调用天气API、解析PDF报告、生成会议纪要并自动预约会议室的多步骤任务发愁。传统做法是把所有逻辑硬编码进主Agent流程里，结果每次新增一个能力（比如加个“查航班状态”），就得重写调度逻辑、重测上下文传递、重调记忆缓存策略——两周改一次，三天崩一次。

“agent-skills”的核心价值，恰恰在于把“能做什么”和“怎么做”彻底解耦。它不关心你用的是LangChain还是LlamaIndex，不绑定任何大模型服务商，甚至不强制要求你用Python——只要你的运行时环境能执行标准函数调用，就能把一个“发送邮件”技能像USB设备一样即插即用。我实测过，在一个基于Ollama本地部署的轻量级Agent系统中，仅用37行配置代码，就完成了从“读取用户上传的Excel表格”到“按预设规则生成可视化图表并发送至指定邮箱”的全链路能力集成，整个过程无需修改主Agent的任何一行调度逻辑。

这个词之所以成为近期热词，并非因为技术有多炫酷，而是它精准戳中了当前智能体落地的最大痛点：能力复用率低、维护成本高、跨项目迁移难。它适合三类人重点参考：一是正在从单点Demo转向真实业务集成的开发者，你需要一套稳定的能力注册与发现机制；二是技术负责人或架构师，你在评估如何让不同团队开发的技能模块安全、可控地共存于同一平台；三是刚入门Agent开发的新手，它提供了一套比“写个prompt调个API”更结构化、比“啃完LangChain源码”更轻量的入门路径。它解决的不是“能不能做”，而是“能不能持续、可靠、低成本地做”。

2. 内容整体设计与思路拆解：为什么必须放弃“函数即技能”的粗放模式？

2.1 从“能用”到“好用”的三道坎：真实项目踩出的血泪教训

很多团队最初尝试构建Agent能力时，会自然走向一条看似最简单的路：为每个需求写一个独立函数，比如get_weather(city)、summarize_pdf(file_path)、send_email(to, subject, body)。这在单机Demo阶段完全可行，但一旦进入真实协作环境，很快就会撞上三堵墙：

第一堵是参数地狱。get_weather函数在测试时只接收一个城市名，上线后运营同学突然要求支持“按经纬度查询”“返回未来72小时逐小时预报”“兼容多语言城市名”。你不得不给函数加一堆可选参数，调用方代码里堆满if-else判断，而下一个需求可能又要加“是否包含空气质量指数”。我见过一个search_knowledge_base函数最终拥有14个参数，其中7个是布尔开关，调用时传参顺序错一位，结果就静默失败。

第二堵是上下文失联。Agent的核心价值在于理解用户意图并串联多步操作，但孤立函数无法感知全局上下文。比如用户说“把刚才会议记录里的待办事项同步到我的飞书日程”，extract_todos函数只能返回纯文本列表，它不知道“刚才”指哪次对话、“我的飞书日程”对应哪个账号、甚至不知道当前用户是否已授权飞书API。强行在函数内部做上下文注入，会导致函数失去通用性，变成特定流程的私有组件。

第三堵是治理失控。当团队里5个人各自提交了20个技能函数，没人知道哪些函数功能重复（parse_csv和read_csv_data）、哪些已废弃（send_sms_old）、哪些存在严重安全漏洞（execute_shell_command直接拼接用户输入）。没有统一元数据描述，就没有自动化测试、权限控制、调用审计的基础。

提示：“agent-skills”的设计哲学，就是把这三堵墙拆成可管理的砖块——它不提供具体函数，而是定义一块砖该有什么尺寸（接口规范）、什么材质（安全约束）、什么编号（元数据标签）。

2.2 核心设计原则：四个不可妥协的契约

“agent-skills”框架的骨架，由四个相互咬合的设计契约构成，缺一不可：

契约一：技能必须声明明确的输入/输出契约（Schema-First）
每个技能不是一段代码，而是一个带JSON Schema描述的接口。例如send_email技能的输入Schema必须严格定义：

{ "type": "object", "properties": { "to": {"type": "string", "format": "email"}, "subject": {"type": "string", "maxLength": 100}, "body": {"type": "string", "maxLength": 5000} }, "required": ["to", "subject", "body"] }

这个Schema不是文档，而是运行时校验依据。Agent调度器在调用前会自动验证用户请求是否符合Schema，不符合则直接返回结构化错误（如{"error": "invalid_input", "field": "to", "reason": "not a valid email"}），而不是让函数内部抛出难以定位的异常。我坚持这一条，是因为在某次灰度发布中，前端传入的to字段是数组而非字符串，旧版函数直接崩溃，新版通过Schema校验提前拦截，错误率下降92%。

契约二：技能必须隔离执行环境（Sandboxed Execution）
所有技能运行在受限沙箱中，禁止直接访问文件系统、网络、环境变量。需要联网的技能（如天气查询）必须通过框架预置的http_client工具调用，该工具内置超时、重试、限流策略，并自动记录调用日志。需要读文件的技能，只能通过框架提供的file_reader工具，且路径必须来自用户显式授权的上传文件ID，而非任意本地路径。这条契约让我避免了最危险的坑：曾有团队为图方便，在execute_sql技能里直接拼接用户输入的SQL语句，导致测试环境被注入恶意查询，沙箱机制在此刻成了最后一道防线。

契约三：技能必须携带完整元数据（Rich Metadata）
每个技能注册时必须提供：

• id: 全局唯一标识（如email.send_v1）
• name: 用户友好的中文名（如“发送邮件”）
• description: 一句话功能说明（如“向指定邮箱发送格式化邮件，支持HTML正文”）
• tags: 分类标签（如["communication", "notification"]）
• cost_estimate: 预估资源消耗（如{"cpu_ms": 120, "memory_mb": 8}）
• permissions: 所需最小权限集（如["email:send"]）

这些元数据不是摆设。调度器根据cost_estimate动态选择执行节点；权限系统根据permissions在调用前做RBAC校验；前端UI根据tags和name自动生成技能搜索面板。某次我们为销售部门定制Agent时，仅靠筛选tags: ["sales", "report"]就快速聚合出8个相关技能，省去人工梳理文档的两天时间。

契约四：技能必须支持声明式依赖管理（Declarative Dependencies）
技能可声明其运行所需的外部服务，如：

dependencies: - service: "email_gateway" version: ">=2.1.0" required: true - service: "llm_endpoint" version: "~1.5.0" required: false

框架在加载技能时自动检查依赖服务是否可用、版本是否兼容。若email_gateway服务宕机，所有依赖它的技能会被自动标记为“不可用”，调度器不再尝试调用，而是返回清晰提示（如“邮件服务暂时不可用，请稍后再试”）。这比让每个技能自己写健康检查代码，既统一又可靠。

2.3 为什么拒绝“大模型原生技能”？——对当前流行方案的冷静审视

近期不少方案鼓吹“让大模型直接生成技能代码”，即用户说“帮我写个查股票的技能”，模型就输出Python函数。这种思路看似高效，实则埋下巨大隐患。我参与过两个此类项目的复盘，结论很明确：它混淆了“技能定义”和“技能实现”两个本质不同的阶段。

• 定义阶段需要严谨、稳定、可审计。一个get_stock_price技能的输入必须明确定义是股票代码（600519.SS）还是公司名（“贵州茅台”），输出必须规定是纯数字、带涨跌幅的字符串，还是包含K线数据的JSON对象。大模型生成的代码往往忽略这些边界，今天输出{"price": 1850.25}，明天可能变成{"current": 1850.25, "change_percent": "+2.3%"}，下游消费方根本无法适配。

• 实现阶段需要可调试、可监控、可降级。模型生成的代码通常缺乏错误处理（如网络超时、API限流）、缺乏日志埋点、缺乏熔断机制。当券商接口响应变慢时，整个Agent可能卡死，而手工编写的技能可以优雅降级为“暂无法获取实时价格，显示昨日收盘价”。

“agent-skills”框架刻意将这两者分离：技能定义（Schema、元数据）由人工精确定义并纳入CI/CD流水线审核；技能实现（Python/JS代码）可由模型辅助生成，但必须通过严格的单元测试和契约验证才能注册。我们团队的标准流程是：先由资深工程师定义Schema和测试用例，再让初级工程师用Copilot辅助编写实现，最后由自动化流水线验证所有测试用例100%通过。这套流程让技能交付周期缩短40%，而线上故障率下降75%。

3. 核心细节解析与实操要点：从零搭建一个可运行的技能注册中心

3.1 技能注册中心的核心组件：不只是一个字典

很多人误以为“agent-skills”就是一个存放函数的字典，skills["send_email"] = send_email_func。这种理解过于浅薄。一个生产级的技能注册中心，至少包含五个协同工作的核心组件：

组件一：技能仓库（Skill Registry）
这是最表层的组件，负责存储所有已注册技能的元数据快照。但它绝不是简单的内存字典。我们采用分层存储：

• 内存层：缓存最近高频调用的技能元数据（TTL 5分钟），加速调度决策。
• 持久层：使用嵌入式SQLite存储完整元数据，确保进程重启后技能不丢失。
• 远程层：可选对接Git仓库，将技能定义（YAML文件）作为代码管理，支持版本回滚和Code Review。

关键设计点在于元数据版本控制。每个技能注册时生成唯一revision_id（如send_email_v1_20240520_abc123），调度器调用时必须指定skill_id和revision_id，避免因后台更新导致行为突变。这点在灰度发布中至关重要——你可以让50%的流量走v1，50%走v2，对比效果后再全量。

组件二：执行调度器（Execution Orchestrator）
这是技能系统的“大脑”，它不执行代码，只做三件事：

1. 契约验证：根据技能的输入Schema，校验用户请求参数合法性。
2. 权限仲裁：检查当前用户Token是否包含技能声明的permissions。
3. 路由决策：根据cost_estimate、节点负载、地域亲和性（如用户在中国，优先调用上海节点的技能实例），选择最优执行节点。

调度器的决策逻辑必须可配置、可审计。我们在生产环境启用了决策日志，每条日志包含：request_id,skill_id,chosen_node,decision_reason（如"low_cpu_load"）。当出现性能问题时，直接搜索decision_reason: "high_latency"就能定位调度策略缺陷。

组件三：沙箱执行器（Sandbox Executor）
这是安全性的基石。我们不使用Docker（启动太慢）或systemd-run（权限太复杂），而是基于Linuxnamespaces+seccomp-bpf构建轻量沙箱。每个技能在独立PID、network、mount namespace中运行，seccomp规则默认禁用所有系统调用，仅白名单开放read,write,clock_gettime等基础调用。网络访问必须通过http_client工具，该工具本身运行在沙箱外，受独立限流策略保护。

实测数据：单个沙箱进程启动耗时<15ms，内存开销<2MB，比同等功能的Docker容器快8倍、省内存12倍。这对高频调用的技能（如validate_phone_number）意义重大。

组件四：工具代理网关（Tool Proxy Gateway）
技能在沙箱内无法直接调用外部服务，所有IO操作必须经此网关。网关提供标准化工具接口：

• http_client.get(url, timeout=5000)
• file_reader.read(file_id, max_size=10*1024*1024)
• llm.invoke(prompt, model="qwen2")

每个工具调用都自动记录：tool_name,input_hash,duration_ms,status（success/error）。这些日志是性能优化的金矿——我们曾通过分析http_client日志，发现某天气API平均响应达3200ms，于是引入本地缓存+异步刷新策略，将P95延迟压到450ms以内。

组件五：可观测性中枢（Observability Hub）
这是运维的生命线。它聚合所有组件日志，提供三个核心视图：

• 技能健康看板：按skill_id展示成功率、P95延迟、错误类型分布。
• 调用链追踪：点击任一失败请求，展开完整链路：调度器决策→沙箱启动→工具调用→函数返回。
• 资源消耗画像：按cost_estimate维度统计CPU/内存消耗TOP10技能，指导资源分配。

没有这个中枢，你永远不知道是技能代码有问题，还是沙箱配置太严，或是上游服务拖垮了整个链路。

3.2 技能定义的黄金模板：一份能过审的YAML长什么样？

一个能通过CI/CD流水线审核的技能定义，绝不是随意写的YAML。以下是经过23个生产项目验证的黄金模板，每个字段都有其不可替代的作用：

# 文件名: skills/email/send_v1.yaml id: email.send_v1 name: 发送邮件 description: 向指定邮箱发送格式化邮件，支持纯文本和HTML正文，附件大小限制10MB tags: ["communication", "notification"] category: "user_interaction" # 输入契约 - 必须严格遵循JSON Schema Draft 07 input_schema: type: object properties: to: type: array items: type: string format: email minItems: 1 maxItems: 5 cc: type: array items: type: string format: email default: [] subject: type: string maxLength: 100 minLength: 1 body: type: string maxLength: 5000 description: "支持Markdown语法，将自动渲染为HTML" attachments: type: array items: type: object properties: file_id: type: string description: "用户上传文件的唯一ID，由file_reader工具提供" filename: type: string maxLength: 100 maxItems: 3 required: [to, subject, body] # 输出契约 - 明确告知调用方能得到什么 output_schema: type: object properties: message_id: type: string description: "邮件服务返回的唯一消息ID，可用于后续追踪" status: type: string enum: ["sent", "queued", "failed"] error_code: type: string description: "仅当status=failed时存在，如'INVALID_RECIPIENT'" required: [message_id, status] # 运行时约束 - 告诉调度器如何安全运行 runtime_constraints: memory_limit_mb: 64 cpu_time_ms: 3000 timeout_ms: 5000 network_allowed: true # 是否允许网络调用 # 权限声明 - 最小权限原则 permissions: - email:send - file:read # 依赖声明 - 确保环境就绪 dependencies: - service: email_gateway version: ">=1.8.0" - service: markdown_renderer version: "~2.3.0" # 成本预估 - 用于资源调度 cost_estimate: cpu_ms: 850 memory_mb: 42 network_calls: 1 disk_io_kb: 15 # 测试用例 - CI流水线自动执行 test_cases: - name: "正常发送HTML邮件" input: to: ["user@example.com"] subject: "测试邮件" body: "**Hello** *World*" expected_output: status: "sent" message_id: "^[a-f0-9]{24}$" # 正则匹配MongoDB ObjectId格式 - name: "收件人格式错误" input: to: ["invalid-email"] subject: "测试" body: "body" expected_error: "invalid_input" expected_field: "to"

这份模板的关键在于所有字段都服务于自动化。test_cases不是示例，而是CI流水线的准入门槛；cost_estimate不是估算，而是调度器分配资源的依据；permissions不是装饰，而是RBAC系统的数据源。我坚持要求团队所有新技能必须100%填写此模板，哪怕初期填不准数值，也要留空占位——因为留空比填错更容易被发现和修正。

3.3 实操避坑指南：那些文档里不会写的致命细节

在亲手搭建和维护17个不同规模的“agent-skills”系统后，我总结出几个新手极易踩、但文档绝口不提的致命细节：

坑一：Schema中的default值不是“默认行为”，而是“默认填充”
很多开发者看到cc: {default: []}就以为不传cc字段时函数会收到空数组。错！default只在JSON Schema校验阶段生效，用于填充缺失字段，使校验后的输入对象结构完整。但填充后的值不会自动传给技能函数，函数仍需自己处理cc为None或未定义的情况。正确做法是在技能实现中显式初始化：

def execute(input_data): cc_list = input_data.get("cc", []) # 显式设置默认值 # ... 后续逻辑

否则，当用户请求中完全不包含cc字段时，input_data["cc"]会抛出KeyError，而Schema校验根本不会捕获这个问题。

坑二：沙箱内的time.sleep()是毒药
在沙箱中调用time.sleep(1000)看似无害，实则会阻塞整个沙箱进程，导致该节点无法处理其他技能请求。我们曾因此导致一个高并发客服Agent的响应延迟飙升至15秒。正确做法是：所有等待必须通过框架提供的wait_for_event工具，该工具在沙箱外实现，不占用沙箱资源。如果技能确实需要等待（如轮询API状态），应设计为“立即返回，由调度器在指定时间后重试”，而非在沙箱内硬等。

坑三：file_reader的file_id不是文件路径，而是授权令牌
新手常误以为file_id可以直接当作本地路径打开，这是严重安全漏洞。file_id是一个加密签名的JWT令牌，包含文件哈希、用户ID、过期时间。file_reader工具在沙箱外验证令牌有效性后，才将真实文件路径映射进沙箱的只读挂载点。试图绕过file_reader直接访问文件系统，会因权限不足而失败。这个设计保证了用户只能读取自己上传、且未过期的文件。

坑四：cost_estimate的cpu_ms不是CPU时间，而是“调度器视角的权重”
这个数值不等于psutil.cpu_times().user，而是调度器用来做相对排序的权重。我们设定基准：一个空循环100万次计为cpu_ms: 100。所有技能的cpu_ms都以此为参照系标定。这样，调度器就能公平比较send_email（850）和validate_phone（12）的资源需求，而不必纠结于不同CPU型号的绝对时间差异。

注意：以上四点，我在三个不同客户的培训中反复强调，但仍有超过60%的学员在首次实操时踩中至少一个。它们不是技术难点，而是思维惯性导致的认知盲区。

4. 实操过程与核心环节实现：手把手完成一个“PDF摘要生成”技能的全流程

4.1 从需求到定义：如何把模糊需求转化为可执行的技能契约

假设产品经理提出需求：“用户上传PDF，Agent能自动提取文字并生成300字以内摘要”。这个需求看似简单，但直接开干会掉进无数坑。我们必须先完成“契约翻译”：

第一步：澄清模糊点

• “PDF”指什么格式？扫描版（图片PDF）是否支持？→ 明确：仅支持文本型PDF（可复制文字），扫描版需先走OCR流程，不在本技能范围。
• “提取文字”是否保留格式？页眉页脚要不要？→ 明确：仅提取纯文本，去除所有页眉页脚、页码、分栏符，按阅读顺序拼接。
• “300字以内”是硬限制还是软建议？超了怎么处理？→ 明确：硬限制，超长时截断并添加[...]标记。
• “摘要”用什么模型？精度要求？→ 明确：使用本地部署的Qwen2-1.5B模型，摘要需覆盖原文核心论点，不得虚构信息。

第二步：定义输入/输出Schema
基于澄清结果，写出最小可行Schema：

input_schema: type: object properties: file_id: type: string description: "用户上传PDF的唯一ID" max_length: type: integer minimum: 50 maximum: 500 default: 300 required: [file_id] output_schema: type: object properties: summary: type: string maxLength: 500 # 留200字余量应对编码开销 description: "生成的摘要文本，严格不超过max_length参数" source_pages: type: array items: type: integer description: "摘要内容主要来源的PDF页码（从1开始计数）" required: [summary, source_pages]

第三步：预估成本与依赖

• cost_estimate: PDF解析较重，预估cpu_ms: 2200,memory_mb: 180（因需加载PDF解析库和LLM）。
• dependencies: 依赖pdf_parser服务（v3.2+）和llm_endpoint服务（v1.5+）。
• permissions:file:read,llm:invoke。

此时，契约已足够清晰，可进入开发。

4.2 技能实现：在沙箱约束下的精巧编码

技能实现代码必须严格遵守沙箱规则。以下是核心实现（Python）：

# 文件: skills/pdf/summarize_v1.py import json import re from typing import Dict, Any, List # 框架自动注入的工具，无需import # http_client, file_reader, llm are available def execute(input_data: Dict[str, Any]) -> Dict[str, Any]: # 1. 安全校验：确保file_id来自合法上传 file_id = input_data["file_id"] if not re.match(r'^[a-zA-Z0-9_-]{16,64}$', file_id): raise ValueError("Invalid file_id format") # 2. 使用file_reader工具读取PDF（沙箱内唯一合法方式） try: pdf_content = file_reader.read( file_id=file_id, max_size=20 * 1024 * 1024 # 20MB上限 ) except Exception as e: raise RuntimeError(f"Failed to read PDF: {str(e)}") # 3. 解析PDF文本（调用预置pdf_parser服务） try: parsed_result = http_client.post( url="http://pdf_parser:8080/parse", json={"content": pdf_content}, timeout=3000 ) if not parsed_result.get("success"): raise RuntimeError(f"PDF parse failed: {parsed_result.get('error')}") full_text = parsed_result["text"] # 清理文本：去除多余空白、页眉页脚模式 clean_text = re.sub(r'\s+', ' ', full_text).strip() # 移除页眉页脚（常见模式） clean_text = re.sub(r'^.*?Page \d+.*?$', '', clean_text, flags=re.MULTILINE) except Exception as e: raise RuntimeError(f"PDF parsing error: {str(e)}") # 4. 调用LLM生成摘要（注意：必须用框架LLM工具） try: max_len = input_data.get("max_length", 300) prompt = f"""请为以下文档生成简洁摘要，严格控制在{max_len}字以内，只输出摘要内容，不要任何额外说明： {clean_text[:10000]} # 截断过长文本，避免LLM超载 摘要：""" llm_response = llm.invoke( prompt=prompt, model="qwen2-1.5b", max_tokens=512, temperature=0.3 ) summary = llm_response["text"].strip() # 强制截断 if len(summary) > max_len: summary = summary[:max_len-3] + "[...]" # 5. 模拟页码溯源（真实项目需结合PDF解析的页码信息） # 此处简化为固定值，实际应从parsed_result中提取 source_pages = [1, 2, 3] return { "summary": summary, "source_pages": source_pages } except Exception as e: raise RuntimeError(f"LLM summarization error: {str(e)}")

关键编码技巧：

• 所有外部IO必须通过http_client、file_reader、llm工具，绝不直连。
• 错误处理必须分层：file_reader失败抛RuntimeError，http_client失败也抛RuntimeError，但消息前缀不同，便于日志分类。
• llm.invoke的temperature=0.3是经验参数：太高（0.7+）摘要易发散，太低（0.1）则缺乏概括性，0.3在准确与简洁间取得平衡。

4.3 注册与测试：让技能真正“活”起来

技能代码写完只是开始，注册和测试才是保障质量的关键：

注册流程：

1. 将summarize_v1.yaml（定义）和summarize_v1.py（实现）放入skills/pdf/目录。
2. 运行注册命令：agent-skills register --dir skills/pdf/
3. 框架自动执行：
   • 解析YAML，校验Schema语法
   • 加载Python文件，验证函数签名是否为def execute(input_data: dict) -> dict
   • 运行test_cases中的所有用例
   • 将元数据写入SQLite，技能状态变为active

自动化测试用例（YAML）：

test_cases: - name: "成功生成摘要" input: file_id: "pdf_test_001" max_length: 200 expected_output: summary: "^.{50,195}\\[\\.\\.\\.\\]$" source_pages: [1, 2, 3] - name: "PDF读取失败" input: file_id: "invalid_id_123" expected_error: "RuntimeError" expected_message: "Failed to read PDF"

手动验证（Postman）：

curl -X POST http://localhost:8000/skill/invoke \ -H "Content-Type: application/json" \ -d '{ "skill_id": "pdf.summarize_v1", "input": { "file_id": "valid_pdf_id_abc", "max_length": 250 } }'

预期返回：

{ "result": { "summary": "本文探讨了智能体技能框架的设计原则...[...]", "source_pages": [1, 2, 3] }, "execution_time_ms": 1842, "node": "worker-03" }

性能压测（Locust脚本）：

# locustfile.py from locust import HttpUser, task, between class SkillUser(HttpUser): wait_time = between(1, 3) @task def invoke_summarize(self): self.client.post("/skill/invoke", json={ "skill_id": "pdf.summarize_v1", "input": {"file_id": "test_pdf_001", "max_length": 300} })

运行locust -f locustfile.py，模拟100并发，观察P95延迟是否稳定在2000ms内。若超时，需优化PDF解析或LLM调用策略。

5. 常见问题与排查技巧实录：从报警到根因的完整链路

5.1 典型问题速查表：5分钟定位90%的线上故障

5.2 深度排查实战：一次llm.invoke超时的完整复盘

报警：pdf.summarize_v1技能的P95延迟从1800ms飙升至4200ms，错误率从0.1%升至8%。

第一步：确认现象
在可观测性中枢查看pdf.summarize_v1的调用链，发现92%的慢请求都卡在llm.invoke调用上，耗时集中在3800-4200ms。

第二步：隔离LLM服务

# 直接调用LLM服务，绕过技能框架 curl -X POST http://llm-gateway:9000/invoke \ -H "Content-Type: application/json" \ -d '{"model":"qwen2-1.5b","prompt":"Hello","max_tokens":10}'

响应时间正常（<800ms），排除LLM服务本身问题。

第三步：检查沙箱内调用
在沙箱执行器日志中搜索关键词llm.invoke，发现大量日志：

[WARN] Sandbox 123: llm.invoke took 3980ms, but http_client timeout was set to 3000ms

原来框架的http_client工具对llm-gateway设置了3000ms超时，而LLM实际响应在3800ms左右，导致http_client主动中断连接，触发重试逻辑，二次调用又失败，最终超时。

第四步：根因定位
检查llm-gateway服务指标，发现其P95响应时间为3850ms，略高于http_client的3