03. AI 辅助开发工作流程
翻译说明： 本页是与 英文源规格 一一对应的机器辅助翻译。代码、协议字段和标识符保持原文；如翻译与英文源事实有歧义，以英文版本为准。
范围：致力于 PI-Desktop 的人工智能代理和人类合作者 状态：已接受 交叉引用：00 基线 · 决策日志 · 接受标准 · e2e-测试计划 · 更改检查表 · ADR索引
1. 核心不可变规则
这四项规则管理着 PI-Desktop 代码库和文档的每次更改。如果没有明确的人工干预，代理就无法放松它们。
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 — 请求分支+工作树+合并门
每个新请求从专用分支上的专用工作树中的
main开始，仅在其 PR/MR 合并到main后结束。
- 在编辑之前，保留任何现有的未提交工作，获取
origin/main， 当工作树干净时快进本地main，并创建一个新请求 来自最新提交的分支和工作树。小学现有工作 决不能仅仅为了开始新的操作而移动、隐藏或覆盖结账 请求。 - 每个请求使用一个短期分支。命名它
<type>/<short-description>，其中type匹配常规更改 实用时键入，例如feat/provider-import或docs/request-branch-workflow。 - 每个请求使用一个专用工作树。不要在 主要结账或重用另一个请求的工作树。
- 在安全的情况下重用主要结帐的开发环境：已安装 工具链、包管理器存储、构建缓存和忽略本地 环境配置仍然是规范环境。参考或 需要时将这些资源链接到请求工作树中；请勿复制 环境状态写入跟踪文件。安装或生成worktree-local 仅当隔离或版本兼容性需要时才声明。
- 禁止对
main进行开发提交和直接推送。 - 开发和任何必要的本地验证后，推送请求 分支，打开一个针对
main的 pull/merge 请求，并完成所有必需的操作 远程检查和审查。 - 将已批准的 PR/MR 合并到
main，移除请求工作树，并删除 请求分支。如果 身份验证、权限、所需的远程检查或所需的审查会阻止 合并，报告阻塞者；请求未完成。 - 工作树清理是强制性的并且是立即的。一旦请求分支 集成到
main— 包括请求时的本地main合并 在没有远程 PR/MR 的情况下交付 — 删除工作树并删除合并的 分支。合并的请求不得在磁盘上留下工作树。仅删除您的 自己的工作树和分支，并且只有在验证合并提交之后 存在于main中。
2. 开发循环
每一个变化都遵循这个顺序。如果实施过程中出现新的需求，则可以重复步骤。
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 the smallest targeted local checks necessary for the change's risk; skip
local validation when it is unnecessary and continue to step 8. Run E2E only
when explicitly requested by the user
8. Commit with conventional message
9. Update BOARD if milestone-related
10. Push branch + open PR/MR to main
11. Pass remote gates + merge + remove worktree and branch一步一步
| 步骤 | 行动 | 输出 |
|---|---|---|
| 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.如有必要请验证 | 使用变更风险和回归范围来决定是否需要进行本地验证。如果是，请运行最小的相关非 E2E 检查集，例如重点 lint、类型检查、unit/integration 测试或构建。如果不是，则跳过本地验证，直接继续提交交付。仅当用户明确请求 E2E 验证时才运行 E2E。 | 有针对性的检查结果，或评估为不必要的验证。 |
| 8.提交 | 使用常规消息进行 Git 提交（请参阅第 4 节）。 | 一项或多项提交。 |
| 9.董事会 | 如果更改完成了里程碑交付，请更新 docs/project/BOARD.md。 | 更新了董事会。 |
| 10.打开 PR/MR | 推送请求分支并打开针对 main 的 pull/merge 请求。 | 可审查的远程变更，列出了受影响的规格和验证。 |
| 11.合并 | 通过所需的远程检查和审查，合并到 main，删除请求工作树，并删除请求分支。 | 更改集成到 main 中；任务工作树和请求分支已删除。 |
本地验证和 E2E 执行策略
- 本地验证是基于风险的，而不是自动先决条件 交货。通常仅进行文档更改和低风险机械编辑 不需要本地测试或检查，直接进行提交、推送和 PR/MR 创建。无需单独批准或豁免即可跳过它们。
- 材料回归风险的变化，包括安全边界， 协议契约、数据迁移、构建配置或广泛共享 行为，通常需要最小的目标非 E2E 验证 解决该风险。完整的本地套件不是默认的。
- E2E 场景文档和 E2E 执行是不同的问题。 R3依然 需要场景更新以实现用户可见或协议可见的行为。
- 代理不得主动运行 E2E 套件或命令，包括
pnpm test:e2e*、剧作家套件、Electron 探针或现场代理 E2E 脚本。仅当用户明确请求 E2E 验证时才运行它们。 - 运行检查或测试的通用指令授权相关的非E2E 步骤7下的验证；它不需要所有可用的本地检查，并且 不授权 E2E 执行。
- 托管平台在运行后自动启动所需的 E2E 作业 推或 PR 仍然是合并门。观察并报告他们的结果，但不要 除非用户明确请求，否则手动调度或重新运行它们。
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 中的强制双区域设置目录） | — | 如果发布政策发生变化 | 确认 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。 - 不存在长期的开发分支。每个请求都会得到一个新的分支； 旧的请求分支不得重复用于不相关的工作。
- 主结账拥有默认开发环境。 请求 工作树重用其工具链、包管理器存储、缓存并忽略 安全的本地配置。请求可能会创建隔离的本地状态 当共享不安全或不兼容时，但该状态仍被忽略 并且不得泄漏到提交中。
- PR/MR 交付是强制性的。推送分支，打开 PR/MR 定位
main，通过所需的远程检查和审查，然后使用存储库进行合并- 允许的合并策略。
典型请求开始（从主结帐运行；选择其外部的路径）：
bash
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 交付（需要时使用托管平台的等效平台）：
bash
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 worktree remove <worktree-path>
git branch -d <type>/<short-description>
git push origin --delete <type>/<short-description>通过合并到本地 main 来集成请求时进行请求清理 而不是远程 PR/MR（从主结帐运行）：
bash
git switch main
git merge <type>/<short-description>
git log --oneline -1
git worktree remove <worktree-path>
git branch -d <type>/<short-description>
git worktree prune拆卸前工作树必须清洁；提交或丢弃请求自己的 首先进行剩余的更改。使用 git branch -d 而不是 -D 因此未合并 分支拒绝删除。如果 git worktree remove 报告工作树为脏 或锁定，解决该状态而不是强制删除，并且永远不要删除 另一个请求的工作树。
6. 完成的定义
当满足以下所有条件时，更改完成：
- 根据最新的请求创建专用请求分支和工作树
main。 - 代码（或文档）实施计划的变更。
- 所有受影响的规格均已更新。
- 记录 E2E 场景（或根据第 3 节确认不需要）。
- 必要的有针对性的本地验证通过，或评估本地验证 不必要的；自动触发远程闸门通行，仅限代理 当明确请求时运行或分派 E2E。
- 改变是通过传统的信息来实现的。
- 如果里程碑交付完成，则更新董事会。
- 提交中不存在任何机密或本地数据。
- 分支被推送，其 PR/MR 被审核并合并到
main。 10.请求工作树被移除，合并的请求分支被删除。
发布/版本标签门
当更改是稳定应用程序版本发布（版本提升+标签）时， 完成的定义还需要双区域设置应用内变更日志条目 对于 packages/shared/src/changelog.ts 中的该版本（EN + zh-CN， 对齐的突出显示计数）之前标签，每 06-release-runbook.md §4.1 和D164。 GitHub 发行说明并不能替代。
7. 禁止的做法
| 练习 | 为什么 |
|---|---|
| 犯下秘密 | 违反安全规定 |
| 未提交的较大差异 | 违反 R2；粒度损失 |
| 无需更新规范即可更改行为 | 违反 R1；规格变得不可靠 |
| 跳过 e2e 文档以进行用户可见的更改 | 违反 R3；可追溯性差距 |
| 无需明确的用户请求即可手动运行或分派 E2E | 违反选择加入 E2E 执行策略 |
| 将完整的本地 test/check 套件视为自动预推送要求 | 忽略基于风险的验证并在没有必要证据的情况下延迟交付 |
直接在 main 上开发、提交或推送 | 违反 R4；绕过隔离和审查门 |
| 在主结帐或另一个请求的工作树中开发新请求 | 违反 R4；混合任务文件和本地状态 |
| 重用请求分支来完成不相关的工作 | 混合请求范围并削弱可追溯性 |
| 标记工作在合并 PR/MR 之前完成 | 违反 R4；更改未集成到 main 中 |
| 将合并的请求工作树保留在磁盘上 | 违反 R4；陈旧的工作树积累并导致交叉请求污染 |
| 修改基线冻结决策，无需 ADR + 版本升级 | 基线被冻结；变更需要正式流程 |
| 提交 CI 应重建的生成工件 | 回购膨胀、合并冲突 |
| 在一次提交中混合多个逻辑更改而没有明确的消息 | 历史粒度的损失 |
在不更新 packages/shared/src/changelog.ts 的情况下标记稳定的应用程序版本（EN + zh-CN） | 违反 D164/发布操作手册；该版本的应用内新增功能为空 |
8. 此工作流程的验收标准
在以下情况下，此工作流程规范本身被接受：
- [ ] R1/R2/R3/R4 已明确说明并与相关规范交叉链接。
- [ ] 开发循环由
AGENTS.md记录和引用。 - [ ] 规范更新矩阵涵盖基线中的所有变更类型。
- [ ] Git 提交规则与现有存储库提交样式匹配（
docs:、chore:）。 - [ ] 每个请求都需要使用创建的专用分支和工作树 从当前的
main开始。 - [ ] 请求工作树在安全的情况下重用主要结账环境 无需提交本地环境状态。
- [ ] PR/MR 创建、远程门、合并和分支清理是强制性的。
- [ ] 工作树删除和分支删除需要在执行完之后立即进行。 请求分支合并到
main中，包括本地合并传递。 - [ ] E2E 执行是选择加入的，需要明确的用户请求，而 E2E R3 中场景文档仍然是强制性的。
- [ ] 本地验证是基于风险的；不必要的检查可以被跳过而无需 阻止提交、推送或 PR/MR 创建。
- [ ] 完成的定义是完整且可操作的。
- [ ] 禁止行为列表涵盖已知的风险领域。
- [ ]
AGENTS.md指向此文档、04-e2e-test-plan.md和05-change-checklist.md。 - [ ] 更新所有索引（NAV、交付自述文件、规格自述文件、文档自述文件、董事会）。