贡献指南

Gitee 是本项目的唯一主仓库。普通成员通过工作分支和 Pull Request 提交内容，仓库管理员负责审核并合并到 main。

项目协作入口已配置

源码以 Gitee 主仓库为准，通过 Gitee Pull Request 审核；GitHub 用作单向镜像，Cloudflare Pages 控制台仅供具备对应账户权限的管理员查看和操作。

项目协作入口

入口	用途	访问说明
Gitee 主仓库	Wiki 源码、文档和 main 主分支	项目的唯一主仓库
Gitee Pull Requests	提交、查看和审核内容修改	普通成员从工作分支发起，管理员审核合并
GitHub 单向镜像	Gitee main 的同步镜像	可能需要登录具备权限的 GitHub 账号
实验室 Gitea 镜像	浏览和下载实验室代码镜像	仅限交叉楼学生办公室内网；查看使用说明
正式 Wiki	查看已经部署的知识库	实验室成员访问入口
Cloudflare Pages 控制台	查看构建、部署记录、域名和运行状态	仅限具备 Cloudflare 项目权限的管理员

主仓库与镜像的边界

Wiki 内容编辑、分支推送和 Pull Request 都应在 Gitee 完成。GitHub 仓库用于部署同步，uull.git 用于办公室内网浏览和下载代码镜像，两者都不应替代各项目标明的上游主仓库；Cloudflare Pages 控制台只用于部署管理，不用于修改 Wiki 内容。

角色与权限

角色	推送工作分支	直接推送 main	合并 Pull Request
开发者	可以	由仓库权限自动拦截并转入 PR	不可以
仓库管理员	可以	权限验证通过后可以	可以

管理员权限由 Gitee 自动判定

协作工具不需要在每次操作前人工询问发起人是否为管理员。提交发布请求后，Gitee 根据当前账户权限和 main 保护规则自动判定：管理员可以更新 main；没有权限时，直接更新会被拦截，修改保留在工作分支并进入 Pull Request 流程。

无论最终进入直接更新还是 Pull Request，都必须先同步远端、完成严格构建和必要检查。禁止强制推送或改写 main 历史；若平台返回权限错误，应按平台提供的 PR 入口继续，不尝试绕过保护规则。

标准编辑流程

1. 从 Gitee 拉取最新的 main 分支。
2. 从 main 创建工作分支，例如 docs/update-instrument-sop。
3. 使用 Obsidian 打开项目的 docs 文件夹，以标准 Markdown 编写或修改文档。
4. 本地预览并运行 mkdocs build --strict。
5. 提交并将工作分支推送到 Gitee。
6. 发起发布：具备权限的管理员可以非强制更新 main；权限不足时由仓库保护和协作工具自动转入以 main 为目标的 Pull Request。
7. 进入 Pull Request 时说明修改内容、依据和验证结果，由管理员审核；需要修改时继续向同一工作分支提交。
8. main 更新后，Gitee 将其镜像到 GitHub，Cloudflare Pages 自动构建并发布。

文档约定

• 一个页面只解决一个清晰主题，标题应便于搜索。
• 文件名使用简短英文小写和连字符，例如 sample-preparation.md。
• 每个一级分类只在左侧导航显示一个入口；分类的 index.md 负责列出该分类下的文档。
• 具体文档放在对应分类目录下，并加入 mkdocs.yml 的对应分类；左侧栏会隐藏子级，但搜索、面包屑和返回上一级功能仍然有效。
• 使用相对链接引用站内页面；截图统一放在 docs/assets/images/screenshots/ 下，优先使用 WebP，再通过 .wiki-screenshot 组件引用。
• 参数必须带单位；命令、路径和代码使用代码格式。
• 对规则、SOP 和方法标注维护人、复核日期与版本变化。
• 不确定的内容明确使用 待确认 标记；缺失事实使用 待填写，尚不存在的文档使用 待创建，不要把猜测写成正式规则。
• 不提交密码、令牌、私钥、个人隐私和未公开研究数据。

经成员同意在组内共享的成员目录联系方式，以及实验室明确决定保留的门禁备用方式，是当前内部 Wiki 的有限例外；不得据此提交其他个人信息或账号凭据。

内容确认与复核周期

• 页面事实可由熟悉现场的成员提供，邓宏健负责最终确认和发布状态。
• 未取得最终确认时保留 draft、待确认或待填写，不得为了完成页面而猜测。
• 安全、入组、仪器 SOP 和仪器故障页面每 6 个月复核；其他制度页面每 12 个月复核。
• SOP 和规则页面在页首记录文档编号、版本、确认人与日期，并在页末维护简短变更记录。
• 全面更新应拆分为安全与入组、仪器与数据、日常制度、计算与资源等可独立审核的 Pull Request，避免把无关内容混入同一分支。

Pull Request 审核清单

• 内容是否准确，并由合适的负责人确认？
• 是否说明适用范围、前置条件和风险？
• 步骤、单位、链接和图片是否完整可用？
• 是否包含不应进入仓库的敏感信息？
• mkdocs build --strict 是否构建通过？
• 新页面是否加入 mkdocs.yml 的正确分类，并在分类 index.md 中登记入口？

管理员合并后

检查 Gitee 镜像、GitHub 提交和 Cloudflare Pages 部署是否成功；页面发布后，再检查导航、搜索、链接和移动端显示。