mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 06:58:57 +08:00
chinboy
38 lines
3.2 KiB
Markdown
38 lines
3.2 KiB
Markdown
# 参考项目源码查找规范
|
||
|
||
本文是 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 中重新验证。
|