| name | offline-bundle-skill |
| description | 当用户提到"离线准备/离线打包/内网部署 zcode skill 的依赖"，或要把某个 skill 的依赖弄到无网络环境使用，或需要在不联网的机器上安装 skill 及其依赖时使用本 skill。覆盖场景：为 docx/pdf/Excel/PPT 等文档 skill 或任何开源 zcode skill 准备离线安装包；在内网机离线安装这些 skill。 |
offline-bundle-skill
为 zcode skill 离线准备依赖 + skill 本体。清单（manifest）是产品，pack.py/install.bat 是执行器，AI 分析方法是产线。
何时使用
- 用户要把某个 skill 部署到无网络的内网
- 用户要"离线打包 / 离线准备依赖"
- 新接入一个开源 skill，需要它的依赖清单
整体流程
联网机 内网机
│ │
├─ AI 分析 skill → manifest │
├─ python pack.py add ... │
│ ↓ 产出 offline-bundle/ │
│ 含 wheelhouse/ │ ──拷贝──►
│ skills/ install.bat │ install.bat → ~/.agents/skills/
命令速查
打包（联网机）：
python "%~dp0scripts\pack.py" add <skill-dir> --manifest <manifest.json> [--target "py:3.12,os:win,arch:amd64,node:20"] [--bundle <bundle-dir>]
安装（内网机）：
install.bat --bundle <bundle-dir> [--dry-run] [--skill <name>]
工作流（详见 references/）
- 接入新 skill：AI 读
references/how-to-analyze.md 分析依赖 → 产出 manifest → 你确认 → 跑 pack.py add
- 追加新 skill（增量）：pack.py 累加进同一个 bundle → 内网 robocopy /MIR → install.bat
- 补缺包：改 manifest → 重跑 pack.py（去重只补缺）→ robocopy → install.bat 重跑
关键概念
- manifest.json：一 skill 一清单，唯一输入。schema 见
templates/manifest.template.json。
- target 环境：manifest 强制记录，pack.py 据此交叉下载。优先级：
--target > manifest.target > 探测本机。
- wheelhouse 池：跨 skill 共享 pip/npm 文件池。
- pip：
.whl 文件名天然去重。
- npm：整棵依赖树落盘到
wheelhouse/npm/node_modules/（不是裸 tgz）。
npm 包有传递依赖，裸 tgz 内网 npm install -g 会联网失败，所以必须整树安装，
内网靠"拷 node_modules + NODE_PATH"使用，零 npm 零网络。
- manual 项：体大/不稳的 exe（libreoffice），只 warn 不阻断。
详见 references/how-to-analyze.md（分析方法）、references/known-recipes.md（docx/pdf 现成清单）、
references/gotchas.md（实现陷阱库——修改脚本前必读）。
给维护者：修改脚本前
如果你要改 pack.py / install.bat / _check_install.py，或给本 skill 加功能，
先读 references/gotchas.md。它记录了开发中真实踩过的 batch 引号/括号陷阱、
pip dry-run 跨版本误判、URL 注释误删等问题。重蹈这些覆辙会浪费大量调试时间。
验收状态（开发机）
以下在联网开发机（Python 3.14，为目标 cp313/win_amd64 交叉下载）验证通过：
pack.py add docx/pdf 端到端打包（pip/npm/playwright/tools/skill 本体）- npm 整树方案：docx/image-size/pdf-lib/playwright 连传递依赖落盘到共享
node_modules/（28 包），内网靠"拷贝 + NODE_PATH"使用，不调 npm install
- wheelhouse 跨 skill 去重（reportlab 只 1 份）
- manifest-index 累加（docx + pdf 共存，target=3.13）
- playwright chromium 下载到 pw-browser/
install.bat 真实安装：pip 装、npm node_modules 拷全局、skill 落盘 ~/.agents/skills/、
重装备份用 move /Y（ren 会在同名备份已存在时卡死）- 内网实跑通过（Python 3.13.9 + Anaconda）：install.bat 全流程完成，skill 装入
内网部署要点（target 必须匹配内网 Python 版本）：
- bundle 的 pip wheel 按 target.python 的 cp 标签下载（cp312 ≠ cp313，装不上就换版本重打）
- 内网跑
install.bat --dry-run 先自检；npm 装完新开终端让 NODE_PATH 生效
