issue-create

问题创建技能

借助智能自动化创建格式规范的 GitHub 问题，包括 AI 驱动的标签建议、内容类型检测、模板格式化和相关问题链接。

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

何时使用此技能

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

• 创建错误报告、功能请求、问题咨询或文档问题
• 需要 AI 根据仓库现有的分类体系推荐标签
• 希望自动检测重复问题并链接相关问题
• 需要在不同仓库中保持问题格式一致

调用方式

斜杠命令：/gh-tools:issue-create

自然语言触发语：

• “创建一个关于……的问题”
• “提交一个……错误报告”
• “提交一个功能请求……”
• “向……报告此问题”
• “在 GitHub 上发布一个问题……”

功能

1. 仓库检测

• 自动从当前 Git 目录检测仓库
• 支持显式使用 --repo owner/repo 标志
• 尝试创建前检查权限

2. 内容类型检测

• AI 驱动的检测（通过 gh-models 使用 gpt-4.1）
• 回退到关键词匹配
• 类型：错误、功能、问题咨询、文档

3. 标题提取

• 从内容中提取信息丰富的标题
• 添加类型前缀（Bug:、Feature: 等）
• 充分利用 GitHub 256 个字符的限制，创建信息丰富的标题

4. 正文长度上限利用（65,536 个字符）

GitHub 问题正文最多支持 65,536 个字符（不是字节——UTF-8 多字节字符按 1 个字符计数）。始终尽量在单篇帖子中写全内容，不要拆分到多个问题或评论中。

原则：一篇完整的帖子比许多零散的内容更有价值。尽可能将分析、背景、历史和多角度推理写入单个问题正文或评论中。

撰写长篇问题内容时：

• 检查剩余容量：echo "$BODY" | wc -m（统计字符数，而非字节数）
• 以约 60,000 个字符为目标，为 GFM 渲染的特殊情况留出余量
• 使用可折叠区块（<details><summary>）放置密集的参考资料——这不会减少字符预算，但能提升可读性
• 涵盖所有观点：如果问题记录了一项决策，请说明考虑过的替代方案、权衡、支持或反对的证据，以及选择当前方案的原因
• 补充历史背景：时间线、先例、相关问题链接、会话溯源信息——都应放在同一篇帖子中
• 不要预先拆分：只有确实超过 65,536 个字符时才拆分（这种情况很少见）

发布前检查大小的模式：

# Build body, then verify it fits
BODY=$(cat <<'EOF'
... your content ...
EOF
)
CHARS=$(echo "$BODY" | wc -m | tr -d ' ')
echo "Body size: ${CHARS}/65536 chars"
if [ "$CHARS" -gt 65536 ]; then
  echo "WARNING: Exceeds limit by $((CHARS - 65536)) chars — trim or split"
fi

5. 模板格式化

• 根据内容类型自动选择模板
• 错误：复现步骤、预期/实际行为
• 功能：使用场景、建议的解决方案
• 问题咨询：背景、已尝试的方法
• 文档：位置、建议的更改

5. 标签建议

• 获取仓库现有标签
• AI 推荐 2-4 个相关标签
• 仅推荐已存在的标签（了解分类体系）
• 使用 24 小时缓存提升性能

6. 相关问题

• 搜索类似问题
• 在正文中链接相关问题
• 对潜在重复问题发出警告

7. 预览并确认

• 创建前提供完整预览
• 支持试运行模式
• 可编辑修改

使用示例

基本用法

# From within a git repository
bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --body "Login page crashes when using special characters in password"

指定仓库

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --repo owner/repo \
  --body "Feature: Add dark mode support for better accessibility"

试运行（仅预览）

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --repo owner/repo \
  --body "Bug: API returns 500 error" \
  --dry-run

自定义标题和标签

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --repo owner/repo \
  --title "Bug: Login fails with OAuth" \
  --body "Detailed description..." \
  --labels "bug,authentication"

禁用 AI 功能

bun ~/eon/cc-skills/plugins/gh-tools/scripts/issue-create.ts \
  --body "Question: How to configure..." \
  --no-ai

CLI 选项

选项	简写	描述
--repo	-r	采用 owner/repo 格式的仓库
--body	-b	Issue 正文内容（必填）
--title	-t	Issue 标题（可选）
--labels	-l	以逗号分隔的标签
--dry-run		预览而不创建
--no-ai		禁用 AI 功能
--verbose	-v	启用详细输出
--help	-h	显示帮助

依赖项

• gh CLI（必需）- GitHub 命令行工具
• gh-models 扩展（可选）- 启用 AI 功能

安装 gh-models

gh extension install github/gh-models

权限处理

级别	行为
WRITE/ADMIN	完整功能
TRIAGE	可以应用标签
READ	显示格式化内容以供手动复制
NONE	建议使用 fork 工作流

日志记录

日志路径：~/.claude/logs/gh-issue-create.jsonl

记录的事件：

• preflight - 初始检查
• type_detected - 内容类型检测
• labels_suggested - 标签建议
• related_found - 搜索相关 Issue
• issue_created - 成功创建
• dry_run - 试运行完成

相关文档

• 内容类型参考
• 标签策略参考
• AI 提示词参考

在 Issue 中嵌入图片

GitHub Issues 没有用于以编程方式上传图片的 API。Web UI 的拖放功能使用一种内部 S3 策略流程，该流程有意不向 API 客户端开放（cli/cli#1895）。

预检：确保图片可访问

?raw=true URL 通过 github.com 解析——如果远程仓库中该路径下不存在图片，它会静默返回 404（图片损坏，不会报错）。创建 Issue 前请运行此预检：

# 1. Detect repo context
OWNER_REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
BRANCH=$(git rev-parse --abbrev-ref HEAD)
VISIBILITY=$(gh repo view --json visibility -q '.visibility')

# 2. Verify images are git-tracked (not gitignored)
IMG_DIR="path/to/images"
for f in ${IMG_DIR}/*.png; do
  git ls-files --error-unmatch "$f" >/dev/null 2>&1 \
    || echo "WARNING: $f is NOT tracked by git (check .gitignore)"
done

# 3. Verify images are committed (not just staged or untracked)
UNCOMMITTED=$(git diff --name-only HEAD -- "${IMG_DIR}/" 2>/dev/null)
UNTRACKED=$(git ls-files --others --exclude-standard -- "${IMG_DIR}/" 2>/dev/null)
if [[ -n "$UNCOMMITTED" || -n "$UNTRACKED" ]]; then
  echo "FAIL: Images not committed — commit and push first"
  echo "  Uncommitted: ${UNCOMMITTED}"
  echo "  Untracked:   ${UNTRACKED}"
  exit 1
fi

# 4. Verify commit is pushed to remote (local commits invisible to github.com)
LOCAL_SHA=$(git rev-parse HEAD)
REMOTE_SHA=$(git rev-parse "origin/${BRANCH}" 2>/dev/null)
if [[ "$LOCAL_SHA" != "$REMOTE_SHA" ]]; then
  echo "FAIL: Local commits not pushed — run: git push origin ${BRANCH}"
  exit 1
fi

# 5. Build image base URL
IMG_BASE="https://github.com/${OWNER_REPO}/blob/${BRANCH}/${IMG_DIR}"
echo "Image base URL: ${IMG_BASE}/<filename>.png?raw=true"
echo "Repo visibility: ${VISIBILITY}"
if [[ "$VISIBILITY" == "PRIVATE" ]]; then
  echo "NOTE: Images only visible to authenticated collaborators"
fi

预检清单（各步骤的检查内容）：

步骤	检查	失败情形
1	仓库上下文存在	没有 OWNER_REPO 可用于构建 URL
2	图片由 Git 跟踪	.gitignore 会静默排除这些图片
3	图片已提交	已暂存/未跟踪的文件在远程仓库中不存在
4	提交已推送	仅在本地的提交对 github.com 不可见
5	URL 构造	分支名称错误 → 404

URL 格式：?raw=true 与 raw.githubusercontent.com

对于已提交并推送的图片，请使用 github.com/blob/...?raw=true URL——不要使用 raw.githubusercontent.com：

![img](https://raw.githubusercontent.com/owner/repo/main/path/image.png)



![img](https://github.com/owner/repo/blob/main/path/image.png?raw=true)

脚本模式（批量图片 → Issue 正文）：

IMG_BASE="https://github.com/${OWNER_REPO}/blob/${BRANCH}/${IMG_DIR}"

gh issue create --title "Feedback with screenshots" --body "$(cat <<EOF
## Item 1
![description](${IMG_BASE}/01-screenshot.png?raw=true)

## Item 2
![description](${IMG_BASE}/02-screenshot.png?raw=true)
EOF
)"

完整技术说明请参阅 GFM 反模式中的 AP-07。

不在仓库中的图片

对于仅存储在本地磁盘上的图片（未提交），有以下 4 种方法：

方法	操作	是否永久有效？	是否需要预检？
先提交并推送	git add 图片，推送，运行预检，然后使用 ?raw=true URL	是（由仓库托管）	是（5 步）
通过 Web UI 粘贴	在浏览器中打开 issue，将图片 Ctrl/Cmd+V 粘贴到评论框中	是（user-attachments CDN）	无
通过 Web UI 拖放	将图片文件拖到评论框中	是（user-attachments CDN）	无
使用 Playwright 自动化	通过脚本自动完成浏览器文件附件流程	是（user-attachments CDN）	无

Playwright 自动化（以编程方式上传到 CDN）

GitHub 没有图片上传 API，但可以通过 Playwright 自动完成浏览器文件附件流程，从而获取永久的 user-attachments CDN URL，无需提交/推送预检。

常规浏览器路径：chrome-profiles。

工作原理：

1. scripts/gh-issue-image-upload.ts 使用持久配置文件（~/.local/share/gh-issue-image-upload/profile，可通过 GH_ISSUE_IMAGE_PROFILE 覆盖）在 Playwright 的 Chromium 中打开 issue 页面。使用 bun "$(cc-plugin-root gh-tools)/skills/issue-create/scripts/gh-issue-image-upload.ts" <issue-url> <image>... 运行。
2. 仅首次运行时：用户登录 GitHub（任意方式均可，包括 Google SSO、通行密钥、密码）。Cookie 会持久保存。
3. 脚本点击“Paste, drop, or click to add files” → 拦截文件选择器 → 设置图片文件。
4. GitHub 将图片上传到其 S3 后端，并在评论文本框中插入带有 user-attachments CDN URL 的 <img> 标签。
5. 脚本提取 CDN URL 并清空文本框（实际上不会发布评论）。

关键实现细节（GitHub 2026 React 评论编辑器）：

• 评论文本框选择器：textarea[placeholder="Use Markdown to format your comment"]（React ID 是动态的——请勿按 id 匹配）
• 文件上传触发方式：点击“Paste, drop, or click to add files”文本，然后拦截 page.waitForEvent("filechooser")
• 上传结果格式：<img width="W" height="H" alt="Image" src="https://github.com/user-attachments/assets/UUID" />（HTML <img> 标签，而非 ![](...) Markdown）
• 旧的 textarea#new_comment_field 和 file-attachment input[type='file'] 选择器已不存在
• 批量上传：每次上传之间使用 textarea.fill("") 清空文本框

浏览器路径：这是 chrome-profiles 阶梯中的第 2 级（Playwright 自带的 Chromium，仅需登录一次），可与日常使用的 Chrome 隔离。如果 GitHub 已在日常使用的配置文件中登录，则可改用该插件的 setup <email> 来驱动浏览器；调试端口和 Chrome-136 机制的说明见该文档，此处不再赘述。

---

故障排查

“没有仓库上下文”

请在 git 目录中运行，或使用 --repo owner/repo 标志。

未提供标签建议

• 检查是否已安装 gh-models：gh extension list
• 确认仓库是否有标签：gh label list --repo owner/repo
• 检查标签缓存：ls ~/.cache/gh-issue-skill/labels/

AI 功能无法使用

安装 gh-models 扩展：

gh extension install github/gh-models

执行后反思

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

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

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