shop_helm/AGENTS.md

AGENTS.md

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

项目定位

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

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

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

事实优先级

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

1. 用户在当前会话中的最新明确指令。
2. 本文件的仓库级执行与安全规则。
3. docs/02-requirements.md 的产品范围和验收标准。
4. docs/03-tech-stack.md、docs/04-architecture.md、docs/api.md 和 docs/routes.md 的技术事实。
5. docs/06-tasks.md 的任务拆分。
6. 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。
• 多 agent 并发时切换到 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: 时，执行反方评审：先查事实，指出需求、技术、商业和合规上的薄弱点，只讨论，不修改代码或文件，除非用户同时明确要求落地修改。

最低验证

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

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

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