编辑文档 - 代码审查总漏检？用 SKILL.md 把团队标准封装起来

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

长期使用 OpenCode，最让我上瘾的不是 AI 对话能力，而是它的**代理技能（Skills）系统**。

简单说：Skill 就是一个文件夹，里面放一个 `SKILL.md`，AI 自己知道什么时候激活它。你不需要手动调命令，它会根据上下文判断。

这对代码审查意味着什么？

**我可以把自己积累的审查经验封装成一个可复用的 Skill，下次换项目、换团队，直接把文件夹拷过去，审查标准跟着走。**

今天把完整流程跑了一遍，记录下来给你参考。

---

## 先说重点：OpenCode 的真实数据

| 指标 | 数值 |
|------|------|
| GitHub 地址 | https://github.com/anomalyco/opencode |
| Stars | **161,286**（活跃仓库） |
| Forks | 18,942 |
| 最后更新 | 2026-05-16 |
| 支持的 Provider | Claude / GPT / Gemini / Grok / 本地模型 |

> 注：OpenCode 原仓库（opencode-ai/opencode）已于 2025 年 9 月归档，当前活跃开发在 `anomalyco/opencode`。

---

## OpenCode 的 Skills 系统

OpenCode 的 Skills 支持多个搜索路径，按优先级从高到低：

```
项目配置：  .opencode/skills/<name>/SKILL.md
全局配置：  ~/.config/opencode/skills/<name>/SKILL.md
Claude 兼容：.claude/skills/<name>/SKILL.md ~/.claude/skills/<name>/SKILL.md
Agent 兼容： .agents/skills/<name>/SKILL.md ~/.agents/skills/<name>/SKILL.md
```

---

## 完整示例：代码审查 Skill

在项目根目录创建：

```
.opencode/skills/code-review/SKILL.md
```

内容：

```markdown
---
name: code-review
description: 对 GitHub Pull Request 进行代码审查，关注安全性、可读性和最佳实践
---

# Code Review Skill

## 触发方式

`@code-review <PR编号>` 或在讨论 PR 时自动识别

## 严重性评级标准

审查结果必须包含严重性评级：

- **严重（Critical）**：远程代码执行、认证绕过、SQL 注入（可未认证利用）
- **高危（High）**：存储型 XSS、涉及敏感数据的 IDOR、权限提升
- **中危（Medium）**：反射型 XSS、CSRF、缺失安全响应头
- **低危（Low）**：轻微信息泄露、非敏感页面的点击劫持
- **信息（Informational）**：最佳实践偏差、纵深防御改进

## 必须检查的漏洞维度

### 安全性
- [ ] **注入**：SQL 注入、XSS（反射/存储/DOM）、命令注入、SSRF、模板注入
- [ ] **认证与授权**：IDOR、水平越权、垂直越权、JWT 算法混淆（alg=none）
- [ ] **密钥安全**：硬编码密钥、API Key 泄露、环境变量中的凭据
- [ ] **输入验证**：边界值、特殊字符、超大载荷、缺失验证

### 可读性
- [ ] 函数长度超过 50 行
- [ ] 命名不规范（单字母变量、语义不清）
- [ ] 缺少必要注释
- [ ] 重复代码（DRY 原则违反）

### 性能
- [ ] N+1 查询问题
- [ ] 不必要的循环或深层嵌套
- [ ] 没有索引的数据库查询
- [ ] 同步阻塞操作在请求路径中

### 最佳实践
- [ ] 错误处理（吞掉异常、暴露堆栈跟踪）
- [ ] 测试覆盖（核心逻辑是否有测试）
- [ ] API 设计（RESTful 规范、响应结构一致性）

## 工作流程

1. 使用 `gh pr view <PR_NUMBER> --json body,title,state,isDraft` 获取 PR 信息
2. 使用 `gh pr diff <PR_NUMBER>` 获取变更内容
3. **跳过性能检查**（如果是 draft PR）
4. 按上述维度逐项检查
5. 每个发现必须包含：
   - 严重性评级
   - 具体文件路径和行号
   - 可利用性说明
   - 直接可复制的修复代码
6. 通过 `gh pr review <PR_NUMBER> --comment-body "..."` 提交评论

## 输出格式模板

## Code Review Report

### 🔴 严重（Critical）: N 个
- [ ] **文件**: `src/auth.py:42`
    **问题**: SQL 注入——字符串拼接构建查询
    **利用**: 未认证攻击者可提取整个用户表
    **修复**:
    ```
    # 错误
    query = f"SELECT * FROM users WHERE id = {user_id}"
    # 正确：使用参数化查询
    db.execute("SELECT * FROM users WHERE id = %s", (user_id,))
    ```

### 🟡 中危（Medium）: N 个
...

### ✅ 通过项
- 认证逻辑：JWT 验证包含算法白名单
- 密钥管理：未发现硬编码密钥

## 注意事项

- 评论使用 Markdown，保持专业语气
- 优先关注**新增代码**，而非重构或格式化改动
- 每个问题必须附带修复代码——只提问题不给答案是耍流氓
- 安全问题和体验问题分开报告，安全问题优先级更高
```

---

## 跑通完整工作流

### 第一步：安装 OpenCode

```bash
# 一键安装（Linux/macOS）
curl -fsSL https://opencode.ai/install | bash

# Windows
scoop install opencode

# 或用 npm
npm i -g opencode-ai@latest
```

### 第二步：创建代码审查 Skill

```bash
# 创建 Skill 目录
mkdir -p .opencode/skills/code-review

# 写入 SKILL.md（内容见上方示例）
```

### 第三步：配置 GitHub CLI（无需给 OpenCode 仓库权限）

```bash
# 确保已安装 gh CLI 并登录
gh auth status

# OpenCode 的 GitHub 集成通过 gh CLI 访问仓库
# 不需要额外的 token 配置
```

### 第四步：触发审查

在本地项目目录下直接运行，不需要记 PR 编号：

```bash
cd your-project  # 先进入你的项目目录
opencode        # 启动后说：帮我审查这个 PR
```

OpenCode 会自动识别当前分支对应的 PR 编号，然后：

1. 调用 `gh pr view` 获取 PR 信息
2. 调用 `gh pr diff` 获取变更
3. 按 SKILL.md 中的维度逐项检查
4. 生成带严重性评级和修复代码的审查报告
5. 调用 `gh pr review` 提交评论

整个过程不需要你手动复制粘贴，也不需要给 OpenCode 任何仓库权限——它只通过你本地的 `gh` CLI 访问 GitHub。

---

## 为什么不用第三方 SaaS 工具做代码审查

常见的 AI 代码审查工具需要你授权他们访问你的 GitHub 仓库，这有几个问题：

| 问题 | 风险 |
|------|------|
| 权限过大 | 它们通常需要 read+write 全权限 |
| 数据泄露 | 代码可能经过第三方服务器 |
| 成本 | 企业版通常按 seat 收费 |
| 锁定 | 换了工具就丢失历史配置 |

OpenCode + Skills 的方案：

- **不需要给仓库权限**——它通过本地的 `gh` CLI 操作
- **配置跟着代码走**——`.opencode/skills/` 放在项目里，团队成员都能用
- **完全免费**——只是 API 费用，没有额外成本
- **Skill 可复用**——写一次，多个项目都能用

---

## 团队推广建议

把代码审查标准封装成 Skill 后，可以：

1. **项目级 Skill**：在 `.opencode/skills/` 放项目专用的审查规则
2. **团队级 Skill**：在 `~/.config/opencode/skills/` 放团队通用标准
3. **开源共享**：把成熟的标准 Skill 发布到 GitHub，其他团队也能用

```
~/.config/opencode/skills/
├── security-review/      # 安全审查标准（OWASP Top 10、CWE Top 25）
├── perf-check/          # 性能检查清单
├── api-design/          # API 设计规范
└── test-coverage/        # 测试覆盖要求
```

---

## 写在最后

Skills 的意义不只是"方便"，而是让**经验可以被封装和传递**。

你团队里最好的审查标准，不再只存在于某个 senior 工程师的脑子里，而是可以变成一个文件，发给所有人。

**你团队现在靠什么做代码审查？是人工看、靠 CI 自动化、还是直接裸奔？** 有没有碰过审查标准执行不下去、或者不同人尺度不一的问题？评论区聊聊，说不定能帮你把标准固化下来。

摘要

标签多个标签用逗号分隔

分类