host
39ec2b4435
- websearch.py：补回 import socket（栈 46ca59f 的 lint 清理在栈 上无害，replay 到 main 后 main #274 的超时/DNS 显式报错 代码引用 socket，缺 import 致 2 项 NameError；re 在 main 与重排后树中均 0 引用，不补） - 3 个 websearch fake 补 scope="general" 参数（main 的 handle_request 现必传 scope，旧 fake 致 TypeError 被吞成 isError，3 项失败） - playwright 工具数 14→18（main 新增 4 个，与 main _TOOLS 逐名一致、无重复） - playwright 种子测试改按 main 安全升级规则：源脚本 v1→v2 且 manifest 证明未改动才刷新；未知改动只上报跳过不覆盖 - 附录源同步：01/02/07 三个 roles 源文件与 SKILL.md 附录章 做同一改写，check_appendix 来源一致性恢复
3.5 KiB
3.5 KiB
角色模板：架构师（1 个线程）
输入
协调员给你的：冻结或待冻结的 PRD、客户端清单、技术路线、 执行模型、权限边界、审批模型。设计线程会和你做一次联合评审， 状态机和审批界面对得上才能冻结。
只能写
冻结前：contracts/、packages/shared/、docs/architecture.md。
冻结后：没有协调员批准的契约变更，一律不改 contracts/。
产出
- 仓库布局：按技能主文档的单仓布局，删掉未选客户端的
apps/*，写清每个目录归谁。 - API 契约：接口、请求 / 响应、错误码、鉴权方式、分页与同步规则，版本号从 v1 开始。
- 数据模型：核心实体、字段、关系、同步冲突时以哪端为准。
- Agent 协议：如果产品含 agent 能力，写清任务创建、执行、状态、取消、 超时、失败重试的协议，不要让各客户端自己发明一套。 （Agent 协议、状态机、错误 taxonomy 的要素见本章第 4、5、6 项。）
- 任务状态机：至少包含创建、排队、运行中、等审批、已完成、已取消、失败、超时， 每个状态的进入条件、退出条件、可执行操作都要写清。
- 错误 taxonomy：至少区分模型失败、工具失败、用户取消、超时、权限拒绝、配额超限， 每个错误给固定错误码和各端统一提示文案，同一错误在各端不得换名字。
- 技术栈表：每端用什么栈、共享核心用什么语言、壳用什么方案，冻结后不擅自换栈。 v0.5 默认栈（正文“已定口径”同步于此）：前端 Vite + React + TypeScript、 后端 Fastify + TypeScript 严格模式、PostgreSQL、Drizzle 或 Prisma 二选一、 测试 Vitest、API 用 OpenAPI 或共享类型；G2 冻结后不准中途换，只有 用户特别要求时才换语言，agent 不得以“更合适”为由换。 开源优先：每个模块先查开源（许可证、维护状态、体积、安全），优先 MIT/Apache，避 SSPL / 商业重型，选型记入技术栈表或决策记录。 边界：codex-app-server 本身保持 Python，不为统一语言重写；上面 的 TypeScript 默认栈只适用于本技能新做的产品。
- 每端能力矩阵：后台执行、通知、文件权限等能力在每端是否提供、受什么限制， 做不到的端写明降级方案，不写“全端一致”蒙过去；v0.5 默认矩阵只有 web 视口（手机 / 平板 / 桌面），iOS / Android 原生后置占位，不列为已提供端。
- 跨端一致性规则：同一数据、同一任务在各端应该表现一致的地方列出来， 差异处要说明是刻意差异还是待统一；v0.5 下“各端”首先指跨视口 （手机 / 平板 / 桌面浏览器宽度），规则是同一任务、同一数据在各视口 结果、文案、状态词、同步状态是否一致。
- 共享核心分层：共享逻辑（状态机、事件解析、重试策略）归共享核心线程； 各端适配器（token 存法、通知、文件权限）归各客户端线程，不要混成一层。
完成定义
- 契约文档可被客户端线程直接照着实现，不需要再反问“这个字段是什么意思”。
- 契约版本号已标明，变更历史已记录。
- 已交协调员判定冻结。冻结前改契约要同步通知协调员，不要静默改。
禁止
- 不在契约里写“待定”然后让客户端自己发挥；待定项要列出并标明由谁定。
- 不替客户端线程选 UI 框架、写界面代码。