多彩编程 多彩编程MZPH · CODE BLOG
ARTICLE DETAIL

文章详情

深耕前端与后端开发技术的一线实战笔记与踩坑复盘。

Repomix 输出格式完全指南:XML、Markdown、JSON 与纯文本的选择与实战

Repomix 输出格式完全指南:XML、Markdown、JSON 与纯文本的选择与实战 开发工具MCP 服务AI 应用【免费下载链接】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 友好文件时支持 XML、Markdown、JSON 和纯文本四种输出格式。本文以 官方西班牙语文档 为主体结合仓库源码输出生成器、输出样式模板深入讲解每种格式的结构差异、适用场景与底层实现并给出 JSON 输出的jq实战操作与配置文件自定义方法。读完本文你将能根据下游消费方Claude、ChatGPT、Gemini、API 或自动化脚本精准选择输出格式并掌握可复制的命令与配置。一、四种输出格式总览Repomix 支持以下四种输出格式其中XML 为默认格式格式CLI 参数默认输出文件核心特点XML--style xmlrepomix-output.xml面向 AI 处理优化语义化标签结构默认Markdown--style markdownrepomix-output.md人类可读代码块带语法高亮语言标注JSON--style jsonrepomix-output.json结构化、可编程解析属性名为 camelCase纯文本--style plainrepomix-output.txt极简分隔线结构通用兼容这一划分在源码中有明确约束配置模式 通过v.picklist([xml, markdown, json, plain])严格限定合法取值并定义默认输出文件映射defaultFilePathMap见 configSchema.tsCLI 选项定义 中的--style type帮助文本也写明Output format: xml, markdown, json, or plain (default: xml)。在 输出生成器 中四种格式的分派逻辑是xml与markdown、plain走 Handlebars 模板渲染json走独立的generateParsableJsonOutput而xml在开启parsableStyle时还会切换为generateParsableXmlOutput。下文逐一展开。二、XML 格式面向 AI 处理的默认选择使用命令repomix --style xmlXML 格式专为 AI 处理优化输出大致结构如下Este archivo es una representación fusionada de toda la base de código... file_summary (Metadatos e instrucciones de IA) /file_summary directory_structure src/ index.ts utils/ helper.ts /directory_structure files file pathsrc/index.ts // Contenido del archivo aquí /file /files git_logs git_log_commit date2025-08-20 00:47:19 0900/date messagefeat(cli): Add --include-logs option for git commit history/message files README.md src/cli/cliRun.ts src/core/git/gitCommand.ts src/core/git/gitLogHandle.ts src/core/output/outputGenerate.ts /files /git_log_commit git_log_commit date2025-08-21 00:09:43 0900/date messageMerge pull request #795 from yamadashy/chore/ratchet-update-ci/message files .github/workflows/ratchet-update.yml /files /git_log_commit /git_logs各语义化标签区块的生成逻辑可在 XML 模板 中找到对应实现file_summary由fileSummaryEnabled控制内含purpose、file_format、usage_guidelines、notes四个子块对应 outputStyleDecorate.ts 中generateSummaryPurpose、generateSummaryFileFormat等函数生成的元数据与 AI 指令user_provided_header仅在配置了headerText时出现用于注入自定义头部文本directory_structure由directoryStructureEnabled控制展示树形目录files每个文件以file path...形式承载路径属性与完整内容由filesEnabled控制git_diffs包含git_diff_work_tree与git_diff_staged由output.git.includeDiffs控制git_logs每条提交以git_log_commit包裹date、message、files由output.git.includeLogs控制instruction读取instructionFilePath指定的文件内容后注入。为什么 XML 是默认格式Repomix 之所以将 XML 定为默认格式是建立在大量研究与测试之上的决策主要受主流 AI 供应商官方推荐的影响AnthropicClaude明确推荐使用 XML 标签来结构化提示词官方文档称Claude 在训练阶段就接触过这类提示GoogleGemini针对复杂任务推荐使用包括 XML 在内的结构化格式OpenAIGPT在复杂场景中倡导结构化提示structured prompting。从仓库实现看默认配置 中style的默认值正是xml且默认输出文件为repomix-output.xml与官方推荐保持一致。可选的可解析 XML--parsable-style默认情况下XML 由 Handlebars 模板渲染{{{this.content}}}直接内插文件内容。若仓库代码中存在会破坏 XML 结构的特殊字符如未转义的、可开启--parsable-style此时 generateParsableXmlOutput 会改用fast-xml-builder库构建文档树自动转义特殊字符保证生成结果始终是合法可解析的 XML。CLI 帮助文本cliRun.ts对此的描述是Escape special characters to ensure valid XML/Markdown (needed when output contains code that breaks formatting)。三、Markdown 格式可读性与语法高亮使用命令repomix --style markdownMarkdown 提供人类友好的可读格式Este archivo es una representación fusionada de toda la base de código... # Resumen de archivos (Metadatos e instrucciones de IA) # Estructura de directorios src/ index.ts utils/ helper.ts # Archivos ## Archivo: src/index.ts typescript // Contenido del archivo aquí # Logs de Git 2025-08-20 00:47:19 0900|feat(cli): Add --include-logs option for git commit history README.md src/cli/cliRun.ts src/core/git/gitCommand.ts src/core/git/gitLogHandle.ts src/core/output/outputGenerate.ts 2025-08-21 00:09:43 0900|Merge pull request #795 from yamadashy/chore/ratchet-update-ci .github/workflows/ratchet-update.yml 源码级细节代码块语言自动推断Markdown 模板 中每个文件的内容被包裹在带语言标注的代码块中语言名由getFileExtensionHandlebars 助手动态计算。其底层实现在 outputStyleUtils.ts通过文件扩展名映射到 GitHub Linguist 风格的语言名如.ts → typescript、.py → python、.vue → vue、.dockerfile → dockerfile映射表覆盖了 100 多种语言/格式见 extensionToLanguageMap未知扩展名则回退为空字符串。源码级细节反引号定界符自动伸缩为避免文件内容中的提前闭合代码块导致输出损坏outputGenerate.ts 中的calculateMarkdownDelimiter会扫描所有文件内容、目录树与 Git diff 中的连续反引号最大长度自动将代码块定界符扩展为max(3, 最长反引号串 1)个反引号——即使仓库里混有 Markdown 文档其代码块自带 上下文行也能保证输出结构完整。四、JSON 格式面向程序化处理与 API 集成使用命令repomix --style jsonJSON 格式提供结构化、可编程访问的输出属性名统一采用 camelCase{ fileSummary: { generationHeader: Este archivo es una representación fusionada de toda la base de código, combinada en un solo documento por Repomix., purpose: Este archivo contiene una representación empaquetada del contenido completo del repositorio..., fileFormat: El contenido está organizado de la siguiente manera..., usageGuidelines: - Este archivo debe tratarse como de solo lectura..., notes: - Algunos archivos pueden haber sido excluidos según las reglas de .gitignore... }, userProvidedHeader: Texto de encabezado personalizado si se especifica, directoryStructure: src/ cli/ cliOutput.ts index.ts config/ configLoader.ts, files: { src/index.js: // Contenido del archivo aquí, src/utils.js: // Contenido del archivo aquí }, instruction: Instrucciones personalizadas desde instructionFilePath }源码级实现generateParsableJsonOutputJSON 由 generateParsableJsonOutput 直接生成files字段被归约为{ 文件路径: 文件内容 }的映射对象每个文件一个键值对gitDiffs、gitLogs数组化提交记录date、message、files等区块仅在对应配置开启时通过展开运算符按需注入最终以JSON.stringify(jsonDocument, null, 2)输出带缩进的合法 JSON。测试用例 jsonStyle.test.ts 验证了其关键行为生成结果可通过JSON.parse、fileSummary可按配置开启/关闭关闭时该字段为undefined、files[src/index.ts]能按路径精确取出文件内容。JSON 格式的优势JSON 格式非常适合以下场景程序化处理任何语言的 JSON 库都能轻松解析与操作API 集成可直接被 Web 服务与应用消费AI 工具兼容性结构化格式便于机器学习系统与 AI 框架读取数据分析使用jq等工具即可快速提取指定信息。用 jq 处理 JSON 输出JSON 格式让程序化提取特定信息变得非常容易以下为常见实战示例。基础文件操作# 列出所有文件路径 cat repomix-output.json | jq -r .files | keys[] # 统计文件总数 cat repomix-output.json | jq .files | keys | length # 提取指定文件内容 cat repomix-output.json | jq -r .files[README.md] cat repomix-output.json | jq -r .files[src/index.js]文件过滤与分析# 按扩展名查找文件 cat repomix-output.json | jq -r .files | keys[] | select(endswith(.ts)) cat repomix-output.json | jq -r .files | keys[] | select(endswith(.js) or endswith(.ts)) # 获取包含指定文本的文件 cat repomix-output.json | jq -r .files | to_entries[] | select(.value | contains(function)) | .key # 生成带字符计数的文件清单 cat repomix-output.json | jq -r .files | to_entries[] | \(.key): \(.value | length) caracteres元数据提取# 提取目录结构 cat repomix-output.json | jq -r .directoryStructure # 获取文件摘要信息 cat repomix-output.json | jq .fileSummary.purpose cat repomix-output.json | jq -r .fileSummary.generationHeader # 提取用户自定义头部若存在 cat repomix-output.json | jq -r .userProvidedHeader // No se proporcionó encabezado # 获取自定义指令 cat repomix-output.json | jq -r .instruction // No se proporcionaron instrucciones高级分析# 按内容长度找出最大的文件 cat repomix-output.json | jq -r .files | to_entries[] | [.key, (.value | length)] | tsv | sort -k2 -nr | head -10 # 搜索包含特定模式的文件忽略大小写 cat repomix-output.json | jq -r .files | to_entries[] | select(.value | test(import.*react; i)) | .key # 提取匹配多个扩展名的文件路径 cat repomix-output.json | jq -r .files | keys[] | select(test(\.(js|ts|jsx|tsx)$))注意fileSummary、directoryStructure、instruction等区块都是可配置的详见下文自定义若对应区块被关闭上方的jq表达式会返回null此时可用//运算符提供兜底值。五、纯文本格式极简与通用兼容使用命令repomix --style plain纯文本输出结构Este archivo es una representación fusionada de toda la base de código... Resumen de archivos (Metadatos e instrucciones de IA) Estructura de directorios src/ index.ts utils/ helper.ts Archivos Archivo: src/index.ts // Contenido del archivo aquí Logs de Git 2025-08-20 00:47:19 0900|feat(cli): Add --include-logs option for git commit history README.md src/cli/cliRun.ts src/core/git/gitCommand.ts src/core/git/gitLogHandle.ts src/core/output/outputGenerate.ts 2025-08-21 00:09:43 0900|Merge pull request #795 from yamadashy/chore/ratchet-update-ci .github/workflows/ratchet-update.yml在 纯文本模板 中区块标题使用 64 个组成的长分隔线PLAIN_LONG_SEPARATOR文件条目使用 16 个的短分隔线PLAIN_SEPARATOR并在文档末尾附加End of Codebase结束标记。该格式不依赖任何标记语言语法适合最广泛的消费场景。六、与 AI 模型的搭配建议每种格式都能很好地配合 AI 模型使用但各有侧重Claude → XML解析精度最佳与 Anthropic 官方推荐一致一般可读性 → Markdown人工审阅与文档化场景友好程序化处理 / API 集成 → JSON机器解析、jq 查询、服务对接首选极简与普适兼容 → 纯文本无需任何语法解析任何环境均可直接读取。七、自定义默认输出格式除命令行临时指定外可以在repomix.config.json中固化默认格式{ output: { style: xml, filePath: output.xml } }配置合并时有一个贴心细节若未显式设置filePathconfigLoad.ts 会根据最终生效的style自动将输出文件名调整为对应的默认值如--style json时自动变为repomix-output.json避免出现内容格式与扩展名不匹配的困扰只有显式指定了filePath才会保留自定义文件名。结合 配置模式 中的output对象你还可以在同一配置里控制各区块开关fileSummary、directoryStructure、files默认均为true、是否转义特殊字符parsableStyle、自定义头部headerText、指令文件instructionFilePath以及 Git 相关区块git.includeDiffs、git.includeLogs、git.includeLogsCount默认 50 条等。八、延伸阅读配置指南完整配置选项参考输出对象的所有字段说明命令行选项--style及其他输出相关参数的完整用法代码压缩在保持结构的前提下降低 Token 数量适合处理超大仓库提示词示例不同 AI 模型消费 Repomix 输出的提示词技巧。赞分享开发工具MCP 服务AI 应用【免费下载链接】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点击查看免费下载相关推荐Gobuster输出格式定制CSV、JSON与纯文本的灵活选择Gobuster输出格式定制CSV、JSON与纯文本的灵活选择 引言告别千篇一律掌控扫描结果 你是否曾在使用Gobuster一款功能强大的目录和文件扫描网络安全渗透测试GPT-2输出文本格式化JSON/纯文本/Markdown的多格式导出GPT 2输出文本格式化JSON/纯文本/Markdown的多格式导出 一、痛点与解决方案概述 在使用GPT 2生成文本时原始输出往往是未经格式化的纯文本人工智能大模型基础模型NLPjrnl 输出格式完全指南Pretty、JSON、Markdown、YAML 等内置格式与 --file 导出实战jrnl 输出格式完全指南Pretty、JSON、Markdown、YAML 等内置格式与 file 导出实战 jrnl 是一款纯命令行的日记与笔记工具其强CLI上一篇Guetzli内存使用分析报告优化前后对比下一篇Turbolinks开发工具推荐提升开发效率的利器创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表