内网环境装技能包:能落地的那一套长什么样
内网环境装技能包:能落地的那一套长什么样
在能上外网的环境里,安装一套 Agent 技能包的成本低到几乎等于一条命令;换成隔离内网,也就是彻底断网的环境,同一条命令会依次卡在三个地方:装不上、拉不到依赖、验不了效果。本文以 BAMA(21 个技能,覆盖 macOS 原生应用从调研到交付的全流程)为样本,逐层拆开它在断网环境中究竟哪几行能跑、哪几行必须重写、哪一层才是企业真正需要补上的。它既是“一个技能包”,也是一份可以照着审查自己内部技能包的现成清单。
一、先把“出网点”数清楚,再谈安装
技能包本身不占空间,占掉时间的是它和外界之间的接口。把 BAMA 的安装方式摊开看,四条推荐路径里有三条需要网络:
| 路径 | 实际动作 | 断网后果 |
|---|---|---|
npx skills@latest add ... |
从 npm registry 拉 CLI,再拉仓库 | 双重失败 |
/plugin marketplace add |
读远端 marketplace 清单 | 清单拿不到 |
codex plugin marketplace add |
同上 | 同上 |
手工克隆 + scripts/link-skills.sh |
本地目录建软链接 | 唯一可用的路径 |
所以内网方案的第一条结论很朴素:把仓库变成“已落地的目录”,把安装变成“建链接”。BAMA 的 README 里那条 By hand 路径,恰好就是全仓库唯一不依赖网络的分支,而且它短到只有十几行:
repo=${0:A:h:h}
for target in ~/.claude/skills ~/.agents/skills; do
mkdir -p "$target"
for skill in "$repo"/skills/*/*/; do
skill=${skill%/}
name=${skill:t}
ln -sfn "$skill" "$target/$name"
echo "$target/$name"
done
done
见 scripts/link-skills.sh。它只做三件事:定位仓库根(${0:A:h:h} 是 zsh 的路径修饰符),遍历 skills/<stage>/<name>/ 两级目录,把每个技能目录强制软链接到两个目标目录(~/.claude/skills 与 ~/.agents/skills)。没有 registry,没有版本解析,没有校验和——这正是内网需要的东西。
但这段脚本直接搬到企业环境会踩两个坑,两个都能从代码里读出来:
其一,命名空间是扁平的。 name=${skill:t} 只取最后一级目录名,skills/plan/clone 落到 ~/.claude/skills/clone。如果内部还有第二个技能包也带一个叫 clone 的技能,ln -sfn 的 -f 会静默覆盖前一个。内网通常同时挂三五个团队的技能包,这种覆盖不会报错,只会让某个技能“莫名消失”。
其二,目标目录写死在 $HOME。 两个 for target 都是用户级路径,无法落到 /opt、共享盘或镜像里,也就没法做机器级统一分发。改造方向很简单:把目标目录做成参数或环境变量,并在名字前加包前缀(bama-clone),把“谁覆盖谁”变成显式的失败。
还有一个流程上的坑:README 特意写了一句 “Pick one route per agent. Two routes install every skill twice.”。内网迁移时最常见的操作是先试插件路由、失败后改软链接,结果同一台机器上技能装了两份,agent 只看见其中一份,另一份留在原地制造版本困惑。内网实施时要把它变成硬规则:一台机器、一个 agent、一条路由。
二、必须重写的部分:依赖拉取与外部调用
判断一个技能包能不能进内网,不能看它宣称支持什么,要看它实际会 fopen / exec 什么。对 BAMA 做一次静态盘点,结论比想象中好:
构建链是干净的。 模板的 Package.swift 里没有任何 dependencies: 数组,只有三个 target;swift-tools-version: 6.2,平台 macOS(.v26),并且用 .defaultIsolation(MainActor.self) 把默认隔离级别写在声明式配置里。零第三方 SPM 依赖,意味着 swift build 不需要解析远端包图,断网也能编译——这是它能进内网的根本前提。
build.sh 同样只调用本机工具:swift build 加 --scratch-path(构建产物放在 ~/Library/Developer/<AppName>,刻意避开 Dropbox/iCloud 同步目录),security find-identity 找签名证书,找不到就退回 ad hoc 签名(identity=-),最后 xattr -cr 加 codesign --force。全程没有 curl。脚手架脚本 new-app.sh 也是一样:cp -R -n 复制模板、sed -i '' 替换占位符、git init 提交首次快照,没有任何下载动作。
真正会出网的是这两处:
-
hig.sh的实时抓取。skills/design/mac-design/scripts/hig.sh 用curl -fsSL从developer.apple.com/tutorials/data/design/human-interface-guidelines拉取 HIG 页面的 JSON,缓存在~/Library/Caches/bama/hig/,只有超过 7 天才会重取;--list首次运行还要沿引用链走三层、抓大约 40 个页面。这段逻辑在内网必然失败,但它失败得很“体面”:curl后面跟了|| { ...; return 1; },会打印no HIG page named ...而不是抛栈。内网改造有两个务实选择。预置缓存:在联网机器上跑一遍
hig.sh --list和常用主题,把~/Library/Caches/bama/hig/打包进镜像,断网机器上只要文件不满 7 天就直接命中缓存——注意find -mtime +7用的是文件 mtime,解包时要保留时间戳(tar -p),否则缓存刚落地就“过期”。换源:把脚本里那行base=提成${HIG_BASE:-https://developer.apple.com/...},指向内部镜像,改动只有一行,但需要重跑一遍校验。 -
research与clone的外部能力。skills/plan/research/SKILL.md 把任务拆成 market / reviews / features / design / platform 五条并行的调研线,明确要求“Search the web”;skills/plan/clone/SKILL.md 的原生应用采集依赖 computer use,而 computer use 需要云端 Pro/Max 订阅。这两处在隔离内网都不是“配置问题”,是能力缺口。这里有个容易被忽略的细节:
research的输出格式要求每条结论打标签——[V]已在来源中验证(附 URL)、[K]来自模型自身知识、[U]未验证必须实测,并且每条决策必须引用一个[V]或一个计划中的测试。这个格式恰好是内网改造的接口:把“Search the web”替换成“检索内部 Confluence / 需求库 / 历史事故单”,[V]的 URL 换成内部文档 ID,其余结构原样保留。换的是检索源,不是方法论。至于
clone,退化路径是现成的:window-shot.sh 用CGWindowListCopyWindowInfo找目标应用最大的窗口,再用screencapture -l <id>抓窗口本身。这一步完全本地,只需要终端拿到“屏幕录制”权限。电脑操作不可用时,用“截图 + 人工按顺序走查 + 写 INDEX.md”依然能得到一份可用的屏幕索引,只是慢一些。
最后一处硬门槛不在代码里,在环境里:skills/start/new-mac-app/SKILL.md 的第一步是 swift --version 和 sw_vers -productVersion,要求 Swift 6.2 与 macOS 26。内网机器要么预装 Xcode 26 的离线包,要么这个技能根本起不了步——技能包依赖管理做得再好,也补不上工具链的缺口。
三、分层:配置层、规范层、验收层
一个技能包“能装”和“能管”是两件事。BAMA 的结构恰好可以按三层切开,而且每一层都能落到具体文件上。
配置层:让 agent 知道你装了哪些东西。
- .claude-plugin/plugin.json 用
skills数组显式列出全部 21 个技能路径,version是1.0.0;AGENTS.md 里还写了一条运维纪律:首个 release 之前不升版本,之后必须升,否则已安装的副本不会更新。 - 每个技能目录下都有一个
agents/openai.yaml,只填display_name和short_description,例如 skills/code/agent-cli/agents/openai.yaml。这是给 Codex 这类客户端的展示层,和SKILL.md的description职责分开。 - 路由技能 skills/start/bama/SKILL.md 在 front-matter 里设了
disable-model-invocation: true,对应的 yaml 里设policy.allow_implicit_invocation: false——入口技能只允许人调用,不允许模型自己决定调用。在自动化程度高的团队里,这一条比多写十个技能都重要。
内网落地时,配置层要补的是“来源清单”:每个技能包从哪个仓库、哪个 commit 来,plugin.json 的 version 是多少,谁审的。BAMA 的 .gitignore 只有 .DS_Store 和 .build/,说明它预期整个仓库可入版本库——那就把它当一个 vendored 依赖管理,而不是“从网上下的一次性东西”。
规范层:让写技能的人有可依据的规矩。
AGENTS.md(与 .claude/CLAUDE.md 内容完全一致,仓库要求两者保持同步)把写作规则压成了几条可判定的条款:description 必须是“上下文指针”——一句话说清是什么,然后 Use when 加每条分支一个触发词;公共内容内联,分支内容放兄弟文件靠链接抵达;每一步都要以可检查的条件收尾,每个技能结尾必须有 Done when 行;提示正向目标,禁止项只作硬护栏;只缓存环境告诉不了 agent 的东西(约定、原因、真实踩过的坑);技能之间调用统一写 “Call the Skill tool with <name>”。
这套规则的价值在于它可审计。你拿到一个第三方技能,不用读完三千字,就能判断它合不合格:
- 有没有
name/description且描述里带触发条件? - 有没有
allowed-tools把权限收窄?BAMA 里只有三个技能声明了它,例如new-mac-app是Bash(*/new-app.sh *) Bash(git *) Bash(swift *) Read Write Edit,build-and-verify是Bash(./build.sh*) Bash(swift *) Bash(tools/*) Bash(*/Contents/MacOS/*) Bash(open *) Read。没有allowed-tools的技能,等于默认拿到全部工具,这是内网审查时最该盯的一栏。 - 有没有
Done when?没有终态定义的技能,Agent 永远不知道自己该不该停。 - 有没有可豁免的例外机制?tools/grid-lint.sh 要求间距只能是 0、1、2 或 4 的倍数,禁止
.offset(和.position(,但允许在行尾写// grid: ok <理由>放行。规范必须留一个有理由的例外通道,否则第一周就会被绕过。
验收层:让“做完了”变成退出码。
这是 BAMA 最值得抄的一层。skills/ship/build-and-verify/SKILL.md 开头就把“完成”定义成四个条件:./build.sh 无错误、看过改动页面的明暗两套快照、快照符合故事或参考图、网格检查通过。四条里三条可以由脚本判定,一条必须由人(或具备视觉能力的 agent)看图。
支撑它的是一条全程本地的工具链:
| 检查 | 命令 | 判定信号 |
|---|---|---|
| 构建 | ./build.sh |
退出码 + “binary is older than ...” 陈旧二进制检测 |
| 单元测试 | swift test --scratch-path ... |
退出码 |
| 应用内自测 | tools/selftest.sh |
每个 PASS 一行,全过退出 0 |
| 视觉快照 | tools/snap.sh |
每页明/暗各一张 PNG,落在 /tmp/<App>-shots |
| 布局网格 | tools/grid-lint.sh + check-layout.swift |
都打印 PASS |
| Agent CLI 契约 | check-agent-cli.sh | PASS agent CLI,任一 FAIL 退出 1 |
check-agent-cli.sh 尤其值得单独看:它在 /tmp 起一个测试副本(APP_STORE 指向临时库),校验 help、help --json(每条命令必须有摘要、示例、schema)、未知命令退出码必须是 2、--json 错误必须是 {"error":{code,message}} 结构、所有只读命令必须返回单个 JSON 对象,最后通过 stdin 灌三段 JSON-RPC 验证 MCP 的 initialize 与 tools/list,并要求工具数量与命令数量严格相等、每个工具都带 readOnlyHint。它验证的不是“能不能跑”,而是“契约有没有漂移”。 这一层在内网是刚需,因为隔离环境里没人会天天手工回归。
另一条工程细节同样来自验收层:tools/snap.sh 在启动前删掉 ~/Library/Saved Application State/<bundle id>.savedState 和旧测试库(含 -wal、-shm)。原因是崩溃后会弹“是否重新打开窗口”,无人值守的流程会卡死在这个弹窗上、没有任何输出。这类“让机器跑得下去”的细节,比多写两个技能更能决定落地成败。
四、对外部技能包的取舍标准
生态已经膨胀到需要“挑选”而不是“收集”的规模:安全方向的技能合集动辄两百多个技能、覆盖代码审计与逆向,Claude Skills 的社区清单也在按“自动化 / 创意 / 文档处理”分三大类扩张。内网场景下,这份清单的正确用法是做减法,判断标准可以从 BAMA 的结构里直接反推出来:
- 能不能闭环离线。 检查三件事:语言包管理器有没有远端依赖、脚本里有没有
curl/wget/npx、有没有必须联网才能用的能力(云端 computer use、在线检索)。BAMA 靠零 SPM 依赖 + 纯本地脚本过了前两关,卡在hig.sh和research,这就是改造清单的全部内容。 - 权限是否收窄。 有
allowed-tools的才敢放进自动化流水线;没有的,先补上再谈。 - 终态是否可判定。 只认“有
Done when、有 PASS/FAIL 输出、有退出码”的技能。判断标准是情绪化描述的(“效果很好”“体验流畅”),在缺少评审人的内网里就是不可验收。 - 结构是否合规范。
skills/<stage>/<name>/SKILL.md加同级引用文件、脚本进scripts/、模板进template/、每个技能配agents/openai.yaml并在plugin.json注册。结构乱的包,后面一定会出现“技能装了但路由找不到”。 - 改动是否可逆。 一键提交、一事一提交、可单独回退。这条在 skills/ship/improve-loop/SKILL.md 里被写死:一个故事一个 commit,快照对比最多三轮,三轮不达标就把故事退回
todo并写明阻塞原因,然后往下走。无人值守的循环最怕的不是做错,而是错了没法回滚。 - 内容边界是否清楚。
hig.sh的注释里有一句很关键的约束:抓下来的 HIG 文本是 Apple 的,只进缓存、永不进仓库。同理,clone技能要求“不取参考应用的文字、logo、图标,截图目录加进.gitignore”。外部技能包带进来的不只是代码,还有内容和许可证,内网审查必须把这一条单列。
顺带一个反直觉的结论:不要因为某个技能“外部依赖多”就一刀切掉,要看它的依赖能不能被替换成内部等价物。 research 的方法论(分轨并行、标签化证据、决策必须引用证据或测试计划)在内网一样成立,只需要把检索源换掉;而 clone 里 window-shot.sh 这条本地路径,反而比云端 computer use 更适合隔离环境。真正该拒的是那些没有降级路径的技能——一旦出网失败就直接抛错、没有本地替代分支的,进了内网就是死代码。
写在最后:软约束要靠硬断点兜住
社区里对“企业级 Agent 落地”的讨论,近期反复落在同一个词上:Harness。它的要点是把软件工程的门禁(决策、规划、评审、验证、复盘)变成对 Agent 的约束范式;同时,实践者也承认这是一层软约束——提示词能命中大部分场景,但命中率不可能是 100%。
BAMA 给出的答案是把软约束尽量往硬断点上压:Done when 是软的语言约定,grid-lint 的 exit 1、selftest.sh 的退出码、check-agent-cli.sh 的 PASS agent CLI 是硬的机器判定;AGENTS.md 的写作规则是软的文化,plugin.json 的显式清单与 link-skills.sh 的软链接是硬的装配事实。
内网环境装技能包,最终要交付的其实是这套“可断言的形状”:一条不依赖外网的装配路径、一份列得清来源的配置清单、一套能被脚本判定的终态定义,以及一条每个技能都写得出来的降级路径。技能本身会过时,这四样东西不会。