Skip to content

README.zh.md

Latest commit

 

History

History
127 lines (94 loc) · 3.45 KB

README.zh.md

File metadata and controls

127 lines (94 loc) · 3.45 KB
Raw

code-report-toolkit

为任意项目生成产品级解构 PDF 报告（11 页），包含中文文字分析 + 架构图表。

支持本地项目路径和 GitHub URL 作为输入。

English

效果预览

生成的报告包含以下 11 页内容：

页 标题
0 封面
1 速览 TL;DR
2 问题与定位
3 核心用户闭环
4 产品能力结构
5 关键设计决策
6 产品哲学
7 主动取舍
8 可复用设计模式
9 启发与迁移
10 本质总结

安装依赖

pip install reportlab playwright pillow pyyaml
playwright install chromium

使用方式

本工具以 Claude Code Skill 形式运行，在 Claude Code 中触发：

分析这个项目并生成代码报告：<本地路径或 GitHub URL>

或直接调用 skill：

请使用 code-report-toolkit skill 分析 https://github.com/owner/repo

工作流

输入（本地路径 / GitHub URL）
    ↓ resolve_source.py
准备本地源码目录
    ↓ scan_project.py
项目扫描（scan_result.json）
    ↓ code-analysis sub-skill
文字分析报告（analysis.md）
    ↓ prepare_report_bundle.py
报告 bundle（report_bundle.json）
    ↓ diagram-renderer sub-skill（每张图）
架构图表（PNG）
    ↓ build_pdf_html.py
最终 PDF

项目结构

code-report-toolkit/
├── SKILL.md                          # 主 skill 入口
└── skills/
    ├── code-analysis/
    │   ├── SKILL.md                  # 代码分析 sub-skill
    │   ├── REFERENCE.md              # 报告格式规范
    │   └── scripts/
    │       ├── resolve_source.py     # 解析输入路径 / clone GitHub 仓库
    │       ├── scan_project.py       # 扫描项目结构，输出 scan_result.json
    │       ├── analysis_progress.py  # 检查 analysis.md 章节完成状态
    │       ├── prepare_report_bundle.py  # 生成 report_bundle.json
    │       ├── build_pdf_html.py     # HTML/CSS → PDF（推荐）
    │       ├── build_pdf.py          # ReportLab → PDF（备用）
    │       └── templates/            # PDF 样式模板
    └── diagram-renderer/
        ├── SKILL.md                  # 图表渲染 sub-skill
        ├── REFERENCE.md              # 颜色规范、元素写法
        ├── scripts/
        │   └── render_to_png.py     # .excalidraw → PNG
        └── templates/               # 13 种图表 excalidraw 模板

Sub-Skills

code-analysis

分析项目源码，生成结构化的 analysis.md。支持断点续跑——若中途中断，重新运行只补写缺失章节。

diagram-renderer

将自然语言图表描述转为 PNG 图片。工作流：自然语言 → Excalidraw JSON → 渲染 → PNG。

支持 13 种图表类型：流程图、层级图、对比图、矩阵图、思维导图、关系图、时间线、泳道图、类图、时序图、ER 图、数据流图、模式结构图。

临时文件说明

运行过程中会在 /tmp/ 下生成以下中间文件：

文件 说明
/tmp/prepared_source.json 解析后的源码路径信息
/tmp/scan_result.json 项目扫描结果
/tmp/analysis.md 文字分析报告
/tmp/report_bundle.json 图表任务 + PDF 输入 bundle
/tmp/diagrams/*.png 生成的架构图表