# miku-text-bundle：面向生成式AI的代码库文本收集与分块工具

> 一个Node.js CLI工具，用于将代码库中的文本文件收集并分割成适合传递给生成式AI的Markdown bundles，支持智能分块、编码处理和TODO提取。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-06T12:14:36.000Z
- 最近活动: 2026-06-06T12:24:30.941Z
- 热度: 163.8
- 关键词: CLI工具, 生成式AI, 代码库分析, Markdown, Node.js, 上下文窗口, 代码审查, 自动化工具, 开发者工具, AI辅助编程
- 页面链接: https://www.zingnex.cn/forum/thread/miku-text-bundle-ai
- Canonical: https://www.zingnex.cn/forum/thread/miku-text-bundle-ai
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：igapyon
- 来源平台：github
- 原始标题：miku-text-bundle
- 原始链接：https://github.com/igapyon/miku-text-bundle
- 来源发布时间/更新时间：2026-06-06T12:14:36Z

## 原作者与来源\n\n- **原作者/维护者**: Toshiki Iga (@igapyon)\n- **来源平台**: GitHub\n- **原始标题**: miku-text-bundle\n- **原始链接**: https://github.com/igapyon/miku-text-bundle\n- **发布时间**: 2026-06-06\n\n## 工具概述\n\nmiku-text-bundle 是一个专门设计用于解决"如何将整个代码库传递给生成式AI"这一问题的命令行工具。随着 ChatGPT、Claude 等大语言模型在软件开发中的广泛应用，开发者经常需要将项目代码作为上下文提供给 AI 助手。然而，直接复制粘贴大量文件既繁琐又容易超出模型的上下文窗口限制。\n\n这个工具通过自动收集指定目录下的文本文件，将其打包成结构化的 Markdown 文档，并在必要时进行智能分块，使得开发者可以方便地将整个项目"喂给"AI 进行代码审查、重构建议或文档生成。\n\n## 核心功能与设计哲学\n\n### 1. 智能文件收集\n\n工具会自动遍历输入目录，识别并收集所有文本文件，同时智能排除常见的非文本内容：\n\n**默认排除的目录**：\n- 版本控制：`.git`\n- IDE配置：`.idea`, `.vscode`\n- 构建输出：`build`, `dist`, `target`\n- 依赖管理：`node_modules`\n- 临时文件：`temp`, `tmp`, `workplace`\n\n**默认排除的文件扩展名**：\n- 媒体文件：`.jpg`, `.png`, `.mp4`, `.wav` 等\n- 压缩文件：`.zip`, `.tar.gz`, `.7z` 等\n- 二进制文件：`.exe`, `.dll`, `.so` 等\n- 文档文件：`.pdf`, `.docx`, `.xlsx` 等\n\n这种设计确保了只有真正有价值的源代码和配置文件会被纳入 bundle，避免了无关内容的干扰。\n\n### 2. 多编码支持\n\n考虑到不同项目可能使用不同的字符编码，工具提供了灵活的编码处理：\n\n- **默认编码**: UTF-8\n- **可选编码**: Shift_JIS（针对遗留日语项目）\n- **扩展名级编码**: 可以为特定文件类型指定不同编码\n\n示例配置：\n```bash\nmiku-text-bundle --input . --output out \\\n  --encoding utf-8 \\\n  --encoding-extension \".java=shift_jis,.properties=shift_jis\"\n```\n\n这种细粒度的编码控制对于维护遗留系统或处理多语言项目尤为重要。\n\n### 3. 智能分块机制\n\n当代码库较大时，单个文件可能超出 AI 的上下文限制。工具提供了智能分块功能：\n\n**分块参数**：\n- `--max-chars`: 每个 bundle part 的最大字符数（默认 120,000）\n- `--max-input-file-bytes`: 单个输入文件的最大字节数（默认 1,000,000）\n\n**分块策略**：\n- 优先保持文件完整性，按文件边界分割\n- 当单个文件超过限制时，按行分割并添加警告\n- 生成索引文件记录分块信息\n\n**输出文件命名规则**：\n- `text-bundle-000-prompt.md`: 使用指南和提示模板\n- `text-bundle-001.md` 至 `text-bundle-998.md`: 实际的代码内容\n- `text-bundle-999-index.md`: 索引和元数据\n\n这种命名约定使得用户可以按照数字顺序依次将内容提供给 AI，而索引文件作为结束标记。\n\n### 4. .gitignore 集成\n\n工具会自动读取输入目录下的 `.gitignore` 文件，并据此排除文件。这确保了 bundle 的内容与版本控制中的实际跟踪文件保持一致，避免了将本地临时文件或敏感配置纳入 bundle。\n\n需要注意的是，工具实现的 `.gitignore` 解析是简化版本，专注于满足工具的核心需求，而非完整实现 Git 的所有忽略规则。\n\n### 5. TODO/FIXME/XXX 提取\n\n工具会自动扫描代码中的 TODO、FIXME、XXX 等标记，并在索引文件中汇总。这为代码审查和任务跟踪提供了便利，开发者可以快速了解项目中的待办事项。\n\n## 使用场景\n\n### 场景一：代码审查与重构\n\n当你想要让 AI 助手审查整个项目的代码质量时：\n\n```bash\nmiku-text-bundle --input . --output ./ai-review\n```\n\n然后将生成的 Markdown 文件依次粘贴到 ChatGPT，并附上类似这样的提示：\n\n```\n请审查以下代码库，重点关注：\n1. 代码结构和组织\n2. 潜在的性能问题\n3. 安全漏洞\n4. 可维护性改进建议\n```\n\n### 场景二：生成项目文档\n\n利用 AI 从代码生成用户文档或 API 文档：\n\n```bash\nmiku-text-bundle --input ./src --output ./docs-bundle --max-chars 80000\n```\n\n### 场景三：遗留系统分析\n\n面对一个没有文档的遗留系统，快速让 AI 理解其架构：\n\n```bash\nmiku-text-bundle --input ./legacy-app --output ./analysis \\\n  --encoding shift_jis \\\n  --add-exclude-directory \"logs,backup\"\n```\n\n### 场景四：面试准备\n\n将开源项目打包后让 AI 解释其工作原理：\n\n```bash\nmiku-text-bundle --input ./awesome-project --output ./study\n```\n\n## 技术实现细节\n\n### 文件排序策略\n\n为了确保输出的一致性（这对分块和比较很重要），工具使用以下排序规则：\n\n1. 将路径转换为 POSIX 格式（使用 `/` 分隔符）\n2. 按 UTF-16 编码单元的 Unicode 码点值升序排序\n3. 不使用本地化特定的排序规则\n\n这种确定性的排序方式确保了相同的输入总是产生相同的输出顺序，便于版本控制和差异比较。\n\n### 文件内容格式\n\n每个收集的文件在 Markdown 中以下列格式呈现：\n\n```markdown\n### path/to/file.ts\n```typescript\n// 文件内容\n```\n```\n\n这种格式具有以下优点：\n- 文件路径作为三级标题，便于导航和引用\n- 代码围栏指定了语言类型，便于语法高亮\n- 保持了原始文件的换行和缩进\n\n### 统计信息输出\n\n执行完成后，工具会输出简洁的统计信息：\n\n```\ncompleted: 3 part(s), 128 file(s) collected, 4 file(s) skipped, \\\n           12 directories ignored, 245 file(s) ignored\n```\n\n使用 `--verbose` 标志可以获取更详细的信息：\n\n```\nignoredDirectories=12\nignoredByDirectory=23\nignoredByExtension=180\nignoredByGitignore=42\nignoredByOutputDirectory=0\n```\n\n这种透明的反馈帮助用户了解哪些文件被包含，哪些被排除，以及排除的原因。\n\n## 与其他工具的比较\n\n### 与简单 `tar` 或 `zip` 的比较\n\n| 特性 | miku-text-bundle | tar/zip |\n|------|------------------|---------|\n| AI可读性 | 原生 Markdown，可直接粘贴 | 需要解压和查看 |\n| 上下文窗口适配 | 智能分块 | 无此功能 |\n| 代码高亮 | 自动语言检测 | 无 |\n| 文件导航 | 目录结构清晰 | 需要额外工具 |\n| TODO提取 | 自动扫描 | 无 |\n\n### 与 IDE "Copy as AI Prompt" 的比较\n\n许多现代 IDE（如 Cursor、GitHub Copilot）提供了将代码发送给 AI 的功能，但 miku-text-bundle 有其独特优势：\n\n- **批量处理**: 一次性处理整个项目，而非单个文件\n- **离线可用**: 不依赖特定 IDE 或在线服务\n- **可版本化**: 生成的 bundle 可以纳入版本控制\n- **可定制**: 灵活的配置选项适应不同需求\n\n## 最佳实践\n\n### 1. 合理设置分块大小\n\n不同的 AI 模型有不同的上下文限制：\n\n- GPT-4: 约 128K tokens\n- Claude 3: 约 200K tokens\n- 其他模型: 可能只有 4K-8K tokens\n\n建议根据目标模型调整 `--max-chars` 参数，留出足够的空间给提示和回复。\n\n### 2. 使用排除列表优化\n\n对于大型项目，默认排除可能不够。可以通过以下方式进一步优化：\n\n```bash\nmiku-text-bundle --input . --output out \\\n  --add-exclude-directory \"tests,docs,examples\" \\\n  --add-exclude-extension \".test.js,.spec.ts\"\n```\n\n### 3. 结合版本控制使用\n\n将生成的 bundle 目录加入 `.gitignore`，避免将生成的文件提交到版本控制：\n\n```\n# .gitignore\nai-bundles/\n```\n\n### 4. 创建快捷脚本\n\n为常用场景创建 shell 脚本或 npm script：\n\n```json\n{\n  \"scripts\": {\n    \"ai:review\": \"miku-text-bundle --input . --output ./ai-review\",\n    \"ai:src-only\": \"miku-text-bundle --input ./src --output ./ai-src --max-chars 80000\"\n  }\n}\n```\n\n## 局限性与注意事项\n\n### 1. 上下文窗口限制\n\n即使经过分块，超大项目仍可能需要多次交互才能完整传递给 AI。用户需要规划好分块策略，确保 AI 能够建立对项目整体架构的理解。\n\n### 2. 二进制文件处理\n\n工具无法处理真正的二进制文件（如编译后的可执行文件、图片等）。这些文件会被自动跳过，如果它们是项目的重要组成部分，需要以其他方式向 AI 描述。\n\n### 3. 编码检测限制\n\n工具不会自动检测文件编码，需要用户显式指定。对于编码混杂的项目，可能需要多次运行或手动处理。\n\n### 4. 敏感信息泄露风险\n\n由于工具会收集目录下的所有文本文件，务必注意：\n- 不要将包含 API 密钥、密码的配置文件纳入 bundle\n- 检查 `.gitignore` 是否正确配置\n- 审查生成的 bundle 后再发送给 AI\n\n## 总结\n\nmiku-text-bundle 是一个精心设计的实用工具，它解决了开发者在使用生成式 AI 时的一个常见痛点：如何高效地将代码库作为上下文提供给 AI。通过智能的文件收集、灵活的分块策略和对多种编码的支持，它使得这一过程变得简单可靠。\n\n随着 AI 辅助编程的普及，这类工具的重要性将日益凸显。miku-text-bundle 不仅是一个技术实现，更代表了一种工作流的优化：让开发者能够更专注于与 AI 的创造性协作，而非繁琐的文件操作。