一、问题背景Spec Kit 是 GitHub 开源的 Spec-Driven Development 工具用 specify init 初始化项目时会从 GitHub API 拉取最新模板。在国内或企业网络环境下常会遇到401 UnauthorizedGitHub API returned status 401 for https://api.github.com/repos/github/spec-kit/releases/latest配置了 Token 仍失败设置了 GITHUB_TOKEN 或 --github-token 依然报 401Windows 编码错误UnicodeEncodeError: ‘gbk’ codec can’t encode character ‘\u2022’二、原因分析2.1 401 的常见原因原因 说明Token 无效或过期 环境变量中的 Token 已失效仍被发送GitHub 返回 401网络/代理限制 国内或企业网络无法稳定访问 GitHub APIToken 传递方式错误 使用 .env 或错误格式导致未正确传递根据 GitHub https://github.com/github/spec-kit/issues/378若环境变量 GITHUB_TOKEN 或 GH_TOKEN 存在但 Token 无效Spec Kit 会带上该 Token 请求 API反而会触发 401。取消设置这些变量改用匿名请求有时可以成功。2.2 Token 配置无效https://github.com/github/spec-kit/issues/1076 中用户将 Token 写在 .env 中仍失败改为在命令行中直接传入后成功错误依赖 .env 或环境变量specify init . --github-token GITHUB_TOKEN # 传的是字面量不是真实 Token# 正确直接传入真实 Tokenspecify init . --ai claude --github-tokenghp_你的实际token三、常规排查步骤在尝试本地化方案前可先按下面顺序排查步骤 1清空 Token 后重试匿名访问PowerShell$env:GITHUB_TOKEN n u l l nullnullenv:GH_TOKEN $nullspecify init . --ai claudeBashunset GITHUB_TOKEN GH_TOKENspecify init . --ai claude步骤 2正确传入 Tokenspecify init . --ai claude --github-tokenghp_你的真实token步骤 3配置代理国内环境e n v : H T T P P R O X Y h t t p : / / 127.0.0.1 : 7890 env:HTTP_PROXY http://127.0.0.1:7890env:HTTPPROXYhttp://127.0.0.1:7890env:HTTPS_PROXY http://127.0.0.1:7890specify init . --ai claude步骤 4企业网络 / SSL 问题specify init . --ai claude --skip-tls若以上都无效建议采用下面的本地化方案。四、本地化解决方案推荐思路不再依赖 GitHub API从本地 spec-kit 源码构建模板 zip用 --local-template 初始化。4.1 克隆 Spec Kit 源码git clone https://github.com/github/spec-kit.git spec-kit-tempcd spec-kit-temp4.2 构建本地模板Spec Kit 的 create-release-packages.sh 会生成模板目录但在 Windows 上常因缺少 zip 命令而失败。可先用脚本生成目录再用 Python 打 zip1. 生成模板目录会在 zip 步骤失败但目录已生成bash .github/workflows/scripts/create-release-packages.sh v0.3.2# 2. 用 Python 生成 zipWindows 无 zip 时使用python -c “import zipfilefrom pathlib import Pathbase Path(‘.genreleases/sdd-claude-package-sh’)zip_path Path(‘.genreleases/spec-kit-template-claude-ps-v0.3.2.zip’)with zipfile.ZipFile(zip_path, ‘w’, zipfile.ZIP_DEFLATED) as zf: for f in base.rglob(‘*’): if f.is_file(): zf.write(f, f.relative_to(base))print(‘Created:’, zip_path.resolve())”4.3 使用本地模板初始化在当前目录初始化uv run --project f:\path\to\spec-kit-temp specify init . --ai claude \ --local-template f:\path\to\spec-kit-temp.genreleases\spec-kit-template-claude-ps-v0.3.2.zip \ --here --force4.4 一键构建脚本可将上述步骤写成 build-local-template.sh方便重复使用#!/usr/bin/env bashset -ecd “$(dirname “0 ) B A S E . g e n r e l e a s e s / s d d − c l a u d e − p a c k a g e − s h i f [ [ ! − d 0)BASE.genreleases/sdd-claude-package-shif [[ ! -d 0)BASE.genreleases/sdd−claude−package−shif[[!−dBASE” ]]; then echo “Building template package…” bash .github/workflows/scripts/create-release-packages.sh v0.3.2fiif [[ -d “$BASE” ]]; then echo “Creating zip archive…” python -c import zipfilefrom pathlib import Pathbase Path(”.genreleases/sdd-claude-package-sh)zip_path Path(“.genreleases/spec-kit-template-claude-ps-v0.3.2.zip”)with zipfile.ZipFile(zip_path, “w”, zipfile.ZIP_DEFLATED) as zf: for f in base.rglob(“*”): if f.is_file(): zf.write(f, f.relative_to(base))print(“Created:”, zip_path.resolve())’ echo Done. Use: specify init . --ai claude --local-template $(pwd)/.genreleases/spec-kit-template-claude-ps-v0.3.2.zip --here --forceelse echo “Error: Package dir not found.” exit 1fi保存后执行bash build-local-template.sh五、关于 --local-template 选项–local-template 并非 Spec Kit 官方默认支持需自行修改源码。若使用官方未修改版本可在能访问 GitHub 的环境如云服务器、VPN完成 specify init再把生成的项目拷贝到本地或向 spec-kit 仓库 提交 Issue/PR请求增加离线/本地模板支持。六、Windows 编码问题若出现 UnicodeEncodeError: ‘gbk’ codec can’t encode character ‘\u2022’多为错误信息中的 Unicode 字符如 •在 GBK 下无法编码。可尝试切换控制台为 UTF-8chcp 65001或设置环境变量$env:PYTHONIOENCODING “utf-8”若使用修改过的 Spec Kit 源码可将错误文案中的 • 替换为 -避免 GBK 编码问题。七、总结场景 建议方案能访问 GitHub 清空无效 Token 或正确传入 Token国内/企业网络 配置代理或使用本地模板完全离线 克隆 spec-kit本地构建 zip用 --local-template 初始化Windows 编码报错 chcp 65001 或修改错误信息中的 Unicode 字符希望本文能帮助遇到类似问题的开发者顺利完成 Spec Kit 的本地化使用。参考资料https://github.com/github/spec-kithttps://github.com/github/spec-kit/issues/378 - 401 with invalid tokenhttps://github.com/github/spec-kit/issues/1076 - Token in .env not workinghttps://github.com/github/spec-kit/issues/273 - 403 rate limit / 国内代理配置 Spec Kit 鉴权问题与本地化解决方案
一、问题背景Spec Kit 是 GitHub 开源的 Spec-Driven Development 工具用 specify init 初始化项目时会从 GitHub API 拉取最新模板。在国内或企业网络环境下常会遇到401 UnauthorizedGitHub API returned status 401 for https://api.github.com/repos/github/spec-kit/releases/latest配置了 Token 仍失败设置了 GITHUB_TOKEN 或 --github-token 依然报 401Windows 编码错误UnicodeEncodeError: ‘gbk’ codec can’t encode character ‘\u2022’二、原因分析2.1 401 的常见原因原因 说明Token 无效或过期 环境变量中的 Token 已失效仍被发送GitHub 返回 401网络/代理限制 国内或企业网络无法稳定访问 GitHub APIToken 传递方式错误 使用 .env 或错误格式导致未正确传递根据 GitHub https://github.com/github/spec-kit/issues/378若环境变量 GITHUB_TOKEN 或 GH_TOKEN 存在但 Token 无效Spec Kit 会带上该 Token 请求 API反而会触发 401。取消设置这些变量改用匿名请求有时可以成功。2.2 Token 配置无效https://github.com/github/spec-kit/issues/1076 中用户将 Token 写在 .env 中仍失败改为在命令行中直接传入后成功错误依赖 .env 或环境变量specify init . --github-token GITHUB_TOKEN # 传的是字面量不是真实 Token# 正确直接传入真实 Tokenspecify init . --ai claude --github-tokenghp_你的实际token三、常规排查步骤在尝试本地化方案前可先按下面顺序排查步骤 1清空 Token 后重试匿名访问PowerShell$env:GITHUB_TOKEN n u l l nullnullenv:GH_TOKEN $nullspecify init . --ai claudeBashunset GITHUB_TOKEN GH_TOKENspecify init . --ai claude步骤 2正确传入 Tokenspecify init . --ai claude --github-tokenghp_你的真实token步骤 3配置代理国内环境e n v : H T T P P R O X Y h t t p : / / 127.0.0.1 : 7890 env:HTTP_PROXY http://127.0.0.1:7890env:HTTPPROXYhttp://127.0.0.1:7890env:HTTPS_PROXY http://127.0.0.1:7890specify init . --ai claude步骤 4企业网络 / SSL 问题specify init . --ai claude --skip-tls若以上都无效建议采用下面的本地化方案。四、本地化解决方案推荐思路不再依赖 GitHub API从本地 spec-kit 源码构建模板 zip用 --local-template 初始化。4.1 克隆 Spec Kit 源码git clone https://github.com/github/spec-kit.git spec-kit-tempcd spec-kit-temp4.2 构建本地模板Spec Kit 的 create-release-packages.sh 会生成模板目录但在 Windows 上常因缺少 zip 命令而失败。可先用脚本生成目录再用 Python 打 zip1. 生成模板目录会在 zip 步骤失败但目录已生成bash .github/workflows/scripts/create-release-packages.sh v0.3.2# 2. 用 Python 生成 zipWindows 无 zip 时使用python -c “import zipfilefrom pathlib import Pathbase Path(‘.genreleases/sdd-claude-package-sh’)zip_path Path(‘.genreleases/spec-kit-template-claude-ps-v0.3.2.zip’)with zipfile.ZipFile(zip_path, ‘w’, zipfile.ZIP_DEFLATED) as zf: for f in base.rglob(‘*’): if f.is_file(): zf.write(f, f.relative_to(base))print(‘Created:’, zip_path.resolve())”4.3 使用本地模板初始化在当前目录初始化uv run --project f:\path\to\spec-kit-temp specify init . --ai claude \ --local-template f:\path\to\spec-kit-temp.genreleases\spec-kit-template-claude-ps-v0.3.2.zip \ --here --force4.4 一键构建脚本可将上述步骤写成 build-local-template.sh方便重复使用#!/usr/bin/env bashset -ecd “$(dirname “0 ) B A S E . g e n r e l e a s e s / s d d − c l a u d e − p a c k a g e − s h i f [ [ ! − d 0)BASE.genreleases/sdd-claude-package-shif [[ ! -d 0)BASE.genreleases/sdd−claude−package−shif[[!−dBASE” ]]; then echo “Building template package…” bash .github/workflows/scripts/create-release-packages.sh v0.3.2fiif [[ -d “$BASE” ]]; then echo “Creating zip archive…” python -c import zipfilefrom pathlib import Pathbase Path(”.genreleases/sdd-claude-package-sh)zip_path Path(“.genreleases/spec-kit-template-claude-ps-v0.3.2.zip”)with zipfile.ZipFile(zip_path, “w”, zipfile.ZIP_DEFLATED) as zf: for f in base.rglob(“*”): if f.is_file(): zf.write(f, f.relative_to(base))print(“Created:”, zip_path.resolve())’ echo Done. Use: specify init . --ai claude --local-template $(pwd)/.genreleases/spec-kit-template-claude-ps-v0.3.2.zip --here --forceelse echo “Error: Package dir not found.” exit 1fi保存后执行bash build-local-template.sh五、关于 --local-template 选项–local-template 并非 Spec Kit 官方默认支持需自行修改源码。若使用官方未修改版本可在能访问 GitHub 的环境如云服务器、VPN完成 specify init再把生成的项目拷贝到本地或向 spec-kit 仓库 提交 Issue/PR请求增加离线/本地模板支持。六、Windows 编码问题若出现 UnicodeEncodeError: ‘gbk’ codec can’t encode character ‘\u2022’多为错误信息中的 Unicode 字符如 •在 GBK 下无法编码。可尝试切换控制台为 UTF-8chcp 65001或设置环境变量$env:PYTHONIOENCODING “utf-8”若使用修改过的 Spec Kit 源码可将错误文案中的 • 替换为 -避免 GBK 编码问题。七、总结场景 建议方案能访问 GitHub 清空无效 Token 或正确传入 Token国内/企业网络 配置代理或使用本地模板完全离线 克隆 spec-kit本地构建 zip用 --local-template 初始化Windows 编码报错 chcp 65001 或修改错误信息中的 Unicode 字符希望本文能帮助遇到类似问题的开发者顺利完成 Spec Kit 的本地化使用。参考资料https://github.com/github/spec-kithttps://github.com/github/spec-kit/issues/378 - 401 with invalid tokenhttps://github.com/github/spec-kit/issues/1076 - Token in .env not workinghttps://github.com/github/spec-kit/issues/273 - 403 rate limit / 国内代理配置