github-code-analysis

name	github-code-analysis
description	> Use when this capability is needed.

GitHub 代码分析套件

提供六大能力，覆盖代码全生命周期质量管控：

能力	触发词示例	说明
PR 审查	"review PR"、"审查 PR #52"	拉取 PR diff，四维度分析，写回 comment
代码质量扫描	"代码质量扫描"、"quality scan"	扫描仓库/目录的命名、复杂度、重复、一致性
安全扫描	"安全扫描"、"security scan"	检测注入、硬编码 secret、不安全依赖
性能扫描	"性能扫描"、"performance scan"	检测 N+1、内存泄露、阻塞调用
不一致扫描	"不一致扫描"、"consistency check"	检测代码风格/模式/命名不一致
自动生成文档	"生成文档"、"generate docs"	为模块/函数/API 生成 markdown 文档

Default Configuration

• Default repository: beyonai/ByClaw
• 授权方式: OAuth Device Flow（自动，无需手动配置）
• 用户不指定仓库时使用默认值，无需询问

Workflow

IMPORTANT: Always start by executing Step 0. Do NOT ask the user for a token. Do NOT suggest creating a token. Do NOT mention GITHUB_TOKEN or environment variables.

Step 0: Check Authorization (MANDATORY FIRST STEP)

Run this command immediately — do not ask the user anything first:

node skills/github-code-analysis/scripts/gh-pr-list.mjs --limit 1

If "ok": true → proceed based on user intent.

If "auth_required": true → the output already contains verification_uri, user_code, and message. Do these things:

1. Show the message field content to the user verbatim (it has the link and code)
2. STOP and wait for user to say "授权完了" / "done" / "好了"
3. When user confirms, execute:

node skills/github-code-analysis/scripts/gh-auth-login.mjs --poll

4. If poll returns "ok": true → 授权成功，重新执行用户的原始请求
5. If poll returns "retry": true → 告诉用户"还没完成，请确认浏览器中已授权"
6. If poll returns expired error → 重新执行 Step 0（会生成新的授权码）

禁止：不得提及 GITHUB_TOKEN、PAT、Personal Access Token、环境变量、手动配置。授权完全由脚本自动处理。

---

Mode 1: PR 审查

When to Use

用户说"review PR"、"审查 PR"、"帮我看看 PR"、"代码审查"等。

Steps

Do NOT ask the user for PR number or repo. Follow this logic:

1. If the user explicitly mentions a PR number (e.g. "review PR #52"), use that number.
2. If the user does NOT specify a PR number, automatically list open PRs and pick the most recently updated one:

node skills/github-code-analysis/scripts/gh-pr-list.mjs --state open --limit 5

Pick the first PR from the result and proceed.

3. Fetch PR data:

node skills/github-code-analysis/scripts/gh-pr-fetch.mjs --pr <number> --format all

4. Read references/review-prompts.md for detailed criteria. Analyze across four dimensions:

   • Security — 注入、硬编码 secret、不安全依赖、auth 问题
   • Performance — N+1 查询、内存泄露、阻塞调用
   • Quality — 命名、圈复杂度、重复代码、不一致模式
   • Test — 缺失测试覆盖、边界条件

5. Post review comment:

echo '<json>' | node skills/github-code-analysis/scripts/gh-pr-comment.mjs

Review Output Format

## 🔍 PR Review: #{number} {title}

**Reviewer**: ByClaw AI | **Dimensions**: Security, Performance, Quality, Tests

### Summary
{1-2 sentence overview}

### Findings

#### 🔒 Security
{findings or "No issues found"}

#### ⚡ Performance
{findings or "No issues found"}

#### 📐 Quality
{findings or "No issues found"}

#### 🧪 Tests
{findings or "No issues found"}

### Verdict
{approve / needs changes / comment only}

---
*Automated review by ByClaw AI*

---

Mode 2: 代码质量扫描

When to Use

用户说"代码质量扫描"、"quality scan"、"扫描代码质量"、"检查代码规范"等。

Steps

1. 确定扫描范围：

   • 用户指定了路径 → 直接使用
   • 用户说"扫描前端" → 用 byclaw-fe/src
   • 用户说"扫描后端" → 用 byclaw-be/src
   • 用户无具体指定 → 扫描最新 PR 的变更文件

2. Clone 仓库到本地（如已 clone 则自动更新）：

node skills/github-code-analysis/scripts/gh-repo-clone.mjs

脚本输出 data.path 即为本地仓库路径。后续直接用 cat/grep/find 等命令读取本地文件分析。

3. 在本地仓库中定位并读取目标文件：

# 列出目标目录结构
find <repo-path>/byclaw-fe/src -name "*.ts" -o -name "*.tsx" | head -30

# 读取具体文件
cat <repo-path>/byclaw-fe/src/utils/request.ts

4. 逐文件分析以下维度：

• 命名规范 — 变量/函数/类/文件命名是否一致（camelCase vs snake_case 混用）
• 圈复杂度 — 深层嵌套（>3层）、超长函数（>50行）
• 代码重复 — 相似逻辑块、copy-paste 模式
• Dead code — 未使用的 import、unreachable 分支、注释掉的代码
• Error handling — 吞掉的异常、缺少错误类型、generic catch

Output Format

## 📐 代码质量报告

**扫描范围**: {repo/path/PR}
**扫描时间**: {timestamp}

### 统计
- 扫描文件数: N
- 发现问题: N (critical: X, warning: Y, suggestion: Z)

### 问题列表

| 严重度 | 文件 | 行号 | 类别 | 描述 |
|--------|------|------|------|------|
| ⚠️ | src/foo.ts | 42 | 命名 | 混用 camelCase 和 snake_case |
| ... | ... | ... | ... | ... |

### 建议
{top 3 改进建议}

---

Mode 3: 安全扫描

When to Use

用户说"安全扫描"、"security scan"、"检查安全漏洞"、"有没有安全问题"等。

Steps

1. 确定扫描范围（同 Mode 2 的逻辑）
2. 确保仓库已 clone 到本地：

node skills/github-code-analysis/scripts/gh-repo-clone.mjs

然后用 find/grep/cat 在本地仓库路径中读取文件。 对于 PR 变更可用：node skills/github-code-analysis/scripts/gh-pr-fetch.mjs --pr <number> --format files

3. 按以下维度深度分析：

• 注入漏洞 — SQL injection（字符串拼接查询）、command injection（exec/spawn 未转义）、XSS
• 硬编码 Secret — API key、token、password、private key 出现在源码中
• 不安全依赖 — 已知漏洞包、typosquatting 包名
• 认证/授权 — 缺少 auth 检查、权限提升路径
• 加密问题 — 弱算法（MD5/SHA1 用于安全场景）、硬编码 IV/salt
• 数据泄露 — 敏感数据进日志、错误信息暴露内部结构

Output Format

## 🔒 安全扫描报告

**扫描范围**: {target}
**风险等级**: {高/中/低}

### 发现

#### Critical
{list or "无"}

#### Warning
{list or "无"}

### 修复建议
{prioritized fix suggestions}

---

Mode 4: 性能扫描

When to Use

用户说"性能扫描"、"performance scan"、"性能分析"、"有没有性能问题"等。

Steps

1. 确定扫描范围（同 Mode 2 的逻辑）
2. 获取源码：

node skills/github-code-analysis/scripts/gh-repo-fetch.mjs --dir <target-path>
# 或针对 PR 变更：
node skills/github-code-analysis/scripts/gh-pr-fetch.mjs --pr <number> --format files

3. 按以下维度分析：

• N+1 查询 — 循环内 DB/API 调用，应改为批量
• 无界操作 — 缺少分页、加载整表、无 LIMIT
• 内存问题 — 大数组全量加载、未关闭资源/句柄
• 阻塞调用 — 异步上下文中的同步 I/O、事件循环上的 CPU 密集操作
• 冗余计算 — 可缓存/memoize 的重复计算
• 网络 — 缺少连接池、无超时、chatty API

Output Format

## ⚡ 性能扫描报告

**扫描范围**: {target}

### 发现

| 严重度 | 文件 | 问题 | 影响 | 建议 |
|--------|------|------|------|------|
| 🔴 | ... | N+1 query in loop | 线性增长延迟 | 改为批量查询 |
| ... | ... | ... | ... | ... |

### 优化优先级
1. {most impactful fix}
2. ...

---

Mode 5: 不一致扫描

When to Use

用户说"不一致扫描"、"consistency check"、"检查一致性"、"风格不统一"等。

Steps

1. 确定扫描范围（同 Mode 2 的逻辑）
2. 确保仓库已 clone 到本地：

node skills/github-code-analysis/scripts/gh-repo-clone.mjs

然后用 find/grep/cat 在本地仓库路径中读取文件。

3. 跨文件对比，检测以下不一致：

• 命名风格 — 同一项目中 camelCase/snake_case/PascalCase 混用
• 异步模式 — callback vs Promise vs async/await 混用
• 错误处理 — 有的地方 try-catch，有的地方 .catch()，有的地方不处理
• 导入风格 — default import vs named import 不一致
• API 风格 — REST 命名不统一（复数/单数、嵌套/扁平）
• 配置模式 — 有的用环境变量，有的用配置文件，有的硬编码
• 日志格式 — 有的结构化，有的 console.log，格式不统一
• 类型使用 — 有的用 interface，有的用 type，有的用 any

Output Format

## 🔄 不一致性报告

**扫描范围**: {target}

### 发现的不一致模式

#### 1. {pattern name}
- **现状**: 文件 A 用 X 方式，文件 B 用 Y 方式
- **涉及文件**: file1.ts, file2.ts, ...
- **建议**: 统一为 {recommended pattern}，原因：{why}

#### 2. ...

### 统一建议
{overall recommendation for consistency}

---

Mode 6: 自动生成文档

When to Use

用户说"生成文档"、"generate docs"、"写文档"、"API 文档"、"模块文档"等。

Steps

1. 确定文档目标：

   • 用户指定了文件/模块 → 为该文件生成文档
   • 用户说"为 PR 生成文档" → 为 PR 中新增/修改的公共 API 生成文档
   • 用户说"生成项目文档" → 生成项目结构概览 + 核心模块文档

2. 确保仓库已 clone 到本地：

node skills/github-code-analysis/scripts/gh-repo-clone.mjs

然后用 find/cat 在本地仓库路径中读取源码。对于 PR 变更可用：

node skills/github-code-analysis/scripts/gh-pr-fetch.mjs --pr <number> --format files

3. 生成文档内容：

   • 模块文档 — 模块职责、导出 API、使用示例
   • 函数文档 — 参数、返回值、异常、使用示例
   • API 文档 — endpoint、请求/响应格式、认证要求
   • 架构文档 — 模块关系、数据流、关键设计决策

4. 输出为 markdown，可直接用于 README 或 docs/ 目录

Output Format

## 📝 自动生成文档

### {Module/Function/API Name}

**路径**: `src/path/to/file.ts`
**职责**: {one-line description}

#### 导出 API

| 名称 | 类型 | 说明 |
|------|------|------|
| functionA | function | ... |
| TypeB | type | ... |

#### 使用示例

\`\`\`typescript
import { functionA } from "./path";
const result = await functionA(params);
\`\`\`

#### 注意事项
- {important notes}

---

Scripts Reference

脚本	用途	示例
gh-repo-clone.mjs	Clone 仓库到本地	node skills/github-code-analysis/scripts/gh-repo-clone.mjs
gh-pr-list.mjs	列出 PR	node skills/github-code-analysis/scripts/gh-pr-list.mjs --state open --limit 5
gh-pr-fetch.mjs	拉取 PR 数据	node skills/github-code-analysis/scripts/gh-pr-fetch.mjs --pr 52 --format all
gh-pr-comment.mjs	写回 PR comment	echo '{...}' | node skills/github-code-analysis/scripts/gh-pr-comment.mjs
gh-repo-fetch.mjs	轻量 API 查询（单文件/目录树）	node skills/github-code-analysis/scripts/gh-repo-fetch.mjs --tree --path src

gh-repo-clone.mjs 用法

Clone 仓库到 skills/github-code-analysis/.cache/ByClaw/：

node skills/github-code-analysis/scripts/gh-repo-clone.mjs

输出 data.path 为本地路径。后续直接用标准命令分析：

# 列出文件
find <path>/byclaw-fe/src -name "*.ts" | head -20

# 搜索模式
grep -rn "password" <path>/byclaw-be/src --include="*.java" | head -20

# 读取文件
cat <path>/byclaw-fe/src/utils/request.ts

再次运行时自动 git pull 更新，不会重复 clone。用 --force 强制重新 clone。

所有脚本默认仓库为 beyonai/ByClaw，可通过 --repo owner/repo 覆盖。

Important Notes

• 用户不指定仓库时，默认 beyonai/ByClaw，不要问
• 用户不指定 PR 号时，自动选最新的 open PR，不要问
• Only post REQUEST_CHANGES when there are critical security or correctness issues
• If the diff is too large (>5000 lines), focus on the most impactful files
• Skip generated files, lockfiles, vendor dirs, node_modules
• 中文回复，除非用户用英文提问

---

Source: beyonai/ByClaw — distributed by TomeVault.