codeflow

codeflow — 几秒内可视化代码库架构

CodeFlow（braedonsaunders，MIT） 可将任意 GitHub 仓库、本地文件夹、PR 或 Markdown/Obsidian 知识库转换为 交互式架构图——完全在浏览器中运行。它是一个单文件 index.html 应用，通过 CDN 加载固定版本的 React 18 + D3.js 7 + Babel： 无需构建流程、无需 npm install、无需后端，也不会收集数据—— 你的代码会直接从 GitHub 获取到浏览器（或从本地文件读取），绝不会离开你的设备。此技能是一个路由优先的封装：选择输入来源、选择可视化模式、查看分析结果，并导出结果（或将自动更新的 CodeFlow Card 添加到 README）。

何时使用此技能

• 用户打开了一个不熟悉的代码库，想快速了解架构概况——通过可拖动、缩放和探索的交互式依赖关系图
• 用户询问**“如果我修改这个文件，哪些地方会出问题？”** → 对依赖关系图进行影响范围分析
• 用户想查看代码归属情况（根据 git 历史列出每个文件的主要贡献者），用于代码审查或判断“我该问谁？”
• 用户想了解代码库的 A–F 健康评分（死代码、循环依赖、耦合、安全问题）或活动热力图
• 用户想进行启发式安全／模式扫描——查找硬编码密钥、SQL 注入、eval()、调试语句；单例／工厂／观察者／React Hooks，以及反模式（上帝对象、高耦合）
• 用户想进行 PR 影响分析——粘贴 PR URL，查看受影响的文件和变更的影响范围
• 用户想将 Obsidian 知识库／Markdown 目录可视化为笔记图（[[wiki-links]] 和 [text](./relative.md) 会转化为边）
• 用户想导出分析结果（JSON／Markdown／文本／SVG／PDF），或将自动更新的 CodeFlow Card SVG 添加到 README

何时不使用此技能

• 用户想要可编辑、手动编写的图表（架构图、ERD、UML、时序图、流程图）→ 使用 drawio 或 mermaid

• 用户想让 Agent 在仓库中进行节省令牌的代码搜索（查找符号、语义化查找相关内容）→ 使用 semble

• 用户想在重构前获取定义／引用／影响的路由优先仓库导航资料包 → 使用 codebase-search

• 用户想要可提交到仓库（.graphify/）的持久、可重新生成的知识图谱，而不是一次性的浏览器视图 → 使用 graphify

• 用户想要深入且语言准确的静态分析／调用图——CodeFlow 的依赖分析基于启发式方法（按名称匹配函数，并限定在文件范围内及显式导入中），可能会漏掉动态导入或重命名后的运行时引用；它适合快速概览，无法保证 100% 准确

前置条件

要求	说明
现代浏览器	整个应用在客户端运行；无需安装任何内容
git（可选）	仅用于自托管：通过 git clone 克隆单文件仓库
GitHub token（可选）	用于私有仓库和更高的速率限制——仅保存在浏览器内存中，绝不会存储
Node.js（可选）	仅 npx skills 安装程序或解析器单元测试（node --test tests/）需要

说明

步骤 1 — 选择运行 CodeFlow 的方式

模式	适用场景	入口
在线（推荐）	最快捷——公开或私有仓库	https://codeflow-five.vercel.app/
自托管	离线／隔离环境／审查源代码	git clone + open index.html
CodeFlow Card	README 上自动更新的健康状况 SVG	card/ 中的 GitHub Action

自托管只需一条命令——无需构建步骤：

bash git clone https://github.com/braedonsaunders/codeflow.git open codeflow/index.html # 或：根据操作系统使用 xdg-open / start

此技能提供 scripts/install.sh，用于在本地克隆（或更新）仓库并打开它。

第 2 步 — 选择输入

输入	方法
公开仓库	粘贴 facebook/react 或完整的 GitHub URL，然后按 Enter
私有仓库	添加 PAT（repo 范围）或 GitHub App 安装令牌到 Token 字段
本地文件	点击 Open Folder（或拖放文件）——不会上传任何内容
PR 影响	粘贴 PR URL，查看受影响的文件和波及范围
Markdown 知识库	指定 Obsidian 知识库 / markdown 目录，以查看笔记图谱

对于本地扫描，请在扫描前设置排除模式（uploads/**、**/cache/**、 *.png），以跳过附件、缓存和生成的资源。

第 3 步 — 选择可视化模式

模式	文件着色依据
Folder	目录结构
Layer	架构层（UI、Services、Utils、……）
Churn	提交频率（热点）
Blast	选中文件时的影响（“什么会出问题？”）

键盘：Enter 分析 · + / - 缩放 · Escape 关闭模态框。

第 4 步 — 查看分析结果

CodeFlow 完全在客户端呈现以下内容：交互式依赖关系图、每个文件的波及范围计数、代码所有权（Git 贡献者排名）、安全扫描器（硬编码的机密信息 / 密钥、SQL 注入、eval()、调试语句）、模式检测（单例 / 工厂 / 观察者 / React hooks 和反模式）、A–F 健康评分（死代码百分比、循环依赖、耦合、安全性）、活动热力图以及 PR 影响分析。完整功能列表和支持的 40 多种语言请参阅 references/features.md。

第 5 步 — 导出或嵌入

• 分析后导出：JSON（完整数据——健康状况、文件、函数、 依赖关系、变更频率、安全性、模式、建议、语言分布）， Markdown、纯文本、SVG（关系图图片）、PDF（可打印的关系图）或原始 JSON。
• 分享：点击 Share 按钮复制链接，即可重新运行相同的分析。
• CodeFlow Card：一个 GitHub Action，每次合并时都会重新计算健康度 / 规模 / 脆弱性 SVG，并将其呈现在你的 README 中（5 种样式、强调色预设、可选的 PR 热度回执评论、自适应浅色 / 深色模式）。请参阅上游的 card/。

第 6 步 — 与 jeo-skills 并行进行插件式安装

此技能文件夹可通过标准的 jeo-skills 流程安装为插件， 使封装器、参考资料和安装程序能够写入磁盘，供任何受支持的运行时使用：

bash

项目安装（写入 .agents/skills/codeflow/）

npx skills add https://github.com/akillness/jeo-skills --skill codeflow

为每个检测到的 Agent 进行全局安装

npx skills add -g https://github.com/akillness/jeo-skills --skill codeflow

指定目标 Agent

npx skills add -g https://github.com/akillness/jeo-skills --skill codeflow -a claude-code -a codex -y

输出格式

当用户向 codeflow 请求帮助时，返回一份简洁的概要：

markdown

codeflow 路由概要

范围

• 运行模式：online | self-host | card-action | undecided
• 输入：public-repo | private-repo | local-files | pr-url | markdown-vault
• 目标：overview | blast-radius | ownership | health | security | pr-impact | note-graph

推荐的下一步

• open-online | self-host | open-folder | paste-pr-url | wire-card | export-json

原因

• 根据用户提供的信息列出 2–3 条依据

其他工具

• drawio / mermaid：用于创建可编辑的手工绘制图表
• semble：用于在仓库中进行节省令牌的 Agent 代码搜索
• codebase-search：用于在重构前生成仓库导航信息包
• graphify：用于创建持久化并提交到仓库的知识图谱

最佳实践

1. 任何重要操作都使用令牌——未通过身份验证的 GitHub API 每小时限 60 次请求；使用 PAT 或 GitHub App 可将限额提升至每小时 5,000 次请求，并加快分析速度（CodeFlow 会为每次请求获取文件内容）。
2. 将令牌保存在本地——令牌仅存储在浏览器内存中，并会在关闭标签页时清除；切勿将其提交到代码库。团队使用时，建议采用 GitHub App 安装令牌（权限精细、可撤销，并记录审计日志）。
3. 在本地扫描前设置排除模式——跳过 node_modules、缓存、构建输出和二进制资源，确保图表清晰易读且运行迅速。
4. 将依赖关系边视为启发式结果——按文件范围和显式导入匹配函数名称；如果重构涉及动态导入或反射，请先核实再根据影响范围判断采取行动。
5. 敏感代码请自行托管——它是一个可审计的 index.html；本地文件分析完全离线运行，不会发起网络请求。
6. 导出 JSON 以供自动化使用——JSON 报告可用于集成 CI/CD、自定义报告，或作为其他工具的输入。

参考资料

• 上游仓库：https://github.com/braedonsaunders/codeflow
• 在线应用：https://codeflow-five.vercel.app/
• CodeFlow Card Action：https://github.com/braedonsaunders/codeflow/tree/main/card
• 功能和语言参考：references/features.md
• 安装脚本：scripts/install.sh
• 相关技能：../drawio/SKILL.md、../semble/SKILL.md、 ../codebase-search/SKILL.md、../graphify/SKILL.md
• 许可证：MIT