企业官网建设流程全解析

Spec Kit 在无网络（Air-Gapped）环境如何安装：构建 wheel 包并离线初始化项目

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

如果你的环境屏蔽了对 PyPI 和 GitHub 的访问（典型的企业管理内网场景），常规的uv tool install specify-cli或pip install specify-cli都无法完成。Spec Kit 官方为此提供了一条便携 wheel 包路径：先在一台有网的机器上构建 wheel 并下载全部运行依赖，把整个dist/目录拷贝到目标机器，再离线安装、离线初始化项目。安装指南也确认：从该仓库本地构建的 wheel 是离线 / air-gapped 环境下的有效安装方式。

本文依据 Enterprise / Air-Gapped Installation 与 Installation Guide 走通这条完整流程。

开始前的环境条件

三个文档明确的适用条件，任何一条不满足都需要先处理：

• 目标机器：Python 3.11+。
• 构建机：必须与目标机器相同的操作系统和 Python 版本。原因是pip download解析的是平台相关的 wheel（例如 PyYAML 含原生扩展），在别的系统或 Python 版本上下载的依赖可能与目标机器不匹配。若要同时支持多个平台，需要在每个目标 OS（Linux、macOS、Windows）和每个 Python 版本上各重复一次构建步骤。
• Windows 目标机器：离线脚手架要求 PowerShell 7+（pwsh），Windows PowerShell 5.x（powershell.exe）不满足要求，需要先安装 PowerShell 7+。

另外，安装指南将 Git 列为可选依赖——仅当启用 git 扩展时才需要。离线流程本身不依赖 Git 扩展。

第 1 步：在有网机器上构建 wheel 并下载依赖

在构建机上执行（文档原命令）：

# Clone the repository git clone https://github.com/github/spec-kit.git cd spec-kit # Build the wheel pip install build python -m build --wheel --outdir dist/ # Download the wheel and all its runtime dependencies pip download -d dist/ dist/specify_cli-*.whl

逐条说明：pip install build在有网机器上安装构建工具，本身需要网络；python -m build --wheel把仓库构建为 wheel 并输出到dist/；最后一条pip download是关键——它以刚构建出的specify_cli-*.whl为输入，把该 wheel 及所有运行时依赖都下载为本地 wheel 文件放进dist/，这一步完成后dist/就是离线安装所需的全部内容。

离线可用的原因：构建配置（见 pyproject.toml 中的force-include段）会把模板（templates/）、三种自动化脚本（scripts/bash、scripts/powershell、scripts/python）、git/agent-context/assess/bug 扩展、speckitworkflow 和 lean/constitution-sync 预设打进 wheel 的core_pack中，注释明确写着这是为了让specify init在无网络环境下工作。所以第 4 步的初始化不需要任何网络请求。

关于版本：air-gapped 文档没有指定要克隆哪个版本，wheel 的版本取决于你克隆时的提交；安装指南对源码安装的建议是固定到一个 release tag（例如v0.12.11，保留前导v），如需版本可复现可先检出对应 tag 再构建。

第 2 步：传输dist/目录

将完整的dist/目录（包含specify-cliwheel 和全部依赖 wheel）通过 USB、网络共享或组织内认可的方式拷贝到目标机器。文档对传输方式没有其他限制。

第 3 步：在目标机器上离线安装

在dist/目录所在位置执行：

pip install --no-index --find-links=./dist specify-cli

• --no-index：安装过程不查询 PyPI，因此不依赖外网；
• --find-links=./dist：让 pip 从本地dist/中查找上一步拷贝过来的 wheel 及其依赖。

第 4 步：验证安装

specify version

按安装指南，这是本地的版本/运行检查：确认specify命令可用并报告版本。它不能证明该可执行文件来自 PyPI 还是本地构建的 wheel。

第 5 步：离线初始化项目

specify init my-project --integration copilot

air-gapped 文档明确说明该命令不需要网络访问——默认使用 wheel 内置的 bundled assets。my-project是文档示例中的项目名，换成你自己的项目名即可；按 快速上手指南的说明，也可以用specify init .在当前目录初始化。

关于--integration参数的文档依据：

• 交互式终端中，init会提示你选择编码代理集成；
• 非交互式会话（CI 或管道运行）在未传--integration时默认 GitHub Copilot，air-gapped 示例正是显式传了--integration copilot；
• 需要其他代理时，安装指南给出的取值示例为claude、gemini、copilot、codebuddy、pi、omp。

可选参数（安装指南与快速上手指南）：

• --script sh|ps|py强制指定自动化脚本类型；不传时 Windows 默认ps、其他系统默认sh，交互模式下未传会提示选择；
• --non-interactive：CI 或 AI agent 环境使用，让未指定的选项采用文档默认值，而不是卡在方向键选择器上。

第 6 步：验证初始化结果

按安装指南，初始化成功后应看到两类结果：

1. 项目下出现与所选脚本类型对应的自动化脚本目录：
   • .specify/scripts/bash/（Linux/macOS 默认，含.sh脚本）
   • .specify/scripts/powershell/（Windows 默认，含.ps1脚本）
   • .specify/scripts/python/（--script py时，同时安装平台 shell 回退脚本）
2. 编码代理中可用以下命令：/speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement、/speckit.analyze、/speckit.clarify、/speckit.checklist、/speckit.constitution、/speckit.converge、/speckit.taskstoissues。

已知问题与限制

Linux 上 Git 认证有问题（可选分支）：air-gapped 文档附带了一个安装 Git Credential Manager v2.6.1 的脚本。注意该脚本的副作用：从 GitHub Releases 下载.deb文件、用sudo dpkg -i安装系统包、修改全局 git 配置（credential.helper manager）、最后删除下载的.deb。它需要 sudo 权限，且脚本内下载地址指向 GitHub Releases，因此只能在可以访问 GitHub 的机器上运行（例如构建机），不适用于完全断网的目标机：

#!/usr/bin/env bash set -e echo "Downloading Git Credential Manager v2.6.1..." wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb echo "Installing Git Credential Manager..." sudo dpkg -i gcm-linux_amd64.2.6.1.deb echo "Configuring Git to use GCM..." git config --global credential.helper manager echo "Cleaning up..." rm gcm-linux_amd64.2.6.1.deb

边界说明：离线安装和初始化完成后，后续在编码代理中使用/speckit.*命令本身是本地行为；但拉取上游新版本等操作仍需要网络，air-gapped 文档未覆盖这部分场景。

下一步

安装与初始化就绪后，即可按 Quick Start Guide 开始 Spec-Driven Development。较短路径为：/speckit.specify→/speckit.plan→/speckit.tasks→/speckit.implement→/speckit.converge；生产级特性可在其中加入/speckit.clarify、/speckit.checklist、/speckit.analyze作为质量门。

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit