code-visual-review

Code Visual Review v2.0.0

生成可视化的 HTML 代码审查页面，支持三种模式：

三种模式共享同一套暗色主题 HTML 模板，可在同一页面中混合使用。

v2.0.0 新增：Architecture 模式（合并自 architecture-review v1.0.0）

---

何时使用

Review 模式

• 代码审查（Code Review）时，需要比纯文本 diff 更直观的审查报告
• 需要向团队解释一个 PR 的变更范围和风险等级
• 需要生成带逐文件 diff + 风险标注 + 修改动机的 PR 描述

Walkthrough 模式

• 需要解释某个模块的调用链路和数据流
• 新人 onboarding 时理解代码结构
• 代码审查中解释复杂逻辑
• 标记安全边界和外部依赖

---

Review 模式：PR 审查

核心能力

1. PR 审查摘要页

   • PR 标题 + 动机 + TL;DR
   • 风险热力图：safe / worth a look / needs attention 三级标签
   • 逐文件 diff，带语法高亮和风险标注
   • Before/After 行为对比

2. PR 描述生成

   • 动机（Why）：解决了什么问题
   • 逐文件 Walkthrough：按阅读顺序排列，标注 why
   • Before/After 行为对比
   • 审查重点提示

使用指南

场景 1：PR 审查摘要

用户提供 PR diff 或 git 输出，生成包含以下结构的 HTML：

1. PR 标题 + 描述 — TL;DR 一句话总结
2. 风险地图 — 按文件列出风险等级
3. 逐文件 diff — 带语法高亮的 diff，标注风险标签
4. 审查建议 — 告诉审查者应该重点关注哪些

场景 2：PR 描述生成

用户提供分支名和变更文件列表，生成：

1. Why — 变更动机，Before/After 对比
2. File-by-file — 按阅读顺序排列的文件说明
3. Where to focus — 审查者应关注的文件

Review 模式 HTML 结构

<!-- 风险标签 -->
🟢 safe
🟡 worth a look
🔴 needs attention

<!-- 风险地图 -->

  src/auth.ts — 🟡 worth a look
  src/utils.ts — 🟢 safe


<!-- Diff 块 -->

  
    src/auth.ts
    +12 -3
  
  + new code here
  - old code here
    context line


<!-- Before/After 对比 -->

  
    Before
    
      行为描述 1
      行为描述 2
    
  
  
    After
    
      新行为 1
      新行为 2
    
  

---

Walkthrough 模式：代码理解

核心能力

1. 调用链路追踪

   • 从入口到出口的完整数据流
   • 模块间依赖关系图（boxes & arrows）
   • 每个步骤标注文件路径和行号

2. 代码标注

   • 关键逻辑逐步 Walkthrough
   • 可展开/折叠的源码块
   • 每个步骤的解释说明

3. 信任边界标注

   • 标注安全边界（哪些是可信的，哪些不可信）
   • 外部依赖标注
   • 数据验证点标注

使用指南

步骤 1：识别入口点

从用户可触达的入口开始（API endpoint、CLI 命令、Webhook 等）。

步骤 2：追踪调用链

沿数据流追踪到最终输出（数据库写入、响应返回、外部调用等）。 记录每一步：

• 文件路径和行号
• 函数名
• 关键逻辑说明

步骤 3：标注信任边界

标记：

• 可信区域：经过验证的数据、内部服务
• 不可信区域：用户输入、外部 API、第三方服务
• 验证点：数据校验、权限检查的位置

步骤 4：生成 HTML

将以上信息组织成自包含的 HTML 页面，包含：

1. Request Path — 可视化数据流
2. Call Stack Walkthrough — 逐步骤代码注解
3. Trust Boundary — 安全边界标注

Walkthrough 模式 HTML 结构

<!-- 请求路径图 -->

  [Browser]
  →
  [LB]
  →
  [API /api/session]
  →
  [verifyToken]
  →
  [SessionStore]


<!-- 调用步骤 -->

  1
  src/app/providers/AuthProvider.tsx:22-48
  On mount, the React provider issues GET /api/session...
  
    show source
    // source code here
  


<!-- 信任边界 -->

  ⚠️ Trust Boundary
  Everything below verifyToken is trusted. Everything above it is not.


<!-- 注解 -->

  This is where the JWT token is validated against the secret.

---

Architecture 模式：代码库架构分析（v2.0.0 新增）

合并自 architecture-review v1.0.0。将代码库架构分析结果以 HTML 可视化报告呈现。

执行流程

Phase 1: 代码库扫描

收集代码库的结构信息：

1. 目录结构 — 顶层目录和关键子目录
2. 模块划分 — 识别主要模块/包/命名空间
3. 依赖关系 — 模块间的导入/导出关系
4. 技术栈 — 语言、框架、关键依赖库
5. 代码指标 — 文件数量、代码行数（大致估算）

Phase 2: 架构分析

基于扫描数据，分析以下维度：

Phase 3: 生成 HTML 报告

1. 报告头部 — 项目名称、分析日期、分析范围
2. 执行摘要 — 整体健康度评分（1-10）+ 3-5个关键发现 + 最高优先级建议
3. 架构视图（Mermaid图表）— 模块依赖图 + 分层架构图 + 数据流图
4. 核心发现（卡片网格）— 每个发现一张卡片，标注强度徽章（Strong / Worth exploring / Speculative）
5. 技术债务清单 — 按严重程度排序，估算修复工作量，优先级建议
6. Before/After 对比 — 当前架构 vs 建议架构，关键改进点可视化
7. 推荐行动 — 按优先级排序，标注强度徽章，预估工作量

Architecture 模式 HTML 结构

<!-- 健康度评分 -->

  7.2
  /10


<!-- 模块依赖图（Mermaid） -->

  
graph TD
    classDef good fill:#d4edda,stroke:#28a745
    classDef warn fill:#fff3cd,stroke:#ffc107
    classDef bad fill:#f8d7da,stroke:#dc3545
    
    UI[UI Layer]:::good --> Service[Service Layer]:::good
    Service --> Repository[Repository Layer]:::warn
    Repository --> Database[(Database)]:::good
    Service --> ExternalAPI[External API]:::bad
  


<!-- 核心发现卡片 -->

  Strong
  循环依赖检测
  Module A 和 Module B 存在双向依赖，建议引入接口层解耦
  影响范围: 3 个文件


<!-- 技术债务清单 -->

  
    Critical
    过时依赖: lodash 4.17.15 (已知安全漏洞)
    修复工作量: 0.5h
  


<!-- Before/After 架构对比 -->

  
    当前架构
    
      扁平模块结构，无分层
      直接数据库访问
    
  
  
    建议架构
    
      引入 Service 层
      Repository 模式隔离数据访问
    
  

适用场景

Architecture 模式降级策略

---

组合模式

当审查同时需要多种视角时，可在同一页面中混合多种内容：

<!-- 先展示 diff 审查 -->

  Code Changes
  <!-- Review 模式 diff 内容 -->


<!-- 再展示调用链理解 -->

  Call Chain Impact
  <!-- Walkthrough 模式内容 -->


<!-- 最后展示架构影响 -->

  Architecture Impact
  <!-- Architecture 模式内容 -->

---

HTML 模板基础

所有输出使用统一的暗色主题模板，详见 templates/base.html。

核心特性：

• 单文件，无外部依赖（所有 CSS/JS 内联）
• 响应式布局，手机可读
• GitHub 风格 diff 配色（绿=新增，红=删除）
• 风险标签用颜色区分：🟢 safe / 🟡 worth a look / 🔴 needs attention
• 可折叠代码块（details/summary）
• 信任边界虚线框

CSS 变量：

:root {
  --bg: #0d1117;
  --surface: #161b22;
  --border: #30363d;
  --text: #c9d1d9;
  --text-muted: #8b949e;
  --accent: #58a6ff;
  --green: #2ea043;
  --red: #da3633;
  --yellow: #d29922;
  --diff-add-bg: rgba(46,160,67,0.15);
  --diff-del-bg: rgba(218,54,51,0.15);
}

---

与 coding-framework 集成

数据流

coding-framework 模式2（代理审查）
  → 输出审查结果（JSON/Markdown）
  → code-visual-review（Review 模式）
  → 生成可视化 HTML
用户浏览器 / canvas 呈现

调度入口

• Review 模式：coding-framework 模式2（代理审查）输出可输入本技能生成可视化页面
• Walkthrough 模式：coding-framework 模式2 中的 architecture-critic 代理可调用本技能生成架构审查的可视化辅助
• 安全守卫：Walkthrough 中标注的信任边界可供 coding-framework 模式4（安全守卫）参考

输入格式

接受以下输入：

1. git diff 输出
2. 代理审查的 JSON 结果
3. 手动提供的文件列表 + 变更说明
4. 入口文件路径 + 函数名（Walkthrough 模式）

---

错误处理与降级策略

Review 模式

Walkthrough 模式

渲染问题

---

注意事项

• 所有 CSS 和 JS 必须内联，不引用外部资源
• diff 颜色使用 GitHub 暗色主题配色
• 风险标签只用三种：🟢 safe / 🟡 worth a look / 🔴 needs attention
• 移动端必须可读（响应式网格）
• 如果 diff 太长，只显示关键变更行（上下文行省略）

---

文件结构

code-visual-review/
├── SKILL.md                    # 本文档
└── templates/
    └── base.html               # 共享 HTML 模板（暗色主题 + 响应式）

---

版本历史

---

Version 2.0.0 — 合并 architecture-review，三模式输出（Review + Walkthrough + Architecture）