企业官网建设流程全解析

Repomix 跨平台代码审查指南：让 Node.js CLI 在 Windows、macOS、Linux 上行为一致

【免费下载链接】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、Plain Text）的 Node.js CLI 工具，其核心功能——文件收集、忽略规则解析、路径处理与输出写入——每一步都依赖文件系统语义，因此天然暴露在三套操作系统差异之下。本文基于仓库内 reviewer-cross-platform.md 这一专职跨平台审查 Agent 的完整规范，系统讲解 Repomix 团队如何审查代码变更中的跨平台隐患：包括四级严重性体系、八大关注领域（路径分隔符、Glob 模式、大小写敏感、Windows 专属文件系统规则、子进程与 Shell、空格路径、CRLF 行尾、环境变量与 OS API）、结构化审查报告格式，以及每条规则背后对应的源码实现与真实事故（issue #1765）。读完你可以直接把这套审查清单用于任何 Node.js 跨平台项目的 code review。

为什么跨平台审查是 Repomix 的一等公民

Repomix 面向所有开发者的本地仓库打包场景，用户在 Windows、macOS、Linux 上运行完全相同的命令。src/core/file/fileSearch.ts中文件搜索、忽略规则、输出路径的处理一旦在某个平台出错，会直接表现为"打包漏文件、路径被改坏、输出文件无法生成"这类用户可见故障。

这份审查规范的开篇明确了一个残酷事实：这个项目真实发布过仅 Windows 触发的 bug——当.gitignore规则中包含反斜杠时，globby在 Windows 上崩溃（issue #1765）。因此规范要求审查者"把 Windows 当作一等目标平台，而不是事后补丁"，而非仅靠 Linux CI 绿灯就放行变更。

审查者角色与工作协议

该文档定义了专职的跨平台审查 Agent（model: sonnet，描述为 "Review code changes for cross-platform (Windows/macOS/Linux) hazards"）。其工作协议有三条核心约束：

• 全量上报，不做预筛：分析传入的 diff，报告每一个有具体证据的发现，每条都标注严重性和置信度。不筛除边缘发现——编排器（orchestrator）会做最终裁决并丢弃不同意的项；你压掉一条发现就是永久丢失，而被拒收一条只损失一行输出。
• 严格遵守范围限制：只报告平台可移植性问题（见八大关注领域），绝不虚构风险。
• 结合兄弟审查者分工：仓库内还有 reviewer-code-quality.md（逻辑错误、异步并发、资源管理）、reviewer-holistic.md（架构契合、变更影响、跨模块连锁反应）等专职审查者，跨平台审查者只负责平台维度，避免重复劳动。

四级严重性体系

所有发现按影响分级，从"必须合并前修复"到"可改可不改"：

分级的关键判断维度是可达性（见后文）：命中所有用户的缺陷（文件收集、忽略处理、输出写入）比命中测试辅助函数的缺陷严重得多。

八大关注领域详解

1. 路径构造与分隔符（Path Construction and Separators）

这是最核心也最容易出错的领域。规范要求：

• 禁止在路径拼接/拆分处硬编码/或\\，必须用path.join()、path.resolve()、path.sep。
• 禁止对路径做字符串手术（split('/')、replace(/\//g, ...)、startsWith('/')），应使用path.relative()、path.parse()、path.isAbsolute()。
• 区分path.posix（用于 glob 模式与序列化路径值，需正斜杠）与默认path（用于文件系统调用）。特别注明：path.posix.normalize()不会转换反斜杠；构建 glob 模式时应使用 fast-glob 的convertPathToPattern()（它同时转义 glob 元字符，因此不能用于序列化/展示路径——那些场景只需做普通的分隔符替换）。
• 用===比较路径前必须先归一化分隔符；只有在明确针对大小写不敏感文件系统时才做大小写折叠——在 Linux 上无条件折叠会错误合并两个仅大小写不同的文件。
• 盘符（C:\）、盘符相对路径（C:foo）、UNC 路径（\\server\share）会破坏路径穿越防护这类前缀检查。

源码佐证：src/core/file/fileSearch.ts中定义了toPosixPath = (value) => value.replace(/\\/g, '/')，用于把输出文件路径转为 POSIX 形式加入 globby 的 ignore 模式（见getIgnorePatterns中对config.output.filePath的处理），并附注释说明原因：globby 用正斜杠路径匹配 ignore 模式，Windows 上若输出路径保持docs\out.xml就会无法自我忽略输出文件。这是文档规则"glob 模式需正斜杠"的典型实现实例。

2. Glob 模式（globby / picomatch / fast-glob）

• Windows 原生路径不能直接当作 glob 模式传给globby/picomatch：在 glob 语法中\是转义字符而非分隔符，模式必须先转成正斜杠。
• 用户提供的忽略规则（.gitignore、.repomixignore、--ignore）中的反斜杠是合法的 gitignore 转义语法，应原样保留给忽略文件 API，而不是剥离——这类匹配器缺陷正是 issue #1765 的成因（一个 globby 回归，上游已修复）。
• Windows 上绝对路径作为 glob 模式时，盘符模式需要 fast-glob 的convertPathToPattern()。注意：原生路径cwd+ POSIX 模式是官方支持的标准用法，不应误报。
• 不要假设 globby 返回的结果使用原生分隔符（它们实际上是 POSIX 形式）。

源码佐证：src/core/file/fileSearch.ts的escapeGlobPattern先转义反斜杠（/\\/g→\\\\）再转义()、[]（但不转义{}），用于处理含括号的路径（如src/(categories)→src/\(categories\)）；normalizeGlobPattern统一目录模式结尾斜杠行为，让**/folder、**/folder/、**/folder/**/*行为一致。这些都是在"给 globby 喂模式之前"完成的归一化。

测试佐证：fileSearch.gitignoreBackslash.test.ts 是 #1765 的回归测试，明确注释"The reported crash ('path should be apath.relative()d string') comes out of the ignore package's path validation and reproduces on Windows only, which is why these tests matter most on the windows-latest CI leg"。测试覆盖三种场景：根.gitignore含\.\NUL、嵌套.gitignore含\*.pid.lock、以及 contenteditable="false">【免费下载链接】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