Skip to content

README_zh-CN.md

Latest commit

 

History

History
111 lines (88 loc) · 4.34 KB

README_zh-CN.md

File metadata and controls

111 lines (88 loc) · 4.34 KB

CodeMap 可视化工具 (CodeMap Visualizer)

English Documentation

CodeMap Visualizer 是一个现代化的交互式 Web 应用程序，旨在渲染、分析和共享结构化的代码分析数据。它将表示代码执行流和架构的复杂 JSON 数据转换为美观、易于理解的可视化指南。

使用 Angular (Zoneless, Signals), Tailwind CSS, 和 Mermaid.js 构建。

🚀 功能特性

  • 交互式架构图: 使用 Mermaid.js 自动渲染高层架构图。
  • 逐步代码追踪: 通过详细的解释和上下文导航复杂的执行流程。
  • 富文本指南: 渲染带有语法高亮的 Markdown 指南，提高可读性。
  • 代码语法高亮: 使用 Highlight.js 精确高亮代码片段。
  • 历史记录管理: 自动将最近查看的图谱保存到本地存储，以便快速访问。
  • 轻松导入/导出:
    • 直接粘贴 JSON。
    • 导入 .json 文件或扫描文件夹。
    • 下载图谱或将其复制到剪贴板。
  • 暗黑模式 UI: 灵感来自现代 IDE 的精致、开发者友好的暗黑主题。

🛠️ 技术栈

  • 框架: Angular v18+ (Standalone Components, Signals, Zoneless Change Detection)
  • 样式: Tailwind CSS
  • 可视化: Mermaid.js
  • Markdown 渲染: Marked.js
  • 语法高亮: Highlight.js
  • 图标: Heroicons (SVG)

📖 用户指南

1. 导入数据

可以通过三种方式加载 CodeMap：

  1. 粘贴 JSON: 点击 "New Import" (新建导入) 并将原始 JSON 字符串粘贴到文本区域中。
  2. 选择文件: 从电脑上传有效的 .json 文件。
  3. 选择文件夹: 选择包含 .json 文件的文件夹以自动查找并加载它。

2. 浏览查看器

加载后，屏幕分为两个主要区域：

  • 侧边栏 (左侧): 显示有关生成的元数据（时间戳、模式）和可用 追踪流 (Trace Flows) 列表。点击追踪流以聚焦查看。
  • 主视图 (右侧):
    • 架构图: 系统组件及其关系的直观概览。
    • 追踪详情: 向下滚动查看特定流程。每个追踪包含一个 "追踪指南" (Markdown 解释)、一个 ASCII 流程图以及一系列显示实际源代码和上下文的 "代码位置"。

3. 管理历史记录

  • 点击顶部导航栏中的 History (历史) 按钮查看之前加载的图谱。
  • 图谱存储在浏览器的本地存储中。
  • 您可以随时清除历史记录。

📄 数据格式 (JSON Schema)

要生成您自己的 CodeMap，您的 JSON 数据必须遵循此结构：

interface CodeMap {
  schemaVersion: number;      // 例如: 2
  title: string;              // 可视化标题
  description: string;        // 简要概述
  mermaidDiagram: string;     // Mermaid 图定义 (例如: "graph TD; A-->B;")
  metadata: {
    mode: 'FAST' | 'SMART' | 'ENHANCED';
    generationTimestamp: string; // ISO 日期字符串
    originalPrompt?: string;
    [key: string]: any;
  };
  traces: Trace[];
}

interface Trace {
  id: string;
  title: string;              // 特定流程的名称
  description: string;        // 此追踪的作用摘要
  traceGuide: string;         // 解释流程的 Markdown 内容
  traceTextDiagram: string;   // 流程的 ASCII 或简单文本表示
  locations: Location[];      // 代码片段的有序列表
}

interface Location {
  id: string;
  path: string;               // 文件路径 (例如: "src/app.component.ts")
  lineNumber: number;         // 关注的行号
  lineContent: string;        // 实际代码内容
  title: string;              // 此步骤的简短标题
  description: string;        // 这里发生了什么的解释
}

📦 开发

本项目构建为 Zoneless Angular Application (无 Zone.js Angular 应用)。

关键文件结构:

  • src/main.ts: 应用程序入口点 (引导 AppComponent)。
  • src/models/codemap.model.ts: 数据域的 TypeScript 接口。
  • src/services/codemap-history.service.ts: 处理 LocalStorage 持久化。
  • src/components/:
    • codemap-viewer: 主布局组件。
    • trace-detail: 处理渲染单个追踪、Markdown 和代码高亮。

外部依赖

该项目通过 index.html 中的 CDN 加载几个较重的库，以保持包大小较小并利用缓存：

  • Tailwind CSS (Script)
  • Mermaid.js
  • Marked
  • Highlight.js

Generated by Google Gemini