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 .
+```
@@ -0,0 +1,39 @@
+# 项目愿景
+
+## 项目目标
+
+`cmbone` 的目标是提供一个简单、可维护的 Wails v3 桌面应用基础工程，让后续功能可以在稳定的 Go 后端、Vue 前端和本地 SQLite 存储上继续演进。
+
+当前最重要的结果是：
+
+- 新成员能按 README 和 Harness Coding 文档启动项目。
+- 初级程序员能看懂目录职责和常用命令。
+- 每次改动都有明确任务、验证命令和提交记录。
+
+## 目标用户
+
+- 项目维护者：需要快速判断当前状态、任务边界和验证方式。
+- 初级前端 / 后端程序员：需要沿着清晰模块做小范围改动。
+- AI coding agent：需要稳定的上下文入口、任务看板和质量规则。
+
+## 产品方向
+
+短期方向是桌面工具壳和设置中心：
+
+- 主窗口负责常驻设置、快捷键和信息展示。
+- 第二窗口用于快捷打开轻量功能，如 OCR 示例。
+- 后端服务负责平台能力、本地配置和数据持久化。
+
+## 非目标
+
+- 现在不做云端账号、远程同步、复杂权限、支付或 SaaS 化。
+- 现在不把项目改造成大型前端单页应用。
+- 现在不引入 Electron、Tauri 或其他桌面框架替代 Wails。
+- 现在不追逐 latest 依赖版本，优先保持当前 Go 1.23.0 可构建。
+
+## 成功标准
+
+- 文档、目录、命令和代码事实一致。
+- `.\init.ps1` 可以完成依赖安装、测试、前端构建和后端编译。
+- 新增功能能落在明确模块内，不需要跨多层猜测。
+- 提交历史能看出每次改动的意图和验证结果。
@@ -0,0 +1,45 @@
+# 需求说明
+
+## MVP 范围
+
+### P0 · 必须保持
+
+- 应用能启动 Wails 主窗口，并加载嵌入的 `frontend/dist` 资源。
+- 主窗口包含 Dashboard、General、Shortcut、Tags、About 等现有区域。
+- 多语言资源能从 `frontend/src/locales/*.json` 加载，并能通过 UI / 服务切换。
+- 主题配置能保存到本地 SQLite 并在前端生效。
+- 快捷键配置能从数据库读取、更新，并注册到系统热键层。
+- 托盘菜单能执行显示、隐藏、语言切换和退出等基础动作。
+- 第二窗口能通过热键或服务打开，承载 OCR 示例页面。
+- `go test ./...`、`npm run build`、`go build -o bin/cmbone.exe .` 通过。
+
+### P1 · 近期增强
+
+- 明确主窗口默认大小、最大化策略和自适应布局规则。
+- 补齐热键服务、配置服务、存储迁移的边界测试。
+- OCR 失败时给出可理解的前端反馈。
+- 文档化 Wails bindings 生成流程。
+
+### P2 · 后续再做
+
+- 发布安装包和自动更新。
+- 更完整的系统通知能力。
+- 可配置插件或更多工具模块。
+- 业务化功能闭环。
+
+## 验收标准
+
+每个任务完成前至少满足：
+
+- 相关代码已格式化。
+- 相关单元测试或构建命令通过。
+- 前端页面在目标窗口尺寸下没有明显溢出或不可用控件。
+- 文档中的命令、版本、接口和当前代码一致。
+- `progress.md` 记录了本次验证命令和结果。
+
+## 约束
+
+- 当前 Go 版本为 `1.23.0`。
+- Wails 版本固定为 `v3.0.0-alpha.9`。
+- 前端 runtime 固定为 `@wailsio/runtime 3.0.0-alpha.66`。
+- 不提交 `node_modules`、`dist`、`bin`、本地数据库或用户配置。
@@ -0,0 +1,96 @@
+# 技术栈
+
+## 后端
+
+- Go：`1.23.0`
+- 桌面框架：`github.com/wailsapp/wails/v3 v3.0.0-alpha.9`
+- 本地数据库：`modernc.org/sqlite v1.38.2`
+- 系统热键：`golang.design/x/hotkey v0.4.1`
+
+Wails CLI 安装命令：
+
+```powershell
+go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9
+```
+
+不要直接安装 `wails3@latest`，避免 CLI、Go SDK 和前端 runtime 版本不匹配。
+
+## 前端
+
+- Vue：`^3.2.45`
+- TypeScript：`^4.9.3`
+- Vite：`^8.1.3`
+- Wails runtime：`@wailsio/runtime 3.0.0-alpha.66`
+- UI：Ant Design Vue `^4.2.6`
+- 样式：Tailwind CSS `^3.4.1`
+- 国际化：Vue I18n `^11.1.5`
+
+## 目录职责
+
+```text
+.
+├── main.go                  # Wails 应用入口、服务注册、资源嵌入
+├── internal/
+│   ├── models/              # 数据模型
+│   └── services/            # Wails 服务、配置、数据库、热键、OCR
+├── platform/                # Windows / macOS 平台差异实现
+├── frontend/
+│   ├── src/                 # Vue 源码
+│   ├── bindings/            # Wails 生成的前端绑定
+│   └── dist/                # 前端构建产物，git 忽略
+├── build/                   # Wails 打包配置
+└── docs/                    # Harness Coding 文档
+```
+
+## 常用命令
+
+安装前端依赖：
+
+```powershell
+cd frontend
+npm install
+```
+
+后端测试：
+
+```powershell
+go test ./...
+```
+
+前端构建：
+
+```powershell
+cd frontend
+npm run build
+```
+
+后端编译：
+
+```powershell
+go build -o bin\cmbone.exe .
+```
+
+统一验证入口：
+
+```powershell
+.\init.ps1
+```
+
+开发启动：
+
+```powershell
+wails3 dev
+```
+
+打包：
+
+```powershell
+wails3 package
+```
+
+## 版本升级规则
+
+- 升级 Go 前，先确认 Wails v3 alpha、SQLite 和热键库的兼容性。
+- 升级 Wails 后，同时检查 `@wailsio/runtime` 和 `frontend/bindings`。
+- 升级 Vite / TypeScript 后，必须跑 `npm run build`。
+- 依赖升级必须单独提交，不和业务功能混在一起。
@@ -0,0 +1,97 @@
+# 架构设计
+
+## 总览
+
+```text
+main.go
+  ├─ Wails application
+  ├─ embedded frontend/dist
+  ├─ embedded frontend/src/locales/*.json
+  └─ services
+       ├─ AppService
+       ├─ AppConfigService
+       ├─ HotkeyService
+       ├─ SystemInfo
+       └─ OCRService
+
+frontend/src
+  ├─ router
+  ├─ components
+  ├─ pages
+  ├─ utils
+  └─ locales
+```
+
+前端通过 `frontend/bindings` 调用 Wails 暴露的 Go 服务。后端服务访问本地 SQLite、平台热键和系统能力。
+
+## 后端边界
+
+- `main.go`：只负责应用组装、资源嵌入、服务注册和启动。
+- `internal/models/`：定义数据库和服务返回的结构体。
+- `internal/services/store.go`：负责 SQLite 连接、迁移和基础读写。
+- `internal/services/appservice.go`：负责窗口、托盘、语言资源和应用生命周期。
+- `internal/services/appconfig_service.go`：负责配置读写的 Wails 服务边界。
+- `internal/services/hotkey_service.go`：负责热键读取、更新和重新注册。
+- `internal/services/ocr_service.go`：负责 OCR 服务入口。
+- `platform/`：隔离 Windows / macOS 热键和系统能力差异。
+
+服务之间不要互相绕过边界直接操作平台实现。新增平台能力时，优先放在 `platform/`，再由 `internal/services/` 暴露稳定方法。
+
+## 前端边界
+
+- `frontend/src/router/index.ts`：只维护页面路由。
+- `frontend/src/components/Main/Index.vue`：主窗口布局入口。
+- `frontend/src/components/Setting/`：设置项和通用设置控件。
+- `frontend/src/components/Shortcut/`：快捷键设置。
+- `frontend/src/pages/Home/Index.vue`：第二窗口 / OCR 页面。
+- `frontend/src/utils/`：国际化、主题、OS 和热键工具函数。
+- `frontend/bindings/`：由 Wails 生成或按 Wails 合约维护，不写业务逻辑。
+
+## 数据模型
+
+SQLite 数据库位于用户配置目录下的 `cmbone/cmbone.db`，不进入 git。
+
+当前核心表：
+
+```sql
+hotkeys(
+  id INTEGER PRIMARY KEY,
+  keycode INTEGER,
+  modifiers INTEGER,
+  description TEXT,
+  target TEXT
+)
+```
+
+```sql
+appconfig(
+  id INTEGER PRIMARY KEY,
+  key TEXT,
+  type TEXT,
+  value TEXT,
+  description TEXT,
+  state INTEGER
+)
+```
+
+迁移要求：
+
+- 初始化必须幂等。
+- 新字段必须有默认值或迁移逻辑。
+- schema 变化必须同步 `store_test.go`、`api.md` 和 `current-state.md`。
+
+## 窗口与事件
+
+- 主窗口路由：`/#/`
+- 第二窗口路由：`/#/second`
+- 托盘菜单由 `AppService` 配置。
+- 热键触发目标当前包含打开第二窗口。
+
+窗口策略应保持简单：主窗口负责配置和信息，第二窗口负责轻量快捷功能。不要把长期复杂流程塞入第二窗口。
+
+## 关键风险
+
+- Wails v3 仍是 alpha，CLI、Go 模块和 runtime 必须保持匹配。
+- bindings 若与 Go 服务签名不一致，前端会在运行时失败。
+- OCR 和热键依赖平台能力，跨平台修改必须分别验证。
+- Vite 构建可能出现 chunk size warning，警告不等于失败，但需要避免无节制增加前端体积。
@@ -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 或删除用户未要求删除的文件。
+- 不把依赖升级和功能改动混在同一个任务里。
@@ -0,0 +1,51 @@
+# 任务看板
+
+> 单 agent / 小项目使用本文件。多 agent 并发时，改用 [`tasks/README.md`](tasks/README.md) 的一任务一文件规则。
+
+## 使用规则
+
+1. 一次只做一个任务：领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
+2. 开始后把状态改为 `DOING`。
+3. 完成并验证后把状态改为 `DONE`。
+4. 任务完成必须在 [`../progress.md`](../progress.md) 写入验证命令和结果。
+5. 完成后更新 [`current-state.md`](current-state.md)，并过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。
+
+## 状态图例
+
+`TODO` 待开始 · `DOING` 进行中 · `DONE` 已完成并验收 · `BLOCKED` 受阻
+
+## Phase 0 · 基线
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-000 | 接入 Harness Coding 文档 | - | `AGENTS.md`、`docs/`、`progress.md`、`init.ps1`、`init.sh` 已创建；README 已登记入口；统一验证通过 | DONE |
+| T-001 | 验证迁移后构建基线 | T-000 | `go test ./...`、`npm run build`、`go build -o bin/cmbone.exe .` 通过 | DONE |
+
+## Phase 1 · 近期维护
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-010 | 梳理主窗口最大化与自适应布局策略 | T-001 | 明确是否默认最大化；主内容区域能填满空余空间；移动/小窗口尺寸下无明显溢出；更新 `routes.md` 或架构说明 | TODO |
+| T-011 | 文档化 Wails bindings 生成流程 | T-001 | README 或技术栈文档说明 `wails3 generate bindings` 的使用、失败处理和版本要求 | TODO |
+| T-012 | 增加前端最小质量检查 | T-001 | 前端至少保留 `npm run build`；如新增 lint/test，命令写入 `package.json` 和文档 | TODO |
+
+## Phase 2 · 服务边界
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-020 | 补强 SQLite 初始化测试 | T-001 | `store_test.go` 覆盖默认配置和热键初始化；`go test ./...` 通过 | TODO |
+| T-021 | 收敛热键服务错误处理 | T-020 | 注册失败、更新失败和重复注册路径有明确错误返回或日志 | TODO |
+| T-022 | 完善 OCR 失败反馈 | T-001 | OCR 失败时前端能展示可理解提示；后端错误不被吞掉 | TODO |
+
+## Phase 3 · 发布准备
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-030 | 补充 Windows 打包验证文档 | T-011 | `wails3 package` 前置条件、输出目录和常见失败处理写入 README 或 docs | TODO |
+| T-031 | 完成一次人工 smoke 清单 | T-010 | 主窗口、第二窗口、语言、主题、热键、托盘都按清单验证并记录结果 | TODO |
+
+## Backlog
+
+- 梳理应用真实产品方向和名称。
+- 评估是否需要 Playwright / Vitest 覆盖前端关键页面。
+- 评估是否需要平台能力降级策略。
@@ -0,0 +1,27 @@
+# Harness Coding 文档导航
+
+本目录用于让后续 AI coding agent 和初级维护者快速恢复上下文、领取任务、验证改动。
+
+## 必读入口
+
+- [`00-ai-start-here.md`](00-ai-start-here.md)：AI 开发入口和固定开工流程。
+- [`01-vision.md`](01-vision.md)：产品目标、用户和非目标。
+- [`02-requirements.md`](02-requirements.md)：MVP 范围和验收标准。
+- [`03-tech-stack.md`](03-tech-stack.md)：真实技术栈、版本和命令。
+- [`04-architecture.md`](04-architecture.md)：模块边界、数据流和风险点。
+- [`05-coding-rules.md`](05-coding-rules.md)：编码规则和验证纪律。
+- [`06-tasks.md`](06-tasks.md)：当前任务看板。
+
+## 辅助文档
+
+- [`api.md`](api.md)：Wails 服务方法和本地模块合约。
+- [`routes.md`](routes.md)：前端路由和页面职责。
+- [`current-state.md`](current-state.md)：当前可运行状态、命令和下一步。
+- [`clean-state-checklist.md`](clean-state-checklist.md)：交接前清理检查。
+- [`method-map.md`](method-map.md)：关键方法和文件索引。
+- [`quality-document.md`](quality-document.md)：质量分层和风险登记。
+- [`evaluator-rubric.md`](evaluator-rubric.md)：评估标准。
+- [`adoption-checklist.md`](adoption-checklist.md)：Harness Coding 接入检查。
+- [`tasks/README.md`](tasks/README.md)：多 agent 时的一任务一文件规则。
+
+根目录 [`../progress.md`](../progress.md) 记录历史执行流水和验证证据。
@@ -0,0 +1,19 @@
+# Harness Coding 接入检查
+
+## 已完成
+
+- [x] 添加 `AGENTS.md` 作为仓库级 AI 入口。
+- [x] 添加 `CLAUDE.md` 指向仓库级规则。
+- [x] 添加 `docs/00-ai-start-here.md` 作为固定开工流程。
+- [x] 添加愿景、需求、技术栈、架构、编码规则和任务看板。
+- [x] 添加 API、路由、当前状态、质量、评估和清理检查文档。
+- [x] 添加 `progress.md` 执行流水。
+- [x] 添加 `init.ps1` 和 `init.sh` 统一验证入口。
+- [x] README 已登记 Harness Coding 文档入口。
+
+## 后续维护
+
+- [ ] 每次任务完成后更新 `progress.md`。
+- [ ] 每次状态变化后更新 `docs/current-state.md`。
+- [ ] 每次接口、路由、schema 改动后同步相关文档。
+- [ ] 每次提交前确认 `git status --short` 只包含本任务文件。
@@ -0,0 +1,71 @@
+# API 与模块合约
+
+> 本项目没有远程 HTTP API。这里记录 Wails 暴露给前端的 Go 服务方法和本地模块约定。
+
+## AppService
+
+文件：`internal/services/appservice.go`
+
+- `OpenSecondWindow()`：打开或显示第二窗口。
+- `SetLanguage(lang string) error`：切换应用语言，并刷新相关菜单/状态。
+
+约束：
+
+- 窗口创建、显示、隐藏和托盘菜单逻辑集中在 `AppService`。
+- 语言资源来自 `frontend/src/locales/*.json` 的嵌入文件。
+
+## AppConfigService
+
+文件：`internal/services/appconfig_service.go`
+
+- `GetAppConfig(key string) (string, error)`：读取配置值。
+- `SetAppConfig(key string, value string) error`：保存配置值。
+- `GetLanguage() string`：读取当前语言。
+- `SetLanguage(lang string) error`：保存当前语言。
+
+约束：
+
+- 配置持久化走 SQLite `appconfig` 表。
+- 新增配置项时，必须有默认值和迁移逻辑。
+
+## HotkeyService
+
+文件：`internal/services/hotkey_service.go`
+
+- `GetHotkeys() ([]models.Hotkey, error)`：读取热键配置。
+- `UpHotkey(id int, key int, modifier int) error`：更新热键配置并重新注册。
+
+约束：
+
+- 热键数据来自 SQLite `hotkeys` 表。
+- 平台注册通过 `platform/` 实现，服务层不直接写平台细节。
+- 更新失败时必须返回错误，不只打印日志。
+
+## SystemInfo
+
+文件：`internal/services/systeminfo.go`
+
+- `GetOS() string`：返回当前系统标识。
+
+## OCRService
+
+文件：`internal/services/ocr_service.go`
+
+- `RecognizeImageBase64(base64str string) (string, error)`：识别 base64 图片内容。
+
+约束：
+
+- 失败时返回错误给前端。
+- 平台依赖或能力缺失时，不应导致主窗口不可启动。
+
+## 前端绑定
+
+绑定目录：`frontend/bindings/cmbone/internal/services`
+
+服务签名变化后优先执行：
+
+```powershell
+wails3 generate bindings
+```
+
+如果本地无法生成 bindings，只允许根据现有绑定模式做最小修正，并在 `progress.md` 写清原因和验证结果。
@@ -0,0 +1,30 @@
+# Clean State Checklist
+
+每轮结束前检查，确保下一位维护者可以直接接手。
+
+## 代码与文档
+
+- [ ] 当前任务只改了必要文件。
+- [ ] 没有夹带依赖升级或无关重构。
+- [ ] README、docs、API、路由、架构和实际代码一致。
+- [ ] 任务状态已更新。
+- [ ] `progress.md` 已记录验证命令和结果。
+- [ ] `current-state.md` 已更新当前状态和下一步。
+
+## 构建与测试
+
+- [ ] `go test ./...` 通过，或已记录失败原因。
+- [ ] `cd frontend && npm run build` 通过，或已记录失败原因。
+- [ ] `go build -o bin/cmbone.exe .` 通过，或已记录失败原因。
+- [ ] 涉及 UI 时，已人工检查目标窗口尺寸。
+
+## Git
+
+- [ ] `git status --short` 中只包含本任务相关文件。
+- [ ] 未提交 `bin/`、`frontend/dist/`、`frontend/node_modules/`。
+- [ ] 提交信息能说明本次任务意图。
+
+## 运行
+
+- [ ] 如改动影响启动，已确认应用能打开主窗口。
+- [ ] 如改动影响热键、托盘或 OCR，已记录人工 smoke 结果。
@@ -0,0 +1,75 @@
+# 当前状态
+
+更新时间：2026-07-08
+
+## 当前阶段
+
+项目处于迁移后基线稳定和 Harness Coding 文档接入阶段。当前主要任务是保持 Wails/Vue/SQLite 工程简单、可构建、可维护。
+
+## 已确认事实
+
+- Go 模块名：`cmbone`
+- Go 版本：`1.23.0`
+- Wails 版本：`v3.0.0-alpha.9`
+- 前端 runtime：`@wailsio/runtime 3.0.0-alpha.66`
+- 前端框架：Vue 3、Vite、TypeScript、Tailwind CSS、Ant Design Vue
+- 本地数据库：SQLite，用户配置目录下 `cmbone/cmbone.db`
+- 主窗口路由：`/#/`
+- 第二窗口路由：`/#/second`
+
+## 当前命令
+
+统一验证：
+
+```powershell
+.\init.ps1
+```
+
+拆分验证：
+
+```powershell
+go test ./...
+cd frontend
+npm run build
+cd ..
+go build -o bin\cmbone.exe .
+```
+
+Wails CLI：
+
+```powershell
+go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9
+wails3 dev
+```
+
+## 已知风险
+
+- Wails v3 alpha 版本需要保持 CLI、Go 模块和前端 runtime 匹配。
+- OCR 和热键依赖平台实现，跨平台修改需要分别验证。
+- 当前前端以构建检查为主，暂未引入专门的前端单元测试。
+- bindings 生成依赖本机安装的 `wails3`。
+- `npm install` 当前报告 3 个 moderate audit findings，后续如做依赖治理应单独开任务。
+- 前端构建当前有 Browserslist 数据过期和 chunk 大小警告，不阻塞生产构建。
+
+## 最近验证
+
+2026-07-08 已运行：
+
+```powershell
+.\init.ps1
+```
+
+结果：
+
+- `npm install` 通过。
+- `go test ./...` 通过。
+- `npm run build` 通过。
+- `go build -o bin\cmbone.exe .` 通过。
+
+## 下一步
+
+从 [`06-tasks.md`](06-tasks.md) 领取第一个 `TODO` 任务。目前建议先做 `T-010`：梳理主窗口最大化与自适应布局策略。
+
+## 当前 blocker
+
+无。
@@ -0,0 +1,38 @@
+# 评估标准
+
+用于 code review、交接和 AI 输出自检。
+
+## 必须满足
+
+- 能说明本次改动对应哪个任务。
+- 没有超出任务范围。
+- 版本、命令、路径和当前代码事实一致。
+- 相关构建或测试命令已运行并记录结果。
+- 没有提交构建产物、依赖目录或本地配置。
+
+## 代码质量
+
+| 等级 | 标准 |
+| --- | --- |
+| A | 改动小、边界清楚、测试充分、文档同步、无明显维护风险 |
+| B | 功能正确、构建通过、文档基本同步，仍有少量后续优化空间 |
+| C | 可运行但边界或错误处理薄弱，需要安排后续任务 |
+| D | 构建失败、范围失控、接口不一致或缺少关键验证 |
+
+## UI 质量
+
+| 等级 | 标准 |
+| --- | --- |
+| A | 布局稳定、信息密度合适、窗口尺寸变化时无溢出 |
+| B | 主要路径可用，局部样式可继续优化 |
+| C | 功能可用但有明显布局问题或交互不清 |
+| D | 关键控件不可用、文本重叠或页面无法加载 |
+
+## 文档质量
+
+| 等级 | 标准 |
+| --- | --- |
+| A | 文档能直接指导新维护者执行任务和验证 |
+| B | 主要事实正确，少量细节需要补充 |
+| C | 有导航但缺少真实命令或验收标准 |
+| D | 文档与代码冲突，可能误导维护者 |
@@ -0,0 +1,45 @@
+# 方法地图
+
+> 维护者查找入口时先看这里，再进入具体文件。
+
+## 应用启动
+
+| 文件 | 方法 / 内容 | 说明 |
+| --- | --- | --- |
+| `main.go` | `main()` | 创建 Wails app、注册服务、嵌入资源、启动应用 |
+| `internal/services/appservice.go` | `ConfigureAppService` | 配置窗口、托盘、语言资源和生命周期 |
+
+## 存储
+
+| 文件 | 方法 / 内容 | 说明 |
+| --- | --- | --- |
+| `internal/services/store.go` | `NewSuiStore` | 打开 SQLite 并执行初始化 |
+| `internal/services/store.go` | migration / CRUD 方法 | 初始化 `hotkeys`、`appconfig` 并提供基础读写 |
+| `internal/services/store_test.go` | store 测试 | 覆盖存储初始化和关键读写 |
+
+## 配置
+
+| 文件 | 方法 / 内容 | 说明 |
+| --- | --- | --- |
+| `internal/services/appconfig_service.go` | `GetAppConfig` / `SetAppConfig` | 前端配置读写入口 |
+| `internal/services/appconfig_service.go` | `GetLanguage` / `SetLanguage` | 语言配置读写入口 |
+
+## 热键
+
+| 文件 | 方法 / 内容 | 说明 |
+| --- | --- | --- |
+| `internal/services/hotkey_service.go` | `GetHotkeys` | 返回当前热键配置 |
+| `internal/services/hotkey_service.go` | `UpHotkey` | 更新热键并重新注册 |
+| `platform/hotkey_windows.go` | Windows 热键实现 | Windows 平台注册逻辑 |
+| `platform/hotkey_darwin.go` | macOS 热键实现 | macOS 平台注册逻辑 |
+
+## 前端
+
+| 文件 | 方法 / 内容 | 说明 |
+| --- | --- | --- |
+| `frontend/src/main.ts` | Vue 入口 | 注册应用、路由和国际化 |
+| `frontend/src/router/index.ts` | routes | `#/` 和 `#/second` 路由 |
+| `frontend/src/components/Main/Index.vue` | 主窗口入口 | 设置页面总布局 |
+| `frontend/src/pages/Home/Index.vue` | 第二窗口入口 | OCR 示例页面 |
+| `frontend/src/utils/ThemeManager.ts` | 主题工具 | 主题切换和持久化协作 |
+| `frontend/src/utils/i18n.ts` | 国际化工具 | 语言资源和切换 |
@@ -0,0 +1,36 @@
+# 质量文档
+
+## 当前质量概览
+
+| 领域 | 当前等级 | 说明 |
+| --- | --- | --- |
+| 项目结构 | B | 已从模板整理为普通工程，目录职责基本清楚 |
+| 后端服务 | B | 服务边界清晰，但热键和 OCR 的错误路径仍可加强 |
+| 本地存储 | B | SQLite 初始化和基础测试已存在，后续可补更多迁移测试 |
+| 前端结构 | B | Vue 组件按功能拆分，主窗口布局策略仍需明确 |
+| 构建验证 | B | Go 测试、前端构建、后端编译可运行 |
+| 文档 | B | Harness Coding 文档已接入，后续随代码继续维护 |
+
+## 主要风险
+
+- Wails v3 alpha 版本兼容性风险。
+- bindings 与 Go 服务签名不一致的运行时风险。
+- 热键和 OCR 跨平台行为不完全一致。
+- 前端缺少专门单元测试，主要依赖构建和人工 smoke。
+
+## 质量门槛
+
+每个代码任务至少达到：
+
+- Go 代码 `gofmt`。
+- `go test ./...` 通过。
+- 涉及前端时 `npm run build` 通过。
+- 涉及后端启动时 `go build -o bin/cmbone.exe .` 通过。
+- 涉及 UI 时完成对应窗口的人工检查。
+
+## 改进方向
+
+- 为存储迁移、配置服务、热键服务补充更细测试。
+- 为主窗口最大化和自适应布局建立明确规则。
+- 为 OCR 失败、热键注册失败补充用户可理解反馈。
+- 为 Wails bindings 生成流程补充完整操作说明。
@@ -0,0 +1,29 @@
+# 前端路由
+
+路由定义文件：`frontend/src/router/index.ts`
+
+当前使用 hash history，适配 Wails 桌面窗口。
+
+## 路由表
+
+| 路由 | 组件 | 窗口 | 职责 |
+| --- | --- | --- | --- |
+| `#/` | `frontend/src/components/Main/Index.vue` | 主窗口 | 设置中心、导航、主题、语言、快捷键、标签、关于等 |
+| `#/second` | `frontend/src/pages/Home/Index.vue` | 第二窗口 | OCR 示例和轻量快捷功能 |
+
+## 主窗口区域
+
+主窗口当前由 `Main/Index.vue` 组织以下区域：
+
+- Dashboard：概览。
+- General：通用设置。
+- Shortcut：快捷键设置。
+- Tags：标签相关展示。
+- About：关于信息。
+
+## 页面规则
+
+- 新增页面必须先确认是否属于主窗口长期功能，还是第二窗口轻量功能。
+- 主窗口应优先使用可维护的设置布局，不做营销式首页。
+- 第二窗口保持小而聚焦，不承载复杂流程。
+- 路由变化必须同步本文和相关任务验收。
@@ -0,0 +1,18 @@
+# 一任务一文件规则
+
+默认情况下，本项目使用 [`../06-tasks.md`](../06-tasks.md) 作为单文件任务看板。
+
+当多人或多个 agent 并发工作时，为避免抢改同一个看板，改用本目录的一任务一文件方式：
+
+1. 新任务复制 [`_template.md`](_template.md)。
+2. 文件命名为 `T-<编号>-<短名称>.md`。
+3. 状态写在文件 frontmatter。
+4. 执行记录写入该任务文件的 `## 执行记录`。
+5. 不再逐任务追加根目录 `progress.md`，只在里程碑或交接时同步摘要。
+
+## 状态
+
+- `TODO`：待开始。
+- `DOING`：进行中。
+- `DONE`：完成并通过验收。
+- `BLOCKED`：受阻，需要明确原因。
@@ -0,0 +1,27 @@
+---
+id: T-000
+title: 任务标题
+status: TODO
+depends_on: []
+owner: ""
+---
+
+# 任务标题
+
+## 背景
+
+说明为什么要做这个任务。
+
+## 范围
+
+- 做什么。
+- 不做什么。
+
+## 验收标准
+
+- [ ] 可观察、可执行的验收点。
+- [ ] 相关测试或构建命令通过。
+
+## 执行记录
+
+尚未开始。