docs: add harness coding documentation

2026-07-08 15:27:21 +08:00
parent e5d10577c0
commit d2eeb049d0
24 changed files with 1119 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 编码规则
+
+> 每次写代码前先读完本文件。与技术细节冲突时，以 [`03-tech-stack.md`](03-tech-stack.md) 和 [`04-architecture.md`](04-architecture.md) 为准。
+
+## 黄金法则
+
+1. 不臆造：字段、接口、依赖和文件必须来自当前代码或文档。
+2. 守范围：只做当前任务，不顺手加后续功能。
+3. 照架构：使用既有 Wails、Vue、SQLite、平台模块边界。
+4. 小步改：一次解决一个问题，不夹带无关重构。
+5. 可验证：完成前必须测试或构建通过。
+
+## 动手前
+
+- 先读 `AGENTS.md`、`00-ai-start-here.md`、`current-state.md` 和当前任务。
+- 查找现有函数、组件、工具和测试，复用优先。
+- 需求不清或会影响架构时，先说明问题再决定。
+- 不确定 Wails API 时，优先看本项目现有代码和已锁版本，不直接按最新文档改。
+
+## 代码规范
+
+- Go 代码用 `gofmt`。
+- TypeScript / Vue 保持当前项目风格。
+- 错误必须返回或展示，不静默吞掉。
+- 后端服务方法签名变化必须同步前端 bindings。
+- 前端 UI 文案走现有 i18n 体系，避免新增硬编码中文/英文。
+- 新依赖必须说明必要性；能用标准库或现有依赖解决时不新增。
+
+## 模块规则
+
+- `main.go` 不写业务逻辑。
+- SQLite 读写集中在 store 或明确服务层，不散落到多个模块。
+- 平台差异放在 `platform/`。
+- 前端 bindings 不承载业务逻辑。
+- 通用 UI 组件保持小而直接，不为未来需求提前抽象。
+
+## 验证要求
+
+代码改动完成前至少运行相关命令：
+
+```powershell
+go test ./...
+cd frontend
+npm run build
+cd ..
+go build -o bin\cmbone.exe .
+```
+
+推荐直接运行：
+
+```powershell
+.\init.ps1
+```
+
+验证失败时，不要标记任务完成。无法运行时，必须在回复和 `progress.md` 里写清原因。
+
+## 绝不
+
+- 不提交密钥、token、密码、本地数据库或用户配置。
+- 不提交 `node_modules`、`frontend/dist`、`bin`。
+- 不用删除测试、降低断言的方式制造通过。
+- 不擅自 reset、checkout 或删除用户未要求删除的文件。
+- 不把依赖升级和功能改动混在同一个任务里。