企业官网建设流程全解析

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），本文接下来即围绕它展开。

仓库布局：按功能组织，测试与源码一一镜像

规范文档给出了清晰的顶层结构划分，实际仓库内容与之完全吻合：

实践要点：

• 新增功能代码时，请遵循"功能化目录结构"（feature-based structure）的设计，避免功能之间产生不必要的依赖，保持模块边界清晰。
• 新增功能必须同步在tests/下建立对应的测试文件，保持目录结构镜像关系，便于快速定位测试。
• 文档变更涉及面向用户的功能时，需要同时更新全部 15 个语言目录下的文档，而不仅是英文（详见下文"陷阱"部分）。

编码规范：Biome 强制 + 单一职责

遵循 Biome 配置

规范要求遵循项目由biome.json强制执行的编码标准。查看仓库根目录的 biome.json，可以发现具体规则：

• 格式化风格：使用空格缩进，缩进宽度为 2，行宽上限 120 字符；
• JavaScript 风格：单引号（quoteStyle: "single"）、尾随逗号（trailingCommas: "all"）、始终加分号（semicolons: "always"）；
• Linter：启用推荐规则集（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-biome（biome check --write）、lint-oxlint（oxlint --fix）、lint-ts（tsc --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.ts）；
• CI 会在合并到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 必须固定到完整 SHA

• GitHub Actions 步骤必须固定到完整的 commit SHA，并附带版本注释，例如uses: actions/checkout@<sha> # v7.0.0；
• CI 中由 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, }, ): Promise<FileCollectResults> => {

对应的测试 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 实现单元测试的主要手段，新增功能时沿用此模式可以最大限度保证测试的隔离性与可维护性。

输出生成原则

规范最后对"输出"提出了两条产品级原则：

1. 除非另有说明，否则包含全部内容，不做缩写——Repomix 的打包输出默认保留完整内容，保证喂给 LLM 的信息不丢失；
2. 在保持输出质量的同时，为大型代码库场景做优化——这是 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