Metadata-Version: 2.4
Name: spec-kit-tool
Version: 1.8.0
Summary: 规范驱动开发（SDD）工具集：安装知识库骨架、部署 AI 技能与命令
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# spec-kit

规范驱动开发（SDD）工具集。为 AI 编码助手（Claude Code / Codex）提供知识库骨架和技能包。

> PyPI 发行名为 `spec-kit-tool`（`spec-kit` 与已有项目 `speckit` 撞名），安装后提供 `spec-kit` 命令。

```bash
pipx install spec-kit-tool
cd my-project
spec-kit install --agents claude-code,codex
```

## 组成

| 组件 | 说明 |
|------|------|
| `spec-kit install` | 部署 `.spec/` 知识库骨架 + 按 agent 部署技能到对应目录（`--agents` 指定或交互式多选） |
| `spec-kit upgrade` | 升级已有安装 |
| `spec-kit uninstall` | 回收已部署的技能 |
| `spec-kit scan` | frontmatter 检索与发现（层级树；自动排除归档目录 `prd/design/fix`） |
| `spec-kit lint` | 全面一致性校验（跳过归档目录 frontmatter 校验） |
| `spec-kit metrics` | 项目健康指标查看 |
| `spec-kit skill` | 全局技能库管理（list/search/push/install/remove；全局缺失但项目 `.spec/skills/` 存在时项目内直装） |
| `spec-kit version` | 版本信息 |
| `spec-kit help` | 命令说明总览 / 单命令详情（如 `spec-kit help skill`） |

## 部署后的工作流

```
/context      → 加载上下文
/iteration    → 创建迭代
/prd          → 需求结构化
/design       → 方案设计
/research     → 技术调研（优先复用过往结论）
/dev          → TDD 实现
/fix          → Bug 修复
/change       → 轻量变更（微调/局部优化）
/complete     → 窗口提交
```

## 技能包

技能是跨 agent 的公共格式（Agent Skills 标准）。以下技能随 install 部署：

| 技能 | 说明 |
|------|------|
| `prd` | 需求结构化 — 多阶段并行 Agent 管道 |
| `design` | 方案设计 — 全栈编排，先后端后前端 |
| `dev` | TDD 开发 — 骨架 → 测试 → 实现 |
| `fix` | Bug 修复 — 根因定位 → 方案 → 落地 |
| `change` | 轻量变更 — 需求微调、局部优化（绕过完整设计） |
| `research` | 技术调研 — 方案对比、选型建议（优先复用过往调研，过期才重调研） |
| `complete` | 窗口提交 — 声明 + 域知识 + 规则 + 进度 + 技能沉淀（决策清单判定 + 沉淀后推送/安装询问） |
| `context` | 上下文加载 |
| `iteration` | 迭代初始化 |
| `checkout` | 迭代切换 |
| `grill-me` | 方案质询 |

## 全局技能库

`/complete` 沉淀的技能写入 `.spec/skills/`，可推送到全局技能库（`~/.spec-kit/skills/`）供其它项目复用：

```bash
spec-kit skill push {name}          # 项目技能 → 全局库
spec-kit skill list                 # 列出全局库技能
spec-kit skill search {keyword}     # 搜索
spec-kit skill install {name}       # 全局库 → 当前项目所有声明 agent
spec-kit skill remove {name}        # 从全局库移除
```

## 支持的 CodingAgent

| agent | 技能目录 | 备注 |
|-------|----------|------|
| `claude-code` | `.claude/skills/` | |
| `codex` | `.codex/skills/` | |
| `pi` | `.pi/skills/` | Pi Agent Harness |
| `dsh` | `.dsh/skills/` | DeepSeek Harness，**实验性**（演进快） |
| `omp` | `.omp/skills/` | Oh My Pi，**实验性**（演进快）；OMP 不读 `.pi/skills/`，勿混用 |

> 多工具共享目录（如 `.agents/skills`）不纳入部署范围 —— 卸载边界与同源保护无法界定。

## 版本

`spec-kit version` 输出**包版本**（本工具的发布版本，权威值见 `pyproject.toml` 与 `CHANGELOG.md`）。

它与 `.spec/iteration/` 下的**迭代标识**是两条正交的轴，不要互相换算：

| 轴 | 位置 | 含义 | 命名 |
|----|------|------|------|
| 包版本 | `pyproject.toml` / `CHANGELOG.md` | spec-kit 工具自身的发布版本（技能与骨架随包发布，其变更也计入） | `X.Y.Z` |
| 迭代标识 | `.spec/iteration/{id}.md` | 项目内一次工作迭代的标签，与工具版本无关 | `{year}-Q{quarter}-{description}` |

> 本仓自身的历史迭代沿用了 `v2.x.x` 形式，与包版本同形 —— 读 commit / CHANGELOG 时容易误读。
> 新迭代请按上表命名；仓库自己的工作流迭代记录在 `.spec/iteration/`，不在 CHANGELOG 里。

```bash
spec-kit version
```

## 开发与发布（维护者）

### 提交门禁

仓库自带 pre-push 门禁（`scripts/gate.py`：lint + pytest），逻辑与 CI 共用同一份脚本。
**新克隆后启用一次**（hook 不像普通文件那样随 clone 生效）：

```bash
git config core.hooksPath .githooks
```

跳过单次：`git push --no-verify`。

### 发布

发布流程分两步，凭据从本地 `.env.release` 读取（已 gitignore，模板见 `.env.release.example`）：

```bash
python scripts/release.py                 # 版本递增（默认 patch+1；--major/--minor/--patch/--to X.Y.Z）
python -m build                           # 构建 wheel + sdist
python scripts/publish.py                 # 上传 TestPyPI（测试环境）
python scripts/publish.py --prod          # 上传正式 PyPI
python scripts/publish.py --check-only    # 仅 twine check
```

`.env.release` 需分别配置 TestPyPI 与正式 PyPI 的 token：

```ini
TESTPYPI_USERNAME=__token__
TESTPYPI_PASSWORD=pypi-xxx
PYPI_USERNAME=__token__
PYPI_PASSWORD=pypi-yyy
```

## 许可

MIT
