repoviz

repoviz 是做什么的？

将代码库转换为可渲染的图表 URL。每个图表都是一个单独的 https://x-cmd.com/draw URL（扁平化的百分号编码参数），可在浏览器、GitHub README 以及任何 Markdown 查看器中渲染为 SVG。默认模式不写入任何本地文件；仅当用户通过 scripts/ 明确请求时才执行本地导出。

渲染 ≠ 虚构：每个节点和边都携带来源证据（已验证/推断/未知）——输出是可验证的资产，而非 AI 草图。

第一步 —— 意图分析与图表路由

根据用户意图和代码库结构选择图表类型。在构建对应图表之前，只读取匹配的 references/ 文件。

用户意图	图表类型	参考文件
系统概览、文件夹层次、微服务、技术栈	架构图 (/draw/archmap)	references/architecture.md
请求生命周期、函数调用链、API 握手	时序图 (/draw/seq)	references/flowchart.md
分支逻辑、算法、认证/流水线阶段	流程图 (/draw/mermaid)	references/flowchart.md
状态机、状态、重试/回滚	生命周期图 (/draw/lifecycle)	references/flowchart.md
数据管道、依赖/包权重、流量路由	桑基图 (?type=sankey)	references/sankey.md
功能树、模块分类	思维导图 (/draw/mindmap)	references/general-charts.md
路线图、时间表、发布计划	甘特图 (/draw/gantt)	references/general-charts.md
定量代码库指标（语言分布、覆盖率、增长）	数据图表 (?type=pie|hbar|gauge|combo|...)	references/general-charts.md
通用的“可视化此仓库”	多图表套件：1 个 archmap 概览 + 1 个桑基图（数据/依赖流）或 seq（核心请求流）	两个匹配的参考文件

archmap 的同语法变体（见 references/architecture.md）：arch2（备用外观）。数据/行为建模：uc、dataflow、erd、class——语法和实时示例见 references/technical-diagrams.md。长尾图表（树图、漏斗图、关系图等）：/draw/echarts?d=<url-encoded echarts option JSON>。

扫描模式 —— 在读取代码前确定扫描范围（用户可选；默认根据意图确定）：

模式	范围	典型输出
quick	清单文件、深度为 2 的目录树、入口点	1 张概览图
architecture	模块、服务、依赖图	archmap（+ 按权重的桑基图）
deep-dive	调用链、数据流、状态机	seq / 流程图 / 桑基图套件
impact	git diff 对比基准：变更文件及其依赖项	变更流图
full	以上所有	仓库报告（套件 + 质量报告）

impact 模式加载 references/architecture-diff.md（git-diff 增量工作流）；full 模式加载 references/codebase-report.md（标准报告结构）；对同一仓库重复扫描可能加载 references/incremental-scan.md（可选缓存协议）；多图表或证据敏感的工作加载 references/repository-ir.md。

第二步 —— 有令牌纪律的代码库扫描

1. 首先读取根清单文件：package.json、go.mod、Cargo.toml、pyproject.toml、docker-compose.yml，以及深度为 3 的目录树和声明的入口点。
2. 绝不读取每个源文件。对入口点文件和路由表进行抽样；将组件总结为高信号的节点和边。
3. 尽可能从实际数量中推导桑基权重：文件大小（du -sh）、导入/引用计数，或用户提供的流量/成本数据。
4. URL 长度防护：将单个图表控制在约 15–20 个节点（桑基图约 60 条链接），使 URL 保持可读并符合 CDN 限制。对于大仓库，生成一个高层概览图 + 每个子系统一个图，绝不生成单个密集的大图。
5. 从清单文件中检测语言和技术栈，并以该视角进行扫描：Go → 包/接口/协程；TypeScript → 模块/导入图/API 路由；Rust → crate/特性/功能；Python → 包/装饰器/入口点。
6. 扫描时记录证据：每个节点/边获得 file[:symbol[:lines]] 和一个级别——已验证（在代码中看到）、推断（从结构推导）或未知（模式假设）。未打开文件则绝不能标记为已验证。

第三步 —— 构建 URL

• 首先为套件构建轻量级的仓库 IR（共享的节点清单，每个图表一个文档）；在编码时将 IR 映射为 URL。模式和验证协议：references/repository-ir.md。
• 你构建的每个 URL 都将其标签传递给渲染器——在构建、验证或导出之前，应用第四步的保密规则。
• 语法（节点/边/边界）、编码表、工作示例和每种类型的限制都在参考文件中。严格遵循；其中的每个示例都经过实机测试。
• 编码要点：空格 %20、+ %2B、& %26、# %23、</> %3C/%3E、换行 %0A；分隔符 ; = , : / @ 保持原样。不进行 Base64 编码。
• 常用修饰符：title=、scheme=dark\|light、t=<style>（按类型的系列见参考文件——arch2/seq 使用 t=shadcn 效果最佳；arch2 节点可接受可选的第 6 个 icon 字段，例如 n=api;be;API;ECS;r2c0;aws:ecs）、w=/h=、v=N 固定缓存的版本、num=all\|peak\|none（图表）。
• PNG 输出嵌入 GB2312 一级 CJK 子集：罕见字符（例如“渲”）在 PNG 中会变成豆腐块。SVG 无此限制——中文 PNG 标签建议使用常用同义词。
• 遇到 4xx 响应时，响应体是纯文本并附有修正示例——读取它，修正有问题的参数，然后重试。切勿猜测两次。

第四步 —— 输出交付

默认模式 —— 不写入文件。 每个图表回复：

### <图表标题>
![<标题>](<draw-url>)
*[交互式预览](<draw-url>)* · [在编辑器中打开](<explore-url>)

- <要点：图表显示的内容 —— 层级、关键路径、最重的流>
- <要点：明显的耦合/单点故障/所有权边界>

• <explore-url> 将 /draw?type=X&q 重写为 /draw/explore?type=X&q，将 /draw/<name>?q 重写为 /draw/explore/<name>?q——draw 内置的交互式编辑器；链接它，不要重新构建。
• 每个图表 2–5 个精炼要点。图像是交付物；要点提供判断。
• 保密性：渲染——以及 L1 验证和 export.sh 下载——将图表标签（对于流程图，是整个程序文本）作为 URL 参数发送到 x-cmd.com 的渲染器；这些标签可能出现在服务器访问日志中（百分号编码不是加密），Markdown 图像嵌入可能被客户端或代理自动获取。本地导出并不能避免这一点——渲染仍然需要从 x-cmd.com 请求。对于机密仓库，在渲染、验证或导出前，先警告用户并获得明确许可——或者通过本地安装的 draw CLI 完全离线渲染。

用质量报告关闭套件（仅使用实际计数——绝不编造）：

仓库分析 —— <repo>（<scan_mode>，<commit>）
检查文件数：N | 模块数：N | 关系数：N
证据：已验证 N · 推断 N · 未知 N
验证：L1 通过|跳过（隐私）· L2 通过 · L3：N 个未解决（如下标记）

L1 不是自动的——它会获取 URL，即将图表发送到 x-cmd.com。对于机密仓库，仅在用户明确批准后运行（第四步保密规则）；否则报告 L1 跳过（隐私）。在其对应的图表下标记每个 unknown。对于“验证”的明确请求或导出前检查：bash scripts/validate.sh <urls...>（L1 渲染）和 bash scripts/validate.sh --ir <ir.json>（L2 结构）。L3 是你对引用文件的重新读取。

导出模式 —— 仅当用户明确说“本地保存”、“下载 SVG/PNG”、“导出图像”、“短链接”、“放入我的 README”或“生成 HTML 报告”时：

bash scripts/export.sh "<draw-url>" "<out.svg|png>"        # 单次下载
bash scripts/export.sh --batch <manifest.tsv>              # 多个：每行 "<url>\t<out>"，# 为注释
bash scripts/shorten.sh <type> '<d-schema json>' [title]   # 永久性 /draw/c/<hash>（仅适用于 ?type= 图表）
bash scripts/build_html.sh "<title>" "<out.html>" '<json>' # 独立报告（+ 可选的 ev 证据）
bash scripts/inject_readme.sh "<README.md>" '<json>'       # 在 repoviz 标记之间插入/更新图表

• export.sh 通过 curl 下载（回退方案：已本地安装的 CLI——它从不获取或安装包）；.png 目标自动添加 &format=png（添加 &scale=2\|3 以获得更高分辨率；传递 scheme=dark——PNG 默认使用浅色主题）。批处理模式：每行一个 url<TAB>output，允许 # 注释；如果任何一项失败则退出非零。
• shorten.sh 将图表定义（?d= JSON 模式）POST 到 x-cmd.com——速率限制约 30/分钟/IP。仅 ?type= 系列接受 POST；节点/边图表（/draw/archmap、/draw/seq、……）返回 405——保留它们的完整 URL。返回的 /draw/c/<hash> 使用 GET 渲染且是永久性的。仅在用户明确请求时运行：存储的定义是永久性的，并且对持有链接的任何人都公开（第四步保密规则）。
• build_html.sh 接受 {"title","url","note"[,"ev"]} 对象的 JSON 数组（url 限制为 https://x-cmd.com / https://www.x-cmd.com 的 draw 渲染 URL；ev 可选，编码为 "node|file|symbol|lines|level;..."——渲染一个可过滤的来源证据表）并生成一个自包含的深色/浅色响应式报告：侧边栏导航、缩放、全屏、复制 URL 按钮、支持打印为 PDF。所有值都经过 HTML 转义。示例负载：[{"title":"架构","url":"https://x-cmd.com/draw/archmap?...","note":"3 层；网关是唯一条目","ev":"api|src/api.ts|createServer|12-40|verified"}]
• inject_readme.sh 是幂等的：首次使用时，追加一个 <!-- repoviz:start --> … <!-- repoviz:end --> 块（每个图表一个 Markdown 图像 + 注释），后续运行时在原地替换——图表成为仓库中的活资产。
• 导出后，打印保存的路径，并继续输出聊天的 Markdown 块，以便用户同时获得两者。

规则

• 品牌中立：将结果呈现为 repoviz 图表；绝不要重命名或包装渲染 URL。
• 一次扫描，多张图表：跨套件重用节点清单，而非为每个图表重新读取仓库。
• 优先选择更少、更精选的节点，而非完整性；将细节折叠到 sub 标题和边界框中。
• 无证据即未发生：每个节点/边都是已验证、推断或标记为未知——绝不编造。保持 IR/渲染器分离，使套件、报告和未来的架构差异共享一个清单；渲染保持在可替换的适配器层面。
• URL 即数据的增量编辑：现有的 repoviz 图表完全由其 URL 定义——绝不使用视觉或图像读取工具来检查它。从 Markdown 中解码 URL，比较其节点/边集与当前代码，并原位发出更新后的 URL，保留节点 ID、标签和布局约定。