Metadata-Version: 2.4
Name: issuekit
Version: 0.1.5
Summary: AI 辅助开发的 Issue 全生命周期工具。从需求分析到代码审核，由你的 AI 编程助手驱动。
Project-URL: Homepage, https://github.com/xsg22/issue-kit
Project-URL: Repository, https://github.com/xsg22/issue-kit
Project-URL: Issues, https://github.com/xsg22/issue-kit/issues
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,codex,cursor,development,issue
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: release
Requires-Dist: build>=1.0; extra == 'release'
Requires-Dist: pytest>=7.0; extra == 'release'
Requires-Dist: twine>=5.0; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# IssueKit

AI 辅助开发的 Issue 全生命周期工具。从需求分析到代码审核，由你的 AI 编程助手驱动。

## IssueKit 是什么？

IssueKit 为 AI 辅助开发提供结构化的工作流。它提供一组 Skills，引导你的 AI 编程助手（Cursor、Claude Code、Codex 等）完成一个 Issue 的完整生命周期：


| 阶段      | Skill               | 说明                     |
| ------- | ------------------- | ---------------------- |
| 1. 需求分析 | `$issuekit-require` | 分析需求，生成面向产品经理的需求文档     |
| 2. 技术方案 | `$issuekit-design`  | 架构设计、接口设计、组件设计、开发步骤    |
| 3. 编码实现 | `$issuekit-coding`  | 按技术方案编码，交叉校验代码与文档一致性   |
| 4. 测试方案 | `$issuekit-test`    | 黑盒业务测试 + 白盒单测/接口测试用例   |
| 5. 发布准备 | `$issuekit-release` | 生成发布文档，创建 Pull Request |
| 6. 代码审核 | `$issuekit-review`  | 多维度交叉验证（需求、方案、质量）      |


还有一个 `$issuekit-knowledge` skill，用于生成项目上下文摘要，让 AI 助手快速理解项目。

## 安装

```bash
pip install issuekit
```

## 快速上手

### 第 1 步：初始化

在你的项目根目录运行：

```bash
cd your-project
issuekit init --ai cursor     # Cursor
issuekit init --ai codex      # Codex
issuekit init --ai claude     # Claude Code
```

这会创建 `.issuekit/` 目录（模板 + 知识库配置），并将 Skills 安装到对应目录。

默认 Issue 文档存放在项目根目录的 `issues/` 文件夹下。你也可以自定义目录：

```bash
issuekit init --ai cursor --issues-dir doc/issues
```

### 第 2 步：构建项目知识（可选但推荐）

在 AI 助手中运行：

```
$issuekit-knowledge
```

AI 助手会分析你的项目，生成结构化的知识摘要到 `.issuekit/knowledge/`。后续的需求分析和技术方案设计会自动读取这些摘要。

### 第 3 步：创建第一个 Issue

假设产品经理给了一个需求："用户个人资料页面增加修改头像功能，支持裁剪和压缩"。

在 AI 助手中调用 `$issuekit-require`，AI 助手会：

1. 深入分析代码，理解现有用户模块的实现
2. 生成 Issue ID（如 `FEAT-20260228-avatar-upload`）
3. 创建 `issues/FEAT-20260228-avatar-upload/requirement.md`
4. 从 master 拉出特性分支 `feature/FEAT-20260228-avatar-upload`

需求文档包含：用户故事（Mermaid 流程图）、边界场景、验收标准、AI 需求评审、待确认问题。

### 第 4 步：设计技术方案

需求确认后，调用 `$issuekit-design`。

生成 `technical-design.md`，涵盖技术调研、架构设计、核心流程、组件设计、接口设计、开发步骤。

### 第 5 步：编码实现

调用 `$issuekit-coding`。

AI 助手按技术文档的开发步骤逐步实现，完成后自动交叉校验代码与技术文档、需求文档的一致性。

### 第 6 步：后续流程

```
$issuekit-test      # 生成测试方案
$issuekit-release   # 生成发布文档 + 创建 PR
$issuekit-review    # 多维度代码审核
```

## `init` 做了什么

1. 创建 `.issuekit/` 目录：
  - `config.yaml` — 项目配置（Issue 文档目录等）
  - `templates/` — 各阶段文档模板（需求、技术方案、测试、发布、审核）
  - `knowledge/` — 项目上下文知识摘要
2. 安装 Skills 到对应目录：
  - Cursor → `.cursor/skills/`
  - Claude Code → `.claude/skills/`
  - Codex → `.agents/skills/`
  - GitHub Copilot → `.github/skills/`

每个 Skill 包含 `SKILL.md`（指令）和 `agents/openai.yaml`（元数据）。

## 更新模板与 Skills（已 init 的项目）

文档模板与 Skills 都来自 **已安装的 `issuekit` PyPI 包**。要拿到新版内容，先升级包，再同步到项目：

```bash
pip install -U issuekit
issuekit upgrade --ai cursor    # 与 init 时选的助手一致：cursor / claude / codex / copilot
```

`upgrade` 会：

- **覆盖** `.issuekit/templates/` 下与内置同名的 `.md`（若你改过模板，请先备份或自行合并）；
- **覆盖** 各 AI Skills 目录下的 `issuekit-*`（如 `.cursor/skills/`）。

**不会** 修改 `.issuekit/config.yaml`、`.issuekit/knowledge/config.yaml`，也不会删除 `.issuekit/knowledge/` 里已生成的知识摘要文件。

若你曾用 `issuekit init --issues-dir` 自定义过 Issue 目录，无需再改；`upgrade` 不涉及该配置。

> **不建议** 用 `issuekit init --force` 仅为了更新：`--force` 会**整目录删除** `.issuekit/` 并重建，可能丢失知识库配置与 `.issuekit/knowledge/` 下已生成的摘要。

## 支持的 AI 助手


| AI 助手          | 参数             | Skills 目录         |
| -------------- | -------------- | ----------------- |
| Cursor         | `--ai cursor`  | `.cursor/skills/` |
| Claude Code    | `--ai claude`  | `.claude/skills/` |
| Codex          | `--ai codex`   | `.agents/skills/` |
| GitHub Copilot | `--ai copilot` | `.github/skills/` |


## 目录结构

```
.issuekit/
├── config.yaml               # 项目配置（issues_dir 等）
├── templates/                # 文档模板
│   ├── requirement.md        # 需求文档模板
│   ├── technical-design.md   # 技术方案模板
│   ├── test-plan.md          # 测试方案模板
│   ├── release-note.md       # 发布文档模板
│   └── code-review.md        # 代码审核模板
└── knowledge/                # 项目上下文知识摘要
    ├── config.yaml           # 知识库配置
    ├── project-overview.md   # 项目概览
    ├── architecture.md       # 架构分析
    ├── api-surface.md        # API 接口摘要
    ├── data-model.md         # 数据模型摘要
    ├── integrations.md       # 外部集成摘要
    └── conventions.md        # 编码约定摘要

.cursor/skills/               # Cursor Skills（示例）
├── issuekit-require/
│   └── SKILL.md
├── issuekit-design/
│   └── SKILL.md
└── ...

issues/                       # Issue 文档（默认目录，可通过 --issues-dir 自定义）
└── FEAT-20260228-xxx/
    ├── requirement.md
    ├── technical-design.md
    ├── test-plan.md
    ├── release-note.md
    └── code-review.md
```

## 许可证

MIT