可移植 Skill 打包

概述

把依赖本机环境（绝对路径、本地模型、本机索引数据）的 Qoder Skill 转换为可复制到其他电脑直接安装的交付包。交付包不含任何本机数据，依赖由幂等安装器补齐，模型由用户手动下载。

触发场景

• 用户要求技能「换电脑也能用」，或要生成可移植/可迁移的技能交付包
• 待交付技能含本地模型路径、盘符绝对路径或本机数据库/索引文件

打包流程

1. 审查本机依赖

• Grep 整个技能目录中的绝对路径模式：[A-Z]:\\、/Users/、/home/，逐一改为可移植形式
• 识别三类本机依赖：模型或运行器路径、索引/数据库文件、临时测试产物（__pycache__、*.pyc、测试用配置）
• 记录运行时依赖及最低版本要求及其原因（例如 node:sqlite 需要 Node.js ≥ 22.5）

2. 相对化配置

• 配置中的路径改用 {{configDir}} 等占位符，解析基准必须是配置文件所在目录，不能依赖进程启动目录（按工作目录解析会导致运行时静默回退，这是已踩过的坑）
• 模型统一放技能内固定相对目录（如 models/<模型名>），不指向用户盘符
• 改完后在原技能目录用完整绝对路径运行一次，确认行为未回退

3. 幂等环境检查

• 生成 scripts/setup-environment.mjs：检查 Node.js、Python、Python 包，维护模块名到包名的映射（如 openvino_genai → openvino-genai）
• --install 仅安装缺失项；已安装依赖跳过并输出 ready
• 模型缺失时明确报错并 exit 1，写明模型下载被有意禁用、按 README 手动下载；绝不自动下载模型
• 环境检查中的模型路径同样相对技能目录解析（曾出现相对路径解析到技能目录之外的 bug，需专门验证）

4. 排除本机数据

交付包禁止包含：

• data/、*.sqlite 等索引数据库（内含旧机器绝对路径，新机必须重建索引）
• 模型文件本体（由用户手动下载放置）
• __pycache__、*.pyc、临时测试配置与测试目录

打包前用 Glob 核对交付目录最终文件清单，确认无以上残留。

5. 编写安装 README

• 目标安装位置（用户级 C:\Users\<用户名>\.qoder\skills\<skill-name> 或项目级 .qoder/skills/）
• 依赖清单、最低版本及原因
• 每个模型的官方下载链接（打包时重新搜索核实，不沿用旧链接）、放置目录、初始化命令
• 交付目录名必须与技能名一致

6. 双状态验证

• 依赖已装状态：环境检查全部 ready，--install 不重复安装
• 模型缺失状态：明确报错并指引 README，不触发下载
• 语法校验（node --check、python -m py_compile）与 JSON 配置校验
• 原技能本机回归：关键词查询与 AI 查询各执行一次，行为不劣化

风险与边界

• 环境检查脚本与相对化改法必须按目标技能的实际依赖定制，本流程提供模式而非万能脚本
• README 中的模型下载链接可能失效，每次打包前重新核实
• 新电脑不复用旧索引：旧 SQLite 含旧机器路径，运行 init 重建
• 修改用户 Skill 的 SKILL.md 时走 skill_manage；不修改内置/插件 Skill