feat: add software-engineering skill v0.2

Add cloud/skills/software-engineering/SKILL.md (686 lines, v0.2, appendix with 9 role templates travels inside SKILL.md because skill_seed only copies SKILL.md, not templates/). Update skill pack tests: EXPECTED set and real-pack list now include software-engineering, plus an explicit seed test asserting it lands at skills/software-engineering/SKILL.md, contains the appendix, and tenant edits are never overwritten. One-line wording tweak in the architect template avoids the existing secret-scan false positive on the substring sk- inside agent-task-contract.md; deployed file sha256 bd0436399ac05c6131b9281dad00973e50d13540e4c56ad21f21e2b5209bae8e (40759 bytes, 686 lines).
This commit is contained in:
host committed 2026-10-30 06:00:31 +00:00
1 parent 5e562d8413
commit 885bf38790
3 files changed
+705 -3

No files matched your search

+686
View File
@@ -0,0 +1,686 @@
---
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`。
## 禁止
- 不在共享逻辑里写某端专属代码,专属逻辑留给各端适配器。
- 不改契约迎合实现;实现不了契约时向协调员提变更请求。
+1 -1
View File
@@ -12,7 +12,7 @@ from pathlib import Path
SKILLS_DIR = Path(__file__).resolve().parents[1] / "skills"
EXPECTED = {"live-info", "document-tools", "image-workflow",
"browser-automation"}
"browser-automation", "software-engineering"}
def _frontmatter(text):
+18 -2
View File
@@ -63,11 +63,12 @@ class SkillSeedHelperTestCase(unittest.TestCase):
self.assertEqual(out["skills_skipped_differ"], ["live-info"])
self.assertEqual(open(dest).read(), "tenant edited version\n")
def test_real_pack_lists_three_skills(self):
def test_real_pack_lists_all_skills(self):
names = [n for n, _p in list_skills()]
self.assertEqual(names,
["browser-automation", "document-tools",
"image-workflow", "live-info"])
"image-workflow", "live-info",
"software-engineering"])
class WorkerSkillSeedTestCase(unittest.TestCase):
@@ -116,6 +117,21 @@ class WorkerSkillSeedTestCase(unittest.TestCase):
self.assertTrue(os.path.exists(path), path)
self.assertIn("name: %s" % name, open(path).read())
def test_flag_on_seeds_software_engineering_and_user_edit_survives(self):
worker = self._worker(seed_skills=True)
dirs = worker._tenant_dirs("projA")
path = self._skill_path(dirs, "software-engineering")
self.assertTrue(os.path.exists(path), path)
text = open(path).read()
self.assertIn("name: software-engineering", text)
# v0.2 P0-1: the appendix travels inside SKILL.md itself,
# because skill_seed only copies SKILL.md, not templates/.
self.assertIn("附录角色:00-coordinator", text)
self.assertIn("附录角色:08-shared-core", text)
open(path, "w").write("tenant edited version\n")
worker._tenant_dirs("projA")
self.assertEqual(open(path).read(), "tenant edited version\n")
def test_old_tenant_merges_and_user_edit_survives(self):
worker = self._worker()
dirs = worker._tenant_dirs("projA")