ilaandClaude Fable 5
0184595ccc
Harness governance / validate (push) Has been cancelled
Initialize the full harness coding document set from the harness_coding_docs template, customized for the SoftBox project: - Vision, requirements, tech stack (modern Go 1.25 + Gio v0.10.1; Win7 legacy Go 1.20.14 + Gio v0.6.0), architecture, coding rules - Protocol contracts (signed catalog, package protocol v1, Ed25519 license, events, CLI) and Gio view structure - Roadmap Phase 0-6 with 20 suggested tasks; T-001 (monorepo skeleton) filed and ready to claim - Agent entry points (AGENTS.md, docs/00-ai-start-here.md), context manifest, governance scripts and tests - Merge Go gitignore with harness rules; keep go.work tracked Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
86 lines
5.3 KiB
Markdown
86 lines
5.3 KiB
Markdown
# 编码规则(Coding Rules)
|
|
|
|
> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
|
|
> 与技术细节冲突时,以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准;与"该不该做"冲突时,以 [需求](02-requirements.md) 为准;协议字段以 [api.md](api.md) 为准。
|
|
|
|
## 0. 黄金法则
|
|
|
|
1. **不臆造**:数据字段、文件、接口、依赖,不确定就查证或询问。
|
|
2. **守范围**:只做当前任务要求的事,不顺手加后续功能。
|
|
3. **照架构**:使用既定技术栈和模块边界,不擅自引入新框架。
|
|
4. **小步改**:一次只解决一个问题,不夹带无关重构。
|
|
5. **可验证**:改完必须能构建、能测试、对得上验收标准。
|
|
|
|
## 1. 动手前
|
|
|
|
- 按链路确认:`vision` → `requirements` → `tech-stack` → `architecture` → `tasks`。
|
|
- 找到本任务对应的验收标准,写之前就知道"怎么算做对"。
|
|
- 先找现有函数、组件、工具和测试,复用优先。
|
|
- 如果需求含糊,或改动会偏离原则 / 架构,先问。
|
|
|
|
## 2. 分层与工具链纪律(本项目最容易翻车的地方)
|
|
|
|
- `core/` 的 domain 与 application **禁止 import Gio、SQLite、Windows API**;下载、存储、时间、进程、系统信息一律接口注入。
|
|
- 依赖方向只允许 `app-modern`/`app-win7` → `core`;任何反向 import 都是返工。
|
|
- `core/` 与 `app-win7/` 只使用 **Go 1.20 可编译**的语法与依赖;新增依赖前检查其 go.mod 的 `go` 指令。泛型可用(1.18+),但 1.21+ 的标准库函数(如 `slices`、`maps`、`min/max` 内建)不得进入这两个模块。
|
|
- Gio 代码只出现在 `ui/gio/`;Windows 调用只出现在 `platform/windows/`,且必须有非 Windows stub,保证 `go test ./...` 在 Linux CI 可跑。
|
|
- 仅 Win10+ 存在的 Windows API 必须 LoadLibrary 动态加载、失败降级,不得成为 EXE 导入表强依赖。
|
|
- Gio Layout 每帧禁止 IO(磁盘/网络/哈希);后台任务只发布 application.Event,不直接改控件;控件状态按软件 ID 保存。
|
|
|
|
## 3. 安全纪律(违反即安全事故)
|
|
|
|
- 任何下载内容未通过 SHA-256 + 签名验证,**不得解压执行**;清单验签失败拒绝,不回退到未验证内容。
|
|
- ZIP 处理必须拒绝:绝对路径、`../` 穿越、符号链接逃逸、entrypoint 指向 payload 外、无上限解压(文件数/体积/压缩比)。
|
|
- 安装/更新只走 `staging → current → backup` 原子流程;任何写 `current/` 的捷径都不允许。
|
|
- 程序更新不得触碰 `data/` 与 `licenses/`。
|
|
- 不强杀用户进程;更新前等待正常退出,超时取消。
|
|
- 私钥、真实注册码、真实机器标识不进代码、测试数据和文档;`testdata/` 只放假数据和专用测试密钥对。
|
|
- 日志不记录注册码、令牌、原始硬件标识和敏感查询参数。
|
|
|
|
## 4. 事实来源纪律
|
|
|
|
- 协议字段只信 `docs/api.md` 与 `schemas/`;架构边界只信 `docs/04-architecture.md`;当前现实只信 `docs/current-state.md` 和代码。
|
|
- 不从旧盒子的逆向笔记、备份或草稿推断当前实现;那些是设计输入,不是本仓库事实。
|
|
- 不虚构字段、事件、错误码、配置项。
|
|
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md`、`schemas/` 和相关任务。
|
|
|
|
## 5. 范围纪律
|
|
|
|
- MVP 只做 `02-requirements.md` 中列为 P0 的功能;V1.1/V2 功能只记录,不实现。
|
|
- 需求明确排除的非目标(社区、支付、云同步、插件、驱动)不得实现。
|
|
- 不为"将来可能用到"提前抽象;SDK 拆分(softbox-sdk)是后续独立仓库的事,本仓库不预建。
|
|
|
|
## 6. 代码规范
|
|
|
|
- 标识符使用英文;错误码用稳定英文枚举,UI 负责中文文案。
|
|
- 错误必须处理,不吞错;每个失败路径要能落到用户可见的状态或日志。
|
|
- 注释解释"为什么",不复述"做了什么"。
|
|
- 使用 `gofmt`(必须)与 `go vet`(必须);不手工制造风格分裂。
|
|
- 状态写入一律临时文件 + 原子替换。
|
|
|
|
## 7. 测试与验证
|
|
|
|
完成前至少检查:
|
|
|
|
- [ ] `cd core && go vet ./... && go test -count=1 ./...` 通过(Linux 无头环境)。
|
|
- [ ] 现代版可交叉编译:`cd app-modern && GOOS=windows GOARCH=amd64 go build ./cmd/softbox`。
|
|
- [ ] Win7 版可用 Go 1.20 编译:`cd app-win7 && GOTOOLCHAIN=go1.20.14 GOOS=windows GOARCH=amd64 go build ./cmd/softbox`。
|
|
- [ ] 状态机改动覆盖:成功、失败、取消、断电恢复、回滚。
|
|
- [ ] UI 事件改动使用 fake submitter + ApplyEvent 测试。
|
|
- [ ] 对得上需求验收标准;没有夹带无关改动。
|
|
- [ ] 涉及文档事实变化时,文档已同步。
|
|
- [ ] 已在当前任务文件(`docs/tasks/T-<编号>.md`)的 `## 执行记录` 记录跑过的命令和结果作为证据,不靠"代码已写"判定完成。
|
|
- [ ] 回复里如实说明跑了什么命令、结果如何。
|
|
|
|
## 8. 绝不
|
|
|
|
- 绝不把密钥、token、密码、私钥写进代码或文档样例的真实值里。
|
|
- 绝不为了让测试通过而删除断言、降低验收标准。
|
|
- 绝不擅自删除用户已有文件或重置工作区。
|
|
- 绝不在没说明的情况下改公共协议(manifest/app.json/许可证)、迁移数据结构或升级 Gio/Go 工具链。
|
|
- 绝不绕过签名验证、哈希校验或回滚机制"先跑起来再说"。
|
|
|
|
## 9. 拿不准就问
|
|
|
|
问题要具体,说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
|