issues-workflow

以 GitHub Issues 为先的工作流

默认：所有内容、层级结构和跟踪均仅使用 GitHub Issues。 可选：仅将 Projects v2 用于跨仓库可视化。

自我演进技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

核心原则：一切皆 Issues

GitHub Issues = 内容 + 层级结构 + 状态 + 历史记录。 GitHub Projects v2 = 仅作可视化层（不包含内容和历史记录）。

自 2025 年 4 月子 Issue 正式发布（GA）后，Issues 现在可原生处理层级结构。Projects v2 因而简化为可选的可视化仪表板。

Issues 与 Projects v2 对比

功能	Issues（默认）	Projects v2（仅作可视化）
内容	正文、评论、代码块	无（仅链接到 Issues）
层级结构	子 Issue（每个父级 100 个）	平面列表
状态	开启/关闭 + 标签	自定义字段（无历史记录）
编辑历史	每次编辑均有完整差异记录	无
时间线	记录所有变更	仅状态变更（限 30 天）
搜索	全文搜索 + 30 多种筛选条件	有限
CLI	gh issue list/view/create	gh project（仅限 Classic PAT）
跨仓库	手动（--repo A --repo B）	单个仪表板视图

何时使用各项功能

┌─────────────────────────────────────────────────────────────┐
│                 ISSUES-FIRST WORKFLOW                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ALWAYS use Issues for:                                     │
│   ├── All content (findings, analysis, conclusions)          │
│   ├── Hierarchy (parent + sub-issues)                        │
│   ├── Status tracking (labels: status:in-progress)           │
│   ├── Categorization (labels: research:regime, priority:P0)  │
│   └── Filtering (gh issue list --label X --state Y)          │
│                                                              │
│   OPTIONALLY use Projects v2 for:                            │
│   ├── Cross-repo dashboard (single view across repos)        │
│   ├── Kanban visualization (drag-and-drop board)             │
│   ├── Roadmap timeline (visual date-based view)              │
│   └── Stakeholder reporting (Status Updates feed)            │
│                                                              │
│   NEVER put in Projects v2:                                  │
│   ├── Research findings (no edit history)                    │
│   ├── Analysis details (lost on update)                      │
│   ├── Any text content (use Issue body/comments)             │
│   └── Anything you need to track changes for                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘

决策树

Need to track work?
├── Single repo, <50 issues → Issues only (skip Projects)
├── Single repo, 50+ issues → Issues + optional Project for kanban
├── Multiple repos → Issues + Project for cross-repo dashboard
└── Stakeholder visibility → Issues + Project Status Updates

何时使用此技能

在以下情况下使用此技能：

• 使用子 Issue 设置 Issue 层级结构（默认工作流）
• 创建跨仓库可视化仪表板
• 配置从 Issues 到 Projects 的自动关联
• 设置面向利益相关者的状态更新

请记住：所有内容都存放在 Issues 中。Projects v2 是只读的可视化层。

调用方式

斜杠命令：/gh-tools:issues-workflow

自然语言触发语句：

• “为此父 Issue 创建子 Issue”
• “设置 Issue 层级结构”
• “创建跨仓库仪表板”
• “将 Issue 关联到项目以进行可视化”

以 Issues 为先的工作流（默认）

子 Issue：原生层级结构（2025 年 4 月正式发布）

子 Issue 取代了 Projects v2 层级结构的需求。所有结构化工作均使用子 Issue。

何时使用子 Issue

使用场景	示例	使用子 Issue 的原因
研究任务拆分	父 Issue：“调查微观结构” → 子 Issue：各个模式	跟踪哪些模式已验证/已否定
大型任务拆解	父 Issue：“用户身份验证” → 子 Issue：登录、注销、密码重置	进度条显示完成百分比
多步骤调查	父 Issue：“调试性能问题” → 子 Issue：性能分析、内存、CPU	可分别为每个子 Issue 指定负责人
分阶段工作	父 Issue：“v2.0 发布” → 子 Issue：阶段 1、阶段 2、阶段 3	可按时间线自然排序

不要使用子议题的情况

情况	改用	原因
简单清单（< 5 项）	在议题正文中使用 Markdown 复选框	开销更小，可直接在行内编辑
跨仓库依赖	议题引用（See org/repo#123）	子议题仅限同一仓库
松散关联	在正文中注明“Related to #X”	子议题意味着包含关系
一次性任务	使用带标签的单个议题	避免过度组织

创建子议题

# Create parent issue
gh issue create --title "Research: Range Bar Microstructure" \
  --label "research:parent" --repo terrylica/rangebar-py

# Create sub-issues (reference parent in body or use UI)
gh issue create --title "Regime detection patterns" \
  --body "Parent: #100" --label "research:sub" --repo terrylica/rangebar-py

结构示例：

#100 Research: Range Bar Microstructure (parent)
├── #101 Regime detection patterns - Invalidated ✗
├── #102 Cross-threshold correlations - Validated ✓
├── #103 Duration normalization - In Progress
└── #104 Microstructure features v7.0 - Open

子议题功能

• 进度条：父议题显示“已完成 X 项，共 Y 项”，并附有可视化进度条
• 双向链接：子议题的侧边栏显示“父议题”，父议题则列出所有子议题
• 自动跟踪：关闭子议题 → 父议题进度随之更新
• 嵌套：最多可嵌套 8 层（子子子议题）
• 限制：每个父议题最多 100 个子议题

迁移说明：任务列表代码块已于 2025 年 4 月 30 日退役。子议题是其官方替代方案。没有迁移工具，需手动转换。

通过标签设置状态（无需 Projects）

使用标签代替 Project 自定义字段：

标签模式	用途	示例
status:*	工作流状态	status:in-progress
priority:*	紧急程度	priority:P0
research:*	研究分类	research:validated
type:*	议题分类	type:hypothesis

# Filter by status
gh issue list --label "status:in-progress" --repo terrylica/rangebar-py

# Filter by research outcome
gh issue list --label "research:validated" --state all

# Combined filters
gh issue list --label "research:regime,status:complete" --state closed

议题类型（2025 年 GA）

在组织级别进行标准化（仅适用于组织，不适用于个人账户）：

# Configure at: Organization Settings → Issues → Issue Types
# Personal accounts: Use labels instead (type:hypothesis, type:finding)

Projects v2：可视化层（可选）

仅在需要跨仓库可视化时使用 Projects v2。所有内容仍保留在 Issues 中。

何时使用 Projects v2

使用场景	Projects v2 的帮助
跨仓库仪表板	在一个视图中查看多个仓库
看板	通过拖放实现可视化工作流
路线图时间线	基于日期的可视化规划
利益相关方状态	状态更新动态（ON_TRACK 等）

不要使用 Projects v2 的情况

• 单个仓库且议题少于 50 个（使用 gh issue list 筛选器）
• 需要编辑历史记录（Projects 没有此功能）
• 需要存储内容（使用 Issue 正文/评论）
• 需要版本跟踪（Projects 会丢失以前的值）

自动将议题关联到 Projects

自动关联 Issues，让 Projects 保持同步：

选项 1：标签前缀约定

标签	自动关联到
project:research	Research Findings
project:dev	Active Development

选项 2：配置文件（.github/project-links.json）：

{
  "mappings": [
    {
      "labels": ["research:regime", "research:validated"],
      "projectNumber": 2
    }
  ],
  "owner": "terrylica"
}

状态更新（利益相关方沟通）

# Create status update via GraphQL
gh api graphql -f query='
mutation($projectId: ID!, $body: String!, $status: ProjectV2StatusUpdateStatus!) {
  createProjectV2StatusUpdate(input: {
    projectId: $projectId
    body: $body
    startDate: "2026-02-01"
    status: $status
  }) {
    statusUpdate { id status body }
  }
}' -f projectId="PVT_xxx" -f body="Research phase complete" -f status="ON_TRACK"

# Status values: ON_TRACK | AT_RISK | OFF_TRACK | COMPLETE | INACTIVE

令牌要求

重要：Projects v2 API 需要具有 project 作用域的 Classic PAT。

# Check token type
~/.claude/tools/bin/gh-token-for-repo | head -c 10
# ghp_ = Classic PAT (supports Projects)
# github_pat_ = Fine-grained (NO Projects support)

Project 命令参考

# List/create/view projects
gh project list --owner <owner>
gh project create --owner <owner> --title "Dashboard Name"
gh project view <number> --owner <owner>

# Link issues to project (for visualization)
gh project item-add <project-number> --owner <owner> \
  --url https://github.com/<owner>/<repo>/issues/<number>

# Bulk link by label
gh issue list --repo terrylica/rangebar-py \
  --label "research:regime" --json url --jq '.[].url' | \
while read url; do
  gh project item-add 2 --owner terrylica --url "$url"
done

GitHub Issues：完整功能参考

核心议题命令

# Create issue
gh issue create --title "Title" --body "Body" --label "label1,label2"

# Create with body file (alternative for very long content)
gh issue create --title "Title" --body-file /tmp/issue-body.md

# View issue
gh issue view <number> --repo owner/repo

# List with filters
gh issue list --label "research:validated" --state all --assignee @me

# Edit issue
gh issue edit <number> --add-label "status:complete" --remove-label "status:in-progress"

# Close/reopen
gh issue close <number> --reason completed
gh issue reopen <number>

高级筛选（30 多种限定符）

# By multiple labels (AND logic)
gh issue list --label "research:regime,priority:P0"

# By milestone
gh issue list --milestone "Research Phase 1"

# By date
gh issue list --search "created:>2025-01-01 updated:<2025-12-01"

# By author/assignee
gh issue list --author @me --assignee username

# Full-text search
gh issue list --search "microstructure in:title,body"

# Combine everything
gh issue list \
  --label "research:validated" \
  --state closed \
  --search "regime created:>2025-06-01" \
  --json number,title,labels

议题关系

# Reference in body (creates link in timeline)
"Related to #45"
"Closes #123"
"Fixes #456"

# Cross-repo reference
"See terrylica/other-repo#789"

# Sub-issue (parent reference in body)
"Parent: #100"

时间线与历史记录

# View full timeline (all events)
gh api repos/owner/repo/issues/123/timeline --paginate

# View edit history (via web UI or API)
gh api repos/owner/repo/issues/123 --jq '.body_html'

# Comment with preserved history
gh issue comment <number> --body "Update: new findings"

里程碑（Project 迭代的替代方案）

# List milestones
gh api repos/owner/repo/milestones

# Create milestone
gh api repos/owner/repo/milestones -f title="Research Phase 2" -f due_on="2026-03-01"

# Assign issue to milestone
gh issue edit <number> --milestone "Research Phase 2"

工作流示例

仅使用 Issues 的研究工作流

# 1. Create parent research issue
gh issue create \
  --title "Research: Range Bar Microstructure Patterns" \
  --label "research:parent,priority:P1" \
  --body-file /tmp/research-parent.md

# 2. Create sub-issues for each investigation
for topic in "regime-detection" "cross-threshold" "duration-normalization"; do
  gh issue create \
    --title "Sub: $topic analysis" \
    --label "research:sub" \
    --body "Parent: #100"
done

# 3. Track progress via labels
gh issue edit 101 --add-label "research:invalidated"
gh issue edit 102 --add-label "research:validated"
gh issue close 101 --reason "not planned"

# 4. Filter to see status
gh issue list --label "research:sub" --state all --json number,title,state,labels

可选：添加到 Project 以便可视化

# Only if you need cross-repo dashboard
gh issue list --label "research:validated" --json url --jq '.[].url' | \
while read url; do
  gh project item-add 2 --owner terrylica --url "$url"
done

标题演变：新评论出现时重新评估

原则：GitHub 议题标题最多 256 个字符。充分利用此限制，创建能够反映议题当前状态的说明性标题。

重新评估时机

添加了重要新信息（新发现、状态变更、范围扩大或工作已完成）时，重新评估并考虑更新问题标题。

命令

# Check current title length
gh issue view <number> --json title --jq '.title | length'

# Update title (maximize 256 chars based on content)
gh issue edit <number> --title "..."

AI Agent 会根据内容的性质，确定最大限度提升信息量的最佳方式。

Issue-分支-PR 生命周期

从问题到代码合并的完整生命周期，并自动关闭问题。所有自动化均在本地执行——不使用 GitHub Actions 进行测试或 lint。

推荐工作流

1. Create issue(s)           → gh issue create --title "..." --body "..."
2. Branch from issue         → gh issue develop <N> --checkout
3. Implement + commit        → git commit -m "feat: description"
4. Create PR (with keywords) → gh pr create --body "Closes #N"
5. Merge PR                  → gh pr merge --squash --delete-branch
6. Issue auto-closes         → GitHub handles this automatically

关闭关键词（合并时自动关闭）

在 PR 正文（而非标题）中使用 Closes #N、Fixes #N 或 Resolves #N，即可在合并时自动关闭问题。不区分大小写。跨仓库格式：Closes owner/repo#N。每个问题都需要单独的关键词——Closes #1, closes #2, fixes #3。

从 Issue 创建分支（gh issue develop）

gh issue develop 214 --checkout              # auto-names branch
gh issue develop 214 --name feat/x --checkout  # custom name

创建与问题关联的分支。从此分支创建的 PR 会自动关联该问题，并在合并时自动关闭问题。

同时使用 develop 和关闭关键词，双重保险。

完整参考：Issue-分支生命周期详细说明——关键词放置规则、跨仓库关闭、批量关闭、分支清理

GFM 渲染反模式

切勿在 Issue/PR 评论中直接使用 #N。 GitHub 会自动为任何存在对应问题 N 的 #N 添加链接，无论它出现在正文、表格还是列表中。这种行为不可预测且不一致（某些数字会生成链接，其他数字则不会）。

• 引用问题：使用完整 URL → [Issue 13](https://github.com/owner/repo/issues/13)
• 表示非问题编号：使用反引号禁用自动链接 → `#1`
• 反斜杠 \#1 在表格单元格中不起作用

有关记录的 6 种反模式，请参阅完整参考：GFM 反模式参考

故障排除

问题	原因	修复
表格中的 #N 自动生成链接	GFM 自动引用	使用反引号代码跨度：`#1`（详情）
“Resource not accessible”	精细化 PAT	Projects v2 使用 Classic PAT
子问题未建立链接	正文格式错误	使用精确格式 "Parent: #123"
标签筛选不正确	标签名称拼写错误	使用 gh label list 验证准确名称
正文过长而被截断	GitHub API 的 65536 字符限制	缩短内容，或将内容拆分到多条评论中
标题太短或含糊	未使用完整长度限制	尽量用足 256 字符限制来提供上下文

参考资料

• gh-tools Issue 创建技能
• Issue-分支生命周期——关闭关键词、gh issue develop、本地优先自动化
• GFM 反模式
• 字段类型参考
• 自动链接配置
• GraphQL 查询参考
• GitHub Issues 文档

执行后反思

此技能执行完毕后，关闭前请检查：

1. 命令是否成功？ — 如果没有，修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生偏移，请更新 Usage 示例和 Parameters 表以保持一致。
3. 是否需要变通方案？ — 如果你不得不临时调整（更换标志、增加步骤），请更新此 SKILL.md，以便下次调用时无需采用相同的变通方案。

只有问题确实存在且可复现时才进行更新，不要基于猜测更新。