issuekit 0.1.0__py3-none-any.whl

issuekit/bundled_commands/issuekit.require.md

@@ -0,0 +1,127 @@
+---
+description: 创建新 Issue 并进行需求分析。结合代码分析需求完整度，生成面向产品经理的需求文档。
+handoffs:
+  - label: 设计技术方案
+    agent: issuekit.design
+    prompt: 为这个 issue 设计技术方案
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+在 `/issuekit.require` 后面输入的文本就是产品需求描述（可包含文字和图片）。如果为空则提示用户提供需求内容。
+
+## 概述
+
+本命令创建一个新的 issue，结合代码库分析需求完整度，生成需求文档。
+
+**核心原则**：需求文档是面向产品经理和业务方的，不涉及源码、技术实现、代码位置。Agent 内部需要深入阅读代码来理解业务，但文档输出只呈现业务层面的分析结果。
+
+## 工作流程
+
+### 第 1 步：解析需求输入
+
+1. 从 `$ARGUMENTS` 提取需求描述
+   - 如果为空：报错 "请提供需求描述（文本/图片）"
+2. 提取关键概念：参与者、操作、数据、约束条件、业务规则
+3. 判断 issue 类型：Feature / Bug / Optimization / Hotfix
+
+### 第 2 步：生成 Issue ID
+
+1. 确定类型前缀：`FEAT` / `BUG` / `OPT` / `HOTFIX`
+2. 获取当天日期：`YYYYMMDD`
+3. 生成简短描述（2-4 个词，kebab-case）
+4. 完整 ID：`{TYPE}-{YYYYMMDD}-{short-description}`（例如 `FEAT-20260305-add-rate-us`）
+
+### 第 3 步：确保项目上下文
+
+检查 `.issuekit/knowledge/` 是否有项目知识摘要。如果缺失或不完整，先运行 `/issuekit.knowledge` 构建完整的项目理解。
+
+### 第 4 步：深入代码分析（内部分析，不输出到文档）
+
+根据需求描述和知识摘要，定位相关业务模块，详细阅读源码以理解当前系统行为：
+
+- 阅读相关入口、业务逻辑层、数据访问层的调用链
+- 理解现有数据模型和业务规则
+- 检查当前配置和功能开关
+- 必要时通过 MCP 查询实际数据库数据
+
+**重要**：代码分析是为了让 Agent 充分理解业务现状，找出需求中的逻辑漏洞。分析结果以业务语言呈现在文档中，**不在文档中出现任何代码路径、类名、方法名、表名**。
+
+### 第 5 步：编写需求文档
+
+加载模板 `.issuekit/templates/requirement.md`。
+
+按以下流程填充各章节：
+
+1. **第 1 章 — 需求描述**：
+   - 整理产品需求内容，图片放入 `assets/` 引用
+   - 简明扼要描述背景、目标用户、核心诉求
+   - 如果是修改现有功能，**用业务语言**说明当前行为和期望变化（不引用代码）
+   - 避免冗余：不要重复产品原话，而是提炼整理
+
+2. **第 2 章 — 用户故事**：
+   - 按优先级排列（P1、P2、P3...）
+   - 每个 story 用一句话描述目标，然后用 **Mermaid flowchart** 展示用户旅程
+   - 流程图**聚焦产品功能流程**：用户看到什么 → 用户做了什么 → 系统给出什么反馈，不涉及内部技术实现
+   - **不使用大段文字描述**，流程图就是最好的表达方式
+   - 边界场景用表格罗列，含"分类"列（如输入异常、重复操作、服务异常等）
+
+3. **第 3 章 — 验收标准**：
+   - 每条标准：**可衡量**（含具体数字）、**用户视角**（描述用户可感知的结果）
+   - 用表格呈现：分类 + 验收项 + 衡量标准（分类如：功能正确、异常处理、用户体验等）
+
+4. **第 4 章 — AI 需求评审**：
+   - 先给评审结论（完整度评分 + 建议）
+   - 再用一张表覆盖 7 个检查维度
+   - 每行一个维度，状态 + 一句话说明
+
+5. **第 5 章 — 待确认问题**：
+   - **面向产品经理**，聚焦：缺失的业务逻辑、缺失的规则配置
+   - **不包含技术实现问题**
+   - 格式简洁：`Q1: 问题。一句话说明缺失了什么`
+   - 最多 3 个
+
+### 第 6 步：创建 Issue 目录和文件
+
+1. 读取 `.issuekit/config.yaml` 中的 `issues_dir` 配置项，获取 Issue 文档存放目录（默认为 `issues`）
+2. 创建目录：`{issues_dir}/{issue-id}/` 和 `assets/` 子文件夹
+3. 将 `requirement.md` 写入 issue 目录
+
+### 第 7 步：创建 Git 分支
+
+```bash
+git checkout master && git pull origin master
+git checkout -b feature/{issue-id}   # Bug 类型使用 bugfix/{issue-id}
+```
+
+### 第 8 步：报告完成
+
+向用户报告：
+- Issue ID 和目录路径
+- Git 分支名称
+- AI 需求评审结果摘要
+- 如果有待确认问题（第 5 章），展示问题并等待产品经理回复
+- 建议下一步：需求确认后运行 `/issuekit.design`
+
+## AI 生成指南
+
+### 文档风格
+
+- **精简**：每个章节只写必要信息，不重复、不冗余
+- **可视化**：优先用流程图和表格，减少大段文字
+- **业务语言**：全文不出现代码、类名、方法名、表名、字段名
+- **面向产品**：读者是产品经理，不是开发者
+
+### 合理推断原则
+
+- 基于代码分析和行业惯例填补需求空白
+- 仅在显著影响用户体验或业务规则的决策上标记待确认问题
+- 技术实现选型**不属于需求待确认问题**
+
+### 澄清优先级
+
+业务逻辑缺失 > 用户交互歧义 > 规则配置缺失 > 范围边界不清

issuekit/bundled_commands/issuekit.review.md

@@ -0,0 +1,82 @@
+---
+description: 多维度代码审核。交叉验证代码变更与需求、技术方案、测试方案的一致性，生成审核报告。
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+## 概述
+
+本命令通过交叉验证代码变更与需求、技术方案、测试方案和编码规范，进行全面的代码审核，生成详细的审核文档。
+
+## 前置条件
+
+- Pull Request 已创建
+- `release-note.md` 存在（或至少代码变更已在分支上）
+
+## 工作流程
+
+### 第 1 步：定位 Issue 并收集材料
+
+1. 读取 `.issuekit/config.yaml` 中的 `issues_dir` 配置项，获取 Issue 文档存放目录（默认为 `issues`）
+2. 定位 issue 目录（从 `$ARGUMENTS` 或当前分支，issue 目录位于 `{issues_dir}/{issue-id}/`）
+3. 阅读所有 issue 文档：`requirement.md`、`technical-design.md`、`test-plan.md`、`release-note.md`
+4. 获取代码差异：`git diff master...HEAD`
+5. 获取 PR 信息（如有）：`gh pr view`
+
+### 第 2 步：七维度审核
+
+#### 2.1 需求吻合度
+- 逐条对照用户故事和验收标准检查代码变更
+- 验证每个 User Story 的流程是否已实现
+- 标记未实现或部分实现的需求
+
+#### 2.2 方案一致性
+- 对照技术方案验证实际实现
+- 检查接口设计是否与实现一致
+- 检查数据库变更是否与设计一致
+- 标记偏离
+
+#### 2.3 测试覆盖度
+- 验证测试方案是否覆盖所有需求点
+- 检查关键代码路径是否有对应测试用例
+- 识别未覆盖区域
+
+#### 2.4 代码质量
+- 命名规范（类名/方法名/变量名）
+- 异常处理（不吞异常、有意义的错误信息）
+- 日志记录（关键路径有日志、级别合理）
+- 边界条件（空值检查、数组越界、并发安全）
+- 代码重复（可提取的公共方法）
+
+#### 2.5 安全审查
+- SQL 参数化（无字符串拼接 SQL）
+- XSS 防护（输出转义）
+- 敏感数据（密码/token 不明文、不日志）
+- 权限校验（接口鉴权完整）
+
+#### 2.6 性能审查
+- 无 N+1 查询问题
+- 大批量操作有分批处理
+- 热点数据有缓存策略
+- 数据库索引覆盖查询条件
+
+#### 2.7 兼容性审查
+- API 向后兼容
+- 数据库迁移安全
+- 客户端版本兼容
+
+### 第 3 步：生成审核文档
+
+加载模板 `.issuekit/templates/code-review.md` 并填入审核结果。
+
+### 第 4 步：写入文件并报告
+
+1. 将 `code-review.md` 写入 issue 目录
+2. 报告审核结论：
+   - **通过**：所有维度通过
+   - **有条件通过**：有必须修复项，修复后通过
+   - **不通过**：发现严重问题

issuekit/bundled_commands/issuekit.test.md

@@ -0,0 +1,75 @@
+---
+description: 为 Issue 制定全面的测试方案。基于需求和技术方案，生成黑盒业务测试和白盒单测/接口测试用例。
+handoffs:
+  - label: 准备发布
+    agent: issuekit.release
+    prompt: 为这个 issue 准备发布
+---
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+## 概述
+
+本命令生成测试方案文档。包含两个互补模块：先输出业务功能测试（黑盒），再输出单测接口测试（白盒）。
+
+## 前置条件
+
+- issue 目录中必须存在已确认的 `technical-design.md`
+
+## 工作流程
+
+### 第 1 步：定位 Issue 并阅读上下文
+
+1. 读取 `.issuekit/config.yaml` 中的 `issues_dir` 配置项，获取 Issue 文档存放目录（默认为 `issues`）
+2. 定位 issue 目录（从 `$ARGUMENTS` 或当前分支，issue 目录位于 `{issues_dir}/{issue-id}/`）
+3. 阅读 `requirement.md` 获取验收标准、用户场景、业务规则
+4. 阅读 `technical-design.md` 获取方案设计、核心流程、关键代码位置
+5. 阅读技术方案中标识的核心方法的实际源码
+
+### 第 2 步：构建测试用例脑图
+
+在编写具体用例之前，先创建一个层级总览（Mermaid mindmap），作为测试方案的目录。
+
+### 第 3 步：模块一 — 业务功能测试（黑盒）
+
+优先输出此模块，这是对需求的首要验证。
+
+1. 将 `requirement.md` 中的每个用户场景和验收标准映射为测试用例
+2. 每个测试用例描述：
+   - **输入**：用户操作（点击按钮、打开页面、触发流程）
+   - **预期输出**：可观察结果（页面内容、提示信息、接口返回值、数据库记录状态、日志、推送消息等）
+3. 覆盖范围：
+   - 每个 User Story 的正常路径
+   - 替代路径
+   - 错误/边界场景
+   - 跨模块交互
+4. **按重要性控制用例数量**：
+   - 核心且复杂的场景 → 全面覆盖（所有分支、边界、并发）
+   - 次要场景 → 正常路径 + 主要错误
+5. 按用户场景组织；多步骤流程使用分步表格
+
+### 第 4 步：模块二 — 单测接口测试（白盒）
+
+1. **可测试性评估**：识别核心方法，评估能否直接单元测试
+   - 如果方法混合了业务逻辑和数据库查询，建议提取纯计算逻辑
+   - 在"可测试性重构建议"章节记录建议
+2. **单元测试**：针对每个核心业务方法：
+   - 指定：方法名、输入参数、预期返回值/状态变更/异常
+   - 使用按重要性驱动的覆盖策略（参见模板）
+3. **接口测试**：针对每个新增/修改的 API 端点：
+   - 指定：HTTP 方法、路径、请求头/体、预期状态码、响应断言、数据库断言
+   - 覆盖：成功路径、参数校验失败、业务规则违反、权限检查
+
+### 第 5 步：构建覆盖矩阵
+
+创建需求-测试覆盖矩阵，确保每个需求点都有对应的测试用例。
+
+### 第 6 步：写入文件并报告
+
+1. 加载模板 `.issuekit/templates/test-plan.md`
+2. 将 `test-plan.md` 写入 issue 目录
+3. 报告完成并建议下一步：开始开发，然后运行 `/issuekit.release`

issuekit/bundled_templates/code-review.md

@@ -0,0 +1,105 @@
+# {Issue ID} - 代码审核文档
+
+> **结论**: 通过 / 有条件通过 / 不通过
+> **审核人**: Agent
+> **日期**: {YYYY-MM-DD}
+> **PR**: {PR link}
+> **关联需求**: [需求文档](./requirement.md)
+> **关联方案**: [技术方案](./technical-design.md)
+> **关联测试**: [测试方案](./test-plan.md)
+> **关联发布**: [发布文档](./release-note.md)
+
+---
+
+## 1. 审核概览
+
+| 维度 | 结果 | 问题数 |
+|------|------|--------|
+| 需求吻合度 | 通过/有问题 | {N} |
+| 方案一致性 | 通过/有问题 | {N} |
+| 测试覆盖度 | 通过/有问题 | {N} |
+| 代码质量 | 通过/有问题 | {N} |
+| 安全审查 | 通过/有问题 | {N} |
+| 性能审查 | 通过/有问题 | {N} |
+| 兼容性审查 | 通过/有问题 | {N} |
+
+## 2. 需求吻合度
+
+{逐条对照需求文档，验证实现完整性}
+
+| # | 需求点 | 实现状态 | 代码位置 | 说明 |
+|---|--------|---------|---------|------|
+| 1 | {需求} | 已实现/部分实现/未实现 | [Class#method](path/File) | {说明} |
+
+## 3. 方案一致性
+
+{对照技术方案，验证实际实现是否偏离设计}
+
+| 设计项 | 实际实现 | 一致性 | 说明 |
+|--------|---------|--------|------|
+| {设计点} | {实际} | 一致/偏离 | {说明} |
+
+## 4. 测试覆盖度
+
+{对照测试方案，验证测试用例是否覆盖所有需求点和关键代码路径}
+
+| # | 需求点/代码路径 | 黑盒覆盖 | 单测覆盖 | 接口测试覆盖 | 说明 |
+|---|---------------|---------|---------|------------|------|
+| 1 | {需求/路径} | 有/无 | 有/无 | 有/无 | {说明} |
+
+## 5. 代码质量
+
+| # | 文件 | 行号 | 级别 | 问题描述 | 建议 |
+|---|------|------|------|---------|------|
+| 1 | {path} | L{N} | 严重/建议/优化 | {问题} | {建议} |
+
+### 检查项
+- [ ] 命名规范（类名/方法名/变量名）
+- [ ] 异常处理（不吞异常、有意义的错误信息）
+- [ ] 日志记录（关键路径有日志、级别合理）
+- [ ] 边界条件（空值检查、数组越界、并发安全）
+- [ ] 代码重复（是否有可提取的公共方法）
+
+## 6. 安全审查
+
+| # | 风险类型 | 文件 | 行号 | 说明 | 建议 |
+|---|---------|------|------|------|------|
+| 1 | SQL注入/XSS/敏感数据 | {path} | L{N} | {说明} | {建议} |
+
+### 检查项
+- [ ] SQL 参数化（无字符串拼接 SQL）
+- [ ] XSS 防护（输出转义）
+- [ ] 敏感数据（密码/token 不明文、不日志）
+- [ ] 权限校验（接口鉴权完整）
+
+## 7. 性能审查
+
+| # | 类型 | 文件 | 行号 | 说明 | 建议 |
+|---|------|------|------|------|------|
+| 1 | N+1查询/大批量/缓存 | {path} | L{N} | {说明} | {建议} |
+
+### 检查项
+- [ ] 无 N+1 查询问题
+- [ ] 大批量操作有分批处理
+- [ ] 热点数据有缓存策略
+- [ ] 数据库索引覆盖查询条件
+
+## 8. 兼容性审查
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| API 向后兼容 | 兼容/不兼容/不适用 | {说明} |
+| 数据库迁移安全 | 安全/有风险/不适用 | {说明} |
+| 客户端版本兼容 | 兼容/不兼容/不适用 | {说明} |
+
+## 9. 问题清单汇总
+
+| # | 维度 | 级别 | 描述 | 状态 |
+|---|------|------|------|------|
+| 1 | {维度} | 必须修复/建议修复/可选优化 | {描述} | 待修复/已修复 |
+
+## 10. 审核结论
+
+**结论**: {通过 / 有条件通过（修复必须项后通过） / 不通过}
+
+**总结**: {1-2 句总结}

issuekit/bundled_templates/release-note.md

@@ -0,0 +1,90 @@
+# {Issue ID} - 发布文档
+
+> **状态**: 待发布 / 已发布 / 已回滚
+> **作者**: {姓名}
+> **发布日期**: {YYYY-MM-DD}
+> **代码分支**: {branch-name}
+> **关联需求**: [需求文档](./requirement.md)
+> **关联方案**: [技术方案](./technical-design.md)
+> **关联测试**: [测试方案](./test-plan.md)
+
+---
+
+## 1. 变更概述
+
+{一段话描述本次发布的核心变更}
+
+## 2. 需求变更汇总
+
+{从 01-progress.md 中汇总所有中途发生的需求/方案调整}
+
+| 日期 | 类型 | 变更内容 | 影响 |
+|------|------|---------|------|
+| {日期} | 需求变更/方案调整 | {内容} | {影响} |
+
+## 3. 变更清单
+
+### 3.1 功能变更
+
+| 变更项 | 类型 | 说明 |
+|--------|------|------|
+| {功能} | 新增/修改/删除 | {说明} |
+
+### 3.2 接口变更
+
+| 接口 | 变更类型 | 兼容性 | 说明 |
+|------|---------|--------|------|
+| POST /api/xxx | 新增 | - | {说明} |
+
+### 3.3 数据库变更
+
+| 操作 | 表 | SQL | 说明 |
+|------|-----|-----|------|
+| ALTER | {表} | ALTER TABLE ... | {说明} |
+
+**SQL 脚本位置**: `sql/{version}/{script}.sql`
+
+### 3.4 配置变更
+
+| 配置项 | 位置 | 操作 | 值 | 说明 |
+|--------|------|------|-----|------|
+| {key} | Apollo/{namespace} | 新增 | {value} | {说明} |
+
+## 4. 影响范围
+
+| 功能/流程 | 影响程度 | 说明 |
+|----------|---------|------|
+| {功能} | 直接变更/需回归 | {说明} |
+
+## 5. 部署步骤
+
+1. [ ] 执行数据库迁移: `sql/xxx.sql`
+2. [ ] 更新配置: {namespace} - {key}
+3. [ ] 部署服务: {服务名}
+4. [ ] 验证功能: {验证步骤}
+5. [ ] 监控观察: 关注 {指标} 持续 {时长}
+
+## 6. 回滚方案
+
+1. [ ] 回滚服务: {version/commit}
+2. [ ] 回滚数据库: {回滚 SQL}
+3. [ ] 回滚配置: {说明}
+4. [ ] 验证回滚: {步骤}
+
+## 7. 监控与告警
+
+| 监控项 | 正常范围 | 告警阈值 | 观察时长 |
+|--------|---------|---------|---------|
+| {指标} | {范围} | {阈值} | {时长} |
+
+## 8. 发布后验证
+
+- [ ] {验证项}
+- [ ] 监控指标正常
+- [ ] 无异常告警
+
+## 变更记录
+
+| 版本 | 日期 | 变更人 | 变更内容 | 原因 |
+|------|------|--------|---------|------|
+| v1.0 | {日期} | {姓名} | 初稿 | - |

issuekit/bundled_templates/requirement.md

@@ -0,0 +1,107 @@
+# {Issue ID} - 需求文档
+
+> **状态**: 草稿 / 待确认 / 已确认
+> **提出人**: {姓名}
+> **日期**: {YYYY-MM-DD}
+> **优先级**: P0(紧急) / P1(高) / P2(中) / P3(低)
+> **类型**: Feature / Bug / Optimization / Hotfix
+
+---
+
+## 1. 需求描述
+
+{整理后的产品需求内容。图片放入 assets/ 并用相对路径引用。}
+
+{简明扼要地描述需求背景、目标用户、核心诉求。如果是修改现有功能，用一段话说明当前行为和期望变化，不涉及代码。}
+
+---
+
+## 2. 用户故事
+
+{按优先级排列。每个 story 用 Mermaid 流程图描述用户旅程。流程图聚焦产品功能流程：用户看到什么 → 用户做了什么 → 系统给出什么反馈，不涉及内部技术实现细节。}
+
+### US-1: {简要标题} (P1)
+
+{一句话描述这个用户旅程的目标}
+
+```mermaid
+flowchart TD
+    A["用户看到 XX 功能入口"] --> B["用户点击/操作"]
+    B --> C["系统反馈结果"]
+    C --> D{"是否成功？"}
+    D -->|"成功"| E["用户看到成功提示"]
+    D -->|"失败"| F["用户看到错误提示"]
+```
+
+### US-2: {简要标题} (P2)
+
+{一句话描述}
+
+```mermaid
+flowchart TD
+    A["触发场景"] --> B["用户操作"]
+    B --> C["用户看到结果"]
+```
+
+---
+
+### 边界场景
+
+| 分类 | 场景 | 处理方式 |
+|------|------|---------|
+| 输入异常 | {边界条件1} | {处理方式} |
+| 重复操作 | {并发/重复操作} | {处理方式} |
+| 服务异常 | {外部依赖不可用} | {处理方式} |
+
+---
+
+## 3. 验收标准
+
+{可衡量的、以用户为中心的验收指标。}
+
+| 分类 | # | 验收项 | 衡量标准 |
+|------|---|--------|---------|
+| 功能正确 | AC-001 | {用户可感知的结果} | {具体数字或明确条件} |
+| 功能正确 | AC-002 | {用户可感知的结果} | {具体数字或明确条件} |
+| 异常处理 | AC-003 | {用户可感知的结果} | {具体数字或明确条件} |
+| 用户体验 | AC-004 | {用户可感知的结果} | {具体数字或明确条件} |
+
+---
+
+## 4. AI 需求评审
+
+{Agent 基于代码分析对需求的综合评审。}
+
+### 评审结论
+
+**完整度**: {高/中/低}
+**建议**: {可进入技术方案设计 / 需产品补充以下问题}
+
+### 评审明细
+
+| # | 检查维度 | 状态 | 说明 |
+|---|---------|------|------|
+| 1 | 正常流程覆盖 | ✅/❌ | {是否覆盖了所有正常路径} |
+| 2 | 异常流程覆盖 | ✅/❌ | {是否考虑了错误和异常场景} |
+| 3 | 边界条件覆盖 | ✅/❌ | {是否识别了边界情况} |
+| 4 | 需求无歧义 | ✅/❌ | {是否存在多种理解方式} |
+| 5 | 与现有功能无冲突 | ✅/❌ | {是否与已有业务规则矛盾} |
+| 6 | 验收标准可衡量 | ✅/❌ | {是否有明确的验收数字} |
+| 7 | 需求范围边界清晰 | ✅/❌ | {做什么、不做什么是否明确} |
+
+---
+
+## 5. 待确认问题
+
+{面向产品经理——聚焦缺失的业务逻辑和规则，不涉及技术实现。}
+
+- **Q1**: {问题}。{一句话说明缺失了什么}
+- **Q2**: {问题}。{一句话说明缺失了什么}
+
+---
+
+## 变更记录
+
+| 版本 | 日期 | 变更人 | 变更内容 | 原因 |
+|------|------|--------|---------|------|
+| v1.0 | {日期} | {姓名} | 初稿 | - |