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 的网页界面，直接Cmd+V粘贴即可，完全不需要手动去查找和打开文件。这是工具设计中“用户体验至上”的一个完美体现。
实操心得：虽然这个功能很方便，但要注意，如果生成的文本文件非常大（比如超过几十万行），将其复制到剪贴板可能会导致系统剪贴板服务内存占用过高，偶尔会引起其他应用卡顿。对于超大型项目，我建议直接上传文件，而不是粘贴。你可以在运行
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 found | 1. 安装未成功。 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. 考虑使用模式过滤，只提取你关心的部分文件，减少处理量。 |
| 剪贴板复制失败（macOS） | 1. 生成的文本内容太大，超出剪贴板容量。 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 仓库的更新，或许未来会有更多如文件大小分块、自定义分隔符等实用功能出现。
