1k-code-review-pr

OneKey PR 代码审查

输出语言：中文

审查范围

• 基础分支：x
• 差异：git fetch origin && git diff origin/x...HEAD（三点语法）

工作流

1. 检出 — gh pr checkout <PR_NUMBER>（如果已经在该分支上则跳过）
2. 确定范围 — 使用 git diff origin/x...HEAD --stat 查看变更范围
3. 分类 — 确定适用哪些审查模块（参见分类表）
4. 主要审查 — 阅读每个变更文件，并应用 references/ 中的相关检查项
5. Codex 交叉审查 — 如果 Codex 可用，运行完整的并行审查（见下文）
6. PR 评论分析 — 获取所有现有 PR 评论（机器人和人工），结合本地代码库上下文进行分析（见下文）
7. 合并审查结果 — 合并主要审查、Codex 和 PR 评论的发现，去重并标注置信度
8. 评分 — 从 4 个维度对 PR 进行评分（参见评分系统）。此步骤为必需 — 每份报告都必须包含评分表。
9. 报告 — 使用统一格式生成结构化报告。严格遵循模板 — 每个章节都不可缺少。
10. GH 评论 — 立即将符合条件的发现作为 PR 行内评论发布（无需等待确认）

Codex 交叉审查集成

确认能否派发 codex:codex-rescue 子 Agent 类型，以检查 Codex 是否可用。如果不确定，调用 /codex:setup 检查是否已就绪。

如果可用：

1. 通过 Agent(subagent_type="codex:codex-rescue") 派发完整的独立审查给 Codex：

   Agent(
     subagent_type = "codex:codex-rescue",
     prompt = "Review this PR diff for the OneKey crypto wallet monorepo. Focus on:
   - Security vulnerabilities (secret leakage, auth bypass, supply-chain risks)
   - Runtime bugs (race conditions, null safety, memory leaks)
   - Architecture violations (import hierarchy, cross-platform issues)
   - Code quality (hooks safety, error handling, performance)
   Report each finding with: file:line, severity (Critical/High/Medium/Low), description, fix suggestion.
   
   Diff:
   ${FULL_DIFF}"
   )
   

2. 解析 Agent 结果，提取结构化发现
3. 合并到主要审查中：
   • 双方发现相同问题 → 标记为 {Cross-validated ✅}，自动提升为 🔵 高置信度
   • 仅 Codex 发现的问题 → 添加 [Codex] 标签，并手动审查以指定置信度
   • 仅主要审查发现的问题 → 正常纳入
4. 在报告中添加 Codex 交叉验证摘要 表（参见报告模板）

如果不可用： 静默跳过。在报告头部设置“Codex 交叉验证：⏭️ 未启用”。其他位置不要提及 Codex。

PR 评论分析

收集 PR 上的所有现有评论，包括机器人和人工评论，然后结合本地代码库上下文逐条分析。你拥有完整的源代码、类型系统和依赖关系图；大多数评论者只看到了差异。利用这一信息优势。

获取所有评论

使用 gh api 获取完整的用户元数据（包括用于检测机器人的 type 字段）：

# Top-level PR reviews (review bodies)
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
  --jq '[.[] | select(.body != "") | {author: .user.login, is_bot: (.user.type == "Bot"), body: .body, state: .state, association: .author_association}]'

# Inline review comments (file:line annotations)
gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
  --jq '[.[] | {author: .user.login, is_bot: (.user.type == "Bot"), path: .path, line: .line, body: .body, association: .author_association}]'

# General PR comments (issue-level)
gh api repos/{owner}/{repo}/issues/{pr_number}/comments \
  --jq '[.[] | {author: .user.login, is_bot: (.user.type == "Bot"), body: .body, association: .author_association}]'

机器人检测 — 使用 GitHub API 返回的 user.type == "Bot" 字段，而不是硬编码的用户名列表。这样无需维护即可自动覆盖任何机器人（现在和未来）。

如果不存在评论，在报告头部设置“PR 评论分析：⏭️ 无评论”，并跳过此部分。

分析框架

对于每条有实质内容的评论（跳过空白批准、CI 状态徽章和纯格式评论）：

判定	含义	操作
✅ 已确认	评论指出了真实问题	纳入审查结果，并标注来源 [<author>]
🔍 补充完善	问题真实存在，但分析较浅或修复方案有误	纳入审查结果，并结合你对代码库的了解提供更深入的修复指导
❌ 噪声	根据完整的代码库上下文来看，这不是问题	在“评论误报分析”中简要说明原因
📋 已覆盖	主要审查已发现该问题	交叉验证并提高置信度

利用你的本地优势：

• 完整源代码 — 跨文件追踪数据流，而不仅仅查看差异
• 类型系统 — 运行 tsc，端到端验证类型
• 架构 — 了解 OneKey 的导入层级和平台模式
• 依赖项 — 使用 yarn info、变更日志和实际漏洞可达性分析
• 运行时推理 — 分析状态流转、异步生命周期和竞态条件

当有人指出模糊问题时，深入检查源代码以确认或反驳。当评论遗漏上下文时（例如某个函数已在上游得到安全保护），解释原因。当评论正确时，补充更丰富的上下文。

交叉验证规则

• 评论与主要审查意见一致 → 标记为 {Cross-validated ✅}，提升为 🔵 高
• 仅评论中提到的问题，且你已确认 → 按适当的置信度纳入，并添加 [<author>] 标签
• 仅评论中提到的问题，且你无法确认或反驳 → 以 ⚪ 低纳入，并附上说明
• 你有证据反驳的评论 → 添加到“评论误报分析”部分

安全评论的特殊处理

对于与安全相关的评论（来自 Snyk/Dependabot 等机器人或人工审查者）：

• 漏洞报告 — 检查 OneKey 的使用场景中是否确实能触及存在漏洞的代码路径
• 许可证问题 — 根据 OneKey 的许可证政策进行核实
• 依赖项警报 — 检查被标记的版本是否确实在使用（而不只是在 lockfile 中）

分流：运行哪些检查

运行 git diff origin/x...HEAD --name-only 并匹配：

变更文件匹配项	加载
package.json、lockfiles、node_modules 补丁、patches/*.patch	[security-and-supply-chain.md] — 全面的供应链审查
**/auth/**、**/vault/**、**/signing/**、**/crypto/**、manifest.json、**/manifest/*.js	[security-and-supply-chain.md] — 全面的安全审查
任何包含业务逻辑的 .ts/.tsx 文件	[code-quality-patterns.md] — hooks、竞态条件、空值安全
.android.ts(x)、.ios.ts(x)、.native.ts(x)、.desktop.ts(x)、.ext.ts(x)、.web.ts(x)、原生模块、BigNumber 的使用	[onekey-platform-patterns.md] — 平台崩溃与数值安全
Shell 脚本（.sh）、CI 工作流（.yml）	[onekey-platform-patterns.md] — 构建与 CI 部分

无论文件类型如何，都务必检查：

• 意外提交的文件（.DS_Store、.env、node_modules）
• 是否违反导入层级（见下文）
• 是否存在可避免的重复实现，而已有稳定的辅助函数、hooks、服务或组件已涵盖相同行为（见下文）
• PR 描述是否与实际变更一致
• 运行 [quick-commands.md] 中的相关命令

导入层级（务必验证）

@onekeyhq/shared     <- FORBIDDEN to import from other OneKey packages
    ↓
@onekeyhq/components <- ONLY imports shared
    ↓
@onekeyhq/core       <- ONLY imports shared
    ↓
@onekeyhq/kit-bg     <- imports shared, core (NEVER components or kit)
    ↓
@onekeyhq/kit        <- imports shared, components, kit-bg
    ↓
apps/*               <- imports all

# Quick hierarchy violation check on changed files
git diff origin/x...HEAD --name-only | grep -E '\.tsx?$' | \
  while IFS= read -r f; do [ -f "$f" ] && grep -l "from.*@onekeyhq" "$f" 2>/dev/null; done | \
  while IFS= read -r f; do echo "=== $f ==="; grep "from.*@onekeyhq" "$f"; done

复用现有实现（务必验证）

对于新添加的辅助函数、hooks、服务、组件、常量、格式化器、验证器或业务逻辑：

• 在接受新代码之前，先在代码库中搜索用途相同的现有实现。
• 优先使用成熟的 OneKey API、组件、hooks、实用工具和服务方法，而不是在本地重复实现。
• 仅当现有抽象在语义上等效、稳定，且不会引入更严重的耦合时，才标记重复实现。
• 在每条复用问题中，注明可复用的现有文件/函数，并说明其为何涵盖了新行为。

文件风险分类

风险	模式	操作
严重	**/vault/**、**/signing/**、**/crypto/**、**/core/src/**、硬件钱包 SDK	逐行审查
高	**/auth/**、API 端点、状态管理、package.json、manifest.json	深入审查
中	UI 组件、特定平台代码、后台服务	标准审查
低	注释、仅类型代码、格式调整、测试、文档	扫描异常情况

评分系统

强制要求——每份报告都必须包含此评分表，无一例外。

从 4 个维度为 PR 评分（每项 1–10 分）：

维度	权重	评估内容
🔒 安全性	35%	密钥泄露、身份验证绕过、供应链风险、输入验证
💎 代码质量	30%	Hooks 安全性、错误处理、竞态条件、空值安全、DRY、复用已有实现
🏛️ 架构合理性	20%	导入层级、关注点分离、跨平台一致性
✅ 完整性	15%	边缘情况处理、测试覆盖率、迁移路径、文档

总分 = 加权平均分，四舍五入到小数点后 1 位。

分数	结论	操作
8.0 - 10.0	✅ 可直接合入	无阻塞问题，仅有少量建议
5.0 - 7.9	⚠️ 需修改后复审	存在应在合并前修复的问题
< 5.0	❌ 建议打回重做	安全性或架构方面存在根本性问题

评分基准——确保评分一致：

• 每个维度从 8 分起，根据发现的问题扣分
• 出现单个 P0 安全问题 → 安全性最高不超过 3 分
• 出现单个 P0 崩溃／运行时错误 → 代码质量最高不超过 5 分
• 违反导入层级 → 架构合理性最高不超过 4 分

置信度等级

强制要求——每项发现必须且只能使用以下三种表情标签之一。不要使用百分比，也不要使用没有表情的纯文本（如“高／中／低”）。始终使用以下格式：

标签	含义	使用时机
🔵 High	已确认，可从代码中验证	明确的错误、明显的违规、可复现的问题
🟠 Medium	可能存在问题，需要上下文	现有模式表明可能有问题，也可能是有意为之
⚪ Low	可能存在问题，需要人工检查	启发式匹配，取决于业务逻辑

交叉验证的发现（主审 + Codex 一致，或主审 + PR 评论一致）→ 自动标记为 🔵 High。

自动修复补丁

以下类别为强制要求——如果发现符合其中一类，必须包含差异补丁：

• console.error/warn/log → 项目日志记录器（defaultLogger）
• 可空 ref 缺少可选链
• 违反导入层级
• useEffect 中缺少清理逻辑
• BigNumber 类型强制转换（Number(decimals)）
• 联合类型定义中缺少类型

格式——始终使用以下确切结构：

**Auto-fix:**
\```diff
- old code
+ new code
\```

对于其他发现，如果修复方式明确且不需要业务上下文，也应包含自动修复方案。如有疑问，请一并提供——给出建议的修复方案总比不提供更有帮助。

不要为以下情况生成自动修复方案：

• 需要业务上下文才能确定的逻辑变更
• 需要架构决策的安全修复
• 存在权衡的性能优化

GH CLI 行内评论

生成报告后，如果有符合评论门槛的发现，请立即发布评论。不要询问“是否确认？”，也不要等待后续消息。新对话不会记得口头说过的“以后都自动发”——本节才是准则。

评论门槛：任何置信度的 P0，或置信度为 🔵 High 的 P1。这意味着：

• 所有 P0 发现（无论置信度如何）
• 所有置信度为 🔵 High 的 P1 发现（经交叉验证或从代码中确认）
• 不包括：P2 发现，以及置信度为 🟠 Medium 或 ⚪ Low 的 P1 发现

1. 列出符合条件、需要发布 PR 评论的发现
2. 在同一轮回复中发布评论；如可用，使用 ManagePullRequest post_comment（路径 + 行号），否则：

# Inline comment on specific file:line
gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
  --field body="**[P1] 问题标题**: 描述...

**建议修复:**
\`\`\`suggestion
修复代码
\`\`\`

_— Auto-review by Claude_" \
  --field path="path/to/file.tsx" \
  --field line=42 \
  --field side="RIGHT" \
  --field commit_id="$(git rev-parse HEAD)"

规则：

• 始终在发布审查报告的同一轮回复中发布符合条件的发现
• 仅发布符合评论门槛的发现（见上文）
• 有可用的自动修复方案时，将其包含在 suggestion 块中
• 每个 PR 最多发布 5 条行内评论
• GitHub 只能将审查评论附加到 PR 差异中的行；如果实际位置未更改，请在最近的已更改行上发表评论，并在评论正文中指出未更改的位置
• 如果现有行内讨论串已指出相同问题，请在该讨论串中回复，而不是重复创建

统一报告格式

重要：请严格遵循此模板。每份报告都必须包含所有标记为 [REQUIRED] 的部分。不得跳过或调整部分顺序。

# PR #NUMBER 代码审查报告

## 审查概要 [REQUIRED]
- **变更范围**: X 个文件, +Y / -Z 行
- **风险等级**: Critical / High / Medium / Low
- **涉及平台**: Extension / Mobile / Desktop / Web
- **Codex 交叉验证**: ✅ 已启用 / ⏭️ 未启用
- **PR 评论分析**: ✅ 已分析 (N 条评论, 其中 M 条来自 Bot) / ⏭️ 无评论

## 评分 [REQUIRED — NEVER SKIP THIS SECTION]

| 维度 | 得分 | 说明 |
|------|------|------|
| 🔒 安全性 | X/10 | 简要说明 |
| 💎 代码质量 | X/10 | 简要说明 |
| 🏛️ 架构合理性 | X/10 | 简要说明 |
| ✅ 完整性 | X/10 | 简要说明 |
| **总分** | **X.X/10** | **✅ 可直接合入 / ⚠️ 需修改后复审 / ❌ 建议打回** |

## Codex 交叉验证摘要 [REQUIRED if Codex was used, OMIT if not]

| 发现 | Primary | Codex | 状态 |
|------|---------|-------|------|
| 问题描述 | Yes/No | Yes/No | 交叉验证 / 仅 Primary / 仅 Codex |

## PR 评论分析 [REQUIRED if comments exist, OMIT if none]

| 来源 | 类型 | 发现 | 判定 | 说明 |
|------|------|------|------|------|
| Snyk | 🤖 Bot | 依赖漏洞 CVE-XXXX | ✅ Confirmed | 漏洞路径在 OneKey 中可达 |
| @reviewer | 👤 Human | 缺少 null check | 🔍 Enriched | 实际需要在上游 hook 中处理 |
| Devin | 🤖 Bot | 变量命名建议 | ❌ Noise | 命名符合项目规范 |

### 评论误报分析 [OMIT if no noise findings]
- **[来源] 误报**: 具体说明为什么这不是问题（引用源码上下文）

## 发现的问题 [REQUIRED]

### [P0] [🔵 High] 问题标题 {Cross-validated ✅}
**文件**: `path/to/file.tsx:42`
**类型**: 安全 / 构建 / 运行时 / 性能 / 规范
**描述**: 问题是什么，为什么有风险
**Auto-fix:**
\```diff
- old code
+ new code
\```

---

### [P1] [🟠 Medium] 问题标题
**文件**: `path/to/file.tsx:18`
**类型**: 运行时
**描述**: ...
**修复建议**: ...

---

## 修改清单 [REQUIRED]

| 优先级 | 置信度 | 文件 | 类型 | 描述 | Auto-fix |
|--------|--------|------|------|------|----------|
| P0 | 🔵 High | file1.tsx:42 | 安全 | 描述 | ✅ |
| P1 | 🟠 Medium | file2.tsx:18 | 运行时 | 描述 | — |

## 测试建议 [REQUIRED]
1. 测试场景
2. 测试场景

## GH 评论操作 [REQUIRED if qualifying findings exist, OMIT if none]
以下问题（P0 任意置信度，或 P1 + 🔵 High 置信度）建议直接评论到 PR：
- [ ] 问题1 — `file.tsx:42`
- [ ] 问题2 — `file.tsx:88`

> 达标问题已在本回合直接发为 inline comments，无需再确认。

优先级定义

必须遵守 — 每条发现都必须且只能带有一个 P0–P2 优先级标签。请勿使用高/中/低或 Critical/High/Medium/Low 作为发现的优先级标签。

优先级	标准	操作
P0	安全漏洞、密钥/资金泄露、数据丢失、崩溃、影响用户的运行时错误、构建失败	阻断项 — 合并前必须修复
P1	边缘情况错误、并发风险、健壮性不足、可维护性问题	应在合并前修复
P2	可有可无的小改进、轻微不一致、小问题（命名、注释、风格）	后续处理 / 可选

历史 PR 讨论串可能仍使用旧版 5 级标准；分析时，请将旧 P1 映射为 P0，旧 P2 映射为 P1，旧 P3/P4 映射为 P2。

审查规范

• 阅读代码 — 不要只用 grep。阅读每个有变更的文件，了解其意图。
• 避免误报 — 只报告你确信存在的问题。不确定？降低置信度。
• 不要吹毛求疵地挑风格问题 — 重点关注安全性、正确性、架构和性能。
• 结合上下文 — 提出修改建议前，先了解代码为何采用当前写法。
• 优先复用 — 接受新的抽象或重复的业务逻辑前，先搜索现有的本地实现，并指出不必要的重复实现及具体的复用目标。
• 确定优先级 — 3 条高质量发现胜过 20 条可有可无的意见。
• 如实评分 — 评分应反映实际情况，而非出于客套。
• 积极自动修复 — 修复方案明确时，务必附上 diff 补丁。审查者更喜欢可直接采取行动的建议。

参考文件

• references/security-and-supply-chain.md — PII 泄露、AuthN/AuthZ、供应链、清单权限
• references/code-quality-patterns.md — Hooks、竞态条件、空值安全、并发请求、错误处理
• references/onekey-platform-patterns.md — Android/iOS 崩溃、Fabric、BigNumber、构建/CI
• references/quick-commands.md — 用于自动检查的 Bash 单行命令