feat: 实现完整的本地配置管理与CLI重构

本次重构实现了标准化的本地配置系统,替换原有的硬编码环境变量读取逻辑:
1. 新增跨平台的原子化配置文件读写,支持Unix和Windows系统
2. 新增init命令用于安全初始化和更新本地凭据
3. 替换原有错误提示文案为更友好的中文提示
4. 更新文档说明新的配置流程和安全规范
5. 新增完整的配置相关测试用例
6. 添加必要的依赖包支持
This commit is contained in:
2026-08-01 02:39:49 +08:00
parent 3466e19d13
commit 340dd241c9
14 changed files with 793 additions and 20 deletions
+19 -7
View File
@@ -6,8 +6,8 @@
- Git
- Go 1.26 或更高版本
- 可访问目标 LightCore API 的网络环境
- 运行环境提供 `LIGHTCORE_API_BASE_URL``LIGHTCORE_SHOP_CRM_AGENT_TOKEN`
- 可访问生产 LightCore API `https://api.zhecent.com` 的网络环境
- 当前员工可登录 Shop 管理后台创建 CRM Agent 凭据
仓库在开发工作区中固定与 `LightCore` 同级。例如:
@@ -24,19 +24,31 @@
```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
```
Windows 构建产物为 `bin/shop-crm-agent.exe`。构建脚本执行测试后,只编译当前操作系统和 CPU 架构,不安装系统服务,也不修改全局 PATH。
缺少 Go 或版本低于 `go.mod` 要求时,先安装官方 Go 工具链,再重新执行构建。Windows 构建产物为 `bin/shop-crm-agent.exe`。构建脚本执行测试后,只编译当前操作系统和 CPU 架构,不安装系统服务,也不修改全局 PATH。
运行业务命令前,由当前 Shell 或 Agent 的受控运行环境提供配置:
## 运行配置
```bash
export LIGHTCORE_API_BASE_URL=https://api.example.com
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 隐藏写入>
```
`LIGHTCORE_SHOP_CRM_AGENT_TOKEN` 必须通过密码管理器、受控 Secret 注入或其他不会回显和记录明文的机制提供。不要在交互式命令中直接输入真实 Token,也不得把它写入仓库、Skill、`.env`、命令历史、普通日志或聊天内容。
`.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 历史、普通日志或聊天内容。
## 更新