后端前端开发工具【免费下载链接】compiler-explorerRun compilers interactively from your web browser and interact with the assembly项目地址https://gitcode.com/gh_mirrors/co/compiler-explorer点击查看免费下载本篇指南以仓库根目录 AGENTS.md 为核心骨架系统讲解 Compiler ExplorerCE在浏览器中交互式运行编译器并查看汇编输出的开源项目为 AI Agent 与协作者制定的构建/测试命令、提交流程、代码风格、前后端分层约束以及编译工作线程SQS Compilation Worker模式、CE Properties Wizard 配置管理等关键实现。读完本文你将掌握该仓库的本地开发全流程、质量门禁的正确用法并深入理解编译任务如何通过 SQS 队列与 WebSocket 在独立工作线程中完成流水线化处理。一、AGENTS.md 在仓库中的定位AGENTS.md 是 Compiler Explorer 面向 AI Agent 的协作规范文件与常规的 README 或 CONTRIBUTING 文档定位不同它直接回答了「当 Agent 需要在本仓库修改代码时应当如何构建、测试、提交以及必须遵守哪些架构约束」这一核心问题。文档明确说明其目的是 provides guidance to AI Agents when working with code in this repository为在本仓库中协作的 AI Agent 提供指引。其内容覆盖面包括五个维度构建与测试命令从开发模式到生产构建的完整命令矩阵提交流程要求pre-commit 钩子、类型检查、lint 与测试的强制顺序代码风格与注释规范TypeScript 严格模式、ES5 编译约束、注释的「只解释为什么」原则架构红线前端static/禁止导入后端lib/代码由钩子强制校验高级主题SQS 编译工作线程模式、CE Properties Wizard、属性文件验证、Vitest 测试策略。下文将逐条展开并结合仓库源码给出底层实现证据。二、构建与测试命令矩阵2.1 本地开发与生产构建AGENTS.md 给出的核心命令与 package.json 中定义的 npm scripts 一一对应用途命令底层实现生产构建 启动npm run webpack/npm startwebpack调用 webpack.config.esm.tsstart会先执行 webpack 构建再以NODE_ENVLOCAL启动 app.ts开发模式热重载make devMakefile 中通过tsx watch监听文件变化并自动重启GPU 开发模式make gpu-dev与dev相同但追加--env gpu参数启动 GPU 专属环境调试模式npm run debug/make debug以--inspect打开调试端口9229完整检查make pre-commit或npm run check见下文「提交流程」一节从 Makefile 看make dev的实际行为是dev: prereqs ## Runs the site as a developer; including live reload support and installation of git hooks NODE_OPTIONS$(TS_NODE_ARGS) $(NODE_ARGS) ./node_modules/.bin/tsx watch $(FILEWATCHER_ARGS) ./app.ts $(EXTRA_ARGS)其中FILEWATCHER_ARGS包含--watch --include etc/config/*即开发模式下修改etc/config/下的属性配置也会触发重启这对调试编译器配置非常实用。2.2 静态检查与类型检查Lintnpm run lint使用 Biome 执行自动修复biome check . --writenpm run lint-check仅检查不修改。Biome 配置见 biome.json。类型检查npm run ts-check通过npm-run-all并行执行五个 TypeScript 工程的无输出编译检查--noEmitts-check:backend→ tsconfig.backend.jsonts-check:frontend→ tsconfig.frontend.jsonts-check:tests→ tsconfig.tests.jsonts-check:frontend-tests→ tsconfig.frontend.tests.jsonts-check:cypress→ cypress/tsconfig.json2.3 单元测试与 E2E 测试全部测试npm run test即vitest run包含昂贵测试如 filters 相关用例。最小测试集npm run test-min等价于cross-env SKIP_EXPENSIVE_TESTStrue vitest run跳过标记为 expensive 的测试套件。单文件测试npm run test -- --run base-compiler-tests.ts对应仓库 test/base-compiler-tests.ts。按名称模式过滤npm run test -- -t should handle execution failures-t是 Vitest 的 test name pattern 参数。覆盖率npm run test-coveragevitest run --coverage。Cypress E2Enpm run cypress测试用例位于 cypress/e2e覆盖编译、diff、embed、execute、多编译器对比等前端核心交互。关于「昂贵测试」的标记方式AGENTS.md 给出了明确的代码模板describe.skipIf(process.env.SKIP_EXPENSIVE_TESTS true)(Test suite, () {...})三、提交流程与质量门禁Workflow Requirements3.1 严禁事项AGENTS.md 用醒目的 ⚠️ 列出三条硬性红线绝不绕过 pre-commit 钩子禁止使用git commit -n或--no-verify禁止改写历史禁止git commit --amend、git push --force与--force-with-lease提交信息中禁止包含共享链接例如/z/、/e#、/clientstate/以及完整的 godbolt.org 短链接。这类链接用于共享编译器状态进入提交历史会造成噪音。3.2 标准提交流程文档要求的完整流程固定为五个步骤修改代码npm run ts-check验证 TypeScript 类型npm run lint自动修复风格问题npm run test验证功能最低要求是npm run test-min只有全部通过后才允许使用不带任何 flag 的git commit提交。make pre-commit在 Makefile 中的定义为pre-commit: $(NODE_MODULES) test-min lint check-frontend-imports check-license-headersnpm run check则串起五道关卡ts-check lint-check check-frontend-imports check-license-headers test-min。此外仓库还配置了 husky 与 lint-staged.config.mjspre-commit 钩子会用vitest related只运行与本次改动文件相关的测试。3.3 许可证头检查npm run check-license-headers调用 etc/scripts/check-license-headers.js确保每个源文件都带有 BSD-2-Clause 许可证横幅——这也是仓库中几乎所有.ts文件顶部都有大段版权注释的原因。四、代码风格与注释规范4.1 TypeScript 风格基线严格类型禁止implicit any禁止未使用的局部变量缩进 4 空格行宽 120 字符字符串使用单引号优先const/let不用var工具函数统一使用 Underscore.js见 package.json 中underscore依赖更新或新增代码时使用现代 TypeScript 特性如可选链 optional chaining新代码中的拼写偏好使用英式英语如initialise、colour但仅作为偏好而非硬性要求。4.2 前端 ES5 编译约束文档特别强调客户端代码会被 TypeScript 编译为 ES5 JavaScript因此即使实际文件是blah.tsimport 时也必须写blah.js。这是使用该仓库时最容易踩的坑——所有static/目录下的前端代码如 static/main.ts在导入同级或子模块时均以.js结尾。4.3 注释哲学AGENTS.md 对注释的立场非常鲜明注释应提供额外上下文或解释「为什么」而不是复述「做了什么」。具体三条铁律不要在自解释代码上方加注释例如// Initialises the thing initialiseThing();这类注释被明确禁止。不要写仅仅重复函数名的冗余头注释例如/** * Sets up compiler change handling */ function setupCompilerChangeHandling() {...}函数名已经表达了含义头注释没有增量信息。不要用注释叙述改动历史、修复的 bug或警告你「刻意没写」的代码。这些理由应属于 commit/PR/issue回归防护应体现在测试里。4.4 其他约定import 必须始终置于文件顶部绝不放函数或方法内部除非万不得已且需先确认为新增的 server 端组件编写测试文档统一放在 docs/ 目录特别是 RESTful API 若有变更必须同步更新文档在合适的地方提出代码质量改进建议尽量 DRY。五、前后端架构分层约束5.1 架构红线static/ 不得导入 lib/AGENTS.md 明确指出前后端分离原则前端代码static/严禁导入后端代码lib/前端应通过 API 调用与后端通信共享类型从types/目录导入例如 types/compiler.interfaces.ts、types/compilation/compilation.interfaces.ts该约束由 pre-commit 钩子npm run check-frontend-imports强制。5.2 实现机制etc/scripts/check-frontend-imports.js 的实现非常简洁用git grep在static/*.ts与static/**/*.ts中搜索from ../.../lib/形式的导入路径一旦命中立即以非零退出码报错const violations execSync( git grep -n from [\\\\]\\.\\./.*lib/ -- static/*.ts static/**/*.ts, {encoding: utf8} ).trim();git grep在无匹配时返回状态码 1脚本将其视为「通过」其余非零状态码才会触发失败。违反该约束会导致构建失败、提交被阻断。之所以用git grep而非普通文件搜索是因为它天然只追踪版本库内的文件不受node_modules等无关目录干扰。六、安全评审校准Security Review CalibrationAGENTS.md 对安全评审给出了一套务实的优先级划分避免把精力浪费在错误的方向上低风险面CE 内部自控的端点如 conan 库服务器不视为敌对输入。针对其内容构造的加固视为卫生问题hygiene小修复直接内联处理大问题提交为 follow-up issue不阻塞 PR。真正的高风险面用户提交的源代码与编译输出生产环境通过 nsjail 沙箱与/nosym/tmp的 nosymfollow 挂载来防护。相关配置见 etc/nsjail/compilers-and-tools.cfg 与 etc/nsjail/user-execution.cfg。优先级排序健壮性故障promise 永不 settle、挂起、资源泄漏优先于精心构造的输入场景——前者曾造成真实故障issue #8811。七、编译工作线程模式Worker Mode Configuration这是 AGENTS.md 中技术含量最高的一节描述了一项将编译任务卸载到独立工作线程实例的新特性与既有的执行execution工作线程对称。其核心实现位于 lib/compilation/sqs-compilation-queue.ts。7.1 配置参数配置项含义默认值 / 说明compilequeue.is_workertrue启用编译工作线程模式类似 execution workerscompilequeue.queue_url编译请求的 SQS 队列 URL普通编译与 CMake 共用必填缺失会直接抛错compilequeue.events_url发送编译结果的 WebSocket URL与execqueue.events_url互为兜底compilequeue.worker_threads2并发工作线程数默认 2compilequeue.poll_interval_ms1000处理完成或出错后两次轮询的间隔文档默认 1000ms注意 SQS 长轮询意味着队列为空时实际等待最长 20 秒--instance-color color可选的命令行参数用于区分部署实例指定 blue/green 时会把队列名改写为带颜色后缀的形式7.2 实例颜色机制从源码 lib/compilation/sqs-compilation-queue.ts 可以看到instanceColor通过字符串替换改写队列 URLqueue_url queue_url.replace( -compilation-queue.fifo, -compilation-queue-${appArgs.instanceColor}.fifo, );例如staging-compilation-queue.fifo会变为staging-compilation-queue-blue.fifo。这意味着蓝绿部署的两套实例可以各自消费专属队列互不抢占。相关命令行参数解析见 lib/app/cli.ts。7.3 队列架构与消息格式单一 SQS FIFO 队列保证消息的有序与可靠投递消息内含isCMake标志新版本演进为更通用的buildSystem字段来区分编译类型。共享解析逻辑公共请求解析工具位于 lib/compilation/compilation-request-parser.tsWeb 处理器与 SQS 工作线程复用同一套解析函数parseUserArguments、parseExecutionParameters、parseTools、parseFilters保证两条路径行为一致。生产者位于仓库之外队列消息由外部 Lambda 函数产生主 CE 服务器只负责消费不承担生产职责。关于buildSystem与isCMake的兼容处理源码中有段精辟的注释sqs-compilation-queue.ts不认识的名字不等于没有名字——生产者可能跨部署领先于工作线程把cargo误读为普通单文件编译会导致把项目清单当源码编译、返回一堆语法错误。因此getRequestedBuildSystem对未知构建系统直接抛错让用户看到「编译失败并指名构建系统」与 HTTP 路由行为一致。7.4 S3 溢出支持SQS 消息体有 256KB 的大小上限超过上限的大型编译请求被自动转存 S3超限消息存入 S3 桶compiler-explorer-sqs-overflowSQS 收到的是一个轻量的引用消息类型为s3-overflow内含 S3 位置bucket/key、originalSize与timestamp工作线程通过isS3OverflowMessage识别此类消息sqs-compilation-queue.ts再调用fetchFromS3取回完整请求并据消息的SentTimestamp计算排队时长queueTimeMsS3 对象由生命周期策略在 1 天后自动删除。7.5 结果投递WebSocket 持久连接结果通过PersistentEventsSender实现在 lib/execution/events-websocket.ts以 WebSocket 长连接回传相比短连接显著提升性能。投递逻辑有两点值得注意背压保护doOneCompilation在persistentSender.isReadyForNewMessages()返回 falseWebSocket 未就绪或存在待确认消息时会跳过本次拉取避免积压。大结果降级当结果含s3Key且序列化后超过WEBSOCKET_SIZE_THRESHOLD31KiB 级别时只通过 WebSocket 发送轻量引用s3KeyokToCacheexecTime完整结果由前端凭s3Key从 S3 按需获取。同时s3Key会在发送给用户前从 API 响应中移除。7.6 远程编译器代理工作线程自动检测请求中的远程编译器引用并代理到对应远端通过 HTTP 转发保持与既有远程编译器基础设施的兼容。7.7 指标与统计SQS 工作线程维护独立的 Prometheus 计数器sqs-compilation-queue.tsce_sqs_compilations_total/ce_sqs_executions_totalce_sqs_cmake_compilations_total/ce_sqs_cmake_executions_totalce_sqs_project_build_compilations_total/ce_sqs_project_build_executions_total带build_system标签同时通过statsNoter.noteCompilation记录编译统计供 Grafana 监控与常规 API 路由的行为保持一致。工作线程还响应SIGINT/SIGTERM优雅关闭 WebSocket 连接sqs-compilation-queue.ts。八、配置管理CE Properties Wizard 与属性校验8.1 CE Properties Wizard位置在 etc/scripts/ce-properties-wizard是一个交互式 CLI 工具用于向本地 CE 安装添加自定义编译器。其独立 READMEetc/scripts/ce-properties-wizard/README.md与 AGENTS.md 的描述互为印证。运行方式需要 Python 3.10 与 uv运行脚本自动处理环境# Linux/macOS ./run.sh /usr/local/bin/g-13 --yes # Windows PowerShell .\run.ps1 C:\MinGW\bin\g.exe --yes完整自动化示例./run.sh /path/to/compiler \ --id custom-gcc-13 \ --name GCC 13.2.0 \ --group gcc \ --options -stdc20 \ --language c \ --yes主要命令行选项COMPILER_PATH可执行文件路径、--id、--name、--group、--options、--language、--yes/-y、--non-interactive、--config-dir、--verify-only只探测不修改、--list-types、--reorganize LANGUAGE、--validate-discovery、--env ENV默认 local、--sdk-pathMSVC 的 Windows SDK 基路径。MSVC 自动配置是 wizard 的一大亮点Demangler自动检测 MSVC 安装目录中的undname.exe按编译器架构x64/x86/arm64匹配路径写入demanglerTypewin32与demanglerpathObjdumper发现llvm-objdump.exe时自动写入objdumperTypellvmSDK 集成--sdk-path指定 Windows SDK 路径后自动配置 MSVC 的 include/library 路径。自动发现./auto_discover_compilers.py --dry-run预览、--languages c,rust限定语言、--yes自动添加 PATH 中的全部编译器。安全操作wizard 只新增/更新配置、绝不删除既有内容修改etc/config/language.local.properties前会创建备份并保证编译器 ID 唯一。其核心 Python 模块包括compiler_detector.py探测编译器类型、config_manager.py配置读写、surgical_editor.py保留格式的精修改写等。8.2 属性文件验证Properties Validation修改任何.properties文件后应运行npm run test:props即vitest run --reporterdot properties-validation-tests.ts检查重复键、错误配置等问题。实现位于 lib/properties-validator.ts测试位于 test/properties-validation-tests.ts。验证器采用「原始文件校验 语义校验」双模式能发现的问题类型包括重复键duplicate keys与compilers.复数拼写错误typo空列表元素如compilers::或尾部裸冒号孤立引用在compilers列表中声明但没有对应compiler.X.exe定义的编译器以及反向的「有 exe 定义但未列入列表」formatter、tool、lib 及其版本同理重复的编译器/分组引用同一 ID 在列表中出现两次可疑路径compiler.X.exe路径不在/opt/compiler-explorer或Z:/compilers前缀下/usr/bin/ldd等白名单系统路径除外时被标记无效默认编译器defaultCompiler引用了未列入compilers的 ID缺失 compilers 列表语言类文件定义了编译器却没有compilers或分组定义跨文件重复编译器 IDvalidateCrossFileCompilerIds检查同一编译器 ID 在多个文件中被重复定义。Disabled:注释如# Disabled: gcc-13会被解析为禁用 ID 集合通过filterDisabled从校验结果中过滤掉这些条目避免误报。九、测试编写指南Testing Guidelines9.1 单元测试规范使用 Vitest兼容 Jest 语法测试位于 test/ 目录命名与源文件对应用vi.spyOn()做依赖 mock结构遵循describe/it模式测试名要有描述性复杂文件按功能而非按方法组织测试用beforeEach/afterEach管理环境测试结束后用vi.restoreAllMocks()恢复成功与错误路径都要覆盖。9.2 编译器测试要点测试文件 I/O 时 mock 文件系统用makeFakeCompilerInfo()创建测试用编译器配置、makeCompilationEnvironment()创建测试环境mockexec调用来测试编译与执行逻辑BaseCompiler 的测试工具来自 test/utils.js断言尽量平台无关聚焦行为而非实现细节。9.3 跨平台Windows注意事项Windows 路径处理是常见陷阱处理方式三选一直接跳过if (process.platform win32) return;写平台特定断言使用与路径无关的检查。9.4 昂贵测试跳过机制SKIP_EXPENSIVE_TESTStrue环境变量会跳过昂贵测试如 filter 测试。pre-commit 钩子用vitest related只跑与改动文件相关的测试npm run test-min等价于开启该变量运行npm run test则包含全部昂贵测试。标记方式为describe.skipIf(process.env.SKIP_EXPENSIVE_TESTS true)(Test suite, () {...})十、实践建议Agent 在本仓库的高效协作路径综合 AGENTS.md 全文可以将 Agent 在本仓库的协作流程浓缩为一条可执行路径改前确认先阅读 CONTRIBUTING.md 与 docs/README.md理解项目定位前端改动遵循「不 importlib/」红线共享类型走 types/。改中守则import 置顶、单引号、4 空格缩进、ES5 兼容.js后缀导入、注释只写「为什么」新 server 组件必配测试。改后验证依次执行npm run ts-check→npm run lint→npm run test-min条件允许跑全量npm run test改动.properties加跑npm run test:props涉及前端再加npm run check-frontend-imports。提交使用无 flag 的git commit提交信息不含共享短链接需要完整校验时直接make pre-commit。涉及编译基础设施若改动与 SQS 编译工作线程相关重点回归 lib/compilation/sqs-compilation-queue.ts 配套的 WebSocket 投递、S3 溢出与指标统计路径并在配置中验证compilequeue.*参数。上述规范与实现共同构成了 Compiler Explorer 可被 AI Agent 安全、高效协作的工程底座既有清晰可执行的命令与流程又有源码级的强制校验与架构约束兜底是大型开源仓库面向自动化协作的范本。赞分享后端前端开发工具【免费下载链接】compiler-explorerRun compilers interactively from your web browser and interact with the assembly项目地址https://gitcode.com/gh_mirrors/co/compiler-explorer点击查看免费下载相关推荐Gatus 仓库开发指南面向 AI 编码 Agent 的工程协作规范与源码架构解析Gatus 仓库开发指南面向 AI 编码 Agent 的工程协作规范与源码架构解析 本指南以 Gatus 仓库根目录的 AGENTS.md https://l后端健康检查告警Rerun 仓库开发协作指南面向 LLM/Agent 的构建、代码生成、测试与架构全流程Rerun 仓库开发协作指南面向 LLM/Agent 的构建、代码生成、测试与架构全流程 本文基于 Rerun 仓库根目录的 AGENTS.md https:数据可视化3D渲染数据分析Continue CLI 开发指南面向 AI 协作的工程架构、构建测试体系与 Agent 规范Continue CLI 开发指南面向 AI 协作的工程架构、构建测试体系与 Agent 规范 extensions/cli/AGENTS.md 是 Cont人工智能AI Agent代码智能体开发工具工具调用RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考