host
34ed438d0e
- P1-1 directory-isolation executable check: git diff --name-only against merge-base, output recorded in merge record - P1-2 derivation checklist table (8 required items, missing one blocks dispatch) - P1-3 QA split into single-client review and cross-client E2E with fixed deliverables and agent-test attribution - P1-4 sub-task slim-pack trimming rules (listed chapters only, never full copies) - P2: inter-thread Q&A default policy, docs/decisions.md append-only, per-client onboarding docs (web first at G4a), v1.1 handover checklist - Body and appendix kept in sync; new lightweight keyword test
906 lines
55 KiB
Markdown
906 lines
55 KiB
Markdown
---
|
||
name: software-engineering
|
||
description: 用户要从零做一款软件、尤其是要同时做 web、macOS、Windows、iOS、Android 多个客户端时使用。按产品规划、产品设计、架构契约、多客户端并行开发、联调测试、验收的顺序，用协调员任务派生角色线程推进，契约冻结后各客户端只在自己目录内开发，最后走评审合并与用户验收。只做单文件小改动、只问概念时不用本技能。
|
||
---
|
||
|
||
# software-engineering：多客户端软件工程编排
|
||
|
||
版本 v0.3，2026-10-30。上一版是 v0.2 + PR #193 GitHub 保证
|
||
（已合并、已部署生产）。v0.3 改了什么：P1-1 目录隔离自动化检查
|
||
（可执行命令 + 检查输出记入合并记录）、P1-2 派生占位符必填表
|
||
（缺一项就不发任务）、P1-3 QA 正式分单端复核与跨端 E2E 两部分
|
||
（各自交付物写死）、P1-4 子任务精简包裁剪规则（只给本端相关章节，
|
||
提示词里列出所含章节）；P2：任务间问答默认策略、决策记录落盘
|
||
`docs/decisions.md`、每端上手文档、v1.1 交接清单。
|
||
装机路径见同目录 `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 小节（见“待办机制”），缺这节视为交付不完整。
|
||
|
||
派生前校验表（必填表，协调员必须把填好的表原样贴进派生提示词，
|
||
不能只在心里过一遍；缺一项就不发任务）：
|
||
|
||
| 必填项 | 填什么 |
|
||
|--------|--------|
|
||
| 客户端名 | 本客户端，例如 web / macOS / Windows / iOS / Android |
|
||
| 拥有目录 | 只能写这一个目录，例如 `apps/web` |
|
||
| 分支名 | `feat/swe/<阶段>-<角色>-<简称>`，例如 `feat/swe/client-web` |
|
||
| 契约版本 | 冻结的契约版本号，例如 v1 |
|
||
| PRD 版本 | 冻结的 PRD 版本号 |
|
||
| 设计版本 | 冻结的设计版本（设计页清单见精简包） |
|
||
| 完成定义 | 产出文件清单 + 必须跑过的自测命令 + 必须提交的证据 |
|
||
| TODO-UPDATE 要求 | 结尾报告必须带 TODO-UPDATE 小节，格式见“待办机制” |
|
||
|
||
子任务精简包（裁剪规则写死，不是“尽量精简”）：只给本端相关的
|
||
契约章节、设计页、PRD 故事和冻结决策摘要，绝不把 PRD、契约、
|
||
设计全文复制给每个线程。精简包由四部分组成，缺一部分就补齐再发：
|
||
① 本端相关的契约章节（列出章节号 / 标题）；② 本端相关的设计页
|
||
（列出页名）；③ 本端相关的 PRD 故事（列出故事编号）；④ 冻结决策摘要
|
||
（不超过 10 条，列出决策标题）。派生提示词里必须列出精简包所含章节
|
||
清单，例如“契约 §任务状态机、§错误码；设计 p2 审批页；PRD 故事 S1、S3；
|
||
决策 D1、D4”——只写“已精简”不算数。线程发现缺章节时向协调员要补发，
|
||
不自己猜、不去全文里翻旧版。
|
||
|
||
## 待办机制（不依赖提示词注入）
|
||
|
||
本技能不虚构任何待办标记语法。标记工具此前因提示词膨胀被故意
|
||
不注入系统提示，只有提示词写明格式模型才会用，所以本技能的待办
|
||
机制不依赖“模型会自动写标记块”这个假设：
|
||
|
||
- 唯一事实来源是协调员维护的待办文件 `docs/swe-todos.md`，
|
||
格式就是普通的 checkbox 清单（`- [ ] G4a web 冒烟通过`），
|
||
加项目待办（如果平台提供项目待办 API，协调员同步一份，不强求子线程会用）。
|
||
- 子线程绝不直接改待办文件。每个子线程的结尾报告必须带一节：
|
||
|
||
```
|
||
TODO-UPDATE
|
||
- 完成：<待办项原文>，证据：<命令 / 文件 / 结果>
|
||
- 未完成：<待办项原文>，原因：<一句话>
|
||
- 新增：<新发现的待办项>，归属：<角色>
|
||
```
|
||
|
||
- 协调员收到报告后核对证据，证据对得上才勾选，证据对不上打回补证据。
|
||
协调员是待办文件的唯一写作者，避免 5 个线程同时改一份清单互相覆盖。
|
||
- 如果平台在子任务提示词里确实注入了待办标记工具，子线程可以在
|
||
TODO-UPDATE 之外再用标记工具，但 TODO-UPDATE 仍是必备项，
|
||
不能只写标记块就不写报告节。
|
||
|
||
## 契约冻结与变更协议
|
||
|
||
- 冻结前：架构线程可以自由改契约，改完要通知协调员更新版本号。
|
||
- 冻结物（G2 必须齐）：API 契约、数据模型、agent 协议、
|
||
任务状态机、错误 taxonomy、技术栈表、每端能力矩阵。
|
||
任务状态机至少包含：创建、排队、运行中、等审批、已完成、
|
||
已取消、失败、超时；错误 taxonomy 至少区分：模型失败、工具失败、
|
||
用户取消、超时、权限拒绝、配额超限。同一错误在各端不得换一个名字。
|
||
- 冻结后：任何线程想改契约，必须给协调员发任务间消息，写清：
|
||
改什么、为什么、影响哪些客户端、是否向后兼容。
|
||
- 协调员批准后：契约版本号加一（v1 -> v2），架构线程改契约，
|
||
受影响的客户端各收到一条变更通知和一个回归任务。
|
||
- 协调员不批准：提议线程按旧契约做，差异记入已知问题，不悄悄分叉。
|
||
|
||
## 任务间问答默认策略与决策记录（v0.3 新增）
|
||
|
||
- 任务间问答默认策略：被问题卡住的线程先按冻结契约做，把假设写成
|
||
开放问题记入结尾报告，不无限等协调员答复、不停工等、不按猜测改契约。
|
||
协调员在下一轮答复：确认假设、纠正假设（发回归任务）、或升级为契约变更；
|
||
答复本身也要记入决策记录。等答复期间线程不阻塞在原地，先做契约内
|
||
无争议的部分。
|
||
- 决策记录落盘路径：`docs/decisions.md`，由协调员维护，子线程只在报告里
|
||
提议、不直接改。只追加不改写历史：一条决策写清日期、议题、决定、理由、
|
||
影响端；推翻旧决策时追加新条写明“取代 D-n”，绝不改旧条原文、不删旧条。
|
||
决策记录是合并记录和验收清单之外的第三份事实来源，口头决定不算数。
|
||
|
||
## 目录与分支规则
|
||
|
||
推荐的单仓布局（单客户端项目可删掉不需要的 `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 通过
|
||
-> 人 / 宿主执行合并”依次合，冲突由协调员判定，
|
||
不由子线程自行解决后静默推主线。
|
||
- 目录隔离必须有自动化检查，不能只靠人工评审、不能只写“人工评审”。
|
||
合并前由人 / 宿主跑（以拥有目录 `apps/web` 为例，基线以合并目标分支
|
||
的最新 HEAD 为准）：
|
||
```
|
||
git fetch origin
|
||
git diff --name-only $(git merge-base origin/main HEAD)...HEAD
|
||
```
|
||
逐项核对输出的每个文件是否落在拥有目录内；契约变更经协调员批准的
|
||
文件除外，但批准记录必须能对应到具体文件。检查命令、输出文件清单、
|
||
例外批准记录必须原样记入合并记录，缺检查输出的合并记录视为不合格，
|
||
不给合并决定。在 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 线程正式分两部分，各自交付物写死，缺一不算 G5 通过：
|
||
① 单端复核：逐端复核各客户端的自测证据是否属实（命令、结果、冒烟清单），
|
||
交付物是逐端复核报告（每端通过 / 不通过 + 证据 + 未复核项）。
|
||
② 跨端 E2E：同一 agent 任务、同一份数据跑遍各端，交付物是跨端一致性矩阵
|
||
（各端结果、错误提示、同步状态是否一致）+ 缺陷清单 + 回归清单。
|
||
- agent 专属测试清单保留，归属如下，不能只测 happy path：
|
||
归单端复核（每端都要过）：沙箱越界、危险动作审批、token / 配额超限；
|
||
归跨端 E2E（同一任务跨端行为一致）：长任务超时和取消、断网续跑、模型 503 重试。
|
||
安全检查点在 G5 单独签字，检查权限边界和密钥处理，不算 QA 的附带项。
|
||
- 未编译端的 QA 口径要写死：iOS / Android / Mac 在 Linux 主机上编不出来时，
|
||
QA 结论写“代码评审 + Web 核心验证”，不写“构建通过”。
|
||
- 验收清单模板在 `templates/artifacts/acceptance-checklist.md`。
|
||
验收人是用户，协调员只负责把清单和各端演示产物准备好，
|
||
不能代替用户勾选通过。验收和发布按端分别做：
|
||
web 演示可真跑，未编译端审代码和构建步骤，两者效力不同，分开标注；
|
||
web 部署、桌面安装包分发、应用商店审核是三条流水线，分开记录回滚方式。
|
||
- 每端上手文档是 G6 交付物之一：每端一份，写清启动、登录、核心流程、
|
||
常见问题；G4 阶段先写 web 版（G4a 交付时随 web 客户端一起交），
|
||
桌面、移动版在各自 G4b / G4c 交付时补齐，不拖到 G6 才现写。
|
||
- v1.1 交接清单是 G6 收尾必备，三项缺一不算收尾完成：未修缺陷
|
||
（带归属和严重程度）、开放问题（含任务间问答里未关闭的假设）、下轮待办。
|
||
|
||
## 失败、续跑与成本
|
||
|
||
- 任务中断后：先看它有没有实际进度。有进度走断点续跑；
|
||
从未开始的任务走全新重跑，不要用“拒绝续跑”把没开始的任务直接判死。
|
||
- 单个客户端失败不拖垮全局：只重开失败的客户端线程，
|
||
其他已完成的客户端不重做，契约不变就不用全量回归。
|
||
- 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 吗？
|
||
- v0.3 新增项：派生校验表 8 项全填且贴进了提示词吗？精简包所含章节
|
||
在提示词里列出了吗？QA 单端复核报告和跨端一致性矩阵都齐了吗？
|
||
agent 测试清单归属对吗？决策记录是只追加的 `docs/decisions.md` 吗？
|
||
web 版上手文档在 G4a 交了吗？v1.1 交接清单三项齐了吗？
|
||
有一项为否，就停在当前门禁，不进入下一阶段。
|
||
|
||
## 附录：角色模板（播种随附版）
|
||
|
||
下面是 `templates/roles/` 的随附全文。租户任务内只能看到本文件时，
|
||
以本附录为准。主聊协调员派生子任务时，贴本附录对应章节全文，
|
||
不要只贴文件名。发布前核对附录与 `templates/roles/` 一致。
|
||
本附录是 v0.3 版的一部分：正文的 v0.3 改动（目录隔离自动化检查、
|
||
派生必填表、精简包、QA 拆分、决策记录、上手文档、v1.1 交接清单）
|
||
已同步进对应角色章节，正文与附录不一致就是不合格。
|
||
（附录正文由生成脚本从 `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 版本、设计版本、
|
||
完成定义、TODO-UPDATE 要求，共 8 项。
|
||
子任务精简包（裁剪规则写死）：只给本端相关的契约章节、设计页、
|
||
PRD 故事和冻结决策摘要（不超过 10 条），绝不把 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，安全检查点单独签字。
|
||
单端复核交付物是逐端复核报告（每端通过 / 不通过 + 证据 + 未复核项），
|
||
归单端复核的 agent 测试：沙箱越界、危险动作审批、token / 配额超限；
|
||
跨端 E2E 交付物是跨端一致性矩阵 + 缺陷清单 + 回归清单，
|
||
归跨端 E2E 的 agent 测试：长任务超时和取消、断网续跑、模型 503 重试。
|
||
两部分交付物缺一不算 G5 通过。
|
||
- G6：你按端分别准备验收清单和演示产物，交用户逐项确认；发布和回滚也按端分开记。
|
||
|
||
## 你的合并规则（评审与执行拆分）
|
||
|
||
- 子线程交付物 = 分支 + 产出文件清单 + 自测命令和结果 + 已知问题 + TODO-UPDATE。
|
||
缺证据或缺 TODO-UPDATE 的不给合并决定，先打回补齐。
|
||
- 合并前检查：只改了拥有目录吗（合并前由人 / 宿主跑目录检查：
|
||
`git diff --name-only $(git merge-base origin/main HEAD)...HEAD`，
|
||
逐项核对是否落在拥有目录内，契约变更经批准的除外；检查命令与输出
|
||
文件清单必须原样记入合并记录，缺检查输出不给合并决定）？
|
||
契约是冻结版本吗？CI 通过吗？有没有把“未验证”写成“已完成”？
|
||
有一项不过就不给合并决定。
|
||
- 你的决定写成合并记录：哪个分支、谁评审、CI 结果、执行人是谁
|
||
（执行人是人或宿主操作，不是你）。冲突由你判定，不让子线程自行解决后静默推主线。
|
||
|
||
## 契约变更处理
|
||
|
||
收到契约变更请求后，你要写清批准或不批准及理由。批准的：
|
||
契约版本号加一，通知所有受影响客户端线程做回归；不批准的：
|
||
提议线程按旧契约做，差异记入已知问题。
|
||
|
||
## 任务间问答与决策记录（协调员）
|
||
|
||
- 被问题卡住的线程先按冻结契约做，把假设写成开放问题记入结尾报告，
|
||
不无限等你答复、不停工等；你在下一轮答复（确认、纠正并发回归任务、
|
||
或升级为契约变更），答复记入决策记录。
|
||
- 决策记录落盘 `docs/decisions.md`，由你维护，只追加不改写历史；
|
||
一条决策写清日期、议题、决定、理由、影响端；推翻旧决策追加新条
|
||
写明“取代 D-n”，绝不改旧条原文、不删旧条。
|
||
|
||
## 失败处理
|
||
|
||
- 有进度的中断任务：断点续跑。
|
||
- 从未开始的任务：全新重跑，不直接判死。
|
||
- 单个客户端失败：只重开它，不重开全部。
|
||
|
||
## 你的交付物
|
||
|
||
每个门禁一份简短判定：过了哪个门、证据是什么、下一阶段派生哪几个线程、
|
||
有什么风险和未完成项。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 个线程）
|
||
|
||
协调员派生你时，必须把下面占位符填好再发给你。
|
||
没填好的不要开工，先向协调员要（派生前校验表共 8 项：客户端名、
|
||
拥有目录、分支名、契约版本、PRD 版本、设计版本、完成定义、
|
||
TODO-UPDATE 要求，缺一项就不发任务）。派生提示词里的精简包必须
|
||
列出所含章节（契约章节、设计页、PRD 故事、冻结决策摘要），只写
|
||
“已精简”时先向协调员要清单再开工；缺章节不自己猜：
|
||
|
||
- 本客户端：{{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 验收标准写，每个用例写清前置条件、步骤、期望结果。
|
||
QA 正式分两部分，各自交付物写死，缺一不算 G5 通过：
|
||
① 单端复核：逐端复核各客户端的自测证据是否属实，交付物是逐端复核报告
|
||
（每端通过 / 不通过 + 证据 + 未复核项）；
|
||
② 跨端 E2E：同一 agent 任务、同一份数据跑遍各端，交付物是跨端一致性矩阵
|
||
（各端结果、文案、状态词、同步状态是否一致；不一致的标明是缺陷还是刻意差异）
|
||
+ 缺陷清单 + 回归清单。
|
||
2. agent 专属测试（缺一项不算测完），归属如下：
|
||
归单端复核（每端都要过）：沙箱越界、危险动作审批、token / 配额超限；
|
||
归跨端 E2E（同一任务跨端行为一致）：长任务超时和取消、断网续跑、模型 503 重试。
|
||
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 部署、桌面安装包分发、
|
||
应用商店审核是三条流水线，分开记录，不要写成一次全上。
|
||
4. 每端上手文档：每端一份，写清启动、登录、核心流程、常见问题；
|
||
web 版在 G4a 交付时先交，桌面、移动版在各自 G4b / G4c 交付时补齐。
|
||
5. v1.1 交接清单：未修缺陷（带归属和严重程度）、开放问题
|
||
（含任务间问答里未关闭的假设）、下轮待办；三项缺一不算 G6 收尾完成。
|
||
|
||
## 用户确认规则
|
||
|
||
- 用户逐项勾选通过 / 不通过。不通过项写清原因，变成新一轮待办，
|
||
不算“基本通过”或“下次再说”。
|
||
- 协调员不能代替用户勾选，不能把 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`。
|
||
|
||
## 禁止
|
||
|
||
- 不在共享逻辑里写某端专属代码，专属逻辑留给各端适配器。
|
||
- 不改契约迎合实现；实现不了契约时向协调员提变更请求。
|