From f5dd23d4d64c34cd77df628d540feb78dc9d03c9 Mon Sep 17 00:00:00 2001 From: tinkle-community Date: Thu, 27 Nov 2025 03:40:56 +0800 Subject: [PATCH] chore: remove .claude directory --- .claude/commands/20-code-review.md | 329 ----------------------------- 1 file changed, 329 deletions(-) delete mode 100644 .claude/commands/20-code-review.md diff --git a/.claude/commands/20-code-review.md b/.claude/commands/20-code-review.md deleted file mode 100644 index f0477a21..00000000 --- a/.claude/commands/20-code-review.md +++ /dev/null @@ -1,329 +0,0 @@ ---- -name: code-review -description: 通用代码审查命令，基于业务需求进行白盒逻辑正确性审查和技术架构评估 ---- - -# 代码审查命令 - -## 审查任务 - -请对当前工作区的代码修改进行全面审查，重点关注业务逻辑的正确性和技术架构的合理性。 - -## 审查维度 - -### 1. 业务层面审查（BLOCKING级别） -- **需求来源验证**：寻找并验证业务需求来源（不能基于代码反推需求） -- **需求实现完整性**：验证代码是否100%满足业务需求 -- **业务流程逻辑正确性**：检查状态转换、数据流、条件判断的逻辑 -- **数据结构正确性**：验证模型定义、字段约束、业务规则映射 -- **Edge Case处理**：评估边界条件和异常场景的处理合理性 - -### 2. 技术层面审查 -- **架构合理性**：模块化、职责分离、依赖关系 -- **KISS原则遵循**：避免过度工程化 -- **扩展性评估**：未来功能添加的容易程度 -- **非Adhoc修改验证**：是否遵循现有代码模式 -- **性能问题检测**：查找明显的性能问题（如N+1查询等） -- **单元测试完备性**：核心逻辑90%覆盖率要求 - -### 3. 契约与连通性专项检查（BLOCKING） -- 端点一致性：前端端点集中配置；路径/动态段/大小写/末尾分隔符与后端路由完全一致；HTTP 方法语义匹配（幂等/副作用）。 -- 认证与跨域：统一的认证机制（会话/令牌）；前端传递方式与后端期望一致（Cookie/Authorization 等）；跨域与 CSRF 策略匹配。 -- 请求/响应 Schema：字段名、类型、必选/可选一致；时间/数值/布尔的编码一致；分页/排序参数与响应元信息对齐。 -- 错误与状态码：4xx/5xx 使用合理；错误负载结构稳定且可解析；前端根据错误类型提供可恢复提示。 -- 异步/事件（如有）：事件类型与载荷字段与文档一致；开始/结束/错误/心跳等语义完整；增量合并无丢失/重复；存在降级路径。 -- 端到端透传：API→Service→下游（存储/第三方）参数（上下文/会话/区域/幂等键）无遗漏；写操作具备幂等/去重策略。 -- 日志与隐私：日志含必要上下文（追踪/用户/会话），敏感信息脱敏；UI 默认不展示内部实现细节。 - -#### 全链路 Contract Crosswalk（必做） -- 选取关键用户流，建立“参数对齐矩阵”： - - 前端请求 → 后端路由/处理 → 服务层 → 下游（存储/第三方）→ 持久化字段。 - - 列出每个参数：`name | type | required | default | source-of-truth(文件:行)`。 - - 如存在事件/流式契约，补充事件类型与载荷字段，以及必要的状态回写。 -- 输出差异点与最小修复建议（谁改、改哪、如何不破坏现有行为）。 - -### 4. 高发问题清单（优先排查） -- 命名错位：不同层对同一概念使用了不同命名风格或名称（例如 `camelCase` ↔ `snake_case`、标识符命名不一致）。 -- 路径错位：端点路径或动态段命名不一致；末尾分隔符导致重定向或方法失败。 -- 类型漂移：数字/字符串/布尔/时间类型在层间编码不一致或未正确转换。 -- 认证混用：请求在不同处使用了不同认证方式；跨域请求未按需携带凭证；CSRF 保护缺失。 -- 事件缺口：后端新增事件类型或字段未在前端解析；增量合并逻辑导致重复/丢失。 -- 可见性/状态：后端状态位或可见性字段被忽略，导致 UI 展示与真实状态不一致。 - -### 5. 零假设验证（VERIFY-FIRST Gate，BLOCKING） -- 禁止基于“猜测的字段/API/事件”写逻辑。每个关键元素必须给出证据： - - 模型/字段定义位置（文件:行） - - 路由/处理方法签名（文件:行） - - 前端类型/解析/调用代码（文件:行） -- 无证据的假设一律不通过。 - -### 6. 用户视角 E2E 可见性审计（BLOCKING） -⚠️ **这是最关键的检查** - "代码完美但功能不工作"的主要原因就是跳过了这一步！ - -**MANDATORY USER FLOW VERIFICATION (必须执行):** -- **完整点击路径追踪**：从用户点击开始，逐步追踪到最终状态 - - 用户点击X → 调用函数Y → 导航到页面Z → 显示内容W - - **必须验证每个步骤都正确执行** -- **URL路由验证**：所有导航路径在路由配置中存在且正确处理参数 -- **状态传递验证**：点击后的状态变化是否正确反映在UI中 -- **错误场景测试**：参数缺失、网络错误、权限不足等场景的处理 - -**具体检查项目:** -- 入口可见：对应功能的入口（按钮/导航/控件）在默认场景与目标设备上可达；不被误判条件隐藏。 -- **链接落地（核心）**：页面路由/回跳/深链接一致；从入口到完成形成闭环。 - - 点击通知 → 是否真的跳转到预期页面？ - - 分享链接 → 是否真的加载预期内容？ - - 所有导航路径都必须实际追踪验证！ -- 状态完整：加载/空数据/错误/权限不足 均有清晰呈现与可恢复路径。 -- 角色/开关：与权限/Feature Flag 的可见性符合预期；默认值不阻断主流程。 - -**⛔ 禁止行为:** -- ❌ 只看代码结构，不追踪实际执行流程 -- ❌ 假设navigate()调用就等于用户到达了目标页面 -- ❌ 不验证URL参数处理逻辑 -- ❌ 说"看起来正确"而不验证"实际正确" - -### 7. Web3 AI 交易系统安全审查（BLOCKING 级别） -🔐 **资金安全是生死线** - 一个安全漏洞可能导致所有资金损失！ - -#### 7.1 私钥与密钥管理（CRITICAL） -- **零泄露原则**： - - ❌ 禁止：私钥/助记词出现在日志、错误消息、前端代码、Git 历史中 - - ❌ 禁止：明文存储私钥（环境变量、配置文件、数据库） - - ✅ 必需：使用硬件钱包、HSM、或加密密钥管理服务（AWS KMS/Vault） - - ✅ 必需：API Key、密钥材料必须加密存储，运行时解密 -- **最小权限原则**： - - 交易签名密钥与只读查询密钥分离 - - 每个功能使用独立的子账户/权限 - - 定期轮换 API Key 和访问令牌 -- **验证检查**： - - [ ] grep 搜索 `private_key`、`mnemonic`、`seed` 等关键词，确保无硬编码 - - [ ] 检查所有密钥存储位置的加密状态 - - [ ] 验证密钥访问日志和审计追踪 - -#### 7.2 交易安全（CRITICAL） -- **签名验证**： - - ✅ 必需：所有交易必须经过签名验证 - - ✅ 必需：验证交易发起者身份（防止伪造） - - ✅ 必需：使用 nonce/序列号防止重放攻击 -- **交易参数验证**： - - ✅ 必需：验证接收地址合法性（checksum、白名单） - - ✅ 必需：金额/价格/滑点限制（防止异常大额交易） - - ✅ 必需：Gas Price/Gas Limit 上限保护（防止 Gas 耗尽攻击） - - ✅ 必需：Deadline/超时保护（防止过期交易执行） -- **滑点与价格保护**： - - ✅ 必需：设置合理的滑点容忍度（如 0.5%-2%） - - ✅ 必需：价格预言机验证（多源对比、时间戳检查） - - ✅ 必需：异常价格波动拒绝交易 -- **验证检查**： - - [ ] 所有交易调用都有 nonce 或幂等键 - - [ ] 金额/价格参数都有上下限验证 - - [ ] Gas 费用有最大限制 - - [ ] 滑点保护代码存在且正确 - -#### 7.3 AI 决策安全（CRITICAL） -- **提示注入防护**： - - ❌ 禁止：直接将用户输入拼接到 AI prompt 中 - - ✅ 必需：用户输入消毒/转义（防止 prompt injection） - - ✅ 必需：系统提示与用户输入明确分离（使用角色隔离） - - ✅ 必需：敏感操作需要用户明确确认，AI 不能自主决定大额交易 -- **决策审计**： - - ✅ 必需：记录所有 AI 决策的完整上下文（输入、输出、时间戳、模型版本） - - ✅ 必需：决策可追溯、可回放、可审计 - - ✅ 必需：异常决策告警（如突然的大额交易建议） -- **模型安全**： - - ✅ 必需：使用官方 API，避免第三方代理（防止中间人攻击） - - ✅ 必需：API 响应验证（检测异常输出、格式错误） - - ✅ 必需：模型输出不直接执行，必须经过参数验证 -- **验证检查**： - - [ ] 搜索用户输入拼接点，确保有消毒处理 - - [ ] 检查决策日志是否完整（包含所有关键参数） - - [ ] 验证大额交易需要额外确认机制 - -#### 7.4 智能合约交互安全（CRITICAL） -- **授权范围控制**： - - ❌ 禁止：无限授权（`approve(spender, type(uint256).max)`） - - ✅ 必需：按需授权，每次交易前计算精确授权额度 - - ✅ 必需：定期清理过期授权 - - ✅ 必需：监控授权事件，异常授权告警 -- **合约调用验证**： - - ✅ 必需：合约地址白名单（只与已审计合约交互） - - ✅ 必需：函数选择器验证（防止调用错误函数） - - ✅ 必需：调用参数类型/范围验证 - - ✅ 必需：模拟执行（dry-run）后再真实执行 -- **重入与异常处理**： - - ✅ 必需：处理合约调用失败情况（revert、out of gas） - - ✅ 必需：检查返回值，不假设调用成功 - - ✅ 必需：避免在外部调用后修改关键状态（防重入） -- **验证检查**： - - [ ] grep `approve` 确保无无限授权 - - [ ] 所有合约地址来自配置/白名单，无硬编码 - - [ ] 调用失败有完整的错误处理和回退逻辑 - -#### 7.5 资金保护机制（BLOCKING） -- **限额控制**： - - ✅ 必需：单笔交易金额上限（如 $1000） - - ✅ 必需：日/周/月累计限额 - - ✅ 必需：异常交易频率限制（防止快速耗尽资金） - - ✅ 必需：大额交易需要多重签名或延迟执行 -- **紧急暂停**： - - ✅ 必需：全局紧急停止按钮（kill switch） - - ✅ 必需：异常检测自动暂停（如价格异常、Gas 费暴涨） - - ✅ 必需：暂停后资金安全提取机制 -- **余额监控**： - - ✅ 必需：实时余额监控，低于阈值告警 - - ✅ 必需：异常资金流出告警（大额转出、未知接收方） - - ✅ 必需：定期对账（链上余额 vs 系统记录） -- **验证检查**： - - [ ] 限额配置存在且合理 - - [ ] 紧急暂停功能可测试且有权限控制 - - [ ] 余额监控代码存在且接入告警系统 - -#### 7.6 链上数据验证（CRITICAL） -- **预言机安全**： - - ❌ 禁止：单一数据源（可被操纵） - - ✅ 必需：多预言机对比（Chainlink、Band、UMA 等） - - ✅ 必需：价格偏差检测（多源价格差异超阈值拒绝） - - ✅ 必需：时间戳验证（数据新鲜度检查，拒绝过期数据） -- **区块确认**： - - ✅ 必需：等待足够的区块确认（主网建议 ≥12 块，L2 根据实际情况） - - ✅ 必需：处理链重组可能（pending → confirmed → finalized） - - ✅ 必需：交易回执验证（status=1 成功） -- **数据完整性**： - - ✅ 必需：事件日志完整性检查（topic、参数匹配） - - ✅ 必需：合约状态一致性验证（链上 vs 本地缓存） - - ✅ 必需：MEV 保护（使用私有内存池或 Flashbots） -- **验证检查**： - - [ ] 价格数据来自多个预言机 - - [ ] 区块确认数配置合理 - - [ ] 交易状态检查包含 finalized 状态 - -## 审查结果 - -请给出以下三种结果之一： -- ✅ **通过**：可以直接提交 -- ❌ **不通过**：存在BLOCKING问题，必须修复 -- ⚠️ **需要修复**：有改进空间，建议修复 - -## 核心原则 - -1. **白盒逻辑正确性是根本**：业务逻辑错误是生死线 -2. **需求驱动**：必须找到真实需求来源 -3. **客观分析**：基于实际代码和需求，不自我欺骗 -4. **actionable建议**：提供具体的修复指导 - -## 评审交付物（必须包含） -- **问题清单**：逐条指出"谁与谁不一致"（路径/参数/字段/事件/状态码），附最小复现样本。 -- **最小修复建议**：明确"谁改、改哪里、如何不破坏现有调用"（可附 1-3 行级 diff 建议）。 -- **兼容/过渡策略**：必要时说明双解析/版本前缀/灰度开关/降级方案。 -- **🚨 E2E验证报告**：对每个用户交互流程的完整追踪验证（MANDATORY） - -## 强制性E2E验证清单（必须逐项检查） -在给出审查结果前，必须完成以下验证： - -### ✅ 用户点击验证 -- [ ] 所有onClick处理器都能正确执行 -- [ ] 处理器中的navigate()调用指向正确的路径 -- [ ] 目标路径在路由配置中存在 -- [ ] 目标页面能正确处理URL参数 - -### ✅ 导航流程验证 -- [ ] 从点击到页面加载的完整路径畅通 -- [ ] URL参数正确传递和解析 -- [ ] 页面状态正确初始化 -- [ ] 用户看到预期的内容和界面 - -### ✅ 状态一致性验证 -- [ ] 点击后应用状态正确更新 -- [ ] UI界面反映状态变化 -- [ ] 没有状态不同步的问题 - -### ✅ 安全验证（Web3 AI 交易系统 - MANDATORY） -- [ ] **密钥安全**：无私钥泄露（日志/错误/前端/Git） -- [ ] **密钥管理**：私钥加密存储，无明文环境变量 -- [ ] **交易验证**：所有交易有签名验证、nonce、金额限制 -- [ ] **滑点保护**：价格/滑点验证存在且合理 -- [ ] **AI 安全**：用户输入有消毒处理，无直接拼接到 prompt -- [ ] **决策审计**：AI 决策有完整日志（输入/输出/时间戳） -- [ ] **合约安全**：无无限授权，合约地址来自白名单 -- [ ] **限额保护**：存在单笔/累计交易限额 -- [ ] **紧急机制**：有 kill switch 或暂停功能 -- [ ] **预言机安全**：价格数据来自多源，有偏差检测 -- [ ] **确认机制**：大额交易需要用户明确确认 - -### ⛔ 审查失败条件 -如果以下任一项为真，审查必须标记为❌不通过： - -**功能性问题：** -- 存在navigate()指向不存在或错误的路径 -- 用户点击后无法到达预期页面 -- 状态更新不完整导致UI不一致 -- 关键用户流程无法完成 - -**安全性问题（Web3 AI 系统）：** -- 私钥/助记词出现在日志、错误消息、前端代码、Git 历史中 -- 私钥明文存储（环境变量/配置文件/数据库） -- 交易缺少签名验证、nonce、或金额限制 -- 存在无限授权（`approve(spender, type(uint256).max)`） -- 用户输入直接拼接到 AI prompt（prompt injection 风险） -- AI 可以自主决定大额交易（无用户确认） -- 缺少紧急暂停机制 -- 单一预言机数据源（可被操纵） -- 大额交易无多重签名或延迟执行 - -**记住：代码编译通过 ≠ 功能正确工作 ≠ 资金安全** - -## 技术验证方法（MANDATORY） - -### 🔍 导航路径验证脚本 -执行以下检查来验证导航逻辑： -```bash -# 1. 找出所有navigate()调用 -grep -r "navigate(" frontend/src --include="*.tsx" --include="*.ts" -n - -# 2. 找出所有路由定义 -grep -r "path=" frontend/src --include="*.tsx" --include="*.ts" -n - -# 3. 检查URL参数处理 -grep -r "useSearchParams\|URLSearchParams" frontend/src --include="*.tsx" --include="*.ts" -n -``` - -### 🔍 状态管理验证 -```bash -# 检查状态更新逻辑 -grep -r "useState\|useEffect.*navigate" frontend/src --include="*.tsx" --include="*.ts" -n - -# 检查onClick处理器 -grep -r "onClick.*=>" frontend/src --include="*.tsx" --include="*.ts" -n -``` - -### 🚨 必须回答的验证问题 -对于每个用户交互，审查者必须回答： - -1. **点击发生什么？** - - onClick处理器具体做了什么操作？ - - 调用了哪些函数？传递了什么参数？ - -2. **导航去哪里？** - - navigate()的目标路径是什么？ - - 这个路径在路由配置中存在吗？ - - 路径参数格式正确吗？ - -3. **目标页面做什么？** - - 目标页面/组件如何处理URL参数？ - - 是否正确提取和使用参数？ - - 用户最终看到什么内容？ - -4. **状态是否一致？** - - 点击后应用状态如何变化？ - - UI是否正确反映状态变化？ - - 有没有状态不同步问题？ - -**如果审查者无法回答这些问题，审查必须标记为❌不通过** - -## 快速验证提示 -- 端点集中来源：前端禁止硬编码 URL；新增/变更端点已同步到常量/SDK。 -- 认证一致：跨域/跨端口请求按需携带凭证（Cookie/Token），不依赖未声明的自定义头。 -- 异步降级：在不支持事件/流式或网络异常时具备降级路径与用户提示。 -- 可见性扫描：关键入口在默认态与目标设备上可见；空/错误/加载可复现且可恢复。 -- 自动化检查：加入简单脚本/CI 规则检查硬编码端点、路径格式、必需认证头/凭证的使用一致性。