# AGENTS.md

> ShopHelm 的仓库级 AI coding agent 入口。进入仓库后先读本文，再读 [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md)。

## 项目定位

ShopHelm（店小航）是面向小团队跨境卖家的 Windows 本地运营工作台。当前只交付三条业务主线：

1. 多店铺运营台。
2. 商品运营助手，其中包含单张商品图叠加预览和导出。
3. 客服话术与跟进助手。

项目采用 Go + Gio、SQLite 和外部 Chrome。它不是完整 ERP，不是浏览器“防关联”产品，也不以全自动 RPA 为核心。

## 事实优先级

发生冲突时按以下顺序处理：

1. 用户在当前会话中的最新明确指令。
2. 本文件的仓库级执行与安全规则。
3. [`docs/02-requirements.md`](docs/02-requirements.md) 的产品范围和验收标准。
4. [`docs/03-tech-stack.md`](docs/03-tech-stack.md)、[`docs/04-architecture.md`](docs/04-architecture.md)、[`docs/api.md`](docs/api.md) 和 [`docs/routes.md`](docs/routes.md) 的技术事实。
5. [`docs/06-tasks.md`](docs/06-tasks.md) 的任务拆分。
6. [`docs/current-state.md`](docs/current-state.md) 和代码、测试所反映的当前现实。

若计划文档与可运行代码冲突，先在 `current-state.md` 记录差异，再确认应修文档还是修实现；不得静默选择一边。

## 必读顺序

每次开始编码前按顺序读取：

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

## 固定开工流程

1. 用 `pwd` 确认仓库根目录。
2. 读取 `progress.md` 和 `docs/current-state.md`，恢复当前事实。
3. 若存在 `.git`，运行 `git status --short --branch` 和 `git log --oneline -5`；若尚未初始化 Git，以 `current-state.md` 为准。
4. 若存在 `go.mod`，运行 `./init.ps1`；若不存在，只允许领取负责初始化项目的 T-001。
5. 基线失败时先修基线，不叠加新功能。
6. 从 `docs/06-tasks.md` 领取第一个依赖均为 `DONE` 的 `TODO` 任务。

## 任务纪律

- 单 agent 模式下一轮只做一个任务。
- 开始前把任务改为 `DOING`；同一时间最多一个 `DOING`。
- 只修改完成该任务所需的代码和文档，不顺手实现 Backlog。
- 验收和验证全部通过后才能改为 `DONE`。
- 把真实命令、结果、阻塞和关键决策追加到 `progress.md`，并覆盖更新 `docs/current-state.md`。
- 会话结束前执行 [`docs/clean-state-checklist.md`](docs/clean-state-checklist.md)。
- 多 agent 并发时切换到 [`docs/tasks/README.md`](docs/tasks/README.md) 的一任务一文件模式。

## 业务与安全硬边界

- 密码、Cookie、token、代理密码不得明文进入 SQLite、日志、测试夹具或文档。
- MVP 不保存平台密码；依靠独立 Chrome profile 保留用户登录会话。
- `user-data-dir` 只表示会话和缓存隔离，不得宣传或实现“防关联”“反指纹”能力。
- Chrome 必须通过 `exec.Command` 参数启动，不拼接 shell 命令。
- 删除或归档店铺时不得自动删除对应 profile 目录。
- 图片导出默认写入独立目录，不覆盖原图；覆盖必须由用户明确选择并二次确认。
- 不绕过验证码、平台风控、权限校验、限流或反爬机制。
- 不实现刷单、刷评、批量未确认发消息、批量爬取或自动修改平台数据。
- 新增任何会改变第三方平台数据的自动化前，必须先补需求、合规边界、dry-run、人工确认、审计和失败恢复设计。

## 工程规则

- 标识符、包名和文件名使用英文；产品界面和项目文档默认使用简体中文。
- 遵守 `internal/domain -> internal/application -> internal/infrastructure/platform -> internal/ui` 的依赖方向。
- Gio 的 frame/layout 回调中不得做数据库、网络、文件或进程阻塞操作。
- UI 控件状态必须持久化在页面状态结构中，不得在每帧临时创建导致状态丢失。
- 数据库 schema 只能通过追加 migration 演进，不得修改已经发布的 migration。
- 文件和数据库写入需处理部分失败；备份、恢复和图片导出使用临时文件加原子替换。
- 新增依赖前先更新 `docs/03-tech-stack.md`，说明用途、许可证、替代方案和锁定版本。
- 默认优先标准库和现有项目组件，不为未来可能需求提前抽象。

## 文档同步规则

| 变化 | 必须同步 |
| --- | --- |
| 产品范围或验收变化 | `02-requirements.md`、`06-tasks.md` |
| 依赖、Go/Gio 版本或命令变化 | `03-tech-stack.md`、`00-ai-start-here.md`、`current-state.md`、`init.*` |
| 模块边界或数据模型变化 | `04-architecture.md`、`api.md`、相关 migration 和任务 |
| 页面或导航变化 | `routes.md`、相关需求和任务 |
| 代码现实或下一任务变化 | `current-state.md`、`06-tasks.md`、`progress.md` |

## 对话约定

- 用户输入 `grill me:` 或 `grill:` 时，执行反方评审：先查事实，指出需求、技术、商业和合规上的薄弱点，只讨论，不修改代码或文件，除非用户同时明确要求落地修改。

## 最低验证

代码初始化后，任务结束前至少运行：

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

涉及 Chrome、图片导出、备份恢复或 Gio 交互时，还必须执行任务中写明的手工 smoke，并在 `progress.md` 记录输入、观察结果和环境。