后端：Go 1.23.0、Wails v3.0.0-alpha.9、SQLite
前端：Vue 3、TypeScript、Vite、Tailwind CSS、Ant Design Vue
当前功能：多语言、主题切换、统一设置 schema、主窗口状态恢复、本地配置、快捷键、本地登录 provider、商品图片 AI 优化页面、本地模拟图片优化任务、审计日志、运行日志、P0 数据统计服务、常用组件示例页、OCR 示例
目标模板模块：登录、设置、主业务、审计日志、运行日志、数据统计、常用组件示例

环境准备

当前项目按本机 Go 1.23.0 锁定依赖，不要直接安装 wails3@latest。

go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.9

如果安装后 PowerShell 找不到 wails3，把 Go bin 目录加入当前终端 PATH：

$env:Path += ";$(go env GOPATH)\bin"
wails3 doctor

目录结构

.
├── main.go                  # Wails 应用入口
├── internal/
│   ├── models/              # 后端数据模型
│   └── services/            # 后端服务和数据库逻辑
├── platform/                # Windows/macOS 平台差异代码
├── frontend/
│   ├── src/                 # Vue 前端源码
│   ├── bindings/            # Wails 前端绑定
│   └── dist/                # 前端构建产物，供 Go embed 使用
└── build/                   # Wails 构建配置

常用命令

go test ./...

cd frontend
npm install
npm run build

安装 wails3 后可以使用：

wails3 dev
wails3 build

Windows 下也可以直接运行：

.\dev.bat
.\build.bat

dev.bat 会从 9245 开始选择一个空闲 Vite 端口，避免已有 dev server 占用端口时无法打开 GUI。开发启动使用快速前端 dev 构建以尽快打开桌面窗口；提交前仍以 npm run build 做完整 TypeScript 检查和生产构建。

Windows 打包验证见 docs/windows-packaging.md。当前默认打包路径是 NSIS，要求本机安装 makensis。

Wails Bindings

修改 Go 服务的公开方法、参数模型、返回模型，或在 main.go 注册新服务后，需要从项目根目录重新生成前端 bindings：

$env:Path += ";$(go env GOPATH)\bin"
wails3 generate bindings -clean=true

当前固定使用 wails3 v3.0.0-alpha.9，前端 runtime 固定为 @wailsio/runtime 3.0.0-alpha.66。不要用 latest 混装。

常见失败处理：

wails3 找不到：先按环境准备安装固定版本，或把 $(go env GOPATH)\bin 加入当前终端 PATH。
生成失败：先运行 go test ./... 或 go build -o bin\cmbone.exe . 修复 Go 编译错误。
前端 import 失效：重新执行 wails3 generate bindings -clean=true，前端源码继续使用无扩展名 import。

生成后提交 frontend/bindings 的变更，并运行 npm run build 验证前端类型和打包。

本地演示登录账号为 admin / admin123；密码由后端初始化为 hash，不写在前端页面里。

维护约定

Go 模块名统一为 cmbone。
当前依赖按系统 Go 1.23.0 锁定，升级 Go 前不要随意升级 Wails、SQLite 或热键库。
修改后端服务后，优先使用 wails3 generate bindings 重新生成 frontend/bindings；如果本机没有 CLI，只做小范围手动绑定。
提交前至少运行 go test ./... 和 npm run build。
模板能力按任务逐步落地，不一次性堆完整平台；优先保证 Windows 10+ 体验和可维护性。

Harness Coding 文档

本项目已接入 Harness Coding 文档，用于让后续维护者和 AI coding agent 快速恢复上下文、领取任务并验证改动。

AGENTS.md：仓库级 agent 入口。
docs/00-ai-start-here.md：固定开工流程。
docs/current-state.md：当前真实状态和命令。
docs/06-tasks.md：任务看板。
docs/windows-packaging.md：Windows 打包验证流程。
docs/smoke-checklist.md：模板 smoke 验证清单。
progress.md：执行流水和验证证据。

统一验证入口：

.\init.ps1

README.md Unescape Escape

cmbone

技术栈