Spec Kit 接入国产模型实录401、proxy failed、OAuth 三连坑一份能直接照抄的排雷路径【免费下载链接】spec-kit Toolkit to help you get started with SDD or any other process!项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit把 Spec Kit 接上 DeepSeek、Qwen、Kimi、Lingma 这类国产模型的 CLI 时你大概率会按顺序撞上三堵墙先是 API 调用直接甩来401接着企业网络环境里冒出proxy failed最后绕开前两个坑又被平台的OAuth登录流程卡在门口。这三连坑不是玄学每一层的根因都能在仓库源码里找到对应位置。本文以真实接入实践为线索逐坑拆解报错成因并给出可以照抄的修复命令与配置模板。先说结论接入通道其实已经就位很多人的第一反应是Spec Kit 是不是不支持国产模型但实际上集成注册表早已覆盖主流国产/本土模型。打开 integrations/catalog.json 和官方集成清单 docs/reference/integrations.md 可以看到DeepSeek Harnessdshskills 型集成安装到.dsh/skills以/speckit-command触发Qwen Codeqwen命令文件写入.qwen/commands见 src/specify_cli/integrations/qwen/init.pyKimi Codekimiskills 型安装到.kimi-code/skills/并提供--migrate-legacy迁移旧布局Lingmalingma、Traetrae、ZCodezcode等也都有独立集成项。即使某款模型没在注册表里还有一条自带模型通道generic集成。它的定位就是 bring your own agent核心代码如下src/specify_cli/integrations/generic/init.pyspecify integration install generic --integration-options--commands-dir .myagent/cmds specify integration install generic --integration-options--commands-dir .myagent/skills --skills也就是说坑从来不在能不能接入而在接入之后模型 CLI 与 Spec Kit 两侧的网络与凭据怎么对齐。坑一401 Unauthorized —— token 没有去它该去的地方401的排查要先分清楚是哪一层在报错因为 Spec Kit 自身和模型 CLI 各有独立的认证体系。Spec Kit 自身的 HTTP 请求拉取 catalog、下载扩展、检查版本走的是 src/specify_cli/authentication/http.py 的open_url它的回退逻辑是本文最值得抄的一段for entry in entries: provider get_provider(entry.provider) token provider.resolve_token(entry) ... try: return opener.open(req, timeouttimeout) except urllib.error.HTTPError as exc: if exc.code in (401, 403): exc.close() continue # try next entry raise # No entry worked (or none matched) — unauthenticated fallback req _make_req({}) ... return opener.open(req, timeouttimeout)即按auth.json中匹配hosts的条目依次尝试遇到 401/403 就换下一个凭证全部失败后再以无认证请求兜底。这带来两个直接后果token 没配到对应的hosts上时请求会静默退化为匿名访问随后在远端收到 401配置了错误 token时401 会被静默吞掉继续降级最终仍以匿名请求失败收场——看起来就像没配 token。正确姿势在 docs/reference/authentication.md 里写得很明确token 一律走环境变量而非明文{ providers: [ { hosts: [github.com, api.github.com, raw.githubusercontent.com, codeload.github.com], provider: github, auth: bearer, token_env: GH_TOKEN } ] }写完记得chmod 600 ~/.specify/auth.json。而模型侧Qwen、DeepSeek、Kimi 各自的 API Key不要写进auth.json它属于模型 CLI 自己的凭据应该配置到 CLI 的配置文件或通过下面的环境变量注入通道传递。坑二proxy failed —— 企业网络的证书与代理proxy failed的坑通常分三层叠加需要逐层排除。第一层Spec Kit 自身请求。请求层基于标准库urllib.request见 src/specify_cli/authentication/http.py会遵循HTTP_PROXY/HTTPS_PROXY/NO_PROXY环境变量。在内网环境先确认这三个变量已正确导出。官方文档 docs/local-development.md 也明确指出企业网络的 TLS 报错需要配置证书存储或代理来解决且--skip-tls已被标记为废弃、不再生效——别再用跳过证书校验这种土办法。第二层安装层。uv/pipx拉取依赖同样要过代理安装指南 docs/install/uv.md 中专门说明了代理设置项。内网环境建议优先用离线包方案docs/install/air-gapped.md从根上绕开拉取失败。第三层模型 CLI 层这是最容易漏的。模型 CLI 是独立进程Spec Kit 通过subprocess把它拉起来执行src/specify_cli/integrations/base.py 的dispatch_command代理变量对它是继承生效的但如果 CLI 需要自己的--proxy参数就需要用 Spec Kit 提供的按集成命名的环境变量注入通道export SPECKIT_INTEGRATION_QWEN_EXTRA_ARGS--proxy http://proxy.internal:8080 export SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE/custom/path/kiro这两个变量的解析逻辑都在 src/specify_cli/integrations/base.py_resolve_executable()支持SPECKIT_INTEGRATION_KEY_EXECUTABLE覆盖二进制路径国产 CLI 常装在非标准位置_apply_extra_args_env_var()支持SPECKIT_INTEGRATION_KEY_EXTRA_ARGS注入任意 CLI 参数。它们同样适用于 CI 等非交互场景。坑三OAuth —— 设备码登录与 token 过期第三个高频坑是 OAuth。不少国产平台的控制台只提供 OAuth 设备码登录不直接发 API Key更麻烦的是 OAuth token 有时效过期后立刻打回 401。关键认知Spec Kit 的认证层原生支持 OAuth 形态的 token。以 docs/reference/authentication.md 中的 Azure DevOps 配置为例它的bearer方案明确写着Pre-acquired OAuth / Azure AD tokens还有azure-cliaz account get-access-token获取和azure-adOAuth2 client credentials 流两种自动化获取方式{ hosts: [dev.azure.com], provider: azure-devops, auth: azure-cli }映射到国产模型场景结论是能提前拿到 token 的平台就把 token 通过token_env挂给对应的 provider拿不到静态 token 的平台先在终端手动完成一次设备码登录让 CLI 把 refresh token 持久化到本地配置之后 Spec Kit 通过继承的环境与配置文件驱动它即可。需要注意的是认证层只在 401/403 时切换到下一个凭证条目它不会替你刷新过期 token——所以登录态过期和token 配错在日志里往往都是同一个 401排查时优先检查模型 CLI 的本地登录态是否还活着。兜底CI 校验脚本如何在链路全挂时仍能兜住网络与认证环节可能同时出问题但有一条链路是完全不依赖网络的本地脚本校验。这正是 scripts/bash/check-prerequisites.sh 与 Python 版 scripts/python/check_prerequisites.py 的价值所在。以 Python 版为例它的典型 CI 用法是./check_prerequisites.py --json --require-tasks --include-tasks行为要点对应源码逻辑校验 feature 目录、spec.md、plan.md、tasks.md是否按阶段齐全--require-spec/--require-tasks分别约束分析与实现阶段输出FEATURE_DIR与AVAILABLE_DOCSresearch.md、data-model.md、contracts/、quickstart.md等的 JSON 结构便于 CI 解析校验失败时向 stderr 报错并以非零退出码结束且明确提示下一步该跑哪个命令如Run specify plan first to create the implementation plan.产物检查只读文件系统不发起任何 HTTP 请求——所以在 401 / proxy / OAuth 全线故障时它依然能给出链路断了还是产物缺了的确定性判断避免把网络问题误判成流程问题。这条本地校验链与声明式工作流配合更佳。workflows/speckit/workflow.yml 定义了specify → plan → tasks → implement四步并在每步之间插入type: gate的人工评审闸门on_reject: abort。把check-prerequisites脚本挂到 CI 的对应阶段之前相当于给整条 SDD 流水线加了一层与模型无关的保险丝模型答得再好产物缺了就是缺了。排雷清单把全文浓缩成一份可照抄的核对表接入注册表已有的模型直接specify integration install key没有的就用generic--commands-dirsrc/specify_cli/integrations/generic/init.py。二进制与参数CLI 不在 PATH 用SPECKIT_INTEGRATION_KEY_EXECUTABLE需要代理/自定义参数用SPECKIT_INTEGRATION_KEY_EXTRA_ARGS。401先分清是 Spec Kit 侧配~/.specify/auth.jsontoken_env还是模型 CLI 侧配模型自己的 Key记住 401 会被认证层静默降级别被日志误导。proxy failed三层逐查——HTTP(S)_PROXY环境变量、uv/pipx安装代理、模型 CLI 自己的--proxy参数。OAuth能拿静态 token 就走bearertoken_env拿不到就在终端先完成设备码登录并意识到过期 token 不会自动刷新。CI 兜底check-prerequisites--json --require-tasks --include-tasks全程离线、退出码非零、错误走 stderr是网络故障时唯一可信的产物校验器。三连坑的排雷路径说到底只有一句话把 Spec Kit 的凭据、模型 CLI 的凭据、系统的代理配置三者各归其位再用离线校验脚本给整条链路兜底。照着这份清单走一遍国产模型接上 Spec Kit 只是时间问题而不是玄学问题。【免费下载链接】spec-kit Toolkit to help you get started with SDD or any other process!项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
