install-apm-package 技能用于管理 APM 原语到各自运行时环境的安全部署。它通过强制验证与目标发现，确保跨环境部署的字节级一致可复现性。
核心不可妥协项
- 源完整性：绝不直接编辑 .agents/、.github/ 或 .claude/ 中的文件。始终编辑 .apm/ 中的源文件并重新安装。
- 锁文件持久化：任何安装变更后必须提交 apm.lock.yaml。
- 验证优先：执行安装前始终运行 validate_apm_package.py。
- 项目根目录纪律：从项目根目录运行 apm install，以确保收敛的技能落入权威的 .agents/ 文件夹。在包目录内运行会创建本地隔离的产物。
决策树
- 全局激活？-> 从项目根目录运行 apm install ./path-to-package。
- 隔离测试？-> 在包目录内运行 apm install。
- 目标已推断？->（例如存在 .claude/）-> 运行 apm install。
- 目标不明确？->（无信号）-> apm install 将以代码 2 退出；询问用户明确的 --target（例如 agent-skills、claude、all）。
- 收敛技能？->（标准）-> 部署到 .agents/skills/。使用 --target agent-skills 进行显式技能部署。
- 旧版技能？->（按客户端路径）-> 使用 --legacy-skill-paths 标志。
- 生产/CI？-> 使用 --frozen 标志以确保符合锁文件。
工作流
- 验证 apm.yml 存在（本地或根目录）。
- 执行 python scripts/validate_apm_package.py。
- 选择执行上下文：
- 项目范围使用：cd <repo-root>
- 本地测试：cd <package-dir>
- 预览：apm install [--target <slug>] --dry-run --verbose。
- 运行：apm install [./relative-path-to-pkg] [--target <slug>] [--legacy-skill-paths]。
- 使用 --target all,agent-skills 部署到所有 harness 及收敛技能。
- 在执行根目录验证 apm.lock.yaml 更新。
重复可见性护栏 在推荐 all,agent-skills 之前，检查用户是在进行：
- 路由冒烟测试，还是
- 实际的日常运行时安装。 对于冒烟测试，all,agent-skills 是合适的。对于真实使用，优先选择与运行时匹配的最小目标列表。同时安装收敛技能和特定目标技能可能导致在扫描多个技能位置的运行时中出现重复技能可见性。
反模式
- 手动物化：手动将文件移入 .github/agents/ 而非使用 apm install。
- 忽略锁文件：添加依赖后未提交 apm.lock.yaml。
- 编辑产物：修改生成的运行时输出而非 .apm/ 源文件。