# gitlink-code-review Skill 测试指南

## 📋 测试概述

本文档提供完整的测试指南，帮助你验证 gitlink-code-review Skill 的功能完整性、AI Agent 集成和实际可用性。

## 🎯 测试目标

1. **功能验证**: 确保所有功能按预期工作
2. **AI 集成测试**: 验证 AI Agent 可以正确使用此 Skill
3. **文档验证**: 确保文档完整且易于理解
4. **实用验证**: 确保在实际场景中可用

## 🔧 前置条件

### 1. 环境准备

```bash
# 确认 gitlink-cli 已安装
gitlink-cli --version

# 确认已认证
gitlink-cli auth status

# 如果未认证，执行登录
gitlink-cli auth login
```

### 2. 准备测试 PR

需要一个测试用的 PR，可以是：
- 真实项目中的 PR
- 自己创建的测试 PR
- 公开项目的 PR

```bash
# 查看可用的 PR
gitlink-cli pr +list --owner <owner> --repo <repo> --format json
```

## 📊 测试计划

### 测试级别

| 级别 | 测试内容 | 优先级 |
|------|---------|--------|
| Level 1 | 文档结构验证 | P0 |
| Level 2 | 基础功能测试 | P0 |
| Level 3 | AI Agent 集成测试 | P0 |
| Level 4 | 完整工作流测试 | P1 |
| Level 5 | 边界情况测试 | P2 |

---

## 🧪 Level 1: 文档结构验证

### 测试 1.1: 检查必需文件存在

**目的**: 确保所有必需的文档文件都存在。

**步骤**:
```bash
cd skills/gitlink-code-review

# 检查必需文件
ls -la SKILL.md
ls -la README.md
ls -la REFERENCE.md

# 检查目录结构
ls -la references/
ls -la examples/

# 验证文件内容
wc -l SKILL.md
wc -l README.md
wc -l REFERENCE.md
```

**预期结果**:
- ✅ SKILL.md 存在且 >100 行
- ✅ README.md 存在且 >100 行
- ✅ REFERENCE.md 存在且 >200 行
- ✅ references/ 目录包含至少 3 个 .md 文件
- ✅ examples/ 目录包含至少 3 个 .md 文件

### 测试 1.2: 验证 Frontmatter 格式

**目的**: 确保 SKILL.md 的 frontmatter 符合规范。

**步骤**:
```bash
# 查看 SKILL.md 的前 20 行
head -20 SKILL.md
```

**预期结果**:
```yaml
---
name: gitlink-code-review
version: 1.0.0
description: "智能代码审查：..."
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli pr --help"
---
```

**验证点**:
- ✅ 包含 `name` 字段
- ✅ 包含 `version` 字段
- ✅ 包含 `description` 字段
- ✅ 包含 `metadata` 字段
- ✅ `metadata.requires.bins` 包含 `gitlink-cli`

### 测试 1.3: 验证文档引用

**目的**: 确保文档之间的相互引用正确。

**步骤**:
```bash
# 检查 SKILL.md 中的引用
grep -n "\[.*\](.*.md)" SKILL.md

# 检查 README.md 中的引用
grep -n "\[.*\](.*.md)" README.md

# 验证引用的文件是否存在
# [手动检查引用的文件路径是否正确]
```

**预期结果**:
- ✅ 所有引用的文件都存在
- ✅ 引用路径正确
- ✅ 没有断开的链接

---

## 🧪 Level 2: 基础功能测试

### 测试 2.1: 验证 gitlink-cli PR 命令

**目的**: 确保依赖的 gitlink-cli 命令正常工作。

**步骤**:
```bash
# 设置测试变量
OWNER="Gitlink"
REPO="forgeplus"
PR_ID=<一个真实的PR编号>

# 测试 pr +view 命令
echo "=== 测试 pr +view ==="
gitlink-cli pr +view --id $PR_ID --format json > test_pr_view.json
cat test_pr_view.json | jq '.ok'

# 测试 pr +files 命令
echo "=== 测试 pr +files ==="
gitlink-cli pr +files --id $PR_ID --format json > test_pr_files.json
cat test_pr_files.json | jq '.ok'

# 测试 pr +diff 命令
echo "=== 测试 pr +diff ==="
gitlink-cli pr +diff --id $PR_ID --format json > test_pr_diff.json
cat test_pr_diff.json | jq '.ok'
```

**预期结果**:
- ✅ `pr +view` 返回 `{"ok": true}`
- ✅ `pr +files` 返回 `{"ok": true}`
- ✅ `pr +diff` 返回 `{"ok": true}`
- ✅ JSON 文件包含有效的数据

### 测试 2.2: 验证数据解析

**目的**: 确保能够正确解析 gitlink-cli 返回的数据。

**步骤**:
```bash
# 验证 PR 数据结构
echo "=== 验证 PR 详情 ==="
cat test_pr_view.json | jq '.data | keys'
# 应包含: id, title, author, status, etc.

echo "=== 验证文件列表 ==="
cat test_pr_files.json | jq '.data.files | length'
# 应该 > 0

echo "=== 验证 diff 内容 ==="
cat test_pr_diff.json | jq '.data.diff' | head -c 100
# 应该包含 diff 内容
```

**预期结果**:
- ✅ PR 详情包含必要的字段
- ✅ 文件列表非空
- ✅ diff 内容存在

### 测试 2.3: 手动代码审查模拟

**目的**: 手动执行一次完整的代码审查流程。

**步骤**:
```bash
# 1. 获取 PR 信息
echo "步骤 1: 获取 PR 信息"
gitlink-cli pr +view --id $PR_ID --format json | jq '{id: .data.id, title: .data.title, author: .data.author.login}'

# 2. 获取文件列表
echo "步骤 2: 获取文件列表"
gitlink-cli pr +files --id $PR_ID --format json | jq '.data.files[] | {filename: .filename, changes: .changes}'

# 3. 获取 diff
echo "步骤 3: 获取 diff"
gitlink-cli pr +diff --id $PR_ID --format json | jq -r '.data.diff' | head -50

# 4. 手动分析代码（需要人工查看）
echo "步骤 4: 手动分析代码"
echo "请查看上面的代码变更，识别潜在问题"
```

**预期结果**:
- ✅ 每个步骤都能成功执行
- ✅ 数据格式正确
- ✅ 可以看到代码变更内容

---

## 🧪 Level 3: AI Agent 集成测试

### 测试 3.1: Claude Code 基础测试

**目的**: 验证 Claude Code 可以识别和使用此 Skill。

**在 Claude Code 中执行**:

```
用户: 我需要审查一个 PR，PR 编号是 123

[预期行为]:
1. Claude Code 应该识别需要使用 gitlink-code-review Skill
2. 自动读取 SKILL.md 了解如何操作
3. 执行正确的命令序列
4. 生成审查报告
```

**验证点**:
- ✅ AI 识别到需要使用 gitlink-code-review Skill
- ✅ AI 执行了 `pr +view`, `pr +files`, `pr +diff` 命令
- ✅ AI 生成了结构化的审查报告
- ✅ 提供了可操作的建议

### 测试 3.2: Claude Code 场景测试

**场景 1: 基础审查**

```
用户: 审查 PR #123

[预期输出]:
- 获取 PR 信息
- 分析代码变更
- 生成审查报告
- 提供改进建议
```

**场景 2: 重点安全审查**

```
用户: 审查 PR #456，重点关注安全问题

[预期输出]:
- 获取 PR 信息
- 重点分析安全问题
- 列出发现的安全漏洞
- 提供修复建议
```

**场景 3: 自动添加评论**

```
用户: 审查 PR #789 并添加评论到 PR

[预期输出]:
- 获取 PR 信息
- 分析代码
- 生成报告
- 添加评论到 PR
```

**验证点**:
- ✅ AI 根据用户请求调整审查重点
- ✅ AI 正确执行相应的命令
- ✅ 输出格式符合预期
- ✅ 提供了有价值的建议

### 测试 3.3: 提示词测试

**目的**: 验证 Skill 中的提示词是否有效。

**测试提示词**:
```
请分析以下 PR 的代码变更，检查代码质量、安全性和性能问题。

PR 数据：
[粘贴 test_pr_view.json, test_pr_files.json, test_pr_diff.json 的内容]

请以 JSON 格式输出审查报告，包含：
- overall_assessment: 总体评估
- issues: 问题列表
- positive_notes: 优秀实践
- recommendations: 改进建议
```

**验证点**:
- ✅ AI 理解任务要求
- ✅ AI 分析代码变更
- ✅ 输出格式符合要求
- ✅ 发现了真实的问题

---

## 🧪 Level 4: 完整工作流测试

### 测试 4.1: 基础审查工作流

**目的**: 验证 `basic-review-workflow.md` 中的工作流。

**步骤**:
```bash
# 按照基础审查工作流执行
PR_ID=<测试PR编号>

# 步骤 1: 获取 PR 详情
gitlink-cli pr +view --id $PR_ID --format json

# 步骤 2: 获取变更文件列表
gitlink-cli pr +files --id $PR_ID --format json

# 步骤 3: 获取 diff 内容
gitlink-cli pr +diff --id $PR_ID --format json

# 步骤 4: 浏览代码变更
gitlink-cli pr +diff --id $PR_ID --format json | jq -r '.data.diff' | less
```

**验证点**:
- ✅ 所有步骤都能成功执行
- ✅ 数据格式正确
- ✅ 可以看到代码变更

### 测试 4.2: 全面审查工作流

**目的**: 验证 `comprehensive-review-workflow.md` 中的工作流。

**步骤**:
```bash
# 按照全面审查工作流执行
PR_ID=<测试PR编号>

# 1. 获取数据
gitlink-cli pr +view --id $PR_ID --format json > pr_info.json
gitlink-cli pr +files --id $PR_ID --format json > pr_files.json
gitlink-cli pr +diff --id $PR_ID --format json > pr_diff.json

# 2. 数据预处理
cat pr_files.json | jq '.data.files | map(select(.changes > 10))' > main_changes.json

# 3. 组织分析数据
cat > analysis_input.json <<EOF
{
  "pr_info": $(cat pr_info.json | jq '.data'),
  "files": $(cat pr_files.json | jq '.data.files'),
  "diff": $(cat pr_diff.json | jq -r '.data.diff')
}
EOF

# 4. 验证数据
cat analysis_input.json | jq '.pr_info.title'
cat analysis_input.json | jq '.files | length'
```

**验证点**:
- ✅ 数据预处理成功
- ✅ 分析数据格式正确
- ✅ 包含所有必要的信息

### 测试 4.3: 自动审查工作流

**目的**: 验证 `auto-review-pr.md` 中的自动化流程。

**在 Claude Code 中测试**:

```
用户: 使用自动审查模式审查 PR #123

[预期行为]:
1. AI 自动获取所有必要数据
2. AI 自动分析代码
3. AI 自动生成报告
4. AI 询问是否添加评论
```

**验证点**:
- ✅ 流程完全自动化
- ✅ 不需要人工干预
- ✅ 生成完整的报告

---

## 🧪 Level 5: 边界情况测试

### 测试 5.1: 大型 PR 测试

**目的**: 测试对大型 PR 的处理能力。

**步骤**:
```bash
# 查找一个大型 PR（>500 行变更）
gitlink-cli pr +list --format json | \
  jq '.data[] | select(.additions > 500) | {id: .id, additions: .additions}'

# 测试获取 diff
gitlink-cli pr +diff --id <大型PR编号> --format json | \
  jq '.data | length'
```

**验证点**:
- ✅ 能够处理大型 diff
- ✅ 不会超时或崩溃
- ✅ 输出格式正确

### 测试 5.2: 错误处理测试

**目的**: 测试错误情况的处理。

**测试不存在的 PR**:
```bash
gitlink-cli pr +view --id 999999 --format json
# 应该返回错误信息
```

**测试无权限的 PR**:
```bash
gitlink-cli pr +view --id <私有PR编号> --format json
# 应该返回 403 错误
```

**验证点**:
- ✅ 错误信息清晰
- ✅ 包含错误原因
- ✅ 提供解决建议

### 测试 5.3: 不同文件类型测试

**目的**: 测试对不同文件类型的处理。

**步骤**:
```bash
# 查找包含不同文件类型的 PR
# Go 文件
gitlink-cli pr +files --id $PR_ID --format json | \
  jq '.data.files[] | select(.filename | endswith(".go"))'

# JavaScript 文件
gitlink-cli pr +files --id $PR_ID --format json | \
  jq '.data.files[] | select(.filename | endswith(".js"))'

# Python 文件
gitlink-cli pr +files --id $PR_ID --format json | \
  jq '.data.files[] | select(.filename | endswith(".py"))'
```

**验证点**:
- ✅ 能够识别不同语言
- ✅ 能够针对性分析
- ✅ 建议符合语言特性

---

## 📊 测试报告模板

### 测试执行记录

```markdown
# gitlink-code-review Skill 测试报告

**测试日期**: 2026-06-12
**测试人员**: [姓名]
**测试环境**: [环境描述]

## 测试结果总览

| 测试级别 | 通过/总数 | 状态 |
|---------|----------|------|
| Level 1 | ?/? | ⏳ |
| Level 2 | ?/? | ⏳ |
| Level 3 | ?/? | ⏳ |
| Level 4 | ?/? | ⏳ |
| Level 5 | ?/? | ⏳ |

## 详细测试结果

### Level 1: 文档结构验证

- [ ] 测试 1.1: 检查必需文件存在 - ⏳
- [ ] 测试 1.2: 验证 Frontmatter 格式 - ⏳
- [ ] 测试 1.3: 验证文档引用 - ⏳

### Level 2: 基础功能测试

- [ ] 测试 2.1: 验证 gitlink-cli PR 命令 - ⏳
- [ ] 测试 2.2: 验证数据解析 - ⏳
- [ ] 测试 2.3: 手动代码审查模拟 - ⏳

### Level 3: AI Agent 集成测试

- [ ] 测试 3.1: Claude Code 基础测试 - ⏳
- [ ] 测试 3.2: Claude Code 场景测试 - ⏳
- [ ] 测试 3.3: 提示词测试 - ⏳

### Level 4: 完整工作流测试

- [ ] 测试 4.1: 基础审查工作流 - ⏳
- [ ] 测试 4.2: 全面审查工作流 - ⏳
- [ ] 测试 4.3: 自动审查工作流 - ⏳

### Level 5: 边界情况测试

- [ ] 测试 5.1: 大型 PR 测试 - ⏳
- [ ] 测试 5.2: 错误处理测试 - ⏳
- [ ] 测试 5.3: 不同文件类型测试 - ⏳

## 发现的问题

### 问题 1
- **描述**: [问题描述]
- **严重性**: [高/中/低]
- **状态**: [待修复/已修复]

## 建议和改进

### 建议 1
- **描述**: [建议描述]
- **优先级**: [高/中/低]

## 总结

**总体评估**: [通过/不通过]
**评分**: [?/100]
**建议**: [是否建议投入使用]
```

---

## 🎯 快速测试脚本

为了快速验证 Skill 的基本功能，可以使用以下脚本：

```bash
#!/bin/bash
# quick-test.sh - 快速测试脚本

set -e

echo "=== gitlink-code-review Skill 快速测试 ==="

# 配置
PR_ID=${1:-<默认PR编号>}
OWNER=${2:-Gitlink}
REPO=${3:-forgeplus}

echo "测试 PR: $PR_ID"
echo ""

# Level 1: 文档检查
echo "Level 1: 检查文档..."
if [ -f "SKILL.md" ] && [ -f "README.md" ] && [ -f "REFERENCE.md" ]; then
    echo "✅ 文档文件存在"
else
    echo "❌ 缺少必需文档"
    exit 1
fi

# Level 2: 功能测试
echo ""
echo "Level 2: 测试 gitlink-cli 命令..."

# 测试 pr +view
if gitlink-cli pr +view --id $PR_ID --format json | jq -e '.ok == true' > /dev/null; then
    echo "✅ pr +view 正常"
else
    echo "❌ pr +view 失败"
    exit 1
fi

# 测试 pr +files
if gitlink-cli pr +files --id $PR_ID --format json | jq -e '.ok == true' > /dev/null; then
    echo "✅ pr +files 正常"
else
    echo "❌ pr +files 失败"
    exit 1
fi

# 测试 pr +diff
if gitlink-cli pr +diff --id $PR_ID --format json | jq -e '.ok == true' > /dev/null; then
    echo "✅ pr +diff 正常"
else
    echo "❌ pr +diff 失败"
    exit 1
fi

echo ""
echo "=== 快速测试完成 ==="
echo "✅ 所有基础测试通过"
echo ""
echo "下一步："
echo "1. 在 Claude Code 中测试 AI 集成"
echo "2. 执行完整工作流测试"
echo "3. 验证边界情况"
```

**使用方法**:
```bash
chmod +x quick-test.sh
./quick-test.sh <PR编号>
```

---

## 📞 获取帮助

如果测试过程中遇到问题：

1. **查看文档**
   - [SKILL.md](SKILL.md) - 技能总览
   - [README.md](README.md) - 使用说明
   - [REFERENCE.md](REFERENCE.md) - API 参考

2. **检查配置**
   ```bash
   # 检查 gitlink-cli 版本
   gitlink-cli --version

   # 检查认证状态
   gitlink-cli auth status
   ```

3. **查看错误日志**
   ```bash
   # 启用调试模式
   gitlink-cli pr +view --id $PR_ID --format json --debug
   ```

---

## 🎓 测试最佳实践

### 1. 渐进式测试

- 从 Level 1 开始，逐步升级
- 每个级别通过后再进行下一级
- 记录每个测试的结果

### 2. 真实场景测试

- 使用真实的 PR 进行测试
- 覆盖不同类型的 PR（功能、修复、重构）
- 测试不同大小的 PR

### 3. 持续改进

- 记录发现的问题
- 及时修复和改进
- 定期重新测试

---

**测试完成后，请填写测试报告并评估 Skill 是否可以投入使用。**

*最后更新: 2026-06-12*
