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,95 @@
+# AI 开发入口
+
+> 给 AI coding agent 的项目入口。硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
+
+## 一句话定位
+
+`cmbone` 是一个 Wails v3 + Vue 3 + SQLite 的本地桌面应用骨架，当前重点是保持可运行、可构建、可维护。
+
+第一版 MVP 只做：桌面主窗口、设置页、多语言、主题、本地配置、热键、托盘和 OCR 示例窗口的稳定闭环。
+
+## 必读顺序
+
+每次开始写代码前，按这个顺序建立上下文：
+
+1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
+2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。
+3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。
+4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
+5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
+6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
+7. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。
+8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
+
+仓库根目录的 `AGENTS.md` 和 `CLAUDE.md` 是仓库级规则，优先级高于本目录中的建议。
+
+## 固定开工流程
+
+1. `pwd`：确认在 `D:\chengma\cmbone` 或对应克隆目录。
+2. 读 [`../progress.md`](../progress.md) 和 [`current-state.md`](current-state.md)：恢复已验证状态、下一步和当前 blocker。
+3. `git log --oneline -5`：看清最近发生了什么。
+4. 运行 `.\init.ps1`，Git Bash / WSL 用 `./init.sh`。
+5. 如果基线失败，先修基线，不在坏的起点上叠新功能。
+6. 基线绿了，再从 [`06-tasks.md`](06-tasks.md) 领取唯一任务。
+
+## 当前阶段
+
+当前项目处于：MVP 基线整理与文档接入阶段。
+
+优先路径：
+
+1. Phase 0：保持可运行、可测试、可构建。
+2. Phase 1：收敛 Wails 服务、前端绑定和本地存储边界。
+3. Phase 2：完善主窗口和第二窗口的真实用户流程。
+4. Phase 3：补齐最小测试和发布文档。
+
+## 领取任务规则
+
+- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
+- 开始前把该任务状态改为 `DOING`。
+- 本轮只完成这一个任务。
+- 验收通过后把状态改为 `DONE`。
+- 完成后把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md) 的当前快照。
+- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。
+
+## MVP 边界
+
+MVP 只做：
+
+- 主窗口能启动并展示设置、快捷键、标签、关于等基础页面。
+- 本地 SQLite 能初始化并保存配置和热键。
+- 托盘菜单、语言切换、主题切换、快捷键和第二窗口能按现有设计工作。
+- 前端构建、后端测试和后端编译保持通过。
+
+MVP 不做：
+
+- 云端账号、同步、付费和远程 API。
+- 复杂任务管理或业务工作流。
+- 未确认产品方向前的大型 UI 重构。
+- 未验证兼容性的 Wails / Go / Vite 大版本升级。
+
+## 常见任务该看哪里
+
+做页面 / UI：先看 [`02-requirements.md`](02-requirements.md)、[`routes.md`](routes.md)，再看现有 Vue 组件。
+
+做后端服务：先看 [`api.md`](api.md)、[`04-architecture.md`](04-architecture.md)，再看 `internal/services/`。
+
+做数据模型：先看 [`04-architecture.md`](04-architecture.md)，改 schema 后必须同步更新相关文档和测试。
+
+做运行 / 打包：先看 [`03-tech-stack.md`](03-tech-stack.md) 和 [`current-state.md`](current-state.md)。
+
+## 验证命令
+
+```powershell
+.\init.ps1
+```
+
+等价拆分命令：
+
+```powershell
+go test ./...
+cd frontend
+npm run build
+cd ..
+go build -o bin\cmbone.exe .
+```