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。