
Repomix 常见问题与故障排查实战指南从仓库打包、Token 优化到安全与 MCP 集成【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomixRepomix 是一款将整个代码仓库打包成单个 AI 友好文件的工具用于把完整代码库上下文交给 ChatGPT、Claude、Gemini 等 LLM 或 MCP Agent。本文围绕 Repomix 官方 FAQ 展开覆盖日常使用中最常遇到的问题如何选择输出格式、如何处理私有仓库与 GitHub 远程仓库、如何缩减输出 Token 以适配模型上下文、如何保护敏感信息以及如何把 Repomix 接入 Hermes Agent、OpenClaw 等 MCP 兼容 Agent。读完本文你将能根据场景选对 Repomix 的 workflow并独立排查文件丢失输出过大include 不生效等高频故障。一、Repomix 是什么一个命令搞定代码库上下文Repomix 的核心用途是把当前目录或指定目录中的代码整理为单个文本文件方便你直接把整个代码库喂给 AI 助手用于 code review、bug 调查、重构、编写文档、新成员 onboarding 等场景。官方 FAQ 的第一句话就点明了定位Repomix mengemas repository menjadi satu file yang ramah AI把仓库打包成一个 AI 友好的文件。从源码看CLI 入口 通过commander注册了全部命令行参数默认处理当前目录.)打包的主流程位于 packager.ts它按收集文件 → 安全检查 → 处理文件 → 生成输出的顺序完成一次打包。整个 CLI 在本地运行不依赖任何云端服务。二、常见问题Pertanyaan umum2.1 Repomix 能处理私有仓库吗可以。在本地已可访问的 checkoutclone 或下载下来的目录中直接运行repomixRepomix 在本地读取文件并生成输出文件不会把代码上传到 Repomix 的任何服务器。在把生成的打包文件分享给外部 AI 服务之前建议先人工检查一遍内容详见本文安全与隐私一节。2.2 不 clone 也能处理 GitHub 公开仓库可以。使用--remote参数支持owner/repo简写或完整 URL 两种写法npx repomix --remote yamadashy/repomix npx repomix --remote https://github.com/yamadashy/repomix底层实现位于 remoteAction.tsRepomix 会先把远程仓库下载到系统临时目录再在临时目录中执行与本地一致的打包流程最后把输出文件复制回当前目录并清理临时目录。下载策略是GitHub archive 优先、git clone 回退解析 URL 判断是否为 GitHub 仓库若是则先尝试下载仓库 archive支持进度显示若 archive 下载失败如仓库过大、网络受限自动回退到 git shallow clone浅克隆克隆成功后同样执行runDefaultAction完成打包。该流程还包含安全约束远程模式下--config必须使用绝对路径以避免从被克隆的仓库里加载恶意配置文件src/cli/actions/remoteAction.ts#L36-L44。2.3 输出格式XML / Markdown / JSON / plain怎么选FAQ 的建议非常明确XML默认结构化、信息完整不确定时选它准没错Markdown适合人类阅读的对话场景JSON适合程序化自动化处理plain text追求最大兼容性。repomix --style markdown repomix --style json--style支持的取值即 configSchema.ts 中定义的xml、markdown、json、plain四种输出风格默认xml。更完整的输出格式介绍见 Format Output 文档仓库中文版对应 输出说明。三、降低 Token 用量Mengurangi penggunaan token3.1 生成的输出文件太大怎么办FAQ 给出了四板斧按需组合使用repomix --include src/**/*.ts,docs/**/*.md # 只打包指定路径 repomix --ignore **/*.test.ts,dist/** # 排除测试与构建产物 repomix --compress # 代码结构压缩 repomix --remove-comments # 移除注释对大仓库建议把 include/ignore 筛选与代码压缩结合使用先用--include收窄范围再用--compress降低单文件体积最后用--remove-comments进一步瘦身。这几个参数都注册在 cliRun.ts--compress的描述是使用 Tree-sitter 解析提取类、函数、接口等关键代码结构--remove-comments是打包前剥离所有代码注释。--include/--ignore接受逗号分隔的 glob 模式列表如src/**/*.js,*.md。另外 cliTokenBudget.ts 在 Token 超限报错时也会提示同样的三条出路--compress减小体积、--include/--ignore收窄范围、或调高--token-budget。3.2--compress到底做了什么--compress会保留 imports、exports、class、function、interface 等关键结构同时删除大量实现细节非常适合需要快速理解仓库架构的场合。其底层是 Tree-sitter 语法解析。以 DefaultParseStrategy.ts 为例策略只挑选名字类name、注释类comment、导入类import/require的语法捕获节点输出其余实现代码直接丢弃项目同时为 C、C、C#、Go、Java、JavaScript、TypeScript、Python、Ruby、Rust、PHP、Dart、Solidity、Swift、Vue、CSS 等语言提供了对应的 parse 策略与查询文件见 queries 目录。正因为依赖每个语言的 parserFAQ 明确提示Tree-sitter 这类高级功能的效果取决于对应语言的 parser 支持情况。3.3 用 Token 预算与分片控制输出规模对于超大型仓库FAQ 还推荐两个实战命令repomix --token-count-tree 1000 # 只看 token 数 ≥ 1000 的文件 repomix --split-output 1mb # 按 1MB 拆分输出文件--token-count-tree [threshold]以文件树形式显示各文件 Token 数可选阈值只显示 Token 数 ≥ N 的文件如--token-count-tree 100。在 cliRun.ts 中该阈值被校验为非负整数--split-output size把输出拆成多个带编号的文件如repomix-output.1.xml、repomix-output.2.xml大小支持500kb、2mb、2.5mb等人类可读格式内部通过 sizeParse.ts 的parseHumanSizeToBytes解析为字节数。注意--split-output与--watch互斥src/cli/cliRun.ts#L283-L287watch 模式暂不支持分片输出。四、安全与隐私Keamanan dan privasi4.1 CLI 会把我的代码上传吗不会。Repomix CLI 完全在本地运行并写出输出文件官方 FAQ 明确说明CLI 不会上传代码网站website和浏览器扩展browser则有各自不同的工作流详见 Kebijakan Privasi中文版隐私说明。4.2 Repomix 如何防止 secret 混入输出Repomix 内置基于Secretlint的安全检查safety check把它视为额外防线但官方强调最终输出仍应人工检查一遍。底层实现位于 securityCheck.ts 与 securityCheckWorker.ts每个文件以及可选的 git diff、git log 内容都会被作为检查项提交检查规则使用secretlint/secretlint-rule-preset-recommendsecurityCheckWorker.ts能识别 API key、密码等常见敏感信息模式检查在 worker 线程中分批并发执行每批 50 项最多 2 个 worker避免阻塞主流程在 packager.ts 中安全检查与文件处理并行运行检查结束后标记为可疑suspicious的文件会被从最终输出中过滤掉。想跳过该检查可使用--no-security-check但仅在你明确知道自己在做什么时才应关闭它。五、故障排查Pemecahan masalah5.1 为什么输出里少了某些文件Repomix 的文件筛选遵循多层规则文件消失通常是以下原因之一.gitignore规则仓库的 gitignore 规则默认生效默认 ignore 规则内置忽略清单位于 defaultIgnore.ts涵盖node_modules/**、.git/**、dist/**、build/**、coverage/**、*.log、package-lock.json、yarn.lock、.env、各类编辑器/缓存/构建产物目录等大量常见噪声.ignore/.repomixignore文件项目级自定义忽略repomix.config.json中的配置包括output.patterns与命令行等价配置--ignore命令行参数追加排除模式。排查时依次检查repomix.config.json、--ignore参数以及各类 git ignore 规则即可。特别地内置 ignore 会默认排除**/repomix-output.*避免打包自身输出defaultIgnore.ts。5.2 如何让团队输出可复现创建并提交一份共享配置即可repomix --init--init会启动交互式向导initAction.ts依次询问是否创建repomix.config.json、选择输出风格xml/markdown/json/plain默认 xml、指定输出文件路径随后生成带$schema的配置文件和.repomixignore模板。把这俩文件提交进仓库团队所有成员用相同配置打包输出自然一致。--global可将配置生成到主目录的全局配置目录src/config/globalDirectory.ts。六、更多问题Pertanyaan umum tambahan6.1 支持 C#、Python、Java、Go、Rust 等其他语言吗支持。Repomix 读取项目中的文件并重新格式化给 AI 工具因此理论上可以打包任何编程语言写的仓库。FAQ 同时提醒两个前提CLI 需要 Node.js 22 或更高版本某些高级功能如基于 Tree-sitter 的代码压缩依赖对应语言的 parser 支持——正如上文所述本项目已为 17 种语言提供了 parse 策略与查询文件但对 parser 未覆盖的语言--compress可能退化为不压缩或效果有限。6.2 能与 Hermes Agent、OpenClaw 等 MCP Agent 一起用吗可以。Repomix 可以以 MCP server 方式运行npx -y repomix --mcpHermes Agent的接入方式在~/.hermes/config.yaml中把 Repomix 注册为 stdio MCP servermcp_servers: repomix: command: npx args: [-y, repomix, --mcp]OpenClaw 或其他 MCP 兼容 Agent在允许配置外部 stdio MCP server 的位置使用同样的command和args即可。MCP 模式下的服务器实现位于 mcpServer.ts提供packCodebaseTool、packRemoteRepositoryTool、grepRepomixOutputTool、readRepomixOutputTool、attachPackedOutputTool、generateSkillTool以及受沙箱约束的文件系统读取工具等见 mcp/tools 目录。另外--sandbox [dir]可以把 MCP 的文件工具限制在指定工作区内并用--remote-trust-config决定是否信任远程仓库中的配置文件。如果你的 AI 助手支持Agent Skills还可以直接使用 Repomix Explorer Skill中文版repomix-explorer-skill仓库中对应 skill 定义见 skills/repomix-explorer/SKILL.md。6.3 如何让 AI 助手快速理解一个新库/新框架把该库或它的文档打包后交给 AI 作为参考即可npx repomix --remote owner/repo npx repomix --remote owner/repo --include docs/**,src/**第二条命令用--include只保留文档与源码目录控制参考材料的体量。如果需要反复使用可以生成可复用的 Agent Skills 目录npx repomix --remote owner/repo --skill-generate library-reference--skill-generate [name]会生成 Claude Agent Skills 格式的输出到.claude/skills/name/目录名字省略时根据仓库 URL 自动生成见 skillUtils.ts远程模式下runRemoteAction会先在临时目录完成打包再把 skill 写入当前目录remoteAction.ts。6.4 如何排除 CSS、测试、构建产物等噪音文件一次性命令用--ignorerepomix --ignore **/*.css,**/*.test.ts,dist/**,coverage/**只想保留某些路径则用--includerepomix --include src/**/*.ts,docs/**/*.md两个参数都支持逗号分隔的多个 glob 模式--ignore也可用-i简写。若想长期生效建议把规则写入repomix.config.json或.repomixignore并提交到仓库。6.5 仓库大小有限制吗CLI 本身没有固定的仓库大小上限但实际打包会受到三方面限制本机内存、文件大小以及目标 AI 工具的上传/上下文上限。对大项目FAQ 给出的处理思路是先用有针对性的 include 模式收窄范围 → 用--token-count-tree找出 Token 大户 → 必要时用--split-output拆分输出。对应命令repomix --token-count-tree 1000 repomix --split-output 1mb6.6 为什么--include没把node_modules或 build 目录里的文件打进去这是最容易被误解的一点--include只是缩小候选文件集合并不会绕过 ignore 规则。也就是说文件仍然可能被以下任意一层规则排除.gitignore.ignore.repomixignore内置默认模式如 defaultIgnore.ts 中的node_modules/**、dist/**等repomix.config.json中的配置对于高级场景可以尝试--no-gitignore不使用 .gitignore 规则或--no-default-patterns不应用内置默认忽略模式来放宽过滤但务必谨慎这会引入 dependencies、构建产物或其他噪音文件打包体积可能急剧膨胀也可能把本应受 gitignore 保护的敏感文件带进输出。对应参数在 cliRun.ts 中有完整定义。七、相关参考Penggunaan Dasar基础用法中文版见 usage.mdOpsi Command Line命令行选项中文版见 command-line-options.mdKompresi Kode代码压缩中文版见 code-compress.mdKeamanan安全中文版见 security.mdKebijakan Privasi隐私中文版见 privacy.mdRepomix Explorer Skill中文版见 repomix-explorer-skill.md【免费下载链接】repomix Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考