DeepSeek Harness Tauri 桌面版 | Only 8mb installer, zero environment setup, preset plugins, Windows / macOS / Linux.
该文档已被固定,禁止修改
通用软件开发协议 (速查手册版)
1. 架构与状态 (Architecture & SSOT)
- 唯一真值 (SSOT):数据/状态仅保留一份权威来源。禁止本地副本,写操作单点收口,读操作只读/订阅。
- 零中间层:仅有单一消费者的文件/Hook/Util/封装层,必须强行内联至调用处。
- 激进重构:重构即彻底删除/替换,严禁保留
_legacy或废弃存根文件;重命名优先使用git mv保留历史。 - 事故防御:非显而易见的兼容代码/边缘处理,必须标注
issue #xxx或阐明 Why(事故背景)。
2. 副作用与通信 (Effects & IPC)
- 声明式副作用:组件内严禁裸写原生副作用(如
useEffect/watch);状态变更与订阅统一使用声明式 API/Hooks。 - 命令式白名单:仅当显式注册/销毁外部资源(原生窗口、网络取消等)时允许使用命令式副作用,且必须注释标记:
// keep:effect <原因>。 - 跨边界 IPC:通信 API 需白名单化;来源校验(Origin Check)在入口处一次性完成;让位标记(Bridge Override)必须精确到具体命令/事件粒度。
3. 目录落位决策树 (Directory Allocation)
代码逻辑判定
├─ 仅单一 Store 使用 ➔ 归属于该 Store 模块目录下
├─ 纯 UI / 无业务语义 ➔ components/ (基础 UI 库)
├─ 依赖业务状态 / 领域数据 ➔ ui/<特定业务领域>/
├─ 无状态 / 纯逻辑计算 ➔ utils/ (全局工具库,严禁放杂货)
└─ 可复用组件状态 / 逻辑 ➔ hooks/
4. 平台与 UI 机制 (Platform & UI)
- 跨端写回:跨进程/语言共享数据时,写回操作必须发生在完整 Hydration(反序列化初始化)之后。
- 双端校验:写入侧(前端)进行数据归一化,读取侧(后端/Native)进行兜底校验。
- 前置拦截:平台限制与版本差异必须在调用发起前同步拦截,严禁依赖 Try-Catch 捕获失败。
- 提示单出处:遵循“谁执行,谁提示”,禁止在上层函数重复弹窗/Toast。
5. 交付前自检清单 (Pre-Commit Checklist)
- [ ] 真值:数据来源是否唯一?
- [ ] 收敛:是否存在单消费者的中间层/文件?(若有,内联)
- [ ] 目录:文件落点是否符合决策树?
- [ ] 副作用:原生副作用是否已标记
// keep:effect <原因>? - [ ] 遗留:是否无废弃符号/旧文件残留?
- [ ] 验证:Typecheck / Lint / Build 是否全部零 Error 通过?