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

---
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`，
播种后租户内位置是 `<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 类产品必须同时确认执行模型、权限边界、审批模型**（见下） | 不开任何开发线程，继续问 |
| 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 就不算过。用户没回复时，协调员等，不按假设推进，
状态保存在待办里。

## 角色线程矩阵

| 角色 | 线程数 | 负责目录 | 产出 |
|------|--------|----------|------|
| 协调员 | 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 任务共享工作目录的环境里，这一步尤其不能省。

## 测试与验收

- 每个客户端线程交付前必须自测：单元测试 + 对接契约的集成测试
  + 一份手工冒烟清单（启动、登录、核心 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 要求？
- 派生前校验清单全填了吗？契约是不是冻结版本？有没有线程在冻结后悄悄改了契约？
- 每个客户端的交付物里，有没有把“未验证”写成“已完成”？
- 待办文件是不是协调员唯一维护的最新状态？有没有子线程直接改了待办？
- 合并记录里执行人写了吗？是协调员评审 + 人 / 宿主执行，还是冒充成协调员自己合的？
- 验收清单是不是用户亲手确认的？有没有一项是协调员替用户勾的？
- 分阶段走了吗？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 的交付物是用户确认过的验收清单，不是你自己勾的清单。

---

## 附录角色：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 小节，格式见技能主文档“待办机制”：
  完成项要附证据，未完成项要写原因，新增项要写归属。缺这节视为交付不完整。

## 禁止

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

---

## 附录角色：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 结果是什么、执行合并的人或宿主操作是谁。
  协调员只给合并决定，不冒充执行人。

---

## 附录角色：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`。

## 禁止

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