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

AI 开发入口

ShopHelm coding agent 的固定入口。硬性实现规则见 05-coding-rules.md。

一句话定位

ShopHelm 是面向小团队跨境卖家的 Windows 本地运营工作台。

首发闭环是：管理店铺和独立 Chrome profile，维护商品草稿与简单图片合成，复用多语言客服话术并记录跟进。

必读顺序

每次写代码前完整读取：

1. ../AGENTS.md
2. 01-vision.md
3. 02-requirements.md
4. 03-tech-stack.md
5. 04-architecture.md
6. 05-coding-rules.md
7. 与任务相关的 api.md 和 routes.md
8. 06-tasks.md
9. ../progress.md
10. current-state.md

固定开工流程

1. pwd，确认根目录是 D:\OPC\shop_helm。
2. 读取 progress.md 和 current-state.md。
3. 若有 .git，运行 git status --short --branch 和 git log --oneline -5。
4. 若有 go.mod，运行 ./init.ps1；若没有，只领取 T-001。
5. 若基线测试或构建失败，先记录并修复基线。
6. 在 06-tasks.md 中领取第一个 TODO 且依赖均为 DONE 的任务。
7. 把任务改为 DOING 后再编辑代码。

当前阶段

当前处于“文档基线完成、生产代码尚未初始化”阶段。

实施顺序：

1. Phase 0：Go、Gio、SQLite 工程地基。
2. Phase 1：先验证 Gio 表格/表单、Chrome profile 启动、图片预览与导出三个高风险点。
3. Phase 2：业务阶段一，多店铺运营台。
4. Phase 3：业务阶段四，商品运营助手。
5. Phase 4：业务阶段五，客服助手。
6. Phase 5：稳定性、完整验收和 Windows 打包。

领取和完成规则

• 一轮只领取一个任务。
• 依赖未完成不跳步。
• DOING 同一时间最多一个。
• 验收必须使用任务中列出的命令和可观察步骤。
• 只有代码、测试、文档和手工 smoke 全部符合时才能标 DONE。
• 完成后追加 progress.md，覆盖更新 current-state.md，再执行 clean-state-checklist.md。
• 多 agent 并发时改用 tasks/README.md，执行记录写入各自任务文件。

首发范围

首发必须交付：

• 今日工作台。
• 店铺 CRUD、筛选、快捷入口、独立 Chrome profile、普通无认证代理、运行状态、备份恢复。
• 商品草稿、文案模板、价格计算、检查清单、CSV/XLSX、图片素材。
• 一张底图加一张叠加图的预览、位置/缩放/透明度调整及 PNG/JPG 导出。
• 多语言客服话术、一键复制、买家问题与跟进提醒。

首发明确不做：

• 平台账号密码保存。
• 代理账号密码自动注入。
• 自动登录、验证码处理、批量发消息、批量改商品。
• 反指纹、防关联、绕过风控或批量爬取。
• 完整订单、库存、财务、广告和团队权限系统。
• Photoshop 式多图层、滤镜、抠图和复杂排版。

事实来源

业务和技术事实只信：

• 本仓库 docs/ 中的权威文档。
• 已应用的 SQLite migration。
• go.mod / go.sum 中已锁定的依赖。
• 当前代码、测试和真实运行结果。
• 第三方平台的官方文档；使用前需在任务中记录具体来源和访问日期。

不把聊天记忆、旧导出文件、浏览器页面猜测、临时实验或未引用草稿当作当前事实。

常见任务入口

做 Gio 页面：

1. 查 02-requirements.md 的需求 ID。
2. 查 routes.md 的页面职责。
3. 查 api.md 的服务调用。
4. 遵守 04-architecture.md 的 UI 异步边界。

做 SQLite：

1. 查 04-architecture.md 的数据模型。
2. 新增不可变 migration。
3. 同步 repository、api.md 和相关测试。

做 Chrome 启动：

1. 查 api.md 的 BrowserLauncher 合约。
2. 只使用外部 Chrome 和独立 profile。
3. 检查 profile 占用、启动参数、进程状态和错误映射。

做图片：

1. Gio 只负责交互和预览。
2. 正式导出走独立 CPU 合成管线。
3. 校验预览与导出几何参数一致，且不覆盖原图。

标准命令

T-001 完成前，./init.ps1 会因缺少 go.mod 主动失败。

T-001 完成后：

./init.ps1
go run ./cmd/shophelm
go test ./...
go vet ./...
go build -o build/shophelm.exe ./cmd/shophelm

改动 Gio 交互、Chrome 进程、备份恢复或图片导出时，还需执行对应任务的 Windows 手工 smoke。