# GUI 项目工作约定（用户历次拍板沉淀；对所有参与者生效）

> 本文件 = 本项目内的持久规矩。全局个人偏好在 Claude 记忆里；这里只放**这个项目**的要求。架构类决策不在此（见 docs/rfc/ 四篇与 docs/web-styling.md）。

## 流程与协作

1. **设计先行，文档给用户 review**：新领域先出设计文档（missions/tasks/ 归档）经用户过目再编码；量小或机械照抄类可直接生码，但契约/架构变更必须先改文档。
2. **teammate 组织**：耗时任务开 background teammate；干完不 kill 保持存活当长期 owner（后续变更 SendMessage 派发）；会话断了从 missions/tasks/ 归档冷启动同名 owner。设计 owner 兼任本领域实现 dispatcher；worker 反复超时时 owner 直接下场写。
3. **小步快跑**（网络慢易超时）：文件改动分批落盘（每批几分钟内）、思考外化、每批一句话回执；产出零落盘超过约 5 分钟即视为可疑。
4. **commit 纪律**：`--no-verify` 跳过门禁（GUI 免门禁期）；不同性质的改动分刀提交（注释类落盘即提不攒批，不与功能改动混）；RFC 独立成刀（回刷时要整体挪位）。工作区里其他 teammate 的在途文件不许混入自己的 commit。commit message 不携带 Co-Authored-By 等 co-auth 尾注。
   - **门禁按 PR 周期收口**（用户 2026-07-20 定）：测试/门禁只在提 PR 的窗口集中修（2026-07-20 首次 PR 已修过一轮）；平时快速开发不随手写测试、不盯门禁；期间弄红存量测试记台账不追修，下次 PR 窗口统一算账。分层结构与文件落点（包级 `tests/`、`.spec.ts` 命名）从第一天守全仓惯例——PR 窗口收口的只是阈值与红绿，不是搬迁。
   - **文档住顶刀**：GUI 文档（missions/、docs/rfc/、docs/ui-*.md、docs/web-styling.md）集中在最顶部的 docs commit，底部实现历史不含文档。每次代码改动的提交顺序：先把文档改动提交完，再开新 commit 改代码；被代码刀压下去的文档 commit，找时间 rebase 重排合并回最顶（重排铁律：终树 diff 为零）。
5. **跨属地改动**：动别人属地的代码先报告/事后备案给属地 owner；契约有误先改契约文档再让实现照抄；发现契约缺口只报告不擅改。
6. **验收自动化**：UI 交付前 agent 自己跑 playwright（chromium headless）过验收清单，不留给用户手验；每修一个 bug 钉一条防回归断言进 verify 脚本；「fixture 全绿」不算完——真 host 级也要过（fixture 掩盖时序 bug 有两次实证）。
7. **进度可见**：用户要求时开 5 分钟巡检（盘上核实+表格同步+催落后线）；巡检探针只用安全 URL。
7a. **未答问题不得代答**（用户 2026-07-21 定，起因：主会话在提问超时后擅自「代拍」并据此派工）：向用户发出的问题若未获回答（超时/离席），该问题**保持未决**——不许以「推荐项/合理默认」自动代答，不许基于代答派发任何工作；只能执行此前已获明确授权的部分，未决项对应的工作线整体挂起等答复。「用户睡觉/全自动模式」也不例外：自动化只覆盖已拍口径内的执行，不覆盖替用户做新决策。

## 代码与文档

8. **代码注释一律英文且少写**：只留非显然契约/约束/防坑（如 Node 16 req 'close' 语义）；不写叙述性/复述代码/评审史；中文只用于 missions/docs 文档（供用户 review）。产品 UI 文案中文，不算注释。
9. **注释不引用工作记录**：禁止引 missions/tasks/*.md、设计稿节号、裁决时间戳——首选注释自含说清约束；确需出处才引 docs/rfc/ 正式 RFC。
10. **产物分流**：截图进 .artifacts/（gitignored）；有归档价值的验收脚本进 scripts/；一次性诊断脚本进 ignore 目录。
11. **命名规则**：packages/host/*、packages/client/* 的包名必含目录前缀（dsh-host-*、dsh-client-*）；全仓 rename 走冻结窗口一次改完。
12. **妥协台账三段式**：设计文档的不做清单写【触发条件（具体到事件）→ 返工点 → 预埋要求】，不写模糊的「将来优化」。
13. **RFC 是活文档**：大改动落地后主动扫时效更新，不等用户提醒；面向开发者体裁（现状+怎么开发），取舍原因短写。

## 架构红线（详见 RFC，此处仅提醒高频踩点）

14. store 无业务对象（sessions/connection 走 OOP 对象层+useSyncExternalStore）；视图选中态等 UI 局部事实不进全局 store。
15. rpcId 严格双向（发起方 mint、应答方回填），但业务函数签名只见 RpcRequest<P> 封装，mint 收在载体层。
16. 逻辑面（hooks/对象层）与展示面（纯 props 组件）分离——组件是耗材会重做。
17. Notifier 双通道纪律：仅用户手势直接回响可用 notifyNow，帧驱动一律 markDirty 合批。
18. **web 是纯呈现层，呈现物不进 session log**（用户 2026-07-20 定）：log 只记模型真正经历的事；「怎么画」类数据（tool 卡 view、queue 排队态等控制面）一律 host 现算随帧下发或 live 帧推送，不持久化——重放时按当时能力重算，算不出就回退通用形态（documented-default）。

## 终局工程（已定待执行）

18. RFC 中英文提交后**回刷历史 commit**：消掉 missions 工作记录、RFC 插历史配对、历史注释转英（映射表在 tasks/20260720-0250-comment-sweep/）；执行时冻结所有其他工作。web-cordis 设计归档列删除豁免（用户自改）。