repomix

英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

---

在线使用 Repomix！👉 repomix.com

需要讨论吗？加入我们的 Discord！
分享您的经验和技巧
了解新功能的最新动态
获取配置和使用方面的帮助

---

📦 Repomix 是一个强大的工具，它可以将整个代码仓库打包成一个适合 AI 使用的文件。它非常适合在需要将代码库提供给大型语言模型（LLM）或其他 AI 工具（如 Claude、ChatGPT、DeepSeek、Perplexity、Gemini、Gemma、Llama、Grok 等）时使用。

请考虑赞助我。

🏆 开源奖项提名

我们感到非常荣幸！Repomix 已被提名为 JSNation 开源奖 2025 的 Powered by AI 类别。

没有你们使用和支持 Repomix，这是不可能实现的。谢谢你们！

🎉 新：Repomix 网站与 Discord 社区！

• 在浏览器中试用 Repomix: repomix.com
• 加入我们的 Discord 服务器 以获取支持和讨论

我们期待在那里见到你！

🌟 功能

• AI优化：以便于AI理解和处理的方式格式化你的代码库。
• 令牌计数：提供每个文件和整个仓库的令牌计数，有助于大型语言模型（LLM）的上下文限制。
• 简单易用：只需一个命令即可打包整个仓库。
• 可自定义：轻松配置包含或排除的内容。
• Git感知：自动遵循你的 .gitignore、.ignore 和 .repomixignore 文件。
• 安全为先：集成 Secretlint 来检测符合已知凭证格式的文件，并将其排除在输出之外。
• 代码压缩：--compress 选项使用 Tree-sitter 提取关键代码元素，在保留结构的同时减少令牌数量。

🚀 快速开始

使用 CLI 工具 >_

您可以在项目目录中立即尝试 Repomix，无需安装：

npx repomix@latest

或者全局安装以便重复使用：

# Install using npm
npm install -g repomix

# Alternatively using yarn
yarn global add repomix

# Alternatively using bun
bun add -g repomix

# Alternatively using Homebrew (macOS/Linux)
brew install repomix

# Then run in any project directory
repomix

就是这样！Repomix 会在您当前的目录中生成一个 repomix-output.xml 文件，其中包含以 AI 友好格式表示的整个仓库。

然后，您可以将此文件发送给 AI 助手，并使用类似以下的提示：

This file contains all the files in the repository combined into one.
I want to refactor the code, so please review it first.

当你提出具体修改时，AI 可能会相应生成代码。借助 Claude 的 Artifacts 等功能，你可能能够输出多个文件，从而生成多个相互依赖的代码片段。

祝编码愉快！🚀

使用网站 🌐

想快速尝试吗？访问官方网站 repomix.com。只需输入你的仓库名称，填写任何可选信息，然后点击 Pack 按钮，即可查看生成的输出。

可用选项

网站提供了几个方便的功能：

• 可自定义输出格式（XML、Markdown 或纯文本）
• 即时令牌计数估算
• 更多精彩功能！

使用浏览器扩展 🧩

从任何 GitHub 仓库直接即时访问 Repomix！我们的 Chrome 扩展在 GitHub 仓库页面添加了一个方便的“Repomix”按钮。

安装

• Chrome 扩展: Repomix - Chrome 网上应用店
• Firefox 附加组件: Repomix - Firefox 附加组件

功能

• 一键访问任何 GitHub 仓库的 Repomix
• 更多激动人心的功能即将推出！

使用 VSCode 扩展 ⚡️

一个由社区维护的 VSCode 扩展 Repomix Runner（由 massdo 创建）让你可以在编辑器内仅用几次点击就运行 Repomix。在任何文件夹上运行，轻松管理输出，并通过 VSCode 直观界面控制一切。

想把输出作为文件还是仅内容？需要自动清理？这个扩展都能满足你。此外，它还能与现有的 repomix.config.json 流畅协同工作。

现在就在 VSCode 市场 试用它吧！源代码可在 GitHub 获取。

替代工具 🛠️

如果你使用 Python，你可能想查看 Gitingest，它更适合 Python 生态系统和数据科学工作流程：https://github.com/cyclotruc/gitingest

📊 使用方法

打包你的整个仓库：

repomix

打包特定目录：

repomix path/to/directory

要使用 glob 模式 打包特定文件或目录：

repomix --include "src/**/*.ts,**/*.md"

要排除特定的文件或目录：

repomix --ignore "**/*.log,tmp/"

打包远程仓库：

repomix --remote https://github.com/yamadashy/repomix

# You can also use GitHub shorthand:
repomix --remote yamadashy/repomix

# You can specify the branch name, tag, or commit hash:
repomix --remote https://github.com/yamadashy/repomix --remote-branch main

# Or use a specific commit hash:
repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695

# Another convenient way is specifying the branch's URL
repomix --remote https://github.com/yamadashy/repomix/tree/main

# Commit's URL is also supported
repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1

从文件列表打包文件（通过标准输入管道）：

# Using find command
find src -name "*.ts" -type f | repomix --stdin

# Using git to get tracked files
git ls-files "*.ts" | repomix --stdin

# Using grep to find files containing specific content
grep -l "TODO" **/*.ts | repomix --stdin

# Using ripgrep to find files with specific content
rg -l "TODO|FIXME" --type ts | repomix --stdin

# Using ripgrep (rg) to find files
rg --files --type ts | repomix --stdin

# Using sharkdp/fd to find files
fd -e ts | repomix --stdin

# Using fzf to select from all files
fzf -m | repomix --stdin

# Interactive file selection with fzf
find . -name "*.ts" -type f | fzf -m | repomix --stdin

# Using ls with glob patterns
ls src/**/*.ts | repomix --stdin

# From a file containing file paths
cat file-list.txt | repomix --stdin

# Direct input with echo
echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin

--stdin 选项允许你将文件路径列表通过管道传递给 Repomix，从而在选择要打包的文件时提供终极的灵活性。

使用 --stdin 时，指定的文件实际上会被添加到包含模式中。这意味着正常的包含和忽略行为仍然适用——如果通过 stdin 指定的文件匹配忽略模式，它们仍然会被排除。

[!注意]
使用 --stdin 时，文件路径可以是相对路径或绝对路径，Repomix 会自动处理路径解析和去重。

在输出中包含 git 日志的方法：

# Include git logs with default count (50 commits)
repomix --include-logs

# Include git logs with specific commit count
repomix --include-logs --include-logs-count 10

# Combine with diffs for comprehensive git context
repomix --include-logs --include-diffs

Git 日志包括每次提交的日期、提交信息和文件路径，为 AI 分析代码演变和开发模式提供了有价值的上下文。

要压缩输出：

repomix --compress

# You can also use it with remote repositories:
repomix --remote yamadashy/repomix --compress

要初始化一个新的配置文件（repomix.config.json）：

repomix --init

一旦生成了打包文件，您可以将其与生成式人工智能工具一起使用，如 ChatGPT、DeepSeek、Perplexity、Gemini、Gemma、Llama、Grok 等。

Docker 使用 🐳

您也可以使用 Docker 运行 Repomix。如果您想在隔离环境中运行 Repomix 或者更喜欢使用容器，这将非常有用。

基本用法（当前目录）：

docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix

打包特定目录：

docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix path/to/directory

处理远程仓库并输出到 output 目录：

docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote https://github.com/yamadashy/repomix

提示示例

一旦您使用 Repomix 生成了打包文件，您就可以将其用于像 ChatGPT、DeepSeek、Perplexity、Gemini、Gemma、Llama、Grok 等 AI 工具。以下是一些示例提示，供您开始使用：

代码审查与重构

关于全面的代码审查和重构建议：

This file contains my entire codebase. Please review the overall structure and suggest any improvements or refactoring opportunities, focusing on maintainability and scalability.

文档生成

生成项目文档:

Based on the codebase in this file, please generate a detailed README.md that includes an overview of the project, its main features, setup instructions, and usage examples.

测试用例生成

用于生成测试用例：

Analyze the code in this file and suggest a comprehensive set of unit tests for the main functions and classes. Include edge cases and potential error scenarios.

代码质量评估

评估代码质量及遵循最佳实践的情况：

Review the codebase for adherence to coding best practices and industry standards. Identify areas where the code could be improved in terms of readability, maintainability, and efficiency. Suggest specific changes to align the code with best practices.

库概览

对该库有一个高层次的理解

This file contains the entire codebase of library. Please provide a comprehensive overview of the library, including its main purpose, key features, and overall architecture.

请根据您的具体需求和所使用的 AI 工具的功能自由修改这些提示。

社区讨论

查看我们的 社区讨论，用户在其中分享：

• 他们在 Repomix 中使用的 AI 工具
• 他们发现的有效提示
• Repomix 如何帮助了他们
• 充分利用 AI 代码分析的提示和技巧

欢迎加入讨论并分享您的经验！您的见解可能帮助其他人更好地使用 Repomix。

输出文件格式

Repomix 生成一个文件，不同部分之间有清晰的分隔符。为了增强 AI 的理解，输出文件以面向 AI 的解释开头，使 AI 模型更容易理解打包仓库的上下文和结构。

XML 格式（默认）

XML 格式以分层方式组织内容：

This file is a merged representation of the entire codebase, combining all repository files into a single document.

<file_summary>
  (Metadata and usage AI instructions)
</file_summary>

<directory_structure>
src/
cli/
cliOutput.ts
index.ts

(...remaining directories)
</directory_structure>

<files>
<file path="src/index.js">
  // File contents here
</file>

(...remaining files)
</files>

<instruction>
(Custom instructions from `output.instructionFilePath`)
</instruction>

对于那些对 AI 环境中 XML 标签的潜力感兴趣的人： https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags

当您的提示包含多个组件（如上下文、指令和示例）时，XML 标签可能会带来显著变化。它们可以帮助 Claude 更准确地解析您的提示，从而产生更高质量的输出。

这意味着 Repomix 的 XML 输出不仅仅是另一种格式，而可能是将您的代码库输入 AI 系统以进行分析、代码审查或其他任务的更有效方式。

Markdown 格式

要生成 Markdown 格式的输出，请使用 --style markdown 选项：

repomix --style markdown

Markdown 格式以分层的方式组织内容：

This file is a merged representation of the entire codebase, combining all repository files into a single document.

# File Summary

(Metadata and usage AI instructions)

# Repository Structure

src/
cli/
cliOutput.ts
index.ts

(...remaining directories)

# Repository Files

## File: src/index.js

// File contents here

(...remaining files)

# Instruction

(Custom instructions from `output.instructionFilePath`)

这种格式提供了一个简洁、可读的结构，既适合人类阅读，又易于被人工智能系统解析。

JSON 格式

要生成 JSON 格式的输出，请使用 --style json 选项：

repomix --style json

JSON 格式将内容结构化为具有驼峰命名属性的层级 JSON 对象：

{
  "fileSummary": {
    "generationHeader": "This file is a merged representation of the entire codebase, combined into a single document by Repomix.",
    "purpose": "This file contains a packed representation of the entire repository's contents...",
    "fileFormat": "The content is organized as follows...",
    "usageGuidelines": "- This file should be treated as read-only...",
    "notes": "- Some files may have been excluded based on .gitignore, .ignore, and .repomixignore rules..."
  },
  "userProvidedHeader": "Custom header text if specified",
  "directoryStructure": "src/\n  cli/\n    cliOutput.ts\n    index.ts\n  config/\n    configLoader.ts",
  "files": {
    "src/index.js": "// File contents here",
    "src/utils.js": "// File contents here"
  },
  "instruction": "Custom instructions from instructionFilePath"
}

这种格式非常适合：

• 程序化处理：使用 JSON 库易于解析和操作
• API 集成：可直接被 Web 服务和应用程序使用
• AI 工具兼容性：为机器学习和人工智能系统提供结构化格式
• 数据分析：使用如 jq 的工具轻松提取特定信息

使用 jq 处理 JSON 输出

JSON 格式使得程序化提取特定信息变得容易：

# List all file paths
cat repomix-output.json | jq -r '.files | keys[]'

# Count total number of files
cat repomix-output.json | jq '.files | keys | length'

# Extract specific file content
cat repomix-output.json | jq -r '.files["README.md"]'
cat repomix-output.json | jq -r '.files["src/index.js"]'

# Find files by extension
cat repomix-output.json | jq -r '.files | keys[] | select(endswith(".ts"))'

# Get files containing specific text
cat repomix-output.json | jq -r '.files | to_entries[] | select(.value | contains("function")) | .key'

# Extract directory structure
cat repomix-output.json | jq -r '.directoryStructure'

# Get file summary information
cat repomix-output.json | jq '.fileSummary.purpose'
cat repomix-output.json | jq -r '.fileSummary.generationHeader'

# Extract user-provided header (if exists)
cat repomix-output.json | jq -r '.userProvidedHeader // "No header provided"'

# Create a file list with sizes
cat repomix-output.json | jq -r '.files | to_entries[] | "\(.key): \(.value | length) characters"'

纯文本格式

要以纯文本格式生成输出，请使用 --style plain 选项：

repomix --style plain

This file is a merged representation of the entire codebase, combining all repository files into a single document.

================================================================
File Summary
================================================================
(Metadata and usage AI instructions)

================================================================
Directory Structure
================================================================
src/
  cli/
    cliOutput.ts
    index.ts
  config/
    configLoader.ts

(...remaining directories)

================================================================
Files
================================================================

================
File: src/index.js
================
// File contents here

================
File: src/utils.js
================
// File contents here

(...remaining files)

================================================================
Instruction
================================================================
(Custom instructions from `output.instructionFilePath`)

命令行选项

基本选项

• -v, --version：显示版本信息并退出

CLI 输入/输出选项

选项	描述
--verbose	启用详细调试日志（显示文件处理、令牌计数和配置详情）
--quiet	抑制所有控制台输出，仅显示错误（适用于脚本）
--stdout	将打包输出直接写入 stdout，而不是文件（抑制所有日志）
--stdin	从 stdin 读取文件路径，每行一个（指定的文件将直接处理）
--copy	处理后将生成的输出复制到系统剪贴板
--token-count-tree [threshold]	显示带有令牌计数的文件树；可选阈值仅显示令牌 ≥ N 的文件（例如：--token-count-tree 100）
--top-files-len <number>	在摘要中显示的最大文件数量（默认：5）

Repomix 输出选项

选项	描述
-o, --output <file>	输出文件路径（默认：repomix-output.xml，使用 "-" 表示标准输出）
--style <style>	输出格式：xml、markdown、json 或 plain（默认：xml）
--output-file-path-style <style>	输出中文件路径的显示方式：target-relative 或 cwd-relative（默认：target-relative）
--parsable-style	转义特殊字符以确保 XML/Markdown 有效（当输出包含可能破坏格式的代码时需要）
--compress	使用 Tree-sitter 解析提取核心代码结构（类、函数、接口）
--output-show-line-numbers	在输出中为每行添加行号前缀
--no-file-summary	在输出中省略文件摘要部分
--no-directory-structure	在输出中省略目录树可视化
--no-files	仅生成元数据而不包含文件内容（适用于仓库分析）
--remove-comments	打包前移除所有代码注释
--remove-empty-lines	移除所有文件中的空行
--truncate-base64	截断长的 Base64 数据字符串以减小输出大小
--header-text <text>	在输出开头包含的自定义文本
--instruction-file-path <path>	包含自定义指令的文件路径，将在输出中使用
--split-output <size>	将输出拆分为多个编号文件（如 repomix-output.1.xml）；大小可为 500kb、2mb 或 1.5mb
--include-empty-directories	在目录结构中包含空文件夹
--include-full-directory-structure	在输出中显示完整目录树，包括未被 --include 模式匹配的文件
--no-git-sort-by-changes	不按 Git 变更频率排序文件（默认：先显示变更最多的文件）
--include-diffs	添加 Git diff 部分，显示工作区和暂存区的更改
--include-logs	添加 Git 提交历史，包括提交信息和变更文件
--include-logs-count <count>	使用 --include-logs 时包含的最近提交数量（默认：50）

文件选择选项

选项	描述
--include <patterns>	仅包含匹配这些 Glob 模式的文件（逗号分隔，例如："src/**/*.js,*.md"）
-i, --ignore <patterns>	额外的排除模式（逗号分隔，例如："*.test.js,docs/**"）
--no-gitignore	不使用 .gitignore 规则来过滤文件
--no-dot-ignore	不使用 .ignore 规则来过滤文件
--no-default-patterns	不应用内置忽略模式（node_modules、.git、构建目录等）

远程仓库选项

选项	描述
--remote <url>	克隆并打包远程仓库（GitHub URL 或 user/repo 格式）
--remote-branch <name>	使用特定分支、标签或提交（默认：仓库的默认分支）
--remote-trust-config	信任并加载远程仓库的配置文件（默认因安全原因禁用）。在交互式终端中，会显示配置并要求您确认

配置选项

选项	描述
-c, --config <path>	使用自定义配置文件，而不是 repomix.config.json
--init	使用默认值创建新的 repomix.config.json 文件
--global	配合 --init 使用，在主目录中创建配置文件，而不是当前目录

安全选项

• --no-security-check：跳过扫描敏感数据，如 API 密钥和密码

令牌计数选项

• --token-count-encoding <encoding>：用于计数的分词模型：o200k_base（GPT-4o）、cl100k_base（GPT-3.5/4）等。（默认：o200k_base）
• --token-budget <number>：当打包输出超过 N 个令牌时，以非零退出代码失败。在 CI 流水线和代理工作流程中作为防护措施使用，以保持输出在目标模型的上下文窗口内。输出仍会生成；仅退出代码表示溢出。

MCP

• --mcp：作为模型上下文协议服务器运行，用于 AI 工具集成
• --sandbox [dir]：（配合 --mcp 使用）将 MCP 服务器的文件工具限制在工作目录中（默认为当前工作目录；例如 --sandbox path/to/project）— 每个路径都相对于该根目录，拒绝绝对/主机路径，并禁用远程打包、技能生成及附加外部输出。

代理技能生成

选项	描述
--skill-generate [name]	生成 Claude Agent 技能格式的输出到 .claude/skills/<name>/ 目录（如果省略则自动生成名称）
--skill-project-name <name>	覆盖生成技能描述中使用的项目名称
--skill-output <path>	直接指定技能输出目录路径（跳过位置提示）
-f, --force	跳过所有确认提示（技能目录覆盖、远程配置信任）

观察模式

• -w, --watch ：监视文件更改并自动重新打包。对快速更改进行去抖（300毫秒），并在每次重建时记录时间戳。使用 Ctrl+C 停止。

  观察模式仅适用于本地目录，因此不能与 --remote、位置远程仓库 URL、--stdout、--stdin、--split-output、--skill-generate 或 --copy（无论是在命令行设置还是在配置文件中）结合使用。

示例

# Basic usage
repomix

# Custom output
repomix -o output.xml --style xml

# Output to stdout
repomix --stdout > custom-output.txt

# Send output to stdout, then pipe into another command (for example, simonw/llm)
repomix --stdout | llm "Please explain what this code does."

# Custom output with compression
repomix --compress

# Process specific files
repomix --include "src/**/*.ts" --ignore "**/*.test.ts"

# Split output into multiple files (max size per part)
repomix --split-output 20mb

# Remote repository with branch
repomix --remote https://github.com/user/repo/tree/main

# Remote repository with commit
repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1

# Remote repository with shorthand
repomix --remote user/repo

# Watch mode — automatically re-pack on file changes
repomix --watch
repomix -w --include "src/**/*.ts"

正在更新 Repomix

要更新全局安装的 Repomix：

# Using npm
npm update -g repomix

# Using yarn
yarn global upgrade repomix

# Using bun
bun update -g repomix

使用 npx repomix 通常更方便，因为它总是使用最新版本。

远程仓库处理

Repomix 支持处理远程 Git 仓库，无需手动克隆。此功能允许您通过一个命令快速分析任何公共 Git 仓库。

要处理远程仓库，请使用 --remote 选项，后跟仓库 URL：

repomix --remote https://github.com/yamadashy/repomix

你也可以使用 GitHub 的简写格式：

repomix --remote yamadashy/repomix

您可以指定分支名称、标签或提交哈希：

# Using --remote-branch option
repomix --remote https://github.com/yamadashy/repomix --remote-branch main

# Using branch's URL
repomix --remote https://github.com/yamadashy/repomix/tree/main

或者使用特定的提交哈希：

# Using --remote-branch option
repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695

# Using commit's URL
repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1

[！注意]
出于安全考虑，远程仓库中的配置文件（repomix.config.*）默认不会加载。这可以防止不受信任的仓库通过配置文件执行代码。您的全局配置和命令行选项仍然会被应用。要信任远程仓库的配置，请使用 --remote-trust-config 或设置 REPOMIX_REMOTE_TRUST_CONFIG=true —— 在交互式终端中，Repomix 会显示该配置并在加载前要求您确认。请参见远程仓库配置信任。

当与 --remote 一起使用 --config 时，需要提供绝对路径（例如，--config /home/user/repomix.config.json）。

代码压缩

--compress 选项使用 Tree-sitter 进行智能代码提取，专注于提取关键函数和类签名，同时去除实现细节。这有助于在保留重要结构信息的同时减少令牌数量。

repomix --compress

例如，这段代码：

import { ShoppingItem } from './shopping-item';

/**
 * Calculate the total price of shopping items
 */
const calculateTotal = (
  items: ShoppingItem[]
) => {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
}

// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

将被压缩为：

import { ShoppingItem } from './shopping-item';
⋮----
/**
 * Calculate the total price of shopping items
 */
const calculateTotal = (
  items: ShoppingItem[]
) => {
⋮----
// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

[！注意]
这是一个实验性功能，我们将根据用户反馈和实际使用情况积极改进。

每文件包含级别（output.patterns）

虽然 --compress 会对每个文件应用相同的级别，但 output.patterns 允许你从配置文件中按 glob 控制详细级别。每个条目通过 glob 定位文件（匹配方式与 include/ignore 相同），并覆盖匹配文件的全局 output.compress 设置：

{
  "output": {
    "compress": false, // global default acts as the catch-all
    "patterns": [
      { "pattern": "docs/**/*", "compress": true },
      { "pattern": "website/**/*", "directoryStructureOnly": true }
    ]
  }
}

有三级:

• 完整内容（默认）— 文件的全部内容将被包含。
• 压缩（compress: true）— 内容通过与 --compress 相同的 Tree-sitter 流程处理。
• 仅目录结构（directoryStructureOnly: true）— 文件会在目录结构中列出，但其内容块会完全从输出中省略。

语义:

• 模式按数组顺序进行评估，对于给定文件第一个匹配的模式胜出。
• 匹配模式的标记会覆盖全局 output.compress 设置。匹配模式如果未设置任何标记，则强制该文件使用完整内容（用于从全局 compress 中列入白名单的文件）。
• directoryStructureOnly 在两者都设置时优先于 compress。
• 如果没有匹配的模式，则应用全局行为（完整内容，或当 output.compress 为 true 时压缩内容）。

此选项仅适用于配置文件；没有每个模式级别的 CLI 标志。

令牌计数优化

了解代码库的令牌分布对于优化 AI 交互至关重要。使用 --token-count-tree 选项可可视化项目的令牌使用情况：

repomix --token-count-tree

这会显示您的代码库的分层视图及令牌计数：

🔢 Token Count Tree:
────────────────────
└── src/ (70,925 tokens)
    ├── cli/ (12,714 tokens)
    │   ├── actions/ (7,546 tokens)
    │   └── reporters/ (990 tokens)
    └── core/ (41,600 tokens)
        ├── file/ (10,098 tokens)
        └── output/ (5,808 tokens)

你也可以设置一个最小令牌阈值以专注于更大的文件：

repomix --token-count-tree 1000  # Only show files/directories with 1000+ tokens

这可以帮助你：

• 识别令牌密集型文件，这些文件可能超出 AI 上下文限制
• 使用 --include 和 --ignore 模式优化文件选择
• 通过针对最大贡献者来规划压缩策略
• 在准备代码进行 AI 分析时平衡内容与上下文

为大型代码库拆分输出

在处理大型代码库时，打包输出可能会超过某些 AI 工具（例如 Google AI Studio 的 1MB 限制） imposes 文件大小限制。使用 --split-output 可自动将输出拆分为多个文件：

repomix --split-output 1mb

这会生成编号的文件，如：

• repomix-output.1.xml
• repomix-output.2.xml
• repomix-output.3.xml

可以用单位指定大小：500kb、1mb、2mb、1.5mb 等。支持小数值。

[!注意]
文件按顶级目录分组以保持上下文。单个文件或目录永远不会被拆分到多个输出文件中。

MCP 服务器集成

Repomix 支持 模型上下文协议 (MCP)，允许 AI 助手直接与您的代码库交互。作为 MCP 服务器运行时，Repomix 提供工具，使 AI 助手能够打包本地或远程仓库进行分析，而无需手动准备文件。

repomix --mcp

沙盒模式

默认情况下，MCP 服务器可以读取主机用户可以访问的任何路径。这对于受信任的本地助手来说很方便，但当服务器暴露给不受信任的客户端或代理时就太宽泛了。--sandbox 标志将服务器的文件工具限制在单个工作区目录中：

# Confine to the current working directory
repomix --mcp --sandbox

# Confine to a specific directory
repomix --mcp --sandbox path/to/project

当沙箱模式开启时，每个路径都是相对于工作区根目录的（绝对路径、~、.. 以及 Windows 驱动器/UNC 路径都会被拒绝，通过符号链接解析到根目录之外的路径也不允许），配置文件不会被加载，并且只注册只读、受根目录限制的工具；远程打包、技能生成和附加外部输出功能将被禁用。原始文件工具（file_system_read_file、file_system_read_directory）仅在沙箱模式下可用，此模式下工作区根目录限制它们可访问的范围。这是对工具表面进行的应用级隔离，而非操作系统级沙箱。

不使用 --sandbox 时，pack_codebase 会加载并信任它打包目录中的 repomix.config.*，这与在命令行中运行该目录下的 repomix 相同。配置文件本质上是代码：加载时可能会运行并读取库外的文件。如果您的助手可能会打包您不信任的目录，例如克隆的第三方仓库，请使用 --sandbox。详情请参见 MCP 服务器指南。

配置 MCP 服务器

要将 Repomix 用作类似 Claude 的 AI 助手的 MCP 服务器，您需要配置 MCP 设置：

对于 VS Code：

您可以通过以下方法之一在 VS Code 中安装 Repomix MCP 服务器：

1. 使用安装徽章：

2. 使用命令行：

   code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

   对于 VS Code Insider 版本：

   code-insiders --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

用于 Cline（VS Code 扩展）：

编辑 cline_mcp_settings.json 文件：

{
  "mcpServers": {
    "repomix": {
      "command": "npx",
      "args": [
        "-y",
        "repomix",
        "--mcp"
      ]
    }
  }
}

对于 Cursor:

在 Cursor 中，从 Cursor Settings > MCP > + Add new global MCP server 添加一个新的 MCP 服务器，其配置类似于 Cline。

对于 Claude Desktop:

编辑 claude_desktop_config.json 文件，配置类似于 Cline 的配置。

对于 Claude Code:

要在 Claude Code 中将 Repomix 配置为 MCP 服务器，请使用以下命令：

claude mcp add repomix -- npx -y repomix --mcp

或者，您可以使用官方的 Repomix 插件（请参阅下面的 Claude Code 插件 部分）。

使用 Docker 代替 npx：

您可以使用 Docker 作为运行 Repomix 作为 MCP 服务器的 npx 替代方法：

{
  "mcpServers": {
    "repomix-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/yamadashy/repomix",
        "--mcp"
      ]
    }
  }
}

配置完成后，你的AI助手可以直接利用Repomix的功能分析代码库，无需手动准备文件，从而提升代码分析工作流程的效率。

可用的MCP工具

作为MCP服务器运行时，Repomix提供以下工具：

1. pack_codebase：将本地代码目录打包到整合的XML文件中进行AI分析

   • 参数：
   • directory：要打包的目录的绝对路径
   • compress：（可选，默认值：false）启用 Tree-sitter 压缩，以提取关键代码签名和结构，同时去除实现细节。在保留语义含义的情况下，可减少约 70% 的令牌使用量。通常不需要开启，因为 grep_repomix_output 允许增量内容检索。仅在您特别需要整个代码库内容用于大型仓库时使用。
   • includePatterns：（可选）使用 fast-glob 模式指定要包含的文件。多个模式可以用逗号分隔（例如，“*/.{js,ts}”，“src/,docs/”）。只有匹配的文件会被处理。
   • ignorePatterns：（可选）使用 fast-glob 模式指定要排除的其他文件。多个模式可以用逗号分隔（例如，"test/*,.spec.js"，"node_modules/,dist/"）。这些模式是对 .gitignore、.ignore 和内置排除规则的补充。
   • outputPatterns：（可选）每个文件的包含级别，类似于配置文件中的 output.patterns 选项。是一个由 { pattern, compress?, directoryStructureOnly? } 条目组成的数组；第一个匹配的模式生效，directoryStructureOnly 优先于 compress，如果匹配条目没有任何标记，则强制使用完整内容（对于将某些文件从全局 compress 中排除非常有用）。会覆盖目标仓库 repomix.config.json 中的任何 output.patterns 设置。
   • topFilesLength：（可选，默认值：10）在代码库分析的指标摘要中显示的按大小排序的最大文件数量。

2. attach_packed_output：附上一个已有的Repomix打包输出文件用于AI分析

   • 参数：
   • path：指向包含 repomix-output.xml 的目录的路径，或指向已打包仓库 XML 文件的直接路径
   • topFilesLength：(可选，默认值：10) 在指标摘要中显示的按大小排序的最大文件数量
   • 特色：
   • 接受包含repomix-output.xml文件的目录或指向XML文件的直接路径
   • 将文件注册到MCP服务器，并返回与pack_codebase工具相同的结构
   • 无需重新处理即可访问现有的打包输出
   • 对于处理已生成的打包仓库非常有用

3. pack_remote_repository：获取、克隆并将 GitHub 仓库打包为用于 AI 分析的整合 XML 文件

   • 参数：
   • remote：GitHub 仓库 URL 或 user/repo 格式（例如 "yamadashy/repomix", "https://github.com/user/repo" 或 "https://github.com/user/repo/tree/branch"）
   • compress：（可选，默认：false）启用 Tree-sitter 压缩以提取关键代码签名和结构，同时删除实现细节。在保留语义意义的同时，可减少约 70% 的 token 使用量。通常不需要，因为 grep_repomix_output 允许增量内容检索。仅在需要整个大型仓库内容时使用。
   • includePatterns：（可选）使用 fast-glob 模式指定要包含的文件。多个模式可用逗号分隔（例如 "*/.{js,ts}", "src/,docs/"）。仅处理匹配的文件。
   • ignorePatterns：（可选）使用 fast-glob 模式指定要排除的额外文件。多个模式可用逗号分隔（例如 "test/*,.spec.js", "node_modules/,dist/"）。这些模式补充 .gitignore、.ignore 和内置的排除规则。
   • outputPatterns：（可选）每文件的包含级别，类似于配置文件中的 output.patterns 选项。为 { pattern, compress?, directoryStructureOnly? } 条目数组；第一个匹配模式生效，directoryStructureOnly 优先于 compress，且若没有标志匹配，将强制读取完整内容（适用于排除文件不受全局 compress 影响）。
   • topFilesLength：（可选，默认：10）在代码库分析的指标摘要中显示的最大文件数量。

4. read_repomix_output：读取 Repomix 生成的输出文件内容。支持对大文件按行范围进行部分读取。

   • 参数：
   • outputId：要读取的 Repomix 输出文件的 ID
   • startLine：（可选）起始行号（基于 1，包含该行）。如未指定，则从头开始读取。
   • endLine：（可选）结束行号（基于 1，包含该行）。如未指定，则读取到末尾。
   • 功能：
   • 专为基于 Web 的环境或沙箱应用设计
   • 使用 ID 获取先前生成的输出内容
   • 提供访问打包代码库的功能，无需文件系统访问
   • 支持大文件的部分读取

5. grep_repomix_output：使用类似 grep 的功能和 JavaScript RegExp 语法，在 Repomix 输出文件中搜索模式

   • 参数：
   • outputId：要搜索的 Repomix 输出文件的 ID
   • pattern：搜索模式（JavaScript RegExp 正则表达式语法）
   • contextLines：（可选，默认值：0）在每个匹配项前后显示的上下文行数。如果指定了 beforeLines/afterLines，将覆盖此设置。
   • beforeLines：（可选）在每个匹配项前显示的上下文行数（类似 grep -B）。优先于 contextLines。
   • afterLines：（可选）在每个匹配项后显示的上下文行数（类似 grep -A）。优先于 contextLines。
   • ignoreCase：（可选，默认值：false）执行不区分大小写的匹配
   • 功能：
   • 使用 JavaScript RegExp 语法进行强大的模式匹配
   • 支持上下文行以更好地理解匹配结果
   • 允许分别控制前/后上下文行
   • 提供区分大小写和不区分大小写的搜索选项

6. file_system_read_file：读取沙箱工作区内的文件。仅在沙箱模式（--sandbox）下可用，工作区根目录限制了其可访问范围。

   • 参数：
   • path：要读取文件的路径，相对于工作区根目录（例如 src/index.ts）
   • 注意事项：
   • 没有 --sandbox 指令时无法注册
   • 作为额外的启发式保护，拒绝匹配已知的秘密格式内容（Secretlint）——访问边界是工作区根目录，而不是扫描范围

7. file_system_read_directory：列出沙箱工作区内目录的内容。仅在沙箱模式（--sandbox）下可用。

   • 参数：
   • path：要列出目录的路径，相对于工作区根目录（例如 . 或 src）
   • 特性：
   • 使用清晰的指示器显示文件和目录（[FILE] 或 [DIR]）
   • 用于探索项目结构和理解代码库组织

Claude 代码插件

Repomix 提供官方插件用于 Claude Code，可与 AI 驱动的开发环境无缝集成。

安装

1. 添加 Repomix 插件市场：

/plugin marketplace add yamadashy/repomix

2. 安装插件：

# Install MCP server plugin (recommended foundation)
/plugin install repomix-mcp@repomix

# Install commands plugin (extends functionality)
/plugin install repomix-commands@repomix

# Install repository explorer plugin (AI-powered analysis)
/plugin install repomix-explorer@repomix

注意：推荐将 repomix-mcp 插件作为基础。repomix-commands 插件提供方便的斜杠命令，而 repomix-explorer 则增加了 AI 驱动的分析功能。虽然你可以单独安装它们，但同时使用这三个插件可以获得最全面的体验。

或者，使用交互式插件安装程序：

/plugin

这将打开一个交互式界面，您可以在其中浏览并安装可用的插件。

可用插件

1. repomix-mcp（MCP 服务器插件）

基础插件，通过 MCP 服务器集成提供 AI 支持的代码库分析。

功能:

• 打包本地和远程仓库
• 读取并搜索打包输出
• 自动 Tree-sitter 压缩（约减少 70% 的 token）

2. repomix-commands（斜杠命令插件）

提供方便的斜杠命令，以便快速操作，并支持自然语言。

可用命令:

• /repomix-commands:pack-local - 使用多种选项打包本地代码库
• /repomix-commands:pack-remote - 打包并分析远程 GitHub 仓库

示例用法:

/repomix-commands:pack-local
Pack this project as markdown with compression

/repomix-commands:pack-remote yamadashy/repomix
Pack only TypeScript files from the yamadashy/repomix repository

3. repomix-explorer（AI 分析代理插件）

由 AI 驱动的代码库分析代理，使用 Repomix CLI 智能地探索代码库。

功能：

• 自然语言代码库探索与分析
• 智能模式发现与代码结构理解
• 使用 grep 和目标文件读取进行增量分析
• 大规模仓库的自动上下文管理

可用命令：

• /repomix-explorer:explore-local - 使用 AI 辅助分析本地代码库
• /repomix-explorer:explore-remote - 使用 AI 辅助分析远程 GitHub 仓库

示例用法：

/repomix-explorer:explore-local ./src
Find all authentication-related code

/repomix-explorer:explore-remote facebook/react
Show me the main component architecture

代理自动执行：

1. 运行 npx repomix@latest 打包仓库
2. 使用 Grep 和 Read 工具高效搜索输出
3. 提供全面分析而不会占用过多上下文

优点

• 无缝集成：Claude 可以直接分析代码库，无需手动准备
• 自然语言：使用会话式命令，而无需记住 CLI 语法
• 始终最新：自动使用 npx repomix@latest 获取最新功能
• 秘密扫描：Secretlint 会标记符合已知凭证格式的文件，使其从输出中排除
• 令牌优化：对大型代码库使用 Tree-sitter 压缩

更多详情，请参见 .claude/plugins/ 目录中的插件文档。

代理技能生成

Repomix 可以生成 Claude Agent Skills 格式的输出，创建一个结构化的 Skills 目录，可作为 AI 助手的可复用代码库参考。当您想引用远程仓库中的实现时，这个功能特别强大。

基本用法

# Generate Skills from local directory
repomix --skill-generate

# Generate with custom Skills name
repomix --skill-generate my-project-reference

# Generate with a custom project name in Skills descriptions
repomix --skill-generate --skill-project-name "My Project"

# Generate from remote repository
repomix --remote https://github.com/user/repo --skill-generate

当你运行该命令时，Repomix 会提示你选择保存技能的位置：

1. 个人技能 (~/.claude/skills/) - 可在你机器上的所有项目中使用
2. 项目技能 (.claude/skills/) - 通过 git 与你的团队共享

非交互式使用

对于 CI 流水线和自动化脚本，你可以使用 --skill-output 和 --force 来跳过所有交互提示：

# Specify output directory directly
repomix --skill-generate --skill-output ./my-skills

# Skip overwrite confirmation with --force
repomix --skill-generate --skill-output ./my-skills --force

# Full non-interactive example
repomix --remote user/repo --skill-generate my-skill --skill-output ./output --force

生成的结构

技能按照以下结构生成：

.claude/skills/<skill-name>/
├── SKILL.md                 # Main Skills metadata & documentation
└── references/
    ├── summary.md           # Purpose, format, and statistics
    ├── project-structure.md # Directory tree with line counts
    ├── files.md             # All file contents (grep-friendly)
    └── tech-stacks.md       # Languages, frameworks, dependencies

包含内容

• SKILL.md：包含技能的元数据、文件/行/标记计数、概览和使用说明
• summary.md：说明技能的用途、使用指南，并提供按文件类型和语言的统计细分
• project-structure.md：目录树，每个文件的行数，便于文件查找
• files.md：所有文件内容，带语法高亮标题，优化以便 grep 搜索
• tech-stacks.md：每个包从依赖文件（package.json、requirements.txt、Cargo.toml 等）自动检测的技术栈

自动生成的技能名称

如果未提供名称，Repomix 会自动生成一个：

repomix src/ --skill-generate                # → repomix-reference-src
repomix --remote user/repo --skill-generate  # → repomix-reference-repo
repomix --skill-generate CustomName          # → custom-name (normalized to kebab-case)

与Repomix功能的集成

技能生成遵循所有标准的Repomix选项：

# Generate Skills with file filtering
repomix --skill-generate --include "src/**/*.ts" --ignore "**/*.test.ts"

# Generate Skills with compression
repomix --skill-generate --compress

# Generate Skills from remote repository
repomix --remote yamadashy/repomix --skill-generate

Repomix 探索者技能（代理技能）

Repomix 提供一个开箱即用的 Repomix 探索者 技能，使 AI 编程助手能够使用 Repomix CLI 分析和探索代码库。该技能旨在与各种 AI 工具配合使用，包括 Claude Code、Cursor、Codex、GitHub Copilot 等。

快速安装

对于 Claude Code，请安装官方 Repomix Explorer 插件：

/plugin marketplace add yamadashy/repomix
/plugin install repomix-explorer@repomix

对于 Codex、Cursor、OpenClaw 以及其他兼容 Agent Skills 的助手，请使用 Skills CLI 安装独立技能：

npx skills add yamadashy/repomix --skill repomix-explorer

要针对特定助手，请传递 --agent：

npx skills add yamadashy/repomix --skill repomix-explorer --agent codex
npx skills add yamadashy/repomix --skill repomix-explorer --agent openclaw

对于 Hermes Agent，请使用 Hermes Agent 的原生技能命令安装单文件技能：

hermes skills install https://raw.githubusercontent.com/yamadashy/repomix/main/skills/repomix-explorer/SKILL.md

它的功能

安装后，您可以使用自然语言指令分析代码库。

分析远程存储库：

"What's the structure of this repo?
https://github.com/facebook/react"

浏览本地代码库：

"What's in this project?
~/projects/my-app"

这不仅有助于理解代码库，也有助于在你想通过参考其他仓库来实现功能时使用。

⚙️ 配置

Repomix 支持多种配置文件格式，以实现灵活性和易用性。

配置文件格式

Repomix 将按照以下优先顺序自动搜索配置文件：

1. TypeScript (repomix.config.ts、repomix.config.mts、repomix.config.cts)
2. JavaScript/ES 模块 (repomix.config.js、repomix.config.mjs、repomix.config.cjs)
3. JSON (repomix.config.json5、repomix.config.jsonc、repomix.config.json)

JSON 配置

在项目根目录下创建一个 repomix.config.json 文件：

repomix --init

这将创建一个带有默认设置的 repomix.config.json 文件。

TypeScript 配置

TypeScript 配置文件提供最佳的开发者体验，具有完整的类型检查和 IDE 支持。

安装：

要使用 defineConfig 的 TypeScript 或 JavaScript 配置，你需要将 Repomix 安装为开发依赖：

npm install -D repomix

示例：

// repomix.config.ts
import { defineConfig } from 'repomix';

export default defineConfig({
  output: {
    filePath: 'output.xml',
    style: 'xml',
    removeComments: true,
  },
  ignore: {
    customPatterns: ['**/node_modules/**', '**/dist/**'],
  },
});

好处:

• ✅ 在你的 IDE 中进行完整的 TypeScript 类型检查
• ✅ 优秀的 IDE 自动补全和智能感知
• ✅ 使用动态值（时间戳、环境变量等）

动态值示例:

// repomix.config.ts
import { defineConfig } from 'repomix';

// Generate timestamp-based filename
const timestamp = new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-');

export default defineConfig({
  output: {
    filePath: `output-${timestamp}.xml`,
    style: 'xml',
  },
});

JavaScript 配置

JavaScript 配置文件的工作方式与 TypeScript 相同，支持 defineConfig 和动态值。

配置选项

以下是配置选项的说明：

选项	描述	默认
input.maxFileSize	要处理的最大文件大小（以字节为单位）。超过此大小的文件将被跳过	50000000
input.processors	有序的 { pattern, command, timeout?, onError? } 条目数组，用于在打包前运行外部命令以转换匹配的文件（例如 JSON→TOON）。第一个匹配的 glob 优先。可以运行任意命令，因此仅在本地 CLI 运行时执行（以及带 --remote-trust-config 的远程仓库）。参见 文件处理器	未设置
output.filePath	输出文件的名称	"repomix-output.xml"
output.style	输出的样式 ( xml , markdown , json , plain )	"xml"
output.filePathStyle	输出中如何显示文件路径（ target-relative 保持路径相对于每个目标根， cwd-relative 保持路径相对于当前工作目录）	"target-relative"
output.parsableStyle	是否根据所选的样式 schema 转义输出。请注意，这可能会增加令牌数量。	false
output.compress	是否执行智能代码提取以减少令牌数量	false
output.patterns	每个文件的包含级别。一个按顺序排列的 { pattern, compress?, directoryStructureOnly? } 条目数组；第一个匹配的 glob 将获胜，并覆盖该文件的全局 output.compress。参见 每个文件的包含级别	未设置
output.headerText	要包含在文件头部的自定义文本	null
output.instructionFilePath	包含详细自定义指令的文件路径	null
output.fileSummary	是否在输出的开头包含摘要部分	true
output.directoryStructure	是否在输出中包含目录结构	true
output.files	是否在输出中包含文件内容	true
output.removeComments	是否从支持的文件类型中移除注释	false
output.removeEmptyLines	是否从输出中移除空行	false
output.showLineNumbers	是否在输出的每一行添加行号	false
output.truncateBase64	是否截断长的 base64 数据字符串（例如图片）以减少令牌数量	false
output.copyToClipboard	除了保存文件之外，是否将输出复制到系统剪贴板	false
output.splitOutput	按每部分的最大大小将输出拆分为多个编号文件（例如 1000000 对应约 1MB）。保持每个文件在限制范围内并避免跨部分拆分文件	未设置
output.topFilesLength	在摘要中显示的顶级文件数量。如果设置为 0，则不显示摘要	5
output.tokenCountTree	是否显示带有令牌计数摘要的文件树。可以是布尔值或数字（最小令牌计数阈值）	false
output.tokenBudget	当打包输出超过此令牌数时，以非零退出码失败。作为 CI/代理上下文限制的保护；输出仍会生成	未设置
output.includeEmptyDirectories	是否在仓库结构中包含空目录	false
output.includeFullDirectoryStructure	使用 include 模式时，是否显示完整目录树（尊重忽略模式）同时仍只处理包含的文件。为 AI 分析提供完整仓库上下文	false
output.git.sortByChanges	是否按 git 变更次数排序文件（更改次数多的文件出现在底部）	true
output.git.sortByChangesMaxCommits	分析 git 变更的最大提交数	100
output.git.includeDiffs	是否在输出中包含 git 差异（分别包括工作区和暂存区的更改）	false
output.git.includeLogs	是否在输出中包含 git 日志（包括带日期、消息和文件路径的提交历史）	false
output.git.includeLogsCount	要包含的 git 日志提交数量	50
include	要包含的文件模式（使用 glob 模式）	[]
ignore.useGitignore	是否使用项目的 .gitignore 文件中的模式	true
ignore.useDotIgnore	是否使用项目的 .ignore 文件中的模式	true
ignore.useDefaultPatterns	是否使用默认的忽略模式	true
ignore.customPatterns	额外要忽略的模式（使用 glob 模式）	[]
security.enableSecurityCheck	是否对文件进行安全检查	true
tokenCount.encoding	OpenAI 兼容的分词计数编码（例如，GPT-4o 使用 o200k_base，GPT-4/3.5 使用 cl100k_base）。由 gpt-tokenizer 提供支持。	"o200k_base"

配置文件支持 JSON5 语法，允许：

• 注释（单行和多行）
• 对象和数组末尾的逗号
• 无引号的属性名称
• 更宽松的字符串语法

模式验证

你可以通过添加 $schema 属性来为配置文件启用模式验证：

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml"
  }
}

这在支持 JSON 模式的编辑器中提供自动补全和验证。

示例配置

示例配置：

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "input": {
    "maxFileSize": 50000000,
    // Optional: transform matching files with an external command before packing (local CLI only)
    // "processors": [
    //   { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
    // ]
  },
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "filePathStyle": "target-relative",
    "parsableStyle": false,
    "compress": false,
    // Optional: override the inclusion level per glob (first match wins)
    // "patterns": [
    //   { "pattern": "docs/**/*", "compress": true },
    //   { "pattern": "website/**/*", "directoryStructureOnly": true }
    // ],
    "headerText": "Custom header information for the packed file.",
    "fileSummary": true,
    "directoryStructure": true,
    "files": true,
    "removeComments": false,
    "removeEmptyLines": false,
    "topFilesLength": 5,
    "tokenCountTree": false, // or true, or a number like 10 for minimum token threshold
    // "tokenBudget": 180000, // optional: fail when the packed output exceeds this many tokens
    "showLineNumbers": false,
    "truncateBase64": false,
    "copyToClipboard": false,
    // "splitOutput": 1000000, // optional: split output into multiple ~1MB files
    "includeEmptyDirectories": false,
    "git": {
      "sortByChanges": true,
      "sortByChangesMaxCommits": 100,
      "includeDiffs": false,
      "includeLogs": false,
      "includeLogsCount": 50
    }
  },
  "include": ["**/*"],
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    // Patterns can also be specified in .repomixignore
    "customPatterns": [
      "additional-folder",
      "**/*.log"
    ],
  },
  "security": {
    "enableSecurityCheck": true
  },
  "tokenCount": {
    "encoding": "o200k_base"
  }
}

全局配置

要创建全局配置文件：

repomix --init --global

全局配置文件将创建于：

• Windows: %LOCALAPPDATA%\Repomix\repomix.config.json
• macOS/Linux: $XDG_CONFIG_HOME/repomix/repomix.config.json 或 ~/.config/repomix/repomix.config.json

注意：本地配置（如存在）优先于全局配置。

包含与忽略

包含模式

Repomix 现在支持使用 glob 模式 指定要包含的文件。这允许更灵活和强大的文件选择：

• 使用 **/*.js 来包含任何目录中的所有 JavaScript 文件
• 使用 src/**/* 来包含 src 目录及其子目录中的所有文件
• 将多个模式组合起来，如 ["src/**/*.js", "**/*.md"]，以在 src 中包含 JavaScript 文件和所有 Markdown 文件

忽略模式

Repomix 提供多种方法，在打包过程中设置忽略模式以排除特定文件或目录：

• .gitignore：默认情况下，会使用列在项目的 .gitignore 文件和 .git/info/exclude 中的模式。此行为可以通过 ignore.useGitignore 设置或 --no-gitignore 命令行选项来控制。
• .ignore: 您可以在项目根目录中使用 .ignore 文件，格式与 .gitignore 相同。该文件会被 ripgrep 和 silver searcher 等工具识别，从而减少维护多个忽略文件的需要。此行为可以通过 ignore.useDotIgnore 设置或 --no-dot-ignore 命令行选项进行控制。
• 默认模式：Repomix 包含一个默认的常见被排除的文件和目录列表（例如，node_modules、.git、二进制文件）。此功能可以通过 ignore.useDefaultPatterns 设置或 --no-default-patterns 命令行选项进行控制。更多详情请参见 defaultIgnore.ts。
• .repomixignore：你可以在项目根目录创建一个 .repomixignore 文件，以定义 Repomix 专用的忽略模式。该文件遵循与 .gitignore 相同的格式。
• 自定义模式：可以使用配置文件中的 ignore.customPatterns 选项指定额外的忽略模式。你可以通过 -i, --ignore 命令行选项覆盖此设置。

优先顺序（从高到低）：

1. 自定义模式（ignore.customPatterns）
2. 忽略文件（.repomixignore、.ignore、.gitignore、以及 .git/info/exclude）：
   • 在嵌套目录中，位于更深层目录的文件优先级更高
   • 在同一目录中，这些文件会以无特定顺序合并
3. 默认模式（如果 ignore.useDefaultPatterns 为 true 且未使用 --no-default-patterns）

这种方法允许根据项目需求灵活配置文件排除。它有助于通过确保排除安全敏感文件和大容量二进制文件来优化生成的打包文件大小，同时防止机密信息泄露。

注意：二进制文件默认不包含在打包输出中，但其路径会在输出文件的“仓库结构”部分列出。这提供了仓库结构的完整概览，同时保持打包文件高效且基于文本。

自定义说明

output.instructionFilePath 选项允许您指定一个单独文件，其中包含有关项目的详细说明或上下文。这使得 AI 系统能够理解项目的具体背景和需求，从而可能提供更相关和量身定制的分析或建议。

以下是使用此功能的示例：

1. 在项目根目录创建一个名为 repomix-instruction.md 的文件：

# Coding Guidelines

- Follow the Airbnb JavaScript Style Guide
- Suggest splitting files into smaller, focused units when appropriate
- Add comments for non-obvious logic. Keep all text in English
- All new features should have corresponding unit tests

# Generate Comprehensive Output

- Include all content without abbreviation, unless specified otherwise
- Optimize for handling large codebases while maintaining output quality

2. 在你的 repomix.config.json 中，添加 instructionFilePath 选项：

{
  "output": {
    "instructionFilePath": "repomix-instruction.md",
    // other options...
  }
}

当 Repomix 生成输出时，它将在专用部分中包含 repomix-instruction.md 的内容。

注意：指令内容会附加在输出文件的末尾。这种安排对于 AI 系统尤其有效。对于那些想了解为什么这可能有益的人，Anthropic 在他们的文档中提供了一些见解： https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips

将长格式数据放在顶部：将你的长文档和输入（约 20K 令牌）放在提示的顶部，高于查询、指令和示例。这可以显著提升 Claude 在所有模型中的性能。
将查询放在末尾可以在测试中提高响应质量最多 30%，尤其是对于复杂的多文档输入。

注释移除

当 output.removeComments 设置为 true 时，Repomix 将尝试从支持的文件类型中移除注释。此功能可以帮助减小输出文件的大小，并专注于核心代码内容。

支持的语言包括： HTML、CSS、JavaScript、TypeScript、Vue、Svelte、Python、PHP、Ruby、C、C#、Java、Go、Rust、Swift、Kotlin、Dart、Shell 和 YAML。

注意：注释移除过程是保守的，以避免意外删除代码。在复杂情况下，某些注释可能会被保留。

文件处理器

input.processors 会在文件打包之前运行外部命令来转换文件内容。每个条目通过 glob（类似 include/ignore 匹配）指定目标文件，并用命令的标准输出替换匹配文件的内容——这对于减少令牌数或进行格式转换的操作很有用，例如 JSON→TOON、SVG 压缩或 notebook→脚本转换。

{
  "input": {
    "processors": [
      { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
    ]
  }
}

{file} 占位符（必填）会被替换为一个临时文件，该文件包含原文件的内容，命令的标准输出将成为新内容。模式按顺序评估，并且第一个匹配优先（每个文件一个处理器）。每个条目还接受 timeout（毫秒，默认 60000）和 onError（"fail" 表示中止打包，默认；"skip" 表示警告并保留原始内容）。

示例命令（每个都是一个 command 值与合适的 pattern 配对）：

模式	command	功能
**/*.json	jq -c . {file}	通过去除空白压缩 JSON
**/*.json	npx @toon-format/cli {file}	将 JSON 转换为 TOON，一种紧凑且高效的代币格式
**/*.svg	npx svgo -i {file} -o -	压缩 SVG
**/*.ipynb	jupyter nbconvert --to script --stdout {file}	将 Jupyter 笔记本转换为普通 Python 脚本

每个文件只应用一个处理器（以首次匹配为准），并确保它调用的工具在你的 PATH 中（基于 npx 的命令会在首次使用时下载）。

[!警告]
文件处理器会从你的配置文件运行 任意命令，因此默认执行策略是拒绝：

• 仅在本地 CLI 运行时启用，此时 Repomix 假定您工作目录中的配置是您自己的 —— 与 npm 脚本或 Makefile 的信任边界相同。与这些类似，如果您在从他人获取的仓库中运行 repomix 而未先检查其 repomix.config.json，其处理器命令将会在您的机器上执行。在打包不受信任的仓库之前，请先检查其配置。
• 对于库 API（pack() / runCli()）、MCP 服务器和托管的 repomix.com 已禁用。
• 对于远程仓库（--remote），克隆的配置及其处理器仅在您明确传递 --remote-trust-config 时才被信任；如果不传递，则远程配置甚至不会被加载。

启动时和错误消息中会打印活动处理器，因此请通过环境变量（例如 $TOKEN）引用凭据，因为它们会以未展开的形式记录，而不是内联。超时情况下，Repomix 会终止命令的 shell，但如果命令启动了自己的长期后台进程，这些进程可能会继续运行。详细信息请参见配置指南。

🔍 安全检查

Repomix 包含一个安全检查功能，该功能使用 Secretlint 来检测文件中可能存在的敏感信息。此功能可帮助您在共享打包的仓库之前识别潜在的安全风险。

打包过程完成后，安全检查结果将显示在命令行输出中。如果检测到任何可疑文件，您将看到这些文件的列表以及警告信息。

示例输出：

🔍 Security Check:
──────────────────
2 suspicious file(s) detected:
1. src/utils/test.txt
2. tests/utils/secretLintUtils.test.ts

Please review these files for potentially sensitive information.

默认情况下，Repomix 的安全检查功能是启用的。您可以通过在配置文件中将 security.enableSecurityCheck 设置为 false 来禁用它：

{
  "security": {
    "enableSecurityCheck": false
  }
}

或者使用 --no-security-check 命令行选项：

repomix --no-security-check

[!注意]
禁用安全检查可能会暴露敏感信息。仅在必要时使用此选项，例如处理包含示例凭证的测试文件或文档时，请谨慎使用。

远程仓库配置信任

一个 repomix.config.* 是代码，而不仅仅是数据：加载 .ts / .js 配置时会执行代码，input.processors 会运行外部命令，路径选项可能读取仓库外的文件。从不熟悉的仓库加载配置相当于运行其 Makefile。

因此，默认情况下永远不会加载克隆仓库的配置。您的全局配置和 CLI 选项仍然适用。

在交互式终端使用 --remote-trust-config（或 REPOMIX_REMOTE_TRUST_CONFIG=true）时，Repomix 会显示即将运行的配置并在加载前询问：

• 是的，仅此一次 — 仅信任此次运行。
• 是的，并且不再询问此仓库 — 此决定是内容固定的：它记录您批准的配置的哈希，因此如果该仓库以后提供不同的配置，将会再次询问（类似 direnv allow 模型）。
• 不（默认选择） — 在不加载配置的情况下中止。

显示的配置由仓库作者编写，因此控制字符、ANSI 字符和双向字符都会被转义，输出会被限制，每行配置都会有前缀，并且指向克隆外部的符号链接配置会被拒绝 — 您看到的即是将运行的配置。

在使用 --force、非交互式 shell（如 CI）以及已选择始终信任该仓库时，将跳过提示（现有自动化仍然有效）。

[!重要]
内容固定仅涵盖入口配置文件。一个 .ts / .js 配置可以 import 其他文件，并且
input.processors 可以调用外部脚本；两者都不进行哈希处理。将“不要再询问”视为信任整个仓库，而不仅仅是您读取的文件。

完整的信任模型请参见 安全指南。

🤖 使用 Repomix 与 GitHub Actions

您也可以在 GitHub Actions 工作流中使用 Repomix。这对于自动化将代码库打包以进行 AI 分析的过程非常有用。

基本用法：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.xml
    style: xml

使用 --style 以不同格式生成输出：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.md
    style: markdown

- name: Pack repository with Repomix (JSON format)
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.json
    style: json

使用压缩打包特定目录：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    directories: src tests
    include: "**/*.ts,**/*.md"
    ignore: "**/*.test.ts"
    output: repomix-output.txt
    compress: true

将输出文件作为构件上传：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    directories: src
    output: repomix-output.txt
    compress: true

- name: Upload Repomix output
  uses: actions/upload-artifact@v7
  with:
    name: repomix-output
    path: repomix-output.txt

完整工作流程示例：

name: Pack repository with Repomix

on:
  workflow_dispatch:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  pack-repo:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Pack repository with Repomix
        uses: yamadashy/repomix/.github/actions/repomix@main
        with:
          output: repomix-output.xml

      - name: Upload Repomix output
        uses: actions/upload-artifact@v7
        with:
          name: repomix-output.xml
          path: repomix-output.xml
          retention-days: 30

请在这里查看完整的工作流程示例。

操作输入

名称	描述	默认
directories	要处理的目录列表，使用空格分隔（例如，src tests docs）	.
include	要包含文件的逗号分隔的通配符模式（例如，**/*.ts,**/*.md）	""
ignore	要忽略文件的逗号分隔的通配符模式（例如，**/*.test.ts,**/node_modules/**）	""
output	打包文件的相对路径（扩展名决定格式：.txt、.md、.xml）	repomix-output.xml
compress	启用智能压缩，通过修剪实现细节来减小输出大小	true
style	输出样式（xml、markdown、json、plain）	xml
additional-args	提供给 repomix CLI 的额外原始参数（例如，--no-file-summary --no-security-check）	""
repomix-version	要安装的 npm 包版本（支持 semver 范围、标签或特定版本，如 0.2.25）	latest

操作输出

名称	描述
output_file	生成的输出文件的路径。可以在后续步骤中用于工件上传、LLM 处理或其他操作。该文件包含基于指定选项的代码库的格式化表示。

📚 作为库使用 Repomix

除了将 Repomix 用作 CLI 工具之外，你还可以在 Node.js 应用程序中将其用作库。

安装

npm install repomix

基本用法

import { runCli, type CliOptions } from 'repomix';

// Process current directory with custom options
async function packProject() {
  const options = {
    output: 'output.xml',
    style: 'xml',
    compress: true,
    quiet: true
  } as CliOptions;

  const result = await runCli(['.'], process.cwd(), options);
  return result.packResult;
}

处理远程仓库

import { runCli, type CliOptions } from 'repomix';

// Clone and process a GitHub repo
async function processRemoteRepo(repoUrl) {
  const options = {
    remote: repoUrl,
    output: 'output.xml',
    compress: true
  } as CliOptions;

  return await runCli(['.'], process.cwd(), options);
}

使用核心组件

如果您需要更多控制，您可以使用低级 API：

import { searchFiles, collectFiles, processFiles, TokenCounter } from 'repomix';

async function analyzeFiles(directory) {
  // Find and collect files
  const { filePaths } = await searchFiles(directory, { /* config */ });
  const rawFiles = await collectFiles(filePaths, directory);
  const processedFiles = await processFiles(rawFiles, { /* config */ });

  // Count tokens
  const tokenCounter = new TokenCounter('o200k_base');

  // Return analysis results
  return processedFiles.map(file => ({
    path: file.path,
    tokens: tokenCounter.countTokens(file.content)
  }));
}

有关更多示例，请查看源代码 website/server/src/remoteRepo.ts，其中演示了 repomix.com 如何使用该库。

打包

使用 Rolldown 或 esbuild 等工具打包 repomix 时，一些依赖项必须保留为外部依赖，并且需要复制 WASM 文件：

外部依赖（无法打包）：

• tinypool - 使用文件路径生成工作线程

需要复制的 WASM 文件：

• web-tree-sitter.wasm → 与打包后的 JS 位于同一目录（代码压缩功能所需）
• Tree-sitter 语言文件 → 由 REPOMIX_WASM_DIR 环境变量指定的目录

有关可运行的示例，请参见 website/server/scripts/bundle.mjs 。

🌍 社区项目

发现由 Repomix 社区构建的精彩项目！

• Repomix Runner - 用于将文件打包成单个输出以进行 AI 处理的 VSCode 扩展
• Repomix Desktop - 用 Python 和 CustomTkinter 构建的 Repomix GUI 桌面应用程序
• Python Repomix - 基于 AST 压缩的 Python 实现
• Rulefy - 使用 Claude AI 将 GitHub 仓库转换为自定义 Cursor AI 规则
• Codebase MCP - 使用 Repomix 进行 AI 驱动代码库分析的 MCP 服务器
• vibe-tools - 适用于 AI 代理的 CLI 工具集，支持网页搜索、仓库分析和浏览器自动化

欲了解更多详情，请访问我们的 社区项目页面。

🤝 贡献

我们欢迎社区的贡献！要开始，请参考我们的贡献指南 。

🔒 隐私政策

查看我们的隐私政策。

📜 许可

本项目遵循 MIT 许可证 许可。

    返回顶部