# shop-crm-agent

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

## 环境要求

- Git
- Go 1.26 或更高版本
- 可访问目标 LightCore API 的网络环境
- 运行环境提供 `LIGHTCORE_API_BASE_URL` 和 `LIGHTCORE_SHOP_CRM_AGENT_TOKEN`

仓库在开发工作区中固定与 `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 run ./scripts/build.go
./bin/shop-crm-agent --version
```

Windows 构建产物为 `bin/shop-crm-agent.exe`。构建脚本执行测试后，只编译当前操作系统和 CPU 架构，不安装系统服务，也不修改全局 PATH。

运行业务命令前，由当前 Shell 或 Agent 的受控运行环境提供配置：

```bash
export LIGHTCORE_API_BASE_URL=https://api.example.com
```

`LIGHTCORE_SHOP_CRM_AGENT_TOKEN` 必须通过密码管理器、受控 Secret 注入或其他不会回显和记录明文的机制提供。不要在交互式命令中直接输入真实 Token，也不得把它写入仓库、Skill、`.env`、命令历史、普通日志或聊天内容。

## 更新

收到内部更新通知后，让 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`。