企业官网建设流程全解析

1. “agent-skills”不是功能列表，而是一套可插拔的智能体行为协议

你第一次在 GitHub 上看到agent-skills这个仓库名，或者在 CLI 工具的文档里读到skills install web-search这条命令时，大概率会下意识把它理解成“一堆预装好的小工具合集”——就像手机应用商店里下载一个“天气插件”或“翻译小部件”。这是最普遍、也最危险的误解。agent-skills的本质，既不是 API 封装库，也不是前端组件包，更不是模型微调产物；它是一套运行时可加载、语义可声明、权限可隔离的智能体行为契约（Behavior Contract）。这个概念听起来抽象，但拆开来看，它解决的是当前所有 LLM 应用落地中最卡脖子的三个现实问题：
第一，能力与模型解耦。你不需要为“查股票”“读 PDF”“发邮件”每个动作都训练一个专用模型，也不需要把所有功能硬编码进主程序逻辑里。agent-skills让模型只负责“想”，而让技能模块负责“做”。
第二，调用链路可审计、可回溯。当一个 agent 最终生成了错误的航班信息，传统做法是翻日志、猜上下文、重跑整个 chain；而在 skills 架构下，你可以直接定位到flight-status-v2这个 skill 的输入参数、调用时间、返回原始 payload，甚至能复现它当时访问的第三方 API 响应。
第三，权限粒度可控到字段级。比如github-pr-review这个 skill，它声明自己只需要repo:status和pulls:read权限，系统在安装时就会拦截任何试图让它写入secrets或删除分支的操作——这和浏览器弹出“该网站请求访问你的摄像头”是同一套信任模型，只是对象从“用户设备”变成了“agent 行为”。

我去年在给一家跨境 SaaS 公司做自动化客服 agent 时，就踩过没理解这套协议的坑。当时我们把所有 API 调用逻辑全写在main.py里，结果客户突然要求增加“自动比价拼多多商品”的功能。开发同学花了两天改代码、加异常处理、补日志埋点，上线后又因为拼多多接口返回结构变更导致整个 agent 卡死。后来我们用agent-skills重构，把pinduoduo-price-check单独抽成一个 skill，定义好它的输入 schema（商品 ID、地区编码）、输出 schema（最低价、历史波动、库存状态）、失败重试策略（最多 3 次，间隔 1.5 秒）和超时阈值（800ms）。新需求上线只用了 47 分钟：写 skill、本地测试、提交 PR、CI 自动构建 Docker 镜像、灰度发布。最关键的是，当拼多多接口某天凌晨返回了空数组，监控系统立刻告警pinduoduo-price-check的empty-response-rate超过阈值，而主 agent 流程完全不受影响，只是降级返回“暂无比价数据”。

提示：不要把agent-skills当作“功能增强包”，而要把它看作智能体的“操作系统内核驱动”。驱动不参与业务决策，但它决定了硬件（API/CLI/文件系统）能否被安全、稳定、可验证地调用。

2. CLI 是 skills 的交付载体，不是交互界面

搜索热词里反复出现zcode cli、codex cli、trae cli、boos cli，甚至还有cli anything wps——这些名字看似五花八门，但背后共享同一个设计哲学：CLI 不是给用户用的，而是给 agent 运行时用的标准化技能调度器。这和我们日常用git commit -m "fix bug"完全不同。当你执行skills install web-search，实际发生的是三件事：

1. 从官方 registry（如https://registry.skills.dev）拉取web-search的 manifest.json 文件，它声明了该 skill 的元信息：版本号、依赖的 runtime（如 Python 3.11+）、所需环境变量（SERP_API_KEY）、支持的模型上下文长度（最小 4096 token）、是否需要网络访问权限；
2. 下载对应的二进制或容器镜像（多数 modern skills 已默认打包为轻量级 OCI 镜像，大小控制在 12–35MB）；
3. 在本地注册一个符号链接/usr/local/skills/web-search → /opt/skills/web-search@v2.3.1，并写入权限策略文件/etc/skills/web-search.policy。

这个过程之所以必须通过 CLI 完成，是因为它承担了传统操作系统中package manager+device driver installer+SELinux policy loader的三重角色。举个具体例子：minimax-cli并不是让你手动敲minimax-cli --model abab6.5 --prompt "总结这段文字"，而是 agent 内部在决定调用“多模态摘要”能力时，自动触发minimax-cli run --skill=multimodal-summary --input=/tmp/clip_abc123.mp4 --output=/tmp/summary.txt。CLI 在这里是一个哑管道（dumb pipe），它不解析 prompt，不缓存响应，不做任何 LLM 相关计算，只做三件事：校验输入路径是否存在且可读、检查输出目录是否有写权限、按 manifest 中声明的--timeout=12000启动子进程并捕获 exit code。

我在实测codex-cli时发现一个关键细节：它的--compact参数根本不是为了“压缩输出”，而是强制关闭所有调试日志和进度条，确保输出流是纯 JSONL 格式（每行一个{ "type": "chunk", "data": "..." }对象）。为什么这么设计？因为 agent 的 orchestrator（编排器）需要逐行消费 stdout，而不是等整个命令执行完再 parse 一整块字符串。如果codex-cli默认开启彩色日志，那{"error":"rate_limit_exceeded"}这行就会被包裹在 ANSI 转义序列里，orchestrator 解析失败，整个 skill 调用就静默失败了。这就是 CLI 作为交付载体的底层约束：它必须是确定性的、无副作用的、流式友好的、零配置的。你不能指望它帮你做重试，也不能让它自动 fallback 到备用模型——这些决策必须由上层 agent 的 policy engine 做出，CLI 只负责精准执行。

注意：所有声称“支持自然语言调用 CLI”的工具（如cli anything wps），本质上都是在 CLI 层之上又裹了一层 LLM 解析 wrapper。这违背了agent-skills的设计初衷。真正的 skills CLI 应该像curl一样可靠：给它 URL 和 header，它就发请求；给它文件路径和 model name，它就调模型。中间不该有任何“理解”环节。

3. Slash Commands 是 skills 的语义入口，不是快捷键

热词中高频出现的slash commands，很容易让人联想到 Slack 或 Discord 里的/giphy cat这种交互。但agent-skills体系下的 slash command，其技术定位完全不同：它是 skills 的 URI Scheme，是 agent 内部路由系统的地址簿，是权限策略的锚点，更是跨 runtime 的 ABI（Application Binary Interface）。
以/github-pr-review为例，它在不同场景下承载着完全不同的技术含义：

• 在 CLI 环境中，它对应一个可执行文件路径/usr/local/skills/github-pr-review；
• 在 Web Worker 环境中，它被映射为一个 ESM 动态导入路径import('/skills/github-pr-review/index.js')；
• 在 Dockerized agent 中，它触发一个docker run --rm -v /tmp:/mnt/data ghcr.io/skills/github-pr-review:v1.8 --pr-url https://api.github.com/repos/xxx/pulls/123；
• 在 iOS app 的 Swift 代码里，它被桥接到一个SKLSkillRunner.execute(command: "/github-pr-review", params: [...])方法。

这种统一语义的关键，在于每个 slash command 都强制绑定一个 OpenAPI 3.0 风格的skill.yaml描述文件。这个文件不是给人看的文档，而是机器可读的契约。它必须包含：

• x-skill-permissions: 声明所需最小权限集，如["github:pulls:read", "github:issues:write"]；
• x-skill-runtime: 指定兼容的执行环境，如["cli", "web-worker", "docker"]；
• x-skill-context-length: 告知 orchestrator 此 skill 的输入输出总 token 占用，用于动态分配上下文窗口；
• x-skill-fallback: 定义当主 skill 失败时的降级路径，如["/github-pr-review-lite", "/text-summary"]。

我在为某金融客户开发财报分析 agent 时，就利用了这个机制。原始需求是/sec-filing-parse，它需要调用 SEC 官方 EDGAR API 解析 10-K 文件。但我们发现该 API 响应极慢（平均 8.2 秒），且经常因 IP 限流返回 429。于是我们写了两个 skill：主 skill/sec-filing-parse（依赖 EDGAR）和备选 skill/sec-filing-parse-cache（从本地 Redis 缓存读取，命中率 93%）。在skill.yaml中，我们这样声明：

x-skill-fallback: - command: "/sec-filing-parse-cache" condition: "response_time > 5000 || status_code == 429" - command: "/text-summary" condition: "cache_miss && file_size > 5000000"

orchestrator 在运行时会实时监控/sec-filing-parse的性能指标，一旦满足条件，自动切换到 fallback skill，整个过程对上层 agent 逻辑完全透明。这才是 slash command 作为语义入口的价值：它让“能力切换”变成配置项，而不是代码修改。

提示：不要在 slash command 名称里塞业务逻辑词，比如/send-email-to-ceo。正确做法是/email-send+to: "ceo@company.com"参数。command 名称应该描述“做什么”，而不是“为谁做”。这保证了 skill 的可复用性和策略可组合性。

4. Skills 开发不是写函数，而是定义行为契约

搜索热词里有大量skills开发、skills安装包下载、reasonix如何安装新skills，说明很多人正尝试从使用者转向开发者。但这里存在一个致命的认知偏差：skills 开发 ≠ 写一个 Python 脚本调用 API。如果你只是把requests.post("https://api.example.com/v1/search", json={"q": query})包进一个main.py，然后打个 zip 包，那得到的不是 skills，只是一个不可维护的胶水代码（glue code）。真正的 skills 开发，必须完成以下四个契约层的定义：

4.1 输入契约：Schema First，而非代码优先

每个 skill 必须提供一个input.schema.json，用 JSON Schema Draft-07 严格定义合法输入。例如/web-search的输入契约不能是“一个字符串”，而必须是：

{ "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "region": { "type": "string", "enum": ["us", "cn", "jp", "kr"] }, "num_results": { "type": "integer", "minimum": 1, "maximum": 10 } }, "required": ["query"] }

为什么必须这么麻烦？因为 orchestrator 在调用前会用这个 schema 做预校验。如果 agent 传入{"query": "", "region": "tw"}，orchestrator 会直接拒绝调用，并返回结构化错误{"error": "validation_failed", "field": "query", "reason": "minLength"}，而不是让 skill 进程启动后才报错。这节省了 90% 的无效资源消耗。

4.2 输出契约：结构化 Payload，禁用自由文本

skills 的 stdout 必须是严格的 JSONL（JSON Lines），每行一个对象，且必须包含type字段。合法类型只有三种：

• "type": "result"：最终成功结果，必须含data字段；
• "type": "error"：明确失败，必须含code（如"rate_limit"）和message；
• "type": "progress"：流式中间状态，用于长任务（如视频转码），必须含percent字段。
  禁止输出任何非 JSONL 内容，包括print("Starting search...")这样的调试语句。我在调试mineru-apiskill 时，就因为忘了删掉一行logging.info("PDF parsed")，导致 orchestrator 解析失败，整个 pipeline 卡在pending状态长达 17 分钟——因为它的 parser 期待的是{"type":"progress","percent":35}，结果收到了INFO:root:PDF parsed这串字符串。

4.3 生命周期契约：明确声明资源边界

每个 skill 必须在manifest.json中声明：

• max_memory_mb: 最大内存占用（如256）；
• max_cpu_ms: 单次调用最大 CPU 时间（如3000）；
• network_access: 是否允许外网访问（true/false/["api.github.com", "api.pinduoduo.com"]）；
• file_access: 文件系统访问范围（["/tmp", "/mnt/data"]）。
  orchestrator 会基于这些声明做沙箱限制。比如max_memory_mb: 256会触发ulimit -v 262144，network_access: ["api.github.com"]会配置 iptables 规则只放行该域名。这比靠代码里try/except捕获 OOM 更可靠。

4.4 退出契约：Exit Code 语义化，禁用 0/1 二分法

skills 的进程退出码（exit code）必须携带语义：

• 0: 成功完成，stdout 含有效 result；
• 10: 输入校验失败（orchestrator 应修正参数后重试）；
• 11: 临时性失败（如网络超时，orchestrator 应按策略重试）；
• 12: 永久性失败（如 API key 无效，orchestrator 应触发告警并 fallback）；
• 13: 资源越界（如内存超限，orchestrator 应记录并降级该 skill）。
  我见过太多团队把所有错误都sys.exit(1)，结果 orchestrator 无法区分“该重试”和“该放弃”，只能盲目重试三次，把本来 200ms 的请求拖成 6 秒超时。

注意：skills 开发的终极目标，是让 orchestrator 能在不看任何代码的情况下，仅凭 manifest + schema + exit code 就能 100% 理解这个 skill 的行为边界。这才是“可插拔”的真正含义。

5. API 不是 skills 的替代品，而是它的数据源与执行通道

热词列表里充斥着deepseek api、智谱api、百度api、海康威视api接口、阿里云短信api……这反映出一个普遍焦虑：“我已经有 API 了，为什么还要搞 skills？”答案很直接：API 是水电煤，skills 是电器。你不会因为家里通了电，就认为不需要冰箱、空调和洗衣机。
skills 和 API 的关系，是“能力封装层”与“数据通道层”的关系。举几个典型对比：

我在对接超稳-q绑在线查询api（一个国内常用的手机号实名认证服务）时，深刻体会到这种分层的价值。最初我们直接在 agent 主流程里调用它的 REST API，结果遇到三个问题：

1. 该 API 响应不稳定，有时 200ms，有时 8 秒，导致 agent 整体 timeout 设置成 10 秒，严重拖慢正常流程；
2. 它的错误码极其混乱：400可能是参数错，也可能是余额不足，还可能是 IP 黑名单；
3. 客户要求所有实名查询必须记录操作人、时间、手机号哈希，但 API 返回里没有这些字段。

改成 skills 后，我们新建了/mobile-realname-verify，在它的实现里：

• 用retry_strategy = ExponentialBackoff(max_attempts=2, base_delay=100)封装重试；
• 把所有4xx错误统一映射为{"code": "invalid_input", "message": "check phone format"}，5xx映射为{"code": "service_unavailable", "message": "third_party_down"}；
• 在 skill 启动时，自动从 orchestrator 注入OPERATOR_ID和TIMESTAMP环境变量，并在最终结果里拼接{"audit": {"operator": "...", "timestamp": "...", "phone_hash": "..."}}。

现在，当客户说“把实名查询换成另一家服务商”，我们只需要：

1. 写一个新的/mobile-realname-verify-altskill；
2. 更新 orchestrator 的 fallback 策略：x-skill-fallback: ["/mobile-realname-verify-alt"]；
3. 发布新版本。
   整个过程不到 15 分钟，主 agent 代码一行未动。这就是 skills 作为“能力抽象层”的威力——它把 API 的脆弱性，转化成了可配置、可监控、可替换的工程资产。

提示：评估一个 API 是否值得封装为 skills，就问一个问题：如果这个 API 明天彻底下线，你的 agent 能否在 30 分钟内无缝切换到竞品，且不修改任何业务逻辑代码？如果答案是否定的，那它就还没达到 skills 的封装标准。