cmbone/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。硬性编码规则见 05-coding-rules.md。

一句话定位

cmbone 是一个 Wails v3 + Vue 3 + SQLite 的本地桌面应用骨架，当前重点是保持可运行、可构建、可维护。

第一版 MVP 只做：桌面主窗口、设置页、多语言、主题、本地配置、热键、托盘和 OCR 示例窗口的稳定闭环。

必读顺序

每次开始写代码前，按这个顺序建立上下文：

1. 01-vision.md：为什么做、为谁做、什么不做。
2. 02-requirements.md：MVP 要什么、怎么算达成。
3. 03-tech-stack.md：既定技术选型。
4. 04-architecture.md：系统结构、职责划分、数据模型和关键难点。
5. 05-coding-rules.md：写代码前必须遵守的规则。
6. 06-tasks.md：领取本轮唯一任务。
7. ../progress.md：历史执行记录、验证结果、阻塞点和关键决策。
8. current-state.md：当前代码现实、可运行命令、下一步任务。

仓库根目录的 AGENTS.md 和 CLAUDE.md 是仓库级规则，优先级高于本目录中的建议。

固定开工流程

1. pwd：确认在 D:\chengma\cmbone 或对应克隆目录。
2. 读 ../progress.md 和 current-state.md：恢复已验证状态、下一步和当前 blocker。
3. git log --oneline -5：看清最近发生了什么。
4. 运行 .\init.ps1，Git Bash / WSL 用 ./init.sh。
5. 如果基线失败，先修基线，不在坏的起点上叠新功能。
6. 基线绿了，再从 06-tasks.md 领取唯一任务。

当前阶段

当前项目处于：MVP 基线整理与文档接入阶段。

优先路径：

1. Phase 0：保持可运行、可测试、可构建。
2. Phase 1：收敛 Wails 服务、前端绑定和本地存储边界。
3. Phase 2：完善主窗口和第二窗口的真实用户流程。
4. Phase 3：补齐最小测试和发布文档。

领取任务规则

• 只领取第一个状态为 TODO 且依赖均为 DONE 的任务。
• 开始前把该任务状态改为 DOING。
• 本轮只完成这一个任务。
• 验收通过后把状态改为 DONE。
• 完成后把执行记录追加到 ../progress.md，并覆盖更新 current-state.md 的当前快照。
• 结束会话前过一遍 clean-state-checklist.md。

MVP 边界

MVP 只做：

• 主窗口能启动并展示设置、快捷键、标签、关于等基础页面。
• 本地 SQLite 能初始化并保存配置和热键。
• 托盘菜单、语言切换、主题切换、快捷键和第二窗口能按现有设计工作。
• 前端构建、后端测试和后端编译保持通过。

MVP 不做：

• 云端账号、同步、付费和远程 API。
• 复杂任务管理或业务工作流。
• 未确认产品方向前的大型 UI 重构。
• 未验证兼容性的 Wails / Go / Vite 大版本升级。

常见任务该看哪里

做页面 / UI：先看 02-requirements.md、routes.md，再看现有 Vue 组件。

做后端服务：先看 api.md、04-architecture.md，再看 internal/services/。

做数据模型：先看 04-architecture.md，改 schema 后必须同步更新相关文档和测试。

做运行 / 打包：先看 03-tech-stack.md 和 current-state.md。

验证命令

.\init.ps1

等价拆分命令：

go test ./...
cd frontend
npm run build
cd ..
go build -o bin\cmbone.exe .