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