code-visualizer

代码可视化技能

目的

自动生成并维护代码流程图。此技能会分析 Python 模块结构、检测导入关系并生成 mermaid 图表。它还会在代码发生变化但图表未更新时监控图表是否过时。

理念契合

此技能体现了 amplihack 的核心理念：

极致简洁

• 单一职责：仅可视化代码结构，不做其他事情
• 最少依赖：仅使用 Python AST 进行分析，将图表语法交给 mermaid-diagram-generator
• 不过度设计：基于时间戳检测是否过时，简单且对 90% 的情况来说「足够好」

零废话实现

• 真实分析：实际解析 Python AST 以提取导入信息，不使用模拟数据
• 坦诚说明局限性：过时检测基于时间戳，而非语义（参见「局限性」部分）
• 可运行代码：展示的所有算法均可运行，并非伪代码

模块化设计（积木与接口）

• 此技能是一个积木：代码分析和过时检测
• 委托给其他积木：语法交给 mermaid-diagram-generator，复杂图表交给 visualization-architect
• 清晰的接口（公开契约）：分析模块、生成图表、检查是否最新

技能委托架构

code-visualizer (this skill)
├── Responsibilities:
│   ├── Python module analysis (AST parsing)
│   ├── Import relationship extraction
│   ├── Staleness detection (timestamp-based)
│   └── Orchestration of diagram generation
│
└── Delegates to:
    ├── mermaid-diagram-generator skill
    │   ├── Mermaid syntax generation
    │   ├── Diagram formatting and styling
    │   └── Markdown embedding
    │
    └── visualization-architect agent
        ├── Complex multi-level architecture
        ├── ASCII art alternatives
        └── Cross-module dependency graphs

调用模式：

# code-visualizer analyzes code structure
modules = analyze_python_modules("src/")
relationships = extract_import_relationships(modules)

# Then delegates to mermaid-diagram-generator for syntax
Skill(skill="mermaid-diagram-generator")
# Provide: Module relationships, diagram type (flowchart/class), styling preferences
# Receive: Valid mermaid syntax ready for embedding

# For complex architectures, delegates to visualization-architect
Task(subagent_type="visualization-architect", prompt="Create multi-level diagram for...")

何时使用此技能

• 创建新模块：为新模块自动生成架构图
• PR 审查：展示拟议更改对架构的影响
• 过时检测：检查现有图表是否反映当前代码
• 依赖分析：可视化导入关系
• 重构：更改前了解模块依赖关系

快速入门

为模块生成图表

User: Generate a code flow diagram for the authentication module

检查图表是否为最新

User: Are my architecture diagrams up to date?

查看 PR 影响

User: What architecture changes does this PR introduce?

核心功能

1. 模块分析

分析 Python 文件以提取：

• 导入语句（内部和外部）
• 类定义和继承关系
• 函数导出（__all__）
• 模块依赖关系

2. 图表生成

创建 mermaid 图表以展示：

• 模块关系（流程图）
• 类层次结构（类图）
• 组件间的数据流
• 依赖关系图

3. 过时检测

比较：

• 文件修改时间戳
• Git 变更历史
• 图表内容与实际代码结构
• 图表中缺少的模块

分析流程

第 1 步：发现模块

# Scan target directory for Python modules
modules = glob("**/*.py")
packages = identify_packages(modules)

第 2 步：提取关系

对每个模块：

1. 解析导入语句
2. 区分本地导入和外部导入
3. 构建依赖关系图
4. 检测循环依赖

第 3 步：生成图表

flowchart TD
    subgraph core["Core Modules"]
        auth[auth.py]
        users[users.py]
        api[api.py]
    end

    subgraph utils["Utilities"]
        helpers[helpers.py]
        validators[validators.py]
    end

    api --> auth
    api --> users
    auth --> helpers
    users --> validators

第 4 步：检查是否最新

将图表时间戳与源文件进行比较：

• 图表比源文件旧 = 过时
• 图表中缺少模块 = 不完整
• 图表中存在多余模块 = 已过时

图表类型

模块依赖关系图

最适合：展示文件之间的导入关系

flowchart LR
    main[main.py] --> auth[auth/]
    main --> api[api/]
    auth --> models[models.py]
    api --> auth

类层次结构

最适合：展示继承和组合关系

classDiagram
    class BaseService {
        +process()
    }
    class AuthService {
        +login()
        +logout()
    }
    BaseService <|-- AuthService

数据流

最适合：展示数据在系统中的流动方式

flowchart TD
    Request[HTTP Request] --> Validate{Validate}
    Validate -->|Valid| Process[Process]
    Validate -->|Invalid| Error[Return Error]
    Process --> Response[HTTP Response]

过时检测

工作原理

1. 查找图表：在 README.md、ARCHITECTURE.md 中定位 mermaid 图表
2. 提取模块：解析图表中引用的模块
3. 比较：检查是否包含所有当前模块
4. 报告：生成最新状态报告

最新状态报告格式

## Diagram Freshness Report

### Status: STALE

**Diagrams Checked**: 3
**Fresh**: 1
**Stale**: 2

### Details

| File         | Last Updated | Code Changed | Status |
| ------------ | ------------ | ------------ | ------ |
| README.md    | 2025-01-01   | 2025-01-15   | STALE  |
| docs/ARCH.md | 2025-01-10   | 2025-01-10   | FRESH  |

### Missing from Diagrams

- `new_module.py` (added 2025-01-12)
- `api/v2.py` (added 2025-01-14)

### Recommended Actions

1. Update README.md architecture diagram
2. Add new_module.py to dependency graph

PR 架构影响

展示内容

针对给定的 PR 或一组更改：

1. 新增的模块/文件
2. 发生变化的导入关系
3. 已删除的依赖项
4. 已修改的类层次结构

影响图

flowchart TD
    subgraph added["New"]
        style added fill:#90EE90
        new_api[api/v2.py]
    end

    subgraph modified["Modified"]
        style modified fill:#FFE4B5
        auth[auth.py]
    end

    subgraph existing["Unchanged"]
        users[users.py]
        models[models.py]
    end

    new_api --> auth
    auth --> models
    users --> models

与其他技能集成

Mermaid 图表生成器

此技能使用 mermaid-diagram-generator 来完成：

• 语法生成
• 图表格式化
• 嵌入 Markdown

可视化架构师 Agent

委托给 visualization-architect，用于：

• 复杂的架构可视化
• ASCII 艺术替代方案
• 多层级图表

使用示例

示例 1：新模块图

User: I just created a new payment module. Generate an architecture diagram.

Claude:
1. Analyzes payment/ directory
2. Extracts imports and dependencies
3. Generates mermaid flowchart
4. Suggests where to embed (README.md)

示例 2：检查过时情况

User: Are my diagrams up to date?

Claude:
1. Finds all mermaid diagrams in docs
2. Compares with current codebase
3. Reports stale diagrams
4. Lists missing modules
5. Suggests updates

示例 3：PR 影响

User: Show architecture impact of this PR

Claude:
1. Gets changed files from PR
2. Identifies new/modified/deleted modules
3. Generates impact diagram
4. Highlights dependency changes

检测算法

导入分析

# Extract imports from Python file
import ast

def extract_imports(file_path):
    """Extract import statements from Python file."""
    tree = ast.parse(Path(file_path).read_text())
    imports = []
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                imports.append(alias.name)
        elif isinstance(node, ast.ImportFrom):
            if node.module:
                imports.append(node.module)
    return imports

过时检查

def check_staleness(diagram_file, source_dir):
    """Check if diagram is stale compared to source."""
    diagram_mtime = Path(diagram_file).stat().st_mtime

    for source in Path(source_dir).rglob("*.py"):
        if source.stat().st_mtime > diagram_mtime:
            return True, source  # Stale

    return False, None  # Fresh

最佳实践

何时更新图表

1. 新增模块：添加到依赖关系图
2. 导入项变更：更新关系
3. 删除文件：从图表中移除
4. 架构变更：完全重新生成

图表放置位置

图表类型	推荐位置
模块概览	README.md
详细架构	docs/ARCHITECTURE.md
包结构	package/README.md
API 流程	api/README.md

命名约定

## Architecture





```mermaid
flowchart TD
    ...
```

成功标准

良好的可视化应：

• 显示所有当前模块
• 反映实际的导入关系
• 使用恰当的图表类型
• 放置在易于发现的位置
• 包含新鲜度元数据
• 清晰且不过于拥挤

局限性

IMPORTANT：依赖此技能前，请了解以下局限性：

过时检测的局限性

1. 基于时间戳，而非语义：检测会比较文件修改时间，而非实际代码变更

   • 文件虽被触碰但没有实质变更，也会触发“过时”提示
   • 代码重新格式化会产生误报
   • 更新 mtime 的 Git 操作会产生误报

2. 无法检测逻辑变更：添加不会改变导入项的函数将无法被检测到

   • 模块内部的重构不可见
   • 函数签名变更不会反映出来
   • 新增但未改变导入项的类方法不会显示

3. 以导入为中心的视图：仅跟踪导入关系

   • 不会检测运行时依赖（依赖注入）
   • 基于配置的连接不可见
   • 不会捕获鸭子类型关系

范围局限性

1. 仅支持 Python：目前仅分析 Python 文件

   • 不支持 TypeScript、JavaScript、Rust、Go
   • 多语言项目仅覆盖部分内容

2. 仅限静态分析：不包含运行时信息

   • 不会检测动态导入（__import__、importlib）
   • 可能会遗漏条件导入
   • 无法完整呈现插件架构

3. 单项目范围：无法分析跨仓库依赖

   • 不会显示外部包的内部结构
   • 单体仓库中的关系需要手动配置

准确性预期

场景	准确率	说明
新模块检测	95%+	对 Python 模块较为可靠
导入关系映射	90%+	会遗漏动态导入
过时检测	70-80%	常有误报
循环依赖检测	85%+	可能遗漏复杂循环
类层级提取	85%+	混入类可能较难处理

不适用此技能的情况

• 安全关键型依赖审计：请使用专门的安全扫描工具
• 运行时依赖分析：请使用分析器或动态分析工具
• 跨语言项目：手动分析可能更准确
• 高度动态的代码库：插件架构、元编程

依赖项

此技能需要：

1. mermaid-diagram-generator 技能：必须可用，以生成图表语法
2. Python 3.8+：用于其使用的 AST 解析功能
3. Git（可选）：通过 Git 历史增强过时检测

如果 mermaid-diagram-generator 不可用，此技能会提供原始关系数据，但无法生成嵌入式图表。

PR 审查集成

图表在 PR 中的呈现方式

审查 PR 时，此技能会生成影响图表，可将其添加到 PR 描述中：

PR 描述模板：

## Architecture Impact



### Changed Dependencies

```mermaid
flowchart LR
    subgraph changed["Modified Modules"]
        style changed fill:#FFE4B5
        auth[auth/service.py]
        api[api/routes.py]
    end

    subgraph added["New Modules"]
        style added fill:#90EE90
        oauth[auth/oauth.py]
    end

    subgraph unchanged["Existing"]
        models[models/user.py]
        db[db/connection.py]
    end

    oauth --> auth
    auth --> models
    api --> auth
    api --> db
```

### Impact Summary

- **New modules**: 1 (oauth.py)
- **Modified modules**: 2 (auth/service.py, api/routes.py)
- **New dependencies**: oauth.py -> auth/service.py
- **Diagrams to update**: README.md (STALE)

CI 集成示例

添加到 .github/workflows/pr-review.yml：

- name: Check Diagram Staleness
  run: |
    # Claude Code analyzes and reports
    # Outputs: STALE diagrams that need updating
    # Generates: Suggested diagram updates

审查者工作流

1. 打开 PR -> code-visualizer 生成影响图表
2. 审查者查看 -> 架构变更的可视化差异
3. 过时检查 -> 如果现有图表需要更新，则发出警告
4. 待办事项 -> 列出需要手动更新的图表

请记住

此技能可自动完成开发者经常忘记的事项：

• 使图表与代码保持同步
• 记录架构变更
• 了解依赖项的影响

目标是让图表自动保持最新。

但请记住其局限性：过时检测只是近似结果。准确性至关重要时，请手动核实。