--- name: software-engineering description: 用户要从零做一款软件、尤其是要同时做 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`， 播种后租户内位置是 `/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//`，共用组件只能通过 `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`。 ## 禁止 - 不在共享逻辑里写某端专属代码，专属逻辑留给各端适配器。 - 不改契约迎合实现；实现不了契约时向协调员提变更请求。