---
name: kanban-regression
description: Kanban 框架回归测试。使用实际代码任务验证 kanban-framework 的核心功能，覆盖 Quick/Lightweight/Full 三种模式、知识库（个人/共享）、Guard 校验、评分收集等关键路径。过程中记录框架 bug，测试完成后统一发布 GitHub issue。当用户提到"回归测试"、"跑kanban流程"、"验证框架"、"测试看板"、"kanban regression"时触发此 skill。
---

# Kanban 框架回归测试

通过实际编码任务驱动 kanban-framework 的完整流程，验证各模式、各阶段、各子系统是否正常工作。

## 前置条件

- 项目已执行过 `kanban init`
- `config.json` 中 `python_bin` 指向可用 venv
- kanban-framework 已安装最新版本（先运行 `pip install --upgrade kanban-framework` 或编辑模式 `pip install -e <skill-path>`）
- `venv/bin/kanban` CLI 可用

## 测试矩阵

按以下顺序执行，每个测试点使用**不同的实际编码任务**（不要重复同一任务）。

### Phase 1: 升级与准备

```
1. pip install --upgrade kanban-framework
2. kanban status  # 确认无残留活跃任务
3. kanban check-env  # 确认环境正常
4. 记录版本号（pip show kanban-framework | grep Version）
```

### Phase 2: Quick 模式

使用简单任务（如"为 X 添加常量定义"）验证 Quick 模式最短路径：

```
1. kanban create "简单任务标题" --json
2. 确认 mode（应为 quick）
3. kanban run <id>
4. 按 next-step 驱动 FSM：
   - execute.spawn → 实现代码 + 测试
   - execute.verify → kanban guard check-artifacts
   - execute.complete → complete-phase
   - user_decision → kanban decide --action approve_and_archive
5. 确认任务出现在 archive
```

**验证点：**
- [ ] 任务创建成功，mode 自动检测为 quick
- [ ] FSM 步骤按序推进，无跳步
- [ ] Guard check-artifacts 通过
- [ ] complete-phase 成功
- [ ] 归档成功，status 显示无活跃任务
- [ ] Git checkpoint 提交生成

### Phase 3: Lightweight 模式

使用中等复杂度任务（如"为 combat.py 添加新函数"）验证 Lightweight 模式：

```
1. kanban create "中等任务标题" --json
2. 确认 mode（应为 lightweight）
3. kanban run <id>
4. 按 next-step 驱动：
   - plan.knowledge_search → 知识库检索
   - plan.plan_A → 需求澄清（interactive）
   - execute.spawn → TDD 实现
   - execute.verify → guard 检查
   - evaluate.spawn → 评审报告（注意：需要顶层 total 字段）
   - evaluate.collect_scores → 分数同步
   - evaluate.check_score → self-improve-check
   - evaluate.complete → complete-phase
   - user_decision → approve_and_archive
```

**验证点：**
- [ ] plan 阶段产出 spec.md, task_breakdown.json, knowledge_used.json
- [ ] 知识库检索返回结果（或正确报告无匹配）
- [ ] TDD 循环：测试先写 → 代码实现 → 全部通过
- [ ] Guard check-artifacts 检查 TDD 表格式
- [ ] 评审报告 JSON 需包含**顶层 total 字段**（否则 _collect_scores 读不到）
- [ ] score_history 正确写入 task.json
- [ ] 归档成功

### Phase 4: Full 模式

使用复杂任务（如"实现完整的新模块"）验证 Full 模式完整阶段链：

```
1. kanban create "复杂任务标题" --mode full --json
2. 阶段链：Plan → Plan Review → QA Spec → Spec Review → Execute → Evaluate → Self-Improve → Retrospective → User Decision → Archive
3. 每个阶段严格按 next-step 驱动，不跳步
```

**验证点：**
- [ ] Plan Review 阶段产出评审报告
- [ ] QA Spec 阶段产出 test_spec.md
- [ ] Spec Review 阶段产出评审报告
- [ ] Execute 阶段：pitfall_check → tech_review → spawn → verify → commit → complete
- [ ] Evaluate 阶段分数收集链路完整（评审报告 → _record_score → score_history → self-improve-check）
- [ ] Retrospective 阶段：retrospective.md + acceptance.md + knowledge_extracted.json
- [ ] 知识自动导入（complete-phase retrospective 时触发）
- [ ] 全阶段 checkpoint 提交

### Phase 5: 知识库测试

#### 5.1 个人知识库

```
1. kanban knowledge add --domain test --category 踩坑 --severity high --title "测试条目1" --content "内容1" --source '{"type":"test"}'
2. kanban knowledge list --json  # 确认条目存在（注意：--json 可能返回空，已知 #380）
3. kanban knowledge list  # 非 JSON 模式验证
4. kanban knowledge search "测试条目" --json  # 验证搜索
5. kanban knowledge hybrid "测试" --json  # 验证混合搜索
6. kanban knowledge match "关键词" --json  # 验证 FTS5（注意：可能返回空，已知 #383）
7. kanban knowledge get <id>  # 验证详情读取
8. kanban knowledge get <id> --json  # 验证 JSON 输出
9. kanban knowledge backup  # 验证备份（注意 -shm/-wal 残留问题 #364）
10. kanban knowledge delete <id>  # 验证删除
```

#### 5.2 共享知识库

```
1. kanban knowledge share --init /tmp/kb_share.db  # 初始化共享 KB（需要路径参数）
2. kanban knowledge share --status  # 查看状态
3. kanban knowledge share --push --all --domain game  # 按 domain 推送
4. kanban knowledge share --push --all --dry-run  # 预览推送
5. kanban knowledge share --list  # 查看共享内容
```

**验证点：**
- [ ] CRUD 操作正常（add/get/list/delete）
- [ ] 去重正常（同 title+domain 自动 skip）
- [ ] 搜索：keyword/semantic/hybrid/intent 四种模式
- [ ] 中文搜索正常（jieba 分词生效）
- [ ] scope 隔离：不同 scope 的条目互不干扰，独立 DB 文件
- [ ] 备份功能正常（注意清理旧 -shm/-wal 文件）
- [ ] 共享 KB init/push/list/status 正常
- [ ] Tags JSON 解析正常（`--tags '["a","b"]'`）
- [ ] import 支持 JSON 数组（单条对象可能失败，已知 #385）
- [ ] teach 创建教程条目正常
- [ ] health 健康检查正常
- [ ] categories 列出标准分类
- [ ] GET --json 结构为 data.entry（非 data 直接）

#### 5.3 知识库在任务流程中的持续积累

验证知识库在 FSM 各阶段的自动积累链路：

```
1. 创建 Full 模式任务，记录当前知识库条目数和 default001 的 referenced_count
2. Plan 阶段：
   - kanban knowledge hybrid 搜索任务相关内容
   - 写入 knowledge_used.json，记录引用的条目 ID
   - 验证 spawn_prompt 中 knowledge_hints 推荐了相关条目
3. Execute 阶段：
   - spawn_prompt 指示发现通用模式时用 kanban knowledge add 实时写入
   - 验证新增条目出现在知识库中
4. Retrospective 阶段：
   - 产出 knowledge_extracted.json
   - complete-phase 时验证自动导入（输出 knowledge_imported: N）
   - 验证新条目出现在 knowledge list 中
5. 归档后：
   - 验证 default001 的 referenced_count 递增
   - 验证 last_referenced_by 为当前任务 ID
```

**验证点：**
- [ ] Plan 阶段知识检索正常触发并返回相关结果
- [ ] knowledge_used.json 正确记录引用的条目 ID
- [ ] Execute 阶段可实时写入知识条目
- [ ] Retrospective 阶段产出 knowledge_extracted.json
- [ ] complete-phase 触发自动导入，输出 knowledge_imported: N
- [ ] 归档后 default001 的 referenced_count 递增
- [ ] last_referenced_by 更新为当前任务 ID

### Phase 6: Guard 系统

```
1. 故意缺失产物 → kanban guard check-artifacts <task_id> <phase>  # 应报告缺失
2. 补全产物 → 再次检查应 passed: True
3. 分数低于阈值 → complete-phase 应报 GuardError
4. 分数达标 → complete-phase 应成功
```

### Phase 7: 已知 Issue 回归

检查之前提过的 issue 是否已修复（参考下面的 issue 清单）。

## 框架问题记录规范

测试过程中发现的框架问题记录到 `$TASK_DIR/regression_issues.json`：

```json
{
  "test_run": "v0.XX.X",
  "date": "YYYY-MM-DD",
  "issues": [
    {
      "id": null,
      "title": "简短描述",
      "severity": "high/medium/low",
      "phase": "出问题的阶段",
      "description": "详细描述",
      "reproduce_steps": ["步骤1", "步骤2"],
      "workaround": "临时解决方案（如有）",
      "source_code": {
        "file": "相关源码路径",
        "line": 行号,
        "function": "函数名"
      }
    }
  ]
}
```

**记录时机：** 遇到异常立即记录，不要等到最后。包括但不限于：
- FSM 步骤报错或状态不一致
- CLI 命令参数解析错误
- Guard 误报或漏报
- 分数收集失败
- 知识库操作异常
- 文件路径/格式问题

## GitHub Issue 发布

所有测试完成后，将 `regression_issues.json` 中的问题逐一发布到 GitHub：

```bash
cd <kanban-framework-repo-path>
for each issue:
  gh issue create \
    --title "<title>" \
    --body "$(cat <<EOF
## 问题描述
<description>

## 复现步骤
<reproduce_steps>

## 版本
<version>

## 严重程度
<severity>
EOF
)"
```

**仓库路径获取：** `pip show kanban-framework` 的 `Location` 字段向上查找 git repo，或直接使用 `~/.claude/skills/kanban/`。

## 已知 Issue 清单

Issue 按回归测试日期记录在独立 md 文件中，方便直接复制粘贴到 GitHub。文件存放在 kanban-framework 仓库的 `docs/regression-issues/` 目录下，按日期命名：

```
docs/regression-issues/
├── 2026-05-15.md    # v0.60.0 回归发现的 #354-#369
├── 2026-05-20.md    # v0.61.0 回归发现的 #370-#376
├── 2026-05-27.md    # v0.61.3 回归发现的 #378-#386
└── ...
```

每个文件格式（直接可作为 GitHub issue body）：

```markdown
## #354 task_breakdown.json 路径查找缺失 plan/ 子目录

**严重程度**: medium | **阶段**: execute | **状态**: ✅ 已修复 v0.60.0

### 描述
...

### 复现步骤
1. ...
2. ...

---

## #355 score key 不一致 (total_score vs total)

**严重程度**: high | **阶段**: evaluate | **状态**: ✅ 已修复 v0.60.0

### 描述
...

---

（每个 issue 用 `---` 分隔，方便整块复制粘贴）
```

### 新发现 Issue 记录流程

1. 当天日期创建/追加文件：`docs/regression-issues/YYYY-MM-DD.md`
2. 每个 issue 用 `---` 分隔，包含标题、严重程度、阶段、描述、复现步骤
3. 复制粘贴对应 section 到 `gh issue create` 即可

## 关键注意事项

1. **评审报告格式**：review report JSON 必须包含**顶层 `total` 字段**（`{"total": 9.0, "scores": {...}}`），否则 `_collect_scores` 读到 0（v0.60.2 后已修复，但建议保留顶层 total 作为兼容）。

2. **score_history key**：使用 `"average"` 而非 `"avg"` 作为 score_history entry 的 key（#371，v0.60.2 已修复）。

3. **FSM 状态恢复**：每次执行步骤前先调用 `kanban workflow next-step <id>`，不要凭记忆判断当前阶段。

4. **TDD 表格格式**：execution_summary.md 中的 TDD 表必须使用 `## TDD 执行证据` 标题和 `| 功能点 | 测试文件 | RED (Fail) | GREEN (Pass) | 备注 |` 格式。

5. **Git 操作**：不使用 `--no-verify`、`--force`、`git reset --hard` 等破坏性命令。

6. **测试任务选择**：每个模式使用不同的编码任务，避免代码冲突。推荐使用 src/rpg/ 目录下的函数添加任务。

7. **知识库备份**：备份前手动删除 `knowledge.db-shm` 和 `knowledge.db-wal` 文件，避免 #364 WAL/SHM 崩溃。

8. **knowledge list --json**：已知 #380 返回空结果，用非 JSON 模式 `kanban knowledge list` 替代验证。

9. **knowledge match**：已知 #383 FTS5 match 查询全部返回 0，用 `search` 或 `hybrid` 替代验证。

10. **unittest.assertRaises**：Python 3.10 及以下不支持 `match` 关键字参数，测试中避免使用。

## 输出

测试完成后产出：

1. **测试报告**：写到 `.kanban/reports/regression_v<version>_<date>.md`，包含各模式测试结果
2. **Issue 清单**：`regression_issues.json` 记录发现的问题
3. **GitHub Issues**：将新发现的问题发布到 `kongshan001/kanban-framework` 仓库