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>
5.3 KiB
5.3 KiB
编码规则(Coding Rules)
每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。 与技术细节冲突时,以 技术栈 / 架构设计 的事实为准;与"该不该做"冲突时,以 需求 为准;协议字段以 api.md 为准。
0. 黄金法则
- 不臆造:数据字段、文件、接口、依赖,不确定就查证或询问。
- 守范围:只做当前任务要求的事,不顺手加后续功能。
- 照架构:使用既定技术栈和模块边界,不擅自引入新框架。
- 小步改:一次只解决一个问题,不夹带无关重构。
- 可验证:改完必须能构建、能测试、对得上验收标准。
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. 拿不准就问
问题要具体,说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。