企业官网建设流程全解析

Repomix 命令行选项完全指南：从基础用法到 MCP 与 Agent Skills 的 CLI 全量参考

【免费下载链接】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

Repomix 是一个将整个代码仓库打包成单个 AI 友好文件的工具，其 CLI 提供了覆盖输入输出、文件选择、远程仓库、配置、安全、Token 计数、MCP 服务器与 Agent Skills 生成的完整选项体系。本文以官方《命令行选项》文档（website/client/src/zh-cn/guide/command-line-options.md）为主体骨架，结合仓库源码（src/cli/cliRun.ts、src/cli/actions/defaultAction.ts 等）逐项解读每个参数的取值、默认值与底层实现原理，帮助你精准构造任何场景下的打包命令。

基本选项

该选项在 src/cli/cliRun.ts 中注册，命中后进入runVersionAction()打印版本号。此外在非 stdin 模式下，CLI 启动时会额外打印一行📦 Repomix v<version>的版本横幅（见 src/cli/cliRun.ts），stdin 模式刻意跳过该横幅，避免干扰管道输出。

CLI 输入/输出选项

从源码实现看（src/cli/cliRun.ts）：

• --verbose与--quiet在 Commander 中通过.conflicts()声明互斥，同时传入会直接报错。两者通过logger.setLogLevel()分别切换 DEBUG 与 SILENT 日志级别（src/cli/cliRun.ts）。
• --stdout与--output互斥；进入 stdout 模式后日志级别被强制设为 SILENT，保证管道里只有纯净的打包内容。注意-o "-"会被自动等价转换为 stdout 模式（src/cli/cliRun.ts）。
• --stdin模式下禁止再传入目录位置参数，文件路径从标准输入逐行读取，由 src/core/file/fileStdin.ts 的readFilePathsFromStdin()处理（校验逻辑见 src/cli/actions/defaultAction.ts）。
• --token-count-tree的阈值参数会在解析阶段校验必须为非负整数，非法输入抛出Invalid token count threshold错误；--top-files-len同理校验为非负整数（src/cli/cliRun.ts）。

Repomix 输出选项

输出风格与文件命名

--style的四种取值由 src/config/configSchema.ts 中的 picklist 枚举约束（xml | markdown | json | plain）。每种风格有对应的默认输出文件名（src/config/configSchema.ts）：

--output-file-path-style的两个取值（target-relative与cwd-relative）同样由 src/config/configSchema.ts 枚举约束，控制输出中文件路径是相对打包目标目录还是相对当前工作目录展示。

拆分输出与大小解析

--split-output的值通过parseHumanSizeToBytes()解析为字节数（src/cli/cliRun.ts），支持500kb、2mb、2.5mb这类人类可读的写法。拆分后生成repomix-output.1.xml、repomix-output.2.xml等编号文件。

与配置文件的关系：--no-*标志的语义

一个容易被忽略的细节：得益于 Commander.js 对--no-*标志的处理，--no-file-summary、--no-directory-structure、--no-files、--no-git-sort-by-changes这类选项只有在显式传入时才生效，且仅当其显式为false时才覆盖配置文件——也就是说配置文件中的对应设置拥有优先级，除非你在命令行明确否定它（src/cli/actions/defaultAction.ts 及buildCliConfig中的相关分支）。这一设计让配置文件可以稳定持有默认值，而 CLI 仅做显式覆盖。

文件选择选项

在源码中，--include与--ignore的逗号分隔字符串会通过splitPatterns()拆分为模式数组，--ignore映射为配置的ignore.customPatterns字段（src/cli/actions/defaultAction.ts）。

--no-default-patterns关闭的内置忽略清单非常庞大，定义在 src/config/defaultIgnore.ts 中，覆盖：

• 版本控制：.git/**、.hg/**、.svn/**
• 依赖目录：**/node_modules/**、vendor/**、**/.gradle/**、target/**
• 日志与运行时数据：**/*.log、logs/**、*.pid
• 构建产物与缓存：dist/**、build/**、out/**、.next/**、coverage/**、各类*.cache
• 环境变量文件：.env
• 编辑器/系统文件：.idea/**、.vscode/**、**/.DS_Store、**/Thumbs.db
• 各语言锁文件：**/package-lock.json、**/yarn.lock、**/pnpm-lock.yaml、**/Cargo.lock、**/go.sum、**/Gemfile.lock、**/poetry.lock等
• Repomix 自身输出：**/repomix-output.*（含旧名**/repopack-output.*）

远程仓库选项

远程仓库的三种写法

• 完整 URL：repomix --remote https://github.com/user/repo/tree/main（可指定分支）或.../commit/<sha>（可指定提交）
• 简写：repomix --remote user/repo
• 自动检测：repomix user/repo—— 当位置参数既不是本地存在的路径、又能通过 GitHub 的 HEAD-onlygit ls-remote探测确认可达时，自动按远程仓库处理（src/cli/cliRun.ts）。从源码注释看，简写与本地相对路径存在歧义，因此只有当本地路径确实不存在且远程探测成功时才判定为远程；误写的本地路径（如src/uitls）会探测失败并回落到本地路径处理，不会误触发克隆。

下载策略与安全边界

远程处理逻辑在 src/cli/actions/remoteAction.ts 中：

• GitHub 仓库优先尝试归档（archive）下载（支持时走downloadGitHubArchive，超时 60 秒、重试 2 次），失败后回退到浅克隆（git clone）（src/cli/actions/remoteAction.ts）。
• 仓库先下载到临时目录，打包完成后将输出文件复制回当前目录，再清理临时目录（cleanupTempDirectory）。
• 远程模式下--config必须是绝对路径，防止从克隆下来的仓库中意外加载恶意配置（src/cli/actions/remoteAction.ts）。
• 未加--remote-trust-config时，远程仓库自身的配置被整体跳过（skipLocalConfig: true），文件处理器（可执行任意命令的input.processors）也不会启用；只有显式信任后才启用，且交互式终端会先展示该配置并请求确认（src/cli/actions/remoteAction.ts）。也可通过环境变量REPOMIX_REMOTE_TRUST_CONFIG=true启用，--force可跳过确认。

配置选项

配置加载是"默认配置 → 文件配置 → CLI 配置"的三层合并（mergeConfigs，见 src/cli/actions/defaultAction.ts）：buildMergedConfig先运行 Repopack 旧版配置迁移，再加载文件配置（loadFileConfig），随后通过buildCliConfig将 CLI 选项解析成配置并合并，最终由 valibot 的repomixConfigCliSchema校验（非法参数会抛出Invalid cli arguments）。

--init是一个交互式向导（src/cli/actions/initAction.ts），会依次询问：是否创建repomix.config.json（已存在时询问是否覆盖）→ 选择输出风格（xml/markdown/json/plain，各带默认输出路径）→ 是否创建.repomixignore文件。--global模式下配置写入主目录（由getGlobalDirectory()定位）而非当前目录，且跳过.repomixignore的创建。

安全选项

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

默认情况下 Repomix 会扫描打包内容中的密钥、密码等敏感信息（security.enableSecurityCheck默认开启）。从 src/cli/actions/defaultAction.ts 可见，该选项仅在显式传入false时才生效并覆盖配置。安全扫描的核心实现位于 src/core/security/securityCheck.ts，配套的检测规则与测试可参考 tests/core/security/securityScanSpec.test.ts。除非你明确知道输出不会泄露敏感信息，否则不建议关闭。更多细节见安全指南。

Token 计数选项

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

支持的编码

可用的 token 编码由 src/core/metrics/tokenEncodings.ts 定义：

• o200k_base（默认，对应 GPT-4o 等 o 系列模型）
• cl100k_base（对应 GPT-3.5/GPT-4）
• p50k_base、p50k_edit
• r50k_base

token-budget 是"事后防护"而非"提前熔断"

--token-budget的校验逻辑在 src/cli/cliTokenBudget.ts 中：输出照常生成并写出，仅当总 token 数超过预算时抛出错误使进程以非零退出码结束。错误信息会给出实际 token 数与预算值，并提示通过--compress、--include/--ignore缩小范围或调高预算。这一语义在远程模式下同样成立：远程运行会先把输出从临时目录复制出来再执行校验（deferTokenBudgetCheck，见 src/cli/actions/remoteAction.ts），避免超预算时输出被随临时目录一起清理掉。因此它可以安全地嵌入 CI 与 agent 工作流作为上下文窗口防护闸。

MCP 选项

• --mcp：作为 AI 工具集成的 Model Context Protocol 服务器运行
• --sandbox [dir]：（配合--mcp使用）将 MCP 服务器的文件工具限制在一个工作区目录内（默认为当前工作目录；例如--sandbox path/to/project）。所有路径都相对于该根目录解析，绝对路径/主机路径会被拒绝，同时远程打包、Skill 生成以及附加外部输出功能均被禁用

--mcp模式下 Repomix 启动 MCP 服务器（runMcpAction，见 src/cli/cliRun.ts），向 AI Agent 暴露pack_codebase、read_repomix_output、grep_repomix_output、file_system_read_file、file_system_read_directory、attach_packed_output、generate_skill、pack_remote_repository等工具（src/mcp/mcpServer.ts）。

--sandbox提供路径级隔离：

• 未指定目录时默认为当前工作目录；所有路径相对该根目录解析，绝对路径与主机路径会被拒绝。
• 沙箱模式下远程打包、Skill 生成、附加外部输出被禁用。
• 源码注释还揭示了更细的防护：沙箱会跳过本地与全局配置文件（skipLocalConfig+skipGlobalConfig），并开启confineToBaseDir兜底，杜绝配置驱动的instructionFilePath或input.processors把工作区外文件引入 Agent 可见输出（src/cli/types.ts）。
• 沙箱根目录会先经realpath规范化（解析符号链接，兼容 macOS/tmp→/private/tmp），保证路径守卫与错误信息抹除基于同一份真实路径（src/cli/cliRun.ts）。注意：不带--mcp单独使用--sandbox时，CLI 会警告该选项不生效。

完整的使用指南见 MCP 服务器文档。

Agent Skills 生成选项

--skill-generate将打包结果转换为 Claude Agent Skills 格式（含SKILL.md），写入.claude/skills/<name>/。省略名称时，会根据目标目录自动生成默认技能名（本地场景用generateDefaultSkillName，远程场景用generateDefaultSkillNameFromUrl，见 src/cli/actions/defaultAction.ts 与 src/cli/actions/remoteAction.ts）。

使用约束（来自 src/cli/actions/defaultAction.ts 与validateConflictingOptions）：

• --skill-output、--skill-project-name、--force必须与--skill-generate搭配使用，否则直接报错；--skill-output不能为空。
• 不传--skill-output时会以交互方式提示选择技能位置；传入后跳过提示直接写入。
• --split-output与--skill-generate冲突（Skill 输出是目录，不是多个编号文件）；--stdout、--copy与--skill-generate同样冲突（src/cli/actions/defaultAction.ts）。

监视模式选项

• -w, --watch：监视文件更改并自动重新打包。会检测新增、修改和删除的文件，对快速连续的更改进行防抖处理（300 毫秒），并在每次重新构建后打印时间戳。按Ctrl+C停止。

监视模式由 src/cli/actions/watchAction.ts 实现，底层使用 chokidar：

• 首次立即打包一次，随后监听change/add/unlink事件触发重建。
• 300ms 防抖（常量REBUILD_DEBOUNCE_MS = 300）合并快速连续的文件事件；同时启用awaitWriteFinish（stabilityThreshold: 100ms），等待文件大小稳定后才触发事件，避免打包到写了一半的文件（src/cli/actions/watchAction.ts）。
• 重建串行化：正在重建时到达的新事件会被排队（pendingRebuild），重建完成后自动补跑一次（src/cli/actions/watchAction.ts）。
• 每次重建后打印Rebuilt at HH:MM:SS时间戳（用toTimeString()取稳定的 24 小时制前段，保证跨平台一致）。
• 监听目标采用与打包器一致的 ignore 过滤（buildWatchIgnoreFilter），chokidar 不会进入node_modules、.git与 gitignore 目录，避免大项目出现 EMFILE 和无谓重建。
• SIGINT/SIGTERM触发优雅关闭：清理防抖定时器、关闭 watcher、等待进行中的重建完成（src/cli/actions/watchAction.ts）。

监视模式的限制

监视模式仅适用于本地目录，不能与以下选项组合（src/cli/cliRun.ts）：

• --remote或位置参数形式的远程仓库 URL
• --stdout（监视模式必须写文件）
• --stdin（监视模式自动发现文件）
• --split-output（拆分会生成编号文件，被 watcher 再次捕获形成循环）
• --skill-generate
• --copy（每次变更都重新覆盖剪贴板）

需要特别注意：无论该选项是写在命令行还是写在配置文件里，这些限制都同样生效——runWatchAction在合并配置后会对配置文件来源的splitOutput、stdout 输出、copyToClipboard、skillGenerate再次校验（src/cli/actions/watchAction.ts），因为cliRun中的命令行级校验看不到配置文件的值。

相关资源

• 配置指南 —— 通过配置文件而非 CLI 标志设置选项
• 输出格式 —— XML、Markdown、JSON 和纯文本格式详解
• 代码压缩 ——--compress与 Tree-sitter 的工作原理
• 安全指南 ——--no-security-check禁用的功能

实用示例

以下示例覆盖文档中的全部典型场景，可直接复制运行：

# 基本使用 repomix # 自定义输出文件和格式 repomix -o my-output.xml --style xml repomix -o my-output.md --style markdown repomix -o my-output.json --style json # 输出到标准输出 repomix --stdout > custom-output.txt # 输出到标准输出，然后管道到另一个命令（例如 simonw/llm） repomix --stdout | llm "请解释这段代码的作用。" # 使用压缩的自定义输出 repomix --compress # 拆分输出为多个文件（每部分最大体积） repomix --split-output 20mb # Git 集成功能 repomix --include-diffs # 包含未提交更改的 git diff repomix --include-logs # 包含 git 日志（默认最近 50 个提交） repomix --include-logs --include-logs-count 10 # 包含最近 10 个提交 repomix --include-diffs --include-logs # 同时包含差异和日志 # 使用模式处理特定文件 repomix --include "src/**/*.ts,*.md" --ignore "*.test.js,docs/**" # 带分支的远程仓库 repomix --remote https://github.com/user/repo/tree/main # 带提交的远程仓库 repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1 # 使用简写的远程仓库 repomix --remote user/repo # 使用简写的远程仓库（自动检测，无需 --remote） repomix user/repo # 使用 stdin 的文件列表 find src -name "*.ts" -type f | repomix --stdin git ls-files "*.js" | repomix --stdin echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin # Token 计数分析 repomix --token-count-tree repomix --token-count-tree 1000 # 仅显示拥有 1000+ Token 的文件/目录 # 监视模式：文件更改时自动重新打包 repomix --watch repomix -w --include "src/**/*.ts"

组合技巧

• CI 防护闸：repomix --token-budget 100000配合 CI 的非零退出码判定，确保任何提交的打包产物都不超出目标模型上下文窗口。
• Agent 脚本化：repomix --quiet --stdout | your-llm-tool在静默模式下把纯净输出交给下游命令，避免版本横幅与日志污染管道。
• 远程仓库精确定位：repomix --remote <url> --remote-branch <tag>可以打包指定 tag 或 commit 的代码快照，适合对历史版本做对比分析。
• 两种未知选项报错体验：Repomix 的 CLI 内置了语义建议映射（src/cli/cliRun.ts），当输错选项时会给出相近的正确选项提示，例如输入--exclude会提示Did you mean: --ignore?，输入--format会提示Did you mean: --style?，降低上手成本。

以上所有选项均可在 src/cli/cliRun.ts 中查看到完整定义，在 src/config/configSchema.ts 中查看其配置化等价字段。若需将选项固化到项目中，可运行repomix --init生成配置文件，或直接阅读配置指南手工编写。

【免费下载链接】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