Add Issue

把用户反馈、终端输出、本地诊断或改进想法整理成可执行的 GitHub issue。目标是减少重复 issue，保留足够复现信息，并避免泄露 token、路径、账号或机器本地细节。

这份流程改写自 osgood001/armchair 的 docs/send-issue.md，适配 claude-zh.cn 的 VitePress 站点、安装脚本、Cloudflare Functions 和部署流程。

目标状态

重复问题追加到已有 issue，而不是新开重复 issue。
新 issue 有清晰标题、复现步骤、实际行为、期望行为和环境信息。
使用仓库已有 labels，不临时发明 label。
milestone 没有合适项时留空或询问 owner。
所有敏感信息都已清理。

1. 收集报告

先把反馈压缩成最小可执行问题：

用户做了什么。
实际发生了什么。
用户期望发生什么。
相关命令、输出、截图文字、系统、shell、Node/npm 版本。
影响范围属于哪一层：站点内容、安装脚本、Windows/WSL、下载资源、Cloudflare Function、telemetry、CI/CD 或部署。

发到 GitHub 前必须删掉：

API key、token、cookie、SSH key、Cloudflare secret。
邮箱、用户名、支付信息、客户数据，除非 owner 明确要求保留且有脱敏方式。
不影响排障的本机私有路径。
大段无关日志。

2. 搜索重复 issue

先搜索打开中的 issue：

gh issue list --state open --search "<main error text or feature topic>" --json number,title,url,labels,milestone --limit 20

如果关键词太宽，再用子系统补搜一次：

gh issue list --state open --search "<subsystem> <symptom>" --json number,title,url,labels,milestone --limit 20

常见子系统关键词：

install.sh
install.ps1
wsl
windows
node
telemetry
cloudflare function
vitepress
deploy

然后二选一：

路径	使用场景	动作
Append	已有 issue 覆盖同一失败模式、同一用户可见症状或同一需求。	在已有 issue 下补充新证据。
New issue	没有打开中的 issue 覆盖，或这次反馈有不同 root cause、平台、影响范围。	新建 issue。

不确定时，优先评论到看起来相关的 issue，并说明“可能相关”，不要制造重复 issue。

3. 选择 label 和 milestone

查看现有 labels：

gh label list --limit 100

当前仓库常用 label：

bug：功能不工作、安装失败、部署异常。
documentation：教程、页面、导航、文案。
enhancement：新能力或体验改进。
question：信息不足，需要用户补充。
duplicate、invalid、wontfix：只在确认后使用。
help wanted、good first issue：适合留给贡献者时使用。

查看 milestone：

gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)"'

如果没有 milestone 或没有合适 milestone，不要强行设置；需要排期时问 owner。

4. 追加到已有 issue

重复或相关报告用 comment：

gh issue comment <issue-number> --body "$(cat <<'EOF'
Additional report:

## Reproduction
1. ...

## Actual behavior
...

## Expected behavior
...

## Environment
- OS:
- Shell:
- Node:
- npm:

## Notes
Secrets, tokens, and unrelated machine-local details have been redacted.
EOF
)"

如果已有 issue 明显缺 label，可以补现有 label：

gh issue edit <issue-number> --add-label "bug"

不要在没有把握时批量改 milestone 或关闭 issue。

5. 新建 issue

标题写用户可见症状，不写内部猜测：

好：install.sh fails when Node is missing on WSL
好：Windows installer reports success after Git download failure
避免：fix telemetry bug

创建 issue：

gh issue create \
  --title "<short user-visible symptom>" \
  --label "<label-1>,<label-2>" \
  --body "$(cat <<'EOF'
## Summary
...

## Steps to reproduce
1. ...

## Actual behavior
...

## Expected behavior
...

## Environment
- OS:
- Shell:
- Node:
- npm:

## Affected area
- install.sh / install.ps1 / docs / functions / telemetry / deploy

## Notes
Secrets, tokens, and unrelated machine-local details have been redacted.
EOF
)"

如果有明确 milestone，再加 --milestone "<milestone>"。创建后验证 metadata：

gh issue view <issue-number> --json number,title,url,labels,milestone

6. 和开发流程衔接

新 issue 创建后，如果用户要求继续修复，切到 skill/issue-to-pr.md：

gh issue view <issue-number> --json number,title,state,body,url,labels,comments

如果 issue 涉及新增功能、安装路径、运行时行为或失败处理，后续 PR 必须按 skill/add-telemetry.md 显式说明 telemetry 决策。

Checklist

[ ] 已删除 secret、token、cookie、SSH key 和不必要的本机路径。
[ ] 已搜索重复或相关 open issue。
[ ] 重复问题已追加到已有 issue。
[ ] 只有在没有覆盖项时才新建 issue。
[ ] 已使用仓库已有 label。
[ ] milestone 没有合适项时已留空或询问 owner。
[ ] issue 包含复现步骤、实际行为、期望行为和环境信息。
[ ] issue 影响范围已标清，方便后续走 skill/issue-to-pr.md。

Add Issue ​

目标状态 ​

1. 收集报告 ​

2. 搜索重复 issue ​

3. 选择 label 和 milestone ​

4. 追加到已有 issue ​

5. 新建 issue ​

6. 和开发流程衔接 ​

Checklist ​