Shiny
340dd241c9
本次重构实现了标准化的本地配置系统，替换原有的硬编码环境变量读取逻辑： 1. 新增跨平台的原子化配置文件读写，支持Unix和Windows系统 2. 新增init命令用于安全初始化和更新本地凭据 3. 替换原有错误提示文案为更友好的中文提示 4. 更新文档说明新的配置流程和安全规范 5. 新增完整的配置相关测试用例 6. 添加必要的依赖包支持
42 lines
3.2 KiB
Markdown
42 lines
3.2 KiB
Markdown
# 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。
|