cmbone/AGENTS.md

AGENTS.md

Codex / AI coding agent 的仓库级入口。进入本仓库后，先读本文，再进入 docs/00-ai-start-here.md。

项目定位

cmbone 是从 SuiDemo 迁移而来的 Wails v3 本地桌面项目。当前目标是打造一个 Windows-first、可扩展到其他平台的可复用桌面应用模板，而不是某个单一业务产品。

模板要内置常见桌面应用能力：应用壳、设置、登录、主业务模块、操作日志、数据统计和常用业务组件。第一批业务样例使用“电商商品图片 AI 优化”，用来验证模板能否承载真实业务闭环。

项目当前已具备：

• Wails v3 桌面壳和前端嵌入。
• Vue 3 设置页、多语言、主题切换。
• 本地 SQLite 配置和热键表。
• 托盘菜单、快捷键、OCR 示例窗口。

目标模块包括：

• 登录：本地固定账号 provider 和真实后端 provider 两种路径。
• 设置：主题、语言、窗口行为、快捷键、数据目录、日志策略。
• 主业务：商品图片 AI 优化样例，包括任务、结果、失败反馈。
• 操作日志：审计日志和运行日志分开设计。
• 数据统计：图片处理量、成功率、耗时、失败数、日志数和 7 天趋势。
• 常用组件：输入框、多选框、下拉框、多行文本、表格、筛选和分页示例。

必读顺序

每次开始工作前，按顺序读取：

1. README.md：了解项目运行、构建和维护约定。
2. docs/README.md：了解 Harness Coding 文档导航。
3. docs/00-ai-start-here.md：进入固定开工流程。
4. docs/05-coding-rules.md：确认编码纪律。
5. docs/current-state.md：确认当前真实状态。
6. progress.md：查看最近验证结果和决策。
7. 与当前任务相关的具体文档。

工作规则

• 只做当前任务要求的改动，不夹带重构、依赖升级或无验收标准的产品扩展。
• 保持 Go 1.23.0、Wails v3.0.0-alpha.9、@wailsio/runtime 3.0.0-alpha.66 的兼容关系；不要直接升级到 latest。
• 不提交 bin/、frontend/dist/、frontend/node_modules/ 等构建产物或依赖目录。
• 后端服务方法变更后，优先使用 wails3 generate bindings 重新生成 frontend/bindings；如果本机没有 CLI，只允许小范围手动修正并在 progress.md 记录原因。
• 涉及存储结构时，同步更新 docs/04-architecture.md、docs/api.md、docs/current-state.md 和相关任务验收。
• 登录、日志、统计和业务样例必须通过 provider / service 边界接入，不把演示逻辑写死在前端页面里。
• 自研组件库不是目标；优先复用 Ant Design Vue，并沉淀项目级组合组件和使用示例。
• 提交前至少运行 go test ./...、cd frontend && npm run build、go build -o bin/cmbone.exe .。

风格

• 文档默认中文，代码标识符默认英文。
• 优先复用现有服务、组件和工具函数。
• 错误必须处理，不吞错。
• 注释只解释不明显的原因，不复述代码。
• 新增抽象必须能减少真实复杂度，否则保持直接实现。

验证入口

Windows 原生 PowerShell 使用：

.\init.ps1

Git Bash / WSL / macOS / Linux 使用：

./init.sh

脚本会安装前端依赖、运行后端测试、构建前端、编译后端，并打印开发启动命令。