shop-crm-agent/README.md

# shop-crm-agent

`shop-crm-agent` 是通过正式 Protobuf HTTP API 操作 Shop CRM 项目和独立报价的受控命令行客户端。源码允许匿名读取，但使用业务 API 仍需要管理员签发的 CRM Agent 凭据。

## 环境要求

- Git
- Go 1.26 或更高版本
- 可访问生产 LightCore API `https://api.zhecent.com` 的网络环境
- 当前员工可登录 Shop 管理后台创建 CRM Agent 凭据

仓库在开发工作区中固定与 `LightCore` 同级。例如：

```text
<workspace>/
├── LightCore/
└── shop-crm-agent/
```

普通构建不依赖 `LightCore` 仓库；只有修改 Protobuf 契约时才需要同级的 LightCore 源码。

## 首次安装

```bash
git clone https://code.zhecent.com/open/shop-crm-agent.git
cd shop-crm-agent
go version
go run ./scripts/build.go
./bin/shop-crm-agent --version
./bin/shop-crm-agent init
```

缺少 Go 或版本低于 `go.mod` 要求时，先安装官方 Go 工具链，再重新执行构建。Windows 构建产物为 `bin/shop-crm-agent.exe`。构建脚本执行测试后，只编译当前操作系统和 CPU 架构，不安装系统服务，也不修改全局 PATH。

## 运行配置

CLI 默认连接生产 API `https://api.zhecent.com`，无需设置 `LIGHTCORE_API_BASE_URL`，也不会回退 localhost。

首次执行 `init` 时，终端会隐藏输入内容并提示粘贴 CRM Agent Token。Token 由员工登录 Shop 管理后台后，在 `/shop/crm/settings/agent-credentials` 创建；凭据绑定当前管理员及所选 `crm.read`、`crm.write`、`crm.delete` scope，明文只在创建成功时显示一次。

初始化成功后，CLI 在仓库根创建 Git 已忽略的 `.env`：

```dotenv
LIGHTCORE_SHOP_CRM_AGENT_TOKEN=<由 init 隐藏写入>
```

`.env` 只保存这一项；`init` 在 Unix 系统写入 `0600` 权限，CLI 会拒绝允许组或其他用户访问的文件。二进制从自身所在的 `bin/` 定位仓库根，因此从其他目录调用同一二进制时仍读取该文件；使用 `go run` 时必须位于仓库根。Agent 不得读取、回显、记录或提交 `.env` 内容。

凭据撤销或更换后重新执行 `./bin/shop-crm-agent init`。该命令可重复执行，每次都会通过同目录临时文件原子覆盖仓库根 `.env`；`init` 只管理本地配置文件，不创建、更新或撤销服务端凭据。

CI 或测试环境可以通过 `LIGHTCORE_SHOP_CRM_AGENT_TOKEN` 临时覆盖 `.env`。`LIGHTCORE_API_BASE_URL` 仅用于覆盖生产地址；覆盖时必须同时显式提供同一环境的 `LIGHTCORE_SHOP_CRM_AGENT_TOKEN`，避免把 `.env` 中的生产凭据发送到其他地址。真实 Token 不得进入命令参数、Shell 历史、普通日志或聊天内容。

## 更新

收到内部更新通知后，让 Agent 在仓库根目录执行：

```bash
git status --short
git pull --ff-only
```

确认拉取成功后，Agent 必须重新读取最新的 `SKILL.md`，再执行：

```bash
go run ./scripts/build.go
./bin/shop-crm-agent --version
```

如果工作区存在本地修改，必须先停止更新并确认修改来源，不得强制重置。只有重新构建和版本探针都通过后才可继续执行 CRM 操作。

## 开发验证

```bash
go test ./...
go build ./...
go run ./scripts/build.go
```

`internal/api/shop_crm_agent.pb.go` 是生成代码，不得手工编辑。协议源文件位于同级 LightCore 仓库，生成入口为：

```bash
(cd ../LightCore/backend && bash scripts/proto_gen_shop_crm_agent.sh)
```

## 许可

本仓库保留全部权利，仅授权 Zhecent 员工用于公司内部业务。详见 `LICENSE`。