docs(skill): add appendix provenance sources, checker and CHANGELOG

SKILL.md claimed its appendix was spliced verbatim from
templates/roles/ by a generation script (see CHANGELOG), but the pack
contained none of the three. Add the nine role sources (mechanically
split from the v0.2 appendix; SKILL.md untouched, zero semantic
change), tools/check_appendix.py (verify + --emit, stdlib only, never
edits SKILL.md), CHANGELOG.md, and test_skill_appendix_provenance.py
(5 tests). Seeding unchanged: skill_seed copies SKILL.md only, so
templates/tools/CHANGELOG never reach the tenant home.
This commit is contained in:
host committed 2026-11-03 02:48:55 +00:00
1 parent 61e08a1a8c
commit 4e554b5c07
12 files changed
+818

No files matched your search

@@ -0,0 +1,43 @@
# 角色模板:架构师(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 框架、写界面代码。