code-visualizer by rysweet/amplihack
npx skills add https://github.com/rysweet/amplihack --skill code-visualizer自动生成和维护可视化代码流程图。此技能分析 Python 模块结构,检测导入关系,并生成 Mermaid 图表。它还会在代码变更但图表未更新时监控其陈旧性。
此技能体现了 amplihack 的核心理念:
code-visualizer (此技能)
├── 职责:
│ ├── Python 模块分析 (AST 解析)
│ ├── 导入关系提取
│ ├── 陈旧性检测 (基于时间戳)
│ └── 图表生成编排
│
└── 委托给:
├── mermaid-diagram-generator 技能
│ ├── Mermaid 语法生成
│ ├── 图表格式化和样式设置
│ └── Markdown 嵌入
│
└── visualization-architect 代理
├── 复杂多层架构
├── ASCII 艺术替代方案
└── 跨模块依赖图
<!-- 由 code-visualizer 生成 -->
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
调用模式:
# code-visualizer 分析代码结构
modules = analyze_python_modules("src/")
relationships = extract_import_relationships(modules)
# 然后委托给 mermaid-diagram-generator 处理语法
Skill(skill="mermaid-diagram-generator")
# 提供:模块关系、图表类型(流程图/类图)、样式偏好
# 接收:可用于嵌入的有效 mermaid 语法
# 对于复杂架构,委托给 visualization-architect
Task(subagent_type="visualization-architect", prompt="为...创建多层图表")
用户:为认证模块生成代码流程图
用户:我的架构图是最新的吗?
用户:这个 PR 引入了哪些架构变更?
分析 Python 文件以提取:
__all__)创建 Mermaid 图表以展示:
比较:
# 扫描目标目录以查找 Python 模块
modules = glob("**/*.py")
packages = identify_packages(modules)
对于每个模块:
flowchart TD
subgraph core["核心模块"]
auth[auth.py]
users[users.py]
api[api.py]
end
subgraph utils["工具集"]
helpers[helpers.py]
validators[validators.py]
end
api --> auth
api --> users
auth --> helpers
users --> validators
比较图表时间戳与源文件:
最佳用于:展示文件间的导入关系
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 请求] --> Validate{验证}
Validate -->|有效| Process[处理]
Validate -->|无效| Error[返回错误]
Process --> Response[HTTP 响应]
## 图表新鲜度报告
### 状态:陈旧
**已检查图表**:3
**新鲜**:1
**陈旧**:2
### 详情
| 文件 | 最后更新 | 代码变更 | 状态 |
| ------------ | ------------ | ------------ | ------ |
| README.md | 2025-01-01 | 2025-01-15 | 陈旧 |
| docs/ARCH.md | 2025-01-10 | 2025-01-10 | 新鲜 |
### 图表中缺失
- `new_module.py` (添加于 2025-01-12)
- `api/v2.py` (添加于 2025-01-14)
### 推荐操作
1. 更新 README.md 架构图
2. 将 new_module.py 添加到依赖关系图中
对于给定的 PR 或一组变更:
flowchart TD
subgraph added["新增"]
style added fill:#90EE90
new_api[api/v2.py]
end
subgraph modified["已修改"]
style modified fill:#FFE4B5
auth[auth.py]
end
subgraph existing["未变更"]
users[users.py]
models[models.py]
end
new_api --> auth
auth --> models
users --> models
此技能使用 mermaid-diagram-generator 来处理:
委托给 visualization-architect 来处理:
用户:我刚刚创建了一个新的支付模块。生成一个架构图。
Claude:
1. 分析 payment/ 目录
2. 提取导入和依赖关系
3. 生成 Mermaid 流程图
4. 建议嵌入位置 (README.md)
用户:我的图表是最新的吗?
Claude:
1. 在 docs 中查找所有 Mermaid 图表
2. 与当前代码库进行比较
3. 报告陈旧图表
4. 列出缺失的模块
5. 建议更新
用户:展示此 PR 的架构影响
Claude:
1. 从 PR 获取变更的文件
2. 识别新增/修改/删除的模块
3. 生成影响图
4. 突出显示依赖关系变更
# 从 Python 文件中提取导入
import ast
def extract_imports(file_path):
"""从 Python 文件中提取导入语句。"""
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):
"""检查图表相对于源文件是否陈旧。"""
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 # 陈旧
return False, None # 新鲜
| 图表类型 | 推荐位置 |
|---|---|
| 模块概览 | README.md |
| 详细架构 | docs/ARCHITECTURE.md |
| 包结构 | package/README.md |
| API 流程 | api/README.md |
## 架构
<!-- code-visualizer:auto-generated -->
<!-- last-updated: 2025-01-15 -->
<!-- source-hash: abc123 -->
```mermaid
flowchart TD
...
## 成功标准
一个好的可视化应:
* 展示所有当前模块
* 反映实际的导入关系
* 使用适当的图表类型
* 放置在易于发现的位置
* 包含新鲜度元数据
* 清晰且不过于拥挤
## 局限性
**重要**:在依赖此技能之前,请理解以下局限性:
### 陈旧性检测的局限性
1. **基于时间戳,而非语义**:检测比较文件修改时间,而非实际代码变更
* 文件被触碰但未发生有意义的变更会触发"陈旧"
* 代码格式化会触发误报
* 更新 mtime 的 Git 操作会触发误报
2. **无法检测逻辑变更**:添加不改变导入的函数将不会被检测到
* 模块内部的代码重构不可见
* 函数签名的变更不会反映出来
* 添加不涉及导入变更的新类方法不会显示
3. **导入中心视图**:仅跟踪导入关系
* 运行时依赖(依赖注入)无法检测
* 基于配置的连接不可见
* 鸭子类型关系无法捕获
### 范围局限性
1. **仅限 Python**:目前仅分析 Python 文件
* 不支持 TypeScript、JavaScript、Rust、Go
* 多语言项目仅部分覆盖
2. **仅限静态分析**:无运行时信息
* 动态导入 (`__import__`, `importlib`) 无法检测
* 条件导入可能被遗漏
* 插件架构无法完全表示
3. **单项目范围**:无法分析跨仓库的依赖关系
* 外部包的内部结构不显示
* 单体仓库关系需要手动配置
### 准确性预期
场景 | 准确性 | 备注
---|---|---
新模块检测 | 95%+ | 对于 Python 模块可靠
导入关系映射 | 90%+ | 遗漏动态导入
陈旧性检测 | 70-80% | 常见误报
循环依赖检测 | 85%+ | 可能遗漏复杂循环
类层次结构提取 | 85%+ | Mixin 可能比较棘手
### 何时不应使用此技能
* **安全关键的依赖审计**:使用适当的安全扫描工具
* **运行时依赖分析**:使用性能分析器或动态分析工具
* **跨语言项目**:手动分析可能更准确
* **高度动态的代码库**:插件架构、元编程
## 依赖项
此技能需要:
1. **mermaid-diagram-generator 技能**:必须可用以生成图表语法
2. **Python 3.8+**:用于使用的 AST 解析功能
3. **Git(可选)**:用于使用 Git 历史记录增强陈旧性检测
如果 mermaid-diagram-generator 不可用,此技能将提供原始关系数据但无法生成嵌入的图表。
## PR 审查集成
### 图表如何在 PR 中显示
在审查 PR 时,此技能会生成影响图,可添加到 PR 描述中:
**PR 描述模板:**
flowchart LR
subgraph changed["已修改模块"]
style changed fill:#FFE4B5
auth[auth/service.py]
api[api/routes.py]
end
subgraph added["新增模块"]
style added fill:#90EE90
oauth[auth/oauth.py]
end
subgraph unchanged["现有模块"]
models[models/user.py]
db[db/connection.py]
end
oauth --> auth
auth --> models
api --> auth
api --> db
### CI 集成示例
添加到 `.github/workflows/pr-review.yml`:
### 审查者工作流
1. **PR 打开** -> code-visualizer 生成影响图
2. **审查者看到** -> 架构变更的可视化差异
3. **陈旧性检查** -> 警告现有图表是否需要更新
4. **待办事项** -> 列出需要手动更新的图表
## 请记住
此技能自动化了开发者经常忘记的事情:
* 保持图表与代码同步
* 记录架构变更
* 理解依赖影响
目标是自动保持图表的新鲜度。
**但请记住其局限性**:陈旧性检测是近似的。当准确性很重要时,请手动验证。
每周安装数
119
代码仓库
[rysweet/amplihack](https://github.com/rysweet/amplihack "rysweet/amplihack")
GitHub 星标数
39
首次出现
2026 年 1 月 23 日
安全审计
[Gen Agent Trust HubPass](/rysweet/amplihack/code-visualizer/security/agent-trust-hub)[SocketPass](/rysweet/amplihack/code-visualizer/security/socket)[SnykPass](/rysweet/amplihack/code-visualizer/security/snyk)
安装于
opencode111
claude-code108
codex105
gemini-cli102
github-copilot101
cursor100
Automatically generate and maintain visual code flow diagrams. This skill analyzes Python module structure, detects import relationships, and generates mermaid diagrams. It also monitors for staleness when code changes but diagrams don't.
This skill embodies amplihack's core philosophy:
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
Invocation Pattern:
# 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...")
User: Generate a code flow diagram for the authentication module
User: Are my architecture diagrams up to date?
User: What architecture changes does this PR introduce?
Analyzes Python files to extract:
__all__)Creates mermaid diagrams showing:
Compares:
# Scan target directory for Python modules
modules = glob("**/*.py")
packages = identify_packages(modules)
For each module:
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
Compare diagram timestamps with source files:
Best for: Showing import relationships between files
flowchart LR
main[main.py] --> auth[auth/]
main --> api[api/]
auth --> models[models.py]
api --> auth
Best for: Showing inheritance and composition
classDiagram
class BaseService {
+process()
}
class AuthService {
+login()
+logout()
}
BaseService <|-- AuthService
Best for: Showing how data moves through system
flowchart TD
Request[HTTP Request] --> Validate{Validate}
Validate -->|Valid| Process[Process]
Validate -->|Invalid| Error[Return Error]
Process --> Response[HTTP Response]
## 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
For a given PR or set of changes:
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
This skill uses mermaid-diagram-generator for:
Delegates to visualization-architect for:
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)
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
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
| Diagram Type | Recommended Location |
|---|---|
| Module overview | README.md |
| Detailed architecture | docs/ARCHITECTURE.md |
| Package structure | package/README.md |
| API flow | api/README.md |
## Architecture
<!-- code-visualizer:auto-generated -->
<!-- last-updated: 2025-01-15 -->
<!-- source-hash: abc123 -->
```mermaid
flowchart TD
...
```
A good visualization:
IMPORTANT : Understand these limitations before relying on this skill:
Timestamp-based, not semantic : Detection compares file modification times, not actual code changes
Cannot detect logic changes : Adding a function that doesn't change imports won't be detected
Import-centric view : Only tracks import relationships
Python-only : Currently only analyzes Python files
Static analysis only : No runtime information
__import__, importlib) not detectedSingle-project scope : Cannot analyze cross-repository dependencies
| Scenario | Accuracy | Notes |
|---|---|---|
| New module detection | 95%+ | Reliable for Python modules |
| Import relationship mapping | 90%+ | Misses dynamic imports |
| Staleness detection | 70-80% | False positives common |
| Circular dependency detection | 85%+ | May miss complex cycles |
| Class hierarchy extraction | 85%+ | Mixins can be tricky |
This skill requires:
If mermaid-diagram-generator is unavailable, this skill will provide raw relationship data but cannot generate embedded diagrams.
When reviewing PRs, this skill generates impact diagrams that can be added to PR descriptions:
PR Description Template:
## Architecture Impact
<!-- Generated by code-visualizer -->
### 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)
Add to .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
This skill automates what developers often forget:
The goal is diagrams that stay fresh automatically.
But remember the limitations : Staleness detection is approximate. When accuracy matters, verify manually.
Weekly Installs
119
Repository
GitHub Stars
39
First Seen
Jan 23, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode111
claude-code108
codex105
gemini-cli102
github-copilot101
cursor100
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
159,700 周安装