Code Extractor - 智能项目代码提取工具

Code Extractor 是一个基于 Node.js 开发的命令行工具，旨在将复杂的项目目录结构和核心代码内容“扁平化”输出为一个单一的 Markdown 文件 (.md)。

该工具主要用于整理项目上下文，方便开发者将整个项目的核心逻辑一次性投喂给 ChatGPT、Claude 等大语言模型 (LLM) 进行代码分析、重构或文档编写。

✨ 核心特性

• ⚡️ Token 极致优化：摒弃了繁琐的 ASCII 分隔符，全面采用 Markdown 格式。利用 LLM 对 Markdown 语法的天然理解能力，大幅减少 Token 占用。
• 🛡️ 灵活的过滤策略：内置两种过滤优先级模式（强制包含 vs 严格排除），解决“既想要忽略整个文件夹，又想保留其中某几个文件”或“包含整个目录但必须排除敏感文件”的复杂需求。
• 🤖 LLM 友好型结构：
  • [CE] 语义标记：所有生成的元数据（目录树、文件名、统计信息）均带有 [CE] (Code Extractor) 标记，帮助 AI 精准区分“工具生成的描述”与“用户实际的代码”。
  • 安全围栏 (Safe Fencing)：智能计算反引号数量，使用 4 个或更多反引号 包裹代码块，解决代码中含有 Markdown 符号导致的格式冲突。
• 🧠 智能类型推断：根据文件特征（如 package.json 依赖）自动识别 Vue, React, Node.js, Flutter 等项目类型，并应用特定的扫描策略。
• 🌳 目录树生成：生成清晰的目录结构树。针对大文件夹（>100 个文件），自动进行折叠处理。
• 📄 智能内容提取：
  • 自动识别并加载 .gitignore 规则。
  • 大文件处理：超过 100KB 的文件自动截断（保留首尾），并以注释形式提示。
  • JSON 结构化裁剪：保留超大 JSON 的层级结构，但自动裁剪过长的数组和对象。
  • 二进制过滤：自动跳过图片、编译产物等二进制文件。

🚀 支持的项目类型

目前支持的自动识别类型如下：

项目类型	关键词/特征	策略备注
Vue	vue, nuxt	自动忽略 .nuxt, dist, dist-ssr
React	react, next	自动忽略 .next, build, .docusaurus
Electron	electron	优先识别，支持包裹 Web 框架
Flutter	pubspec.yaml	自动忽略 .dart_tool, android, ios 等原生目录
Node.js	后端框架 (express等)	区分纯后端与通用 Web
Generic Web	index.html, Webpack/Vite	兜底策略

🛠 环境要求

• Node.js: v14.0.0 或更高版本 (推荐 v16+)
• 系统: macOS / Linux / Windows

📦 安装

在项目根目录下执行安装依赖：

npm install

建立全局链接（推荐）：

npm link

之后即可在任意位置直接使用 code-extractor 命令。

💻 使用方法

1. 命令行模式 (CLI)

基本用法： 指定项目路径（支持相对路径或绝对路径）即可开始扫描。

# 扫描当前目录下的 demo 项目
code-extractor ./demo-project

# 或者使用绝对路径
code-extractor /Users/username/workspace/my-app

2. 可视化 Web 界面 (GUI)

通过图形化界面进行配置，适合不熟悉命令行参数的用户。

code-extractor ui

启动后浏览器将自动打开 http://localhost:3000。

注意：由于浏览器安全限制，Web 界面无法直接读取文件夹路径。请在界面中手动粘贴项目的完整绝对路径进行扫描。

进阶选项 (Advanced)

Code Extractor 提供过滤控制能力，可通过参数精细控制扫描范围。

1. 添加额外排除规则 (-e / --exclude)

在默认策略和 .gitignore 的基础上，额外排除某些目录或文件。

# 排除所有测试文件和 logs 目录
code-extractor ./my-project -e "test" "*.spec.js" "logs"

2. 强制包含/白名单 (-i / --include)

扫描被默认策略忽略的重要目录（如 Node 项目的 bin 目录）。

# 正常扫描，但强制包含 bin 目录（即使默认策略忽略了它）
code-extractor ./my-project -i "bin"

3. 设定过滤优先级 (-p / --priority) ✨

当“包含规则”与“排除规则”发生冲突时，通过此参数决定谁生效。

• 模式 A: 强制包含 (默认) include-preferred

  • 逻辑：Include > Exclude
  • 场景：.gitignore 忽略了 dist 目录，但我非要看里面的 main.js。只要在 Include 里写了，它就会被扫描，忽略排除规则。

  code-extractor ./my-project -i "dist" --priority include-preferred

• 模式 B: 严格排除 exclude-preferred

  • 逻辑：Exclude > Include
  • 场景：我包含了整个 src 目录，但我绝对不想看到任何 *.secret.js 文件，哪怕它在 src 里面。

  code-extractor ./my-project -i "src" -e "*.secret.js" --priority exclude-preferred

命令行参数一览表

选项	简写	说明
--exclude	-e	额外排除的文件或目录模式 (空格分隔)
--include	-i	额外包含的文件或目录模式 (空格分隔)
--priority	-p	冲突时的优先级策略：include-preferred (默认) 或 exclude-preferred
--help	-h	显示帮助信息

📂 输出结果

扫描完成后，结果将保存在当前目录的 output/ 文件夹下，文件名为： 项目名-项目类型-上级目录名.md

输出文件片段示例：

# 🛡️ [CE] 项目扫描报告: my-app

- **项目类型**: vue
- **优先级策略**: Force Include (包含优先)
- **生成时间**: 2025-11-30 20:45:00

#### 🌳 [CE] 目录结构树

````text
/
├── bin/
│   └── cli.js
├── src/
│   ├── App.vue
│   └── main.js
...

📚 [CE] 文件内容详情

📝 [CE] 文件: bin/cli.js

#!/usr/bin/env node
console.log('Hello World');

📝 [CE] 文件: src/App.vue

<template>
  <div id="app">...</div>
</template>

## 🏗 二次开发指南

本项目采用**策略模式 (Strategy Pattern)** 构建。

### 目录结构

```text
src/
├── core/
│   ├── Scanner.js     # 核心扫描逻辑 (包含优先级判定)
│   ├── Runner.js      # 任务调度器
│   └── ...
├── server/            # Web UI 服务端
├── strategies/        # 策略模块 (定义不同框架的默认忽略规则)
└── index.js           # 逻辑入口
bin/
└── cli.js             # 命令行参数解析

提示词 (Prompting) 建议

将生成的 .md 文件发给 AI 时，建议配合以下提示词：

"这是一个项目的完整代码扫描报告。请忽略所有以 [CE] 开头的标记和结构信息，它们只是元数据。请重点分析 '文件内容详情' 部分的代码，并回答我关于 xxx 的问题。"

---

License: ISC