Back to Details

issues-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Issues-First Workflow

以GitHub Issues为核心的工作流

Default: Use GitHub Issues exclusively for all content, hierarchy, and tracking. Optional: Link to Projects v2 for cross-repo visualization only.
默认规则：所有内容、层级结构和追踪工作均仅使用GitHub Issues完成。 可选方案：仅将Projects v2用于跨仓库可视化。

Critical Principle: Issues Are Everything

核心原则：议题即一切

GitHub Issues = Content + Hierarchy + Status + History. GitHub Projects v2 = Visualization layer only (no content, no history).
With sub-issues (GA April 2025), Issues now handle hierarchy natively. Projects v2 is reduced to an optional visualization dashboard.
GitHub Issues = 内容 + 层级 + 状态 + 历史记录。 GitHub Projects v2 = 仅可视化层（无内容、无历史记录）。
随着子议题功能（2025年4月正式发布）的推出，Issues现在可原生处理层级结构。Projects v2仅作为可选的可视化仪表盘存在。

Issues vs Projects v2

Issues vs Projects v2

CapabilityIssues (Default)Projects v2 (Visualization Only)
ContentBody, comments, code blocksNone (links to Issues only)
HierarchySub-issues (100 per parent)Flat list
StatusOpen/Closed + labelsCustom fields (no history)
Edit historyFull diff on every editNone
TimelineAll changes loggedStatus changes only (30-day limit)
SearchFull-text + 30+ filtersLimited
CLI
gh issue list/view/create
gh project
(Classic PAT only)
Cross-repoManual (
--repo A --repo B
)		Single dashboard view
功能项Issues（默认使用）Projects v2（仅可视化）
内容存储正文、评论、代码块无（仅链接到Issues）
层级结构子议题（每个父议题最多100个）扁平列表
状态管理开启/关闭 + 标签自定义字段（无历史记录）
编辑历史每次编辑的完整差异记录无
时间线所有变更均被记录仅状态变更（30天限制）
搜索功能全文搜索 + 30+筛选条件功能受限
命令行支持
gh issue list/view/create
gh project
（仅支持经典PAT）
跨仓库支持手动操作（
--repo A --repo B
）		单一仪表盘视图

When to Use Each

适用场景区分

┌─────────────────────────────────────────────────────────────┐
│                 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                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                 以Issues为核心的工作流                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   始终使用Issues完成：                                     │
│   ├── 所有内容（研究发现、分析、结论）          │
│   ├── 层级结构（父议题 + 子议题）                        │
│   ├── 状态追踪（标签：status:in-progress）           │
│   ├── 分类管理（标签：research:regime, priority:P0）  │
│   └── 筛选操作（gh issue list --label X --state Y）          │
│                                                              │
│   可选择使用Projects v2完成：                            │
│   ├── 跨仓库仪表盘（跨仓库的统一视图）        │
│   ├── 看板可视化（拖拽式看板）             │
│   ├── 路线图时间线（基于日期的可视化视图）              │
│   └── 干系人汇报（状态更新信息流）            │
│                                                              │
│   切勿在Projects v2中处理：                                  │
│   ├── 研究发现（无编辑历史）                    │
│   ├── 分析细节（更新后丢失）                      │
│   ├── 任何文本内容（使用Issue正文/评论）             │
│   └── 任何需要追踪变更的内容                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Decision Tree

决策树

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
需要追踪工作？
├── 单一仓库，议题数<50 → 仅使用Issues（跳过Projects）
├── 单一仓库，议题数≥50 → 使用Issues + 可选的Projects看板
├── 多仓库 → 使用Issues + Projects跨仓库仪表盘
└── 需向干系人展示 → 使用Issues + Projects状态更新

When to Use This Skill

何时使用该工作流

Use this skill when:
  • Setting up issue hierarchy with sub-issues (default workflow)
  • Creating cross-repo visualization dashboards
  • Configuring auto-linking from Issues to Projects
  • Setting up stakeholder Status Updates
Remember: All content lives in Issues. Projects v2 is a read-only visualization layer.
在以下场景使用本工作流：
  • 需设置带子议题的议题层级结构（默认工作流）
  • 创建跨仓库可视化仪表盘
  • 配置从Issues到Projects的自动链接
  • 设置干系人状态更新
注意：所有内容均存储在Issues中。Projects v2是只读的可视化层。

Invocation

调用方式

Slash command: 
/gh-tools:issues-workflow
Natural language triggers:
  • "Create sub-issues for this parent"
  • "Set up issue hierarchy"
  • "Create cross-repo dashboard"
  • "Link issues to project for visualization"
斜杠命令：
/gh-tools:issues-workflow
自然语言触发词：
  • "为该父议题创建子议题"
  • "设置议题层级结构"
  • "创建跨仓库仪表盘"
  • "将议题链接到项目以实现可视化"

Issues-First Workflow (Default)

以Issues为核心的工作流（默认）

Sub-Issues: Native Hierarchy (GA April 2025)

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

Sub-issues replace the need for Projects v2 hierarchy. Use for all structured work.
子议题可替代Projects v2的层级功能，适用于所有结构化工作。

When to Use Sub-Issues

子议题适用场景

Use CaseExampleWhy Sub-Issues
Research breakdownParent: "Investigate microstructure" → Subs: individual patternsTrack which patterns validated/invalidated
Epic decompositionParent: "User authentication" → Subs: login, logout, password resetProgress bar shows completion %
Multi-step investigationParent: "Debug performance issue" → Subs: profiling, memory, CPUEach sub can be assigned differently
Phased workParent: "v2.0 release" → Subs: Phase 1, Phase 2, Phase 3Natural ordering with timeline
适用场景示例选择子议题的原因
研究任务拆分父议题："研究微观结构" → 子议题：各独立研究方向追踪哪些研究方向已验证/未验证
史诗任务分解父议题："用户认证系统" → 子议题：登录、登出、密码重置进度条显示完成百分比
多步骤问题排查父议题："调试性能问题" → 子议题：性能分析、内存排查、CPU分析每个子议题可分配给不同人员
阶段性工作父议题："v2.0版本发布" → 子议题：阶段1、阶段2、阶段3带时间线的自然排序

When NOT to Use Sub-Issues

子议题不适用场景

SituationUse InsteadWhy
Simple checklist (< 5 items)Markdown checkboxes in issue bodyLess overhead, editable inline
Cross-repo dependenciesIssue references (
See org/repo#123
)		Sub-issues are same-repo only
Loose relationships"Related to #X" in bodySub-issues imply containment
One-off tasksSingle issue with labelsDon't over-structure
场景替代方案原因
简单 Checklist（<5项）Issue正文中的Markdown复选框开销更低，可在线编辑
跨仓库依赖议题引用（
See org/repo#123
）		子议题仅支持同仓库
松散关联正文中添加"Related to #X"子议题表示包含关系
一次性任务带标签的单一议题避免过度结构化

Creating Sub-Issues

创建子议题

bash
undefined
bash
undefined

Create parent issue

创建父议题

gh issue create --title "Research: Range Bar Microstructure"
--label "research:parent" --repo terrylica/rangebar-py
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)

创建子议题（在正文中引用父议题或使用UI操作）

gh issue create --title "Regime detection patterns"
--body "Parent: #100" --label "research:sub" --repo terrylica/rangebar-py

**Structure example**:
#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
undefined
gh issue create --title "Regime detection patterns" \ --body "Parent: #100" --label "research:sub" --repo terrylica/rangebar-py

**结构示例**:
#100 Research: Range Bar Microstructure (父议题) ├── #101 Regime detection patterns - 未验证 ✗ ├── #102 Cross-threshold correlations - 已验证 ✓ ├── #103 Duration normalization - 进行中 └── #104 Microstructure features v7.0 - 开启
undefined

Sub-Issue Features

子议题功能特性

  • Progress bar: Parent shows "X of Y completed" with visual bar
  • Bidirectional links: Sub shows "Parent issue" in sidebar, parent lists all subs
  • Automatic tracking: Close sub → parent progress updates
  • Nesting: Up to 8 levels deep (sub-sub-sub-issues)
  • Limit: 100 sub-issues per parent
Migration Note: Tasklist blocks retired April 30, 2025. Sub-issues are the official replacement. No migration tooling - manual conversion required.
  • 进度条：父议题显示"已完成X/Y"的可视化进度条
  • 双向链接：子议题侧边栏显示"父议题"，父议题列出所有子议题
  • 自动追踪：关闭子议题 → 父议题进度自动更新
  • 嵌套支持：最多支持8级嵌套（子-子-子议题）
  • 数量限制：每个父议题最多100个子议题
迁移说明：Tasklist模块已于2025年4月30日停用。子议题是官方替代方案。无迁移工具，需手动转换。

Status via Labels (No Projects Needed)

基于标签的状态管理（无需Projects）

Use labels instead of Project custom fields:
Label PatternPurposeExample
status:*
Workflow state
status:in-progress
priority:*
Urgency
priority:P0
research:*
Research categorization
research:validated
type:*
Issue classification
type:hypothesis
bash
undefined
使用标签替代Projects的自定义字段：
标签格式用途示例
status:*
工作流状态
status:in-progress
priority:*
紧急程度
priority:P0
research:*
研究分类
research:validated
type:*
议题类型
type:hypothesis
bash
undefined

Filter by status

按状态筛选

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

Filter by research outcome

按研究结果筛选

gh issue list --label "research:validated" --state all
gh issue list --label "research:validated" --state all

Combined filters

组合筛选

gh issue list --label "research:regime,status:complete" --state closed
undefined
gh issue list --label "research:regime,status:complete" --state closed
undefined

Issue Types (GA 2025)

议题类型（2025年正式发布）

Organization-level standardization (orgs only, not personal accounts):
bash
undefined
组织级标准化（仅支持组织账户，不支持个人账户）：
bash
undefined

Configure at: Organization Settings → Issues → Issue Types

配置路径：组织设置 → Issues → 议题类型

Personal accounts: Use labels instead (type:hypothesis, type:finding)

个人账户：使用标签替代（type:hypothesis, type:finding）

undefined
undefined

Projects v2: Visualization Layer (Optional)

Projects v2：可视化层（可选）

Use Projects v2 only for cross-repo visualization. All content remains in Issues.
仅将Projects v2用于跨仓库可视化。所有内容仍存储在Issues中。

When to Use Projects v2

Projects v2适用场景

Use CaseWhy Projects v2 Helps
Cross-repo dashboardSingle view across multiple repos
Kanban boardDrag-and-drop visual workflow
Roadmap timelineDate-based visual planning
Stakeholder StatusStatus Updates feed (ON_TRACK, etc.)
适用场景选择Projects v2的原因
跨仓库仪表盘跨仓库的统一视图
看板拖拽式可视化工作流
路线图时间线基于日期的可视化规划
干系人状态更新状态更新信息流（ON_TRACK等）

When NOT to Use Projects v2

Projects v2不适用场景

  • Single repo with < 50 issues (use 
    gh issue list
    filters)
  • Need edit history (Projects has none)
  • Need content storage (use Issue body/comments)
  • Need version tracking (Projects loses previous values)
  • 单一仓库且议题数<50（使用
    gh issue list
    筛选）
  • 需要编辑历史（Projects无此功能）
  • 需要存储内容（使用Issue正文/评论）
  • 需要版本追踪（Projects会丢失历史值）

Auto-Linking Issues to Projects

议题到Projects的自动链接

Link Issues automatically so Projects stay in sync:
Option 1: Label prefix convention
LabelAuto-links to
project:research
Research Findings
project:dev
Active Development
Option 2: Config file (
.github/project-links.json
):
json
{
  "mappings": [
    {
      "labels": ["research:regime", "research:validated"],
      "projectNumber": 2
    }
  ],
  "owner": "terrylica"
}
自动链接Issues与Projects，保持两者同步：
方案1：标签前缀约定
标签自动链接到
project:research
Research Findings
project:dev
Active Development
方案2：配置文件（
.github/project-links.json
）：
json
{
  "mappings": [
    {
      "labels": ["research:regime", "research:validated"],
      "projectNumber": 2
    }
  ],
  "owner": "terrylica"
}

Status Updates (Stakeholder Communication)

状态更新（干系人沟通）

bash
undefined
bash
undefined

Create status update via GraphQL

通过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"
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

状态值：ON_TRACK | AT_RISK | OFF_TRACK | COMPLETE | INACTIVE

undefined
undefined

Token Requirements

令牌要求

CRITICAL: Projects v2 API requires Classic PAT with 
project
scope.
bash
undefined
关键提示：Projects v2 API需要经典PAT并拥有
project
权限。
bash
undefined

Check token type

检查令牌类型

cat ~/.claude/.secrets/gh-token-terrylica | head -c 10
cat ~/.claude/.secrets/gh-token-terrylica | head -c 10

ghp_ = Classic PAT (supports Projects)

ghp_ = 经典PAT（支持Projects）

github_pat_ = Fine-grained (NO Projects support)

github_pat_ = 细粒度PAT（不支持Projects）

undefined
undefined

Project Commands Reference

项目命令参考

bash
undefined
bash
undefined

List/create/view projects

列出/创建/查看项目

gh project list --owner <owner> gh project create --owner <owner> --title "Dashboard Name" gh project view <number> --owner <owner>
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>
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
undefined
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
undefined

GitHub Issues: Complete Feature Reference

GitHub Issues：完整功能参考

Core Issue Commands

核心议题命令

bash
undefined
bash
undefined

Create issue

创建议题

gh issue create --title "Title" --body "Body" --label "label1,label2"
gh issue create --title "标题" --body "正文" --label "label1,label2"

Create with body file (recommended for long content)

使用文件作为正文（长内容推荐）

gh issue create --title "Title" --body-file /tmp/issue-body.md
gh issue create --title "标题" --body-file /tmp/issue-body.md

View issue

查看议题

gh issue view <number> --repo owner/repo
gh issue view <编号> --repo owner/repo

List with filters

带筛选的列出议题

gh issue list --label "research:validated" --state all --assignee @me
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"
gh issue edit <编号> --add-label "status:complete" --remove-label "status:in-progress"

Close/reopen

关闭/重新开启议题

gh issue close <number> --reason completed gh issue reopen <number>
undefined
gh issue close <编号> --reason completed gh issue reopen <编号>
undefined

Advanced Filtering (30+ qualifiers)

高级筛选（30+限定符）

bash
undefined
bash
undefined

By multiple labels (AND logic)

多标签筛选（逻辑与）

gh issue list --label "research:regime,priority:P0"
gh issue list --label "research:regime,priority:P0"

By milestone

按里程碑筛选

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

By date

按日期筛选

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

By author/assignee

按作者/经办人筛选

gh issue list --author @me --assignee username
gh issue list --author @me --assignee username

Full-text search

全文搜索

gh issue list --search "microstructure in:title,body"
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
undefined
gh issue list \ --label "research:validated" \ --state closed \ --search "regime created:>2025-06-01" \ --json number,title,labels
undefined

Issue Relationships

议题关联

bash
undefined
bash
undefined

Reference in body (creates link in timeline)

正文中引用（时间线中创建链接）

"Related to #45" "Closes #123" "Fixes #456"
"Related to #45" "Closes #123" "Fixes #456"

Cross-repo reference

跨仓库引用

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

Sub-issue (parent reference in body)

子议题（正文中引用父议题）

"Parent: #100"
undefined
"Parent: #100"
undefined

Timeline and History

时间线与历史记录

bash
undefined
bash
undefined

View full timeline (all events)

查看完整时间线（所有事件）

gh api repos/owner/repo/issues/123/timeline --paginate
gh api repos/owner/repo/issues/123/timeline --paginate

View edit history (via web UI or API)

查看编辑历史（通过Web UI或API）

gh api repos/owner/repo/issues/123 --jq '.body_html'
gh api repos/owner/repo/issues/123 --jq '.body_html'

Comment with preserved history

带历史记录的评论

gh issue comment <number> --body "Update: new findings"
undefined
gh issue comment <编号> --body "Update: new findings"
undefined

Milestones (Alternative to Project Iterations)

里程碑（替代项目迭代）

bash
undefined
bash
undefined

List milestones

列出里程碑

gh api repos/owner/repo/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"
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"
undefined
gh issue edit <编号> --milestone "Research Phase 2"
undefined

Workflow Examples

工作流示例

Issues-Only Research Workflow

仅使用Issues的研究工作流

bash
undefined
bash
undefined

1. Create parent research issue

1. 创建父研究议题

gh issue create
--title "Research: Range Bar Microstructure Patterns"
--label "research:parent,priority:P1"
--body-file /tmp/research-parent.md
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

2. 为每个研究方向创建子议题

for topic in "regime-detection" "cross-threshold" "duration-normalization"; do gh issue create
--title "Sub: $topic analysis"
--label "research:sub"
--body "Parent: #100" done
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

3. 通过标签追踪进度

gh issue edit 101 --add-label "research:invalidated" gh issue edit 102 --add-label "research:validated" gh issue close 101 --reason "not planned"
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

4. 筛选查看状态

gh issue list --label "research:sub" --state all --json number,title,state,labels
undefined
gh issue list --label "research:sub" --state all --json number,title,state,labels
undefined

Optional: Add to Project for Visualization

可选：添加到Projects进行可视化

bash
undefined
bash
undefined

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
undefined
gh issue list --label "research:validated" --json url --jq '.[].url' | \ while read url; do gh project item-add 2 --owner terrylica --url "$url" done
undefined

Title Evolution: Re-evaluate on New Comments

标题优化：新增评论时重新评估

PRINCIPLE: GitHub issue titles have a 256-character limit. Maximize this limit to create informative titles that reflect the current state of the issue.
原则：GitHub议题标题有256字符限制。需最大化利用该限制，创建能反映议题当前状态的信息性标题。

When to Re-evaluate

重新评估时机

Re-evaluate and potentially update the issue title when significant new information is added - new findings, status changes, scope expansion, or when the journey is complete.
当添加重要新信息时——如新发现、状态变更、范围扩大或任务完成时，需重新评估并可能更新议题标题。

Commands

相关命令

bash
undefined
bash
undefined

Check current title length

检查当前标题长度

gh issue view <number> --json title --jq '.title | length'
gh issue view <编号> --json title --jq '.title | length'

Update title (maximize 256 chars based on content)

更新标题（根据内容最大化利用256字符）

gh issue edit <number> --title "..."

The AI agent determines the best way to maximize informativeness based on the nature of the content.
gh issue edit <编号> --title "..."

AI Agent会根据内容性质，决定如何最大化标题的信息性。

GFM Rendering Anti-Patterns

GFM渲染反模式

NEVER use bare 
#N
in issue/PR comments. GitHub auto-links any 
#N
where issue N exists — in prose, tables, lists. This is unpredictable and inconsistent (some numbers link, others don't).
  • To reference an issue: Use explicit full URL → 
    [Issue 13](https://github.com/owner/repo/issues/13)
  • For non-issue numbers: Suppress with backtick → 
    `#1`
  • Backslash 
    \#1
    does NOT work     inside table cells
See the full reference for 6 documented anti-patterns: GFM Anti-Patterns Reference
切勿在议题/PR评论中使用裸
#N
格式。GitHub会自动链接任何存在的议题N——包括在散文、表格、列表中。这一行为不可预测且不一致（部分数字会被链接，部分不会）。
  • 引用议题：使用完整显式URL → 
    [Issue 13](https://github.com/owner/repo/issues/13)
  • 非议题数字：使用反引号包裹 → 
    `#1`
  • 反斜杠
    \\#1
    在表格单元格中无效
查看完整的6种已记录反模式：GFM反模式参考

Troubleshooting

故障排查

IssueCauseFix
#N
auto-links in tables		GFM auto-referenceUse backtick code span: 
`#1`
(details)
"Resource not accessible"Fine-grained PATUse Classic PAT for Projects v2
Sub-issues not linkingWrong body formatUse exact "Parent: #123" syntax
Labels not filtering correctlyTypo in label name
gh label list
to verify exact names
Long body truncatedInline 
--body
limit		Use 
--body-file
instead
Title too short/vagueNot using full limitMaximize 256-char limit for context
问题原因修复方案
表格中
#N
自动链接		GFM自动引用规则使用反引号代码块：
`#1`
（详情)
"资源不可访问"错误使用了细粒度PAT为Projects v2使用经典PAT
子议题无法关联正文格式错误使用精确的"Parent: #123"语法
标签筛选不生效标签名称拼写错误使用
gh label list
验证准确名称
长正文被截断内联
--body
参数限制		使用
--body-file
替代
标题过短/模糊未充分利用字符限制最大化利用256字符限制添加上下文

References

参考资料

  • gh-tools Issue Create Skill
  • GFM Anti-Patterns
  • Field Types Reference
  • Auto-Link Configuration
  • GraphQL Queries Reference
  • GitHub Issues Documentation
  • gh-tools Issue Create Skill
  • GFM反模式
  • 字段类型参考
  • 自动链接配置
  • GraphQL查询参考
  • GitHub Issues官方文档 ",