shop-crm-agent/AGENTS.md

# AGENTS.md

本仓库是 `shop-crm-agent` 的唯一源码仓库。默认使用中文沟通。

## 项目边界

- 客户端只通过 `/api/shop/crm-agent/v1` Protobuf HTTP API 工作，不直接访问数据库、Redis、LightCore 配置或后端运行容器。
- Go module 固定为 `code.zhecent.com/open/shop-crm-agent`，不得引入 LightCore backend module、Gin、GORM、数据库驱动或 Redis 客户端。
- `internal/api/shop_crm_agent.pb.go` 是生成代码，不得手工编辑。
- Protobuf schema 的唯一真相位于同级 `../LightCore/backend/application/shop/interfaces/crm_agent_proto/proto/shop_crm_agent.proto`。
- 协议变更必须从 `../LightCore/backend` 执行 `bash scripts/proto_gen_shop_crm_agent.sh`，同时检查两个仓库的生成结果和测试。

## CLI 契约

- 所有业务命令输出 Protobuf JSON，不输出表格或混合说明文本。
- 业务失败先输出服务端结构化响应再返回非零退出码；运输或解析失败不得伪造业务响应。
- 写命令必须使用稳定且唯一的 `--request-id`；同一操作重试时复用原 request ID 和原参数。
- 报价编辑固定使用 `begin -> command -> preview -> commit`，放弃时使用 `discard`。
- 项目和报价删除必须先执行对应 `delete-preview`，不得绕过 revision 与 `changeSetId`。
- API 默认连接 `https://api.zhecent.com`；`LIGHTCORE_API_BASE_URL` 只用于显式覆盖，不回退 localhost。
- CLI 只以仓库内 `bin/shop-crm-agent[.exe]` 运行；不得用 `go install` 安装该 CLI，不得将其二进制复制或软链接到仓库外，也不得为该 CLI 修改 `PATH`、Shell 启动文件或系统级配置。
- 本地配置只通过 `shop-crm-agent init` 隐藏读取 Token，并在仓库根写入 Git 已忽略的 `.env`；该命令可重复执行且每次原子覆盖原文件，除 `init` 外不得修改该文件。
- 二进制从 `bin/` 定位仓库根 `.env`，`go run` 只允许从仓库根使用。`.env` 只包含 `LIGHTCORE_SHOP_CRM_AGENT_TOKEN`；`init` 在 Unix 系统写入 `0600`，加载时拒绝组或其他用户权限。
- 进程环境中的 `LIGHTCORE_SHOP_CRM_AGENT_TOKEN` 优先于 `.env`；覆盖 API 地址时必须同时显式提供环境 Token，禁止把 `.env` 的生产凭据发送到其他地址。
- CLI 不创建、更新或撤销服务端凭据。Agent 不得读取、显示、记录或提交 `.env` 内容；Token 不得进入源码、命令参数、日志或输出，测试只能使用明显虚构的占位值。

## 开发流程

1. 先读取相邻实现和 `SKILL.md`，确认命令边界与安全流程。
2. 只修改职责明确的 command/client 代码，不在客户端复制服务端业务规则。
3. 生成代码只通过 LightCore 的协议生成脚本更新。
4. 执行 `go test ./...` 和 `go build ./...`。
5. 执行 `go run ./scripts/build.go`，确认 `bin/shop-crm-agent[.exe] --version` 可运行。
6. 用 `rg` 检查 Token、Secret、内部绝对路径和意外的后端依赖。

## Git 与更新

- `main` 必须始终可测试、可构建；禁止 force push。
- 更新只使用 `git pull --ff-only`。
- 工作区有本地修改时不得自动覆盖、重置或清理。
- 本仓库不提交编译产物，不提供二进制自更新或预编译 Release。