议题管理 Issue Manager

目标

将代码审查发现的问题转化为可追踪的 GitHub Issues，并协助修复和管理这些问题。

核心功能

1. 从审查报告创建 Issues

• 读取 code-audit 生成的审查报告
• 将问题按严重程度分类
• 为每个问题创建结构化的 GitHub Issue
• 自动添加合适的标签（bug, enhancement, documentation, tech-debt）
• 设置优先级和里程碑

2. 讨论和分析 Issues

• 深入分析特定 issue 的根本原因
• 提供多种解决方案及其权衡
• 估算修复的影响范围
• 生成修复计划

3. 批量修复 Issues

• 选择一个或多个相关 issues 进行修复
• 自动创建修复分支
• 实施修复
• 运行测试验证
• 创建 Pull Request

使用方式

方式 1: 从审查报告创建议题

请用 /issue-manager 从最新的代码审查报告创建 issues

方式 2: 讨论特定问题

请用 /issue-manager 讨论 issue #42 的解决方案

方式 3: 修复单个问题

请用 /issue-manager 修复 issue #42

方式 4: 批量修复相关问题

请用 /issue-manager 修复所有组件一致性相关的 issues

方式 5: 查看问题状态

请用 /issue-manager 查看所有待修复的代码质量问题

工作流程

流程 1: 创建 Issues

当用户请求从审查报告创建 issues 时：

步骤 1: 确认创建

必须先获得用户明确同意，使用 AskUserQuestion 询问：

• 是否要创建 issues？
• 创建哪个严重级别的问题？（严重/中等/低优先级/全部）
• 是否要添加特定标签或里程碑？

步骤 2: 读取审查报告

• 查找最近的审查报告（或用户指定的报告）
• 解析问题列表

步骤 3: 检查重复议题

重要：创建前必须先查重，避免重复创建

使用 gh issue list 搜索已有的相似议题：

# 搜索标题中包含关键词的议题
gh issue list --search "投放状态" --state all --json number,title,state

# 搜索特定标签的议题
gh issue list --label "tech-debt,code-quality" --json number,title,body

对于每个待创建的问题：

1. 提取关键词（如"投放状态"、"重复代码"、"组件一致性"）
2. 搜索已有 issues 的标题和内容
3. 如果找到相似的议题，询问用户：
   • 是否要在已有 issue 中补充信息？
   • 还是仍然创建新 issue？
4. 如果是重复议题，跳过创建，在已有 issue 中添加评论补充信息

示例输出：

⚠️ 发现可能重复的议题：

待创建: "大量重复的投放状态检查逻辑"
已存在: #85 "投放状态验证逻辑需要统一" (open)

是否要：
1. 在 #85 中补充新发现的重复代码位置
2. 仍然创建新 issue（如果确实是不同的问题）

步骤 4: 为每个问题创建 Issue

使用 gh issue create 创建结构化的 issue：

gh issue create \
  --title "🔴 [严重] 大量重复的投放状态检查逻辑" \
  --body "$(cat <<'EOF'
## 📍 位置
`actions/delivery.ts:145-180`

## ❌ 问题描述
大量重复的投放状态检查逻辑分散在不同函数中，导致维护困难，容易出现不一致。

## 💥 影响
- 代码维护困难
- 容易出现逻辑不一致的 bug
- 修改时需要同步多处代码

## ✅ 建议方案
抽离到统一的工具函数 `lib/utils/delivery-status.ts`

```typescript
// 建议创建
export function validateDeliveryStatus(status: DeliveryStatus) {
  // 统一的状态验证逻辑
}

📋 验收标准

• 创建 lib/utils/delivery-status.ts
• 实现统一的状态验证函数
• 重构所有调用点使用新函数
• 添加单元测试
• 验证所有功能正常

🔗 相关文件

• actions/delivery.ts
• 其他调用投放状态检查的文件

---

由 code-audit 自动生成 EOF )"
--label "tech-debt,priority-high,code-quality"
--assignee "@me"

#### 步骤 5: 生成总结报告
创建完成后，输出 Markdown 报告：

```markdown
# ✅ Issues 创建完成

共创建 **12 个 issues**：

## 🔴 严重问题 (3 个)
- #123 - [严重] 大量重复的投放状态检查逻辑
- #124 - [严重] 组件中的业务逻辑应移至 Server Actions
- #125 - [严重] 'use client' 滥用导致 bundle 过大

## 🟡 中等问题 (6 个)
- #126 - [中等] 函数过长需要拆分
- #127 - [中等] 组件一致性问题
- #128 - [中等] 无效代码清理
- ...

## 🟢 低优先级 (3 个)
- #129 - [低] 依赖更新
- #130 - [低] 添加 Prettier
- ...

## 📊 标签分布
- `tech-debt`: 8 个
- `bug`: 2 个
- `enhancement`: 2 个
- `documentation`: 1 个

## 🔗 查看所有 issues
https://github.com/your-repo/issues?q=is:issue+is:open+label:code-quality

流程 2: 讨论 Issue

当用户请求讨论某个 issue 时：

步骤 1: 获取 Issue 详情

gh issue view 42 --json title,body,labels

步骤 2: 分析问题

• 读取相关文件
• 理解问题的上下文
• 分析根本原因

步骤 3: 提供解决方案

生成详细的讨论报告：

# 🔍 Issue #42 深度分析

## 问题回顾
[问题描述]

## 🎯 根本原因
经过分析，这个问题的根本原因是...

## 💡 解决方案

### 方案 1: 抽离公共函数（推荐）
**优点**:
- 易于维护
- 可复用
- 测试简单

**缺点**:
- 需要重构多处调用点

**实施步骤**:
1. 创建 `lib/utils/delivery-status.ts`
2. 实现统一的验证函数
3. ...

**预计工作量**: 2-3 小时

### 方案 2: 使用装饰器模式
**优点**:
- ...

**缺点**:
- ...

## 🔗 影响范围
需要修改的文件：
- `actions/delivery.ts` (3 处)
- `actions/campaign.ts` (2 处)
- ...

## ⚠️ 风险评估
- **风险等级**: 低
- **回归风险**: 需要充分测试投放流程
- **建议**: 在测试环境充分验证后再部署

## 🗳️ 建议
推荐使用方案 1，理由是...

步骤 4: 等待用户决策

使用 AskUserQuestion 询问用户：

• 选择哪个方案？
• 是否立即开始修复？

流程 3: 修复 Issue

当用户请求修复 issue 时：

步骤 1: 分析问题并制定修复方案

• 获取 issue 详情
• 读取相关文件了解上下文
• 制定详细的修复方案

步骤 2: 在 Issue 评论区说明修复方案并等待确认

重要：在实际修复前，必须先在 issue 评论区说明方案，等待用户确认

使用 gh issue comment 发布修复方案：

gh issue comment 42 --body "$(cat <<'EOF'
## 🤖 AI 修复方案

我已分析了这个问题，建议采用以下方案进行修复：

### 📋 修复计划

**问题**: 大量重复的投放状态检查逻辑

**方案**: 抽离到统一的工具函数

**具体步骤**:
1. 创建 `lib/utils/delivery-status.ts`
2. 实现统一的 `validateDeliveryStatus` 函数
3. 重构以下文件使用新函数：
   - `actions/delivery.ts` (3 处调用)
   - `actions/campaign.ts` (2 处调用)
   - `app/api/delivery/route.ts` (1 处调用)

**预期效果**:
- ✅ 删除约 45 行重复代码
- ✅ 提高代码可维护性
- ✅ 统一状态验证逻辑

**影响范围**:
- 修改 3 个文件
- 不影响现有功能
- 无破坏性变更

**验证方式**:
- 运行 `pnpm tsc --noEmit` 确保类型正确
- 运行 `pnpm build` 确保构建成功
- 测试投放相关功能

### ⚠️ 风险评估
- **风险等级**: 低
- **建议**: 修复后需测试投放流程

---

**是否同意此修复方案？**

如果同意，请在评论中回复：
- 自然语言："修"、"同意"、"开始修复"（AI 会自动理解）
- 明确指令：`/confirm-fix` 或 `/approve`（快捷通道）

我将自动开始修复。如果需要调整，请说明具体要求。
EOF
)"

然后等待用户回复或确认：

• 用户回复"同意"或类似内容
• 或用户添加 fix-approved 标签
• 或用户在对话中明确表示同意

步骤 3: 确认修复范围

获得用户初步同意后，使用 AskUserQuestion 再次确认细节：

• 是否需要创建新分支？
• 是否需要添加测试？
• 是否立即推送 PR？

步骤 4: 创建修复分支（如果需要）

git checkout -b fix/issue-42-delivery-status-duplication

步骤 5: 实施修复

• 根据讨论的方案进行代码修改
• 使用 Edit/Write 工具修改文件
• 添加必要的测试

步骤 6: 验证修复

# 运行类型检查
pnpm tsc --noEmit

# 运行测试（如果有）
pnpm test

# 运行构建
pnpm build

步骤 7: 提交和关联 Issue

git add .
git commit -m "$(cat <<'EOF'
fix: 抽离投放状态验证逻辑到公共函数

- 创建 lib/utils/delivery-status.ts
- 实现统一的 validateDeliveryStatus 函数
- 重构 actions/delivery.ts 使用新函数
- 重构 actions/campaign.ts 使用新函数

Fixes #42

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
EOF
)"

步骤 8: 报告修复结果

# ✅ Issue #42 修复完成

## 📝 修复内容
- 创建了 `lib/utils/delivery-status.ts`
- 实现了统一的状态验证函数
- 重构了 3 个文件的调用点

## ✅ 验证结果
- TypeScript 类型检查: ✅ 通过
- 构建: ✅ 成功
- 测试: ✅ 通过（如果有）

## 📊 代码变更
- 新增文件: 1
- 修改文件: 3
- 删除重复代码: ~45 行

## 🔗 下一步
是否要：
1. 推送到远程并创建 PR？
2. 继续修复相关的 issue #43？
3. 运行 code-audit 验证修复效果？

流程 4: 批量修复

当用户请求批量修复时：

步骤 1: 查找相关 Issues

gh issue list --label "组件一致性" --json number,title

步骤 2: 展示并确认

使用 AskUserQuestion 让用户选择要修复的 issues

步骤 3: 逐个修复

按照"流程 3"的步骤依次修复每个 issue

步骤 4: 生成批量修复报告

Issue 模板

严重问题模板

标题: 🔴 [严重] {问题简述}
标签: priority-high, tech-debt, code-quality

中等问题模板

标题: 🟡 [中等] {问题简述}
标签: priority-medium, tech-debt, code-quality

低优先级模板

标题: 🟢 [低] {问题简述}
标签: priority-low, enhancement

组件一致性问题

标签: ui-consistency, tech-debt

无效代码清理

标签: cleanup, tech-debt

文档缺失

标签: documentation

性能优化

标签: performance, enhancement

智能功能

1. 自动分类

根据问题类型自动添加合适的标签：

• 代码重复 → tech-debt, refactoring
• 组件一致性 → ui-consistency, tech-debt
• 性能问题 → performance, enhancement
• 文档缺失 → documentation
• 类型安全 → type-safety, bug
• 无效代码 → cleanup, tech-debt

2. 关联相关 Issues

创建时自动检测相关的 issues，在 body 中添加：

## 🔗 相关 Issues
- #123 - 类似的重复代码问题
- #124 - 同一文件的其他问题

3. 优先级推荐

根据问题的影响范围和严重程度推荐优先级

4. 里程碑建议

根据问题类型建议合适的里程碑（如 "代码质量提升 Q1"）

查询和统计

查看待修复问题

gh issue list --label "code-quality" --state open

统计问题分布

gh issue list --label "tech-debt" --json labels --jq '.[].labels[].name' | sort | uniq -c

查看某个标签的所有问题

gh issue list --label "组件一致性"

特殊场景处理

场景 1: 没有 Git 仓库

如果项目不是 Git 仓库或没有配置 GitHub，改为：

1. 创建本地 TODO 文件 .claude/issues/TODO.md
2. 以 Markdown 格式记录问题
3. 提示用户后续可手动创建 issues

场景 2: 依赖问题

如果 gh CLI 未安装，提示用户：

# macOS
brew install gh

# 认证
gh auth login

场景 3: 用户取消

如果用户不同意创建 issues，提供其他选项：

• 导出为 Markdown 文件
• 导出为 CSV 文件
• 仅显示问题清单

输出格式

创建 Issue 时的输出

每创建一个 issue，显示进度：

✅ [1/12] 创建 Issue #123: 大量重复的投放状态检查逻辑
✅ [2/12] 创建 Issue #124: 组件中的业务逻辑应移至 Server Actions
...

修复 Issue 时的输出

显示清晰的步骤进度：

🔧 开始修复 Issue #42

[1/5] 📖 读取相关文件...
[2/5] ✏️ 创建 lib/utils/delivery-status.ts...
[3/5] ♻️ 重构 actions/delivery.ts...
[4/5] ✅ 运行验证...
[5/5] 💾 提交更改...

✅ 修复完成！

最佳实践

1. 始终获得用户同意再创建 issues
2. 提供详细的上下文在 issue body 中
3. 添加验收标准让 issue 可执行
4. 关联相关文件和代码位置方便定位
5. 一次只修复一个问题避免改动过大
6. 修复后运行验证确保没有引入新问题
7. 使用语义化的 commit message
8. 在 commit 中关联 issue（使用 Fixes #42）

与 code-audit 的协作

issue-manager 是 code-audit 的完美补充：

code-audit (发现问题)
    ↓
issue-manager (创建追踪)
    ↓
issue-manager (讨论方案)
    ↓
issue-manager (实施修复)
    ↓
code-audit (验证效果)

GitHub Actions 自动化

issue-manager 包含多个 GitHub Actions 工作流，实现全自动的 issue 管理：

已部署的工作流

详细文档请查看 workflows/README.md

1. claude-code-pr-review.yml - PR 代码审查

   • 使用 /code-audit 自动审查每个 PR
   • 检查 Next.js 最佳实践、代码重复等

2. claude-code-issue-triage.yml - Issue 自动分诊

   • 新 issue 打开时自动分析
   • 建议分类、优先级和标签

3. claude-code-auto-fix.yml - 两阶段自动修复

   • 阶段 1：AI 提出修复方案
   • 阶段 2：用户确认后执行修复
   • 自动创建修复 PR

4. claude-code-issue-chat.yml - Issue 对话

   • AI 自动回复 issue 中的评论
   • 支持多轮对话和代码查看

5. claude-code-confirm-fix.yml - 确认修复指令

   • 快速响应明确的确认指令（/confirm-fix、/approve）
   • 自动添加 fix-confirmed 标签触发修复
   • 自然语言确认由 issue-chat 智能处理

用户体验优化

通过评论指令确认修复方案，支持两种方式：

方式 1：自然语言（推荐）

1. AI 提出修复方案（发布在 issue 评论中）
2. 用户直接评论："修"、"同意"、"开始修复"等
3. issue-chat 工作流识别意图，检查标签，添加 fix-confirmed
4. 触发修复工作流执行修复
5. 创建草稿 PR

方式 2：明确指令（快捷通道）

1. 用户评论 /confirm-fix 或 /approve
2. confirm-fix 工作流快速添加 fix-confirmed 标签
3. 触发修复工作流

生成工作流文件

使用以下命令生成 GitHub Actions 工作流：

请用 /issue-manager 生成 GitHub Actions 工作流

这将在 .github/workflows/ 目录下创建以下文件：

1. code-audit-pr.yml - PR 代码审查

   • 每次 PR 时自动运行代码质量检查
   • 在 PR 中发布审查评论
   • 严重问题自动创建 issue

2. weekly-audit.yml - 每周质量扫描

   • 每周一自动扫描代码库
   • 生成质量报告 issue
   • 统计代码指标和趋势
   • 自动创建改进建议 issue

3. auto-fix.yml - 自动修复

   • 对标记 auto-fix 的 issue 自动修复
   • 自动创建修复 PR
   • 支持批量修复简单问题

工作流详解

1. PR 代码审查工作流

触发时机：

• 创建 PR
• PR 更新
• 手动触发

自动检查：

• TypeScript 类型错误
• 未使用的导入
• Console 调试语句
• TODO/FIXME 标记
• 文件大小

输出：

• PR 评论中的审查报告
• 严重问题自动创建 issue
• 上传审查报告为 artifact

2. 每周质量扫描

触发时机：

• 每周一早上 9:00 (UTC)
• 手动触发

统计指标：

• 代码库规模（文件数、行数）
• 质量指标（TODO、console、any 类型）
• 依赖更新状态
• 构建状态

自动化：

• 创建每周报告 issue
• console 过多时自动创建清理 issue
• 趋势分析和建议

3. 自动修复工作流

触发时机：

• issue 被标记为 auto-fix
• 手动指定 issue 编号

支持修复：

• 移除 console.log 调试语句
• 修复导入语句排序
• 代码格式化（通过 ESLint）

流程：

1. 创建修复分支 auto-fix/issue-{number}
2. 应用自动修复
3. 提交更改
4. 创建 PR 并关联原 issue
5. 在 issue 中评论 PR 链接

如何使用

启用 PR 审查

1. 将工作流文件复制到 .github/workflows/
2. 每次创建 PR 时自动运行
3. 在 PR 评论中查看审查结果

启用每周扫描

1. 工作流会在每周一自动运行
2. 在 Issues 中查看每周报告
3. 根据建议采取行动

使用自动修复

1. 对于简单问题，添加 auto-fix 标签
2. GitHub Actions 自动创建修复 PR
3. Review 并合并 PR

示例：

# 创建一个需要清理 console 的 issue
gh issue create \
  --title "清理 console.log 语句" \
  --label "auto-fix,cleanup" \
  --body "自动移除调试用的 console 语句"

# GitHub Actions 会自动：
# 1. 检测到 auto-fix 标签
# 2. 创建修复分支
# 3. 移除 console.log
# 4. 创建 PR

工作流模板位置

所有工作流模板保存在： .claude/skills/issue-manager/workflows/

使用 issue-manager 时可以一键复制到项目的 .github/workflows/ 目录。

最佳实践

1. 逐步启用：先启用 PR 审查，稳定后再启用其他工作流
2. 调整阈值：根据项目实际情况调整触发条件（如文件行数限制）
3. Review 自动修复：自动修复的 PR 仍需人工 review
4. 定期查看报告：关注每周报告中的趋势变化
5. 及时处理 issue：不要让自动创建的 issue 积压太多

注意事项

• 创建 issues 前必须征得用户同意
• 修复代码时要充分测试
• 批量修复时注意不要一次改动过多
• 对于复杂的修复，先创建 PR 让团队 review
• 保持 issue 描述的清晰和可执行
• 定期回顾和关闭已解决的 issues
• GitHub Actions 工作流需要适当的权限配置
• 自动修复仅适用于简单的代码质量问题