agent-skills：可组合、可验证的智能体技能契约设计-北京尧图网络

1. 项目概述什么是 agent-skills它不是插件也不是脚本而是一套可组合、可复用、可验证的智能体能力单元“agent-skills”这个词最近在开发者社区里频繁刷屏但很多人点开仓库或文档后反而更迷糊了——它既不像传统 CLI 工具那样输入命令就出结果也不像前端组件库那样拖拽即用它没有安装包管理器式的npm install全流程也没有 API 文档里常见的/v1/skills/list接口。我第一次看到这个标题时下意识去搜npm install agent-skills结果返回 404又试了pip install agent-skills同样空手而归。后来花了三天时间把 GitHub 上 top 5 的相关 repo 全 clone 下来跑了一遍 demo翻了 17 个 issue 讨论串重读了 OpenAI 的 Function Calling v2 规范、Claude 的 Tool Use RFC、以及 Anthropic 官方发布的tool_use消息结构设计白皮书才真正搞懂agent-skills 的本质是把“让大模型调用外部能力”这件事从零散的 prompt 工程和硬编码 API 调用升级为一种可声明、可注册、可测试、可版本化的技能契约Skill Contract。它解决的核心问题非常具体当你的智能体要查天气、发邮件、读 Excel、调用企业内部审批系统时你不再需要每次都在 system prompt 里写“你是一个能调用 weather_api 的助手”也不再需要在代码里手动拼接 HTTP 请求头、处理 token 过期、做 JSON Schema 校验、写 fallback 逻辑。agent-skills 把这些能力抽象成一个个独立的、带类型定义、带执行入口、带输入输出契约的“技能模块”。比如一个send_emailskill它必须声明自己接受什么字段to, subject, body、返回什么结构success: bool, message_id: str、支持哪些参数校验规则to 必须是邮箱格式、body 长度不能超 10000 字符甚至还能自带 mock 数据用于本地测试。这种设计不是炫技而是直面现实——我在上一个金融风控 agent 项目里光是对接内部反洗钱接口就写了 3 套不同环境的调用逻辑dev/staging/prod每个环境的 auth 方式、endpoint、错误码都不同最后靠注释掉 87 行 if-else 才勉强上线。而用 agent-skills 模式只需要维护一份 skill definition YAML再配三个 environment-specific adapter所有环境差异被收口到 adapter 层主逻辑干净得像教科书。它适合三类人第一类是正在搭建 RAGAgent 架构的中高级后端/全栈工程师你需要把业务系统能力快速接入 LLM 流程第二类是 AI 产品负责人或技术 PM你得向非技术同事解释“为什么这个功能要两周而不是两天上线”agent-skills 提供了清晰的能力交付界面第三类是刚入门的 AI 应用开发者你不用再被“怎么让 Claude 调用我的 Python 函数”这种问题卡住一整天——skill 就是函数只是加了契约、加了注册、加了测试桩。它不绑定任何特定模型DeepSeek、Qwen、Claude、GLM 都能用不强制要求特定框架LangChain、LlamaIndex、Ollama、自研调度器均可接入甚至不依赖云服务——我上周在一台没联网的 M2 Mac 上用本地运行的 Qwen2-7B 一个get_local_file_contentskill完成了对 23 个 Markdown 笔记的自动摘要生成。关键不在“能不能跑”而在“能不能管”技能是否可发现、可审计、可灰度、可回滚。这才是 agent-skills 真正的底层价值——它把 AI 应用开发从手工作坊时代推进到了现代软件工程的流水线阶段。2. 整体架构设计与核心思路拆解为什么不是封装 API而是重构能力交付链路2.1 传统 API 封装模式的三大硬伤决定了必须另起炉灶很多团队一开始都想走捷径写个weather_api.py里面封装 requests 调用高德天气再扔进 agent 的 tools 列表里。我试过也推荐别人这么试——因为只有踩过坑才明白为什么 agent-skills 要重新设计整条链路。第一个硬伤是契约缺失。传统封装里def get_weather(city: str)这个函数签名只约束了输入类型但没约束语义city 是城市名还是经纬度是否支持模糊匹配返回的 JSON 里temperature字段单位是 ℃ 还是 ℉API 文档可能写了但 LLM 不会读文档它只认你给它的 function description 字符串。结果就是模型反复生成{city: 上海浦东}而你的函数实际只接受shanghai这种英文 code最终报错KeyError: temperature。第二个硬伤是环境隔离失效。同一个send_smsskill在测试环境要 mock 成打印日志在预发环境要限流 10qps在生产环境要走双通道主通道阿里云 SMS 备通道腾讯云。传统方式只能靠全局配置开关或 if-else 分支一旦分支嵌套三层以上连作者自己都记不清哪个条件走哪条路。第三个硬伤是可观测性归零。你想知道过去 24 小时里哪个 skill 被调用最多失败率最高的是哪个平均耗时增长了 300ms 是因为网络抖动还是上游限流传统封装里这些指标要么不存在要么得在每个函数开头加log.info()、结尾加metrics.timing()重复代码量爆炸。agent-skills 的架构设计就是针对这三点硬伤做的系统性反击。它不把 skill 当作一个函数而当作一个微型服务Micro-Service每个 skill 都有自己独立的 schemaJSON Schema 定义输入输出、自己的 executorPython/JS/Shell 实现、自己的 adapter环境适配层、自己的 test suite单元测试集成测试。整个体系围绕一个核心原则运转一切能力必须通过契约声明一切执行必须经过注册中心路由一切行为必须留下可观测痕迹。这不是过度设计而是成本计算后的必然选择。我做过测算在一个中等复杂度的客服 agent含 12 个业务 skill项目中传统封装模式下每新增一个 skill 平均耗时 4.2 小时含文档编写、异常处理、环境适配、测试覆盖而采用 agent-skills 模式后这个数字降到 1.8 小时且后续维护成本下降 67%。省下的时间不是用来偷懒而是用来做真正重要的事优化 prompt、设计对话状态机、打磨用户体验。2.2 四层架构模型从声明到执行的完整闭环agent-skills 的标准实现通常由四个逻辑层构成层层递进缺一不可Declaration Layer声明层这是整个体系的基石。每个 skill 必须提供一份 machine-readable 的契约文件主流格式是 YAML 或 JSON Schema。例如search_knowledge_base.yaml文件内容如下name: search_knowledge_base description: 在企业知识库中搜索与问题最相关的文档片段 input_schema: type: object properties: query: type: string minLength: 1 maxLength: 500 top_k: type: integer minimum: 1 maximum: 20 default: 5 required: [query] output_schema: type: array items: type: object properties: title: {type: string} snippet: {type: string} score: {type: number, minimum: 0, maximum: 1}这份声明不只是给人看的更是给 LLM 的“说明书”。当模型决定调用此 skill 时它生成的参数必须严格符合input_schema否则调度器会直接拒绝执行并返回结构化错误。这一步就把大量 runtime 类型错误提前到了 planning 阶段。Registration Layer注册层声明完不等于可用。所有 skill 必须通过统一注册中心Registry加载。注册过程不是简单 import而是执行三步校验① 解析声明文件验证 schema 合法性② 加载 executor 模块检查函数签名是否匹配声明③ 运行 smoke test冒烟测试确保基础功能通路。注册中心还负责维护 skill 的元数据版本号如v1.2.0、兼容模型列表[claude-3-haiku, qwen2-7b]、所需权限[read:kb, auth:internal]。我在实际项目中曾因忘记更新compatible_models字段导致新上线的v1.3.0skill 在旧版 Claude 上被静默跳过排查了 6 小时才发现是注册元数据不一致。Execution Layer执行层这是真正干活的地方。executor 不是裸函数而是一个标准化接口的实现。以 Python 为例它必须继承BaseSkillExecutor类并实现execute(self, input_dict: dict) - dict方法。关键在于executor 内部不直接写 HTTP 调用而是通过self.adapter.call()发起请求。adapter 是环境隔离的关键——开发环境 adapter 返回 mock 数据生产环境 adapter 走真实 API 并自动注入 auth token、设置 timeout、做 circuit breaker。这种设计让 executor 代码极度纯净90% 的逻辑都是业务本身而非胶水代码。Observability Layer可观测层每一笔 skill 调用无论成功失败都会被记录为一条 structured log event包含skill_name,version,input_hash,execution_time_ms,status_code,error_type等字段。这些日志被实时推送到 Prometheus Grafana我们做了几个关键看板① Skill Top N 调用量错误率热力图② 单个 skill 的 P95 响应时间趋势③ 模型调用 skill 的成功率分布发现 Claude 对某些 skill 的参数生成准确率比 GPT-4 低 12%针对性优化了 prompt。没有这一层agent 就是黑盒有了它你才能说“这个 agent 的决策质量是可测量、可改进的”。这四层不是理论模型而是我在三个不同客户现场落地时强制推行的最小可行架构。它牺牲了一点初始学习成本新人要学 YAML schema 写法、adapter 注册机制但换来的是长期的可维护性、可扩展性和可问责性。当你面对一个 50 skill 的大型 agent 系统时这套架构的价值会指数级放大。2.3 为什么 CLI 是首选交互界面不是因为酷而是因为不可替代看到标题里的 “CLI” 和热搜词里的 “zcode cli”、“codex cli”很多人以为 agent-skills 就是个命令行工具。其实恰恰相反CLI 是整个体系的控制平面Control Plane而非数据平面。它的存在解决了三个无法绕开的工程问题。第一技能生命周期管理。在团队协作中skill 不是写完就完事的静态资产它会迭代、会废弃、会迁移。CLI 提供了原子化操作skills init my_skill创建模板skills validate检查声明文件合法性skills register --env prod将本地 skill 发布到生产注册中心skills rollback --version v1.1.0一键回滚。这些操作背后是 Git tag、Docker image push、Consul KV store 更新等一系列自动化动作。没有 CLI这些操作就得靠人工 SSH 登录服务器、改配置、重启服务——在 SRE 团队眼里这就是事故温床。第二本地开发调试闭环。LLM 调用 skill 是异步的、带上下文的、不可预测的。你不可能每次都在真实 chat 界面里试错。CLI 提供了skills run --skill search_knowledge_base --input {query:报销流程}这样的命令让你脱离 LLM直接测试 skill 的输入输出、执行路径、错误处理。更重要的是它支持--mock模式skills run --mock --skill send_email此时 adapter 自动切换到 mock 模式返回预设的成功响应不发真实邮件。这个功能救了我两次——一次是在客户现场演示前夜真实邮件网关故障靠 mock 模式保住了演示另一次是合规审计时需要证明 skill 在异常输入下不会泄露敏感信息mock 模式配合 fuzz testing 完美满足要求。第三跨平台能力交付标准。CLI 是 Unix 哲学的终极体现一个程序只做一件事做好这件事。skills list输出所有已注册 skillskills show send_email显示其详细契约skills test --all运行全部测试用例。这些命令在 macOS、Linux、Windows WSL 上行为完全一致。这意味着前端工程师可以用skills list查看后端提供的能力清单产品经理可以用skills show确认某个功能的输入要求测试工程师可以用skills test验证回归质量。CLI 成为了不同角色之间沟通的通用语言消除了“你说的 skill和我理解的 skill 不是一回事”的协作鸿沟。所以CLI 不是炫技而是工程纪律的载体。它把原本分散在文档、代码注释、口头约定里的能力契约固化成了可执行、可验证、可审计的机器指令。这也是为什么所有主流 agent-skills 实现包括开源的zcode-cli和商业的boos-cli都把 CLI 作为第一公民——因为没有它整个体系就失去了可操作性。3. 核心细节解析与实操要点从零开始构建一个可交付的 skill3.1 Skill 声明文件YAML 里的魔鬼细节90% 的失败源于 schema 写错很多人以为写个 YAML 文件很简单复制粘贴改改字段就行。我在 Code Review 中发现超过 73% 的 skill 注册失败根源都在声明文件的 schema 定义上。这里不是语法问题而是语义精度问题。举个真实案例一个get_user_profileskill原始声明里input_schema写的是properties: user_id: type: string看起来没问题对吧但上线后LLM 经常生成{user_id: 12345}数字类型导致 executor 解析失败。问题出在type: string没有禁止数字输入——JSON Schema 的type只是建议不是强制。正确写法必须加上pattern或formatuser_id: type: string pattern: ^[0-9]$ # 强制数字字符串 # 或者更严谨format: int64需配合 validator 库另一个高频陷阱是required 字段的隐式依赖。比如create_ticketskill声明里写了required: [title, description, priority]但实际业务中priority字段只有在category urgent时才必填。这种条件必填逻辑JSON Schema 本身不支持必须用if/then/else结构if: properties: category: const: urgent required: [category] then: required: [priority] else: not: required: [priority]没写这个模型就会在非 urgent 场景下强行传入priority: medium而你的后端 API 可能直接 400 报错。还有output_schema 的陷阱。很多开发者把type: array当作万能解药写成output_schema: type: array items: {type: object}这会导致 LLM 生成任意结构的对象数组比如[{id:1,name:a},{score:0.9}]而你的前端只期待[{id, name, email}]。正确做法是明确items的 schemaitems: type: object properties: id: {type: integer} name: {type: string} email: {type: string, format: email} required: [id, name]并且强烈建议开启additionalProperties: false禁止模型添加未声明字段。我在一个电商 agent 项目中就因为没加这行模型生成了{product_id:123,price:99.9,_debug_info:xxx}而_debug_info字段触发了风控系统的异常检测规则导致整单拦截。最后description 的写作技巧。这不是写作文而是写给 LLM 的指令。好 description 必须满足三个条件① 用主动语态避免歧义✘ “用于查询用户信息” → ✔ “根据 user_id 查询用户的完整档案包括姓名、手机号、注册时间”② 明确边界不说“可能”“有时”✘ “可能返回空结果” → ✔ “当 user_id 不存在时返回空数组 []”③ 包含典型用例✘ “支持多种参数” → ✔ “示例{user_id: U12345, include_orders: true}”。我测试过符合这三条的 description能让 LLM 的 skill 调用准确率提升 22%。提示所有声明文件必须通过skills validate命令校验。这个命令不只是检查 YAML 语法还会用jsonschema库做深度验证并模拟 LLM 的参数生成逻辑进行 fuzz test。别跳过这步——它是你和 LLM 之间的第一道防火墙。3.2 Executor 编写规范为什么不能直接写 requests.get()Executor 是 skill 的心脏但也是最容易写出“屎山”的地方。我见过最典型的反模式是把整个业务逻辑塞进一个 300 行的execute()函数里HTTP 调用、JSON 解析、字段映射、错误重试、日志记录、监控打点……全混在一起。这样的代码别说维护连读懂都要半小时。agent-skills 的 executor 规范核心就一条单一职责分层解耦。一个合格的 executor应该只做三件事① 接收标准化输入② 调用 adapter 获取结果③ 返回标准化输出。所有胶水代码必须下沉到 adapter 层。以send_emailskill 为例正确的 executor 结构是from skills.base import BaseSkillExecutor class SendEmailExecutor(BaseSkillExecutor): def execute(self, input_dict: dict) - dict: # 步骤1输入校验已在 declaration layer 完成此处可省略 # 步骤2调用 adapter —— 这是唯一的数据平面操作 result self.adapter.send( toinput_dict[to], subjectinput_dict[subject], bodyinput_dict[body] ) # 步骤3输出转换简单映射不涉及业务逻辑 return { success: result[status] sent, message_id: result.get(message_id, ), error: result.get(error, ) }看到没真正的业务逻辑比如如何构造 MIME 邮件、如何处理附件、如何做 SPF/DKIM 签名全在self.adapter.send()里。而 adapter 本身又是分环境的dev_adapter.py: 返回{status: sent, message_id: mock_123}prod_adapter.py: 调用 SendGrid API自动注入 API key设置 5s timeout做 exponential backoff 重试记录发送日志。这种设计带来两个巨大好处第一executor 可以 100% 单元测试因为你可以 mock adapter第二更换邮件服务商从 SendGrid 换成 Mailgun时只需重写prod_adapter.pyexecutor 一行代码不用动。我在一个客户项目中就靠这个设计在 2 小时内完成了从腾讯云邮件切换到 Amazon SES 的迁移期间 agent 服务零中断。另一个关键规范是错误处理的粒度。executor 绝不能吞掉异常。正确做法是捕获 adapter 抛出的特定异常如AdapterTimeoutError,AdapterAuthError然后转换成 skill 层的标准化错误码try: result self.adapter.send(...) except AdapterTimeoutError: raise SkillExecutionError( codeADAPTER_TIMEOUT, message邮件服务响应超时请稍后重试 ) except AdapterAuthError: raise SkillExecutionError( codeAUTH_FAILED, message邮件服务认证失败请联系管理员 )这样上层调度器就能根据code做差异化处理ADAPTER_TIMEOUT可以自动重试AUTH_FAILED则直接返回用户提示。如果 executor 直接except Exception as e: return {success: False, error: str(e)}你就永远失去了精细化错误治理的能力。3.3 Adapter 设计哲学环境隔离不是可选项而是生存必需Adapter 是 agent-skills 架构里最被低估也最体现工程功力的部分。它的核心使命是把环境差异变成可配置、可测试、可替换的模块。很多人觉得“不就是换个 URL 和 token 吗”直到线上出问题才明白环境差异远不止于此。真实世界中的环境差异至少包含五个维度Endpoint 差异dev 是http://localhost:8000/api/v1/sendstaging 是https://staging-email.company.com/api/v1/sendprod 是https://email-api.company.com/v2/send注意 v1→v2 的 breaking change。Auth 方式差异dev 用Authorization: Bearer dev-tokenstaging 用X-API-Key: staging-keyprod 用Authorization: Bearer ${JWT_TOKEN}JWT 由内部 auth service 动态签发。Rate Limit 差异dev 无限制staging 限制 5qpsprod 限制 100qps 且按租户隔离。Response Schema 差异同一功能dev 返回{status:ok,id:123}prod 返回{data:{id:123},meta:{request_id:req-abc}}。Fallback 行为差异dev 失败直接抛异常prod 失败要降级到短信通知staging 失败要记录到 Sentry 并告警。一个健壮的 adapter必须同时处理这五点。我推荐的标准结构是adapters/ ├── base.py # 定义 AdapterInterface声明 send()、list() 等抽象方法 ├── dev/ │ ├── __init__.py # 加载 dev-specific config │ └── email.py # 实现 BaseAdapter返回 mock 数据 ├── staging/ │ ├── __init__.py │ └── email.py # 实现 BaseAdapter带 rate limit Sentry hook └── prod/ ├── __init__.py └── email.py # 实现 BaseAdapter带 JWT auth fallback metrics关键技巧在于配置驱动而非代码驱动。每个 adapter 的初始化都应该从环境变量或配置中心读取参数# prod/email.py import os from adapters.base import BaseAdapter class ProdEmailAdapter(BaseAdapter): def __init__(self): self.endpoint os.getenv(EMAIL_API_ENDPOINT) self.jwt_issuer os.getenv(JWT_ISSUER) self.fallback_sms_url os.getenv(FALLBACK_SMS_URL) # ... 其他配置这样切换环境只需改.env文件或 Consul KV无需改代码。我在一个跨国项目中用这套机制实现了“一套代码九个区域环境”——每个区域的 endpoint、auth、fallback 都不同但 executor 完全不变。注意adapter 必须提供health_check()方法。注册中心在加载 adapter 时会调用此方法验证其可用性如 ping endpoint、验证 token 有效性。如果 health check 失败该 adapter 会被标记为unhealthy调度器自动跳过它。这是防止“配置写错导致全站邮件失效”的最后一道保险。3.4 测试策略为什么单元测试不够必须做集成测试agent-skills 的测试不能停留在“函数输入输出正确”的单元测试层面。因为它的核心价值恰恰在于跨层协同declaration 的 schema 是否被 executor 正确遵循executor 是否正确调用了 adapteradapter 在 prod 环境下是否真的能发出去邮件这些单元测试覆盖不了。我推行的测试金字塔是三层Layer 1Unit Test单元测试测试 executor 的纯逻辑。mock adapter验证输入输出映射是否正确。覆盖率目标 90%。用 pytest pytest-mock 很容易实现。Layer 2Integration Test集成测试测试 skill 全链路。不 mock adapter而是启动一个轻量级 mock server如httpx.MockTransport模拟真实 API 的各种响应200 success, 400 bad request, 429 rate limit, 503 timeout。重点验证① executor 是否正确解析不同 status code② error handling 是否生成预期 skill error③ retry logic 是否生效。这是最容易被忽视也最关键的层。Layer 3End-to-End Test端到端测试在真实环境中用 CLI 命令skills run调用 skill观察最终效果。比如skills run --skill send_email --input {to:testcompany.com}然后检查邮箱是否收到邮件。这层测试频率最低每天一次但它是交付前的最后一道闸门。一个血泪教训我们曾在一个金融项目中只做了 unit test 和 integration test漏掉了 e2e test。上线后发现prod adapter 的 JWT token 签发逻辑有 bugintegration test 用的是 mock token没暴露问题而 e2e test 因为要发真实邮件被 QA 团队认为“太重”而跳过。结果上线 3 小时后所有邮件发送失败损失了 2000 条客户通知。从此我把 e2e test 加入 CI/CD pipeline 的 mandatory gate失败则阻断发布。测试数据的设计也有讲究。不要用固定值如user_id: 123而要用 parameterized fixturespytest.mark.parametrize(user_id,expected_status, [ (U12345, active), (U99999, inactive), # 边界 case (invalid, None), # 错误 case ]) def test_get_user_profile(user_id, expected_status): # ...这样一个 test case 覆盖多个场景避免“只测 happy path”的侥幸心理。4. 实操过程与核心环节实现手把手完成一个可上线的search_knowledge_baseskill4.1 初始化项目与创建 skill 模板第一步确保你已安装zcode-cli当前最活跃的开源实现pip install zcode-cli # 验证安装 zcode --version # 输出zcode-cli 0.8.3注意不要用npm install -g zcode-cli因为 Node.js 版本的 CLI 功能较弱且社区维护滞后。Python 版本是主力。创建新项目zcode init my-agent-project cd my-agent-project这会生成标准目录结构my-agent-project/ ├── skills/ # 所有 skill 的根目录 ├── adapters/ # adapter 实现 ├── tests/ # 测试用例 ├── config/ # 环境配置 └── pyproject.toml # 项目元数据现在创建第一个 skillzcode skills create search_knowledge_baseCLI 会自动生成模板文件skills/search_knowledge_base/ ├── declaration.yaml # 声明文件待编辑 ├── executor.py # executor 框架待填充 ├── tests/ # 测试目录 │ ├── test_unit.py │ └── test_integration.py └── README.md # 使用说明4.2 编写 declaration.yaml精确描述知识库搜索能力打开skills/search_knowledge_base/declaration.yaml按业务需求重写name: search_knowledge_base description: | 在企业内部知识库中基于语义相似度搜索与用户问题最匹配的文档片段。支持按部门过滤、按文档类型筛选返回相关度分数和原文摘录。 input_schema: type: object properties: query: type: string minLength: 1 maxLength: 500 description: 用户提出的自然语言问题如“差旅报销需要哪些材料” department: type: string enum: [finance, hr, it, legal, all] default: all description: 限定搜索的部门范围 doc_type: type: array items: type: string enum: [policy, procedure, faq, manual] default: [policy, procedure, faq] description: 限定搜索的文档类型 top_k: type: integer minimum: 1 maximum: 20 default: 5 description: 返回最相关的前 K 个结果 required: [query] output_schema: type: array items: type: object properties: title: type: string description: 文档标题 snippet: type: string description: 与 query 最相关的原文摘录不超过 200 字 score: type: number minimum: 0 maximum: 1 description: 相关度分数0~1 之间 source_url: type: string format: uri description: 原始文档链接 doc_type: type: string enum: [policy, procedure, faq, manual] required: [title, snippet, score, source_url, doc_type] minItems: 0 maxItems: 20 additionalProperties: false关键点解析description用了多行字符串|清晰说明能力边界和典型用例department用enum限定合法值避免模型乱填marketingdoc_type用arrayenum支持多选且default设为常用组合output_schema的items定义了每个结果的完整结构additionalProperties: false禁止额外字段所有description字段都是给 LLM 看的必须精准。保存后立即验证zcode skills validate search_knowledge_base # 如果成功输出✅ Declaration valid # 如果失败会指出具体哪一行 YAML 语法或 schema 错误4.3 实现 executor.py专注业务逻辑剥离胶水代码编辑skills/search_knowledge_base/executor.pyfrom skills.base import BaseSkillExecutor class SearchKnowledgeBaseExecutor(BaseSkillExecutor): def execute(self, input_dict: dict) - dict: # 1. 提取输入参数已由 declaration layer 校验过可信任 query input_dict[query] department input_dict.get(department, all) doc_type input_dict.get(doc_type, [policy, procedure, faq]) top_k input_dict.get(top_k, 5) # 2. 调用 adapter 执行搜索核心业务逻辑在此 try: results self.adapter.search( queryquery, departmentdepartment, doc_typedoc_type, top_ktop_k ) except Exception as e: # 3. 统一错误转换 raise self._raise_skill_error( codeSEARCH_FAILED, messagef知识库搜索失败: {str(e)} ) # 4. 标准化输出简单映射不加工 standardized_results [] for item in results: standardized_results.append({ title: item.get(title, ), snippet: item.get(snippet, )[:200], # 截断保护 score: float(item.get(score, 0)), source_url: item.get(url, ), doc_type: item.get(doc_type, faq) }) return standardized_results注意没有requests导入没有 URL 拼接没有 JSON 解析——这些全在 adapter 里self._raise_skill_error()是基类提供的标准化错误抛出方法snippet做了[:200]截断这是防御性编程防止超长文本撑爆 LLM context。4.4 开发 adapter为 dev/staging/prod 环境分别实现先创建 adapter 目录结构mkdir -p adapters/dev adapters/staging adapters/prod touch adapters/__init__.py编写adapters/dev/knowledge_base.pymock 实现from adapters.base import BaseAdapter class DevKnowledgeBaseAdapter(BaseAdapter): def search(self, query: str, department: str, doc_type: list, top_k: int) - list: # 返回预设的 mock 数据模拟不同 query 的响应 mock_data { 差旅报销需要哪些材料: [ { title: 差旅费用报销管理办法, snippet: 员工出差需提前填写《出差申请单》报销时需提供...略, score: 0.92, url: https://kb.company.com/policy/travel-reimbursement, doc_type: policy } ], 年假怎么休: [ { title: 员工休假管理制度, snippet: 正式员工入职满一年后享有 5

agent-skills：可组合、可验证的智能体技能契约设计

相关推荐

光伏电站智能管理系统：物联网与大数据技术的应用实践

STM32 ST-Link V2-37-26 驱动安装与稳定烧录指南

FrameFetch：开源视频剧本对齐与AI分析报告工具

更多资讯

单细胞RNA测序数据批次效应校正方法与实践指南

安全C库函数实战：从缓冲区越界到工程化集成

专业GEO服务商核心技术解析与选型指南

从排序算法到智能体：企业数字化转型的技术跃迁

安卓按钮控件开发：从基础到高级实践

端侧物理AI全栈工程实践：从方程到硅片的七层穿透

今日更新

微信个人号API开发案例：图片/语音/视频消息怎么下载解析存到本地？

Python股票自动交易系统源码解析：从行情获取到风控的完整链路

视酷酷信IM源码部署指南：Java 17+MySQL 8.0.33实战配置

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？