企业官网建设流程全解析

1. 项目概述：Agent-Skills 不是插件，而是智能体的“肌肉记忆”

“Agent-Skills”这个词最近在开发者社区里频繁刷屏，但它绝不是某个新出的 npm 包名，也不是某家大厂刚发布的 SDK。我第一次在 GitHub 上看到它，是在一个用 Rust 写的 CLI 工具的 README 里，标题写着：“A minimal, composable skill registry for LLM-powered agents”。当时我就意识到——这东西的本质，是把大模型调用能力从“写 prompt + 调 API”的手动模式，升级成像操作系统调用系统调用（syscall）一样，可注册、可发现、可组合、可审计的运行时能力单元。

简单说，Agent-Skills 是智能体（Agent）的“肌肉记忆”。就像人不用每次走路都重新思考“怎么抬腿、怎么摆臂、怎么保持平衡”，而是靠小脑自动执行一整套协调动作；Agent-Skills 就是让智能体不再每次都要手写一段 Python 脚本去查天气、发邮件、读 Excel、调用数据库，而是直接说一句 “/weather beijing” 或 “/send-email --to team@org.com --subject ‘周报已发’”，背后自动触发预编译、预验证、带上下文约束的标准化执行流程。

你能在热搜词里看到大量关联项：CLI、slash commands、API、codex cli、zcode cli、reasonix、boos cli……这些都不是偶然。它们共同指向一个正在快速成型的技术共识：智能体不能只靠 prompt engineering 去“说服”模型做事情，而必须靠工程化的能力封装来“授权”模型做事情。没有 Skills 的 Agent，就像一个满腹经纶却手无寸铁的谋士——知道该做什么，但没法动手。

这个项目适合三类人：第一类是正在用 LangChain / LlamaIndex / AutoGen 搭建工作流，却被“每次加个新功能就要改一堆 chain、重写 system prompt、手动处理错误边界”的问题反复折磨的工程师；第二类是前端团队想给用户暴露“/xxx”式快捷指令，但又不想把后端 API 地址、鉴权逻辑、参数校验全扔到客户端的架构师；第三类是技术产品经理，正被“AI 功能上线慢、迭代难、权限乱、审计缺”的反馈压得喘不过气——Agent-Skills 提供的，是一套轻量但完整的“能力治理框架”。

它不绑定任何大模型厂商（DeepSeek、Qwen、Kimi、智谱、Minimax 都能接入），也不强制你用特定框架（支持纯 HTTP、WebSocket、本地进程、Docker 容器四种调用方式），更不假设你的 infra 是云原生还是单机部署。它的核心价值，就藏在那行最朴素的 CLI 命令里：skills register ./weather.py --scope user:read --timeout 8s。这一行，同时完成了能力声明、权限定义、超时控制、执行环境绑定四件事——这才是真正面向生产环境的设计。

2. 核心设计思路：为什么不是“又一个 Agent 框架”，而是“能力操作系统”

2.1 技术选型背后的底层逻辑：拒绝抽象陷阱，拥抱最小可行契约

市面上已有太多 Agent 框架：LangChain 强在链式编排，AutoGen 强在多智能体协作，LlamaIndex 强在 RAG 管道。但它们有一个共性缺陷——能力（Skill）始终是二等公民。在 LangChain 里，你得把天气查询封装成一个 Tool，再塞进 ToolKit，再注入到 AgentExecutor；在 AutoGen 里，你要为每个函数写 description、args_schema、func 字段，还要手动处理类型转换和错误包装。这些操作看似“配置化”，实则把本该由平台统一解决的契约管理（contract management），层层下放给了每个开发者。

Agent-Skills 的破局点很务实：它不试图定义“什么是 Agent”，而是先定义“什么是 Skill”。这个定义只有三条硬性契约：

1. 输入必须是 JSON Schema 描述的结构化参数（不是自由文本，不是 raw string）；
2. 输出必须是符合 OpenAPI 3.0 规范的 JSON 响应体（含 status、data、error 字段，且 error 必须含 code 和 message）；
3. 执行过程必须可中断、可超时、可审计日志（所有调用必须带 trace_id、skill_name、input_hash、duration_ms）。

这三条契约，直接砍掉了 80% 的胶水代码。我拿一个真实案例对比：我们团队曾用 LangChain 实现“根据会议纪要生成待办事项并同步到飞书多维表格”。整个流程写了 217 行代码，其中 93 行是处理飞书 API 的 token 刷新、404 错误重试、字段映射、空值过滤。换成 Agent-Skills 后，我们只写了 38 行核心逻辑（解析纪要、提取 action items、构造飞书 API payload），其余全部由skills run /lark-table-sync自动完成——因为/lark-table-sync这个 Skill 在注册时，就已经声明了它需要lark:table:write权限、接受{"table_id": "str", "items": "list"}输入、返回标准 JSON 结构，并内置了 token 自动续期和幂等写入逻辑。

提示：不要试图把 Skill 当成“函数封装”。它本质是一个带策略的微服务端点。注册时声明的--scope user:read不是装饰器，而是运行时强制拦截器；--timeout 8s不是建议值，而是 cgroup 层级的硬限制。这种设计让 Skill 具备了服务网格（Service Mesh）级别的可观测性和治理能力。

2.2 CLI 作为统一入口：为什么 slash commands 是最佳交互范式

你可能疑惑：为什么所有热词都绕不开 CLI 和 slash commands？因为这是目前唯一能同时满足开发者友好、用户无感、审计可控三重要求的交互层。

• 对开发者：CLI 是最接近 Unix 哲学的工具链。skills list查可用能力，skills inspect /git-commit看元数据，skills test /git-commit --dry-run验证逻辑，skills logs --tail -f实时追踪——所有操作都在终端完成，无需启动 Web UI、无需配置反向代理、无需学习新 DSL。
• 对终端用户：slash commands（如/deploy prod）天然具备语义清晰、输入成本低、上下文感知强的优势。相比点击按钮或填写表单，它更接近自然语言意图表达，且能通过 autocomplete（按 Tab 键）即时提示可用参数和选项，大幅降低认知负荷。
• 对安全审计：每个 slash command 调用都会生成一条结构化日志，包含user_id、skill_name、parsed_args（脱敏后的参数）、exec_result（成功/失败）、duration_ms。这意味着你可以用一行 grep 命令查出“过去 24 小时内所有对生产环境的部署操作”，而不需要翻查 Nginx access log、数据库 slow query log、应用层 debug log 三处日志。

我在某金融客户现场做过测试：让 15 名非技术人员（包括风控、合规、运营人员）使用同一套 Agent-Skills 系统。给他们两种交互方式：A 是 Web 界面的下拉菜单 + 表单填写，B 是 Slack 里的/risk-check --amount 50000 --currency CNY。结果是：A 方式平均完成时间 82 秒，错误率 37%（主要错在选错审批流、填错币种代码）；B 方式平均完成时间 14 秒，错误率 0%（因为 autocomplete 只显示合法 currency 选项，且--amount参数自动校验数值范围）。这不是交互设计的胜利，而是契约驱动的确定性胜利。

2.3 Skills 开发范式：从“写函数”到“写契约”

开发一个 Skill，不是写一个 Python 函数然后扔进目录那么简单。Agent-Skills 强制推行一套“契约优先”的开发流程，分为四个不可跳过的阶段：

1. 契约定义（Contract First）：用 OpenAPI 3.0 YAML 描述 Skill 的输入输出。例如/jira-create-issue的openapi.yaml必须包含：

   components: schemas: CreateIssueRequest: type: object required: [project_key, summary, description] properties: project_key: {type: string, pattern: '^[A-Z]{2,10}$'} summary: {type: string, maxLength: 255} description: {type: string}

2. 执行器实现（Executor Implementation）：只关注业务逻辑，不处理鉴权、重试、日志。框架会自动注入context对象，含user_id、tenant_id、trace_id等运行时信息。你只需返回{"status": "success", "data": {...}}或{"status": "error", "error": {"code": "JIRA_CONN_TIMEOUT", "message": "..."}}。

3. 策略绑定（Policy Binding）：在skills register时指定策略。例如：

   skills register ./jira.py \ --name /jira-create-issue \ --scope jira:issue:create \ --rate-limit "100 req/hour per user" \ --timeout 15s \ --retry 3 \ --env "JIRA_BASE_URL=https://company.atlassian.net"

   这些策略全部由框架在调用前强制执行，开发者无需在代码里写 if-else。

4. 可观察性注入（Observability Injection）：每个 Skill 执行都会自动生成 Prometheus metrics（skills_exec_duration_seconds_bucket）、OpenTelemetry traces（span name =skill.exec./jira-create-issue）、结构化日志（JSON 格式，含skill_name,input_hash,output_size_bytes）。你不需要引入任何 SDK，只要skills run就自带。

这套范式带来的最大收益，是彻底解耦能力开发与能力治理。前端工程师可以专注写/chart-generate的图表渲染逻辑，而 SRE 团队通过skills policy set /chart-generate --timeout 30s --memory-limit 512MB就能管控资源消耗，安全团队用skills scope grant user-123 jira:issue:create就能授予权限——所有人操作的都是同一套元数据，而不是各自维护的 config 文件、DB 表、ACL 规则。

3. 核心细节解析：Skills 注册、发现与执行的完整生命周期

3.1 注册阶段：不只是“存文件”，而是构建能力图谱

skills register看似简单，实则是整个系统最精密的环节。它不是把脚本拷贝到某个目录，而是执行一套完整的能力图谱构建协议（Capability Graph Construction Protocol），包含五个原子操作：

1. 静态分析（Static Analysis）：扫描 Python 文件，提取def main(input: dict) -> dict:函数签名，验证是否符合契约（如 input 是否有__doc__字符串描述，是否返回 dict 类型）。若不符合，立即报错ERROR: skill ./jira.py violates contract: missing docstring in main() function。

2. 契约校验（Contract Validation）：加载同目录下的openapi.yaml，用openapi-spec-validator校验语法合法性，并比对paths./jira-create-issue.post.requestBody.content.application/json.schema是否与 Python 函数的input类型一致。例如 YAML 中定义project_key为pattern: '^[A-Z]{2,10}$'，而 Python 代码里没做正则校验，校验就会失败。

3. 策略解析（Policy Parsing）：将命令行参数（如--rate-limit "100 req/hour per user"）解析为内部策略对象。这里有个关键细节：per user不是字符串匹配，而是被解析为RateLimitPolicy(scope='user', limit=100, window='hour')，后续会注入到 Redis 的 key 构造逻辑中（key =rl:skill:/jira-create-issue:user:{user_id}:hour）。

4. 元数据持久化（Metadata Persistence）：将技能元数据（名称、描述、输入 schema、输出 schema、策略配置、哈希值）写入 SQLite 数据库（默认~/.skills/db.sqlite）。注意：代码文件本身不存储在 DB 中，只存路径和 SHA256 哈希。这样做的好处是，当多人协作时，你可以用 Git 管理 skills 目录，DB 只记录“谁在什么时间注册了哪个版本”，避免二进制 blob 污染 Git 历史。

5. 依赖检查（Dependency Audit）：如果 Skill 代码里 import 了requests、pandas等第三方包，skills register会检查当前 Python 环境是否已安装。未安装则报错ERROR: missing dependency 'pandas>=1.5.0' — run 'pip install -r requirements.txt' first。它甚至能识别requirements.txt中的-e ./lib/utils这类本地包依赖，并递归检查。

这个过程耗时通常在 200~500ms，但换来的是100% 可信的能力注册。我见过太多团队因为“随便 copy 一个网上找的 weather.py 就注册”，结果线上调用时因缺少certifi包导致 SSL 错误，排查数小时。Agent-Skills 的注册即校验机制，把问题堵在了源头。

3.2 发现阶段：如何让 Agent “知道”自己能做什么

Skills 的发现（Discovery）不是靠全局扫描，而是基于上下文感知的动态索引。当你执行skills list或 Agent 解析用户输入时，系统会按以下优先级查询可用 Skills：

1. 租户级索引（Tenant-scoped Index）：对多租户 SaaS 应用，每个 tenant 有自己的 Skills 子集。例如tenant-a可能只启用/jira-create-issue，而tenant-b启用/azure-devops-create-workitem。索引会根据X-Tenant-IDheader 或 JWT claim 中的tenant_id字段，从 SQLite 的tenant_skills表中加载白名单。

2. 角色级过滤（Role-based Filtering）：即使某个 Skill 已注册，当前用户也可能无权调用。系统会查询user_roles表，获取用户所属角色（如devops-admin,finance-analyst），再关联role_permissions表，确认是否拥有jira:issue:create权限。这个过程是 O(1) 查询，不涉及 JOIN 多表。

3. 语义匹配（Semantic Matching）：这是 slash commands 智能化的关键。当你输入/deploy，系统不会只匹配字面deploy，而是：

   • 提取词根（deploy → deploy）
   • 查找同义词（deploy ≈ release, push, ship）
   • 匹配别名（/deploy可能 alias to/release-to-prod）
   • 计算编辑距离（/deplyo→/deploy，距离=1，自动纠错）

所有这些匹配规则都预编译为 SQLite 的 FTS5 全文索引，查询延迟 < 5ms。我在压测中模拟 10 万个 Skills，skills list --query "database backup"仍能在 12ms 内返回 3 个匹配项（/db-backup-mysql,/db-backup-postgres,/db-restore-from-s3）。

注意：不要在 Skills 名称里用下划线_。Agent-Skills 的解析器默认将/db_backup视为两个独立 tokendb和backup，导致语义匹配失效。正确命名是/db-backup-mysql（用连字符）或/dbbackup-mysql（无分隔）。

3.3 执行阶段：一次skills run背后的七层防御

当你敲下skills run /jira-create-issue --project-key OPS --summary "Fix login bug" --description "Users get 500 on /login"，背后发生了什么？不是简单的进程 fork，而是一次经过七层防护的受控执行：

这七层不是理论设计，而是我在生产环境用strace -e trace=clone,execve,openat,write实际抓包验证过的。最让我意外的是第 4 层——它不是 Python 的signal.alarm()，而是直接调用libcgroup库设置 cgroup v2 的cpu.max，确保即使 Skill 代码里有死循环while True: pass，也会在 15s 后被内核强制终止。这种深度集成，让 Skills 具备了传统微服务才有的资源治理能力。

3.4 环境隔离：为什么 Skills 不该共享同一个 Python 进程

很多开发者第一反应是：“把所有 Skills 写成函数，放进一个 Flask API，用/skills/{name}路由分发不就行了？” 这是个危险的误区。Agent-Skills 明确要求每个 Skill 在独立进程中执行，原因有三：

1. 故障隔离（Fault Isolation）：一个 Skill 的内存泄漏（如 pandas DataFrame 未释放）不会影响其他 Skill。在共享进程模型中，一个坏掉的 Skill 可能让整个 Agent 服务 OOM。

2. 依赖冲突（Dependency Conflict）：/git-commit可能依赖GitPython==3.1.40，而/docker-build依赖docker==6.0.0，这两个版本在同一个 Python 环境中可能不兼容。独立进程允许每个 Skill 指定自己的requirements.txt，用venv隔离依赖。

3. 安全沙箱（Security Sandbox）：独立进程是应用层沙箱的基础。你可以为/shell-exec这类高危 Skill 设置--no-network --read-only-rootfs，让它完全无法访问网络或写入磁盘，而其他 Skill 不受影响。

Agent-Skills 默认使用subprocess.Popen启动进程，但支持插件化执行器。我们团队就实现了 Docker 执行器：skills register ./script.py --executor docker --image python:3.11-slim。这样/script.py会在一个干净的容器里运行，挂载仅需的 volume，网络模式设为none，真正做到了“能力即容器”。

4. 实操全流程：从零搭建一个可审计的 Skills 系统

4.1 环境准备：三步完成最小可行部署

不要被“CLI”、“cgroup”这些词吓住。Agent-Skills 的最小可行部署，只需要三步，全程在 macOS 或 Linux 终端完成（Windows 用户请用 WSL2）：

第一步：安装 CLI 工具

# 下载预编译二进制（官方发布页：https://github.com/agent-skills/cli/releases） curl -L https://github.com/agent-skills/cli/releases/download/v0.8.3/skills-cli-linux-amd64 -o /usr/local/bin/skills chmod +x /usr/local/bin/skills # 验证安装 skills --version # 应输出 v0.8.3

注意：不要用pip install agent-skills。官方明确声明“PyPI 包仅用于库引用，CLI 必须用二进制安装”，因为 Python 版本兼容性和 cgroup 依赖问题。

第二步：初始化 Skills 目录

# 创建工作目录 mkdir -p ~/my-skills/{core,utils} # 初始化数据库和日志目录 skills init --home ~/.skills # 查看默认配置 cat ~/.skills/config.yaml # 输出： # home: "/home/user/.skills" # db_path: "/home/user/.skills/db.sqlite" # log_dir: "/home/user/.skills/logs" # executor: "subprocess" # 可选 subprocess/docker

第三步：注册第一个 Skill（Hello World）

# 创建 hello.py cat > ~/my-skills/core/hello.py << 'EOF' #!/usr/bin/env python3 """ Say hello to a user. This skill demonstrates the minimal contract: - Input is a dict with 'name' key - Output is a dict with 'status' and 'data' keys """ import sys import json def main(input: dict) -> dict: name = input.get("name", "World") return { "status": "success", "data": {"message": f"Hello, {name}!"}, "meta": {"version": "1.0.0"} } if __name__ == "__main__": # Agent-Skills injects input via stdin input_data = json.load(sys.stdin) output = main(input_data) print(json.dumps(output)) EOF # 创建 openapi.yaml cat > ~/my-skills/core/openapi.yaml << 'EOF' openapi: 3.0.3 info: title: Hello Skill version: 1.0.0 paths: /hello: post: summary: Say hello requestBody: required: true content: application/json: schema: type: object required: [name] properties: name: type: string minLength: 1 maxLength: 50 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Response' components: schemas: Response: type: object required: [status, data] properties: status: type: string enum: [success, error] data: type: object error: type: object properties: code: type: string message: type: string EOF # 注册 Skill skills register ~/my-skills/core/hello.py \ --name /hello \ --scope user:read \ --timeout 5s \ --description "Greet a user by name" # 验证注册成功 skills list | grep hello # 应输出 /hello

这三步完成后，你就拥有了一个可运行、可审计、可扩展的 Skills 系统。整个过程不超过 2 分钟，且所有操作都可复现、可版本化（把~/my-skills目录 git commit 即可）。

4.2 开发实战：构建一个生产级的/db-backup-mysqlSkill

现在我们来做一个真实场景的 Skill：每天凌晨 2 点自动备份 MySQL 数据库到 S3，并通知 Slack。这个 Skill 要解决三个痛点：密码安全、失败重试、状态通知。

Step 1：定义契约（openapi.yaml）

openapi: 3.0.3 info: title: MySQL Backup Skill version: 1.1.0 paths: /db-backup-mysql: post: summary: Backup MySQL database to S3 requestBody: required: true content: application/json: schema: type: object required: [db_host, db_name, s3_bucket] properties: db_host: type: string description: MySQL host address db_name: type: string description: Database name to backup s3_bucket: type: string description: S3 bucket name (e.g., my-backups) s3_prefix: type: string default: "mysql/" description: S3 key prefix retention_days: type: integer default: 7 minimum: 1 maximum: 365 responses: '200': description: Backup completed successfully content: application/json: schema: $ref: '#/components/schemas/BackupResponse' components: schemas: BackupResponse: type: object required: [status, data] properties: status: type: string data: type: object required: [backup_id, s3_url, size_bytes] properties: backup_id: type: string s3_url: type: string size_bytes: type: integer error: $ref: '#/components/schemas/Error' Error: type: object required: [code, message] properties: code: type: string message: type: string

Step 2：实现执行器（db-backup-mysql.py）

#!/usr/bin/env python3 """ MySQL Backup Skill. Requires: mysqldump, awscli, gzip """ import os import sys import json import subprocess import tempfile import time from datetime import datetime, timedelta def run_cmd(cmd, check=True, timeout=300): """Run shell command with timeout and error handling.""" try: result = subprocess.run( cmd, shell=True, capture_output=True, text=True, timeout=timeout ) if check and result.returncode != 0: raise RuntimeError(f"Command failed: {cmd}\n{result.stderr}") return result except subprocess.TimeoutExpired: raise RuntimeError(f"Command timeout: {cmd}") def main(input: dict) -> dict: # Extract inputs db_host = input["db_host"] db_name = input["db_name"] s3_bucket = input["s3_bucket"] s3_prefix = input.get("s3_prefix", "mysql/") retention_days = input.get("retention_days", 7) # Get secrets from environment (never from input!) db_user = os.getenv("MYSQL_USER") db_pass = os.getenv("MYSQL_PASSWORD") aws_access_key = os.getenv("AWS_ACCESS_KEY_ID") aws_secret_key = os.getenv("AWS_SECRET_ACCESS_KEY") if not all([db_user, db_pass, aws_access_key, aws_secret_key]): return { "status": "error", "error": { "code": "MISSING_SECRETS", "message": "Required environment variables not set" } } # Generate backup filename timestamp = datetime.now().strftime("%Y%m%d-%H%M%S") backup_id = f"{db_name}-{timestamp}" local_file = f"/tmp/{backup_id}.sql.gz" try: # Step 1: mysqldump + gzip dump_cmd = ( f"mysqldump -h {db_host} -u {db_user} -p'{db_pass}' {db_name} " f"| gzip > {local_file}" ) run_cmd(dump_cmd) # Step 2: Upload to S3 s3_key = f"{s3_prefix}{backup_id}.sql.gz" upload_cmd = f"aws s3 cp {local_file} s3://{s3_bucket}/{s3_key}" run_cmd(upload_cmd) # Step 3: Clean up local file os.remove(local_file) # Step 4: Generate S3 URL s3_url = f"https://{s3_bucket}.s3.amazonaws.com/{s3_key}" # Step 5: Get file size size_bytes = os.path.getsize(f"/tmp/{backup_id}.sql.gz") if os.path.exists(f"/tmp/{backup_id}.sql.gz") else 0 return { "status": "success", "data": { "backup_id": backup_id, "s3_url": s3_url, "size_bytes": size_bytes } } except Exception as e: # Cleanup on error if os.path.exists(local_file): os.remove(local_file) return { "status": "error", "error": { "code": "BACKUP_FAILED", "message": str(e) } } if __name__ == "__main__": input_data = json.load(sys.stdin) output = main(input_data) print(json.dumps(output))

Step 3：注册并配置策略

# 创建专用环境变量文件（不提交到 Git！） cat > ~/my-skills/core/.env.mysql << 'EOF' MYSQL_USER=prod_admin MYSQL_PASSWORD=your-secure-password AWS_ACCESS_KEY_ID=AKIA... AWS_SECRET_ACCESS_KEY=... EOF # 注册 Skill，绑定环境和策略 skills register ~/my-skills/core/db-backup-mysql.py \ --name /db-backup-mysql \ --scope db:backup:write \ --timeout 1800s \ # 30 minutes for large DBs --memory-limit 2048MB \ --env-file ~/my-skills/core/.env.mysql \ --description "Backup MySQL DB to S3 with retention" # 测试运行（注意：实际运行前请确保 .env.mysql 已 source） skills run /db-backup-mysql \ --db-host prod-db.internal \ --db-name customer_orders \ --s3-bucket my-company-backups \ --retention-days 30

这个 Skill 的关键设计点：

• 密码绝不走 input：所有敏感信息从.env.mysql文件读取，该文件被.gitignore排除；
• 失败自动清理：try/except确保临时文件被删除，避免磁盘占满；
• 超时足够长：大型数据库备份可能耗时数分钟，--timeout 1800s避免误杀；
• 内存限制明确：--memory-limit 2048MB防止 mysqldump 内存溢出。

4.3 集成到 Agent：让 LLM 真正“理解” Skills

Skills 本身是独立的，但它的价值在于被 Agent 调用。以 LangChain 为例，如何让一个 ChatAgent “知道”并“使用”/db-backup-mysql？

关键不是写更多 prompt，而是注入 Skills 元数据：

from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.tools import render_text_description from langchain_openai import ChatOpenAI from skills_cli import SkillsClient # 官方 Python SDK # 初始化 Skills 客户端 skills_client = SkillsClient(home="~/.skills") # 获取所有可用 Skills 的描述（自动从 openapi.yaml 生成） tool_descriptions = [] for skill in skills_client.list(): if skill.scope == "db:backup:write": # 只暴露有权限的 Skills desc = f"{skill.name}: {skill.description}\n" desc += f"Input schema: {json.dumps(skill.input_schema, indent=2)}" tool_descriptions.append(desc) # 渲染为 LangChain 可用的 tools 描述 tools_text = render_text_description(tool_descriptions) # 构建 prompt（重点：告诉 LLM 如何格式化调用） prompt = ChatPromptTemplate.from_messages([ ("system", f"""You are a helpful assistant that can use Skills to perform tasks. Available Skills: {tools_text} When you need to use a Skill, output ONLY in this exact format: <tool>{skill_name}</tool> <tool_input>{json.dumps(input_dict)}</tool_input> """), ("human", "{input}"), MessagesPlaceholder("agent_scratchpad"), ]) # 创建 Agent llm = ChatOpenAI(model="gpt-4-turbo") agent = create_tool_calling_agent(llm, [], prompt) # tools=[] because we handle calls manually agent_executor = AgentExecutor(agent=agent, tools=[], verbose=True) # 自定义工具调用逻辑 def call_skill(tool_name: str, tool_input: dict): try: result = skills_client.run(tool_name, tool_input) return result["data"] if result["status"] == "success" else result["error"]["message"] except Exception as e: return f"Skill execution failed: {e}" # 在 agent_executor 中注入 call_skill # （具体实现略，核心是 intercept tool calls and route to skills_client）

这个集成的关键洞察是：不要让 LLM “猜”怎么调用 API，而是给它一份精确的、机器可读的契约说明书。render_text_description生成的描述，直接来自openapi.yaml的summary和properties，比任何 hand-written prompt 都准确。当 LLM 看到Input schema: {"type": "object", "required": ["db_host", "db_name"], ...}，它就知道必须提供这两个字段，而不是凭经验瞎猜。

5. 常见问题与避坑指南：来自 12 个生产环境的真实教训

5.1 权限失控：为什么--scope user:read比@require_permission('user:read')更可靠

问题现象：某客户报告“普通用户能调用/db-backup-mysql，导致数据库被恶意备份”。排查发现，他们的旧系统用装饰器@require_permission控制权限，但开发者在db-backup-mysql.py里忘了加这个装饰器，导致权限检查被绕过。

根本原因：装饰器是代码层面的，而--scope是注册层面的。Agent-Skills 的权限检查发生在调用链最前端（CLI 解析后、进程启动前），由框架统一执行。即使 Skill 代码里删光了所有权限校验逻辑