AtomUI/docs/engineering/contributing/reference-project-source-guidelines.md

参考项目源码查找规范

本文是 AtomUI 的全局工程约束。凡是用户要求“参考某个项目源码”，或表达同等意图（例如“对照某项目实现”“借鉴某项目代码”“看看某项目是怎么做的”），都必须先按本文定位参考源码，再进行分析、设计、编码或回答。触发不依赖用户是否使用了完全相同的措辞。

强制查找顺序

将当前任务所属的仓库根目录视为“项目目录”，按以下顺序查找用户指定的项目名：

1. 先查项目目录下的隐藏目录 .referenceprojects，目标位置为 <项目目录>/.referenceprojects/<项目名>。
2. 如果没有找到对应项目，从项目目录本身开始逐级向上查找。每一级只检查该目录下名为 ReferenceProjects 的目录，即 <项目目录>/ReferenceProjects/<项目名>、<父目录>/ReferenceProjects/<项目名>、<祖父目录>/ReferenceProjects/<项目名>，持续到文件系统根目录。
3. 只有上述全部本地位置都没有对应项目时，才允许去 GitHub 搜索源码。

目录名 .referenceprojects 与 ReferenceProjects 必须按本文所写的大小写和拼写处理；不得因为某一级未命中就跳到更高一级，也不得用其他未授权目录、全盘递归搜索或 GitHub 搜索替代规定顺序。

项目匹配与来源选择

• <项目名> 优先使用用户给出的项目名称做精确路径匹配。遇到名称歧义时，可以列出候选目录核对，但不得凭记忆选择一个“看起来相近”的项目。
• 在本地找到对应项目后，以本地源码为本次参考的唯一默认来源；不得未经用户明确要求再用 GitHub 版本替换或覆盖本地来源。
• 只有本地查找完全结束且没有命中时，才使用 GitHub。GitHub 来源应优先选择项目官方仓库，并记录仓库 URL、分支或 tag，以及能够确定时的 commit；不要把搜索结果摘要当作源码依据。
• 如果本地和 GitHub 都无法找到对应源码，必须明确报告“未找到参考源码”，停止把该项目当作已验证依据，不得编造实现细节或暗示已经参考过。

执行与记录要求

开始依赖参考项目的工作前，必须实际执行上述查找流程，而不是只根据已有记忆回答。结果中至少说明：

• 最终采用的来源类型：本地或 GitHub；
• 本地来源的绝对路径，或 GitHub 来源的仓库 URL；
• 若存在多个候选，说明为什么选择该候选；
• GitHub 来源可确定时的分支、tag、commit 或检索日期。

如果用户同时指定了多个参考项目，必须对每个项目独立执行完整顺序；一个项目命中本地目录，不代表其他项目可以跳过本地查找。用户明确要求比较本地源码与 GitHub 上游时，才可以在本地来源命中后继续查 GitHub，并分别标注两类来源。

与其他规则的关系

本规范只规定“参考项目源码从哪里找”。参考源码不是 AtomUI 自身公共契约、架构事实或版本来源；长期文档仍必须以 AtomUI 已验证的行为和契约为准。引用外部实现时，应说明哪些内容是外部参考、哪些内容已经在 AtomUI 中重新验证。