1. 项目概述：为AI助手准备的代码“打包神器”

如果你经常用ChatGPT、Claude或者Cursor这类AI编程助手来审查代码、重构函数或者调试问题，那你一定遇到过这个痛点：项目文件太多，一次只能贴一小段代码给AI看。上下文不完整，AI给出的建议往往隔靴搔痒，甚至因为不了解项目全貌而给出错误的方案。手动把所有相关文件复制粘贴到一个文档里？那简直是噩梦，不仅费时费力，还容易漏掉关键文件，更别提那些 node_modules 、 .git 、 __pycache__ 之类的“噪音”文件夹了。

Code Export For AI 这个工具，就是为了解决这个“最后一公里”的问题而生的。它本质上是一个Python脚本，但功能非常聚焦：把你指定的项目文件夹（或者整个代码仓库）递归地扫描一遍，然后生成一个单一的、格式整洁的文本文件。这个文件里，每个源文件都会被一个带有相对路径的标题和对应语言的高亮代码块包裹起来，就像你在Markdown里贴代码一样。你可以直接把这个文件的内容整个丢给AI，让它瞬间获得你项目的完整上下文。

我自己在重构一个遗留的Flask项目时，第一次用上了它。那个项目结构混乱，有几十个 .py 文件分散在不同目录，还有一堆静态资源和配置文件。我需要AI帮我理清路由逻辑和数据库模型的关系。手动整理？不可能。用了这个工具，一键生成一个 export.txt ，直接粘贴到Claude的对话框里，然后提问：“请根据提供的完整项目代码，分析 /api 下的所有路由分别对应了哪些数据模型，并指出可能存在循环导入风险的地方。” 十分钟后，我就拿到了一份清晰的分析报告和重构建议，效率提升了不止一个量级。

2. 核心设计思路：不只是“复制粘贴”

这个工具的设计，体现了一个资深开发者对“工作流”的深刻理解。它不是一个简单的文件拼接器，而是一个高度可配置的上下文构建器。我们来拆解一下它的核心设计哲学。

2.1 以“可读性”和“可操作性”为第一原则

AI模型（尤其是大语言模型）处理文本时，结构和格式至关重要。杂乱无章的代码粘贴会导致模型理解困难。因此，该工具在输出时做了两件关键事：

1. 添加文件路径标题 ：在每个代码块前，明确标注 src/utils/logger.py: 这样的相对路径。这让AI（以及任何阅读者）能立刻知道这段代码在项目中的位置，便于结合目录结构进行分析。
2. 使用围栏代码块 ：用 ```python 这样的语法包裹代码。这不仅在支持Markdown的AI界面（如ChatGPT Web版）中能实现语法高亮，更重要的是，它向AI清晰地声明了：“这是一段Python代码”，有助于模型调用正确的代码理解模块。

2.2 多层过滤机制：精准控制输出内容

一个项目里并非所有文件都对代码分析有帮助。二进制文件、日志、依赖库、构建产物都是噪音。该工具设计了一套组合拳式的过滤策略，优先级从高到低：

1. 目录黑名单 ：最粗粒度的过滤。直接跳过整个 node_modules 、 .git 、 venv 等目录。这是通过 BLACKLIST_DIRS 配置的。
2. 文件扩展名黑名单 ：过滤掉 .png , .jpg , .log , .pyc 等非文本或无需分析的文件。通过 BLACKLIST_EXTENSIONS 设置。
3. 文件名黑名单 ：可以精确忽略 thumbs.db 、 desktop.ini 等特定文件。支持“精确匹配”和“包含”两种模式（ FILENAME_FILTER_MODE ）。
4. 文件大小限制 ：通过 MAX_FILE_SIZE_MB ，防止意外将巨大的数据库文件或日志文件纳入，导致输出爆炸。
5. 递归深度限制 ：对于大型单体仓库，可以用 MAX_DEPTH 控制扫描深度，避免陷入无关的子项目。
6. 集成.gitignore ：这是我认为最巧妙的设计。当 USE_GITIGNORE = True 时，工具会读取项目根目录的 .gitignore 文件，并自动遵守其中的规则。这意味着你的版本管理策略直接成为了AI上下文过滤策略，两者保持高度一致，避免了配置重复。

2.3 配置即代码：为不同场景定制“导出方案”

这是该工具从“好用”到“专业”的关键一跃。它支持将配置保存在 configs/ 目录下的独立 .py 文件中。你可以创建：

• configs/python.py : 专门用于Python项目，忽略 .pyc ，包含 requirements.txt 。
• configs/frontend.py : 用于前端项目，忽略 dist/ , build/ ，包含 package.json 。
• configs/golang.py : 用于Go项目，忽略 vendor/ , 包含 go.mod 。

通过命令行参数 -c 即可快速切换。这种设计使得针对不同技术栈的优化配置可以沉淀下来，团队共享，而不是每次都在命令行里敲一堆 --ignore 参数。

3. 从安装到实战：手把手配置与使用

理解了设计思路，我们来实际操作一遍。我会以一个典型的Python Web项目为例，展示从环境准备到生成一份完美AI上下文文件的完整流程。

3.1 环境准备与安装

首先，确保你的系统安装了Python 3.10或更高版本。我推荐使用 pyenv 或 conda 来管理Python版本，避免系统自带的旧版本带来兼容性问题。

# 克隆项目仓库
git clone https://github.com/OlyoshaOlyosha/Code-Export-For-AI.git
cd Code-Export-For-AI

接下来安装依赖。项目核心依赖是 colorama ，用于在控制台输出彩色文字，提升可读性。剪贴板支持有两种方式：优先使用功能更稳定的 pyperclip 库；如果没安装，则会回退到调用系统原生命令（Windows的 clip 、macOS的 pbcopy 、Linux的 xclip / xsel ）。

# 使用项目提供的requirements.txt安装（推荐）
pip install -r requirements.txt

# 或者手动安装
pip install colorama pyperclip

注意 ：如果你在Linux服务器（无GUI环境）上使用，并且需要剪贴板功能，请务必确保已安装 xclip 或 xsel 。例如在Ubuntu上： sudo apt install xclip 。否则，回退机制可能因缺少这些命令而失败。

3.2 创建你的第一个配置文件

工具默认会寻找 configs/ 目录下的配置文件。我们首先创建这个目录，并从项目根目录复制示例配置过来进行修改。

# 创建配置目录
mkdir -p configs

# 复制示例配置文件
cp config.py configs/my_project.py

现在，用你喜欢的编辑器打开 configs/my_project.py 。我们来针对一个Python Django/Flask类型的Web项目进行定制化配置。

# configs/my_project.py
import os

# 1. 输出设置
OUTPUT_DIR = "exports"  # 所有导出文件的根目录
OUTPUT_FILENAME = "ai_context.txt"  # 输出文件名
CREATE_FILE = True  # 是否生成文件
COPY_TO_CLIPBOARD = True  # 是否复制到剪贴板
MAX_CLIPBOARD_CHARS = 800000  # 剪贴板字符数上限，可根据需要调大

# 2. 内容控制
EXPORT_STRUCTURE = True  # 导出目录树状图
EXPORT_CONTENT = True    # 导出文件内容
SHOW_EMPTY_DIRS = False  # 在目录树中显示空文件夹（通常不需要）
INCLUDE_EMPTY_FILES = False  # 包含空文件（仅出现在目录树中，无代码块）

# 3. 过滤规则 - 核心部分
BLACKLIST_EXTENSIONS = {
    # 媒体与二进制文件
    "png", "jpg", "jpeg", "gif", "bmp", "ico", "svg",
    "mp3", "mp4", "avi", "mov",
    "pdf", "doc", "docx", "xls", "xlsx",
    "zip", "tar", "gz", "7z",
    # 日志与缓存
    "log", "tmp", "cache",
    # Python编译文件
    "pyc", "pyo", "pyd",
    # 其他
    "db", "sqlite3", "DS_Store"
}

ALLOWED_EXTENSIONLESS_FILES = {
    "Dockerfile", "Makefile", "docker-compose.yml",
    "README", "README.md", "LICENSE", ".env.example",
    "Procfile", "requirements", "runtime.txt"
}

BLACKLIST_DIRS = {
    "__pycache__", ".pytest_cache", ".mypy_cache",
    "htmlcov", ".coverage",
    "node_modules", ".npm", ".yarn",
    "dist", "build", "out", "target",
    ".git", ".svn", ".hg",
    ".idea", ".vscode", ".vs",
    "venv", ".venv", "env", ".env",
    "staticfiles", "media"  # Django的静态文件收集目录和用户上传目录
}

BLACKLIST_FILENAMES = {
    "thumbs.db", "desktop.ini", ".DS_Store",
    "package-lock.json", "yarn.lock"  # 这些文件通常很大且对代码分析无用
}
FILENAME_FILTER_MODE = "exact"  # 对上述文件名进行精确匹配

# 4. 高级控制
USE_GITIGNORE = True  # 强烈建议开启，与版本控制保持一致
MAX_DEPTH = -1  # 无限深度，扫描所有子目录
MAX_FILE_SIZE_MB = 2  # 忽略大于2MB的文件，防止大日志或数据文件混入

配置解析与心得 ：

• BLACKLIST_DIRS ：这里我不仅包含了通用的缓存和版本控制目录，还特意加入了Django项目中常见的 staticfiles 和 media 。前者是 collectstatic 命令生成的，后者是用户上传文件，都不属于需要分析的源代码。
• ALLOWED_EXTENSIONLESS_FILES ：注意，我把 docker-compose.yml 和 .env.example 也加了进来。虽然它们有扩展名，但 yml 和 example 可能不在你的源代码扩展名列表中（如 .py , .js ），通过这个集合可以确保这些重要的配置文件被包含。
• MAX_FILE_SIZE_MB ：设置为2MB是一个比较安全的阈值。它能过滤掉大多数意外生成的调试日志或数据集，同时保留正常的源代码文件。如果你的项目中有必要的大型配置文件（如一个巨大的 json schema），可以临时调大这个值或将其加入白名单逻辑（需修改源码）。

3.3 运行与实战：生成你的第一份AI上下文

配置完成后，就可以运行了。最简单的方式是使用GUI文件夹选择器。

python main.py

运行后，会弹出一个文件夹选择窗口。导航到你的项目根目录（比如 ~/projects/my_django_app ），点击“选择文件夹”。接着，如果你在 configs/ 目录下放了多个配置文件，工具会列出它们让你选择；如果只有 my_project.py 一个，则会自动使用它。

处理完成后，你会在终端看到类似这样的统计信息：

[INFO] 扫描完成！
[INFO] 已处理目录: /path/to/your/project
[INFO] 包含文件数: 47
[INFO] 输出字符数: 125,430
[INFO] 运行时间: 0.8 秒
[INFO] 输出已保存至: exports/my_project/ai_context.txt
[INFO] 内容已复制到剪贴板（125,430 字符）。

现在，打开你的AI聊天窗口（ChatGPT, Claude等），直接粘贴（Ctrl+V）。你会看到一个清晰的项目结构树， followed by 所有源代码文件，格式工整，一目了然。

更高效的使用方式：命令行直接指定 如果你已经知道项目路径和配置，使用命令行参数更快捷。

python main.py -d ~/projects/my_django_app -o django_export.txt -c my_project

• -d : 指定项目目录绝对路径。
• -o : 指定输出文件名（会保存在 exports/my_project/ 下）。
• -c : 指定配置名（对应 configs/my_project.py ，省略 .py 扩展名）。

4. 高级技巧与场景化配置

掌握了基础用法后，我们可以针对更复杂的场景进行优化。工具的灵活性就体现在这些细节配置上。

4.1 场景一：仅导出项目结构，用于快速文档化

有时你不需要把代码都贴出去，只想让AI或同事快速了解项目模块划分。这时可以修改配置：

# configs/structure_only.py
EXPORT_STRUCTURE = True
EXPORT_CONTENT = False  # 关键：不导出文件内容
SHOW_EMPTY_DIRS = True  # 显示空目录，更完整地体现结构
INCLUDE_EMPTY_FILES = True

# 可以放宽过滤，因为只输出结构，负担很小
MAX_FILE_SIZE_MB = 10

运行后，输出将只包含ASCII树状图，非常适合放入项目 README 或用于架构讨论。

4.2 场景二：深度限制与聚焦扫描

对于庞大的微服务仓库或Monorepo，你可能只想分析其中一个子服务。

# configs/monorepo_service_a.py
BLACKLIST_DIRS = {
    "node_modules", ".git", "__pycache__",
    "service-b", "service-c", "shared-lib/node_modules"  # 忽略其他服务
}
MAX_DEPTH = 3  # 只扫描3层深度，防止进入无关的深层嵌套
USE_GITIGNORE = True

这样，工具就只会扫描 service-a 目录下三层以内的文件，高效且聚焦。

4.3 场景三：为特定AI模型优化输出

不同的AI模型对上下文长度和格式的容忍度不同。例如，某些模型对超长代码块处理不佳。

# configs/for_claude.py
# Claude 支持超长上下文，可以放宽限制
MAX_CLIPBOARD_CHARS = 0  # 禁用剪贴板限制，但小心系统内存
MAX_FILE_SIZE_MB = 5  # 允许稍大的文件

# configs/for_cursor.py
# Cursor等IDE插件可能对即时粘贴的上下文长度更敏感
MAX_CLIPBOARD_CHARS = 200000  # 设置一个更保守的上限
# 优先包含核心源码，忽略测试和文档
BLACKLIST_DIRS.add("tests")  # 动态添加，假设基础配置已导入
BLACKLIST_FILENAMES.add("README.md")

4.4 自定义代码块语言映射

工具根据文件扩展名自动判断代码块语言（如 .py -> python ）。如果你使用了不常见的扩展名，或者想修正映射，需要修改源码中的 EXTENSION_LANGUAGE_MAP 。这个字典位于 exporter/processor.py 文件中。

# 在 exporter/processor.py 中找到 EXTENSION_LANGUAGE_MAP，添加或修改
EXTENSION_LANGUAGE_MAP = {
    ".py": "python",
    ".js": "javascript",
    ".jsx": "javascript",
    ".ts": "typescript",
    ".tsx": "typescript",
    ".vue": "vue",        # 添加Vue文件支持
    ".svelte": "svelte",  # 添加Svelte文件支持
    ".rs": "rust",        # 添加Rust文件支持
    ".tf": "hcl",         # Terraform文件，使用HCL语法高亮
    ".yml": "yaml",
    ".yaml": "yaml",
    # ... 其他默认映射
}

修改后，你的 .vue 或 .svelte 文件在输出中就会有正确的语法高亮标识了。

5. 常见问题、排查与实操心得

即使工具设计得再完善，在实际操作中还是会遇到各种边界情况。下面是我在大量使用后总结的“避坑指南”。

5.1 问题一：运行后无输出，或输出文件为空

可能原因及排查步骤：

1. 过滤规则过于严格 ：这是最常见的原因。检查你的 BLACKLIST_EXTENSIONS 是否不小心包含了 .py 、 .js 等目标扩展名？检查 BLACKLIST_DIRS 是否包含了项目根目录本身？
2. 路径错误 ：通过 -d 参数指定的路径是否正确？如果包含空格或特殊字符，是否使用了引号包裹？ python main.py -d "C:\My Projects\code" 。
3. 配置文件未生效 ：确保配置文件在 configs/ 目录下，且通过 -c 参数指定的名称正确（无需 .py 后缀）。如果不指定 -c ，工具会尝试自动选择，逻辑是：
   • 如果 configs/ 下只有一个 .py 文件，就用它。
   • 如果有多个，会弹出数字菜单让你选。
   • 如果 configs/ 为空，则回退到项目根目录的 config.py （旧版方式）。
4. 权限问题 ：在Linux/macOS下，是否对目标项目目录有读权限？对 outputs/ 或 exports/ 目录是否有写权限？

诊断技巧 ：在配置文件中暂时将所有过滤规则注释掉，并将 MAX_DEPTH 设为0（只扫描当前目录），看是否有输出。然后逐步放开过滤，定位问题规则。

5.2 问题二：剪贴板复制失败（尤其是在Linux服务器或WSL中）

现象 ：程序提示文件已保存，但“复制到剪贴板”失败或没有提示。

原因与解决方案：

环境	可能原因	解决方案
Linux (无GUI)	默认依赖 xclip 或 xsel ，但未安装或DISPLAY变量未设置（无图形界面）。	1. 安装 xclip : sudo apt install xclip 。 2. 如果是在纯终端服务器，剪贴板功能可能不适用。可以设置 COPY_TO_CLIPBOARD = False ，然后手动用 cat exports/your_config/output.txt 查看或用 ssh 工具（如MobaXterm、Windows Terminal）的复制功能。
WSL (Windows Subsystem for Linux)	WSL1或某些WSL2配置下，系统剪贴板与Windows宿主未正确集成。	1. 确保安装了 pyperclip : pip install pyperclip 。 pyperclip 在WSL中有时有更好的兼容性。 2. 可以尝试安装 win32y （仅Windows）的WSL桥接工具，但更简单的方法是直接使用输出文件。
macOS	极少失败。如果失败，通常是因为 pbcopy 命令异常。	检查终端是否具有辅助功能权限（系统偏好设置 -> 安全性与隐私 -> 隐私 -> 辅助功能）。
通用方案	pyperclip 安装有问题或版本冲突。	重新安装： pip install --force-reinstall pyperclip 。

我的实践 ：在跨平台工作中，我 从不完全依赖剪贴板 。我会始终开启 CREATE_FILE = True ，然后使用终端命令或文件管理器快速打开输出文件，再用鼠标选中复制。这样更可控，尤其是处理大型项目时，能避免因剪贴板内容意外被覆盖而丢失。

5.3 问题三：输出文件过大，导致AI无法处理或粘贴卡顿

优化策略：

1. 利用 .gitignore ：确保 USE_GITIGNORE = True 。一个良好的 .gitignore 已经帮你过滤了大多数构建产物和依赖。
2. 调整 MAX_FILE_SIZE_MB ：从默认的5MB降低到1MB或2MB，可以瞬间过滤掉很多编译后的二进制包、视频、数据库文件等。
3. 使用 MAX_DEPTH ：如果你的项目结构是扁平的，或者你只关心顶层逻辑，将深度设为2或3。
4. 针对性过滤目录 ：在 BLACKLIST_DIRS 中明确加入那些你知道包含大量非源码文件的目录，如 docs/images/ , data/raw/ , static/vendor/ 。
5. 分模块导出 ：不要总想着一次导出整个巨型仓库。分别进入 frontend/ 和 backend/ 目录，运行两次工具，生成两个独立的上下文文件，分别提交给AI分析。

5.4 问题四：包含了我不想暴露的敏感文件（如 .env ）

这是一个安全问题，必须重视。

解决方案：

1. 首要方法：依赖 .gitignore 。确保你的 .env 、 config.local.json 等敏感文件在项目的 .gitignore 列表中。工具在 USE_GITIGNORE = True 时会自动排除它们。
2. 配置黑名单 ：在配置文件的 BLACKLIST_FILENAMES 中加入 ".env" , "secrets.yml" 等。
3. 使用 FILENAME_FILTER_MODE = "contains" ：如果你有一系列类似 config.production.json , config.staging.json 的文件，可以设置 FILENAME_FILTER_MODE = "contains" ，并在 BLACKLIST_FILENAMES 中加入 "config." ，但要注意这可能会误伤 config.schema.json 等非敏感文件。
4. 终极检查 ：在将输出内容粘贴给AI前， 务必 用文本编辑器打开生成的 output.txt ，快速搜索一下 .env 、 password 、 secret 、 key 等关键词，做最后的人工审查。

5.5 性能与效率心得

• 首次扫描慢 ：工具在首次扫描一个大型项目时，可能会因为文件系统I/O而稍慢。后续扫描相同项目（文件未变）时，由于系统缓存，速度会快很多。
• 忽略虚拟环境 ：务必把 venv , .venv , node_modules 等加入 BLACKLIST_DIRS 。这些目录包含成千上万个小文件，会严重拖慢扫描速度，且对代码分析毫无意义。
• 输出文件位置 ：默认输出到 outputs/<config_name>/ 下。我习惯将 OUTPUT_DIR 改为 exports ，并在项目的 .gitignore 里加上 /exports/ ，防止这些临时文件被误提交。
• 集成到工作流 ：你可以为这个工具创建一个Shell别名或函数。比如在 .zshrc 或 .bashrc 中添加：

  alias ai-export='python /path/to/Code-Export-For-AI/main.py -c my_project'
  

  这样，在任何项目目录下，只需运行 ai-export ，它就会以当前目录为项目根目录，使用 my_project 配置进行导出，极大提升了使用频率。

这个工具的精髓在于“聚焦”和“净化”。它帮你从庞杂的项目文件中，提取出AI真正需要阅读和分析的“核心源代码”，并以一种高度结构化的方式呈现。经过几次配置和磨合，它就能无缝融入你的开发调试流程，成为与AI结对编程时一个无声却高效的伙伴。