yzkx-cli

易指快销（SQEasySaler）REST API v1 的命令行工具，面向 Agent 与运维。项目代号 yzkx，二进制名 yzkx。

三层命令体系：

| 层 | 形式 | 说明 | |---|---|---| | 原始接口层 | yzkx api POST /api/v1/<controller>/<action> | REST 逃生门，带 v1 只读写操作闸门 | | 业务域 action 层 | yzkx <domain> <action> | registry 驱动的只读查询（108 个审计注册接口） | | shortcut 层 | yzkx <domain> +shortcut | 高频查询的声明式快捷命令（13 个，全只读） |

v1 为纯只读：开单类写操作（59 个 OUT_OF_SCOPE）一律不注册、不提供 dry-run 预览；yzkx api 逃生门命中写动词默认拒绝（policy 错误，退出码 6），需 --allow-write 显式放行。

AI Skills 安装

仓库内置 7 个命令速查式 AI Skills（skills/，随二进制内嵌，yzkx skills list 可查看）与 7 个 Hermes 原生四段式 Skills（skills/hermes/）。支持 10 个 Agent 工具：claude-code / codex / cursor / github-copilot / hermes-agent / kiro-cli / opencode / qoder / trae-cn / workbuddy。

方式一：交互式安装脚本（推荐，可选安装目标）

运行后列出可选 Agent 工具，由你勾选装到哪些（hermes-agent / workbuddy 走直拷，其余走 npx skills）：

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File scripts\install-skills.ps1

# Linux / macOS
bash scripts/install-skills.sh

方式二：交互式 npm 安装器（免克隆仓库）

npx -y yzkx-skills

方式三：命令行指定目标

npx skills add skiyoumi/yzkx-cli -y -g --agent "claude-code" --agent "codex" --agent "opencode"

注意：skills 工具要求每个 --agent 单独传参（逗号/空格分隔会报 Invalid agents）；不带 --agent 会尝试装到全部工具，其中部分工具不支持全局安装会报错（可忽略，或显式指定目标避免）。

安装与构建

方式一：npx（零安装，推荐）

npx -y yzkx-cli version        # 验证可用
npx -y yzkx-cli config init    # 初始化配置
npx -y yzkx-cli auth login     # 登录
npx -y yzkx-cli product +search 牙线 --dry-run

要求：Node.js ≥ 16（npm 自带）。npx 每次拉取最新版，无全局安装负担，也不要求本机有 Go 环境。

方式二：npm 全局安装

npm i -g yzkx-cli
yzkx version
yzkx config init

已知限制：npm 11 全局安装可能跳过 optionalDependencies 的平台包（报"未找到平台二进制"），此时改用 npx 或项目级安装即可。

方式三：项目级安装

npm i yzkx-cli    # 在项目目录内
npx yzkx version

方式四：源码构建

要求 Go 1.23+。本项目零第三方依赖（内置 cobra 风格命令框架），可完全离线构建。

make build          # 产出 ./bin/yzkx
./bin/yzkx version  # 输出版本号
go build ./... && go vet ./... && go test ./...

快速开始

# 1) 初始化配置（非交互式；也可以交互式直接运行 `yzkx config init`）
yzkx config init --base-url https://yzkxmobileapi.ezhisoft.com --company-id 1

# 2) 登录：POST /api/v1/logins/login 换取 Bearer token，存入当前 profile（0600）
yzkx auth login --phone <手机号> --password <密码> --company-id 1

# 3) 先用 --dry-run 预览请求体（不发送任何真实请求，也不需要配置）
yzkx product +search 牙线 --dry-run
yzkx report +daily-summary --dry-run

# 4) 正式查询
yzkx product +search 牙线
yzkx product +detail --id 123
yzkx report +daily-summary --startDate 2026-08-01 --endDate 2026-08-12
yzkx api POST /api/v1/basePtypes/getall --data '{"fillterName":"牙线"}'

三层命令

1. 原始接口层（逃生门）

yzkx api POST /api/v1/<controller>/<action> [--data '{...}'] [--dry-run] [--allow-write]

• 请求体自动附加 loginTelNumber / loginTelSnNumber / clientVersion，带 Authorization: Bearer <token>。
• 不做参数 schema 校验（逃生门），仅校验路径形状 /api/v1/{controller}/{action}。
• 写操作闸门：action 名命中内置写动词词表（add/update/delete/remove/save/submit/check/edit/audit 等，大小写不敏感）默认拒绝，--allow-write 显式放行并打日志告警；--dry-run 只预览、不受闸门限制。
• 词表见 internal/registry/registry.go 的 WriteVerbs，README 用途与风险见下文「写操作闸门」。

2. 业务域 action 层

yzkx <domain> <action> [--params '{...}'] [--red-flag] [--draft]

• 六域：product 商品 / stock 库存 / customer 客户 / bill 单据 / report 报表 / visit 拜访，全部从 docs/registry-v1.json（构建期内嵌）加载。
• <action> 可为裸 action 名（域内唯一）或 controller/action；运行 yzkx <domain> --help 查看该域全部注册接口。
• --params 为 JSON 请求体，与注入参数合并；关键参数按 registry schema 做类型校验（类型错误 → validation 退出码 2），未登记 key 透传。
• 注册表外（含 OUT_OF_SCOPE 写操作）的 action 一律拒绝（validation 错误）。
• --json（默认）输出原始字段名；其他格式（pretty/table/ndjson/csv）输出中文标签。

3. shortcut 层

yzkx <domain> +<shortcut> [flags]

声明式结构体（shortcuts/common）+ 统一 runner，自动注入 --dry-run / --format。v1 全部 Risk=read。

| 域 | shortcut | |---|---| | product | +search 商品搜索（支持位置参数，如 yzkx product +search 牙线）、+detail 商品详情、+price 商品价格 | | stock | +query 库存列表、+expiry 批次效期 | | customer | +search 客户搜索、+detail 客户详情 | | bill | +detail 销售单详情、+reconcilia 对账明细、+payment 欠款单列表 | | report | +daily-summary 营业日报（默认今天）、+sales-ranking 销售排行 | | visit | +plan 拜访计划、+workflow 拜访工作流 |

配置与凭据

• 配置：~/.yzkx/config.json，单文件多 profile（prod/pre/test 或自定义），每个 profile 独立保存 BASE_URL、companyID、设备号、clientVersion、token。
• 权限：config.json 0600、目录 0700、原子写（先写临时文件再 rename）；损坏文件自动备份为 config.json.corrupt 后可恢复。
• 凭据按 profile 隔离：登录 prod 不影响 test；yzkx auth status / yzkx auth logout 只操作当前 profile。
• 绝不读写 ~/.easycrm/ 的任何文件。
• 环境变量覆盖：YZXK_PROFILE（覆盖当前 profile）、YZXK_BASE_URL（覆盖 BASE_URL）、YZXK_TOKEN（覆盖 token）、YZXK_CONFIG（覆盖配置文件路径）。

yzkx profile list                      # 列出所有 profile
yzkx profile add test --base-url https://testeasywaymobile.ezhisoft.com
yzkx profile use test --yes            # 切换（交互式有确认提示；--yes 跳过）
yzkx config show                       # 查看当前配置摘要（token 脱敏）
yzkx doctor                            # 本地配置健康检查（不发网络请求）
yzkx whoami                            # 当前 profile / 身份（手机号脱敏）

输出与错误契约

成功 → stdout JSON 信封，退出码 0；失败 → stderr JSON 错误信封，退出码非 0。判断成功只看 ok==true 或退出码，绝不用上游 code/status 字段。

{"ok":true,"identity":"user","dry_run":false,"data":{...},"meta":{"count":1}}
{"ok":false,"error":{"type":"validation","subtype":"invalid_argument","message":"...","hint":"...","param":"--flag"}}

| 退出码 | 类别 | 典型场景 | |---|---|---| | 0 | 成功 | ok==true | | 1 | api | 上游 HTTP/业务错误（status=false） | | 2 | validation | 参数/路径/未知命令/未知 flag | | 3 | auth / config | 401 未登录 / 配置缺失损坏 | | 4 | network | 网络不可达/超时 | | 5 | internal | 内部错误（不应发生） | | 6 | policy | 违反 v1 只读闸门（写操作被拒） |

• --format json|pretty|table|ndjson|csv；--jq 最小子集（仅支持对象键与数组下标路径，如 .data.content[0].name，不支持过滤器/函数）。
• stdout 是数据、stderr 是其余一切；_notice 承载 update/skills 提示。
• 未知子命令/flag 输出结构化 invalid_argument 错误 + "did you mean" 建议（退出码 2），不打印 help 后退出 0。
• 完整契约见 docs/usage.md。

业务语义对齐（App 裁决）

• G7 红冲：单据查询默认隐藏红冲单；--red-flag 显式开启（bill 域）。
• G8 草稿：单据查询默认隐藏草稿；--draft 显式开启（bill 域）。
• G9 拜访日期：不复刻 App 的"减一天"入口默认；visit +workflow 使用用户显式给定的 --dayforDate。
• 电话/手机号：默认脱敏（面向人输出），--show-sensitive 显式开启。
• 枚举/中文标签取自 docs/field-labels.md（Task1 审计，SQEasySaler 源码为唯一权威）；UNVERIFIED 项原样透传不映射。
• 差异裁决表见 docs/app-diff.md（G1-G9）。

字段级脱敏（B3）

按 registry 中 Task1 提取的原系统字段权限规则逐字段控制显示（73 个敏感接口、37 个敏感字段）：默认不输出未授权字段，--show-sensitive 显式开启全量。成本/售价/金额/库存权限以原系统配置为唯一权威，不自行定义分级。详见 docs/security.md。

写操作闸门

yzkx api 逃生门默认拒绝写类 Action（退出码 6，policy 错误）。--allow-write 显式放行并在 stderr 打日志告警：

warning: write action invoked via api escape hatch with --allow-write

用途：仅限运维/诊断；v1 业务层不注册任何写操作。词表维护在 internal/registry/registry.go（WriteVerbs，常量列表，大小写不敏感子串匹配）。--dry-run 不受闸门限制（不实际发送，仅预览）。

已知限制

• v1 纯只读：开单类写操作不注册、不提供 dry-run 预览（Q6，v2 再评估）。
• 单公司：profile 内绑定 companyID；多公司需求后续加 company list/use（架构 B1）。
• --jq 为最小子集：仅对象键 + 数组下标，无过滤器/函数。
• yzkx update 为 v1 占位，不执行网络更新；skills 打包与分发已由 Task3 交付（skills/ + packages/yzkx-skills + 安装脚本）。
• 自动化测试使用 mock HTTP server + 假凭据，不连接真实环境；真实凭据只能人工显式登录。

发布形态

• GitHub 仓库：skiyoumi/yzkx-cli（公开）；tag v* 触发 GitHub Actions → GoReleaser 产出 6 平台产物（yzkx-<ver>-<os>-<arch>.{tar.gz,zip} + checksums.txt）到 Releases。
• npm 分发：yzkx-cli 主包 + 6 个平台分包（yzkx-cli-{linux,darwin,windows}-{x64,arm64}），npx -y yzkx-cli 零安装使用；make build / make install 为源码构建路径（可选）。
  • make npm-packages VERSION=0.1.0 生成 6 个平台分包到 dist/npm/；make npm-publish VERSION=0.1.0 发布（真实发布由维护者在 npm 账号下执行）。
• Skills 分发：随仓库 skills/ 目录发布（另发布 yzkx-skills npm 包），通过 npx skills add skiyoumi/yzkx-cli、npx -y yzkx-skills 或本地安装脚本安装。
• make install 会把可执行文件安装到 ~/.local/bin/yzkx，请确保 PATH 包含 ~/.local/bin。

文档

• docs/architecture.md — 架构设计决策记录（Q1-Q12、B1-B5、G1-G9 裁决）
• docs/usage.md — 命令/信封/退出码/格式完整契约
• docs/security.md — 凭据与脱敏安全模型
• docs/api-audit.md — Task1 接口审计报告
• docs/registry-v1.json — 108 个注册查询接口 + 59 个 OUT_OF_SCOPE 写操作（唯一权威）
• docs/field-labels.md — 字段中文标签与脱敏规则（唯一权威）
• docs/app-diff.md — CLI 与 App 差异裁决表