企业官网建设流程全解析

OpenAlice 是一个面向原生编码 Agent CLI 的本地交易工作区（Alice 负责启动 Workspace 并注入交易上下文，独立的 UTA 进程持有券商凭据与所有交易写入）。本文以仓库中的 docs/development-workflow.md 为核心骨架，系统讲解其维护者工作流：分支车道划分、三种交付模式的合并权限、PR 生命周期与主题标签契约、本地反馈阶梯、CI 反馈车道、dev→master晋升、beta/stable 发布治理、紧急热修复、外部贡献审查与风险门禁。读完本文，你将能准确执行"从会话开始到发布验收"的全链路操作，并理解每条命令背后的治理约束。

该指南是 OpenAlice 治理体系的"灵魂文档"：它拥有维护者工作流的全部细则，而 AGENTS.md 只保留每次会话开始必须遵守的精简规则；docs/README.md 则是全部 Owner Guide 的索引。三者的关系是：AGENTS.md 是入口，workflow 指南是详细程序，各子系统 Owner Guide 承载持久化的事实。

分支车道（Branch Lanes）

OpenAlice 的分支拓扑将"日常集成"与"用户可见发布源"分离，并让发布动作始终由人从master手动触发：

• dev—— 集成车道与可测试预览环境：常规开发在此整合。合并进dev的安装器变更会通过可变的raw/.../dev/install端点与匹配的--channel dev载荷选择器被实际演练。也就是说，推送到dev本身就是一条"仅限 CLI 的滚动发布车道"（详见下文 CI 反馈车道）。
• master—— 发布源/用户面车道与默认 GitHub 分支：dev合并到master只确立"可发布源码"，并不选择版本或发布 Release。
• 发布自动化：从master手动派发，必须显式携带beta或stable通道与 tag。tag 版本与两个产品包清单（根package.json与packages/cli/package.json）必须一致，候选工作才能开始。每个被接受的 tag 只能更新属于自己的可变产品别名；新接受的发布还可以刷新共享的通道中立install引导。
• Release操作的publish-npm：只分发一个已经发布的 stable 版本。它可以复用集成好的dev或master工具链，但不能创建版本、重建构件或变更产品通道。其首次发布/重试契约见 docs/cli-package-managers.md。
• Release操作的verify-npm：从dev或master校验完整的 npm OIDC 包集合，不打 tag、不构建、不上传包。npm 发布使用工作流的身份（OIDC），而不是轮换的仓库 token。
• archive/dev-pre-beta6：历史快照分支，禁止修改或删除。
• local：遗留的共享 worktree 分支，不是默认工作流；在决定保留还是退役前，必须先审计其未合并提交。

常规工作的起点是当前dev，使用聚焦的特性分支并开 PR 回到dev。永远不要对dev或master强推（force-push）或删除。

会话开始（Session Start）

每次开始编辑前，先同步远端并确认 checkout 状态：

git fetch origin git status -sb git log --oneline origin/dev..HEAD git log --oneline origin/master..HEAD

然后确立 checkout 的所有权：

1. 保留无关的脏文件：不要 stash、reset 或把它们吸收进任务里（除非明确授权）。
2. 共享 worktree：如果另一个活跃会话共用同一个 worktree，不要在其脚下切换分支；应串行化工作或使用独立的 checkout/sandbox。
3. HEAD 在dev：先快进（fast-forward）再开分支。
4. HEAD 在特性分支：先查明其 PR 是仍打开、已合并、关闭未合并还是不存在，再继续。
5. HEAD 在master或意外历史分支：确认任务是晋升/热修复，还是应回到dev。

这套规则的目的是：任何时刻都清楚"我站在哪个车道、该把增量送到哪里"，避免把无人认领的分支或脏状态带进下一个任务。

交付模式（Delivery Modes）

交付模式控制的是合并权限（merge authority），而不是实现质量。三种模式共享同一条实现与评审标准，差异只在于"增量何时、以何种形式进入dev或master"。

特性分支迭代保持（Feature-branch iteration hold）

特性分支迭代是一条显式的自然语言指令，而不是第三种交付模式或配置 schema。例如维护者可以说："把这个留在特性分支上，迭代到我满意为止。"该保持独立适用于串行或并行工作，覆盖其正常的 PR 时机，但不改变实现或评审标准。

保持生效期间：

1. 把连贯的工作保留在一条基于dev的命名分支上；
2. 由一个集成者负责该分支；并行协作者使用临时分支或 worktree，以提交交接而非抢占推送；
3. 把验证过的增量提交并推送到特性分支，但暂不向dev开 PR 或合并；
4. 在规范的plans/<topic>.md（如 PLANS.md 所述的规划文件）中用普通文字保持多会话范围与验收进展的最新状态；
5. 在增加范围前继续检查已知 CI 或集成失败，并周期性地并入当前dev，但不重写共享分支历史；
6. 持续保持，直到维护者明确说"可以开 PR"或明确废弃该分支。

当维护者接受分支时：先与当前dev调和，对累积 diff 运行完整的按比例验证，然后开常规 PR 到dev。"继续干活"、一次交互式跟进或一次成功的本地增量，都不意味着保持自动结束。被保持的分支也不是预览或发布车道：dev与master保留它们原有的集成与晋升所有权。

串行 / 交互模式（Serial / interactive）

当用户正在主动请求、评审并引导具体工作时，这是默认模式：

1. 从当前dev开分支；
2. 工作中解释关键设计取舍；
3. 实现并运行按比例验证；
4. 发布下一个增量之前，检查上一个串行 PR 的检查结果及其合并后的dev运行：已完成的失败必须先修复再叠加工作；仍待定的运行记录在案即可，不必等待；
5. 开 PR 到dev，确认预期的 base 与 head，然后立即合并——除非用户要求评审暂停、声明特性分支迭代保持，或此前 CI 已有已知失败；
6. 删除已合并的特性分支，回到更新后的dev。

关键认知：PR 是把完成增量持久集成进dev并记录其 diff 的载体，不是同步的 CI 或审批暂停。在此模式下，远端 CI 是"滞后一个增量"的反馈——它在合并后继续运行，必须在下一个串行发布前被检查。

自主 / 主题贡献模式（Autonomous / topic contribution）

该模式只在出现/goal或明确要求自主发现并贡献改进时激活。

GitHub 的 PR 列表是面向社区的产品表面，不要把内部 Agent 任务拆解镜像成"每个发现一个 PR"。自主工作应汇集成一个评审者能理解为一个产品结果的一致主题：

1. 用一句话定义主题，记录其验收边界与非目标；
2. 从最新dev在一条主题分支上开始，在第一个验证过的增量之后打开Draft PR（除非特性分支迭代保持把 PR 推迟到维护者接受）；
3. 保持一个集成者负责该分支；并行协作者使用临时分支/worktree 交接提交，而不是竞相推送主题分支；
4. 把相关改进做成原子化、可独立理解、可回滚的提交；
5. 保持 Draft PR 正文与已包含增量、验证、开放风险、剩余主题工作同步；
6. 默认在开始下一个社区面向的主题之前，先完成、冻结并提交当前主题供验收；
7. 在维护者明确接受该主题之前不得合并。

PR 是主题的验收表面；提交仍是调试与评审单元。一个大型 diff 只要服务于一个清晰的验收叙事就不必拆分。只有在工作有真正不同的产品目标、需要独立回滚/安全/发布边界、或维护者明确授权并发主题时才另开 PR。绝不因为某个内部任务或 Agent 结束就创建另一个 PR。

后续的交互消息不会追溯授权合并主题 PR。在其最新 CI 待定时可以继续相关增量（新推送会取代旧运行），但已完成的失败必须先理解并修复，再增加范围。

主题 PR 标签

标签是交付契约的一部分，不是事后积压清理。在添加第二个增量之前，每个自主主题 PR 必须具备：

• workflow:parallel；
• 恰好一个描述"变更为何存在"的主要theme:*标签；
• 至少一个描述"谁拥有被变更表面"的area:*标签；
• 当变更触及交易写入、持久化配置、凭据、破坏性操作、安全边界或大量跨表面结构时，必须加review:deep。

优先使用一个主要 area。只有主题有意跨越所有者边界时才增加第二个；不要为偶然的文件触及累积 area 标签。

受控 theme 标签：

受控 area 为：area:app-shell、area:collaboration、area:demo、area:devtools、area:market-data、area:onboarding、area:settings、area:trading、area:workspace。如果反复没有合适的 area，应有意添加一个，并在同一治理变更中更新本指南。

标签是对 PR 正文的补充，不能替代问题证据、验证记录或明确的残余风险说明。review:deep只标识评审深度，永远不算批准。返回dev前，应在 GitHub 上核实标签确实存在。

常规 PR 流程（Routine PR Flow）

git switch dev git pull --ff-only origin dev git switch -c <type>/<short-description> # 实现并验证 git add <intentional-files> git commit -m "<terse outcome>" git push -u origin HEAD gh pr create --base dev --head "$(git branch --show-current)" # 串行模式：确认 PR base/head 后，不等待待定 CI。 gh pr merge <number> --merge --delete-branch

PR 正文应包含：

## Summary - what changed and why ## Included increments - [ ] atomic outcome represented by one or more named commits ## Verification - exact automated and manual checks run ## Boundary touch - trading, auth, credentials, migrations, runtime, packaging, or none ## Non-goals - adjacent work intentionally left out

增量清单与非目标是自主主题 PR 的必填项，小型串行 PR 可选。分支增长时请同步更新清单，不要让评审者仅凭提交标题去重构主题。

不要附加 Agent 厂商广告或自动 co-author 尾注。对人提供的报告、设计或评审的致谢应通过 CONTRIBUTORS.md 与指向塑造该工作的 issue/PR 的链接完成。

本地反馈阶梯（Local Feedback Ladder）

常规开发从"能证伪变更的最小门禁"开始，默认不购买整个 monorepo 的完整测试套件：

pnpm test:changed使用 Vitest 的变更文件依赖选择，针对新拉取的origin/dev，同时包含已提交与工作区变更。它是常规特性分支反馈工具，不是发布门禁。静态导入可被发现；动态导入、生成契约、注册表、隐式运行时耦合以及零测试选择，都需要显式的 owner/area/package/path 选择或升级。包清单、Vitest/Vite 配置、别名或测试 harness 的变更必须运行完整套件，因为它们可能改变每个 owner 的收集行为。

typecheck 必须覆盖变更的代码：根npx tsc --noEmit覆盖src/；UI 使用cd ui && npx tsc -b；Workspace 包使用各自的 typecheck 命令。一条没包含变更代码的绿色命令不算证据。UI 与运行时行为仍需要真实的浏览器、启动器、包或原生表面——变更测试选择不能替代该验收。

在 PR 中记录确切命令与真实表面结果。当一个 owner 的影响面比静态依赖闭包更宽时，使用匹配的pnpm test:owner:*套件。pnpm test作为第三行以及手动派发/stable 车道的显式封闭式完整套件后备。完整命令目录、包本地契约、选择器组合与副作用规则见 docs/testing.md。

从实现上看，这套命令目录与选择器由 scripts/run-tests.mjs 与 scripts/test-lanes.mjs 承载：run-tests.mjs解析--lane、--owner、--area、--package、--path、--changed等维度（见 run-tests.mjs），同一维度内 OR、不同维度间 AND，默认车道为hermetic，零文件结果会"失败关闭"而非假装通过。各 product owner 套件在根 package.json 中映射为pnpm test:owner:*别名（alice、ui、uta、connector、runtime-cli、desktop、repo-tooling），系统级命令（test:system:installer、test:system:remote等）永不进入pnpm test。

CI 反馈车道（CI Feedback Lanes）

Pull-request CI 与滚动的 dev CLI 发布分别提供变更级与合并后集成反馈。它们的阻塞权限取决于交付车道：

• **常规集成 PR（base 非master）**只跑一条干净的 Ubuntu 车道：workflow 契约、根 typecheck、完整 workspace 构建。稳定的build-and-test检查名通过"要求构建成功并有意跳过完整测试车道"保持绿色。PR 必须记录来自上文阶梯的适用 owner 级测试、typecheck、浏览器、Electron、remote、installer 或原生运行时证据——托管 CI 不是同一置信度的二次购买。
• 目标是master的 PR自动运行受信任的 source-contract/typecheck 门禁与原生 Windows dev-stack smoke。封闭式 Ubuntu 套件、完整 workspace 构建与 macOS build-and-test 复跑，只在维护者显式派发 Full Source Validation（或启动 stable Release，它调用同一完整工作流）时运行。Windows 桌面与 Broker Pack 打包留在单独的 package 工作流中。本地开发负责 macOS/Linux 的变更测试选择；托管 runner 是刻意的原生主机或发布候选工具，不是每个本地检查的二次购买。
• 精确 beta 版本专用 PR 的快速车道：当master目标 PR 的完整 diff 恰好是根package.json与packages/cli/package.json中同步的、向前的 betaversion值时，它走发布准备快速车道：保留受信任分类器、workflow 契约、根 typecheck 与稳定聚合检查名，跳过 source build/完整测试车道与 CLI 安装器、Broker Pack、桌面/跨平台 PR 矩阵（因为没有任何运行时实现变化）。随后 beta Release 工作流从确切masterSHA重建并验收每个最终带版本候选。分类器从受信任的 base 提交读取并失败关闭：stable 版本、多余字节或路径、不匹配、非法版本与分类器错误都会保留常规 master PR 门禁。
• 同一 PR 的被取代运行会被取消，只有最新 head 的结果是可行动证据。
• 中央 CI 聚合为精确 beta 版本 PR 持有 workflow 契约与根 typecheck；Desktop Package Smoke 只保留其受信任分类器，然后跳过昂贵的宿主包矩阵与 Windows Broker Pack 车道。这些包车道预留给master目标的实现 PR 与手动验证；常规集成使用匹配的本地未签名包 smoke。
• 串行模式下，devPR 可在按比例本地验证后合并，远端检查仍在待定。发布下一个串行 PR 前，检查该 PR 的检查与随之产生的devpush 运行。已完成的产品或契约失败会阻塞进一步叠加，直到被理解并修复；待定状态本身不阻塞。托管 runner 的资源失败不会被重复转换成产品风险：抓取日志，在本地或最小原生车道上复现受影响的契约，然后修复或移除有噪声的常规检查，而不是盲目重试整个矩阵。
• 自主主题 PR 保持打开等待接受。待定运行不阻塞相关提交，但只有最新 head 是证据；已完成的失败在修复前阻塞更多范围。CI 从不授予合并权限。
• 推送到dev是仅限 CLI 的滚动发布车道：不运行通用 CI 工作流、不构建 Electron、不构建 Docker。六个原生 CLI 候选由一份共享服务端输入组装：macOS/Linux 候选在激活一个原子 dev manifest 前运行打包的 Guardian/Alice、Web、Workspace、PTY 与发布所属 Git 验收；Windows x64/ARM64 在 Linux 上交叉构建，其原生 runner 验收是手动或 stable 专属的，因此 Windows 队列不是 dev/beta 发布依赖。原生排练（native rehearsal）先保留构件，可在安装器/夹具修复后重放验收。更重的 UTA/Connector 恢复与外部 Broker Pack 夹具在 Linux x64 上运行一次；手动 Full Source Validation 与最终 Release 车道保留更宽的原生宿主覆盖。
• 安装器或分布式 CLI 工作在本地用确定性的干净容器 HTTP 安装证明检出树。常规devPR 不购买该夹具的第二个托管副本。合并后，devpush 构建每个原生候选，将raw/.../dev/install下载到干净宿主，以--channel dev安装，并验证实时预览通道的 provenance、命令、服务器控制面与幂等复用。托管 checkout、Bun 宿主、包管理器与托管 SSH 候选验收从master/手动边界开始。
• beta 晋升使用记录的本地验收、自动 source 门禁、Windows dev-stack smoke 与最终 Release 工作流的构件验收；它不等待重复的托管 macOS/Linux 完整套件。stable 候选在候选构建的同时，对其精确派发提交运行 Full Source Validation。最终发布要求完整工作流成功；无需单独的串行派发。真实产品失败仍会停止或撤回候选；托管 runner 饥饿与已知的非产品夹具超时不会通过重复变成产品风险。

常规集成没有托管变更路径白名单。串行开发使用上述本地阶梯，仅在这些表面变化时补充pnpm test:system:remote、真实浏览器、OrbStack、安装器、未签名 Electron/包与原生运行时验收。远端验收从用户已通过普通 SSH 可达的宿主开始；CI 与仓库脚本不配置或管理云供应商。在 PR 中记录命令与结果。stable Release 在构建构件的同时重新建立完整 source 矩阵，即使常规集成与 beta 使用了更轻的托管反馈。

这些车道约束不是纸面声明，而是由测试强制执行的契约：scripts/ci-workflow.spec.ts 断言devPR 只触发 "Dev PR Clean Build"（单 job：pnpm install --frozen-lockfile、pnpm test:contract:workflow、pnpm build，不含npx tsc --noEmit与pnpm test，15 分钟超时），断言 "Full Source Validation" 只对masterPR 与workflow_dispatch触发、其重 job 必须显式手动门禁，并断言 beta 分类器从BASE_SHA读取（见 ci-workflow.spec.ts）。分类器本身由 scripts/classify-beta-release-prep.mjs 实现：它要求变更恰好是两份清单的M（修改）且版本是"向前的新 beta"（vX.Y.Z-beta或vX.Y.Z-beta.N），不匹配即失败关闭。对应工作流文件为 .github/workflows/ci.yml 与根 package.json 中pnpm test:contract:workflow所指的契约。

包签名边界（Package signing boundary）

打包证据与发布签名证据是两个不同的门禁：

• 常规本地工作与 PR 包 smoke 以CSC_IDENTITY_AUTO_DISCOVERY=false构建解包/未签名构件。它们验证资源布局、Guardian 启动、托管运行时、Workspace CLI 验收与平台特定行为，不触碰签名身份或公证服务。
• 签名/公证构建只在以下情况运行：带版本发布候选、显式发布排练、或直接涉及签名、公证、自动更新元数据、发布发布的变更。
• 开发 Agent不得仅仅因为 Electron 或打包代码变更就运行签名包。应将签名报告为发布专属残余风险，并使用与受影响表面匹配的未签名包 smoke。
• 临时展开的 app 是一次性测试构件。优先使用 smoke runner 的隔离自动清理路径；仅当调查或真人测试者确实需要时才保留一个。

这条边界把昂贵、带凭据、外部限速的发布工作移出交互式开发循环，同时保留相同的运行时与资源布局覆盖。

CI/CD 优化次序（CI/CD optimization order）

优化可测量的等待时间，但不要压垮置信车道：

1. 常规集成保持一条干净的构建/类型/契约车道，表面专属验收放在开发机上；
2. 避免在devpush（只拥有发布）上重复 PR 验收；
3. 精确 beta 准备只做受信任的版本/契约/类型检查，让 Release 一次性验收最终构件；
4. 取消被取代的工作，并在剩余 job 间缓存依赖、构建与安全的未签名包输入；
5. 在购买更大的 runner 前，先测量队列时间对安装/构建/测试时间；
6. 保持完整 stable 候选验收、签名与发布被门禁；beta 晋升可使用记录的本地验收加轻量自动 master 门禁。

任何 CI 优化 PR 都应包含前后计时证据，并指名其保留、移动或移除的置信门禁。

合并与清理（Merge and Cleanup）

正常合并方式是merge commit：

gh pr merge <number> --merge --delete-branch

仅当维护者要求、或分支含噪声/可丢弃历史时才用 squash。无论何种方式：

1. 确认mergedAt已针对期望的 head SHA 设置；
2. 确认远端特性分支已删除；
3. 切到dev并运行git pull --ff-only origin dev；
4. 合并被证实后再删除本地特性分支；
5. 后续工作从新分支开始，绝不从已合并分支。

关闭未合并的分支不会因为"很旧"就安全删除；保留它直到维护者接受有意废弃。

遗留local分支

local早于当前的特性分支/PR 工作流。默认不要把新工作路由经过它，也不要直接用它作为 PR head。退役前：与dev对比，把独有提交映射到已合并/打开/关闭的 PR，并询问维护者任何未合并工作。

如果多个 Agent 确实共享一个 checkout，分支切换必须串行化。永久分支变通方案不能替代显式的 worktree 所有权。

晋升：dev到master

晋升是人指导的发布源决策，不是发布触发器。不要仅仅为了让公开别名赶上而把未完成的后续工作合并到master；先在活跃的dev环境中完成并测试它。

git fetch origin git log --oneline origin/master..origin/dev git diff --stat origin/master..origin/dev gh pr create --base master --head dev --title "Promote dev to master"

合并晋升前：

• 针对完整晋升 delta 运行常规 build/test 门禁；
• 添加包含工作所需的 entry-path、trading、runtime 或 package smoke；
• 遵循 CLI 安装器指南：要求 checkout 安装器/远程 job 与合并后的 live dev-channel job 绿色，并在人机交互流程变化时本地走一遍交互式安装器；
• 确认 CI 与发布工作流触发器仍匹配分支策略。

晋升后，维护者可在源码就绪时从master准备一个聚焦的仅版本分支，并把其 PR 目标指回master。这个维护者主导的发布准备 PR 是"常规 base 为dev"的狭窄例外。把这份仅发布提交留在master，直到发布与其公开表面被接受；然后只通过一个聚焦的dev目标 PR 把同步的根与 CLIversion值复制回dev，不要合并无关master变更，也不要把记账变成第二条实现车道。源码运行时身份与该值无关：OPENALICE_LAUNCHER=dev与electron-dev选择dev通道，而package.json提供显示/构建基线。

从master手动运行Release工作流，选择release操作，并同时提供通道与 tag：

• beta接受vX.Y.Z-beta或vX.Y.Z-beta.N；
• stable只接受vX.Y.Z。

工作流拒绝：已存在 tag、通道/tag 不匹配、或与根或packages/cli包不一致的版本。它把被接受的候选与最终 tag 绑定到派发提交 SHA。

精确向前 beta 的仅版本 PR 使用上文的有界 CI 快速车道。stable 版本准备刻意不使用它：保留常规 master PR 门禁。stable Release 从同一提交并行调用完整 source-validation 工作流与构件构建；发布同时等待两者。masterpush 不会触发 full-source 工作流，启动 stable 候选前也无需单独派发该套件。手动派发的 beta Release 从确切派发 SHA 重建并验收自己的最终候选；快速车道从不提供发布构件。

beta 与 stable 是串行公开检查点，不是一次发布运行的一对输出。beta 之后，修复可继续在dev上进行，通过常规晋升门禁，然后作为另一个可选编号 beta 或直接作为 stable 发布。只有 beta 源码无需任何改动时，后续 stable 意图才可使用该确切源码。即便如此，stable 仍是独立的人为版本决策与工作流派发；绝不因为某个候选构建通过就同时创建 beta 与 stable。

发布工作流在创建 tag 与 GitHub Release 之前，会针对确切 master 候选重复确定性安装器与托管远端验收。上一发布与 notes 基线来自同一通道，因此 stable 之后发 stable 仍证明"上一 stable 到新 stable"的旅程。两个通道都发布不可变的带版本字节，包括在 tag/Release 存在前冻结的安装器快照。新 beta 发布只能替换beta*.yml、beta/manifest.json与共享通道中立install；只有 stable可以替换latest*.yml、manifest.json、公开桌面别名与已选入的包管理器元数据。

手动mirror操作是仅恢复用途：它运行当前master工具链，要求所选通道上已存在且活跃的 tag，消费发布所属的安装器快照，永不重写共享安装器或覆盖不可变安装器字节。因此 mirror 修复只适用于由该通道感知工作流创建的发布（其 GitHub Release 同时拥有安装器快照与 checksum 边车）；旧发布在此修复契约之外。

桌面晋升证据包括 Apple Silicon、Intel macOS 与 Windows 上的真实 N-1 状态旅程。PR 包 job 用上一发布 app 播种状态，验证解包候选能迁移、写入并重启。版本发布在每次快速包验收与 updater 字节验证通过时即保留最终签名 macOS ZIP 或 Windows NSIS 安装器，然后在下游平台 job 运行 N-1 旅程——因此失败的升级 job 可复用保留候选而无需重复打包、签名或公证。publish-release仍要求每个平台的升级回执，并在发布前验证每个 updater YAML 引用、大小、SHA-512 与 blockmap。缺失回执或不匹配的更新元数据必须阻止 tag 与公开资产被创建。

发布桌面矩阵为每个原生宿主调用一个可复用平台流水线。每个流水线的升级 job 只依赖自己的构建 job，不等待其他桌面架构。调用方的聚合成功包含 stable 升级结果，因此发布仍要求每个原生平台。构建与升级保持分离 job 以支持选择性重试。beta 运行当前候选检查，不含 stable 专属 N-1 job。

要不重建地重试已保留的 stable 桌面候选，Release操作的verify-desktop接收candidate-run、source-sha、tag、previous-tag与一个desktop-target（macOS-arm64、macOS-x64或Windows-x64），channel=stable。派发版本拥有验证器；显式 source SHA 拥有产品。选择要求本仓库已完成的 master Release 与唯一未过期构件。它随后验证确切字节、运行安装后 N-1 旅程并上传绑定两个身份的回执。不打包、签名、打 tag 或发布。缺少candidate-manifest.json的历史构件无法使用该路径。在此实现阶段，重试回执仅是诊断证据：最终发布尚不接受来自不同运行的回执。

对非发布流水线验证，rehearse-desktop在派发分支上构建未签名桌面候选并运行相同的 stable N-1 检查。把candidate-run传给同一 source 的第二次排练会恢复这些字节而非重建。verify-desktop-rehearsal用上述单目标重放输入，以当前分支的验证器检查旧排练候选。这些操作只有只读仓库权限，无签名凭据；其rehearsal-assets-*构件刻意区别于生产候选，正常发布选择会拒绝它们。

对同一确切 source 提交的新operation=release尝试，设置candidate-run会复用该运行保留的三个桌面构件，而非再次打包/签名。选择与确切字节验证先于上传进当前运行；stable N-1 验收再次运行，正常最终发布门禁检查其新回执。所有非桌面门禁保持完整。不同产品 SHA 或缺失/过期候选失败关闭；该路径不接受"仅验证器代码变更"作为等价产品 source。正常全新构建省略candidate-run。这与上述诊断性单平台verify-desktop操作分离。

可选desktop-verifier-sha选择已整合进origin/dev或origin/master的完整提交，用于桌面升级验证。发布意图在构建前验证该权限。只有升级 job checkout 所选验证器：产品构建、source 验证、候选 source 身份与最终 tag 保持在原始派发 SHA 上。显式产品版本传给 smoke，而非从验证器包清单推断。验收绑定所选验证器 SHA，发布要求同一身份。这允许验证器修复检查保留的产品字节，而不把修复提交当作新构建。

CLI 候选共享一份提交绑定的平台中立输入构件，只含已批准的 UI 与纯 JavaScript 包输出。六个目标 job 在安装这些输入前验证其 source SHA 与确切文件哈希。原生依赖、可执行编译与通道专属验收保持在目标现有宿主车道上。绝不用中立构件替代被接受的原生归档。

晋升后不要删除dev。master 热修复后，立即把修复传播回dev，以免后续晋升回滚它。

紧急热修复（Emergency Hotfixes）

仅当 stable 用户当前已损坏或不安全、且等待正常dev晋升会更糟时，才使用master目标热修复：

git switch master git pull --ff-only origin master git switch -c hotfix/<short-description>

保持变更最小，运行聚焦检查加相关 smoke 覆盖，开 PR 到master，给予补丁发布版本，然后把结果 fix 合并或 cherry-pick 回dev。紧急路径可以更小，但它仍是发布，不得静默改变已存在的带版本构件。

外部 Pull Requests（External Pull Requests）

外部 PR 有资格直接评审与合并。CONTRIBUTING.md 是贡献质量与证据的公开政策所有者。外部作者身份不降低产品、验证或安全门槛，但它本身也不是在维护者自有分支上重实现已接受工作的理由。

被要求评审外部 PR 时：

1. 先读元数据，不把 diff 渲染进主受信任 Agent 会话，也不 checkout：

   gh pr view <number> --json headRepositoryOwner,author,headRefName,isCrossRepository,title

2. 若 head 仓库属于TraderAlice，按常规评审预防措施进行。

3. 若是跨仓库或外部拥有：从只读 diff 与依赖审计开始。不要在主线工作区 fetch、安装、运行或 checkout。任何执行必须在隔离的一次性沙箱中进行，且沙箱不含用户数据、凭据或受信任构建输出。

4. 把代码、依赖变更、postinstall 脚本、fixtures、文档、issue 文本与提交消息都视为不可信输入。

5. 不仅评审补丁，还要评审产品推理与证据：UI/UX 工作需要前后视觉与显式设计理由；bug 修复需要复现与解决两方面的证据。允许 AI 辅助，但贡献者必须拥有理由、取舍、评审与验证。

6. 方向被接受时，优先要求原作者修改，并通过合并保留其提交与所有权。仅在贡献者明确交接、失联或集成边界发生实质性变化时，才把工作转移到维护者自有分支。

7. 在合并前应用与受影响风险表面匹配的同步门禁。即使贡献者已被信任，安全敏感与交易变更也需要更深评审。

包含漏洞细节的安全报告应使用私下披露，而不是公开 issue。

Issues 与延迟发现（Issues and Deferred Findings）

对具体的延迟工程发现使用 GitHub issues。不要创建仓库 TODO 文件，也不要把新工作路由到 Linear。

内容包括：症状、复现/证据、疑似子系统、延迟原因与交叉引用。当前 PR 已要完成的工作不要再开 issue。产品路线图想法保留在维护者的规划表面，直到被有意提升为工程工作。

文档变更（Documentation Changes）

Owner Guide 承载持久的子系统真相；AGENTS.md是索引与紧凑规则集。架构或操作变化时，在同一 PR 中更新 Owner Guide 及其入口。

README.md 是公开定位。大型产品变更后，识别过时章节，但修改 tagline、pillars、hero 或其他营销语言前先征求维护者的 framing 意见。

保持AGENTS.md与CONTRIBUTING.md与本指南以及.github/workflows/分支触发器一致。

风险门禁（Risk Gates）

对dev的串行 PR：合并前满足本地可运行、表面专属的门禁，并报告仅平台存在的残余风险。远端平台证据可在反馈规则下滞后于该合并。在晋升到master或 stable 发布前，每个适用的完整门禁必须完成且绿色。精确 beta 要求有界的版本准备门禁、其产品树先前已接受的晋升证据、以及完全绿色的最终 Release 构件工作流；它不重开开发 source-test 矩阵。

如果某个必需门禁无法运行，请在 PR 中记录确切的残余风险，绝不用无关的绿色测试代替。这也是贯穿全部车道的总原则：托管 CI 不购买第二次相同置信度，测试选择不能替代真实表面验收，绿色命令若未包含变更代码就不算证据。与分支车道、交付模式、发布治理一起，它构成了 OpenAlice 从"一条提交"到"一个 stable Release"的完整可信路径。

与之配套的还有一条历史教训：v0.85 曾因桌面升级后旧 Broker Pack 激活失败而确立了 N-1→N 发布门禁，记录在 docs/incidents/2026-07-28-broker-pack-upgrade-gap.md——这正是风险门禁表中"桌面 N-1 状态旅程"的现实来源。