1. 项目概述为什么我们需要一个“代码扁平化”工具如果你和我一样经常需要把整个项目的代码扔给 Claude 或 ChatGPT 来分析那你肯定遇到过这个痛点大模型的文件上传数量有限制。一个稍微有点规模的项目动辄几百个文件你不可能一个个手动上传。传统的解决方案是使用 RAG检索增强生成但说实话在处理需要全局理解的架构分析、代码审计或者系统梳理任务时RAG 的效果总感觉隔了一层。它更像是“按需检索”而不是让 AI 真正“沉浸”在整个代码的上下文里。那种把整个代码库像一张大地图一样铺开在 AI 面前让它自由穿梭、建立关联的感觉是完全不同的。这就是 Flatty 要解决的问题。它本质上是一个命令行脚本能把你的整个 GitHub 仓库或者本地文件夹“压扁”成一个结构清晰、格式良好的纯文本文件。这个文件包含了项目结构、文件路径以及所有文本文件的内容可以直接作为一个整体上传给支持文件上传的大模型。想象一下你不再需要复制粘贴零散的代码片段而是直接把整个项目的“灵魂”——一个包含了所有逻辑和依赖关系的文本副本——交给 AI让它进行深度推理。这对于理解遗留代码库、进行跨模块的架构评审或者快速为新项目编写技术文档都是一个效率利器。我最初发现这个需求是在尝试让 AI 帮我重构一个老旧的 Flask 应用时。那个项目结构混乱依赖分散手动上传文件让我精疲力尽。Flatty 的出现让我能一键生成一个完整的上下文文件极大地提升了与 AI 协作分析复杂代码的效率。接下来我会详细拆解它的核心设计、使用技巧并分享一些我在实际使用中踩过的坑和总结的经验。2. 核心设计思路与方案选型解析Flatty 的设计哲学非常明确极简、专注、自动化。它没有试图做一个功能繁杂的 IDE 插件或桌面应用而是选择了一个最通用、最轻量的形态——Shell 脚本。这个选择背后有深刻的考量。2.1 为什么是 Shell 脚本而不是更“强大”的语言首先零依赖与跨版本兼容。Shell特别是 Bash是 Unix/Linux/macOS 系统的“母语”。一个纯 Shell 脚本意味着用户几乎不需要安装任何额外的运行时环境如 Python、Node.js、Go降低了使用门槛和潜在的版本冲突风险。对于它的核心任务——遍历文件系统、读取文本、拼接字符串——Shell 的内置命令find,grep,cat,sed完全够用而且性能极高。其次管道哲学的极致体现。Shell 脚本天生适合处理文本流。Flatty 的工作流本质上就是一个复杂的文本处理管道find文件 -grep过滤 -cat读取 - 格式化输出。用 Shell 来实现代码直观且高效符合 Unix “一个工具做好一件事”的设计哲学。第三部署成本极低。一行curl命令就能完成安装这对于需要快速分享和使用的工具来说至关重要。用户不需要关心包管理器、虚拟环境或者编译过程。当然Shell 脚本也有其局限性比如复杂的字符串处理和错误处理会稍显繁琐。但 Flatty 巧妙地将复杂度控制在了合理范围内对于它的核心使命而言这是一个非常务实和高效的选择。2.2 智能化文件过滤不仅仅是跳过node_modules一个合格的代码扁平化工具绝不能简单地把文件夹里所有文件都塞到一起。那样会产生大量噪音比如二进制文件、构建产物让 AI 的上下文窗口被无用信息填满降低分析质量。Flatty 的“智能文件处理”是其核心价值之一。它内置了一套基于经验和常见约定的过滤规则二进制文件识别通过file命令或简单的扩展名黑名单如.png,.jpg,.so,.dll来跳过非文本文件。构建产物与依赖目录主动排除node_modules/,vendor/,build/,dist/,.next/,__pycache__/等目录。这些目录通常体积庞大且不包含需要分析的业务逻辑。版本控制与系统文件忽略.git/目录和.DS_Store等系统元数据文件。隐藏文件通常以.开头的配置文件如.env,.eslintrc.js有时需要有时不需要。Flatty 的默认策略是跳过但用户可以通过模式过滤功能将其包含进来。这个过滤策略不是拍脑袋决定的而是基于一个核心假设当你想让 AI 理解“项目”时你通常指的是“开发者编写的源代码和配置文件”而不是“构建系统生成的中间文件或下载的第三方库”。这个假设在绝大多数代码分析场景下都是成立的。注意这套默认过滤规则对于大多数现代 Web 项目JavaScript/TypeScript, Python, Go非常有效。但如果你在处理一个 Rust/C 项目可能需要留意target/或cmake-build-debug/是否被正确排除。Flatty 的过滤列表是预设的对于非常规的项目结构你可能需要临时调整脚本或使用模式过滤进行精细控制。2.3 模式过滤从“全部扁平”到“精准狙击”这是 Flatty 一个非常亮眼的功能升级。早期的代码扁平化工具只能“全有或全无”而模式过滤让你能进行外科手术式的提取。其工作原理是在遍历文件时不仅检查文件名是否在排除列表还会用grep检查文件内容中是否包含用户指定的关键词或模式通过--pattern指定。然后根据--condition参数AND/OR来决定文件的去留。场景举例审计所有涉及数据库操作的代码flatty --pattern SELECT --pattern INSERT --pattern UPDATE --condition OR。这会找出所有包含任一 SQL 关键字的文件。查找所有使用了特定自定义 Hook 的 React 组件flatty --pattern useCustomHook --condition OR。定位同时包含“错误处理”和“日志记录”的模块flatty --pattern try { --pattern logger.error --condition AND。这能帮你找到那些实现了完整错误处理链的文件。这个功能将 Flatty 从一个简单的“打包工具”变成了一个基于内容的代码检索与聚合工具。你可以在将代码喂给 AI 之前先做一轮精准的预处理确保提交的上下文高度相关从而节省宝贵的 Token 并提升 AI 回复的质量。3. 安装与配置详解安全与便捷的权衡Flatty 提供了两种安装方式这背后体现了对安全性和便捷性的不同侧重。3.1 两种安装模式深度解析快速安装模式curl -fsSL https://raw.githubusercontent.com/mattmireles/flatty/main/install_flatty.sh | bash -s -- --quick做了什么这个命令会下载install_flatty.sh脚本并立即执行传入--quick参数。在快速模式下安装脚本会跳过 SHA256 校验和验证。优点极快一步到位。适合在可信的网络环境下如你自己的电脑访问 GitHub快速尝鲜。风险如果从 GitHub 下载脚本的过程中网络被劫持中间人攻击或者 GitHub 仓库本身被恶意篡改虽然概率极低你可能会运行一个被注入恶意代码的脚本。-f失败时不输出、-s静默、-S显示错误这些curl参数主要是为了更好的用户体验而非安全。偏执安装模式默认curl -fsSL https://raw.githubusercontent.com/mattmireles/flatty/main/install_flatty.sh | bash做了什么下载安装脚本和对应的.sha256校验和文件。然后安装脚本会先计算下载的install_flatty.sh的 SHA256 值再与官方提供的校验和文件进行比对。只有完全一致才会继续执行安装。优点提供了完整性验证确保你运行的脚本与仓库中发布的完全一致没有被篡改。这是软件分发的安全最佳实践。代价多了一次网络请求下载校验文件和一次本地计算耗时稍长。我个人的选择与建议对于任何通过curl | bash方式安装的工具我强烈推荐始终使用默认的偏执模式。多花的这几秒钟是对你系统安全的基本尊重。尤其是在公司环境或处理重要项目时这点时间成本微不足道。快速模式仅适用于你在一个隔离的沙箱环境里进行一次性测试。3.2 安装脚本内部机制与自定义我们来看看install_flatty.sh大概会做什么非官方代码是原理性阐述检查系统是否安装了curl、git等必要工具。确定安装目录通常是/usr/local/bin需要sudo或~/.local/bin用户级。从 GitHub 仓库克隆或下载flatty主脚本文件。将其设置为可执行 (chmod x)。可能还会在~/.zshrc或~/.bashrc中添加安装路径到PATH环境变量。如果你想将 Flatty 安装到自定义目录或者你的系统PATH设置比较特殊可以手动操作# 1. 下载脚本 curl -o flatty https://raw.githubusercontent.com/mattmireles/flatty/main/flatty.sh # 2. 放到你喜欢的目录比如 ~/my_scripts/ mv flatty ~/my_scripts/ # 3. 赋予执行权限 chmod x ~/my_scripts/flatty # 4. 确保该目录在 PATH 中。可以将下面这行添加到 ~/.zshrc 或 ~/.bashrc export PATH$HOME/my_scripts:$PATH # 5. 重新加载 shell 配置 source ~/.zshrc # 或 source ~/.bashrc4. 核心使用技巧与场景化实战安装好后基本使用确实“简单到愚蠢”进入你的项目目录运行flatty。但要想真正发挥威力需要结合具体场景。4.1 基础工作流与 macOS 集成优势在项目根目录下执行flatty后会发生遍历与过滤脚本递归扫描当前目录应用智能过滤规则。生成文件在~/Documents/flatty/目录下生成一个类似myproject-v1.0-2025-01-10_12-57-33.txt的文件。文件名包含了项目名取自目录名、版本如果项目有package.json或类似文件和时间戳便于版本管理。macOS 专属增强自动复制到剪贴板生成完成后脚本会用pbcopy命令将整个文本文件的内容复制到系统剪贴板。在 Finder 中显示同时用open -R命令在 Finder 中高亮显示生成的文件。这个“一键复制定位”的流程对于 macOS 用户来说体验是无缝的。你从终端切换到 ChatGPT 或 Claude 的网页界面直接CmdV粘贴即可完全不需要手动去查找和打开文件。这是工具设计中“用户体验至上”的一个完美体现。实操心得虽然这个功能很方便但要注意如果生成的文本文件非常大比如超过几十万行将其复制到剪贴板可能会导致系统剪贴板服务内存占用过高偶尔会引起其他应用卡顿。对于超大型项目我建议直接上传文件而不是粘贴。你可以在运行flatty后从 Finder 中打开那个.txt文件然后用编辑器的“全选复制”来控制。4.2 模式过滤的高级应用场景模式过滤是 Flatty 的杀手锏我们来深入几个实战场景。场景一为新成员生成项目核心逻辑导读假设一个新同事要接手一个大型 React Node.js 后端项目。你可以为他生成一个聚焦于“业务逻辑”和“API 层”的扁平文件排除所有样式、测试和配置文件。# 包含路由、控制器、服务层和主要的组件 flatty --pattern router --pattern controller --pattern service --pattern useEffect --pattern API --condition OR --output core-overview.txt这里我添加了一个虚构的--output参数来说明意图。实际上Flatty 会按默认命名规则生成文件但你可以事后重命名。这个命令会抓取所有文件名或内容中包含这些关键词的文件形成一个高度浓缩的项目核心指南然后让 AI 基于此生成一份架构说明。场景二安全审计查找潜在的安全漏洞你想快速检查项目中是否存在硬编码的密码、密钥或可能不安全的函数调用。# 查找可能存在的敏感信息和不安全模式 flatty --pattern password --pattern secret --pattern key\s* --pattern eval( --pattern exec( --condition OR这个命令会筛选出所有包含这些敏感模式的文件。你可以先将结果文件自己快速浏览一遍再交给 AI让它以安全专家的视角分析这些代码片段是否存在风险并给出修复建议。这比在成千上万个文件中人工搜索高效得多。场景三技术栈迁移评估计划将项目从express迁移到fastify。你需要先了解express在项目中是如何被使用的。# 找出所有直接使用 express 的地方 flatty --pattern require(express) --pattern from express --pattern app.get --pattern app.post --condition OR生成的文件会集中展示所有与 Express 路由、中间件相关的代码。你可以将这个文件交给 AI提问“请分析这些代码并给出一个逐步迁移到 Fastify 的具体重构计划指出需要特别注意的兼容性问题。”4.3 输出文件结构解析理解生成的文件结构能帮助你更好地利用它。一个典型的 Flatty 输出文件如下 Flatty Output Project: my-awesome-app Version: 1.2.0 Generated: 2025-01-10_12-57-33 Total Files Included: 47 Total Tokens (Estimated): 125,000 DIRECTORY STRUCTURE src/ ├── components/ │ ├── Button.js (Tokens: ~450) │ └── Header.js (Tokens: ~600) ├── utils/ │ └── helpers.js (Tokens: ~300) ├── App.js (Tokens: ~1200) └── index.js (Tokens: ~150) config/ ├── database.js (Tokens: ~500) └── constants.js (Tokens: ~200) package.json (Tokens: ~800) README.md (Tokens: ~400) FILE: src/components/Button.js // 这里是 Button.js 的完整内容 ... FILE: src/components/Header.js // 这里是 Header.js 的完整内容 ... ...这个结构的精妙之处在于元数据头部让 AI和你一眼就知道这个文件的来源、规模和生成时间。目录树与 Token 估算在 AI 处理前它就提供了一个全局视图。Token 估算虽然不精确能让你对上下文消耗有个大致概念避免超出模型限制。清晰的文件分隔符每个文件以 FILE: path/to/file 开始内容完整呈现。这比把所有代码无差别拼接在一起要清晰得多AI 在分析时也能更好地关联代码和其位置。注意事项Token 估算是基于简单规则如单词数、空格的粗略计算与 OpenAI 或 Anthropic 使用的实际分词器Tokenizer结果会有差异尤其是对于非英文代码如包含大量中文注释。它只是一个参考用于判断文件是否“过大”。对于超大型单文件你可能需要手动拆分。5. 常见问题、排查技巧与性能优化即使工具设计得再好在实际使用中也会遇到各种边界情况。下面是我在大量使用 Flatty 后总结的一些典型问题和解决方案。5.1 问题排查速查表问题现象可能原因解决方案运行flatty提示command not found1. 安装未成功。2. 安装目录不在PATH环境变量中。1. 重新运行安装脚本确保无报错。2. 执行echo $PATH查看路径确认/usr/local/bin或~/.local/bin在其中。若不在按前文方法修改 shell 配置文件并source。生成的文本文件内容为空或极少1. 当前目录不包含文本文件。2. 模式过滤条件过于严格无匹配项。3. 脚本的过滤规则意外排除了所有文件。1. 确认你在正确的项目目录下。2. 检查--pattern参数是否拼写错误或尝试不使用任何模式过滤。3. 使用flatty --dry-run如果支持或临时修改脚本在关键过滤步骤后添加echo语句查看哪些文件被处理了。处理速度非常慢大型项目项目目录极其庞大如包含未过滤的node_modules或磁盘 I/O 慢。1.确保在项目根目录运行避免从更高层级开始扫描无关目录。2. 检查脚本是否成功跳过了node_modules等大目录。可以手动在项目根目录执行find . -name \node_modules\ -type d确认。3. 考虑使用模式过滤只提取你关心的部分文件减少处理量。剪贴板复制失败macOS1. 生成的文本内容太大超出剪贴板容量。2. 权限问题极罕见。1. 对于超大输出不要依赖自动复制。直接去~/Documents/flatty/找到文件用文本编辑器打开并手动复制你需要提交给 AI 的部分。2. 可以尝试运行pbcopy /dev/null清空剪贴板后再试或重启终端。模式过滤--condition AND结果不符合预期对AND逻辑的理解有误。AND要求同一个文件中同时包含所有指定的模式。确认你的需求。如果你想找“包含模式A的文件”和“包含模式B的文件”的合集应该使用两次OR条件分别运行然后手动合并结果。AND是用于在单个文件内进行多条件精确匹配。某些想包含的配置文件如.env.example被跳过脚本的默认规则跳过了所有以点.开头的隐藏文件。这是设计如此。如果你需要包含特定的隐藏文件目前版本的 Flatty 可能需要你修改脚本中的过滤规则查找-name \.*\相关的find参数或者先将这些文件复制到一个非隐藏的临时目录进行处理。5.2 性能优化与处理大型项目的技巧对于超过 10 万行代码的超大型单体仓库直接运行flatty可能会产生一个巨大的、超出任何 AI 模型上下文窗口的文件。这时需要一些策略分层级扁平化不要一次性处理整个仓库。按模块或层级来。# 只处理 src/core 核心模块 cd /path/to/monorepo/src/core flatty # 只处理 src/api API 模块 cd /path/to/monorepo/src/api flatty分别生成两个文件然后可以分别提交给 AI或者在你自己的笔记中合并摘要。利用版本控制如果你只关心最近的更改可以结合git。# 找出最近一次提交中更改的所有文件 git diff --name-only HEAD~1 HEAD changed_files.txt # 然后写一个简单的脚本用 flatty 的逻辑只读取这些文件并拼接 # 这需要一些 shell 脚本功底但思路可行这样生成的上下文只包含差异部分极其精准。预处理与摘要对于实在太大的项目可以先让 Flatty 生成一个仅包含文件结构和大小的概览这需要稍微修改脚本只输出第一部分目录树。将这个概览交给 AI让它帮你识别出哪些是核心模块、哪些是依赖或生成代码。然后你再针对它识别出的核心模块比如src/下的几个关键子目录分别运行 Flatty 进行深度分析。关注输出位置默认输出到~/Documents/flatty/。确保这个目录所在磁盘有足够空间。对于 Linux 用户如果~/Documents是符号链接到一个空间较小的分区可以考虑修改脚本中的输出路径到一个空间更大的位置。5.3 与不同 AI 模型的协作策略不同的 LLM 对长上下文的处理能力和成本不同需要调整使用策略Claude (100K/200K 上下文)处理 Flatty 生成的大文件能力最强。你可以相对放心地将一个中等规模项目估算 5-8 万 Token的完整扁平文件丢给它进行复杂的架构问答。ChatGPT (GPT-4 Turbo, 128K 上下文)能力也很强但需要注意其 Token 消耗和成本。对于非常大的输出可以先在本地用文本编辑器打开删除一些显然无关的巨长注释块或自动生成的代码精简后再上传。本地模型 (如 Llama 3, Qwen)上下文窗口可能较小4K-32K。这时必须使用模式过滤功能提取出最相关的代码片段。例如只提取与当前正在修复的 bug 相关的那些文件和函数。一个高级技巧是让 AI 帮你写过滤模式。你可以先把项目的目录树find . -type f -name \*.js\ | head -30扔给 AI然后问它“基于这个 React 项目结构如果我想让 AI 分析其状态管理逻辑应该用哪些关键词来过滤文件” AI 可能会建议--pattern \useState\ --pattern \useReducer\ --pattern \Context\ --pattern \redux\ --condition OR。这样你就得到了一个更智能的过滤起点。Flatty 解决了一个非常具体但普遍存在的痛点如何高效地将本地代码上下文注入到 AI 对话中。它通过极简的 Shell 脚本形式结合智能过滤和强大的模式匹配在便捷性、安全性和功能性之间取得了很好的平衡。无论是快速分析一个小脚本还是深入理解一个庞杂的遗留系统它都能显著降低你与 AI 协作的摩擦。工具本身也在不断进化关注其 GitHub 仓库的更新或许未来会有更多如文件大小分块、自定义分隔符等实用功能出现。