Repomix 代码库核心开发指南从仓库结构到提交规范的完整实践【免费下载链接】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 项目根目录下的.agents/rules/base.md核心开发规范文档整理而成。Repomix 是一款将整个仓库打包为单一 AI 友好文件的开源工具支持 XML、Markdown、JSON 与纯文本四种输出格式。读完本文你将掌握该项目的仓库布局、编码标准、测试与依赖注入约定、提交信息规范、PR 流程以及诸多文档里不会明说的隐藏规则与常见陷阱可直接用于参与 Repomix 的日常开发与代码评审。Repomix 项目速览Repomix 的核心能力是打包将仓库中的代码内容聚合进一个文件方便直接投喂给 Claude、ChatGPT 等大语言模型LLM使用。项目根目录的 README.md 明确写道Repomix 是一款强大的工具可将整个仓库打包为单一、AI 友好的文件。其核心特性包括 AI 优化格式输出、文件级 Token 计数、Git 感知自动尊重.gitignore、.ignore与.repomixignore、基于 Secretlint 的敏感信息检测以及基于 Tree-sitter 的代码压缩能力。而在 .agents/rules/base.md 这份规范文档中项目定义了所有贡献者包括代码 Agent在 Repomix 代码库内工作时应遵循的准则。它是仓库的宪法级文件声明了对任何代码、文档或配置文件变更都生效frontmatter 中alwaysApply: true本文接下来即围绕它展开。仓库布局按功能组织测试与源码一一镜像规范文档给出了清晰的顶层结构划分实际仓库内容与之完全吻合目录职责仓库证据src/主源码按功能模块组织cli/、config/、core/、shared/功能之间避免相互依赖如 src/core/file/fileCollect.ts、src/config/configSchema.tstests/测试目录与src/目录结构一一镜像例如 tests/core/file/fileCollect.test.ts 对应src/core/file/下实现website/文档站点VitePress文档位于website/client/src/下的 15 个语言目录en 14 个翻译语言仓库中确实存在en、de、es、fr、hi、id、it、ja、ko、pt-br、ru、tr、vi、zh-cn、zh-tw等语言目录browser/浏览器扩展基于 WXT 框架browser/entrypoints/background.ts 等实践要点新增功能代码时请遵循功能化目录结构feature-based structure的设计避免功能之间产生不必要的依赖保持模块边界清晰。新增功能必须同步在tests/下建立对应的测试文件保持目录结构镜像关系便于快速定位测试。文档变更涉及面向用户的功能时需要同时更新全部 15 个语言目录下的文档而不仅是英文详见下文陷阱部分。编码规范Biome 强制 单一职责遵循 Biome 配置规范要求遵循项目由biome.json强制执行的编码标准。查看仓库根目录的 biome.json可以发现具体规则格式化风格使用空格缩进缩进宽度为 2行宽上限 120 字符JavaScript 风格单引号quoteStyle: single、尾随逗号trailingCommas: all、始终加分号semicolons: alwaysLinter启用推荐规则集recommended: true并对*.vue文件关闭noUnusedVariables与noUnusedImports对src/index.ts关闭 import 自动整理以保留其入口文件的导出顺序。文件单一职责与 250 行信号规范提出一个非常实用的判断标准将每个文件聚焦于单一职责。将约 250 行视为一个复核信号signal而非拆分命令mandate当文件混杂多种职责时才拆分如果行数多是因为单一内聚关注点如大型数据/配置表则保持原样。换句话说250 行不是硬性上限而是触发你重新审视文件内聚度的提示。例如大型语言配置表、正则查询文件即使行数超出也无需强行拆分。注释与验证在逻辑不明显之处添加英文注释注释统一使用英文新功能必须配套对应的单元测试修改后运行验证命令npm run lint # 确保代码风格合规 npm run test # 确保所有测试通过从根目录 package.json 可以看到npm run lint实际串联了四道检查lint-biomebiome check --write、lint-oxlintoxlint --fix、lint-tstsc --noEmit类型检查与lint-secretlint敏感信息扫描npm run test则调用 Vitest 执行测试。非明显规则与陷阱新手最容易踩的坑这一节是文档的精华所在列出了只有深入参与开发才会知道的隐性规则务必逐条阅读1. 配置 JSON Schema 禁止手改website/client/src/public/schemas/下的配置 JSON Schema 是自动生成的生成命令npm run website-generate-schema对应 website/client/scripts/generateSchema.tsCI 会在合并到main分支后重新生成绝不手工编辑该目录下的 Schema 文件否则下次生成会被覆盖且可能造成漂移。2. 面向用户的变更必须更新全部 15 种语言的文档任何面向用户的选项或功能变更都要同步更新website/client/src/下全部 15 个语言目录的文档而不仅是en只更新英文文档会被视为不完整变更这也是该国际化项目对贡献者的基本要求。3. 根目录 lint 不检查网站客户端类型根目录npm run lint的lint-ts步骤不包含对website/client的类型检查修改website/client后需要在该目录下单独运行npm run docs:build验证。4. VitePress 不校验页内锚点链接VitePress 构建时不会验证页内锚点链接in-page anchor links是否有效当重命名某个标题heading时必须手动搜索文档中对旧锚点的引用并同步更新否则会产生失效链接。5. GitHub Actions 必须固定到完整 SHAGitHub Actions 步骤必须固定到完整的 commit SHA并附带版本注释例如uses: actions/checkoutsha # v7.0.0CI 中由 pinact 和 zizmor 强制校验此规则短引用如v7或main会被拦截。提交信息规范Conventional Commits提交信息遵循 Conventional Commits 规范格式为type(scope): Description例如feat(cli): Add new --no-progress flag具体要求Scope作用域标注受影响区域如cli、core、website、security等Description描述清晰、简洁使用现在时态首字母大写提交正文遵循contextual-commitskill见.claude/skills/contextual-commit/SKILL.md仓库中位于 .agents/skills/contextual-commit/SKILL.md的指导写出有上下文的提交说明。Pull Request 指南规范要求的 PR 流程要点如下遵循 PR 模板仓库根目录存在 .github/pull_request_template.md模板要求填写变更摘要并勾选运行npm run test与运行npm run lint两项检查在 PR 顶部附上清晰的变更摘要使用#issue-number引用相关 Issue合并策略同一区域内小而相关的变更应合并为一个 PR而非拆成多个碎片 PR——这与文件 250 行信号的内聚性思想一脉相承。依赖注入与测试deps 参数模式这是 Repomix 测试策略的核心模式规范给出了明确的代码范式export const functionName async ( param1: Type1, param2: Type2, deps { defaultFunction1, defaultFunction2, } ) { // 使用 deps.defaultFunction1() 而非直接调用 };规则通过deps对象参数注入依赖以获得可测试性测试时通过向deps对象传入测试替身test doubles来 mock 依赖仅当依赖注入不可行时才使用vi.mock()。这一模式在源码中得到了广泛应用。以 src/core/file/fileCollect.ts 为例collectFiles函数将readRawFile作为deps的默认依赖注入export const collectFiles async ( filePaths: string[], rootDir: string, config: RepomixConfigMerged, progressCallback: RepomixProgressCallback () {}, deps { readRawFile: defaultReadRawFile, }, ): PromiseFileCollectResults {对应的测试 tests/core/file/fileCollect.test.ts 则通过传入readRawFile: mockReadRawFile的方式注入 mock文件中第 25、53、75、102、123、141 行等处多次出现该用法并验证自定义maxFileSize等行为第 110 行注释// Verify readRawFile is called with custom maxFileSize完全不需要vi.mock的全局干预。除fileCollect.ts外这一模式还广泛存在于src/core/git/下的 git 相关模块如gitCommand.ts、gitDiffHandle.ts、gitLogHandle.ts、src/core/security/securityCheck.ts、src/core/packager/produceOutput.ts等核心模块中。从源码结构看deps注入已成为 Repomix 实现单元测试的主要手段新增功能时沿用此模式可以最大限度保证测试的隔离性与可维护性。输出生成原则规范最后对输出提出了两条产品级原则除非另有说明否则包含全部内容不做缩写——Repomix 的打包输出默认保留完整内容保证喂给 LLM 的信息不丢失在保持输出质量的同时为大型代码库场景做优化——这是 Repomix 处理大规模仓库时的核心性能诉求与 README.md 中AI-Optimized的特性定位一致。总结.agents/rules/base.md虽篇幅不长却是参与 Repomix 开发不可绕过的入场须知。它回答了几个关键问题代码放在哪里、风格如何统一、哪些规则容易踩坑、提交与 PR 怎么写、测试依赖如何组织。理解并遵守这些约定无论是人类开发者还是代码 Agent都能在 Repomix 代码库中高效、合规地工作。【免费下载链接】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），仅供参考