Files

T

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

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

2026-08-01 02:39:49 +08:00

3.5 KiB

Raw Blame History

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 同级。例如：

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

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

首次安装

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：

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 在仓库根目录执行：

git status --short
git pull --ff-only

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

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

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

开发验证

go test ./...
go build ./...
go run ./scripts/build.go

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

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

许可

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

3.5 KiB Raw Blame History Unescape Escape