issuekit 0.1.0__tar.gz

issuekit-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+*.pyc
+__pycache__/
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.issuekit/
+.cursor/

issuekit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

issuekit-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: issuekit
+Version: 0.1.0
+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: 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 辅助开发提供结构化的工作流。它提供一组命令，引导你的 AI 编程助手（Cursor、Claude Code、Codex 等）完成一个 Issue 的完整生命周期：
+
+| 阶段 | 命令 | 说明 |
+|------|------|------|
+| 1. 需求分析 | `/issuekit.require` | 分析需求，生成面向产品经理的需求文档 |
+| 2. 技术方案 | `/issuekit.design` | 架构设计、接口设计、组件设计、开发步骤 |
+| 3. 编码实现 | `/issuekit.coding` | 按技术方案编码，交叉校验代码与文档一致性 |
+| 4. 测试方案 | `/issuekit.test` | 黑盒业务测试 + 白盒单测/接口测试用例 |
+| 5. 发布准备 | `/issuekit.release` | 生成发布文档，创建 Pull Request |
+| 6. 代码审核 | `/issuekit.review` | 多维度交叉验证（需求、方案、质量） |
+
+还有一个 `/issuekit.knowledge` 命令，用于生成项目上下文摘要，让 AI 助手快速理解项目，无需每次从零扫描。
+
+## 安装
+
+```bash
+pip install issuekit
+```
+
+## 快速上手
+
+### 第 1 步：初始化
+
+在你的项目根目录运行：
+
+```bash
+cd your-project
+issuekit init --ai cursor
+```
+
+这会创建 `.issuekit/` 目录（模板 + 知识库配置），并将命令文件安装到 `.cursor/commands/`。
+
+默认 Issue 文档存放在项目根目录的 `issues/` 文件夹下。你也可以自定义目录：
+
+```bash
+issuekit init --ai cursor --issues-dir doc/issues
+```
+
+### 第 2 步：构建项目知识（可选但推荐）
+
+在 Cursor 中运行命令：
+
+```
+/issuekit.knowledge
+```
+
+AI 助手会分析你的项目，生成结构化的知识摘要到 `.issuekit/knowledge/`。后续的需求分析和技术方案设计会自动读取这些摘要。
+
+### 第 3 步：创建第一个 Issue
+
+假设产品经理给了一个需求："用户个人资料页面增加修改头像功能，支持裁剪和压缩"。
+
+在 Cursor 中运行：
+
+```
+/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/` — 项目上下文知识摘要（由 `/issuekit.knowledge` 生成）
+
+2. 安装 AI 助手命令到对应目录：
+   - Cursor → `.cursor/commands/`
+   - Claude Code → `.claude/commands/`
+   - Codex → `.codex/commands/`
+   - GitHub Copilot → `.github/agents/`
+
+## 支持的 AI 助手
+
+| AI 助手 | 参数 | 状态 |
+|---------|------|------|
+| Cursor | `--ai cursor` | 已支持 |
+| Claude Code | `--ai claude` | 已支持 |
+| Codex | `--ai codex` | 已支持 |
+| GitHub Copilot | `--ai copilot` | 已支持 |
+
+## 目录结构
+
+```
+.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   # 项目概览（/issuekit.knowledge 生成）
+    ├── architecture.md       # 架构分析
+    ├── api-surface.md        # API 接口摘要
+    ├── data-model.md         # 数据模型摘要
+    ├── integrations.md       # 外部集成摘要
+    └── conventions.md        # 编码约定摘要
+
+issues/                       # Issue 文档（默认目录，可通过 --issues-dir 自定义）
+└── FEAT-20260228-xxx/
+    ├── requirement.md        # 需求文档
+    ├── technical-design.md   # 技术方案
+    ├── test-plan.md          # 测试方案
+    ├── release-note.md       # 发布文档
+    └── code-review.md        # 代码审核
+```
+
+## 许可证
+
+MIT

issuekit-0.1.0/README.md

@@ -0,0 +1,152 @@
+# IssueKit
+
+AI 辅助开发的 Issue 全生命周期工具。从需求分析到代码审核，由你的 AI 编程助手驱动。
+
+## IssueKit 是什么？
+
+IssueKit 为 AI 辅助开发提供结构化的工作流。它提供一组命令，引导你的 AI 编程助手（Cursor、Claude Code、Codex 等）完成一个 Issue 的完整生命周期：
+
+| 阶段 | 命令 | 说明 |
+|------|------|------|
+| 1. 需求分析 | `/issuekit.require` | 分析需求，生成面向产品经理的需求文档 |
+| 2. 技术方案 | `/issuekit.design` | 架构设计、接口设计、组件设计、开发步骤 |
+| 3. 编码实现 | `/issuekit.coding` | 按技术方案编码，交叉校验代码与文档一致性 |
+| 4. 测试方案 | `/issuekit.test` | 黑盒业务测试 + 白盒单测/接口测试用例 |
+| 5. 发布准备 | `/issuekit.release` | 生成发布文档，创建 Pull Request |
+| 6. 代码审核 | `/issuekit.review` | 多维度交叉验证（需求、方案、质量） |
+
+还有一个 `/issuekit.knowledge` 命令，用于生成项目上下文摘要，让 AI 助手快速理解项目，无需每次从零扫描。
+
+## 安装
+
+```bash
+pip install issuekit
+```
+
+## 快速上手
+
+### 第 1 步：初始化
+
+在你的项目根目录运行：
+
+```bash
+cd your-project
+issuekit init --ai cursor
+```
+
+这会创建 `.issuekit/` 目录（模板 + 知识库配置），并将命令文件安装到 `.cursor/commands/`。
+
+默认 Issue 文档存放在项目根目录的 `issues/` 文件夹下。你也可以自定义目录：
+
+```bash
+issuekit init --ai cursor --issues-dir doc/issues
+```
+
+### 第 2 步：构建项目知识（可选但推荐）
+
+在 Cursor 中运行命令：
+
+```
+/issuekit.knowledge
+```
+
+AI 助手会分析你的项目，生成结构化的知识摘要到 `.issuekit/knowledge/`。后续的需求分析和技术方案设计会自动读取这些摘要。
+
+### 第 3 步：创建第一个 Issue
+
+假设产品经理给了一个需求："用户个人资料页面增加修改头像功能，支持裁剪和压缩"。
+
+在 Cursor 中运行：
+
+```
+/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/` — 项目上下文知识摘要（由 `/issuekit.knowledge` 生成）
+
+2. 安装 AI 助手命令到对应目录：
+   - Cursor → `.cursor/commands/`
+   - Claude Code → `.claude/commands/`
+   - Codex → `.codex/commands/`
+   - GitHub Copilot → `.github/agents/`
+
+## 支持的 AI 助手
+
+| AI 助手 | 参数 | 状态 |
+|---------|------|------|
+| Cursor | `--ai cursor` | 已支持 |
+| Claude Code | `--ai claude` | 已支持 |
+| Codex | `--ai codex` | 已支持 |
+| GitHub Copilot | `--ai copilot` | 已支持 |
+
+## 目录结构
+
+```
+.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   # 项目概览（/issuekit.knowledge 生成）
+    ├── architecture.md       # 架构分析
+    ├── api-surface.md        # API 接口摘要
+    ├── data-model.md         # 数据模型摘要
+    ├── integrations.md       # 外部集成摘要
+    └── conventions.md        # 编码约定摘要
+
+issues/                       # Issue 文档（默认目录，可通过 --issues-dir 自定义）
+└── FEAT-20260228-xxx/
+    ├── requirement.md        # 需求文档
+    ├── technical-design.md   # 技术方案
+    ├── test-plan.md          # 测试方案
+    ├── release-note.md       # 发布文档
+    └── code-review.md        # 代码审核
+```
+
+## 许可证
+
+MIT

issuekit-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "issuekit"
+version = "0.1.0"
+description = "AI 辅助开发的 Issue 全生命周期工具。从需求分析到代码审核，由你的 AI 编程助手驱动。"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["ai", "issue", "development", "cursor", "claude", "codex"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "typer>=0.9",
+    "click>=8.1",
+    "rich>=13.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+issuekit = "issuekit.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/xsg22/issue-kit"
+Repository = "https://github.com/xsg22/issue-kit"
+Issues = "https://github.com/xsg22/issue-kit/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/issuekit"]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-v", "--tb=short"]

issuekit-0.1.0/src/issuekit/__init__.py

@@ -0,0 +1,3 @@
+"""IssueKit - AI 辅助开发的 Issue 全生命周期工具。"""
+
+__version__ = "0.1.0"

issuekit-0.1.0/src/issuekit/agent_commands.py

@@ -0,0 +1,80 @@
+"""将 issuekit 命令文件安装到目标 AI 助手的命令目录。"""
+
+from importlib import resources
+from pathlib import Path
+
+from issuekit.agents.registry import AgentConfig
+
+COMMAND_FILES = [
+    "issuekit.require.md",
+    "issuekit.design.md",
+    "issuekit.coding.md",
+    "issuekit.test.md",
+    "issuekit.release.md",
+    "issuekit.review.md",
+    "issuekit.change.md",
+]
+
+
+def install_agent_commands(commands_dir: Path, agent_config: AgentConfig) -> int:
+    """安装所有 issuekit 命令文件，返回安装的文件数。"""
+    bundled = resources.files("issuekit") / "bundled_commands"
+    count = 0
+
+    for filename in COMMAND_FILES:
+        source = bundled / filename
+        if not source.is_file():
+            continue
+
+        content = source.read_text(encoding="utf-8")
+
+        if not agent_config.command_frontmatter:
+            content = _strip_frontmatter(content)
+
+        if not agent_config.supports_handoffs:
+            content = _strip_handoffs(content)
+
+        dest = commands_dir / f"{Path(filename).stem}{agent_config.command_ext}"
+        dest.write_text(content, encoding="utf-8")
+        count += 1
+
+    return count
+
+
+def _strip_frontmatter(content: str) -> str:
+    """移除 YAML frontmatter（--- ... ---）。"""
+    if content.startswith("---"):
+        end = content.find("---", 3)
+        if end != -1:
+            return content[end + 3:].lstrip("\n")
+    return content
+
+
+def _strip_handoffs(content: str) -> str:
+    """移除 YAML frontmatter 中的 handoffs 部分（用于不支持 handoffs 的 AI 助手）。"""
+    if not content.startswith("---"):
+        return content
+
+    end = content.find("---", 3)
+    if end == -1:
+        return content
+
+    frontmatter = content[3:end]
+    body = content[end + 3:]
+
+    lines = frontmatter.split("\n")
+    filtered = []
+    skip = False
+    for line in lines:
+        if line.strip().startswith("handoffs:"):
+            skip = True
+            continue
+        if skip and (line.startswith("  ") or line.startswith("\t")):
+            continue
+        skip = False
+        filtered.append(line)
+
+    new_frontmatter = "\n".join(filtered).strip()
+    if new_frontmatter:
+        return f"---\n{new_frontmatter}\n---{body}"
+    return body.lstrip("\n")

issuekit-0.1.0/src/issuekit/agents/__init__.py

@@ -0,0 +1,5 @@
+"""AI 助手适配层，支持不同编程助手的命令格式。"""
+
+from .registry import AGENT_REGISTRY, get_agent_config
+
+__all__ = ["AGENT_REGISTRY", "get_agent_config"]

issuekit-0.1.0/src/issuekit/agents/registry.py

@@ -0,0 +1,68 @@
+"""AI 助手配置注册表。
+
+每个助手定义了命令文件的存放位置和格式要求。
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AgentConfig:
+    """AI 助手配置项。"""
+    name: str
+    commands_dir: str
+    rules_dir: Optional[str]
+    command_ext: str
+    command_frontmatter: bool
+    supports_handoffs: bool
+
+    def format_description(self) -> str:
+        return f"{self.name} ({self.commands_dir})"
+
+
+AGENT_REGISTRY: dict[str, AgentConfig] = {
+    "cursor": AgentConfig(
+        name="Cursor",
+        commands_dir=".cursor/commands",
+        rules_dir=".cursor/rules",
+        command_ext=".md",
+        command_frontmatter=True,
+        supports_handoffs=True,
+    ),
+    "claude": AgentConfig(
+        name="Claude Code",
+        commands_dir=".claude/commands",
+        rules_dir=None,
+        command_ext=".md",
+        command_frontmatter=False,
+        supports_handoffs=False,
+    ),
+    "codex": AgentConfig(
+        name="Codex",
+        commands_dir=".codex/commands",
+        rules_dir=None,
+        command_ext=".md",
+        command_frontmatter=False,
+        supports_handoffs=False,
+    ),
+    "copilot": AgentConfig(
+        name="GitHub Copilot",
+        commands_dir=".github/agents",
+        rules_dir=None,
+        command_ext=".md",
+        command_frontmatter=False,
+        supports_handoffs=False,
+    ),
+}
+
+AGENT_ALIASES: dict[str, str] = {
+    "cursor-agent": "cursor",
+    "claude-code": "claude",
+}
+
+
+def get_agent_config(name: str) -> Optional[AgentConfig]:
+    """根据名称获取 AI 助手配置，支持别名解析。"""
+    resolved = AGENT_ALIASES.get(name, name)
+    return AGENT_REGISTRY.get(resolved)

issuekit-0.1.0/src/issuekit/bundled_commands/issuekit.change.md

@@ -0,0 +1,52 @@
+---
+description: 记录和管理 Issue 的需求或方案变更。追踪变更对所有文档的影响。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+## 概述
+
+本命令处理开发过程中的需求变更、技术方案调整等，确保所有受影响的文档一致更新，变更被正确追踪。
+
+## 工作流程
+
+### 第 1 步：定位 Issue 并解析变更
+
+1. 读取 `.issuekit/config.yaml` 中的 `issues_dir` 配置项，获取 Issue 文档存放目录（默认为 `issues`）
+2. 定位 issue 目录（从 `$ARGUMENTS` 或当前分支，issue 目录位于 `{issues_dir}/{issue-id}/`）
+3. 从 `$ARGUMENTS` 解析变更内容（用户提供的文字/图片）
+4. 分类变更类型：
+   - **需求变更**：产品需求发生变化
+   - **方案调整**：技术方案调整
+   - **配置变更**：配置项变化
+   - **范围变更**：需求范围扩大/缩小
+
+### 第 2 步：影响分析
+
+1. 阅读相关现有文档
+2. 对比变更内容与当前内容，识别差异
+3. 评估对下游文档的影响：
+   - 需求变更 → 可能影响：技术方案、测试方案、发布文档
+   - 方案调整 → 可能影响：测试方案、发布文档
+   - 范围变更 → 可能影响：所有文档
+
+### 第 3 步：更新受影响文档
+
+对每个受影响的文档：
+
+1. **原地更新内容**（保持可读性，不使用删除线）
+2. **追加变更记录条目**到文档的变更记录表：
+   ```
+   | v{N} | {日期} | {变更人} | {变更描述} | {原因} |
+   ```
+
+### 第 4 步：向用户报告
+
+1. 总结变更内容
+2. 列出所有更新的文档及版本号
+3. 如果下游文档需要手动更新（如技术方案需要重新设计），提醒用户并建议使用对应的命令
+4. 如果变更显著影响范围，建议重新运行需求文档的质量验证