# AI 开发入口

> ShopHelm coding agent 的固定入口。硬性实现规则见 [`05-coding-rules.md`](05-coding-rules.md)。

## 一句话定位

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

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

## 必读顺序

每次写代码前完整读取：

1. [`../AGENTS.md`](../AGENTS.md)
2. [`01-vision.md`](01-vision.md)
3. [`02-requirements.md`](02-requirements.md)
4. [`03-tech-stack.md`](03-tech-stack.md)
5. [`04-architecture.md`](04-architecture.md)
6. [`05-coding-rules.md`](05-coding-rules.md)
7. 与任务相关的 [`api.md`](api.md) 和 [`routes.md`](routes.md)
8. [`06-tasks.md`](06-tasks.md)
9. [`../progress.md`](../progress.md)
10. [`current-state.md`](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`](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 完成后：

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

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