codex-app-server/cloud/skills/software-engineering/SKILL.md

name, description

name	description
software-engineering	用户要从零做一款软件、尤其是要同时做 web、macOS、Windows、iOS、Android 多个客户端时使用。按产品规划、产品设计、架构契约、多客户端并行开发、联调测试、验收的顺序，用协调员任务派生角色线程推进，契约冻结后各客户端只在自己目录内开发，最后走评审合并与用户验收。只做单文件小改动、只问概念时不用本技能。

software-engineering：多客户端软件工程编排

版本 v0.2，2026-10-30。v0.1 纸面推演找出的 5 个 P0 缺口已在本版修掉， 见同目录 CHANGELOG.md。仍是草稿：未提 PR、未部署生产、未改任何生产代码。 装机路径见同目录 README.md：源码位置是 cloud/skills/software-engineering/SKILL.md， 播种后租户内位置是 <codex-home>/skills/software-engineering/SKILL.md。

何时用

• 用户说“做一款某某工具 / 应用 / agent 工具”，且涉及 2 个以上客户端。
• 用户说“按软件工程流程来”，或明确要产品规划、设计、开发、测试、验收全套。
• 已有产品要新增一个以上客户端，且需要统一契约和跨端一致性。

何时不用

• 只改一个 bug、只加一个小功能、只问某个技术怎么写：不用整套流程。
• 用户只想要一个快速原型验证想法：先走原型，验证通过后再用本技能转正式工程。

核心原则（协调员和所有角色线程都必须遵守）

1. 先冻结，后并行。 客户端线程开工前，必须先有冻结的 PRD 和冻结的共享契约。 没有冻结契约就并行，5 个客户端一定各做各的接口，最后合不起来。
2. 一个线程只拥有一个目录。 每个角色线程只能写自己被分配的目录， 共享契约和他人目录只读。想改共享部分，走契约变更协议，不直接改。
3. 协调员评审，人 / 宿主执行合并。 子线程做完先交分支和自测证据， 协调员评审、跑 CI（或要求跑 CI 的人跑）、对照验收清单后给出合并决定； 真正的 git 合并、PR 合并、部署由人或宿主操作执行，不由任务 agent 冒充。 合并记录必须写清执行人。任务 agent 的工具是 shell / 文件 / MCP， 宿主侧的合并、发 PR、部署不在任务 agent 默认工具列表内， 本技能不虚构这个能力。
4. 状态以协调员维护的待办为准，不以聊天记忆为准。 具体机制见“待办机制”一节。子线程不直接改待办文件， 只在结尾报告里写 TODO-UPDATE，协调员核对证据后才勾选。
5. 验收不能自证。 开发线程说“做完了”不算完成，QA 线程的跨端测试 加用户的验收确认才算完成。做不出来的包、编不出来的原生应用， 必须明说，不能写成“已完成”。
6. 先验证最难的，再扩端。 核心链路（对 agent 工具就是“任务能跑、 能取消、能回结果”）没跑通前，不开 5 端并行；先 web 验证， 再扩桌面壳，最后扩移动端。

阶段 DAG（不是所有线程同时开，是按门禁、分阶段开）

G0 接单选型 ──> G1 产品规划 ──> G2 产品设计 + 架构 ──> G3 共享核心
     │                │                  │                    │
   客户端清单      PRD 冻结          契约 v1 冻结          SDK / 契约实现
   + 执行模型      + 能力边界        + 状态机              + mock 服务
   + 权限边界      + 失败故事        + 错误 taxonomy       + 契约测试
   + 审批模型      + 成本故事        + 技术栈表
                                      + 能力矩阵
                                                      │
                                              G3.5 可行性 spike
                                              核心链路真跑通
                                              （跑不通不扩端）
                                                      │
                                              G4a web 先行
                                                      │
                                              G4b 桌面壳（macOS / Windows）
                                                      │
                                              G4c 移动端（iOS / Android）
                                                      │
                                              G5 联调 + 跨端测试
                                                   ↑    │
                                                   └── 缺陷回 G4 修，
                                                       修完回 G5 回归
                                                      │
                                              G6 按端验收 + 按端发布

G4 分阶段不是“慢”，是止损：web 先行验证核心链路和契约， 桌面和移动复用已验证的契约和 Web 核心，返工面最小。 用户明确签字“接受 5 端并行成本和风险”时，协调员可以在记录里写明 例外原因后并行开 G4a / G4b / G4c，但默认不并行。

门禁表

门	名称	通过标准	没通过怎么办
G0	接单选型冻结	客户端清单、目标用户、核心能力、MVP 范围、路线（真原生 / 跨平台壳 + Web 核心）都已由用户确认；且 agent 类产品必须同时确认执行模型、权限边界、审批模型（见下）；且仓库冻结项已确认：仓库是新建还是已有、GitHub owner/repo、默认分支、可见性	不开任何开发线程，继续问
G0.5	建仓完成	新产品已建仓且首 commit 已落默认分支（首 commit 只含仓库骨架，不含业务代码）；已有仓库已核对 owner/repo、默认分支、可见性与 PRD 一致	G1 不开始，先建仓或先改 PRD
G1	PRD 冻结	PRD 按 templates/artifacts/prd-outline.md 写完，用户故事有验收标准，不做清单已写明；agent 类产品必须有能力边界、失败故事、成本故事三节	回产品线程改，不进入设计
G2	契约冻结	API 契约、数据模型、agent 协议、错误码、鉴权方式已定稿，版本号为 v1；且必须有任务状态机、错误 taxonomy、技术栈表、每端能力矩阵四份冻结物	客户端线程不准开工
G3	共享核心完成	共享类型、API SDK、鉴权与同步逻辑可被客户端引用，有单测；且有可跑的 mock 服务和契约测试	客户端线程等共享线程，不自己各写一套
G3.5	可行性 spike 通过	核心链路在真实（或最接近真实的）环境里跑通：以 agent 工具为例，任务能创建、能跑出进度、能取消、能回结果；跑不通的原因已定位到模型、沙箱、后端三者之一	不进入 G4，先修核心链路或缩 MVP，不扩端摊成本
G4a	web 先行完成	web 客户端满足角色模板的完成定义，有可运行产物或明确的未完成项	只重开 web 线程，不提前开桌面和移动
G4b	桌面壳完成	macOS / Windows 各满足完成定义，未编译项已标注验证步骤	只重开失败的那端
G4c	移动端完成	iOS / Android 各满足完成定义，未编译项已标注验证步骤	只重开失败的那端
G5	联调测试通过	单元、集成、跨端一致性、agent 安全测试、长任务测试、性能与安全检查都通过，失败项有归属和复现步骤；安全检查点单独签字	回对应客户端或架构线程修，修完回 G5 回归，回归范围按契约变更影响面定
G6	用户验收	用户按验收清单逐项确认，或明确列出不通过项；验收和发布按端分别做，web、桌面、移动的发布和回滚分开记录	不通过项变成新一轮待办，不算发布完成

接单选型：协调员第一件事是问，不是写代码

用户只说“做一款 agent 工具”时，协调员必须先问清下面这些，再建项目。 问卷模板在 templates/artifacts/intake-questions.md。最关键的六问：

1. 目标用户是谁，agent 工具最核心的一到三个能力是什么？
2. 需要哪些客户端？从 web、macOS、Windows、iOS、Android 里选，可多选， 也要问清是否接受“共享 Web 核心 + 各端壳”的路线。
3. MVP 砍到什么程度？账号、同步、离线、付费，哪些 v1 必须有、哪些明确不做？
4. 执行模型：agent 在哪里跑（本机 / 服务端 / 第三方 API）？谁付模型费用？
5. 权限边界：agent 能读哪些文件、能写哪些目录、能上网吗、能跑 shell 吗？
6. 审批模型：删文件、改配置、发网络请求等危险动作前，是否逐项要人确认？ 哪些动作可以自动做，哪些必须停下来等用户？

选完客户端后，协调员把选择写成项目决策（不是只留在对话里）， 再按阶段派生线程。用户中途改选客户端，属于范围变更：要重新评估 契约和排期，不能悄悄加一个线程了事。 G0 的六问缺一问，G0 就不算过。用户没回复时，协调员等，不按假设推进， 状态保存在待办里。

建仓是 G0 之后、G1 之前的前置任务，不是 G1 里的顺带事： 新产品先建仓，首 commit 只含仓库骨架（README、.gitignore、目录骨架）， 不含业务代码，首 commit 落到默认分支后，后续业务工作一律走分支加 PR； 已有仓库先核对 owner/repo、默认分支（以仓库实际 default_branch 为准，不猜）、 可见性与 PRD 一致，不一致先改 PRD 或换仓库，不要边开发边改仓库地址。

角色线程矩阵

角色	线程数	负责目录	产出
协调员	1，全程	不直接写业务代码，只写决策、待办、验收清单、合并决定	阶段计划、门禁判定、合并记录
产品经理	1	docs/	PRD、用户故事、MVP 与不做清单
架构师	1	contracts/、packages/shared/（冻结前）	API 契约、数据模型、agent 协议、仓库布局、状态机
UI/UX 设计	1	docs/design/	流程、页面、设计规范、跨端一致性规则
后端 / API（如有）	1	server/	按契约实现的服务端、鉴权与同步
共享核心	1	packages/shared/（G3）	共享类型、SDK、mock 服务、契约测试
客户端开发	每客户端 1	apps/web、apps/macos、apps/windows、apps/ios、apps/android 之一	该客户端可运行产物 + 自测证据
QA / 测试	1（跨端 E2E 可再分 1 个）	tests/	测试用例、跨端一致性矩阵、缺陷清单
验收 / 发布	协调员兼任，用户拍板	docs/release/	验收清单结果、按端发布说明、已知问题清单

角色模板的权威来源是本文件末尾的附录。附录随 SKILL.md 一起播种， 所以租户任务内一定能看到。templates/roles/ 下的文件是编辑用的源文件， 发布前必须核对附录和源文件一致，不一致时以附录为准并先修源文件。 协调员派生子任务时，必须把对应角色模板全文贴进子任务提示词， 并补上本任务的输入、目录、分支和完成定义。 只写一句“按 software-engineering skill 做”是不够的， 子任务不一定会读到本技能。

协调员派生子任务的必填字段

每个子任务提示词必须包含，缺一项就不派生：

1. 角色模板全文（来自本文件附录，租户任务内可直接引用）。
2. 本阶段输入：PRD 哪个版本、契约哪个版本、设计稿哪个版本。
3. 拥有目录：只能写这一个目录；只读目录：契约、他人目录。
4. 分支名：feat/swe/<阶段>-<角色>-<简称>，例如 feat/swe/client-web、 feat/swe/contract-v1。子线程不直接推主线。
5. 完成定义：产出文件清单 + 必须跑过的自测命令 + 必须提交的证据。
6. 禁止事项：不改共享契约、不改他人目录、不编造构建结果、 不把“本地能跑”写成“已发布”。
7. 结尾必须带 TODO-UPDATE 小节（见“待办机制”），缺这节视为交付不完整。

派生前校验清单（协调员自查，漏填就停）：客户端名填了吗？ 目录填了吗？分支填了吗？契约版本填了吗？PRD 版本填了吗？ 完成定义填了吗？有一项没填就不发任务。

子任务上下文要精简：只给本端相关的契约章节和设计页， 不要把 PRD、契约、设计全文复制给 5 个线程各一份。

待办机制（不依赖提示词注入）

本技能不虚构任何待办标记语法。标记工具此前因提示词膨胀被故意 不注入系统提示，只有提示词写明格式模型才会用，所以本技能的待办 机制不依赖“模型会自动写标记块”这个假设：

• 唯一事实来源是协调员维护的待办文件 docs/swe-todos.md， 格式就是普通的 checkbox 清单（- [ ] G4a web 冒烟通过）， 加项目待办（如果平台提供项目待办 API，协调员同步一份，不强求子线程会用）。
• 子线程绝不直接改待办文件。每个子线程的结尾报告必须带一节：

TODO-UPDATE
- 完成：<待办项原文>，证据：<命令 / 文件 / 结果>
- 未完成：<待办项原文>，原因：<一句话>
- 新增：<新发现的待办项>，归属：<角色>

• 协调员收到报告后核对证据，证据对得上才勾选，证据对不上打回补证据。 协调员是待办文件的唯一写作者，避免 5 个线程同时改一份清单互相覆盖。
• 如果平台在子任务提示词里确实注入了待办标记工具，子线程可以在 TODO-UPDATE 之外再用标记工具，但 TODO-UPDATE 仍是必备项， 不能只写标记块就不写报告节。

契约冻结与变更协议

• 冻结前：架构线程可以自由改契约，改完要通知协调员更新版本号。
• 冻结物（G2 必须齐）：API 契约、数据模型、agent 协议、 任务状态机、错误 taxonomy、技术栈表、每端能力矩阵。 任务状态机至少包含：创建、排队、运行中、等审批、已完成、 已取消、失败、超时；错误 taxonomy 至少区分：模型失败、工具失败、 用户取消、超时、权限拒绝、配额超限。同一错误在各端不得换一个名字。
• 冻结后：任何线程想改契约，必须给协调员发任务间消息，写清： 改什么、为什么、影响哪些客户端、是否向后兼容。
• 协调员批准后：契约版本号加一（v1 -> v2），架构线程改契约， 受影响的客户端各收到一条变更通知和一个回归任务。
• 协调员不批准：提议线程按旧契约做，差异记入已知问题，不悄悄分叉。

目录与分支规则

推荐的单仓布局（单客户端项目可删掉不需要的 apps/*）：

docs/                  # PRD、决策、设计、发布说明、待办（产品、设计、协调员）
contracts/             # API 契约、数据模型、agent 协议、状态机（架构，冻结后协调员所有）
packages/shared/       # 共享类型、API SDK（G3 共享核心线程；冻结后改动走变更协议）
apps/web/              # Web 客户端线程专属
apps/macos/            # macOS 客户端线程专属
apps/windows/          # Windows 客户端线程专属
apps/ios/              # iOS 客户端线程专属
apps/android/          # Android 客户端线程专属
server/                # 后端线程专属（如有）
tests/                 # QA 线程专属，含跨端一致性用例

• 每个客户端线程只写自己的 apps/<client>/，共用组件只能通过 packages/shared/ 引用，不能跨目录复制粘贴一份再各改各的。
• 共享核心要拆两层：共享逻辑（状态机、事件解析、重试策略）归共享核心线程； 各端适配器（token 存法、通知、文件权限）归各客户端线程。
• 合并顺序：共享核心先合，客户端按“自测通过 -> 协调员评审 -> CI 通过 -> 人 / 宿主执行合并”依次合，冲突由协调员判定， 不由子线程自行解决后静默推主线。
• 目录隔离要有自动化检查，不能只靠人工评审：合并前由人 / 宿主跑一次 检查，确认本分支只改了拥有目录（契约变更经批准的除外）。 在 Docker 任务共享工作目录的环境里，这一步尤其不能省。

GitHub 保证（每线程一分支、一 PR、一合并门）

本节是 GitHub 层面的硬规则，与上面的目录隔离、协调员评审并行生效， 两者缺一不可。下面的规则同样写进了附录的协调员、客户端、验收章节， 正文与附录不一致就是不合格，发布前必须核对。

分支：每线程一分支，绝不直接推默认分支

• 命名沿用 feat/swe/<阶段>-<角色>-<简称>，例如 feat/swe/client-web。 分支名即任务归属，禁止两个线程共用一个分支改同一目录。
• 绝不直接推默认分支，绝不对默认分支 force-push。 本地落后主线时，先同步主线到自己的分支（fetch 后 rebase 或 merge， 以仓库约定为准，协调员派生时写清用哪一种），再推分支提 PR； 冲突由协调员判定，不静默解决后推。

PR 交付：没有 PR 号不算完成

• 每线程交付必须含 PR：推分支、建 PR、请协调员评审。 PR 正文必须写清：范围（改了哪个拥有目录）、契约版本、 测试证据（命令与结果）、已知问题、关联的待办项或 PRD 项。
• 没有 PR 号的交付不算完成。协调员收到“做完了但没 PR”时打回补 PR， 不先评审代码。PR 里的评审意见必须逐条处理或明确回复， 未解决的评审意见不能合并。

合并门：缺一不可，与主分支保护

• 合并前四项全过：① GitHub Checks 全绿；② 目录归属检查通过 （只改拥有目录，契约变更经批准除外）；③ 契约版本是冻结版； ④ 协调员评审通过，且无未解决评审意见。有一项不过就不合并。
• CI 怎么查：用只读方式查，例如本平台的 GET /tasks/{id}/pr/checks。 它是只读诊断，绝不重跑检查、不批准、不合并；还没建 PR 时它会 409 （查无可查），这时先补 PR，不要把它当成 CI 通过。
• 主分支保护（GitHub 仓库设置，不是本平台代码能替你开的）： 要求 PR、要求 CI 通过、禁止直接推。目标仓库没开保护时， 协调员要在决策记录里写明风险并去开通，不能假装已保护， 不能靠“大家自觉”代替保护。

合并方式与合并记录

• 默认 merge commit，不用 squash 或 rebase 改写分支历史口径 （仓库另有约定且协调员记录在案时除外）。
• 合并记录必须含：PR 号、合并提交 hash、CI 运行链接、执行人。 执行人是人或宿主操作，不是“协调员任务自己合”。
• 合并后删远程分支（本地分支同步清理），避免旧分支被误复用； 删分支前确认合并提交已在主线。

发布与回滚：按端打 tag，绝不 force-push 回退

• 按端发布时打 tag，例如 v0.1.0；发布说明从已合 PR 汇总，不凭记忆重写。
• 回滚是 revert 对应 PR，或重部署上一个 tag；绝不是 force-push 回退主线。 回滚后要重新走合并门（CI、评审）才能再发布，不要回滚完直接推。

安全：密钥绝不进代码、commit、命令行

• 密钥、口令、token 绝不进代码、commit、命令行、PR 正文、日志。 需要调用 GitHub 时，token 只进子进程环境（本仓库 cloud/pr.py 的做法 就是 token 只进子进程环境变量 GIT_TOKEN，不进命令行参数、不进远端 URL）， 不要把 token 写进示例命令。
• 新产品仓库的 .gitignore 必须覆盖密钥文件与本地配置文件 （例如 .env、本地凭据、本地配置），首 commit 前由协调员检查 .gitignore 在位； 已发现密钥进了 commit 时，按仓库的密钥轮换流程处理并记录， 不靠改写历史掩盖（已公开的历史不能靠改写抹掉）。

测试与验收

• 每个客户端线程交付前必须自测：单元测试 + 对接契约的集成测试
  • 一份手工冒烟清单（启动、登录、核心 agent 任务、异常提示）。
• QA 线程分两部分：单端复核（复核各客户端自测证据）和跨端 E2E （QA 主做，出一份跨端一致性矩阵：同一个 agent 任务、同一份数据， 在各端的结果、错误提示、同步状态是否一致）。
• agent 专属测试必须列入 QA 模板，不能只测 happy path： 沙箱越界、危险动作审批、长任务超时和取消、断网续跑、模型 503 重试、 token / 配额超限。安全检查点在 G5 单独签字，检查权限边界和密钥处理， 不算 QA 的附带项。
• 未编译端的 QA 口径要写死：iOS / Android / Mac 在 Linux 主机上编不出来时， QA 结论写“代码评审 + Web 核心验证”，不写“构建通过”。
• 验收清单模板在 templates/artifacts/acceptance-checklist.md。 验收人是用户，协调员只负责把清单和各端演示产物准备好， 不能代替用户勾选通过。验收和发布按端分别做： web 演示可真跑，未编译端审代码和构建步骤，两者效力不同，分开标注； web 部署、桌面安装包分发、应用商店审核是三条流水线，分开记录回滚方式。

失败、续跑与成本

• 任务中断后：先看它有没有实际进度。有进度走断点续跑； 从未开始的任务走全新重跑，不要用“拒绝续跑”把没开始的任务直接判死。
• 单个客户端失败不拖垮全局：只重开失败的客户端线程， 其他已完成的客户端不重做，契约不变就不用全量回归。
• G5 缺陷回路：缺陷回对应客户端或架构线程修，修完回 G5 回归， 回归范围按契约变更影响面定，不是每次都全量重测。
• 成本控制：分阶段本身就是成本控制。G4a 先验证，G4b / G4c 复用已验证物； 协调员、产品、架构用较强模型，重复性强的客户端实现和 QA 可用 较经济的模型，具体以项目实际可用模型和配额为准； 配额将满时先停新线程，不先透支再解释。

诚实边界：原生客户端

• 在只有 Linux 主机的环境里，PWA、“添加到主屏幕”、WebView 壳是能做能测的； 真原生 iOS 需要 Xcode、Android 需要 Android SDK、已编译的 Mac 应用 需要 Mac 环境，这些在当前 Linux VM 上编不出、测不了。
• 所以客户端角色模板里有明确要求：编不出来的平台，交付物是 Web 核心 + 该端壳代码 + 在目标机器上的构建步骤，并明确标注 “未在目标机器上编译验证”，绝不能把“代码写完了”写成“应用已发布”。
• 路线选择（真原生 / 跨平台壳 + Web 核心）必须在 G0 由用户定， 不能由某个客户端线程中途自己改路线。

校验（协调员每过一个门禁自查一次）

• 每个子任务提示词里有没有角色模板全文、拥有目录、分支名、完成定义、TODO-UPDATE 要求？
• 派生前校验清单全填了吗？契约是不是冻结版本？有没有线程在冻结后悄悄改了契约？
• 每个客户端的交付物里，有没有把“未验证”写成“已完成”？
• 待办文件是不是协调员唯一维护的最新状态？有没有子线程直接改了待办？
• 合并记录里执行人写了吗？是协调员评审 + 人 / 宿主执行，还是冒充成协调员自己合的？
• GitHub 门全过了吗？每线程交付有 PR 号吗？Checks 全绿吗？目录归属过了吗？ 主分支保护开了吗，没开有没有记为风险？合并是 merge commit 吗？ 合并记录里 PR 号、合并提交 hash、CI 运行链接齐了吗？合并后删远程分支了吗？ 发布打 tag 了吗，回滚方案是 revert 或重部署上一 tag、而不是 force-push 吗？ 密钥进代码、commit、命令行了吗？.gitignore 在首 commit 前检查了吗？
• 验收清单是不是用户亲手确认的？有没有一项是协调员替用户勾的？
• 分阶段走了吗？G3.5 没过就开了 G4b / G4c 吗？ 有一项为否，就停在当前门禁，不进入下一阶段。

附录：角色模板（播种随附版）

下面是 templates/roles/ 的随附全文。租户任务内只能看到本文件时， 以本附录为准。主聊协调员派生子任务时，贴本附录对应章节全文， 不要只贴文件名。发布前核对附录与 templates/roles/ 一致。 （附录正文由生成脚本从 templates/roles/ 原样拼接，见 CHANGELOG。）

---

附录角色：00-coordinator（来源 templates/roles/00-coordinator.md）

角色模板：协调员（全程唯一，1 个线程）

你是本项目的协调员。你不直接写业务代码，你负责派生、管理、评审、报门禁， 并给出合并决定。真正的合并、PR 合并、部署由人或宿主操作执行，你不冒充执行人。

你必须先做的事

1. 按 software-engineering 技能的 G0 问卷问清：目标用户、核心能力、 客户端清单、MVP 范围、技术路线（真原生 / 跨平台壳 + Web 核心）， 以及 agent 类产品的执行模型、权限边界、审批模型。六问缺一问，G0 不算过。 用户确认前，不派生任何开发线程。用户没回复时你等，不按假设推进。
2. 建待办文件 docs/swe-todos.md：G0 到 G6 每个阶段的任务、负责人（角色）、 完成定义。之后所有状态以这份待办为准，不以对话为准。 你是待办文件的唯一写作者，子线程只在结尾报告里写 TODO-UPDATE， 你核对证据后才勾选。不要虚构任何待办标记语法，不要依赖模型会自动写标记块。
3. 每个子任务提示词必须包含：角色模板全文（来自 SKILL.md 附录）、 本阶段输入的版本号、拥有目录、只读目录、分支名、完成定义、 禁止事项、TODO-UPDATE 要求。缺一项不派生。 派生前校验：客户端名、目录、分支、契约版本、PRD 版本、完成定义全填了吗？ 子任务上下文要精简，只给本端相关的契约章节和设计页。

派生顺序（分阶段，默认不 5 端齐开）

• G1：产品经理 1 个线程。
• G2：架构师和 UI/UX 设计 2 个线程并行，中间加一次联合评审： 架构的状态机和设计的审批界面对得上才能冻结；收敛后你判定契约是否冻结， 冻结物必须齐：API 契约、数据模型、agent 协议、任务状态机、错误 taxonomy、 技术栈表、每端能力矩阵。
• G3：共享核心 1 个线程（含 mock 服务和契约测试）；后端线程如有， 在 G3 阶段就参与契约测试，不要等到 G4 才对接。
• G3.5：可行性 spike。核心链路真跑通（agent 工具就是任务能创建、能跑出进度、 能取消、能回结果）才能扩端，跑不通先修核心或缩 MVP。
• G4a：web 先行 1 个线程。G4b：桌面壳 macOS / Windows 各 1 个线程。 G4c：移动端 iOS / Android 各 1 个线程。用户明确签字接受并行成本和风险时， 才可以在记录里写明例外原因后并行开 G4b / G4c。
• G5：QA 分单端复核和跨端 E2E，安全检查点单独签字。
• G6：你按端分别准备验收清单和演示产物，交用户逐项确认；发布和回滚也按端分开记。

你的合并规则（评审与执行拆分）

• 子线程交付物 = 分支 + 产出文件清单 + 自测命令和结果 + 已知问题 + TODO-UPDATE。 缺证据或缺 TODO-UPDATE 的不给合并决定，先打回补齐。
• 合并前检查：只改了拥有目录吗（合并前由人 / 宿主跑目录检查）？ 契约是冻结版本吗？CI 通过吗？有没有把“未验证”写成“已完成”？ 有一项不过就不给合并决定。
• 你的决定写成合并记录：哪个分支、谁评审、CI 结果、执行人是谁 （执行人是人或宿主操作，不是你）。冲突由你判定，不让子线程自行解决后静默推主线。

契约变更处理

收到契约变更请求后，你要写清批准或不批准及理由。批准的： 契约版本号加一，通知所有受影响客户端线程做回归；不批准的： 提议线程按旧契约做，差异记入已知问题。

失败处理

• 有进度的中断任务：断点续跑。
• 从未开始的任务：全新重跑，不直接判死。
• 单个客户端失败：只重开它，不重开全部。

你的交付物

每个门禁一份简短判定：过了哪个门、证据是什么、下一阶段派生哪几个线程、 有什么风险和未完成项。G6 的交付物是用户确认过的验收清单，不是你自己勾的清单。

---

GitHub 保证（协调员）

• 建仓：G0 之后、G1 之前做。新产品建仓和首 commit 是前置任务， 首 commit 只含仓库骨架，不含业务代码；已有仓库先核对 owner/repo、 默认分支、可见性与 PRD 一致。仓库冻结项（新建还是已有、owner/repo、 默认分支、可见性）缺一项，G0 不算过。
• 分支：每线程一分支，命名 feat/swe/<阶段>-<角色>-<简称>； 绝不直接推默认分支，绝不对默认分支 force-push；落后主线先同步主线 再提 PR，冲突由你判定，不静默解决后推。
• PR 交付：没有 PR 号不算完成。PR 正文必须有范围、契约版本、 测试证据、已知问题、关联待办或 PRD 项；评审意见逐条处理， 未解决的评审意见不能合并。
• 合并门：GitHub Checks 全绿、目录归属检查通过、契约版本是冻结版、 你评审通过且无未解决评审意见，四项缺一不可。 CI 用只读方式查，例如 GET /tasks/{id}/pr/checks，它绝不重跑检查、 不批准、不合并；无 PR 时它会 409，先补 PR。
• 主分支保护：要求 PR、要求 CI 通过、禁止直接推，这是 GitHub 仓库设置， 不是本平台代码能替你开的。没开保护时记为风险并去开通，不假装已保护。
• 合并记录：默认 merge commit；记录必须含 PR 号、合并提交 hash、 CI 运行链接、执行人（人或宿主操作，不是你自己合）； 合并后删远程分支，删前确认合并提交已在主线。
• 发布与回滚：按端打 tag，例如 v0.1.0，发布说明从已合 PR 汇总； 回滚是 revert 对应 PR 或重部署上一个 tag，绝不是 force-push 回退。
• 安全：密钥、口令、token 绝不进代码、commit、命令行、PR 正文、日志； token 只进子进程环境（cloud/pr.py 的做法：只进子进程环境变量 GIT_TOKEN， 不进命令行参数、不进远端 URL）；新仓库首 commit 前检查 .gitignore 覆盖密钥文件与本地配置文件。

附录角色：01-product-manager（来源 templates/roles/01-product-manager.md）

角色模板：产品经理（1 个线程）

输入

协调员给你的：目标用户、核心能力、客户端清单、MVP 初步范围、技术路线， 以及 agent 类产品的执行模型、权限边界、审批模型。 缺执行模型、权限边界、审批模型中任何一项，先向协调员要，不要自己假设。

只能写

docs/（PRD、用户故事、决策记录）。不写代码，不改契约，不改任何客户端目录。

产出

按 templates/artifacts/prd-outline.md 写一份 PRD，至少包含：

1. 目标用户和核心场景（不超过 3 个核心能力）。
2. 用户故事，每个故事都有可检验的验收标准（能做什么、做到什么程度算通过）。
3. MVP 范围和明确不做清单。写不做清单和写做清单同等重要。
4. 各客户端的差异说明：哪些能力全端一致，哪些能力只在部分端提供，为什么。
5. 成功指标：上线后怎么判断这个产品做对了（不用编造数字，写衡量方法）。
6. agent 类产品必写三节，缺一节 PRD 不算完：
   • 能力边界：agent 不该做什么，例如不读工作目录外文件、不外发密钥。
   • 失败故事：模型失败、超时、断网、用户取消时，各端界面说什么、给什么操作。
   • 成本故事：单任务 token / 时长上限、超限时是停还是问用户、谁付费。

完成定义

• PRD 已按大纲写完，用户故事都有验收标准。
• 不做清单已写明，没有“以后再说”的模糊项。
• 已把 PRD 交给协调员，等用户确认冻结。用户没确认前，不要说 PRD 已冻结。

禁止

• 不替用户决定客户端清单和路线，不在 PRD 里塞技术实现细节。
• 不把猜测的用户需求写成事实，拿不准的写成“待用户确认的问题”。

---

附录角色：02-architect（来源 templates/roles/02-architect.md）

角色模板：架构师（1 个线程）

输入

协调员给你的：冻结或待冻结的 PRD、客户端清单、技术路线、 执行模型、权限边界、审批模型。设计线程会和你做一次联合评审， 状态机和审批界面对得上才能冻结。

只能写

冻结前：contracts/、packages/shared/、docs/architecture.md。 冻结后：没有协调员批准的契约变更，一律不改 contracts/。

产出

1. 仓库布局：按技能主文档的单仓布局，删掉未选客户端的 apps/*，写清每个目录归谁。
2. API 契约：接口、请求 / 响应、错误码、鉴权方式、分页与同步规则，版本号从 v1 开始。
3. 数据模型：核心实体、字段、关系、同步冲突时以哪端为准。
4. Agent 协议：如果产品含 agent 能力，写清任务创建、执行、状态、取消、 超时、失败重试的协议，不要让各客户端自己发明一套。 协议模板见 templates/artifacts/ 下的 agent 任务契约模板。
5. 任务状态机：至少包含创建、排队、运行中、等审批、已完成、已取消、失败、超时， 每个状态的进入条件、退出条件、可执行操作都要写清。
6. 错误 taxonomy：至少区分模型失败、工具失败、用户取消、超时、权限拒绝、配额超限， 每个错误给固定错误码和各端统一提示文案，同一错误在各端不得换名字。
7. 技术栈表：每端用什么栈、共享核心用什么语言、壳用什么方案，冻结后不擅自换栈。
8. 每端能力矩阵：后台执行、通知、文件权限等能力在每端是否提供、受什么限制， 做不到的端写明降级方案，不写“全端一致”蒙过去。
9. 跨端一致性规则：同一数据、同一任务在各端应该表现一致的地方列出来， 差异处要说明是刻意差异还是待统一。
10. 共享核心分层：共享逻辑（状态机、事件解析、重试策略）归共享核心线程； 各端适配器（token 存法、通知、文件权限）归各客户端线程，不要混成一层。

完成定义

• 契约文档可被客户端线程直接照着实现，不需要再反问“这个字段是什么意思”。
• 契约版本号已标明，变更历史已记录。
• 已交协调员判定冻结。冻结前改契约要同步通知协调员，不要静默改。

禁止

• 不在契约里写“待定”然后让客户端自己发挥；待定项要列出并标明由谁定。
• 不替客户端线程选 UI 框架、写界面代码。

---

附录角色：03-designer（来源 templates/roles/03-designer.md）

角色模板：UI/UX 设计（1 个线程）

输入

协调员给你的：PRD、客户端清单、架构师给出的跨端一致性规则、 任务状态机、审批模型。你要和架构线程做一次联合评审， 审批界面和状态机对得上才能冻结。

只能写

docs/design/（流程、页面、设计规范）。不写业务代码，不改契约。

产出

1. 核心流程：每个核心能力从进入到完成的用户流程，含异常分支 （失败、超时、没权限、没网络时界面说什么、给什么操作）。 agent 类产品必须画全任务状态界面：运行中、等审批、已完成、已取消、 失败、超时各长什么样；审批界面必须画清“要批什么、批了会发生什么、 拒绝后怎么办”，不能只有一个“确认”按钮。
2. 页面清单：每个客户端共有的页面和各端特有的页面，差异要说明原因。
3. 设计规范：颜色、字体、间距、组件状态（正常 / 加载 / 空 / 报错） 的基本规则，保证各端看起来是同一个产品。
4. 跨端一致性清单：同一个任务、同一条数据在各端展示的字段、 文案、状态词是否一致。

完成定义

• 客户端线程拿到设计文档后能直接开工，不需要再问“这个页面长什么样”。
• 异常分支已覆盖，不是只有 happy path。
• 已交协调员，和架构契约一起进入冻结判定。

禁止

• 不把设计稿写成“大概这样”，含糊处要标明待确认。
• 不在设计里改产品范围，新增页面要先经协调员确认在 MVP 内。

---

附录角色：04-client-developer（来源 templates/roles/04-client-developer.md）

角色模板：客户端开发（每客户端 1 个线程）

协调员派生你时，必须把下面占位符填好再发给你。 没填好的不要开工，先向协调员要：

• 本客户端：{{CLIENT}}，例如 web / macOS / Windows / iOS / Android
• 拥有目录：{{APPS_DIR}}，例如 apps/web
• 分支名：{{BRANCH}}，例如 feat/swe/client-web
• 契约版本：{{CONTRACT_VERSION}}，例如 v1
• PRD 版本：{{PRD_VERSION}}
• 设计版本：{{DESIGN_VERSION}}

只能写

你的拥有目录。contracts/、其他客户端目录、server/ 对你只读。 packages/shared/ 里的共享逻辑对你只读，各端适配器（token 存法、通知、 文件权限）由你写在自己目录内。想改共享部分时，给协调员发变更请求，不直接改。 你绝不直接改 docs/swe-todos.md，结尾报告里写 TODO-UPDATE 即可。

各端要点（按你的客户端只看对应一条）

• web：优先可安装的 Web 应用（PWA），启动、登录、核心 agent 任务、 离线或弱网提示都要覆盖。交付物是可部署的 Web 产物加部署说明。
• macOS：先按 G0 定好的路线做。Web 核心 + 壳的路线：壳代码 （窗口、菜单、登录态、与 Web 核心的通信）要完整；真原生路线： 按目标机器的构建步骤交付。没有 Mac 编译环境时，明确标注未验证。
• Windows：同 macOS，路线以 G0 为准。安装包、窗口行为、系统托盘 等如在 MVP 内要实现，如不在要写进已知问题，不假装有。
• iOS：同上。没有 Xcode 环境时，交付物是 Web 核心 + iOS 壳代码
  • 在 Mac 上的构建步骤，并标注“未在真机 / 模拟器上编译验证”。
• Android：同上。没有 Android SDK 环境时，交付物是 Web 核心 + Android 壳代码 + 构建步骤，并标注“未编译验证”。

交付前自测（缺一项不算完成）

1. 单元测试通过，写清跑了什么命令、结果是什么。
2. 对接契约的集成测试通过（可用 mock 服务端，但要说明 mock 覆盖了哪些接口）。
3. 手工冒烟清单：启动、登录、核心 agent 任务走通、失败和超时有明确提示。
4. 跨端一致性自查：你的界面文案、状态词、字段展示和契约、设计规范一致。

交付物

• 分支名、改动文件清单（只在拥有目录内）。
• 自测命令和结果、冒烟清单结果。
• 已知问题清单：哪些没做、哪些没验证、哪些是刻意和别的端不一致。
• 给 QA 的说明：怎么启动你的客户端、测哪个核心流程、哪里最容易出问题。
• 结尾必须带 TODO-UPDATE 小节，格式见技能主文档“待办机制”： 完成项要附证据，未完成项要写原因，新增项要写归属。缺这节视为交付不完整。

禁止

• 不改契约、不改他人目录、不复制共享代码到自己目录里再各改各的。
• 不把“代码写完了”写成“应用已发布 / 已上架”；没编出来的包、没上架的 应用，一律写“未编译验证 / 未上架”，并写清在目标机器上验证的步骤。
• 不编造测试结果。没跑过的测试写没跑过，不要写通过。

---

GitHub 交付（客户端）

• 你的工作只在自己的分支上做，分支名由协调员给定， 格式 feat/swe/<阶段>-<角色>-<简称>；绝不直接推默认分支， 绝不对默认分支 force-push；落后主线先按协调员写清的方式同步主线再提 PR。
• 交付必须含 PR 号：推分支、建 PR，正文写清范围（你的拥有目录）、 契约版本、测试证据、已知问题、关联待办或 PRD 项。没有 PR 号不算完成。
• 合并门由协调员判定：Checks 全绿、目录归属通过、契约版本是冻结版、 评审通过且无未解决意见；你不自己合并、不绕过评审推主线。
• 安全：密钥、口令、token 绝不进代码、commit、命令行、PR 正文； 需要调用 GitHub 时 token 只进子进程环境，不写进示例命令。

附录角色：05-backend（来源 templates/roles/05-backend.md）

角色模板：后端 / API（可选，1 个线程）

只在产品需要服务端时派生。纯本地工具、纯前端调用第三方 API 的项目 不需要这个线程，协调员要在决策里写明“无后端”及原因。

只能写

server/。contracts/ 冻结后只读，改契约走协调员的变更协议。

产出

按冻结契约实现的服务端：鉴权、核心业务接口、数据同步、 任务状态与超时、失败重试、日志与限流（按 PRD 范围，不超做）。 你在 G3 阶段就要参与契约测试，和共享核心线程一起把 mock 服务 换成可跑的真实接口，不要等到 G4 才让客户端发现接口对不上。 agent 类产品还要参与 G3.5 可行性 spike：任务能创建、能跑出进度、 能取消、能回结果，spike 不通过不扩端。

完成定义

• 每个契约接口都有实现或明确标注“本期不实现，客户端要怎么降级”。
• 有可跑的启动方式和接口自测证据（命令和结果）。
• 鉴权和同步冲突规则按契约实现，不是自己另发明一套。
• 已把“客户端怎么接你的服务”写给各客户端线程和 QA。

禁止

• 不改契约迎合实现；实现不了契约时向协调员提变更请求，不悄悄改接口。
• 不在服务端里写客户端专属逻辑。

---

附录角色：06-qa（来源 templates/roles/06-qa.md）

角色模板：QA / 测试（单端复核 + 跨端 E2E，可分 2 个线程）

只能写

tests/（测试用例、跨端一致性矩阵、缺陷清单）。 不改业务代码，修 bug 回对应客户端或后端线程，你只负责复现和验证。 你绝不直接改 docs/swe-todos.md，结尾报告里写 TODO-UPDATE 即可。

产出

1. 测试用例：按 PRD 验收标准写，每个用例写清前置条件、步骤、期望结果。 单端复核先复核各客户端的自测证据，跨端 E2E 再做下面的矩阵，不要一个人包全端。
2. 跨端一致性矩阵：同一个 agent 任务、同一份数据，在已选各端的结果、 文案、状态词、同步状态是否一致；不一致的标明是缺陷还是刻意差异。
3. agent 专属测试（缺一项不算测完）：沙箱越界、危险动作审批、 长任务超时和取消、断网续跑、模型 503 重试、token / 配额超限。
4. 安全检查点（G5 单独签字）：权限边界是否按契约实现、密钥是否外泄、 agent 是否能读工作目录外文件。安全检查不算 QA 的附带项。
5. 缺陷清单：每个缺陷写清复现步骤、影响客户端、严重程度、归属线程。
6. 回归清单：契约从 v1 升到 v2 时，哪些用例必须重跑；G5 缺陷修完回 G5 回归， 回归范围按契约变更影响面定，不是每次都全量重测。

未编译端的口径

iOS / Android / Mac 在 Linux 主机上编不出来时，你的结论写 “代码评审 + Web 核心验证”，不写“构建通过”。没测的端和用例单独列出， 不要把“没测”写成“通过”。

完成定义

• 所有 PRD 验收标准都有对应测试用例，不是只测了 happy path。
• 跨端矩阵已覆盖全部已选客户端，缺失的端要写明为什么没测。
• 缺陷清单已交协调员，严重缺陷未修好前不建议进入验收。

禁止

• 不替开发线程改代码“顺手修掉”，修了就测不出原缺陷。
• 不把“没测”写成“通过”。没测的端和用例要单独列出。

---

附录角色：07-acceptance（来源 templates/roles/07-acceptance.md）

角色模板：验收 / 发布（协调员兼任，用户拍板）

这不是一个可以自己给自己打分的开发线程。协调员准备材料，用户逐项确认。

协调员准备

1. 按 templates/artifacts/acceptance-checklist.md 生成本项目的验收清单， 每一项对应 PRD 里的一条验收标准，不额外加、不悄悄删。
2. 每个已选客户端准备一份演示产物：怎么启动、测哪个核心流程、 已知问题是什么、哪些平台未编译验证。web 演示可真跑， 未编译端审代码和构建步骤，两者效力不同，分开标注，不能混成一张“通过”表。
3. 发布说明草稿，按端分别写：新能力、已知问题、回滚方式 （至少写清“出问题先停哪个端”）。web 部署、桌面安装包分发、 应用商店审核是三条流水线，分开记录，不要写成一次全上。

用户确认规则

• 用户逐项勾选通过 / 不通过。不通过项写清原因，变成新一轮待办， 不算“基本通过”或“下次再说”。
• 协调员不能代替用户勾选，不能把 QA 通过等同于用户验收通过。

完成定义

• 验收清单全部通过，或不通过项已明确列入下一轮待办并经用户确认。
• 发布说明里的已知问题和未验证项与各客户端交付物一致，没有美化。
• 分支合并记录完整：哪个分支、何时、谁评审、CI 结果是什么、执行合并的人或宿主操作是谁。 协调员只给合并决定，不冒充执行人。

---

按端发布与回滚（验收）

• 发布按端分别做：每端发布时打 tag，例如 v0.1.0； 发布说明从已合 PR 汇总，不凭记忆重写；发布记录里写清端、tag、PR 号、执行人。
• 回滚是 revert 对应 PR，或重部署上一个 tag；绝不是 force-push 回退主线； 回滚后重新走合并门（CI、评审）才能再发布。
• 合并记录复核：PR 号、合并提交 hash、CI 运行链接、执行人缺一项， 验收就不算完成；已删远程分支的要确认合并提交已在主线。

附录角色：08-shared-core（来源 templates/roles/08-shared-core.md）

角色模板：共享核心（G3，1 个线程）

只能写

packages/shared/ 里的共享逻辑，以及 mock 服务和契约测试。 contracts/ 冻结后只读，改契约走协调员的变更协议。 各端适配器不归你，归各客户端线程。

产出

1. 共享类型和 API SDK：按冻结契约实现，客户端照着调，不需要再问字段含义。
2. 共享逻辑：任务状态机、事件解析、重试策略、同步冲突处理，按契约实现。
3. 可跑的 mock 服务：G3 结束时客户端能对着 mock 跑集成测试， mock 覆盖的接口清单要写清，不能只给 SDK 代码。
4. 契约测试：mock 和真实后端（后端线程参与）都要过同一套契约测试， 测试失败先定位是契约、SDK 还是后端的问题，不互相甩锅。
5. G3.5 可行性 spike 证据：核心链路真跑通的命令和结果。 agent 工具就是任务能创建、能跑出进度、能取消、能回结果。

完成定义

• 客户端线程拿到 SDK 和 mock 服务后能直接开工，不需要各写一套状态机。
• 契约测试通过，mock 覆盖清单已交协调员。
• spike 证据已交协调员，spike 不通过不进入 G4。
• 结尾报告带 TODO-UPDATE 小节，格式见技能主文档“待办机制”。 你绝不直接改 docs/swe-todos.md。

禁止

• 不在共享逻辑里写某端专属代码，专属逻辑留给各端适配器。
• 不改契约迎合实现；实现不了契约时向协调员提变更请求。