1. 项目概述与核心痛点

如果你和我一样，每天都在和 Cursor、Copilot、Claude 这类 AI 编程助手打交道，那你一定经历过这种抓狂时刻：你想让 AI 帮你改几行核心业务逻辑，结果它吭哧吭哧地把你项目里那几百兆的 venv 虚拟环境、 node_modules 文件夹，甚至几个 G 的日志文件全给“看”了一遍。最后，它要么因为上下文窗口爆满而“失忆”，要么就开始一本正经地胡说八道（幻觉）。你支付的昂贵 Token，大部分都浪费在了这些 AI 根本不需要看到的“垃圾”上。

这就是 AI-Native Project Scaffolding（我习惯叫它 AI 工具箱）要解决的核心问题。它不是一个普通的脚手架生成器，而是一个专门为“AI 辅助开发”这个新范式设计的项目优化引擎。它的目标很简单： 让你的项目对 AI 来说，就像一本结构清晰、重点突出的说明书，而不是一个塞满杂物的仓库。

想象一下，你有一个 50 个文件的实际代码项目，但 AI 看到的上下文里却混杂了 500 万个 Token 的无关信息。AI 工具箱通过一系列精密的自动化操作，能将这个数字压缩到原来的 1% 甚至更低。它不仅仅是生成一个干净的初始结构，更能像一个经验丰富的“项目医生”一样，诊断并修复现有项目的各种“AI 不友好”症状，比如把虚拟环境挪到项目外部、自动生成智能的忽略规则、甚至将大型数据文件移走并自动修补代码中的引用路径。

这个工具适合所有希望提升 AI 编码效率的开发者，无论你是想快速启动一个为 AI 优化过的新项目，还是想拯救一个已经被各种依赖和垃圾文件拖慢的旧项目。接下来，我会带你深入它的设计哲学、核心功能以及我是如何在实际项目中应用它的。

2. 设计哲学与核心架构解析

2.1 三大核心原则：为 AI 而生的项目哲学

这个项目的背后有一套非常清晰且强硬的设计哲学，我称之为“AI 原生三原则”。理解这些原则，你就能明白它每一个功能决策背后的逻辑。

原则一：虚拟环境永驻项目之外 这是第一条，也是最重要的一条铁律。一个典型的 Python venv 或 node_modules 文件夹，动辄几百兆，包含成千上万个文件。对 AI 来说，解析这些文件不仅是巨大的 Token 浪费，更会严重干扰它对项目核心逻辑的理解。AI 工具箱在创建新项目时，会强制在项目目录的 上一级 创建一个统一的 _venvs 目录来存放所有虚拟环境。对于现有项目， doctor 命令会检测并帮你迁移。这不仅仅是移动文件夹，它还会自动更新你的 IDE 配置和启动脚本，确保开发体验无缝衔接。

原则二：绝不完整读取大型文件 日志、CSV 数据集、大型 JSON 配置文件——这些文件对 AI 理解代码逻辑帮助甚微，但消耗的 Token 却极其惊人。传统的 .gitignore 或 .cursorignore 只能让 AI 不看它们，但有时 AI 又确实需要知道这些文件的结构（Schema）。AI 工具箱的“深度清理（Deep Clean）”功能提供了更优雅的解决方案：它将大型文件移动到项目外部的 _data 目录，同时在项目内生成一个轻量级的“导航地图”（ AST_FOX_TRACE.md ），里面只描述文件的结构和用途，并自动生成一个“桥梁”文件（ config_paths.py ）来修补代码中对这些文件路径的引用。AI 通过阅读几百个 Token 的地图就能掌握全局，无需吞下数万 Token的原始数据。

原则三：先查阅，后创建 项目里应该有一个 _AI_INCLUDE/ 目录，里面存放着项目的编码规范（ PROJECT_CONVENTIONS.md ）、核心文件位置说明（ WHERE_THINGS_LIVE.md ）等元信息。这相当于给 AI 的一份“入职指南”。在让 AI 编写新代码前，先引导它阅读这些文件，能极大提升生成代码的准确性和一致性。AI 工具箱会自动为所有主流 AI 助手（Cursor, Copilot, Claude, Windsurf）生成对应的配置文件，其中就包含指向这些指南的指令。

2.2 架构总览：模块化与命令驱动

整个工具采用经典的 CLI 工具架构，清晰且易于扩展。所有功能都通过 main.py 这个统一的入口点，以子命令的形式调用。

AI-Native_Project_Scaffolding/
├── src/
│   ├── commands/       # 核心：12个CLI命令的实现
│   │   ├── create.py   # 项目创建
│   │   ├── doctor.py   # 项目诊断与修复（核心）
│   │   ├── trace.py    # AST依赖追踪
│   │   └── ...
│   ├── generators/     # 生成器：负责创建各类文件
│   │   ├── ai_configs.py # 生成.cursorrules等AI配置
│   │   ├── scripts.py    # 生成bootstrap.sh等脚本
│   │   └── ...
│   ├── utils/         # 工具箱：各种底层工具函数
│   │   ├── context_map.py     # 核心：用AST解析代码结构
│   │   ├── heavy_mover.py     # 核心：大文件移动与代码修补
│   │   ├── ast_patcher.py     # 核心：自动重构代码引用
│   │   └── ...
│   └── core/          # 核心配置与常量
├── templates/         # 6种项目模板（bot, webapp等）
└── tests/            # 超过220个测试，保障稳定性

这种架构的好处是职责分离。 commands 目录下的每个文件都对应一个清晰的用户意图（如“创建”、“诊断”）。当需要执行复杂操作时，命令模块会调用 generators 来生成文件，或使用 utils 里的工具函数完成具体任务。例如， doctor --deep-clean 命令会依次调用 token_scanner.py 寻找大文件， heavy_mover.py 移动它们， ast_patcher.py 修改代码，最后 fox_trace_map.py 生成导航地图。

3. 核心功能深度剖析与实战

3.1 项目创建与模板系统：一键生成AI就绪环境

create 命令是起点。它不仅仅是创建文件夹和复制文件，而是在构建一个为协作（人与AI）优化过的生态系统。

# 交互式创建，工具会一步步引导你
python main.py create

# 或直接指定参数创建
python main.py create my_telegram_bot --template bot

运行后，你会得到一个立即可以投入开发的项目结构。以 bot 模板为例，它不仅仅生成了 aiogram 的基础结构，还包含了为AI优化过的完整配置：

my_telegram_bot/
├── .cursor/                    # Cursor专属配置
│   └── rules/
│       ├── project.md          # 项目级规则：技术栈、架构
│       └── handlers.md         # 模块级规则：如何编写处理器
├── .github/
│   └── copilot-instructions.md # 给GitHub Copilot的指令
├── _AI_INCLUDE/
│   ├── PROJECT_CONVENTIONS.md  # 代码风格：用f-string，异常处理规范
│   └── WHERE_THINGS_LIVE.md    # 文件地图：中间件在哪，数据库配置在哪
├── scripts/
│   ├── bootstrap.sh            # 环境一键安装脚本
│   └── context.py              # 动态上下文切换器（高级功能）
├── src/
│   ├── handlers/               # 你的业务逻辑
│   ├── keyboards/
│   ├── middlewares/
│   └── ...
├── .cursorignore               # 智能忽略规则（已排除venv, __pycache__等）
├── .cursorrules                # 主规则文件（引用上述模块化规则）
├── CLAUDE.md                   # 给Claude的专属提示
├── .windsurfrules              # Windsurf配置
└── requirements.txt            # 依赖（aiogram, redis等）

关键细节与技巧：

• bootstrap 脚本的妙用 ：生成的 scripts/bootstrap.sh （或 .ps1 ）是你和团队新人快速上手的利器。它不仅仅执行 pip install ，还会根据当前操作系统，自动在项目外的 ../_venvs/ 创建虚拟环境，并打印出激活命令。我建议把这个脚本加入你的项目 README 第一步。
• 模块化的AI规则 ： .cursor/rules/ 下的多个 .md 文件比一个巨大的 .cursorrules 更有效。AI 可以根据当前编辑的文件，更精准地加载相关规则。例如，当你在 handlers/ 目录下工作时， handlers.md 中的规则会被优先考虑。
• 模板的选择 ： full 模板看似全能，但如果你刚开始，我建议从 bot 或 fastapi 这样的单一模板入手。 monorepo 模板适用于微服务或共享库的多项目场景，它会生成一个包含 packages/ 和 shared/ 的复杂结构，对AI上下文管理要求更高。

3.2 Doctor命令：全自动项目诊断与修复

这是工具箱中最强大、最常用的功能。你的项目随着时间推移，难免会混入 __pycache__ 、本地测试数据库、临时日志等“垃圾”。手动清理费时费力，且容易出错。 doctor 命令就是你的自动化项目保洁员。

# 第一步：先做体检，生成报告，不修改任何文件
python main.py doctor /path/to/your/project --report

# 第二步：信任它，一键修复所有问题
python main.py doctor /path/to/your/project --auto

doctor 的工作流程像一个严谨的医生：

1. 诊断 ：使用 token_scanner.py 等工具扫描项目，根据预定义的规则库给问题分类。
   • CRITICAL（红色） ：虚拟环境在项目内、 node_modules 、大型二进制文件。这些是“肿瘤”，必须切除。
   • WARNING（黄色） ： __pycache__ 、 .log 文件、 .DS_Store 。这些是“炎症”，需要清理。
   • SUGGESTION（绿色） ：缺少 AI 配置文件、 .cursorignore 规则不完善。这些是“亚健康”，建议优化。
2. 治疗 ：根据诊断结果，按顺序执行修复操作。它会先创建一个完整的 .tar.gz 备份，让你绝对安心。然后开始清理、移动文件、生成配置。
3. 康复报告 ：最后呈现一个清晰的对比报告，展示修复前后 Token 数、问题数量的变化。

实操心得与避坑指南：

• 一定要先 --report ：尤其是在第一次对重要项目使用前，务必先用 --report 模式查看它会做什么。有时候它可能把一些你需要的但较大的配置文件（如本地化的 config.prod.json ）标记为“大文件”，你可以根据报告调整后续命令的参数。
• 理解修复逻辑 ： doctor 移动文件时，会在原位置创建一个同名的软链接（符号链接）吗？ 不会 。它的哲学是彻底移除干扰源。对于需要被移走但代码又引用的数据文件，它会通过后续的 --deep-clean 功能配合 config_paths.py 桥梁来解决。对于纯粹的垃圾如 __pycache__ ，则是直接删除。
• 与版本控制的配合 ：运行 doctor --auto 后，你会看到工作区有很多文件变更（新增的配置文件、删除的垃圾文件）。这是一个很好的提交点，建议你 git add 这些有益的变更，同时确保 .gitignore 文件已经包含了被移走文件的原始路径（通常 AI 工具箱的模板已包含），避免误提交。

3.3 Fox Trace与Deep Clean：极致的Token优化策略

当 doctor 完成了基础清洁后， Fox Trace 和 Deep Clean 这两个功能将 Token 优化推向极致。它们解决的是另一个层面的问题： 代码依赖分析 和 大型资源文件管理 。

Fox Trace：精准的代码依赖图谱 传统做法是，把整个项目文件一股脑塞给 AI。Fox Trace 则像一名外科医生，只提取你关心的那部分代码及其精确的依赖。

# 追踪 src/handlers/payment.py 中所有函数/类的依赖，深入2层
python main.py trace src/handlers/payment.py --depth 2

它的工作原理基于 Python 的 ast （抽象语法树）模块：

1. 解析目标文件，找出所有的 import 语句。
2. 不是简单地把整个被导入文件都拿过来，而是继续分析，只提取目标文件中实际 使用到的 特定函数、类或变量。
3. 将这些代码片段与原始目标代码一起，打包成一个结构化的 XML 或 Markdown 文档。

例如，你的 payment.py 只用了 utils.py 里的 calculate_tax 函数，Fox Trace 就绝不会把 utils.py 里另外 20 个无关函数也带进来。这通常能将需要发送给 AI 的上下文从数百万 Token 减少到数万，实现 99% 以上的缩减。

Deep Clean：大文件搬运工与代码缝合师 这是 v3.5 的王牌功能。它专门处理那些“不能删，但看着又太占地方”的文件，比如 data/products.json (50K tokens)， logs/app.log (100K tokens)。

# 预览哪些文件会被移走（干跑模式）
python main.py doctor ./my_project --deep-clean --dry-run

# 实际执行深度清理，并自动修补代码
python main.py doctor ./my_project --deep-clean --auto --threshold 500

--threshold 500 参数意味着任何估计超过 500 Token 的文件都会被考虑移走。这个功能做了三件了不起的事：

1. 识别与搬迁 ： token_scanner.py 和 heavy_mover.py 协作，识别大文件，并将它们安全地移动到项目外部的 ../_data/project_name/ 目录下。

2. 代码自动修补 ：这是最神奇的一步。 ast_patcher.py 会解析你所有的 Python 代码，寻找那些引用被移动文件的语句。然后，它自动将这些硬编码路径替换为通过 config_paths.py 桥梁函数获取的动态路径。

   # 修补前 - 硬编码路径，AI会读取整个big_data.json
   import json
   with open("data/big_data.json") as f:
       data = json.load(f)
   
   # 修补后 - 通过桥梁函数，AI在上下文中看不到文件内容
   from config_paths import get_path
   import json
   with open(get_path("data/big_data.json")) as f: # AI只看到这个函数调用
       data = json.load(f)
   

   它支持 open() 、 pathlib.Path 、 pandas.read_csv 、 sqlite3.connect 等多种常见模式。

3. 生成AI导航地图 ： fox_trace_map.py 会生成一个 AST_FOX_TRACE.md 文件。这个文件不是数据本身，而是数据的“目录”或“元数据”。

   ## 📦 data/big_data.json
   **位置：** `../_data/my_project/LARGE_TOKENS/data/big_data.json`
   **大小：** ~50,000 Tokens
   **结构：** 一个包含1500个对象的数组，每个对象有 `id` (int), `name` (str), `price` (float) 字段。
   **被引用于：** `src/handlers/shop.py` 第45行。
   

   现在，当你在 shop.py 附近编码并向 AI 提问时，AI 通过阅读这个简短的“地图”，就能理解 big_data.json 的结构和用途，而无需消耗 5 万个 Token 去加载实际内容。这实现了信息传递效率和成本的最优解。

注意事项：

• 桥梁函数的局限性 ：自动修补主要针对标准的文件操作模式。如果你有非常动态的路径拼接（如 os.path.join(‘data’, variable, ‘file.json’) ），可能无法被完美识别和修补。执行后务必运行一遍你的测试用例。
• 恢复机制 ：使用 doctor --restore 可以撤销深度清理操作，将文件移回原位置并恢复代码。它依赖清理时生成的 manifest.json 。所以，切勿手动删除外部 _data 目录下的这个清单文件。
• 版本控制 ：执行深度清理后， config_paths.py 和 AST_FOX_TRACE.md 应该被加入版本控制。而外部的 _data 目录应该被加入 .gitignore 。你需要考虑如何与团队共享这些大型数据文件（例如通过网盘、Git LFS 或内部文件服务器）。

4. 与主流AI助手集成实战

AI工具箱的价值，最终体现在你日常使用的IDE和AI助手上。它为你准备好了所有“开箱即用”的配置。

4.1 Cursor：深度集成与规则引擎

Cursor 是目前对这类优化最敏感的编辑器。AI 工具箱为其生成了一套组合拳配置：

• .cursorignore ：这是第一道防线。它比 .gitignore 更激进，排除了所有 AI 绝对不需要看的文件类型（如 *.pyc , *.log , *.sqlite , *.jpg ），以及根据本项目哲学排除了 venv/ 、 */__pycache__/ 等目录。
• .cursorrules ：这是主配置文件。它的关键作用是 include 指令，将复杂的规则模块化。

  # .cursorrules
  When working anywhere in the project:
  - Read the `_AI_INCLUDE/PROJECT_CONVENTIONS.md` first.
  - Follow the Python style guidelines defined there.
  
  # 引入模块化规则
  {{ include “.cursor/rules/project.md” }}
  {{ include “.cursor/rules/handlers.md” }}
  

• .cursor/rules/ 目录 ：这里存放着针对不同模块的细化规则。例如 handlers.md 里会写：“本项目的处理器都采用类视图，请使用 async def 并妥善处理异常”。当你在 handlers/ 目录下新建文件时，Cursor 会自动加载这些相关规则，提供更精准的补全和建议。

配置技巧 ：你可以手动往 .cursor/rules/ 里添加更多 .md 文件，比如 database.md 来描述你的 ORM 使用规范，然后在 .cursorrules 里包含它。这让 AI 的“知识”变得可维护、可扩展。

4.2 GitHub Copilot 与 Claude

• GitHub Copilot ：通过 .github/copilot-instructions.md 文件提供全局指令。这个文件对所有使用 Copilot 的开发者生效。你可以在这里定义项目级的模式，比如“所有 API 响应请使用统一的 ResponseSchema 包装”。
• Claude ： CLAUDE.md 文件是给 Claude Code（或类似产品）的专用提示。由于 Claude 的上下文窗口可能更大，你可以在这里提供更详细的架构说明和示例代码。

4.3 通用配置： _AI_INCLUDE/ 目录

这个目录是项目的“知识库”，是所有 AI 助手的共享上下文。至少应该包含两个文件：

1. PROJECT_CONVENTIONS.md ：代码风格、提交信息规范、命名约定等。
2. WHERE_THINGS_LIVE.md ：项目结构导航。例如：“用户模型在 src/models/user.py ，数据库配置在 src/core/database.py ，工具函数在 src/utils/helpers.py ”。

当 AI 助手被要求创建一个新功能时，优先引导它阅读这些文件，能极大减少因“不了解项目情况”而产生的错误或不符合规范的代码。

5. 高级应用场景与排坑指南

5.1 在现有大型项目中引入AI工具箱

对于已经存在一段时间、结构可能有些混乱的项目，直接运行 doctor --auto 可能有些冒险。我推荐一个渐进式的“五步法”：

1. 备份 ：确保项目已用 Git 提交，或手动备份。
2. 扫描评估 ：运行 python main.py health /path/to/project 或 doctor --report ，生成一份“体检报告”。仔细阅读，了解主要问题。
3. 分步执行 ：
   • 先处理垃圾 ：手动或使用 cleanup 命令清理明显的 __pycache__ 、日志文件。
   • 迁移虚拟环境 ：如果 venv 在项目内，这是提升最大的步骤。可以手动将 venv 文件夹移到项目外部（如 ../_venvs/project-name ），然后使用 doctor --auto ，它会帮你修复激活脚本和 IDE 配置。
   • 引入AI配置 ：运行 python main.py migrate . 。这个命令会谨慎地添加缺失的 .cursorrules 、 .cursorignore 、 _AI_INCLUDE/ 等文件，而不会改动你的现有代码。
4. 深度清理（可选） ：在确保代码有良好测试覆盖后，尝试对某个子目录运行 doctor --deep-clean --dry-run ，预览效果。确认无误后再对全项目执行。
5. 团队同步 ：将生成的 AI 配置文件（ .cursor* , .github/copilot-instructions.md , _AI_INCLUDE/ ）提交到版本库。同时，更新团队的 README ，说明新的项目结构约定（如虚拟环境位置）。

5.2 常见问题与解决方案

在实际使用中，你可能会遇到以下问题，这里是我的排查思路：

问题现象	可能原因	解决方案
运行 bootstrap.sh 脚本时报权限错误	脚本没有执行权限	执行 chmod +x scripts/bootstrap.sh
doctor --deep-clean 后代码运行报 FileNotFoundError	ast_patcher 未能识别某些动态路径	1. 检查 config_paths.py 中的 get_path 函数逻辑。 2. 手动修复报错的文件路径，改为使用 from config_paths import get_path 。 3. 考虑将某些文件从清理阈值中排除（ --threshold 调大）。
Cursor 似乎没有读取 .cursorrules	Cursor 版本过旧或配置文件位置不对	1. 确保 Cursor 更新到最新版。 2. 确保 .cursorrules 文件在项目根目录。 3. 在 Cursor 中尝试重启语言服务器（Command Palette: Cursor: Restart Language Server ）。
fox trace 命令报语法错误	目标 Python 文件存在语法错误（如 async/await 使用不当）	fox trace 依赖 ast 模块解析，文件必须语法正确。先修复文件中的语法错误。
执行命令后项目 Token 数没明显下降	最大的 Token 占用者可能不是文件，而是某个巨大的单行字符串或内嵌数据	使用 doctor --report 仔细查看报告，找到具体的“大文件”列表。有时需要手动优化代码中的大字典或字符串常量。

5.3 性能与成本考量

使用 AI 工具箱的最终目的是节约成本并提升效率。你可以建立一个简单的监控习惯：

1. 建立基线 ：在优化前，用 doctor --report 记录下项目的总估计 Token 数。
2. 优化后对比 ：执行完 doctor --auto 和可能的 --deep-clean 后，再次运行报告，查看 Token 减少的百分比。
3. 关注AI助手的响应 ：最直观的感受是，AI 补全和建议的速度是否变快、准确性是否提高。之前那些因上下文混乱而产生的“幻觉”代码是否减少。

在我的经验中，一个中等规模的 FastAPI 项目（约 50 个文件），优化前 AI 上下文约 120 万 Token，经过“基础清理 + 深度清理”后，可以降到 3 万 Token 以下。这意味着每次向 AI 发送请求的成本降低约 97%，并且响应质量显著提升。

6. 开发模式与贡献指南

如果你想深入了解这个工具，甚至为其添加新功能（比如支持你喜欢的另一个 IDE），它的代码库本身也遵循了“AI 原生”的原则，结构清晰，易于参与。

# 1. 克隆并进入开发环境
git clone https://github.com/Adrena1ine-ai/AI-Native_Project_Scaffolding.git
cd AI-Native_Project_Scaffolding

# 2. 在外部创建开发虚拟环境（践行自身哲学！）
python -m venv ../_venvs/ai-toolkit-dev
source ../_venvs/ai-toolkit-dev/bin/activate  # Linux/Mac
# ..\_venvs\ai-toolkit-dev\Scripts\activate.ps1  # Windows

# 3. 以可编辑模式安装，并包含开发依赖
pip install -e ".[dev]"

# 4. 运行测试套件（220+个测试）
pytest tests/ -v

项目开发的核心约定：

• 测试驱动 ：任何新功能或修复必须附带测试。测试文件位于 tests/ 目录，模仿了主项目的结构。
• 类型提示 ：尽可能使用 Python Type Hints。项目使用 mypy 进行类型检查。
• 代码风格 ：使用 ruff 进行代码格式化和 linting。提交前请运行 ruff check src/ --fix 和 ruff format src/ 。
• 命令模式 ：新的 CLI 命令应在 src/commands/ 下创建新的 .py 文件，并在 main.py 中注册。参考 create.py 或 doctor.py 的模式。
• 工具函数 ：通用的功能应放在 src/utils/ 下。保持函数单一职责，并编写清晰的文档字符串。

为现有项目添加新模板 ： 如果你想添加一个 django 或 streamlit 模板：

1. 在 templates/ 目录下创建新文件夹，例如 django_app 。
2. 在其中放置标准的 Django 项目结构，并 确保包含所有 AI 工具箱的配置文件 （ .cursorignore , _AI_INCLUDE/ 等）。你可以复制现有模板（如 fastapi ）的配置文件作为基础修改。
3. 在 src/core/constants.py 的 TEMPLATES 字典中注册你的新模板。
4. 在 src/generators/project.py 中，确保模板复制逻辑能正确处理你的新模板。
5. 编写相应的测试文件 tests/test_create_django.py 。

这个过程本身，就是利用一个为 AI 优化过的项目，去开发一个帮助他人优化项目的工具，形成了一个非常有趣的闭环。你会发现，在这个项目里编码，由于它自身严格的规范和清晰的上下文，AI 助手（包括 Cursor 和 Copilot）的表现出奇地好，这恰恰证明了其理念的有效性。