npm-git-install

基于 Git 的 Node 软件包安装

当核心问题是**“我们应该信任哪个安装软件包？哪种交付路径适合此依赖？接下来该怎么做？”**时，请使用此技能。

任务不是罗列所有语法变体，也不是把原始 Git 安装当作常规基础设施。 任务是：

1. 规范化手头已有的软件包交付信息包，
2. 选择一种主要交付模式，
3. 明确说明持久性、身份验证和构建方面的影响，
4. 根据实际使用的软件包管理器定制命令，
5. 当临时 Git 桥接开始变成永久方案时，提供清晰的退出路径。

处理不熟悉的交付信息包前，请阅读 references/intake-packets-and-route-outs.md。 在 Git、tarball、工作区或先发布之间进行选择时，请阅读 references/delivery-decision-matrix.md。 如需了解特定软件包管理器的注意事项，请阅读 references/package-manager-behavior.md。 如果信息包中已涉及 CI 或私有身份验证，请阅读 references/private-auth-and-ci.md。

何时使用此技能

• 用户想从 GitHub 或其他 Git 托管平台安装 Node 软件包
• 软件包尚未发布、来自 fork、固定到分支、标签或提交，或者是私有软件包
• 软件包位于 monorepo 中，用户不确定 Git 安装、工作区链接、tarball 还是先发布才是合适的选择
• 用户询问 git+ssh、git+https、github:owner/repo、tarball 安装、npm pack 或 file: / 工作区链接
• 共享依赖仍被当作临时 Git 捷径使用，需要有人判断是否应继续采用该捷径

何时不要使用此技能

• 主要任务是修复本地 Git 分支/历史问题 → 使用 git-workflow
• 主要任务是在管理层面创建或运维 GitHub 仓库、软件包或发行版 → 使用 github-repo-management
• 主要任务是 monorepo / 任务运行器自动化，而非选择软件包交付方式 → 使用 deployment-automation
• 主要任务是更广泛的运行时、机器、容器或服务设置 → 使用 system-environment-setup
• 用户已有常规的注册表依赖，只需要进行普通版本升级

指令

步骤 1：从手头已有的交付信息包开始

使用 references/intake-packets-and-route-outs.md。

将请求规范化为以下某种信息包类型：

• temporary-bridge-packet — 尚未发布的修复、fork、PR 分支，或用于立即解除阻塞的短期桥接方案
• shared-bridge-packet — 队友或 CI 也需要使用此桥接方案，因此分支漂移和锁文件稳定性很重要
• private-auth-packet — 安装路径是私有的，真正的风险在于本地与 CI 凭证的一致性
• artifact-fallback-packet — 原始 Git 源码安装过于脆弱，但完整的注册表工作流仍然过于繁重
• workspace-inner-loop-packet — 应用和软件包正在本地或 monorepo 中一起开发
• durable-distribution-packet — 此依赖已不再是一次性桥接方案，可能不应继续按桥接方案的方式处理

记录最少但有用的背景信息：

Packet: shared-bridge-packet
Package manager: pnpm
Package state: unpublished fork fix
Audience: CI + teammates
Current ref: feature branch
Main risk: branch drift and auth parity

规则：从用户已有的信息包开始。回答前不要强迫用户填写一份完美的发行管理模板。

Step 2：选择一种主要交付模式

恰好选择一种主要模式：

• direct-git-bridge — 仅限本地，或明确为临时的 Git 桥接
• sha-pinned-shared-bridge — 仍以 Git 为桥接方式，但需要保证共享使用的可复现性
• private-git-auth-path — 短期方案仍是私有 Git，关键约束是身份验证一致性
• tarball-or-pack-artifact — 打包依赖项，不依赖原始 Git 源码安装行为
• workspace-or-file-link — 保持本地协同开发，或限定在单体仓库内
• publish-first-registry-path — 转向持久的分发渠道

可选：提及一种备用模式，但不要把每个请求都简化成六选一的菜单。

Step 3：确定持久性等级

使用简明的持久性模型：

• 第 0 级 — 仅限本地
• 第 1 级 — 团队 / CI 桥接
• 第 2 级 — 持久的共享软件包
• 第 3 级 — 生产 / 发布基础设施

仅记录会影响决策的内容：

• 谁会使用它
• 引用是浮动的还是固定的
• 是否能接受原始源码安装行为
• 本地与 CI 是否已有一致的身份验证方案
• 如果依赖项持续存在，应采用什么退出路径

如果请求涉及多个等级，则按最高等级规划。

Step 4：从阶梯中选择最安全的模式

使用 references/delivery-decision-matrix.md。

默认顺序：

1. publish-first-registry-path
2. workspace-or-file-link
3. sha-pinned-shared-bridge
4. tarball-or-pack-artifact
5. direct-git-bridge

规则：

• 共享使用时，优先选择 SHA 固定引用，而非浮动分支
• 如果原始 Git 构建 / prepare 行为存在风险，优先选择 制品或优先发布
• 如果双方在本地共同迭代，优先选择 工作区 / 文件
• 将 私有身份验证视为约束，而非 Git 适合作为长期渠道的证明

Step 5：根据所用包管理器调整命令

只提供范围最小且正确的语法。

常见模式：

• SHA 固定桥接：npm install github:owner/repo#<commit> / pnpm add github:owner/repo#<commit> / yarn add owner/repo#<commit> / bun add github:owner/repo#<commit>
• Git URL 形式：git+https://github.com/owner/repo.git#<commit> 或 git+ssh://[email protected]/owner/repo.git#<commit>
• Tarball：npm install https://.../package.tgz（或 pnpm / Yarn / Bun 的等效命令）
• 本地路径："dep": "file:../relative-path" 或常规工作区流程

如果优先发布才是正确方案，应先给出交接计划，再列出临时 Git 语法。

Step 6：明确身份验证、构建和可复现性

每个回答都必须说明：

• 所选引用 / 制品 / 发布版本策略
• 安装是否会拉取原始源码并触发生命周期 / 构建行为
• 本地与 CI 的身份验证方案
• 确定性安装预期（npm ci、冻结锁文件的等效方式、固定引用）
• 依赖项不再是临时方案后，如何替换

默认原则：

• 浮动分支是方便的捷径，不是共享基础设施
• 私有 Git 的可靠性取决于身份验证配置最差的环境
• Tarball 用制品所有权问题换取避免 Git 带来的意外
• 一旦软件包成为常规共享基础设施，优先发布通常才是坦诚的答案

Step 7：立即将后续工作交给负责人

此技能负责选择软件包交付方式，不负责所有后续任务。

常见转交方向：

• git-workflow — 修正或规划底层分支 / 历史状态
• github-repo-management — 管理仓库、软件包、发布或软件包托管设置
• deployment-automation — 围绕所选软件包流程配置可重复的仓库脚本或单体仓库自动化
• system-environment-setup — 当依赖项问题不再是主要障碍后，处理机器 / 运行时 / 容器 / 服务设置

如果用户问“我们应该如何使用这个软件包？”，请留在此处。 如果用户问“如何管理托管，或在平台层面修复身份验证？”，请转交处理。

步骤 8：生成一份简洁的安装简报

返回一份简短的操作人员风格简报，包含：

• 交付包
• 主要模式
• 持久性等级
• 1-3 个建议步骤
• 仅包含所需命令
• 身份验证／构建／可复现性说明
• 退出策略
• 如果工作移交出此技能，注明下一位负责人

如果坦诚的答案是“发布这个包，或妥善打包”，就直接这么说。

输出格式

始终返回一份Git 包安装简报、制品建议简报或优先发布交接简报。

必须具备以下特征：

• 明确指出手头已有的交付包
• 选择一种主要交付模式
• 明确分类持久性
• 清楚说明身份验证／构建／可复现性方面的影响
• 根据实际使用的包管理器定制命令
• 明确说明退出策略
• 将包托管、仓库管理、工作流衔接或环境设置转交给适当的相邻技能

示例

示例 1：在 CI 中共享尚未发布的修复

输入

我们需要在 npm 应用中使用 GitHub 仓库里尚未发布的修复。在分支上安装，还是采用更安全的 CI 方案？

良好输出方向

• shared-bridge-packet
• sha-pinned-shared-bridge
• 不建议在共享 CI 中使用浮动分支
• 给出一条针对 npm 的命令和一条退出路径

示例 2：私有包身份验证问题

输入

我们的包位于 GitHub 私有仓库中，pnpm install 在 CI 中一直失败。应该采用什么方案？

良好输出方向

• private-auth-packet
• 选择 private-git-auth-path 或 publish-first-registry-path
• 说明 CI 凭据一致性，避免提交密钥

示例 3：Monorepo 或持久共享包

输入

包位于 monorepo 中。我本地使用 Yarn，但团队其他成员只需要在常规项目中使用这个包。应该直接从 GitHub 安装吗？

良好输出方向

• workspace-inner-loop-packet 或 durable-distribution-packet
• 本地协同开发优先选择 workspace／file:，持久使用则优先选择先发布
• 不要过度推荐直接从 Git 安装

最佳实践

1. 从手头已有的交付包入手，而不是从偏好的语法形式入手。
2. 将 Git 引用视为过渡方案，而非默认发布渠道。
3. 只要 Git 依赖会被共享，就优先使用 SHA 固定版本，而不是浮动分支。
4. 尽早说明生命周期／构建行为；直接从 Git 安装可能相当于打包源代码，而非下载注册表中的包。
5. 明确区分本地、团队／CI 和持久共享这几种用法。
6. 将私有身份验证问题视为重新评估交付路径的信号，而不是永远修补凭据。
7. 依赖不再是临时方案后，建议采用持久的退出路径。
8. 如果入口文案发生实质性变化，应更新精简版和发现入口。

参考资料

• 接收信息包与转交路径
• 交付决策矩阵
• 包管理器行为
• 私有身份验证与 CI 说明
• ../git-workflow/SKILL.md
• ../github-repo-management/SKILL.md
• ../deployment-automation/SKILL.md
• ../system-environment-setup/SKILL.md
• npm 包规范：https://docs.npmjs.com/cli/v11/using-npm/package-spec
• npm package.json 的 Git 文档：https://docs.npmjs.com/cli/v11/configuring-npm/package-json
• npm pack：https://docs.npmjs.com/cli/v11/commands/npm-pack
• pnpm add：https://pnpm.io/cli/add
• pnpm workspaces：https://pnpm.io/workspaces
• Yarn Git 协议：https://yarnpkg.com/protocol/git
• Yarn workspaces：https://yarnpkg.com/features/workspaces
• Bun add：https://bun.sh/docs/pm/cli/add
• GitHub Packages：https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages