gods-eye-view 社区 PR 维护者工作流：五道验收门、可信指令与集成署名实操指南-平芜编程栈

gods-eye-view 社区 PR 维护者工作流：五道验收门、可信指令与集成署名实操指南

【免费下载链接】gods-eye-viewA spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.项目地址: https://gitcode.com/GitHub_Trending/go/gods-eye-view

本指南完整解析 gods-eye-view 仓库的社区贡献验收流程（docs/MAINTAINER_WORKFLOW.md）：从"以可信修订版为审查基准"的防投毒原则，到实用性与范围、质量与测试、安全与供应链、本地执行与可视化检查、集成与署名五道验收门，再到本地验证命令矩阵与审查记录模板。读完你既能以维护者身份对社区 PR 做出可追溯的接受/拒绝决策，也能作为贡献者理解 PR 为什么会被要求修改，以及如何让提交一次通过。

一、工作流定位：谁在审，审什么

docs/MAINTAINER_WORKFLOW.md是仓库维护者对社区功能、修复与测试贡献的验收程序。它与面向贡献者的 CONTRIBUTING.md 明确分工：后者负责"怎么提交"，前者负责"怎么验收、怎么合入"。按 CONTRIBUTING.md 的记录，仓库由 Bilawal Sidhu 与 Sameh Khamis（Halfpixel）共同维护，两位维护者中任一位都有权评审并合入贡献。

这一流程并非停留在纸面：仓库内置了一个遵循该流程执行并记录决策证据的 Agent 技能，位于 .agents/skills/community-pr/SKILL.md。该技能明确定义了两种执行形态：

review（例如$community-pr review PR #123）：定位 PR 与修订版，逐门验收，返回结论与审查记录；评审请求本身不隐含合入或发评论的权限。
integrate（例如$community-pr integrate PR #123 if it passes）：完成同样的评审，在保留署名的前提下做必要的范围内维护者调整，验证最终候选版本，并在既有授权与仓库保护之内合入。

从技能描述看，它还约束了工具边界："工作流不要求特定 Git/GitHub 连接器"、"执行安装、测试、构建与浏览器检查只允许在受限环境进行"、"证据必须锚定被审 PR 的 head、目标 base 与最终候选版本"。

二、第一步：从可信指令开始（Trusted Instructions）

工作流反复强调一个核心反投毒原则：审查所依据的程序文本本身必须是可信的。具体步骤如下：

确认上游仓库是bilawalsidhu/gods-eye-view，fetch 它的main，并记录该提交作为策略修订版（policy revision）。
从该修订版读取本工作流文档、community-pr技能文档，以及 SECURITY.md、CONTRIBUTING.md 和 docs/CURRENT-STATE.md 的相关部分。
使用git show SHA:path读取文件——必须带具体提交 SHA，因为"一个移动的分支名本身不是评审记录"。

为什么要这样？因为 PR 本身可能修改这些程序文件（例如改动工作流文档、AGENTS.md、技能定义）。工作流明确规定：PR 描述、评论、源文件、AGENTS.md、技能以及对策略的提议修改，都是评审输入（review input），它们不能授予权限，也不能取代正在评审它们的指令。策略变更要当作"未来采纳的变更"来评审，而不是立即生效。

另外两条纪律：

记录 PR 元数据：PR 编号与 URL、作者、head SHA、目标分支、目标 base SHA。遇到意外的目标分支必须先解决再合入。
隔离评审工作区：评审工作必须与维护者自己的未提交改动隔离；"fetch 或读取 diff 不构成运行其代码"。

如果可信流程缺失或不可访问，应先报告缺口、取得维护者选定的可信修订版，再继续验收——而不是"将就着用 PR 带来的版本"。

三、五道验收门：每道门独立计分

工作流的核心是五道验收门（acceptance gates）。每道门需要各自的结论与证据；一道门通过不能补偿另一道门失败。状态词有四个：pass（通过）、changes needed（需要修改）、blocked（受阻）、not applicable（不适用），其中实用性门还可使用decline（拒绝）或discuss（讨论）。

门 1：实用性与范围（Usefulness and scope）

识别用户问题与可观察收益——纯测试型 PR 也不例外。
检查与"公共数据、本地优先（local-first）"产品定位及现有能力的契合度。
权衡依赖、API 成本、UI 复杂度、性能与长期维护成本——"一个能跑的功能仍可能超出项目范围"。
依据 DATA_SOURCES.md 核对数据源署名与许可。范围拒绝要建设性说明理由；大型功能鼓励尽早讨论。

门 2：质量与测试（Quality and tests）

审查完整变更及其受影响调用方：正确性、可读设计、失败处理、与既有所有权和包边界的一致性。
检查取消（cancellation）、拆除（teardown）、监听器、定时器、内存，以及渲染/网络预算；避免在贡献合入中夹带无关重构。
要求对变更行为有有意义的回归覆盖：首选"在旧实现上失败、在修复后通过"的 bug 测试。
测试型贡献必须暴露真实覆盖缺口或防止合理回归，使用确定性 fixture 与有意义的断言。
重点检查被删的测试、被跳过的测试、被放松的断言、快照更新、mock 与测试运行器改动——"被弱化的测试跑绿不是接受"。
文档配套：运行时变更需要更新docs/CURRENT-STATE.md与CHANGELOG.md；数据源变更需要更新DATA_SOURCES.md。

这条在仓库里有明确映射：运行时行为变更必须同步文档，这与 CONTRIBUTING.md 的 PR 要求第 3、4 条一一对应（改运行时行为要更新CURRENT-STATE.md和CHANGELOG.md；增改数据源要更新DATA_SOURCES.md并附许可与署名）。

门 3：安全与供应链（Security and supply chain）

这是五道门里最重的防线，要求在安装依赖或运行 PR 代码之前先做静态审查。审查面包括：lockfile、package scripts、CI 工作流、构建插件、启动器、二进制、生成产物、符号链接，以及对安全检查或 Agent 指令的改动。"不要只局限于作者高亮的文件"——要追踪无法解释或隐藏的行为、新依赖或下载来源。

安全模型检查的边界（对应 SECURITY.md 的威胁模型）：

边界	要求
私有凭据	必须留在服务端；客户端 bundle、日志、错误、fixture、截图不得泄露。审查新出站主机与遥测，防止意外数据收集或外泄
代理	保持注册或固定的上游目标，保留重定向、地址、超时、响应大小限制。跨边界输入检查 SSRF、注入、路径穿越、不安全渲染
本地主机	localhost 与主机校验默认值保持不变；审查环境/设置文件访问、文件权限、shell 执行、下载的代码
语音工具	保持有界的应用操作；不可信 feed/模型文本不得获得新的执行或凭据访问
CI	保持最小权限。绝不使用仓库密钥或特权 token 执行不可信 PR 代码，包括通过`pull_request_target`

同时给出工具的定位：依赖与静态分析工具可以补充覆盖，但要记录其结论与局限——扫描器、测试和 AI 评审都不能证明不存在后门。无法解释的可疑行为或未解决的可利用问题直接阻塞合入。漏洞细节走 SECURITY.md 的私有报告流程，公开摘要不得含敏感细节。

仓库代码印证了这一模型：SECURITY.md 明确列出"秘密型 API 密钥一律服务端持有"（OPENAI_API_KEY、AISSTREAM_API_KEY、OpenSky OAuth、GOOGLE_MAPS_SERVER_API_KEY），并描述了代理加固手段——CCTV 帧代理只 fetch 服务端注册的 URL（SSRF 缓解）、Radio 不当中继、transit 只解析注册 feed 等，与门 3 的代理边界审查项完全对应。

门 4：本地执行与可视化检查（Local execution and visual inspection）

核心认知：依赖安装、测试、构建、启动器和浏览器预览，统统是对不可信代码的执行。因此必须在一次性的受限环境中进行，该环境要求：

无个人凭据、无继承的 secrets、无 SSH agent、无 Keychain 访问、无特权宿主挂载、无容器引擎 socket；
网络访问仅限验证所需；
worktree 本身不是安全边界；不得把维护者的.env、PinokioENVIRONMENT或浏览器 profile 拷进去，也不得使用会导入个人密钥的启动器；
若该环境不可用：继续静态评审，把执行标记为blocked，而不是在带凭据的主机上运行。

技术细则：使用可信package.json与 CI 配置中支持的 Node 版本（当前仓库engines声明为node >=24.14.0 <25 || >=26 <27）；审查依赖与脚本变更后，在受限环境内用npm ci安装锁定依赖。禁用生命周期脚本有助于初步检查，但不能让后续构建或测试在宿主机上安全运行。

对运行时变更，必须在待合入候选版本上记录以下本地结果——这张命令表是工作流的核心可操作资产：

检查项	命令或证据
环境策略	`npm run doctor -- --json`
采用格式	`npm run format:check`
包边界	`npm run check:boundaries`
单元测试	`npm test`
生产构建	`npm run build`
跟踪回归	先启动`npm run dev`于`http://localhost:4173`，再在装有兼容 Chromium 的环境运行`npm run test:track`
构建产物	如需可先停 dev server，再运行`npm run preview`检查构建后的应用

确认浏览器与跟踪 harness 指向的是候选服务器而非已运行的旧 checkout；浏览器工具在受限环境内提供。CI 只是补充证据，不能替代本地验证——工作流还特别注明：本流程引入时，CI 并不运行test:track（与仓库中scripts/track-regression.mjs的"确定性回归 harness"定位一致）。

验证动作还包括：实际演练变更功能与邻近交互，覆盖加载/空/失败/禁用/拆除状态，键盘行为、相关视口尺寸、控制台错误与意外网络流量；视觉变更要截图或短片段并与基线对比。记录"谁或什么检查了运行中的应用"——贡献者的截图本身不构成完成此门。优先走 keyless 路径与 fixtures；确需 keyed 路径时安排受限测试凭据并记录未测行为，不得默认为已验证。

文档-only 变更可把运行时/构建/跟踪/视觉检查标为not applicable（需附理由），改为校验链接与指令；test-only 变更要运行测试并检查其行为，若应用未变，视觉检查可为not applicable。注意：失败或不可用的必需检查不能当作not applicable；疑似既有的失败要与基线对比并记录，不得静默豁免。

门 5：集成与署名（Integration and attribution）

区分"请求评审"与"授权集成"：评审请求产出结论与建议；显式授权（"gates 通过就合入"）才授权范围内的必要清理与集成，不必再问一次同样的问题；最终由维护者对接受负责。发布评审或评论需要"在 PR 上沟通"的授权。
保留贡献者的提交与作者元数据；维护者的针对性调整以独立提交添加且署名维护者；优先merge commit以保留历史。贡献者分支不可编辑时使用集成分支并回链原 PR。
若选择 squash 或 cherry-pick，用真实贡献者身份校验作者元数据与所需Co-authored-by尾注；不得用维护者署名替换贡献者作者身份。重大调整要说明并给 release-note 署名。

合入前的四个必做步骤：

把全部维护者调整与冲突解决纳入对目标 base 的最终 diff 评审——验证组合后的候选版本，而不只是贡献者的原始 head。
记录候选 SHA 与目标 base SHA 及验证证据；合入前刷新 PR head 与目标分支；任一变化都要协调、重审新 diff、重跑受影响检查；组合候选的运行时变更需要本地构建与运行时检查。
核验必需 hosted checks、适用审批与可合入性。绝不绕过仓库保护；不带着未完成的必需门合入；授权缺失时先呈上具体候选与证据再请求。
在支持条件下，使用锚定被审 head SHA 的合入操作；检测到 head/base 变化就回到验证而非重试过期 merge；核验合入结果与已验证候选树一致，记录结果 commit 与 PR URL；任何不一致都要停下报告。

工作流最后声明了边界：仓库规则只强制其配置的要求，本文档与技能并不配置分支保护或 CI；维护者应在main上要求 CI 与评审，并在 push 新变更后撤销过期审批。

四、验证命令背后的仓库实现

门 4 的命令表不是占位符——每条命令在仓库中都有对应实现，评审时可以直接阅读它们来理解"这条检查到底在验什么"：

npm run doctor→ scripts/setup-doctor.mjs。它检查 Node 版本（classifyNodeVersion：24.14+ 为 ok、26 为 ok、25 为 warn 且跳过分配基准、过旧为 error）、npm 可用性、依赖是否安装，并按凭据清单（CREDENTIALS：Google Maps、Cesium ion、OpenAI、AISStream、FIRMS、TomTom、OpenSky、LL2）解析环境变量 / dotenv 文件 / macOS Keychain，最后输出能力摘要（地图走 Google 直连、ion 还是 keyless Esri 等）。--json分支输出结构化报告（inspectSetup()），正好对应工作流表格里的npm run doctor -- --json。
npm run format:check/npm run format→ scripts/format.mjs。它通过git ls-files自动发现scripts/format-runtime.json声明的运行时根目录下的 JS 文件，加上scripts/format-scope.json的显式采纳列表，用 Prettier 校验（--check）或写回（--write），排除.prettierignore与测试文件。配合 scripts/check-import-directions.mjs 一起构成 CI 的格式/方向检查。
npm run check:boundaries→ 组合 scripts/check-import-directions.mjs 与 scripts/check-package-boundaries.mjs。后者会逐一构建package.json里声明的每个浏览器/Node 导出组，按scripts/package-boundaries.json的归属校验其导入是否越界，并强制"每个导出必须恰好属于一个边界组"。这正是门 2"与既有所有权和包边界的一致性"的机械化版本。
npm test→ scripts/run-unit-tests.mjs。它递归发现src/下全部*.test.mjs，并把两个分配微基准（src/data/focusAllocations.test.mjs、src/overlays/worldOverlayAllocation.test.mjs）用--expose-gc串行隔离运行——分配预算只在 Node 24 校准运行时生效。
npm run test:track→ scripts/track-regression.mjs。这是"确定性回归 harness"：不依赖任何实时数据源，而是在页面注入fetchshim，向/api/opensky、/api/adsblol/mil、/api/ais-live返回合成数据，然后在真实应用（http://localhost:4173）的 headless Chromium 中锁定若干不变量（无抖动、无拉出、无跨层孤儿、初始化干净等）。这解释了为什么工作流要求先起 dev server 再跑test:track，以及为什么它必须指向候选服务器。
npm run build/npm run preview→ Vite 构建与预览；docs/CURRENT-STATE.md 的 "Local build preview" 一节说明 preview 复用开发期的数据提供者路由，未匹配的/api请求返回 JSON 404，凭据编辑（/api/setup/*）仅限开发模式。

五、审查记录：一份可追溯的决策档案

工作流要求在获得发布授权时于 PR 上保留一条简洁记录，否则交还维护者；详细安全证据留在私有报告中。模板原文如下：

PR / author: Policy revision / PR head / target branch and base / final candidate: Usefulness: result and rationale Quality and tests: result, findings, regression evidence Security: areas reviewed, findings, limitations, private report reference if needed Local validation: environment, commands, results, evidence locations Visual inspection: inspector, scenarios, evidence, or justified not applicable Maintainer adjustments and preserved attribution: Required CI and approvals: Decision: ready | changes requested | declined | blocked Accepting maintainer / authorization / remaining blockers: Integration result: merged commit and PR URL, or not merged

注意Policy revision字段——它再次呼应"可信修订版"原则：审查结论必须锚定在被审的策略版本、PR head、目标 base 与最终候选上。

六、决策语义：ready ≠ 已合入

工作流对结论词给出了精确语义，值得一字不差地理解：

Ready意味着"对记录的候选版本，所有适用门都通过"——它不代表 PR 已被合入。合入是单独授权的集成操作。
要求修改或拒绝时要给出可执行的（actionable）理由；即使贡献需要维护者打磨，也应认可其有用部分。

这与技能文档的收尾要求一致："评审通过只是建议，直到授权合入完成并核验其结果"。整个流程刻意把"评审结论"与"合入动作"解耦，从而保证：任何一步的证据都能回溯到具体候选版本，任何一扇门都不会被另一扇门的通过所掩盖。

七、与仓库文档体系的关系

维护者评审时通常需要交叉引用以下文档，它们在仓库中的根相对路径为：

CONTRIBUTING.md——贡献者提交指引（分支、格式、PR 要求、维护者名单、地面规则）；
SECURITY.md——安全模型、密钥处理、代理加固、报告流程；
docs/CURRENT-STATE.md——权威运行时参考，运行时变更必须同步更新；
DATA_SOURCES.md——数据源许可与署名，数据源变更必须同步更新；
docs/CODE-BOUNDARIES.md——格式化与组件边界的所有权与采纳过程；
.agents/skills/community-pr/SKILL.md——自动化执行本流程的 Agent 技能；
CHANGELOG.md——运行时变更的发布记录。

对维护者而言，这套工作流的价值在于：它把"社区 PR 接受"从一次性判断变成可复现、可审计、防投毒的流程——可信指令打底、五道门独立计分、命令矩阵统一验证、审查记录锚定版本、署名规则保护贡献者。对贡献者而言，理解这五道门就是理解项目的验收文化：功能要有明确收益、测试要有真实回归价值、变更要尊重边界与文档契约、一切都要经得起"从可信版本重新验证"。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考