03. AI 辅助开发工作流程
翻译说明： 本页是与 英文源规格 一一对应的机器辅助翻译。代码、协议字段和标识符保持原文；如翻译与英文源事实有歧义，以英文版本为准。
范围：致力于 PI-Desktop 的人工智能代理和人类合作者 状态：已接受 交叉引用：00 基线 · 决策日志 · 接受标准 · e2e-测试计划 · 更改检查表 · ADR索引
1. 核心不可变规则
下列规则管理着 PI-Desktop 代码库和文档的每次更改。R1–R4 复述 AGENTS.md 中五条编号的不可变规则（R4 同时涵盖合并回 main 与清理工作树两条）；R5 与 R6 复述其 GitHub issue 与 pull request 处理章节。如果没有明确的人工干预，代理就无法放松它们。
R1 — 规格优先/规格同步
如果不更新相应的规范，行为不会发生变化。
- 改变可观察行为的每个代码、配置或 UX 更改都必须在更改之前或同时更新相关的
docs/spec/文档。 - 架构边界变更（进程模型、IPC 合约、存储所有权、安全边界）也需要 ADR — 请参阅
docs/adr/README.md。 - 保留行为和 API 合约的纯重构不需要规范更新，但仍必须提交（R2）。
R2 — 每次更改提交
每个已完成的逻辑更改都必须进行 git 提交。
- 没有大量未提交的工作。每个逻辑工作单元——一个功能、一个修复、一个规范更新、一个杂务——都有自己的提交。
- 会话结束时未提交的工作违反了此规则。
- 如果更改不完整，请将其作为带有
WIP:前缀的草稿提交或回滚。
R3 — E2E 覆盖文档
每个影响用户可见或协议可见行为的 feature/fix 都必须更新 e2e 测试文档。
- “用户可见”：最终用户看到或与之交互的任何内容（UI、CLI 输出、对话框、通知）。
- “协议可见”：IPC 消息、RPC 方法、插件 API 表面、事件负载。
- 在
06-delivery/04-e2e-test-plan.md中记录场景——甚至在自动化测试存在之前。 - 仅内部更改（日志记录格式、内部变量重命名）不需要 e2e 文档更新。
R4 — 请求分支+工作树+合并门
每个开发请求都必须从当前
origin/main的专用分支和工作树开始。打开或更新 PR 时，该 head 必须包含最新的origin/main。
- 编辑前保留未提交工作，获取
origin/main，工作树干净时快进本地main，并从该提交创建请求分支和工作树。不得为了开新请求而移动、藏匿或覆盖主工作区里的现有工作。 - 每个请求使用一个短期分支，命名为
<type>/<short-description>。 - 每个请求使用一个专用工作树。不要在主工作区或别人的工作树里实现新请求。
- 在安全的情况下复用主工作区的宿主开发环境：工具链、兼容的
node_modules、Electron、Rust/Cargo 目标、包存储、缓存和忽略的本地配置。 必要时通过引用或链接使用，不要为 E2E 单独安装第二套环境。 - 禁止在
main上开发或直接推送。 - 仅请求提交并不授权远程发布。未获远程授权时，停在任务分支提交；不要为了跑 E2E 把任务合进本地
main。 - 打开或更新 PR/MR 之前，获取
origin/main并确认它是请求 head 的祖先（git merge-base --is-ancestor origin/main HEAD或pnpm check:pr-base）。私有分支用 rebase；已共享且不宜改写历史时用非破坏性合并。不得打开或更新落后于origin/main的 PR。 - 获准远程交付后，按
AGENTS.md的固定顺序：相对最新origin/main刷新，在工作树跑 task-candidate E2E，推送请求分支，打开面向main的 PR/MR，通过远程检查（含 PR-base 门）和审查后合并，再同步本地main。 - 合入
main后立即删除自己的工作树和已合并分支。 - 若用户要求启动应用，从已集成的
main构建并启动。
R5 — 先核实链接的 GitHub issue，再回复并关闭
链接的 GitHub issue 在被独立证实存在之前，还不是一项任务。结论明确后，必须在该 issue 上回复并关闭。
当用户提示包含 GitHub issue URL，或本仓库中无歧义的 issue 编号时，适用本规则。
- 在为所声称的问题创建工作树或修改文件之前，先获取 issue（标题、正文、标签、评论和状态）。
- 对照当前代码库独立核实该主张。对于缺陷：复现，或给出具体的代码/规范证据。对于功能或改进：确认所请求的行为确实缺失或不完整，且在范围内。
- 在核实确认问题存在之前，不得开始实现。
- 若问题不存在（已修复、无效或理解有误）：用核实证据评论；结论明确时关闭 issue。若核实无法定论：评论已尝试的内容并保持 issue 打开。
- 若问题存在：遵循 R4，实现最小一致的变更，并在请求合并到本地
main之后，用处理结果评论并关闭 issue。 - 用原始 issue 标题和正文的语言撰写 GitHub 评论。代码、提交、规范和仓库内其他文档仍使用英文。
- issue 链接仅授权评论并关闭该 issue。它不授权 git push。远程发布仍按 R4 和
AGENTS.md选择加入。 - 不得评论或关闭无关 issue。除非用户明确要求，否则不得重新打开已关闭的 issue。
R6 — 链接 PR 必须根治问题且改动最小才可合入
链接的 GitHub pull request 只有真正从根上消掉所报告的失败路径、且改动是最小一致修复时才可合入。方向正确不够。完整性细枝末节可以合入后再做；没修完的问题不能合。
当用户提示包含 GitHub pull request URL，或本仓库中无歧义的 pull request 编号时，适用本规则。
- 在创建替代实现或要求重写之前，先获取 pull request（标题、正文、文件、提交、评论、检查、草稿状态、base/head 以及关联 issue）。
- 独立核实以下全部成立：
- 所报告的问题真实且在范围内（与 R5 同一标准）。
- 该变更必须从根上修复所报告的问题，且是最小一致改动——不是旁边的症状、纯文档重述、配置契约测试，或留下原路径的半截绕过。
- 多出来的文件、重构和规格表演不能弥补没修完的问题。方案仍须与基线、安全边界和架构兼容（或是有规格依据的正当修订）。
- 当 (1)–(3) 成立时，不得把该 pull request 重写为替代实现、因细枝末节关闭它，或要求贡献者从头再来。
- 若 (1)–(3) 成立：
- 先合入该 pull request，并保留贡献者的提交。使用仓库允许的、能让贡献者作为合入工作作者的合并策略。
- 额外测试覆盖、文档、命名清理、格式化和其他非阻塞打磨可以作为后续工作，前提是它们不是证明根因修复所必需的。构建、类型检查、相关既有测试、必需的 E2E、安全、数据安全、协议兼容性和合并冲突失败仍然是落地阻塞项。
- 会破坏
main的落地阻塞（无法编译、使改动区域的现有测试失败、或存在合并冲突）可以在作者工作之上追加最小提交以便合入。不得 squash 掉作者。不得改写设计。不得把 diff 扩到根因修复之外。 - 该 pull request 进入
main之后，按 R4 从更新后的main做任何后续完善。 - 用该 pull request 的原文语言评论：肯定贡献、说明已合入的内容，并列后续工作（如有）。
- 若 (1)–(3) 不成立，或存在危害阻塞（密钥、沙箱或权限绕过、恶意或明显破坏性改动、超出范围地推翻冻结决策、无关的顺便改动）：不得合入，不得以「方向没问题、以后再补」为由通过，并用该 pull request 的原文语言评论证据。作者的方案若能真正修到根因，优先做最小补完。除非用户要求接管，否则不得假装该 pull request 从未存在而悄悄重做同一想法。
- 不得合入作者尚未标为 ready 的草稿 pull request，除非用户明确要求合入该草稿。评论审查结果并等到它 ready。
- pull request 链接在本规则适用时，授权审查、评论并合入该 pull request。它不授权对贡献者分支 force-push，也不授权发布无关分支。后续工作仍遵循 R4 的远程发布选择加入规则。
- 不得评论或合入无关 pull request。已合入的 pull request 不再重新打开；剩余缺口转为普通后续工作。
- 当同时链接了 issue 和 pull request 时，R6 适用于该 pull request；R5 在合入结果之后仍适用于该 issue。
R7 — 原则成立的代码 pull request 必须通过相关 E2E
代码 pull request 未成功通过相关 E2E 验证时不得合入。
此规则适用于修改可执行或影响运行时的内容，包括 apps/、packages/、 crates/、运行时脚本、构建或 CI 配置、打包行为、协议行为和持久化数据。 如果文档更改不影响可执行行为，则仅文档更改可豁免。
代码 pull request 必须执行 E2E。根据 04-e2e-test-plan.md 中的回归面选择套件； 构建、类型检查、lint、单元测试、集成测试、人工审查和源码检查都不能替代相关 E2E。
代码变更集成到本地 main 时也适用同一门禁。必要的验证和 E2E 属于获准集成流程的一部分， 无需再次请求单独的测试授权。
如果当前环境无法运行必需套件，必须记录原因并保持分支未合入、PR/MR 为 Draft / Not Ready。 在具备条件且可信的环境中通过该套件之前，任何交付路径都不得合入。必需 E2E 失败是落地阻塞项。
GitHub issue 模板
.github/ISSUE_TEMPLATE 是唯一公开入口（blank_issues_enabled: false）。 英文是标签源语言；中文写在同一字段上。
- Bug 反馈必填：描述、复现步骤、预期行为、实际行为、应用版本和操作系统。日志、其他环境信息和截图选填。从应用内「设置 → 信息」打开时会预填版本、操作系统和环境（D313）。
- 功能请求必填：问题和期望改动。其他方案和补充信息选填。
不得削弱这些必填项。空白 issue 保持关闭。
2. 开发循环
每一个变化都遵循这个顺序。如果实施过程中出现新的需求，则可以重复步骤。如果提示包含 GitHub issue，必须在步骤 1 之前完成 R5 核实。如果提示包含 GitHub pull request，必须在开始替代实现或后续完善之前完成 R6 根因审查（只有真正修好且改动最小时才合入）。
0. If a GitHub issue is linked: verify the claim (R5) before any implementation
0b. If a GitHub pull request is linked: review root cause and minimality (R6); merge only when it actually fixes the problem; start follow-up only after it is in `main`
1. Sync main + create a request branch and worktree
2. Read baseline + relevant specs
3. Plan change + list impacted specs and necessary validation
4. Implement
5. Update specs / ADR / decisions-log if needed
6. Update or add e2e scenarios when R3 applies
7. Run targeted local checks necessary for the change's risk and the relevant
E2E suites required for code-bearing main integration
8. Commit with conventional message
9. Update BOARD if milestone-related
10. If remote delivery is authorized: push branch + open PR/MR to main
11. Complete requested main integration after applicable gates; verify and clean up
12. If launch was requested: build and start from integrated main一步一步
| 步骤 | 行动 | 输出 |
|---|---|---|
| 0. Issue 核实 | 当链接了 GitHub issue 时，先获取并独立核实所报告的问题是否存在。若不存在则停止实现（评论，并仅在结论明确时关闭）。 | 已核实的 issue，或评论以及关闭/保持打开的决定。 |
| 0b. PR 审查 | 当链接了 GitHub pull request 时，先获取并独立核实它是否从根上修好所报告的问题、且改动最小。成立才合入；仅在它进入 main 之后开始后续完善。不成立则停止（评论，不重写）。 | 已合入的贡献者 PR 加后续计划，或评论且不合入。 |
| 1.分支+工作树 | 保留现有工作，从 origin/main 进行更新，并在专用工作树中创建专用请求分支。在安全的情况下重复使用主要结账环境。 | 当前 main 上的独立任务文件具有一致的开发环境。 |
| 2.阅读 | 阅读 00-baseline.md 以及与变更区域相关的任何规范。 | 约束的心理模型。 |
| 3. Plan | 描述预期的改变。列出需要更新的每个规范、ADR 和 e2e 场景，并评估是否需要本地验证。 | 变更计划+影响和验证列表。 |
| 4.实施 | 编写代码、配置或资产。 | 更改了文件。 |
| 5.规格同步 | 根据影响列表更新规格。如果是建筑，请添加 ADR。如果实现默认值发生更改，请更新 decisions-log.md。 | 更新了 docs/spec/* and/or docs/adr/*。 |
| 6。 E2E 文档 | 当 R3 应用时，添加或更新 04-e2e-test-plan.md 中的场景条目并链接到验收标准 ID (A–H)。否则，确认不需要场景更新。 | 更新了 e2e 测试计划，或确认不适用。 |
| 7.验证 | 使用变更风险和回归范围选择最小的有用本地检查。每个代码变更的本地或远程 main 集成都必须在可合入前运行相关 E2E；无法运行的必需套件必须记录为未运行并阻止合入。 | 有针对性的检查和 E2E 结果，或明确的环境限制。 |
| 8.提交 | 使用常规消息进行 Git 提交（请参阅第 4 节）。 | 一项或多项提交。 |
| 9.董事会 | 如果更改完成了里程碑交付，请更新 docs/project/BOARD.md。 | 更新了董事会。 |
| 10.远程交付 | 仅在获得远程发布授权时，推送请求分支并创建面向 main 的 PR/MR。 | 可审查的远程变更，列出了受影响的规格和验证；或明确的本地交付路径。 |
| 11.集成 | 完成 R4 要求的集成，满足验证和适用的远程门禁；确认本地 main（远程交付时还包括远程 main）包含预期提交，并清理工作树和分支。 | 请求已完成集成，或记录明确的阻塞原因/用户限定的交付范围。 |
| 12.启动 | 用户要求时，从已集成的 main 工作树和开发环境构建并启动。 | 运行中的应用包含已交付的变更。 |
本地验证和 E2E 执行策略
- 本地验证是基于风险的，而不是自动先决条件 交货。通常仅进行文档更改和低风险机械编辑 不需要本地测试或检查，直接按 R4 进入获准的交付路径。无需单独批准或豁免即可跳过不必要的检查， 但代码变更仍必须通过 E2E 合并门禁。
- 材料回归风险的变化，包括安全边界， 协议契约、数据迁移、构建配置或广泛共享 行为，通常需要最小的目标非 E2E 验证 解决该风险。完整的本地套件不是默认的。
- E2E 场景文档和 E2E 执行是不同的问题。 R3依然 需要场景更新以实现用户可见或协议可见的行为。
- 每个代码 PR 或本地
main集成都必须运行至少一个相关 E2E 套件，并运行受影响回归面所需套件的并集。可用命令由根目录package.json和04-e2e-test-plan.md中的选择说明定义。 - task-candidate E2E 可以使用请求工作树中的源码，但必须使用 R4 所述的宿主依赖/运行时环境。不要每次运行都重新安装仓库环境；仅当宿主依赖缺失或不兼容时才安装或重建，并记录原因。临时 profile、数据、socket、端口、日志和工件仍须与宿主可变运行时状态隔离。
- 开发迭代仍然基于风险：小改动不需要每次都运行全部套件，但合入前所有相关 E2E 必须通过。
- 如果本地环境无法运行必需套件，必须记录套件、原因、替代验证和剩余风险。在具备条件且可信的环境中通过前，分支不具备合入条件。
- 托管平台在运行后自动启动所需的 E2E 作业 推或 PR 仍然是合并门。观察并报告结果；仅在托管平台或仓库工作流要求时重新运行。
市场/更新诊断门
插件更新事故在改代码之前必须走证据优先的提示流程：
- 记录确切的插件 ID、已安装版本、显示版本、预期发布版本、目录 URL 和观察时间。
- 抓取线上目录并检查确切条目，然后分别独立检查本地目录缓存和已安装注册表。
- 划分失败边界：发布者/目录数据、抓取/缓存回退、宿主版本比较、IPC 传播，还是渲染器呈现。
- 运行
pnpm check:marketplace -- --url <catalog-url> --plugin <id>。缺少shasum、url、正数sizeBytes或permissions属于发布数据失败，不是渲染器过期的证据。不完整的发布仍然不可安装。 - 在修改宿主或渲染器代码之前，先用包含未排序版本和不完整元数据的 fixture 复现。
代理必须说明哪个边界失败，以及哪些证据排除了其他边界。客户端回退可以保住安全的发现能力，但不得用来掩盖无效的市场发布。
3. 规格更新矩阵
哪些变更类型需要更新哪些文档。
| 变更类型 | 规格更新 | ADR | 决策日志 | E2E 文档 | 董事会 |
|---|---|---|---|---|---|
| 新功能（用户可见） | 相关域规范 | 如果建筑边界 | — | 新场景 | 如果里程碑可交付 |
| 错误修复（用户可见） | 相关规范（如果行为已明确） | — | — | 新的或更新的场景 | — |
| 错误修复（内部） | — | — | — | — | — |
| 重构（保留行为） | — | — | — | — | — |
| 建筑变革 | 相关规格+基线 | 新 ADR | 如果默认更改则更新条目 | 更新受影响的场景 | — |
| 新的 IPC/RPC 方法 | 03-runtime/01-ipc-protocol.md 或 06-host-rpc-protocol.md | 如果合同边界 | — | 新协议场景 | — |
| 插件 API 添加 | 07-plugins/03-plugin-api.md | 如果边界改变 | — | 新插件场景 | 如果M4可交付 |
| 安全变更 | 05-security/01-security.md | 如果边界改变 | 如果 D001–D010 被触摸则更新 | 新安全场景 | — |
| 用户体验变化 | 相关 04-ux/ 规范 | — | — | 新的UI场景 | — |
| 仅规格更新 | 规范本身 | — | — | — | — |
| 杂务（部门、工具） | — | — | 如果模具决定 | — | — |
| 应用程序版本发布/稳定标签 | 06-delivery/06-release-runbook.md（打标签前的强制版本面门禁：双语 packages/shared/src/changelog.ts 及其测试清单、全部工作区/Cargo/APP_VERSION 版本号，以及 README.md + README.zh-CN.md 中的版本线） | — | 如果发布政策发生变化 | 确认 E2E-067B 仍然准确 | 如果里程碑船 |
4. Git 提交规则
4. 1 常规提交
格式：type(scope): description
| 类型 | 用于 |
|---|---|
feat | 新功能 |
fix | 错误修复 |
docs | 仅文档更改 |
test | 添加或更新测试 |
chore | 构建、部门、工具、CI |
refactor | 代码重构，没有行为改变 |
perf | 性能提升 |
build | 构建系统或外部依赖项更改 |
ci | CI/CD 配置更改 |
范围是可选的，但受到鼓励 - 例如feat(host-core):、fix(ui):、docs(spec):。
4. 2 语言
- 提交消息：仅限英语（符合基准语言政策）。
- 主体：可选；用于不明显的上下文。
4. 3 每次提交一个逻辑更改
- 喜欢小而集中的承诺。
- 与代码更改紧密耦合的规范更新应该在同一个提交中。
- 纯文档更改（规范重写、ADR）可能是单独的相邻
docs:提交。
4. 4 永不提交
- 秘密、API 密钥、令牌、密码
- 仅限本地数据（用户配置、会话数据、日志）
node_modules/，构建工件，发布包- 生成的文件应根据 CI 重建
4. 5 预提交清单
提交之前，请验证：
- 变化是一个逻辑单元（或明确划分）。
- diff 中没有秘密或本地数据。
- 根据 §3 矩阵更新规格。
- 如果行为发生变化，则更新 E2E 文档。
git diff --stat评论——没什么意外的。 6.提交消息遵循常规格式。
5. 分支模型
存储库使用强制请求分支和工作树工作流程：
main始终可部署，并且是受保护的集成目标。做 不开发、提交或直接推动它。- 请求分支和工作树对于每个新请求都是强制性的， 包括文档、杂务和小修复。创建每个分支和工作树 最新的
main，然后在合并分支后立即删除两者 进入main。 - 分支名称 使用
<type>/<short-description>和小写字母， 烤肉串案例描述。允许的类型前缀镜像§4.1。 - 不存在长期的开发分支。每个请求都会得到一个新的分支； 旧的请求分支不得重复用于不相关的工作。
- 主结账拥有默认开发环境。 请求 工作树重用其工具链、包管理器存储、缓存并忽略 安全的本地配置。请求可能会创建隔离的本地状态 当共享不安全或不兼容时，但该状态仍被忽略 并且不得泄漏到提交中。
- 交付遵循 R4 的授权边界及其固定顺序。 仅提交的交付停在工作树里的请求分支提交。获准远程交付时，先相对最新
origin/main刷新（pnpm check:pr-base），在工作树跑 task-candidate E2E，再推送并打开 PR/MR，合入远程main后同步本地。明确要求仅分支或草稿时，以较窄的范围为准。不得打开或更新落后于origin/main的 PR。
典型请求开始（从主结帐运行；选择其外部的路径）：
git status --short
git fetch origin main
git worktree add -b <type>/<short-description> <worktree-path> origin/main如果在干净的主工作树中签出 main，则 git switch main 加上 git pull --ff-only origin main 应在 git worktree add 之前运行。如果 主工作树不干净或者位于另一个分支上，保持其不变并且 直接从获取的 origin/main 创建请求工作树。从来没有 仅仅为了满足这一点而丢弃、隐藏、移动或覆盖不相关的工作 序列。
环境重用是特定于资源的。包管理器存储和语言 工具链通常会自动共享。忽略本地配置或 兼容的依赖树可以从主引用或链接 当任务需要时结账。构建可以竞争、可变运行时的输出 数据和不兼容的依赖树必须保持工作树本地。
典型的已授权 GitHub 交付（需要时使用托管平台的等效平台；合并后从干净的主结账同步 并清理）：
# from the request worktree
git fetch origin main
git rebase origin/main # private branch; do not force-push a shared branch
pnpm check:pr-base
# run the required task-candidate E2E suites for this change (R7)
git push -u origin <type>/<short-description>
gh pr create --base main --head <type>/<short-description>
gh pr checks --watch
gh pr merge --merge
git fetch origin main
# from a clean primary checkout
git switch main
git merge --ff-only origin/main
git worktree remove <worktree-path>
git branch -d <type>/<short-description>
git worktree prune
git push origin --delete <type>/<short-description>远程合并后，尽可能快进同步本地 main。确认请求提交已在远程 main 且没有仅本地提交后，才把本地 main 重置到 origin/main。
如果主工作区无法做这次同步，另开一个短命的 main 工作树，不要打扰无关工作。
不要为了跑 E2E 或开 PR 把请求分支合进本地 main。无远程 PR/MR 的本地交付留在请求分支上，直到用户明确要求集成。
拆卸前工作树必须清洁；提交或丢弃请求自己的 首先进行剩余的更改。使用 git branch -d 而不是 -D 因此未合并 分支拒绝删除。如果 git worktree remove 报告工作树为脏 或锁定，解决该状态而不是强制删除，并且永远不要删除 另一个请求的工作树。
拆卸前工作树必须清洁；提交或丢弃请求自己的 首先进行剩余的更改。使用 git branch -d 而不是 -D 因此未合并 分支拒绝删除。如果 git worktree remove 报告工作树为脏 或锁定，解决该状态而不是强制删除，并且永远不要删除 另一个请求的工作树。
6. 完成的定义
在遵守明确的“仅分支”或“草稿”范围限制的前提下，满足所有适用条件时，更改才算完成：
- 根据最新的请求创建专用请求分支和工作树
main。 - 代码（或文档）实施计划的变更。
- 所有受影响的规格均已更新。
- 记录 E2E 场景（或根据第 3 节确认不需要）。
- 必要的有针对性的本地验证和代码变更所需的 E2E 通过；若环境受限则记录限制并在 E2E 通过前保持不可合入；自动触发的远程闸门也通过。
- 改变是通过传统的信息来实现的。
- 如果里程碑交付完成，则更新董事会。
- 提交中不存在任何机密或本地数据。
- 按用户要求的提交/推送交付已集成到本地
main；获得远程交付授权时，PR/MR 已审核并合入远程main，且本地main包含已落地的变更。 - 集成后已在
main中确认预期提交，且请求工作树已移除、合并的请求分支已删除。 - 若链接了 GitHub issue：在实现前已核实该主张；issue 收到以其原文语言撰写的评论；结论明确时已关闭该 issue。
- 若链接了 GitHub pull request：已审查根因门槛；仅在真正修好且改动最小时合入；后续完善在合入之后落地；未因细枝末节丢掉贡献者的工作。
发布/版本标签门
当更改是稳定应用程序版本发布（版本提升 + 标签）时，完成的定义还要求在 打标签之前，所有带版本号的位置都描述新版本：packages/shared/src/changelog.ts 中的已发货语言应用内变更日志条目（英语和每个已发货产品语言，亮点条数一致）及其 changelog.test.ts 清单、每个工作区 package.json（含 docs/package.json）、 Cargo 工作区版本与 host-core 锁文件条目、APP_VERSION，以及 README.md + README.zh-CN.md 中声明的版本线。node scripts/check-release-docs.mjs 必须 通过；scripts/release.mjs 会执行它，未通过则拒绝打标签。参见 06-release-runbook.md §4.1、 D164 与 D260。 GitHub 发行说明并不能替代。
7. 禁止的做法
| 练习 | 为什么 |
|---|---|
| 犯下秘密 | 违反安全规定 |
| 未提交的较大差异 | 违反 R2；粒度损失 |
| 无需更新规范即可更改行为 | 违反 R1；规格变得不可靠 |
| 跳过 e2e 文档以进行用户可见的更改 | 违反 R3；可追溯性差距 |
代码变更未成功通过相关 E2E 就集成到本地或远程 main | 违反 R7，跨进程行为未经验证 |
| 将完整的本地 test/check 套件视为自动预推送要求 | 忽略基于风险的验证并在没有必要证据的情况下延迟交付 |
直接在 main 上开发、提交或推送 | 违反 R4；绕过隔离和审查门 |
| 在主结帐或另一个请求的工作树中开发新请求 | 违反 R4；混合任务文件和本地状态 |
| 重用请求分支来完成不相关的工作 | 混合请求范围并削弱可追溯性 |
打开或更新 head 落后于 origin/main 的 PR/MR | 违反 R4；审查会从过期基线开始 |
| 用户要求提交/推送交付时停在任务分支提交或推送 | 违反 R4，除非用户明确限定为分支或草稿交付 |
| 将合并的请求工作树保留在磁盘上 | 违反 R4；陈旧的工作树积累并导致交叉请求污染 |
| 修改基线冻结决策，无需 ADR + 版本升级 | 基线被冻结；变更需要正式流程 |
| 提交 CI 应重建的生成工件 | 回购膨胀、合并冲突 |
| 在一次提交中混合多个逻辑更改而没有明确的消息 | 历史粒度的损失 |
| 未核实问题是否存在就开始实现链接的 GitHub issue | 违反 R5；把工作浪费在无效或已修复的主张上 |
| 关闭链接的 GitHub issue 时没有以其原文语言撰写的评论 | 违反 R5；没有公开记录处理结果 |
| 关闭、重写或要求重启已经根治问题且改动最小的链接 pull request（仅因细枝末节） | 违反 R6；丢掉贡献者的工作 |
| 仅因缺失规格、额外测试、风格或智能体工作流完整性而阻止合入已根治问题的链接 pull request | 违反 R6；那些是合入后的后续工作 |
| 合入只是方向正确、仍留下原失败路径、或未经说明就大于最小修复的链接 pull request | 违反 R6；方向正确不够 |
| 合入引入危害阻塞的链接 pull request | 违反 R6 |
| 为落地链接 pull request 而对贡献者分支 force-push | 违反 R6；落地修复加在作者提交之上 |
在不为每个已发货语言更新 packages/shared/src/changelog.ts 的情况下标记稳定的应用程序版本 | 违反 D164/D345/发布操作手册；该语言版本的应用内新增功能为空 |
在 README.md / README.zh-CN.md 仍声明旧版本线时标记稳定版本，或用 --skip-docs-check 绕过 scripts/check-release-docs.mjs | 违反 D260/发布操作手册；已发布文档宣传的版本与实际发布不符 |
在必需的 E2E 于已集成的本地 main 上运行之前推送请求分支或创建 PR/MR，或在缺少该结果（已记录的 NOT RUN 限制除外）的情况下宣告含代码变更已交付 | 违反 R7 的固定顺序；审查将从未经验证的提交开始 |
8. 此工作流程的验收标准
在以下情况下，此工作流程规范本身被接受：
- [ ] R1/R2/R3/R4/R5/R6/R7 已明确说明并与相关规范交叉链接。
- [ ] 开发循环由
AGENTS.md记录和引用。 - [ ] 规范更新矩阵涵盖基线中的所有变更类型。
- [ ] Git 提交规则与现有存储库提交样式匹配（
docs:、chore:）。 - [ ] 每个请求都需要使用创建的专用分支和工作树 从当前的
main开始。 - [ ] 请求工作树在安全的情况下重用主要结账环境 无需提交本地环境状态。
- [ ] 用户请求提交/推送时，无需再次确认即可完成本地
main集成；明确的仅分支或草稿范围优先。 - [ ] 远程发布需要授权，并且在远程
main集成和同步本地之前通过 PR/MR 门禁。 - [ ] 工作树删除和分支删除需要在执行完之后立即进行。 请求分支合并到
main中，包括本地合并传递。 - [ ] 代码 PR 和本地
main集成都必须执行相关 E2E，R3 中的 E2E 场景文档仍然是强制性的。 - [ ] 本地验证是基于风险的；不必要的检查可以被跳过而无需 阻止提交、推送或 PR/MR 创建。
- [ ] 完成的定义是完整且可操作的。
- [ ] 禁止行为列表涵盖已知的风险领域。
- [ ]
AGENTS.md指向此文档、04-e2e-test-plan.md和05-change-checklist.md。 - [ ] 链接的 GitHub issue 必须在实现前核实，然后以其原文语言评论，并在结论明确时关闭。
- [ ] 链接的 GitHub pull request 只有根治问题且改动最小才可合入；不得因细枝末节丢掉贡献者的工作。
- [ ] 更新所有索引（NAV、交付自述文件、规格自述文件、文档自述文件、董事会）。