From 64ee4c71aa985f992c5a79e4a42b142581d5b2f3 Mon Sep 17 00:00:00 2001 From: FNS Service Date: Tue, 21 Apr 2026 11:17:53 +0800 Subject: [PATCH] Update from Sync Service --- 实践积累/code-reviewer技能.md | 517 +++++------------- .../fireworks-tech-graph技术图生成工具.md | 53 +- 2 files changed, 170 insertions(+), 400 deletions(-) diff --git a/实践积累/code-reviewer技能.md b/实践积累/code-reviewer技能.md index 1da950b..c8396e6 100755 --- a/实践积累/code-reviewer技能.md +++ b/实践积累/code-reviewer技能.md @@ -1,463 +1,242 @@ --- -name: code-reviewer -description: 这个 Skills 帮助进行代码审查，提供代码质量分析/报告生成、最佳实践建议和潜在问题识别。 +title: Code Reviewer 代码审查专家技能 +tags: + - AI-Skill + - Code-Review + - TDD + - Java + - Security +created: 2026-04-12 +source: 用户分享的SKILL文件 --- -# 代码审查专家 Skills -你是一个经验丰富的代码审查者，遵循业界最佳实践，提供专业的代码评估和改进建议。 + +# Code Reviewer 代码审查专家 + +> 经验丰富的代码审查者，遵循业界最佳实践，提供专业的代码评估和改进建议。 + ## 审查重点 -1. **代码质量** - - 命名规范 - - 代码复杂度 - - 重复代码 -2. **安全性** - - SQL 注入风险 - - XSS 漏洞 - - 认证授权问题 -3. **性能** - - 算法效率 - - 资源使用 - - 缓存策略 -4. **可维护性** - - 代码注释 - - 模块化设计 - - 测试覆盖 + +| 维度 | 内容 | +|------|------| +| **代码质量** | 命名规范、代码复杂度、重复代码 | +| **安全性** | SQL 注入风险、XSS 漏洞、认证授权问题 | +| **性能** | 算法效率、资源使用、缓存策略 | +| **可维护性** | 代码注释、模块化设计、测试覆盖 | + ## 审查流程 + 1. 理解代码变更的目的 2. 检查代码风格和规范 3. 分析潜在的 Bug 和性能问题 4. 验证安全性 5. 提供建设性的改进建议 -## 问题定位规范 -### 问题报告必须包含的位置信息 -每个发现的问题**必须**包含以下精确位置信息： +--- + +## 问题报告规范 + +每个问题必须包含以下**精确位置信息**： | 字段 | 说明 | 示例 | |------|------|------| -| **文件路径** | 相对于项目根目录的完整路径 | `hi-hydro-modules/hi-hydro-system/src/main/java/com/zhdgps/ims/system/service/impl/UserServiceImpl.java` | -| **行号范围** | 问题代码的起止行号 | `L45-L52` 或 `L45` | -| **类名** | 问题所在的类名 | `UserServiceImpl` | -| **方法名** | 问题所在的方法签名 | `getUserById(Long userId)` | -| **代码片段** | 有问题的具体代码（前后各保留2-3行上下文） | 见下方示例 | +| 文件路径 | 相对于项目根目录的完整路径 | `com/example/UserServiceImpl.java` | +| 行号范围 | 问题代码的起止行号 | `L45-L52` 或 `L45` | +| 类名 | 问题所在的类名 | `UserServiceImpl` | +| 方法名 | 问题所在的方法签名 | `getUserById(Long userId)` | +| 代码片段 | 有问题的具体代码（前后各 2-3 行上下文） | 见示例 | ### 问题输出格式 + ``` 🔴 [严重] SQL注入风险 -📁 文件: hi-hydro-modules/hi-hydro-system/src/main/java/.../UserServiceImpl.java +📁 文件: com/example/UserServiceImpl.java 📍 位置: L45-L48 | 类: UserServiceImpl | 方法: findByUsername(String) + 🔗 代码上下文: 44 | public User findByUsername(String username) { 45 | String sql = "SELECT * FROM user WHERE username = '" + username + "'"; 46 | return jdbcTemplate.queryForObject(sql, userMapper); 47 | } + 💡 问题说明: 直接拼接用户输入到SQL语句中，存在SQL注入风险 -✅ 修复建议: 使用参数化查询 + +✅ 修复建议: String sql = "SELECT * FROM user WHERE username = ?"; return jdbcTemplate.queryForObject(sql, userMapper, username); ``` +### 严重程度分级 + +| 级别 | 含义 | +|------|------| +| 🔴 严重 | 需要立即修复的问题 | +| 🟡 中等 | 建议修复的问题 | +| 🟢 轻微 | 可选的改进建议 | + +--- + ## 输出格式 -### 文本报告格式 -- ✅ **优点**：列出做得好的地方 -- ⚠️ **问题**：按以下格式详细列出每个问题 - ``` - [严重级别] 问题标题 - 📁 文件: 完整文件路径 - 📍 位置: L行号 | 类: 类名 | 方法: 方法签名 - 🔗 代码上下文: (带行号的代码片段) - 💡 问题说明: 详细描述问题原因和影响 - ✅ 修复建议: 具体的修复方案或示例代码 - ``` - 严重程度分类： - - 🔴 严重：需要立即修复的问题 - - 🟡 中等：建议修复的问题 - - 🟢 轻微：可选的改进建议 -- 📊 **总体评分**：1-10 分 -### HTML 报告生成（必选） + +### 文本报告 + +``` +✅ 优点：列出做得好的地方 + +⚠️ 问题： + [级别] 问题标题 + 📁 文件: 完整文件路径 + 📍 位置: L行号 | 类: 类名 | 方法: 方法签名 + 🔗 代码上下文: (带行号的代码片段) + 💡 问题说明: 详细描述 + ✅ 修复建议: 具体的修复方案或示例代码 + +📊 总体评分：1-10 分 +``` + +### HTML 报告（自动生成） + 当用户要求审查代码时，**自动生成 HTML 报告**： -#### 报告生成步骤 -1. **创建 HTML 报告文件**，包含以下内容： - - 页面标题和审查时间 - - 审查摘要和总体评分（大号显示，带进度条） - - 四个维度的评分卡片： - * 代码质量（Code Quality） - * 安全性（Security） - * 性能（Performance） - * 可维护性（Maintainability） - - **问题详情卡片**（每个问题一个独立卡片，包含）： - * 严重级别标识（Critical/Medium/Minor） - * 问题标题和详细描述 - * **精确位置信息**： - - 文件路径（可点击复制的完整路径） - - 行号范围（L45-L52 格式） - - 类名和方法签名 - - Git blame 风格的代码上下文展示 - * 带语法高亮的问题代码片段 - * 修复建议和示例代码 - - 优点列表 - - **变更统计摘要**（审查的文件数、问题总数、各级别问题数） -2. **样式要求**： - - 使用现代化的 CSS 设计（渐变背景、卡片阴影、圆角） - - 响应式布局，适配不同屏幕尺寸 - - 使用专业的配色方案 - - 代码块使用等宽字体和语法高亮 - - **代码上下文展示**： - - 类似 IDE 的行号显示 - - 问题行高亮标记（红色/黄色/绿色背景） - - 前后各展示3行上下文代码 - - 添加图标和视觉元素提升可读性 -3. **保存和预览**： - - 文件名格式：`code-review-report-{timestamp}.html` - - 保存到工作区根目录 -#### HTML 模板结构 -```html - - - - - - 代码审查报告 - - - - - - -``` -#### 问题卡片HTML模板 -每个问题使用以下结构： -```html -
-
- 🔴 严重 - SQL注入风险 -
-
-
-
📁 hi-hydro-modules/hi-hydro-system/.../UserServiceImpl.java
-
📍 行号: L45-L48 | 类: UserServiceImpl | 方法: findByUsername(String)
-
-
-
44 public User findByUsername(String username) {
-
45 String sql = "SELECT * FROM user WHERE username = '" + username + "'";
-
46 return jdbcTemplate.queryForObject(sql, userMapper);
-
47 }
-
-
- 💡 修复建议: 使用参数化查询防止SQL注入 - 
String sql = "SELECT * FROM user WHERE username = ?";
-return jdbcTemplate.queryForObject(sql, userMapper, username);
-
-
-
-``` -## 审查示例 +- 文件名格式：`code-review-report-{timestamp}.html` +- 保存到工作区根目录 +- 包含评分圆环、四维评分卡片、问题详情卡片 +- 代码上下文：IDE 风格行号 + 问题行高亮 -### 示例1: 命名规范问题（Java项目示例） -``` -🟢 [轻微] 方法命名不规范 -📁 文件: hi-hydro-modules/hi-hydro-system/src/main/java/com/zhdgps/ims/system/service/impl/UserServiceImpl.java -📍 位置: L78 | 类: UserServiceImpl | 方法: f(UserQuery) -🔗 代码上下文: - 76 | /** - 77 | * 查询用户列表 - 78 | */ -→ 79 | public List f(UserQuery query) { - 80 | return userMapper.selectList(query); - 81 | } -💡 问题说明: 方法名 f 过于简短，不符合Java命名规范，应使用有意义的名称 -✅ 修复建议: 重命名为 selectUserList 或 queryUserList -``` +--- + +## 典型问题示例 + +### 1. SQL 注入（🔴 严重） -### 示例2: 安全性问题（SQL注入） ``` -🔴 [严重] SQL注入风险 -📁 文件: hi-hydro-modules/hi-hydro-system/src/main/java/com/zhdgps/ims/system/service/impl/UserServiceImpl.java +📁 文件: UserServiceImpl.java 📍 位置: L45-L48 | 类: UserServiceImpl | 方法: findByUsername(String) + 🔗 代码上下文: - 43 | @Override - 44 | public User findByUsername(String username) { -→ 45 | String sql = "SELECT * FROM sys_user WHERE user_name = '" + username + "'"; -→ 46 | return jdbcTemplate.queryForObject(sql, userMapper); - 47 | } -💡 问题说明: 直接拼接用户输入到SQL语句，存在SQL注入漏洞 -✅ 修复建议: +→ 45 | String sql = "SELECT * FROM sys_user WHERE user_name = '" + username + "'"; +→ 46 | return jdbcTemplate.queryForObject(sql, userMapper); + +✅ 修复建议: 使用参数化查询 String sql = "SELECT * FROM sys_user WHERE user_name = ?"; return jdbcTemplate.queryForObject(sql, userMapper, username); ``` -### 示例3: 性能问题（循环内重复查询） +### 2. 循环内重复查询（🟡 中等） + ``` -🟡 [中等] 循环内重复数据库查询 -📁 文件: hi-hydro-modules/hi-hydro-flow/src/main/java/com/zhdgps/hydro/flow/service/impl/TaskServiceImpl.java 📍 位置: L112-L118 | 类: TaskServiceImpl | 方法: batchProcess(List) + 🔗 代码上下文: 110 | public void batchProcess(List tasks) { 111 | for (Task task : tasks) { → 112 | Device device = deviceMapper.selectById(task.getDeviceId()); → 113 | task.setDeviceName(device.getName()); -→ 114 | taskMapper.updateById(task); + 114 | taskMapper.updateById(task); 115 | } 116 | } -💡 问题说明: 循环内执行单条查询，N次循环导致N次数据库访问，严重影响性能 -✅ 修复建议: - // 批量查询设备，使用Map缓存 - Set deviceIds = tasks.stream().map(Task::getDeviceId).collect(Collectors.toSet()); + +✅ 修复建议: 批量查询 + Map 缓存 + Set deviceIds = tasks.stream().map(Task::getDeviceId).collect(toSet()); Map deviceMap = deviceMapper.selectBatchIds(deviceIds) - .stream().collect(Collectors.toMap(Device::getId, Function.identity())); + .stream().collect(toMap(Device::getId, d -> d)); tasks.forEach(task -> task.setDeviceName(deviceMap.get(task.getDeviceId()).getName())); - taskMapper.updateBatch(tasks); ``` -### 示例4: 资源泄漏问题 +### 3. 资源泄漏（🔴 严重） + ``` -🔴 [严重] 未关闭数据库连接资源 -📁 文件: hi-hydro-modules/hi-hydro-netty/src/main/java/com/zhdgps/ims/netty/handler/DataHandler.java 📍 位置: L56-L62 | 类: DataHandler | 方法: processData(Connection) + 🔗 代码上下文: - 54 | private void processData(Connection conn) { - 55 | try { → 56 | Statement stmt = conn.createStatement(); → 57 | ResultSet rs = stmt.executeQuery("SELECT * FROM data"); 58 | // 处理数据... 59 | } catch (SQLException e) { 60 | log.error("处理失败", e); 61 | } - 62 | } -💡 问题说明: Statement和ResultSet未关闭，会导致资源泄漏和连接池耗尽 -✅ 修复建议: 使用try-with-resources自动关闭资源 + +✅ 修复建议: 使用 try-with-resources try (Statement stmt = conn.createStatement(); ResultSet rs = stmt.executeQuery("SELECT * FROM data")) { // 处理数据... - } catch (SQLException e) { - log.error("处理失败", e); } ``` -### 示例5: 空指针风险 +### 4. 空指针风险（🟡 中等） + ``` -🟡 [中等] 潜在空指针异常 -📁 文件: hi-hydro-modules/hi-hydro-iot/src/main/java/com/zhdgps/hydro/iot/service/impl/DeviceServiceImpl.java 📍 位置: L89-L92 | 类: DeviceServiceImpl | 方法: getDeviceStatus(Long) + 🔗 代码上下文: - 87 | public String getDeviceStatus(Long deviceId) { - 88 | Device device = deviceMapper.selectById(deviceId); → 89 | return device.getStatus().getName(); - 90 | } -💡 问题说明: device可能为null，直接调用getStatus()会抛出NullPointerException + ✅ 修复建议: Device device = deviceMapper.selectById(deviceId); - if (device == null) { - throw new ServiceException("设备不存在: " + deviceId); - } - return Optional.ofNullable(device.getStatus()) - .map(Status::getName) - .orElse("未知状态"); + if (device == null) throw new ServiceException("设备不存在: " + deviceId); + return Optional.ofNullable(device.getStatus()).map(Status::getName).orElse("未知状态"); ``` + +### 5. 命名不规范（🟢 轻微） + +``` +📍 位置: L79 | 类: UserServiceImpl | 方法: f(UserQuery) + +🔗 代码上下文: +→ 79 | public List f(UserQuery query) { + +✅ 修复建议: 重命名为 selectUserList 或 queryUserList +``` + +--- + ## 评分标准 -### 总体评分（1-10分） -- **9-10分**：优秀，代码质量高，几乎没有问题 -- **7-8分**：良好，有少量改进空间 -- **5-6分**：中等，存在一些需要修复的问题 -- **3-4分**：较差，有较多问题需要解决 -- **1-2分**：很差，存在严重问题 -### 各维度评分 -每个维度（代码质量、安全性、性能、可维护性）独立评分： -- **优秀（8-10）**：符合最佳实践 -- **良好（6-7）**：基本合格，有改进空间 -- **需改进（4-5）**：存在明显问题 -- **差（1-3）**：有严重缺陷 -## 使用示例 -当用户说"帮我审查这段代码"或"review 这个文件"时： + +### 总体评分（1-10 分） + +| 分数 | 评价 | +|------|------| +| 9-10 | 优秀，代码质量高，几乎没有问题 | +| 7-8 | 良好，有少量改进空间 | +| 5-6 | 中等，存在一些需要修复的问题 | +| 3-4 | 较差，有较多问题需要解决 | +| 1-2 | 很差，存在严重问题 | + +--- + +## 使用方法 + +当用户说"审查代码"或"review 这个文件"时： + 1. 仔细分析代码，记录每个问题的精确位置 2. 使用 Read/Grep 工具确认代码位置和上下文 -3. 识别问题和优点，为每个问题收集： - - 完整文件路径 - - 精确行号范围 - - 所在类名和方法签名 - - 相关代码片段（含上下文） -4. 生成详细的 HTML 报告（包含精确位置信息和代码上下文） +3. 识别问题和优点，为每个问题收集：文件路径、行号范围、类名、方法签名、代码片段 +4. 生成详细的 HTML 报告 5. 告知用户报告已生成并可以查看 +--- + ## 代码位置识别指南 -### 如何精确定位问题代码 -1. **文件路径**: 从项目根目录开始的完整相对路径 -2. **行号**: 使用工具读取文件时记录精确行号，问题涉及多行时标注范围 -3. **类名和方法名**: 从代码结构中识别： - - Java: `public class ClassName` 和 `public ReturnType methodName(Params)` - - Python: `class ClassName:` 和 `def method_name(self, ...):` - - JavaScript: `class ClassName` 和 `methodName(params) {` -4. **代码上下文**: 提取问题行及其前后各2-3行，确保上下文完整 - ### 行号标注规范 -- 单行问题: `L45` -- 连续多行问题: `L45-L52` -- 不连续多行: `L45, L48, L52` -- 方法/类范围: `L45-L78 (method: getUserById)` + +| 类型 | 格式 | 示例 | +|------|------|------| +| 单行问题 | `L45` | `L45` | +| 连续多行 | `L45-L52` | `L45-L52` | +| 不连续多行 | `L45, L48, L52` | `L45, L48, L52` | ### 代码上下文格式 + ``` 行号 | 代码内容 -----|---------------------------------------- 43 | @Override 44 | public User getUserById(Long userId) { -→ 45 | String sql = "SELECT * FROM user WHERE id = " + userId; // ← 问题行 +→ 45 | String sql = "SELECT * FROM user WHERE id = " + userId; 46 | return jdbcTemplate.queryForObject(sql, userMapper); 47 | } ``` + - 使用 `→` 标记问题行 -- 保留前后2-3行上下文 -- 行号右对齐，保持整齐 \ No newline at end of file +- 保留前后 2-3 行上下文 +- 行号右对齐，保持整齐 diff --git a/实践积累/fireworks-tech-graph技术图生成工具.md b/实践积累/fireworks-tech-graph技术图生成工具.md index 33f8f18..b567c0d 100755 --- a/实践积累/fireworks-tech-graph技术图生成工具.md +++ b/实践积累/fireworks-tech-graph技术图生成工具.md @@ -19,38 +19,35 @@ language: Python ## 概述 -将自然语言描述转化为精美的 SVG 技术图，并通过 `rsvg-convert` 导出高分辨率 PNG。内置 **7 种视觉风格**，深度覆盖 AI/Agent 领域常见图类型（RAG、Agentic Search、Mem0、Multi-Agent、Tool Call 流程等），并完整支持全部 14 种 UML 图类型。 - -```用户: "画一张 Mem0 的架构图，暗黑风格" - → Skill 识别：Memory Architecture Diagram，Style 2 - → 生成含泳道、圆柱体、语义箭头的 SVG - → 导出 1920px PNG - → 输出路径：mem0-architecture.svg / mem0-architecture.png -``` +将自然语言描述转化为精美的 SVG 技术图，并通过 `rsvg-convert` 导出高分辨率 PNG。内置 **7 种视觉风格**，深度覆盖 AI/Agent 领域常见图类型，并完整支持全部 14 种 UML 图类型。 ## 7 种视觉风格 | # | 名称 | 背景色 | 字体 | 适用场景 | |---|------|--------|------|----------| -| 1 | **扁平图标风** *(默认)* | `#ffffff` | Helvetica | 博客、幻灯片、技术文档 | -| 2 | **暗黑极客风** | `#0f0f1a` | SF Mono / Fira Code | GitHub README、开发者文章 | -| 3 | **工程蓝图风** | `#0a1628` | Courier New | 架构设计文档、工程规范 | -| 4 | **Notion 极简风** | `#ffffff` | system-ui | Notion、Confluence、内部 Wiki | -| 5 | **玻璃态卡片风** | `#0d1117` 渐变 | Inter | 产品官网、演讲 Keynote | -| 6 | **Claude 官方风格** | `#f8f6f3` | system-ui | Anthropic 风格图表，温暖专业 | -| 7 | **OpenAI 官方风格** | `#ffffff` | system-ui | OpenAI 风格图表，简洁现代设计 | +| 1 | 扁平图标风（默认） | `#ffffff` | Helvetica | 博客、幻灯片、技术文档 | +| 2 | 暗黑极客风 | `#0f0f1a` | SF Mono / Fira Code | GitHub README、开发者文章 | +| 3 | 工程蓝图风 | `#0a1628` | Courier New | 架构设计文档、工程规范 | +| 4 | Notion 极简风 | `#ffffff` | system-ui | Notion、Confluence、内部 Wiki | +| 5 | 玻璃态卡片风 | `#0d1117` 渐变 | Inter | 产品官网、演讲 Keynote | +| 6 | Claude 官方风格 | `#f8f6f3` | system-ui | Anthropic 风格图表 | +| 7 | OpenAI 官方风格 | `#ffffff` | system-ui | OpenAI 风格图表 | ## 支持的图类型 ### AI/Agent 领域（内置 Pattern） -- **RAG Pipeline** — Query → Embed → VectorSearch → Retrieve → LLM → Response -- **Agentic RAG** — RAG + Agent 循环 + 工具调用 -- **Agentic Search** — Query → Planner → [Search/Calc/Code] → Synthesizer -- **Mem0 记忆层** — Input → Memory Manager → [VectorDB + GraphDB] → Context -- **Multi-Agent** — Orchestrator → [SubAgent×N] → Aggregator → Output -- **Tool Call 流程** — LLM → Tool Selector → Execution → Parser → LLM (循环) + +| 类型 | 流程 | +|------|------| +| RAG Pipeline | Query → Embed → VectorSearch → Retrieve → LLM → Response | +| Agentic RAG | RAG + Agent 循环 + 工具调用 | +| Agentic Search | Query → Planner → [Search/Calc/Code] → Synthesizer | +| Mem0 记忆层 | Input → Memory Manager → [VectorDB + GraphDB] → Context | +| Multi-Agent | Orchestrator → [SubAgent×N] → Aggregator → Output | +| Tool Call 流程 | LLM → Tool Selector → Execution → Parser → LLM（循环） | ### UML 支持（14 种） + 类图、组件图、部署图、包图、复合结构图、对象图、用例图、活动图、状态机图、序列图、通信图、时序图、交互概览图、ER 图 ## 形状词汇表 @@ -105,19 +102,13 @@ sudo apt install librsvg2-bin # Ubuntu/Debian ⭐⭐⭐⭐⭐（5/5） **优点**： -- 7种风格覆盖所有场景 -- 内置AI/Agent领域知识，开箱即用 -- 语义形状+箭头系统，图示专业 +- 7 种风格覆盖所有场景 +- 内置 AI/Agent 领域知识，开箱即用 +- 语义形状 + 箭头系统，图示专业 - 中文支持友好 **局限**： - 需要 Claude Code 或兼容 Skill 运行时 - 依赖 rsvg-convert 工具 -**适合场景**：技术博客配图、架构文档、PPT素材、GitHub README - -## 相关工具 - -- [[OpenPencil]] — 设计编辑器（开源Figma替代） -- [[code-reviewer]] — 代码审查技能 - +**适合场景**：技术博客配图、架构文档、PPT 素材、GitHub README