issuekit 0.1.0__py3-none-any.whl

issuekit/commands/init.py

@@ -0,0 +1,185 @@
+"""issuekit init 命令 — 在项目中初始化 Issue 驱动的开发环境。"""
+
+import shutil
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.tree import Tree
+
+from issuekit.agents import AGENT_REGISTRY, get_agent_config
+from issuekit.templates import copy_templates
+from issuekit.knowledge import copy_knowledge_commands
+
+console = Console()
+
+OK = "[green]+[/green]"
+
+ISSUEKIT_DIR = ".issuekit"
+
+SUPPORTED_AI = ", ".join(AGENT_REGISTRY.keys())
+
+USAGE_EXAMPLES = (
+    "\n[dim]用法示例:[/dim]\n"
+    "  issuekit init --ai cursor\n"
+    "  issuekit init --ai claude\n"
+    "  issuekit init --ai cursor --force"
+)
+
+
+def init(
+    ai: str = typer.Option(
+        ...,
+        help=f"指定 AI 助手：{SUPPORTED_AI}",
+    ),
+    issues_dir: str = typer.Option(
+        "issues",
+        "--issues-dir",
+        help="Issue 文档存放目录（相对项目根目录，默认：issues）",
+    ),
+    here: bool = typer.Option(
+        True,
+        "--here/--no-here",
+        help="在当前目录初始化（默认：是）",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="如果 .issuekit/ 已存在，强制覆盖",
+    ),
+):
+    """在项目中初始化 IssueKit。"""
+    agent_config = get_agent_config(ai)
+    if not agent_config:
+        console.print(
+            f"[red]错误:[/red] 不支持的 AI 助手 '{ai}'\n"
+            f"[dim]支持的选项:[/dim] {SUPPORTED_AI}"
+            f"{USAGE_EXAMPLES}"
+        )
+        raise typer.Exit(1)
+
+    project_path = Path.cwd()
+    issuekit_path = project_path / ISSUEKIT_DIR
+
+    if issuekit_path.exists() and not force:
+        console.print(
+            f"[yellow]提示:[/yellow] {ISSUEKIT_DIR}/ 目录已存在，"
+            "如需覆盖请添加 --force 参数。"
+            f"{USAGE_EXAMPLES}"
+        )
+        raise typer.Exit(1)
+
+    console.print()
+    console.print(
+        Panel(
+            f"[cyan]IssueKit 初始化[/cyan]\n\n"
+            f"{'项目':<10} [green]{project_path.name}[/green]\n"
+            f"{'AI 助手':<9} [green]{agent_config.name}[/green]\n"
+            f"{'Issues':<10} [green]{issues_dir}[/green]\n"
+            f"{'路径':<10} [dim]{project_path}[/dim]",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+
+    # 第 1 步：创建 .issuekit/ 目录结构
+    console.print(f"\n[cyan]创建 {ISSUEKIT_DIR}/ 目录...[/cyan]")
+
+    templates_path = issuekit_path / "templates"
+    knowledge_path = issuekit_path / "knowledge"
+
+    if issuekit_path.exists():
+        shutil.rmtree(issuekit_path)
+
+    templates_path.mkdir(parents=True)
+    knowledge_path.mkdir(parents=True)
+
+    template_count = copy_templates(templates_path)
+    console.print(f"  {OK} 已复制 {template_count} 个模板到 {ISSUEKIT_DIR}/templates/")
+
+    # 第 2 步：创建项目配置和知识库配置
+    console.print(f"\n[cyan]创建项目配置...[/cyan]")
+    write_project_config(issuekit_path, issues_dir=issues_dir)
+    console.print(f"  {OK} 项目配置已创建：{ISSUEKIT_DIR}/config.yaml")
+
+    console.print(f"\n[cyan]配置知识库引擎...[/cyan]")
+    write_knowledge_config(knowledge_path)
+    console.print(f"  {OK} 知识库配置已创建：{ISSUEKIT_DIR}/knowledge/")
+
+    # 第 3 步：安装 AI 助手命令
+    console.print(f"\n[cyan]安装 {agent_config.name} 命令...[/cyan]")
+    commands_dir = project_path / agent_config.commands_dir
+    commands_dir.mkdir(parents=True, exist_ok=True)
+
+    command_count = copy_knowledge_commands(commands_dir, agent_config)
+    from issuekit.agent_commands import install_agent_commands
+    cmd_count = install_agent_commands(commands_dir, agent_config)
+    command_count += cmd_count
+    console.print(f"  {OK} 已安装 {command_count} 个命令到 {agent_config.commands_dir}/")
+
+    # 第 4 步：展示结果
+    console.print()
+    tree = Tree(f"[bold]{project_path.name}[/bold]")
+
+    issuekit_tree = tree.add(f"[cyan]{ISSUEKIT_DIR}/[/cyan]")
+    issuekit_tree.add("config.yaml")
+    tpl_tree = issuekit_tree.add("[cyan]templates/[/cyan]")
+    tpl_tree.add("requirement.md")
+    tpl_tree.add("technical-design.md")
+    tpl_tree.add("test-plan.md")
+    tpl_tree.add("release-note.md")
+    tpl_tree.add("code-review.md")
+    kn_tree = issuekit_tree.add("[cyan]knowledge/[/cyan]")
+    kn_tree.add("config.yaml")
+
+    cmd_tree = tree.add(f"[cyan]{agent_config.commands_dir}/[/cyan]")
+    for name in [
+        "issuekit.require", "issuekit.design", "issuekit.coding",
+        "issuekit.test", "issuekit.release", "issuekit.review",
+        "issuekit.change", "issuekit.knowledge",
+    ]:
+        cmd_tree.add(f"{name}{agent_config.command_ext}")
+
+    console.print(tree)
+
+    console.print(
+        f"\n[green]IssueKit 初始化完成！[/green]\n\n"
+        f"下一步：\n"
+        f"  1. [cyan]/issuekit.knowledge[/cyan]  构建项目知识摘要（推荐）\n"
+        f"  2. [cyan]/issuekit.require[/cyan]    创建第一个 Issue\n"
+    )
+
+
+def write_project_config(issuekit_path: Path, *, issues_dir: str = "issues"):
+    """写入 IssueKit 项目级配置文件。"""
+    config = issuekit_path / "config.yaml"
+    config.write_text(
+        "# IssueKit 项目配置\n"
+        "\n"
+        "# Issue 文档存放目录（相对项目根目录）\n"
+        f"issues_dir: {issues_dir}\n",
+        encoding="utf-8",
+    )
+
+
+def write_knowledge_config(knowledge_path: Path):
+    """写入知识库引擎的默认配置文件。"""
+    config = knowledge_path / "config.yaml"
+    config.write_text(
+        "# IssueKit 知识库配置\n"
+        "# 项目上下文摘要自动生成到此目录\n"
+        "\n"
+        "# 摘要输出目录\n"
+        "output_dir: .issuekit/knowledge\n"
+        "\n"
+        "# 生成的摘要章节\n"
+        "sections:\n"
+        "  - project-overview    # 目录结构、技术栈、依赖\n"
+        "  - architecture        # 分层架构、设计模式\n"
+        "  - api-surface         # API 端点、请求/响应约定\n"
+        "  - data-model          # 数据库表、ORM 实体、关系\n"
+        "  - integrations        # 外部服务、SDK、消息队列\n"
+        "  - conventions         # 编码规范、命名约定、错误处理\n",
+        encoding="utf-8",
+    )

issuekit/knowledge/__init__.py

@@ -0,0 +1,32 @@
+"""知识库引擎 — 项目上下文总结命令的安装。"""
+
+from pathlib import Path
+from importlib import resources
+from issuekit.agents.registry import AgentConfig
+
+
+def copy_knowledge_commands(commands_dir: Path, agent_config: AgentConfig) -> int:
+    """复制知识库相关的 Agent 命令文件，返回安装的文件数。"""
+    bundled = resources.files("issuekit") / "bundled_commands"
+    knowledge_file = bundled / "issuekit.knowledge.md"
+
+    if not knowledge_file.is_file():
+        return 0
+
+    content = knowledge_file.read_text(encoding="utf-8")
+
+    if not agent_config.command_frontmatter:
+        content = _strip_frontmatter(content)
+
+    dest = commands_dir / f"issuekit.knowledge{agent_config.command_ext}"
+    dest.write_text(content, encoding="utf-8")
+    return 1
+
+
+def _strip_frontmatter(content: str) -> str:
+    """移除 Markdown 内容中的 YAML frontmatter。"""
+    if content.startswith("---"):
+        end = content.find("---", 3)
+        if end != -1:
+            return content[end + 3:].lstrip("\n")
+    return content

issuekit/templates.py

@@ -0,0 +1,17 @@
+"""模板管理 — 将内置模板复制到项目目录。"""
+
+from importlib import resources
+from pathlib import Path
+
+
+def copy_templates(target_dir: Path) -> int:
+    """将所有内置模板复制到目标目录，返回复制的文件数。"""
+    bundled = resources.files("issuekit") / "bundled_templates"
+    count = 0
+    for item in bundled.iterdir():
+        if item.name.endswith(".md"):
+            content = item.read_text(encoding="utf-8")
+            dest = target_dir / item.name
+            dest.write_text(content, encoding="utf-8")
+            count += 1
+    return count

issuekit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,27 @@
+issuekit/__init__.py,sha256=ALt_H4k70i_3UbBmw_rj8UNI8kimQWrVK9WyKUiXbuI,93
+issuekit/agent_commands.py,sha256=UpdGX9SBD3hYtpzKA_-LTMQQlgPz_501sq0J_kV7IIs,2344
+issuekit/cli.py,sha256=k3i2rvJZe5SCAXUKtAa5HP3Op9p7zyR5L-3cr89yi9Q,2517
+issuekit/templates.py,sha256=c7dSlKVz1rRWRtkAgbxaeeZIMw-IMVvaoCIfUXjAG54,611
+issuekit/agents/__init__.py,sha256=H2ST9gtPIlqqm3ldrFjVyrrtUn7upftpK48JPc3h_kk,181
+issuekit/agents/registry.py,sha256=CvaH14_0vU0iDebtgnVh89yHEojkn8TxcFbbtdzFX30,1779
+issuekit/bundled_commands/issuekit.change.md,sha256=C7N8BH7z3aEzMqcRyn-zGxI8l43wKxDNbfFF0hXKTN4,1861
+issuekit/bundled_commands/issuekit.coding.md,sha256=-dCDJJWpGZGPTaWeCxw0_BgKEiC4fRGDNwf1E4XGgSU,4809
+issuekit/bundled_commands/issuekit.design.md,sha256=u3kVoumgoZJCBJJfIckk_fARaQq4vyzTa_KrwEkRdpk,4464
+issuekit/bundled_commands/issuekit.knowledge.md,sha256=k5oQHTWBjez_EzVRLREhuCvcPVT8lWPG2bPGbjmT2zc,4617
+issuekit/bundled_commands/issuekit.release.md,sha256=vi9tE2S5F7YkiJoy4B8QvadLT1gAoIB12ij68oAYlSM,2397
+issuekit/bundled_commands/issuekit.require.md,sha256=ylT2UQdw9y_zbNNycvYXPyaclxgJi8Sm3IeUETHoVgk,5334
+issuekit/bundled_commands/issuekit.review.md,sha256=Y1VqlbvZrv_sTYN_h3OdZ9XW_wBzGnFnERQ0wH4HRqI,2667
+issuekit/bundled_commands/issuekit.test.md,sha256=MjyaOhL8XzhXoTs0Abg3jeyM0du8Tt0Nl5ecEKF0i3U,3177
+issuekit/bundled_templates/code-review.md,sha256=Ip_x_HX5HXWoerfD8dhK5ANkoVIHYq3Z860j4AydP6M,3425
+issuekit/bundled_templates/release-note.md,sha256=Vq8jNqomoKmsDXSVzr3P7RSeJLerr7_UFtZ0xu1AWeE,2232
+issuekit/bundled_templates/requirement.md,sha256=wn4IM8dpWoY0BEBXfhaFagtI49UMQgBWZv7ZrnpzjNU,3231
+issuekit/bundled_templates/technical-design.md,sha256=GjUQ55q1XYrsDQtyVKx3n6t5Fv8_B4STDnK1f8qy7g4,5792
+issuekit/bundled_templates/test-plan.md,sha256=r9ZUYXm4PbWno4yJWnpAV0pNNpwRmryeW_prOisfcUs,9412
+issuekit/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+issuekit/commands/init.py,sha256=nHrb1xZ8m8pFuGILkzMOlyEkY0ET8tw6-FzPLicnlXY,6507
+issuekit/knowledge/__init__.py,sha256=RDnYb-XeWCVMyrYw8vu1qcWit4Hv3ilC5tjmzP-KHYM,1100
+issuekit-0.1.0.dist-info/METADATA,sha256=gn0VSfj9FiKHQQDaUwfEBLTWVkyCIppGaN0DwLLY3I4,6211
+issuekit-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+issuekit-0.1.0.dist-info/entry_points.txt,sha256=1ftj_n9rjULfEjjgO0wfBZvSC1_JhY3yS6PLZLFMEtI,46
+issuekit-0.1.0.dist-info/licenses/LICENSE,sha256=XKKSDU9WlUEAyPNlRhq6e2xhVNpJc097JwPZJ1rUnRE,1077
+issuekit-0.1.0.dist-info/RECORD,,

issuekit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

issuekit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+issuekit = issuekit.cli:app

issuekit-0.1.0.dist-info/licenses/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.