议题管理 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

对于每个待创建的问题：

提取关键词（如"投放状态"、"重复代码"、"组件一致性"）
搜索已有 issues 的标题和内容
如果找到相似的议题，询问用户：
- 是否要在已有 issue 中补充信息？
- 还是仍然创建新 issue？
如果是重复议题，跳过创建，在已有 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，改为：

创建本地 TODO 文件 .claude/issues/TODO.md
以 Markdown 格式记录问题
提示用户后续可手动创建 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] 💾 提交更改...

✅ 修复完成！

最佳实践

始终获得用户同意再创建 issues
提供详细的上下文在 issue body 中
添加验收标准让 issue 可执行
关联相关文件和代码位置方便定位
一次只修复一个问题避免改动过大
修复后运行验证确保没有引入新问题
使用语义化的 commit message
在 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

claude-code-pr-review.yml - PR 代码审查
- 使用 /code-audit 自动审查每个 PR
- 检查 Next.js 最佳实践、代码重复等
claude-code-issue-triage.yml - Issue 自动分诊
- 新 issue 打开时自动分析
- 建议分类、优先级和标签
claude-code-auto-fix.yml - 两阶段自动修复
- 阶段 1：AI 提出修复方案
- 阶段 2：用户确认后执行修复
- 自动创建修复 PR
claude-code-issue-chat.yml - Issue 对话
- AI 自动回复 issue 中的评论
- 支持多轮对话和代码查看
claude-code-confirm-fix.yml - 确认修复指令
- 快速响应明确的确认指令（/confirm-fix、/approve）
- 自动添加 fix-confirmed 标签触发修复
- 自然语言确认由 issue-chat 智能处理

用户体验优化

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

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

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

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

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

生成工作流文件

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

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

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

code-audit-pr.yml - PR 代码审查
- 每次 PR 时自动运行代码质量检查
- 在 PR 中发布审查评论
- 严重问题自动创建 issue
weekly-audit.yml - 每周质量扫描
- 每周一自动扫描代码库
- 生成质量报告 issue
- 统计代码指标和趋势
- 自动创建改进建议 issue
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）

流程：

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

如何使用

启用 PR 审查

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

启用每周扫描

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

使用自动修复

对于简单问题，添加 auto-fix 标签
GitHub Actions 自动创建修复 PR
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/ 目录。

最佳实践

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

注意事项

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