后端【免费下载链接】passengerA fast and robust web server and application server for Ruby, Python and Node.js项目地址https://gitcode.com/gh_mirrors/pa/passenger点击查看免费下载Phusion Passenger 仓库根目录下的 AGENTS.md 是官方为 AI Agent以及人类开发者准备的“工作前必读”规范它规定了动手前的文档阅读顺序、编码与注释策略、C 专属安全约定、测试原则、文档写作原则以及 commit/PR 消息、Changelog 和升级escalation政策。读完本文你将掌握在这套以 C14 和 Ruby 为主的代码库中如何做出“外科手术式”修改、如何遵守其 oxt 系统调用与临时文件安全约定以及如何写出符合该仓库审美的提交信息与变更日志条目。动手前先读哪些文档AGENTS.md 开宗明义这是 Phusion Passenger 应用服务器application server的代码库主体语言是C14 和 Ruby。它要求任何工作在开始前先做两件事阅读 doc/DevHandbook.md 的目录找到与任务相关的内部开发文档并按需精读阅读 doc/BasicArchitectureOverview.md 获取基础架构知识帮助确定研究方向。从 doc/DevHandbook.md 的实际内容可以看到这份手册按主题组织了完整的文档索引基础篇开发环境搭建doc/DevEnvironmentSetup.md、构建系统doc/BuildSystem.md与构建缓存doc/BuildCaching.md、运行测试doc/RunningTests.md、编写 C 测试doc/WritingCxxTests.md与 C mock 策略doc/CxxMockingStrategy.md最佳实践篇C 编码技巧与常见陷阱doc/CodingTipsAndPitfalls.md、临时文件安全处理doc/SecureTempFileHandling.md设计决策篇有限的 gem 依赖策略doc/DesignAspects/LimitedGemDependencies.md、Ruby loader 初始化阶段不激活 gemdoc/DesignAspects/NoGemActivationDuringRubyLoaderInitialization.mdC 子系统篇ConfigKit、SpawningKit、Wrapper registry 等核心子系统的 README。也就是说AGENTS.md 扮演的是“入口路由器”的角色它自己不重复这些文档的内容而是规定你先查地图再进迷宫。编码准则优先无聊而显式的代码AGENTS.md 的 “Coding guidelines” 部分给出了一组相当具体的风格要求优先简单显式而非聪明或过早抽象让主代码路径易于跟随、聚焦业务逻辑把掩盖主流程的次要技术细节移入 helper。允许一定程度的重复只有在共享抽象能明显提升可读性或消除大量重复时才提取避免推测式泛化。外科手术式修改surgical changes改动严格限定在请求的结果范围内不做无关的清理、重构、格式化或风格修改为实现清晰或可读性可以自主做低风险的重构并删除因本次改动而过时的代码除非有充分理由否则遵循项目现有惯例不要动无关的既有问题把“值得注意的”问题报告出来但不让它阻塞当前任务。正确的错误处理Shell 脚本使用pipefail忽略错误时只忽略特定的错误不要一刀切地吞掉所有错误。注释策略这是全文中最细的一节值得逐条拆解注释代码本身表达不出来的非显然信息目的、领域术语、职责、输入输出语义、算法阶段、不变量、注意事项和决策。复杂算法用高层视角解释帮助人类阅读对非显然的类/模块/方法职责做简短说明把注释放在该信息真正适用的位置。面向“有能力但对该子系统或平台是新人”的贡献者写作用自然平实的语言恰当使用精确术语首次出现的不熟悉概念要定义并解释它与邻近代码的关系不要指望读者从机制或调用点自行反推含义。先讲目的或约束再讲机制。注释保持短小、贴近局部更宏观或跨切面的理由/注意事项放进开发者手册不要对显而易见的代码进行流水账式叙述。收尾前做一次最终验证重新读一遍需求检查完整 diff运行合适的测试/检查寻找漏掉的 Requirements、错误假设、规范违反、相关边缘情况、回归或多余改动发现具体问题就修复必要时重复受影响的检查保留正确的代码不要为了改而改。这套准则的整体取向是“降低认知负担、控制变更半径”后文的 commit 消息规范见下文其实是同一理念的延伸。C 专属约定用对内部工具库AGENTS.md 单独为 C 设了一节核心是“优先使用内部工具库”并点名了三个落点优先使用 oxt 的系统调用封装例如用oxt::open而非直接调系统调用如果没有现成封装就要循环重试直到不再遇到EINTR。查这三类头文件找现成工具Utils.h通用工具、IOUtils.hI/O、FileTools/*.h文件操作。优先用FileDescriptor或safelyClose()代替裸的close()。安全意识参考 doc/SecureTempFileHandling.md读文件优先用safeReadFile()。仓库源码可以逐条印证这些约定。先看 oxt——oxt是 “OS eXtensions for boosT”即对 Boost 的操作系统层扩展。src/cxx_supportlib/oxt/system_calls.hpp 的注释说明了封装带来的两大能力阻塞系统调用的可中断性和随机失败模拟。其工作方式与 AGENTS.md 的要求直接对应必须先调用oxt::setup_syscall_interruption_support()之后oxt::syscalls中的函数可以作为系统调用/C 库函数的 drop-in 替身被中断时抛出boost::thread_interrupted异常而不是返回EINTR错误——这正是“优先 oxt 封装而非直接 syscall”的原因封装替你把 EINTR 处理掉了。官方明确警告不要用boost::thread::interrupt因为它不把系统调用当作中断点应当用oxt::thread::interrupt()/interrupt_and_join()。实现上通过向特定线程发送信号推荐oxt::INTERRUPTION_SIGNAL即SIGUSR1来中断阻塞调用。注意 SIGUSR2 被 Valgrind 保留。还有一句直白的告诫system_calls.hpp“初始化支持函数被调用后发送信号会让系统调用以 EINTR 返回。oxt::syscall 会自动处理这件事但如果你绕过该命名空间直接调用系统调用就必须自己检查并处理 EINTR”——这就是 AGENTS.md 中“如果没有封装就循环到 EINTR 不再出现”这一条的底层依据。再看safeReadFile()。它在 src/cxx_supportlib/FileTools/FileManip.cpp 中实现声明位于 FileManip.h签名是pairstring, bool safeReadFile(int dirfd, const string basename, size_t maxSize)它通过dirfd basename的 fd 相对方式读取配合O_NOFOLLOW类标志以避免符号链接问题并受maxSize上限保护。同文件中的unsafeReadFile()注释也明确提醒读者参考safeReadFile()的安全检查文档FileManip.h。而它防的是哪一类攻击则由 doc/SecureTempFileHandling.md 完整给出临时文件名必须不可预测防 symlink 攻击、TOCTOU 竞态、file squatting甚至信息泄露与提权创建必须原子地完成“找空闲名 → 预留已存在则失败→ 收紧权限到如 0600”三步具体做法是用getSystemTempDir()、单文件用mkstemp()不要拿它建 Unix socket 这类非普通文件、目录或非普通文件用mkdtemp()以及“mktemp()是坏的”。测试原则按行为复杂度定测试规模AGENTS.md 的 “Testing principles”明确声明不适用于 shell 脚本与 Ansible有三条主线测试规模看行为复杂度、回归风险与故障影响不看 diff 大小。对 bug 修复以及并发/异步排序、状态机、重试/超时、协议、持久化、安全敏感代码等“顺序敏感或复杂”的改动要加“能真正证明该行为的最小聚焦回归覆盖”如果省略覆盖必须给出具体的理由。优先确定性测试。对异步/并发行为尽量控制调度、时钟、I/O 与故障注入而不是靠sleep或墙钟计时避免写“只是照抄实现”或重复已有覆盖的测试条件允许时对行为变更采用红/绿red/green测试尤其是 bug 修复。保持核心逻辑可独立测试隔离副作用和外部交互为可测试性做小规模低风险重构是允许的。如果有效覆盖需要大范围或有侵入的重构/架构改动不要悄悄扩大当前变更的范围——报告这一限制并建议作为后续工作除非“无法测试”让正确性留下实质性不确定否则继续完成请求的工作此时按升级政策处理。这些原则与仓库的测试文档形成呼应C 测试如何组织、fork 版 tut 框架如何工作见 doc/WritingCxxTests.mdmock 策略见 doc/CxxMockingStrategy.md各测试套件Ruby、Node.js、C/oxt、集成、打包如何运行、如何选组、调试器与 Valgrind 支持等见 doc/RunningTests.md。测试代码本身位于 test/ 下C 测试在 test/cxx/oxt 自身测试在 test/oxt/例如验证 syscall 中断行为的 syscall_interruption_test.cppRuby/Node 规格测试在 test/ruby/ 与 test/node/端到端集成测试在 test/integration_tests/。文档写作原则为“懂行但新来的人”写AGENTS.md 的 “Documentation principles” 对内部文档和用户文档分别设限总体文风自然、直接、平实的英语主语和动作要具体避免套路化开头和夸大的说法标题用 sentence case不限制行宽。内部开发文档写给“有能力但刚接触本代码库”的开发者先讲目的或约束再讲实现细节术语先引入再密集使用示例比解释更省时就用示例。只保留帮助读者“理解非显然设计、定位改动位置、做决策、避坑”的信息容易从代码和测试中恢复的实现细节、穷尽行为和小边缘情况留给代码和测试。用户文档聚焦公开的 setup、行为与限制省略内部实现和穷尽行为。组织结构围绕读者需要的“不同信息”组织内容而不是套模板只有确有实质且不同的信息才加小节反对每个主题例行地配 “What it is / Why it matters / How it works” 三段式。用标题帮助导航但不把紧密相关的材料切碎“结论”用于综合长而复杂的文档而不是重复前文。定稿前删掉一切对理解没有实质帮助的内容。这一节实际上是 doc/DevHandbook.md 各文档的写作标尺——手册自身在“写作指南”中也声明“使用 documentation principles”。Commit 与 PR 消息为人类评审者降负担AGENTS.md 明确由于使用 squash commitscommit 消息与 PR 消息被视为同一种东西且要“为人类评审者而写”应用文档写作原则但目标专门优化为减少理解和 review diff 所需的心智负担。要点包括在意图、行为、设计层面描述改动而不是代码机械细节。推断出的意图和设计必须落在请求、对话、测试、相关仓库历史以及与旧行为的对比上不要编造没有依据的动机也不要把未解决的意图不确定性写进消息当意图实质性不清楚时先查相关历史若聚焦研究仍不能解决“可能实质性改变消息表述”的歧义就问一个聚焦的问题否则写出“有最佳依据支撑的消息”。解释深度随 review 负担伸缩大跨度或概念宽的 diff先给评审者足够的上层背景——改了什么、主要部分如何拼合、预期看到什么小而自明的 diff除非有非显然背景否则不要冗余总结。纳入实质性帮助 review 的非显然信息先前问题或动机、设计决策与理由、研究发现或约束、权衡、注意事项、后果、有意义的验证或发布信息、需要特别关注的区域。但不要把它当清单硬凑。不要复述 diff、罗列文件或符号、枚举显而易见的编辑、加泛泛断言和填充语实现细节只在解释设计选择或权衡时提及避免贴“跑了哪些测试”的清单。标题要简洁用清楚描述“实际改动或结果”的主语而不是 “Fix X” 之类的含糊标签。正文给到让 review 更容易为止不多不少避免僵硬模板。Changelog 条目面向用户的单句行为描述“Changelog entries” 一节把 changelog 定位为用户文档专门优化为“快速传达用户可见影响”从用户视角描述变化现在能做什么、什么行为变了、修好了什么问题优先可观察的行为/结果而非实现细节、内部架构或开发者理由。保持短。通常一句只有当用户需要额外信息理解影响、限制或必须采取的动作时才加。有助于用户判断“这事与我有关吗”的条件或受影响场景要写出来破坏性变更、默认值变化、兼容性影响、必须的用户动作必须显式声明。bug 修复写“修好了什么用户可见问题”而非内部成因改进写具体改进避免在可以精确描述时写“improved performance / improved reliability”这类泛泛断言。不包含实现机制、改动的文件或符号、测试、内部设计决策或评审背景除非与用户如何使用产品直接相关。若改动没有实质用户可见影响通常不要加 changelog 条目。仓库根目录的 CHANGELOG 即为该规范约束下的产物。开发者手册Dev Handbook的定位与更新义务AGENTS.md 把doc/下的一系列 Markdown 文件称为开发者手册并定义其双重目的教会“不了解本代码库的有能力的人类或 AI 开发者”代码库如何工作使其能有效贡献对 AI 而言手册就是一组“技能skills”索引充当技能路由器skill router。把重要的设计决策、理由与约束固化下来不让它们丢失或变成隐式知识。内容覆盖整体架构/流程、重要概念与约束、非显然的重要设计模式、重要或非显然的设计决策、重要子系统。写作规则还包括用 doc/DevHandbook.md 作“简洁、关键词丰富”的主题索引与技能路由器每个主要主题一份规范文档、每份文档一个主要主题——“主要”的判定标准是安全地改动它需要一套独立的心智模型有自己的概念、约束、失效模式、平台行为或变更理由仅有代码模块边界不构成文档边界。架构文档只作为“组件、主流程、系统级约束的地图”对子系统细节做摘要并链接到规范文档主题边界处只解释局部交互并给出链接不复制完整策略记录重要理由和非显然决策省略琐碎信息与用户文档/AGENTS.md/CONTRIBUTING.md 已覆盖的内容必须反映当前行为而非理想化目标若两者不同记录这个差异。最后是一条硬性义务当架构、流程、主要概念、约束、模式、决策或子系统变化时在同一次变更中更新手册。升级政策Escalation Policy别默默选一种解释“Escalation policy” 一节定义了与人“me”协作时的边界优化底层目标而非字面合规。工作过程中持续 sanity-check 请求、需求、契约、约束与假设是否真的说得通。发现中/高影响的歧义、矛盾、坏假设或战略/设计问题时停下来调查而不是绕开问题或默默选一种解释把问题具体化把它亮出来在推进该决定前与请求方讨论这个实质性决策。发现得越晚越要重新考虑计划而不是为已做的工作辩护。低影响问题自行判断处理事后提及值得注意的。进度停滞或复杂度意外增长时停止在当前方法上机械迭代扩大搜索空间重新审视方法本身主动探索实质不同的策略——简化或重新表述问题、改善复现或可观测性、使用现有工具/库、改变假设或约束。环境特定规则Codex harness 与绕过 Rake 的约定文末两节是环境相关的操作性规则OpenAI Codex harness如果运行在 Codex harness 下开工前先读并遵循 .agents/skills/codex-subagent-delegation/SKILL.md——它规定子代理委派subagent delegation策略主动在“保存主 agent 上下文、并行化独立工作、获得独立判断”有明显收益时委派给每个子代理自包含的任务简报按“所需判断力而非工作量”选择模型档位主 agent 对结果负全责把子代理输出当证据而非事实需核查可信性、完整性与矛盾后再采信。绕过 Rake 时的规则“Rules for avoiding caveats”在test/目录下运行测试即 cwd 设为 test/手动设置 doc/BuildSystem.md 中所述config.rb里定义的环境变量——该文件仓库根目录的config.rb通常由 Rake 启动时加载Rakefile 第 49 行require(#{SOURCE_ROOT}/config) if File.exist?(...)可证用于持久化环境变量例如# config.rb ENV[FOO] 123因为绕过 Rake 时这个加载步骤不会发生这些环境变量如构建选项USE_CCACHE、OPTIMIZE、EXTRA_CFLAGS等完整列表见 doc/BuildSystem.md就必须手动补齐。doc/RunningTests.md 同样提示选择绕过 Rake 时务必从test/目录运行测试。小结一份“降低认知负担”的工程宪法把 AGENTS.md 的各节放在一起看会发现它们服务于同一目标让每一个进入该代码库的工作者无论人类还是 AI用最小的心智负担做正确的事。具体表现为四条主线入口即路由先读 doc/DevHandbook.md 与 doc/BasicArchitectureOverview.md再按主题读规范文档避免凭空猜测架构变更半径最小化surgical changes、不动无关问题、测试规模看行为而非 diff收尾前做最终验证用仓库自己的安全抽象oxt 系统调用封装自动处理中断与 EINTR、FileDescriptor/safelyClose()、safeReadFile()与mkstemp()/mkdtemp()的临时文件纪律均有对应源码src/cxx_supportlib/oxt/system_calls.hpp、src/cxx_supportlib/FileTools/FileManip.cpp与专门文档doc/SecureTempFileHandling.md、doc/CodingTipsAndPitfalls.md可查文档即沟通媒介注释写给“懂行但新来的人”commit/PR 消息为评审减负changelog 只写用户可见影响架构变化必须同步更新doc/手册歧义升级而非默默解释。对在这套仓库上工作的工程师与 AI Agent 而言AGENTS.md 的价值不在于单条规则本身而在于它把“先查地图 → 最小化改动 → 用对安全工具 → 把知识固化回文档”这一完整闭环显式化了。赞分享后端【免费下载链接】passengerA fast and robust web server and application server for Ruby, Python and Node.js项目地址https://gitcode.com/gh_mirrors/pa/passenger点击查看免费下载相关推荐面向 AI 代理的营销技能仓库AGENTS.md 协作规范深度解读Marketingskills面向 AI 代理的营销技能仓库AGENTS.md 协作规范深度解读Marketingskills 本篇以仓库根目录的 AGENTS.md https://AI 技能人工智能PhotoPrism 仓库 AGENTS.md 全解读面向 AI Agent 与开发者的开发协作规范指南PhotoPrism 仓库 AGENTS.md 全解读面向 AI Agent 与开发者的开发协作规范指南 本指南以仓库根目录的 AGENTS.md https后端前端图像处理人工智能AI 应用面向 AI 代理的 EUI 仓库协作指南解读 AGENTS.md 与 Elastic UI 框架的开发规范面向 AI 代理的 EUI 仓库协作指南解读 AGENTS.md 与 Elastic UI 框架的开发规范 导读 本文围绕 AGENTS.md https:/前端UI组件设计系统上一篇终极指南解决rough-notation跨域资源共享问题的完整方案下一篇Semi Design性能基准测试全面对比主流UI库的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考