本地开发指南

本指南展示如何在不发布版本或不提交到 main 分支的情况下，本地迭代 specify CLI。

脚本现同时提供 Bash（.sh）与 PowerShell（.ps1）两种版本。CLI 会根据操作系统自动选择，除非传入 --script sh|ps。

1. 克隆并切换分支

  1. git clone https://github.com/github/spec-kit.git 
  2. cd spec-kit
  3. # 切换到功能分支
  4. git checkout -b your-feature-branch

2. 直接运行 CLI（最快反馈）

无需安装，通过模块入口点即可执行 CLI：

  1. # 在仓库根目录
  2. python -m src.specify_cli --help
  3. python -m src.specify_cli init demo-project --ai claude --ignore-agent-tools --script sh

如喜欢脚本文件风格（使用 shebang）：

  1. python src/specify_cli/__init__.py init demo-project --script ps

3. 使用可编辑安装（隔离环境）

使用 uv 创建隔离环境，确保依赖与最终用户完全一致：

  1. # 创建并激活虚拟环境（uv 自动管理 .venv）
  2. uv venv
  3. source .venv/bin/activate  # 或在 Windows PowerShell：.venv\Scripts\Activate.ps1
  5. # 以可编辑模式安装项目
  6. uv pip install -e .
  8. # 现在 'specify' 入口点可用
  9. specify --help

代码修改后无需重新安装，因为处于可编辑模式。

4. 使用 uvx 直接从 Git（当前分支）调用

uvx 可从本地路径（或 Git 引用）运行，模拟用户流程：

  1. uvx --from . specify init demo-uvx --ai copilot --ignore-agent-tools --script sh

也可在不合并的情况下指向特定分支：

  1. # 先推送工作分支
  2. git push origin your-feature-branch
  3. uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch  specify init demo-branch-test --script ps

4a. 任意路径 uvx（可在任意位置运行）

如在别的目录，使用绝对路径而非 .：

  1. uvx --from /mnt/c/GitHub/spec-kit specify --help
  2. uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --ai copilot --ignore-agent-tools --script sh

为便捷可设置环境变量：

  1. export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit
  2. uvx --from "$SPEC_KIT_SRC" specify init demo-env --ai copilot --ignore-agent-tools --script ps

（可选）定义 shell 函数：

  1. specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; }
  2. # 然后
  3. specify-dev --help

5. 测试脚本权限逻辑

执行 init 后，检查 POSIX 系统上的 shell 脚本是否可执行：

  1. ls -l scripts | grep .sh
  2. # 期望有所有者执行位（如 -rwxr-xr-x）

在 Windows 你会使用 .ps1 脚本（无需 chmod）。

6. 运行 Lint / 基础检查（可自定义）

目前未内置强制 lint 配置，但可快速检查导入：

  1. python -c "import specify_cli; print('Import OK')"

7. 本地构建 Wheel（可选）

发布前验证打包：

  1. uv build
  2. ls dist/

如需可安装到全新临时环境。

8. 使用临时工作区

在脏目录测试 init --here 时，创建临时工作区：

  1. mkdir /tmp/spec-test && cd /tmp/spec-test
  2. python -m src.specify_cli init --here --ai claude --ignore-agent-tools --script sh  # 如果仓库已复制到此

或仅复制修改后的 CLI 部分，以获得更轻量的沙箱。

9. 调试网络 / TLS 跳过

实验时如需绕过 TLS 验证：

  1. specify check --skip-tls
  2. specify init demo --skip-tls --ai gemini --ignore-agent-tools --script ps

（仅用于本地实验。）

10. 快速编辑循环总结

操作 命令
直接运行 CLI python -m src.specify_cli --help
可编辑安装 uv pip install -e . 然后 specify ...
本地 uvx 运行（仓库根） uvx --from . specify ...
本地 uvx 运行（绝对路径） uvx --from /mnt/c/GitHub/spec-kit specify ...
Git 分支 uvx uvx --from git+URL@branch specify ...
构建 wheel uv build

11. 清理

快速删除构建产物 / 虚拟环境：

  1. rm -rf .venv dist build *.egg-info

12. 常见问题

现象 解决
ModuleNotFoundError: typer 执行 uv pip install -e .
脚本在 Linux 不可执行 重新运行 init 或 chmod +x scripts/*.sh
Git 步骤被跳过 你传入了 --no-git 或未安装 Git
下载了错误的脚本类型 显式传入 --script sh 或 --script ps
企业网络 TLS 错误 尝试 --skip-tls（不用于生产）

13. 后续步骤

  • 更新文档并用你修改后的 CLI 走一遍快速入门
  • 满意后开启 PR -（可选）变更合并到 main 后打标签发布