| name | issue-creator |
| description | 创建结构化的 GitHub Issue，采用"人类优先、AI 友好"的双层信息架构，支持 sub-issue 拆解与自动关联。当用户说"创建 issue"、"建个需求"、"拆 issue"、"创建子 issue"、"写个 feature issue"时触发。 |
Issue Creator
创建高质量 GitHub Issue：人类能 1 分钟做决策，AI agent 能从中获取精准的问题上下文直接开工。
核心理念
Issue 是问题描述空间，不是解决方案空间
Issue 应该提供：
- 精准的问题/需求上下文 — 是什么、在哪里、什么时候触发、影响范围
- 清晰的验收标准 — 怎样算完成
- 必要的决策点 — 需要人类判断的选择
Issue 不应该包含：
- ❌ 具体实现方案或代码修改建议
- ❌ 技术路线选择或架构决策
- ❌ "建议使用 xxx 来实现" 之类的措辞
原因：Issue 的创建者不一定是最终执行者。如果创建时写入了质量不确定的实现方案，会误导后续执行的人或 AI agent。把实现判断留给执行者，基于代码现状自行决定。
"AI 友好"= 精准的定位上下文，而非实现指导
AI agent 需要的是：
- 精确的文件路径和行号
- 当前代码的实际行为描述（不是猜测）
- 可机械复现的触发步骤
- 充分的上下文信息（来自用户工作环境和对话中的真实数据）
双层信息架构
┌─────────────────────────────────────┐
│ 🧑 人类层（快速决策） │ ← TL;DR + 决策点 + 验收标准
│ 一眼看懂：是什么、为什么、要不要做 │
├─────────────────────────────────────┤
│ 🔍 定位层（精确上下文） │ ← 文件路径 + 行号 + 当前行为 + 触发方式
│ 精准描述：在哪里、现在什么样、怎么触发│
└─────────────────────────────────────┘
触发场景
/issue-creator 或 /create-issue- 用户说"创建 issue"、"建个需求"、"写个 enhancement issue"、"帮我拆成子 issue"
- 用户描述了一个功能需求、优化方向、重构计划或任何需要追踪的工作项
执行流程
Step 1: 理解需求并收集上下文
OWNER=$(gh repo view --json owner --jq '.owner.login')
REPO=$(gh repo view --json name --jq '.name')
git log --oneline -10
git status --short
gh issue list --state open --json number,title,labels --limit 20
gh label list --json name --jq '.[].name'
同时回顾当前对话上下文——用户提到的现象、截图、报错、设计决策、优先级、已确认的结论等。不要重复提问已回答过的问题。
从仓库信息和对话上下文中提炼：
- 是什么 — 问题现象或需求本质
- 为什么 — 动机、对用户/团队的价值
- 在哪里 — 影响哪些模块/页面/功能
- 什么时候 — 触发条件或复现步骤
Step 1.5: 查重
两段式：先用 Step 1 拿到的 open issue 列表做近况了解，再针对核心关键词做检索（覆盖 open + closed，能抓到曾以 wontfix 关闭又被重提的需求）：
gh search issues --repo "$OWNER/$REPO" "<核心关键词>" --limit 10 --json number,title,state,url
gh issue view <number> --repo "$OWNER/$REPO" --json title,body,labels,assignees
对比当前需求与已有 issue 的核心意图（不是字面措辞），判断：
| 判定 | 行动 |
|---|
| 完全重复 | 停止创建，向用户报告已有 issue 编号和链接 |
| 部分重叠（范围更大或角度不同） | 向用户说明重叠点，询问：补充到已有 issue / 创建新 issue 并关联 / 取消 |
| 无重复 | 继续 Step 2 |
Step 2: 探索相关代码，获取精准定位
定位信息的详细程度应与 Issue 复杂度匹配，避免过量信息变成噪音：
| Issue 类型 | 定位粒度 | 示例 |
|---|
简单功能 / good first vibe | 涉及的模块或功能域 | "点赞相关逻辑"、"用户认证模块" |
| 中等复杂度 | 相关文件路径 + 当前行为概述 | "src/features/hub/ 下的点赞组件，目前无动画" |
| 复杂 bug / 难复现问题 | 精确文件路径 + 行号 + 当前行为 | "src/lib/auth.ts:42-58 中 token 刷新逻辑在并发时竞态" |
探索代码时记录：
- 涉及的模块/功能域（必须）
- 当前代码的实际行为（必须，基于代码阅读而非推测）
- 具体文件路径和行号（仅在复杂 issue 中提供）
Step 3: 判断是否需要拆分
| 信号 | 行动 |
|---|
| 范围可被一个 AI agent session 完成 | 单个 issue |
| 涉及多个独立模块或有先后依赖 | 拆分 sub-issues |
| 用户明确说"拆一下" | 创建 parent + sub-issues |
拆分原则：
- 每个 sub-issue 应该是一个独立可完成的工作单元
- 标注 sub-issues 之间的依赖关系（可并行 vs 必须串行）
Step 4: 向用户提问对齐
创建 Issue 前必须通过提问与用户对齐。 不要默默生成然后直接提交。
使用 AskUserQuestion（或当前环境中等效的交互式提问工具）向用户提出选择题，让用户通过选择选项来确认或纠偏。每个问题提供具体选项和简要说明，降低用户的回答成本。每个问题的选项中必须标注一个"推荐"和一个"次推荐"，让用户在没有强烈偏好时能快速采纳你的建议。
需要对齐的维度（根据实际情况组合提问，不必每次都问全）：
- 需求理解 — 你对核心问题/需求的理解是否正确？如有多种解读，每种解读作为一个选项
- 范围边界 — 这个需求包含哪些、不包含哪些？模糊的边界作为选项让用户勾选
- 拆分方案 — 单个 issue 还是拆分？如果拆分，给出拆法选项
- 标签建议 — 准备打什么标签，让用户确认或调整
- 其他模糊点 — 任何你不确定的地方，都转化为选择题而非开放问题
原则：宁可多问一轮，不要创建出需要关闭重建的 issue。
豁免：用户明确说"直接建，不用确认"，或当前处于无人值守/自主执行模式（如 /goal 模式、定时任务、CI 等无法交互的场景）时，跳过提问，直接采用各维度的推荐选项创建，并在 Step 7 的输出摘要中列出所采用的假设。
Step 5: 生成 Issue 内容
使用下方模板。关键：
- TL;DR 必须让人类 10 秒内理解核心
- 定位信息必须来自实际代码探索，不能猜测
- 验收标准必须可机械检查
Step 6: 创建 Issue 并关联
gh issue create \
--repo "$OWNER/$REPO" \
--title "Issue 标题" \
--label "enhancement" \
--body "$(cat <<'ISSUE_EOF'
[Issue body]
ISSUE_EOF
)"
Sub-issues 关联：
SUB_URL=$(gh issue create --repo "$OWNER/$REPO" --title "..." --label "..." --body "...")
SUB_NUMBER=$(echo "$SUB_URL" | grep -oE '[0-9]+$')
PARENT_ID=$(gh issue view <parent_number> --repo "$OWNER/$REPO" --json id --jq ".id")
CHILD_ID=$(gh issue view "$SUB_NUMBER" --repo "$OWNER/$REPO" --json id --jq ".id")
gh api graphql -f parentId="$PARENT_ID" -f childId="$CHILD_ID" -f query='
mutation($parentId: ID!, $childId: ID!) {
addSubIssue(input: {issueId: $parentId, subIssueId: $childId}) {
issue { title number }
subIssue { title number }
}
}'
GitLab 环境（glab）的等效命令见 references/glab.md——GitLab 没有 GitHub 式 sub-issue，需用 issue links 表达父子/依赖关系。
Step 7: 输出摘要
创建完成后，向用户报告：
- 创建了哪些 issue（编号 + 链接）
- sub-issue 关联状态
- 建议的工作顺序（如有依赖关系）
Issue 模板
单一 Issue
## TL;DR
[1-2 句话。人类读完这段就能决定要不要做。]
## 决策点
> 需要人类判断的选择。没有则删除本节。
- [ ] [选择 A vs 选择 B：简述权衡]
## 问题/需求描述
[3-5 句话描述问题现象或需求背景。聚焦"是什么"和"为什么"。]
## 当前行为
[精确描述当前代码的实际行为。基于代码阅读而非猜测。]
## 期望行为
[精确描述完成后应该是什么样。]
---
<!-- 以下为定位信息，详细程度按 Issue 复杂度调整 -->
## 影响范围
<!-- 简单 issue：只写模块/功能域 -->
涉及模块：[模块名 / 功能域描述]
<!-- 复杂 issue：展开为精确表格 -->
| 文件 | 行号 | 当前状态 |
|------|------|---------|
| `src/features/xxx/pages/XxxPage.tsx` | 42-58 | [当前代码在这些行做了什么] |
| `src/lib/xxx.ts` | 15 | [当前状态描述] |
## 触发/复现方式
1. [具体步骤 1]
2. [具体步骤 2]
3. [观察到的现象]
## 验收标准
- [ ] [可检查的标准 1]
- [ ] [可检查的标准 2]
- [ ] [仓库约定的构建/测试命令]通过（从 CLAUDE.md、package.json、Makefile、CI 配置探测，如 `pnpm run build`、`cargo test`）
## 关联
- 相关 Issue: #N
- 依赖: #M（需先完成）
Parent Issue（带 Sub-issues）
## TL;DR
[1-2 句话概括整体目标]
## 概述
[3-5 句话描述问题/需求的完整背景]
## Sub-issues 总览
| # | 标题 | 依赖 |
|---|------|------|
| 1 | [子任务 1] | 无 |
| 2 | [子任务 2] | 无 |
| 3 | [子任务 3] | #1 完成后 |
## 依赖关系
Sub-Issue 1 ──┐
Sub-Issue 2 ──┼──→ 可并行
│
▼
Sub-Issue 3 ──→ 依赖 Sub-Issue 1
## 验收标准（整体）
- [ ] 所有 sub-issues 完成
- [ ] [整体集成验证标准]
标签选择
标签是 Issue 的分类入口，直接影响优先级排序、看板过滤和任务分配。必须根据 Issue 内容主动选择标签，并在 Step 4 对齐时向用户确认。
选择标签时考虑两个维度：
1. 类型标签（必选，描述这个 Issue 是什么性质）：
| 类型 | 标签 | 判断依据 |
|---|
| 新功能 | enhancement | 当前不存在的能力，需要新增 |
| Bug 修复 | bug | 现有功能的行为不符合预期 |
| UI/视觉 | enhancement + design（如有） | 涉及样式、布局、交互体验 |
| 文档 | documentation | 仅涉及文档变更，不改代码逻辑 |
2. 难度/协作标签（符合条件时必须打）：
| 标签 | 判断依据 |
|---|
good first issue | 改动范围小、上下文自包含、不需要深入理解项目架构，适合新贡献者上手 |
good first vibe | Issue 正文本身已提供充足上下文，AI agent 仅凭 Issue 内容（无需额外对话）就能独立完成 |
3. 辅助标签（可选，描述额外属性）：
根据仓库中已有的标签体系，酌情追加优先级（priority:high）、模块（area:auth）等辅助标签。不要凭空发明标签体系，优先复用仓库现有标签。
如果仓库中没有需要的标签，先用 gh label create 创建。
标题格式
[模块] 动词短语描述
示例：
[Hub] 独立化色彩体系，消除 primary 色污染[Dashboard] 马赛克墙触摸设备长按无响应[Auth] 邀请码注册后未自动跳转到仪表板
质量自检
示例
示例 1: 简单功能需求
用户说： "Hub 页面的点赞加个动画效果"
执行：
- 搜索点赞相关代码，记录模块和当前行为（点击后立即切换状态，无过渡）
- 向用户确认动画类型偏好（缩放、弹跳、粒子等）
- 创建单个 issue，标注
good first vibe
示例 2: 需要拆分的大需求
用户说： "把认证系统从 mock 切换到 Supabase，帮我拆一下"
执行：
- 分析 mock 和 Supabase 接口差异，列出涉及的模块
- 向用户确认拆分方案和优先级
- 创建 parent + sub-issues 并关联
- 报告依赖关系和建议工作顺序
