企业官网建设流程全解析

1. 项目起因：skill 为什么会散落在三台电脑上？

1.1 从提示词到技能包，AI 工程的重心在转移

老实说，我一开始没觉得 skill 是个值得认真对待的东西。最早的 agent 用 skill，无非就是把常用的提示词、工作流模板和脚本丢进一个目录，让 AI 在开始干活之前先读一遍。那时候的 skill 更像是一个"开场白"，帮你约束 AI 的语气、输出格式和思考路径，核心是提示词工程那一套。

但等我自己手头的 skill 超过十五个、电脑超过两台之后，问题就开始变得非常现实。你会发现自己陷入一个尴尬的处境：同一个技能，Windows 上是旧版本，macOS 上是改过的版本，服务器上干脆没装。三台电脑各留一套残缺副本，比没有更折磨人。更麻烦的是，有些技能依赖特定的运行环境和工具链，A 机器上跑得好好的，B 机器上连依赖是什么都说不清。这种情况下，技能本身已经不是一段文本，而是一个具备完整状态、依赖关系、运行入口和验证方法的软件资产。

你让我用一句话总结这个项目，我会说：把二十个 skill 当成一套可以自我安装、自我校验、自我修复的软件系统来治理，让 AI 自己完成跨设备部署。这不是在写提示词，这是在做一个非常轻量的"智能体自主容错控制"工程。核心思路来自社区里大家都在讨论的 LLM 智能体自主容错控制框架：系统不能假设环境永远正确，必须让 AI 在安装、执行、验证的闭环里实时发现问题、自己做判断、自己回滚。

这也是我写这篇实录的原因。网上讲 skill 怎么写的内容很多，讲"怎么管理一堆 skill"的内容很少。更没人告诉你，当 skill 数量到了一定规模、机器到了一定数量，真正卡住你的不是技能内容本身，而是技能的分发、版本和故障恢复。这篇文章就是来补这个空白的。

1.2 三台电脑各留一套残缺副本的教训

我手头常驻三台设备，用途完全不同。一台 Windows 桌面机，主要处理文档、表格、批量数据处理，偶尔写点报告；一台 macOS 笔记本，主力开发机，跑 agent、跑代码生成、做 GIS 空间分析和日常自动化；还有一台 Linux 服务器，放在家里内网，跑定时任务、数据抓取和需要长时间执行的后台批处理。

这三台机器的操作系统不同、软件环境不同、网络条件也不同。早期我给每台机器分别手工配置 skill，结果就是"同一时间三个版本"：Windows 上的某个写报告技能还停留在上一个迭代，macOS 上已经加了今年新要求的格式规范，服务器上则干脆缺了好几个关键技能，因为装的时候正好赶上一次大改，我忘了同步。再加上有些技能需要调用外部的命令行工具，比如 pandoc、ffmpeg、ogr2ogr 这些，不同机器上装没装、版本够不够，完全靠脑子记。

真正让我下定决心重构的是一次线上事故。当时我在 macOS 上调好了一个生成短剧脚本的技能，跑得很顺。第二天出差，只有 Windows 笔记本在身边，我顺手让 AI 写一个短剧脚本，它直接给我报错——"技能未安装"。我一查，这个技能在 macOS 上是通过一个软链接目录启用的，Windows 上文件倒是拷过去了，但目录结构不对，依赖的批处理脚本也找不到。那个时候我意识到，靠人肉同步 skill 已经完全不可行了。

所以这个项目的目标特别明确：同一套技能清单，二十个 skill，无论放到哪台电脑上，都只需要执行一条指令，AI 自己完成目录创建、文件拷贝、依赖检查、自检启用、失败回滚。我不再关心某台机器上缺什么，我只需要维护好一个技能仓库和一个技能清单，剩下的事全部交给 AI 的自主容错能力。

2. 技能工程的顶层设计：SKILL 也是软件资产

2.1 技能的文件组织规范

要让 AI 能自己安装技能，首先得给技能定一套严格的目录规范和文件格式。我的做法是把每个技能做成一个独立目录，放进技能仓库统一管理。一个标准技能的最小结构是四样东西：

skills/ └── write-report/ ├── SKILL.md ├── run.sh ├── check.sh └── assets/

SKILL.md是这个技能的身份证和说明书，头部用 YAML 格式写元信息，正文用 Markdown 写执行规则。run.sh是实际执行的入口脚本，AI 调用这个技能时读的就是它。check.sh是自检脚本，用来判断这个技能在当前环境下是否处于可用状态。assets/放模板文件、配置文件、参考样例这些辅助资源。

之所以把技能说明和运行入口分开，我是踩过坑才想明白的。最开始我把所有内容都塞进SKILL.md，AI 读完后自己决定怎么做，看起来灵活，实际上每次执行结果都不稳定。后来改成SKILL.md只做主流程拆解和规则约束，具体的确定性操作收敛到脚本里，AI 只负责编排和参数填充，不再临场发挥。这个改动让技能输出稳定了非常多。

再看 SKILL.md 的元信息头，这是给程序看的，不是给人看的：

--- name: write-report version: 2.1.0 signature: skill-report-0193 platforms: [windows, darwin, linux] run: run.sh check: check.sh dependencies: [python3, pandoc] ---

这里我特别解释一下signature字段。技能名可能会改，但签名是一个唯一编号，相当于技能的程序指纹。技能升级不影响签名，只要功能定位没变，签名就不变。skill 编码 0193、0247 就是这么来的——我给我的每个技能分配了一个固定编号，哪怕以后重命名目录、改版本号，AI 都能通过签名认出"这个技能我见过"。后来我把签名格式统一成skill-{category}-{number}，写报告是 0193，GIS 空间分析是 0247，短剧脚本是 0248，一眼就能看出归属。

2.2 用 manifest 索引一切技能

技能目录是物理存在，但 AI 不能靠肉眼找技能，它需要一个机器可读的总索引。我在仓库根目录放了一份inventory.json，维护所有技能的元数据、版本、签名、所属分类、目标平台和安装状态。

{ "skill_inventory": [ { "signature": "skill-report-0193", "name": "write-report", "version": "2.1.0", "category": "writing", "platforms": ["windows", "darwin", "linux"], "install_to": "~/.agent/skills/write-report", "checksum": "a3f29c..." } ] }

AI 在处理"安装"这个任务时，不是直接遍历目录猜测要装什么，而是先读inventory.json，拿到这份标准化的清单，再跟当前机器的实际状态做对比。这一步非常关键，它把"让 AI 自己装好"从一句口号变成了一个可执行的项目管理流程：读清单、查现状、算差异、执行安装、跑自检、更新状态。

目录规范之外，我还定了一条硬性约定：技能的物理文件放在哪个位置不重要，重要的是安装后必须注册到本机的状态文件里。每台机器上维护一个~/.agent/skill_state.json，记录本机已安装技能的签名、版本、安装时间和自检结果。这样 AI 检查状态时就有一个明确的依据——清单里有、状态文件里也有、且自检通过，才算这个技能可用。

2.3 为什么把"可用"和"启用"拆开

刚开始设计自动安装的时候，我以为装完就算完事。后来发现不对，某台机器上技能文件倒是复制过去了，但依赖没装好，AI 调用技能时照样报错。于是我把技能的目录拆成两层：available/存放所有已安装但未经自检的技能文件，enabled/只放通过自检的软链接。

这个设计其实来源于一个特别朴实的管理学类比：药品仓库里可以堆着一批新到的库存，但只有通过质检、拿到批号的药品才会放进药房货架。available 相当于待检验库存，enabled 才是真正能对外提供服务的货架。AI 安装技能的时候，先把文件解压/复制到 available 目录，然后运行check.sh，通过之后在 enabled 目录创建软链接；如果自检失败，技能就留在 available 里，等着排查，但 AI 调用时不会加载它。

这套"先准入、后启用"的机制给了自动安装一个安全边界：AI 的任何错误操作，最多污染 available 目录，不会影响已经正常服务的技能。你在执行一条自主安装指令时，最担心的是它搞崩你本来能用的东西，有了这层隔离，最坏情况也只是新增技能没装上，存量技能一个都不会坏。

3. 一句话自装：自主安装与容错控制的核心逻辑

3.1 自举流程的设计

让 AI 自己装好，本质上是把一套完整的部署流程封装成一个超级 skill，我给它起名叫agent-bootstrap。这个技能不干别的，只负责管理其他技能。它的执行入口是一个bootstrap.sh，但真正起作用的是 AI 会按照 SKILL.md 里的流程动作，走完四个阶段：扫描、对账、安装、验证。

第一阶段是扫描。AI 读取inventory.json技能清单和本机的skill_state.json状态文件，同时实际查看 enabled 目录里的软链接，拿到"当前机器到底有哪些技能可用"的真实情况。这一阶段不修改任何文件，只做信息采集。

第二阶段是对账。AI 逐项对比清单和现状，得出三类结论：缺失技能（清单有、机器没有）、版本过期（签名一致但版本落后）、冗余技能（机器有、清单已删除）。对账结果会写进一份临时差异报告，AI 会输出这段内容，让我确认。这一步我坚持必须要人看一眼，因为自主再高，也不该在用户没确认的情况下动文件。

第三阶段是安装。对于缺失和过期的技能，AI 按分类处理：先把技能文件复制到available/，再检查依赖声明，缺什么装什么。依赖装不动的情况，AI 不会硬来，它会判断瓶颈在哪里，给出两个选项："需要本机管理员权限"或者"需要用户手动操作某项前置步骤"。这种判断是执行 prompt 里明确规定的，不是 AI 现场猜的。

第四阶段是验证。每个安装完的技能都跑一遍check.sh，通过则创建软链接到enabled/，失败则保留在available/并记录失败原因。整个流程结束后，AI 输出一张报告表，列出"新装、升级、回滚、失败"四个分类，方便最终确认。

用户侧的操作，其实就是一句话：

"请按标准流程检查这台机器上的技能状态，对照 inventory 清单补齐缺失技能，完成自检后输出报告。"

这句话发出去之后，AI 会自己按流程动作，不需要我再干预。中途如果遇到必须人工介入的点，它会主动停下来问我，而不是蒙着继续跑。

3.2 验证与回滚机制

自主容错控制的重点不在"能装"，而在"装错了怎么办"。我设计了两个安全阀，一个是自检命令，一个是回滚机制。

自检命令就是每个技能自带的check.sh。写这个脚本的时候我给自己立了一个规矩：check.sh 必须做三件事——检查入口文件是否存在、检查关键依赖是否可达、执行一次最小烟雾测试。拿 GIS 分析技能来举例，它的 check.sh 先确认run.sh存在，再用which ogr2ogr验证 GDAL 工具链已安装，最后尝试跑一次极小的空间分析命令，比如读取一个测试 GeoJSON 并输出要素数量。三步全过才算自检通过。

如果自检失败，AI 会进入回滚流程。回滚的粒度是单个技能，不影响其他技能。具体做法是：安装之前，AI 先把该技能对应的 enabled 软链接指向的原目录做一个快照备注，记录原版本号；安装中如果自检失败，AI 删除 available 里新拷贝的目录，保留原可用目录不动。因为可用和启用是分离的，所以回滚操作非常简单——把软链接重新指向原版本目录即可，整个过程不需要重新拷贝文件，几秒钟就完成。

我一开始自己写回滚逻辑的时候想的很复杂，什么版本快照、差异备份，后来发现根本不需要。目录结构上做一点隔离，回滚自然就变得很轻。这个思路后来也写进了我的 SKILL.md 设计模板里：任何 skill 都必须提供 check 命令，任何安装流程都必须假设 check 可能失败。

3.3 跨设备同步的心得

二十个 skill 散在三台机器上，最重要的枢纽其实是一份统一的技能仓库。我的做法是把整个技能仓库放在内网服务器上，用 Git 管理，每台设备上只需要保证能访问这个仓库地址。为什么不用云盘同步文件夹？我试过，文件能同步，但目录权限和软链接会被云盘搞得乱七八糟，而且同步回来的文件经常带着冲突副本，AI 去读的时候根本分不清哪个是准的。

Git 仓库做源，有几个天然优势。第一，版本有记录，每个技能什么时候改过、为什么改，一目了然，这就是技能的完整变更历史。第二，分支可以玩策略，稳定版放主干，测试中的技能放单独分支，AI 默认只从主干安装。第三，Git 的 clone/pull 动作本身就是 AI 很容易执行的命令，不需要额外的同步协议。

跨设备同步的完整链路是这样的：我更新技能内容后，提交并推送内网 Git 仓库；任意一台电脑上，我发一条"同步技能仓库并检查技能状态"的指令；AI 先执行 Git pull 拉取最新清单和技能文件，然后自动走扫描、对账、安装、验证的流程。这样我只需要在一台电脑上改一个技能，其他机器下次同步时就会自动跟上，不会再有"改了 A 忘了 B"的情况。

这里我多说一句，为什么这个方案比直接 rsync 文件更值得做。rsync 只会机械地把文件从源头复制到目标，它不知道目标机器的依赖缺了什么，也不知道复制过去的技能是否能在当前环境运行。而 AI 自装流程做的是语义级同步——它不只是把文件放到位，还会检查依赖、执行自检、判断启用、处理回滚。文件同步解决的是"有没有"的问题，AI 自装解决的是"能不能用"的问题。

4. 实操记录：三台电脑的部署实录

4.1 设备与技能清单

先把实际部署的环境摆出来。三台机器的角色和技能分布如下：

三台机器加起来一共装过 20 个不同的技能，其中大约 7 个技能在多台设备上共用。比如说write-report这个写报告技能，三台机器都要用，因为我在任何一台电脑上都有可能临时要出报告。而像gis-spatial-analysis这种技能，只在 macOS 主力机和 Linux 服务器上装，Windows 桌面机用不到。

技能清单的分类我分成五类：写作类（报告、短剧脚本、语言学习）、开发类（代码生成、代码审查、测试命令生成）、数据处理类（批量文件处理、数据清洗、GIS 分析）、系统自动化类（定时任务管理、设备文件扫描）、以及提示词工程类（去 AI 味写作、角色风格控制、打斗动作提示词）。每类技能对运行环境和依赖的要求不同，正好能检验自动安装流程的通用程度。

4.2 在新增电脑上"一句话装好"的全过程

我拿最近一次在新笔记本上部署来演示完整流程。那台笔记本是一台全新的 macOS，干净系统，只装了基础开发工具，一个技能都没有。我要做的是直接在对话里发出指令：

"请同步技能仓库到本机，并按照 inventory 清单完成所有技能的安装与自检。"

AI 拿到这条指令后，第一件事是确认仓库地址和访问凭据。仓库我放在了内网服务器的 Git 服务上，AI 执行了git clone把技能仓库拉到了~/.agent/skills-src/。这一步用了一分多钟，取决于仓库大小和网络速度，主要是技能 assets 里有一些模板文件和样例数据比较大。

然后 AI 读取inventory.json，对照本机空的skill_state.json，得出"全部 20 个技能缺失"的结论。它没有直接动手，而是先把一份"即将安装 20 个技能"的清单打印出来，并标出其中需要额外依赖的技能名称，然后问我是否继续。这一步是我在 prompt 规则里强制要求的，AI 不能在未确认的情况下大批量修改系统。

确认后，AI 开始逐个处理技能。每个技能的安装顺序是先看依赖。比如write-report需要 pandoc，AI 检测 Mac 上没装，它会先执行brew install pandoc，成功后再继续装技能本体。如果某个依赖装不上，比如某个技能需要特定版本的 GDAL 而 Homebrew 默认源里没有，AI 会跳过这个技能，继续装后面的，最后在报告里单独标出失败原因。这个"跳过但不中断"的容错逻辑很重要，否则一个技能失败会拖垮整条安装链。

全部处理完后，AI 输出了一份安装报告，我简化一下核心内容：

看到这个结果，我只花了大概十分钟处理那两个待处理项和那个授权问题，其余 17 个技能一装就能用。如果按以前的手工方式，新机器配置完全部技能至少得大半天，而且中间很容易漏装少装。

4.3 实际效果：安装耗时、容错表现、人工介入点

这套流程跑了大半年，体感和一些具体数据都积累了不少。一次全量安装从开始到出报告，总耗时通常控制在五到十分钟。其中 Git 拉取占了大头，真正执行安装的耗时反而很短，因为大部分技能就是复制文件和建软链接，真正费时间的是依赖安装。

容错表现给了我不少惊喜。有一次服务器上的技能批量升级，其中一个技能新版本引用了系统里不存在的库。自检失败后，AI 自动把那个技能保留在 available 目录，enabled 软链接还是指向旧版本，旧技能照常能用。等我在仓库里修复了依赖声明并推送新版本后，再发一次同步指令，AI 检测到版本落后，重新走了安装和自检流程。整个过程几乎没感觉到中断。

人工介入点主要集中在两类技能上。一类是需要账号授权的，比如某些外部服务的 API 密钥或网盘授权，这类技能的安装本身很简单，但凭证不在技能包里，需要我手动完成一次授权操作，AI 会卡在那里等我。另一类是需要特定 GUI 环境的，比如某个 Windows 上的自动化技能，它依赖一个只有桌面登录后才能访问的本地工具，AI 检测到当前会话没有 GUI 权限，会明确提示需要使用图形界面环境执行。这些情况不是缺陷，反而说明 AI 的容错判断是有效的——它知道自己能力的边界。

5. 常见问题与避坑速查表

5.1 高频问题与排查思路

排查的时候最好反过来想，绝大多数问题都出在技能声明不够严格，而不是 AI 执行不给力。依赖写得模糊、路径写死、check 命令设计得过于简单，这些才是根源。AI 只是在执行一份写得有漏洞的说明书，你不能指望它自己把漏洞补上。

5.2 几个让我少走弯路的设计心得

第一个心得：每个技能必须有一个可执行的验证命令。这可能是整个项目里最重要的一条规则。没有验证命令，自动安装就是一个盲盒——装上之后到底能不能用，只能靠运气。有了 check.sh，AI 才能做出"装上了"和"能用了"这两个层次的判断，后者的价值比前者高得多。

第二个心得：技能名是写给人看的，签名是写给程序看的。刚开始我给技能取名很随意，结果改名之后 AI 的逻辑就乱了，因为状态文件里记录的还是旧名字。后来强制引入 signature 签名机制，改名不影响识别，技能的身份和名字解耦。这个改动看起来很小，但对稳定性的提升是质的。

第三个心得：权限和凭据绝不放进技能包。技能包主要分发给三台电脑，如果里面包含 API 密钥或私有凭证，只要仓库泄露一次，所有机器的安全性都完蛋。我的做法是技能安装时只生成一个配置文件模板，具体的密钥由用户手动填，或者从本机独立的凭据文件里读取。AI 可以在需要时提示用户配置，但绝不能通过 Git 分发敏感信息。

第四个心得：定期做一次技能体检。我给自己设了一个 cron 任务，每周在 Linux 服务器上跑一次"全量技能自检"，把每个技能的 check.sh 都执行一遍，然后生成健康报告。服务器上的技能常在后台批处理场景中使用，出了问题不会立刻被发现，体检机制帮我提早抓到过好几次依赖静默失效的隐患。

如果让我重新来一次，我最先做的一定不是先写二十个 skill，而是先把 inventory.json、目录规范和自检机制搭好。技能内容可以慢慢迭代，但骨架和闭环要一步到位。工具会换，模型会升级，真正能积累下来的东西，其实是这套让 AI 自己做决策、自己做检查、自己承担容错责任的工作流。