sznr-cli
v0.1.7
Published
WorkBuddy CLI for Shunong Assistant
Readme
sznr-cli
数农助手 WorkBuddy CLI,npm 包名和命令名均为 sznr-cli,当前版本 0.1.7。
兼容 Node.js 20 及以上版本,无第三方运行时依赖。负责本地授权凭证、Gateway 授权命令和通用 GET/POST。
会话调用指引
CLI 是数字农人连接器的实际请求通道,提供 auth login/status/context/logout 和通用 get/post。不提供 whoami、set_current_enterprise 等 MCP 工具,也没有业务 search 或分类命令;MCP 工具索引没有条目不代表 CLI 未授权,不据此重连或停止取数。
先使用当前会话可用的业务技能确定任务与接口:经营分析、台账和月报走 df-enterprise-insight,采购执行走 df-enterprise-operations,资金流水及发票核对走 df-fund-invoice-guarded,操作和政策问答走 df-knowledge-qa。技能负责业务规则与参数,CLI 负责凭证、设备签名和请求执行;业务技能缺失或接口未收录时说明具体缺口,不猜测路径。
企业业务任务按以下流程执行,纯连接或知识查询只执行实际需要的步骤:
- 在 WorkBuddy 同一受管环境中执行
auth status,检查退出码和 JSON。只有退出码0且布尔loggedIn=true才确认已授权。 - 未授权或需要重新授权时执行一次
auth login。命令输出授权链接后即退出;用户完成网页登录和企业授权后,再执行auth status确认,继续原业务任务。 pending等待页面批准及平台默认状态检测,不重复创建授权或写轮询脚本;denied停止,用户再次要求连接时才重试。网络失败表示状态未知,不当作未登录。- 需要企业数据且本任务没有可复用上下文时,执行一次
auth context,使用顶层customerId和currentEnterprise;同一任务内复用,切换企业或重新授权后更新。企业详情查询失败不直接当作授权失效。 - 读取业务技能的单 API 文档,再使用
get/post调用规定的方法、相对路径和参数。POST 可用于只读查询,不能按方法推断写权限;遵守业务技能边界,不因为用户确认而执行技能禁止的操作。 - 先检查退出码和稳定错误码,再按接口文档判断业务成功、空结果及分页完整性。GET/POST 输出业务响应原文,没有统一的
ok/status/body外层。只有成功空结果才表示当前查询范围暂无记录。
企业参数只有业务文档要求时才使用 auth context 返回的 customerId,不从用户输入或缓存猜测;认证及企业身份 header 由 CLI/Gateway 管理。用户明确要求切换企业时,说明当前授权将结束,执行 auth logout 成功后再 auth login,由用户在网页选择企业。
正常交付展示业务结论、数据范围、截止时间和必要的脱敏明细。技术排查可提供不含凭证的命令、退出码和稳定错误码;不读取或展示凭证及设备私钥。只有会话中实际可用的命令和技能可以调用,提示词里的工具名称不构成其存在的证据;更高层明确强制 MCP 而禁止 CLI 时应报告配置冲突。
安装与开发
源码目录可直接运行:
node bin/sznr-cli.js --version
node bin/sznr-cli.js --help
npm test
npm run test:install
npm pack包发布到 npm registry 后,Connector 通过受管流程非交互式安装稳定版:
npm install --global --no-audit --no-fund sznr-cli@latestmacOS/Linux 使用 sznr-cli,Windows Connector 使用 sznr-cli.cmd。包无安装脚本;安装和核心命令不要求 Bash 或 PowerShell。Windows 使用系统文件权限完成读写,不依赖额外的 ACL 校验工具。
会话通过 Connector 的受管安装流程取得 CLI,不在业务任务中自行执行 npm 安装。刚安装后命令不可用时,先检查受管运行环境与 PATH 是否一致;仅使用安装流程确认的入口,不猜测其他用户的安装路径,不因此注销或重新授权。
只发布 CLI 的自动升级
从 CLI 0.1.7 与连接器 0.1.2 起,WorkBuddy 的 versionCheck.command 使用 sznr-cli update-check(Windows 使用 .cmd),旧 CLI 不支持该命令时回退 --version,以低于最低版本触发安装。minVersion 固定为 0.1.7,init 安装 sznr-cli@latest。
update-check 在 2.5 秒预算内读取固定公开地址 https://registry.npmjs.org/-/package/sznr-cli/dist-tags 的 latest。稳定版更高时只输出 0.0.0,让 WorkBuddy 按低于最低版本的分支重新执行安装;相同、较旧、预发布、无效元数据或检测失败时输出当前安装版本,退出码均为 0。不跟随重定向,不访问 Gateway、凭证或设备身份,不在 CLI 内启动安装子进程。--version 仍是离线的真实版本查询,升级标记不能当作实际版本或授权失败。
首次先发布 CLI 0.1.7 到 npm latest,再发布连接器 0.1.2。之后兼容版本执行 npm publish --tag latest 即可,连接器无需同步发布;beta 等标签不参与检测。触发点是 WorkBuddy 执行连接器版本检测,不是发布后即时后台推送。更新检测失败时保留当前版本;安装失败由 WorkBuddy 报告,CLI 不自行注销或改写授权记录。
latest 必须兼容当前连接器的命令、检测标记、授权与业务输出、凭证与设备格式及 Node 20 运行时。破坏这些契约的升级仍需制定迁移方案并同步更新连接器;不把不兼容版本直接推广到该标签。首次迁移、安装复检和三平台更新需真实 WorkBuddy 验收。
CLI 改名后继续使用既有 SHUNONG_* 环境变量和 .shunong-workbuddy 凭证目录,以兼容现有 Connector 配置及授权记录。
Connector 配置
| 环境变量 | settings.json 字段 | 包内默认值 | 含义 |
| --- | --- | --- | --- |
| SHUNONG_GATEWAY_URL | gatewayUrl | https://agent-gateway.gc365.com | 唯一 Gateway base URL,生产必须 HTTPS;可包含固定基础路径 |
| SHUNONG_AUTH_ORIGIN | authOrigin | https://shunong.gc365.com | Connector 允许的 Web 授权 origin,生产必须 HTTPS,只能包含协议、域名和可选端口 |
| SHUNONG_ALLOW_LOCAL_HTTP | 无 | 关闭 | 显式设为 1 才允许 Gateway 和授权 origin 使用 http://localhost[:port] |
SHUNONG_GATEWAY_URL 和 SHUNONG_AUTH_ORIGIN 按字段使用“环境变量 > 用户配置 > 包内默认值”的优先级。环境变量未定义时,CLI 从 Windows 的 %USERPROFILE%\.shunong-workbuddy\settings.json 或 macOS/Linux 的 ~/.shunong-workbuddy/settings.json 回退读取;对应字段仍未配置时使用上表中的默认值:
{
"gatewayUrl": "https://agent-gateway.gc365.com",
"authOrigin": "https://shunong.gc365.com"
}环境变量或用户配置显式设为空字符串属于配置错误,不会继续回退。默认生产地址作为代码常量随 npm 包发布;用户的 settings.json 不进入 npm 包,因此升级包不会覆盖用户配置。Connector 可以通过环境变量或预置 settings.json 切换测试、私有部署等非默认环境。
SHUNONG_AUTH_ORIGIN 和 SHUNONG_ALLOW_LOCAL_HTTP 是本实现为需求中未命名的两个配置定义的对接名称。SHUNONG_AUTH_ORIGIN 或 authOrigin 应与 Connector 的 authUrlDomain 对应同一来源。
本地 HTTP 例外只接受主机名 localhost,不接受 127.0.0.1、[::1] 或其他主机;未设置开关时仍强制 HTTPS。
默认 Gateway URL 为 https://agent-gateway.gc365.com,默认 Web 授权 origin 为 https://shunong.gc365.com。CLI 不接受命令行 Gateway 覆盖项。HTTP_PROXY、HTTPS_PROXY 不参与请求路由。
NODE_DEBUG 和 NODE_DEBUG_NATIVE 必须为空。Node 在入口执行前已缓存调试配置,HTTP 调试可能泄漏凭证,因此 CLI 检测到上述设置时在读取凭证、发送请求之前返回 2。
配置错误均在请求前失败。基础路径例如 https://gateway.example/api/ 配合 /orders 得到 https://gateway.example/api/orders,所有授权路径也遵循此基础路径。切换 Gateway base URL 时,旧凭证不能发送到新环境;先使用旧环境配置完成 auth logout,再切换并登录。
命令
sznr-cli --version
sznr-cli update-check
sznr-cli auth login
sznr-cli auth status
sznr-cli auth context
sznr-cli auth logout
sznr-cli get /business/path --query '{"page":1}'
sznr-cli post /business/path --body '{"name":"example"}' --header "X-Trace: example"
sznr-cli get /business/path --debug示例业务路径只表示语法,实际可用路径由 Gateway 白名单和 Skill 定义。JSON 引号按调用 Shell 的规则处理;Connector 使用平台对应命令入口。
授权和业务命令可添加 --debug;update-check 不接受额外参数。开启后,CLI 在 stderr 依次输出单行 JSON 请求和响应日志,正常命令结果仍写入 stdout。日志包含方法、URL、调用方 header、请求体、HTTP 状态、安全响应 header 和响应体;认证 key、签名、Cookie、token、password 及常见 key 字段会脱敏。请求尚未收到响应即失败时,只输出 request 日志和原有错误诊断。
授权
login:已有记录先查一次远端状态;未过期pending复用 URL,已授权返回状态 JSON,终态或损坏记录重新创建。无法确认状态时保留记录并报错。login:start 响应经字段和授权 origin 校验后,先安全落盘,再输出前后带换行的完整 URL。命令不打开浏览器、不轮询、不驻留;整个操作设置 9 秒预算,为 WorkBuddy 的 10 秒识别窗口预留余量。status:每次至多一次服务端只读请求,不创建授权、不换 token、不修改凭证文件或服务端 TTL。已登录响应中的有效customerId会输出并原子同步到本地配置,值相同时不重复写入。无本地记录时不请求 Gateway。context:先执行与status相同的实时授权检查;已登录时再查询当前账号的企业列表,按授权响应中的customerId精确匹配并返回完整企业记录。企业详情不写入本地配置,无本地记录或未登录时不查询企业列表。logout:仅远端明确成功或稳定错误码确认记录已失效时删除本地凭证。网络失败、普通 404 和未知结果均保留凭证供重试。没有本地凭证时幂等成功。
状态输出固定为单行 JSON,例如:
{"loggedIn":true,"state":"authorized","customerId":123}auth context 成功时输出完整授权企业上下文:
{"loggedIn":true,"state":"active","customerId":559,"currentEnterprise":{"id":559,"name":"示例采购企业","customerName":"示例采购企业","status":1,"useStatus":1,"roleKey":"buyer_admin","staffInfoStatus":1,"openProduct":["PURCHASE","FUND"],"version":"STANDARD","purchaseMode":["B2C"]}}currentEnterprise 是企业列表中 ID 与 customerId 唯一匹配的原始完整记录。数字 ID 与规范正整数字符串按十进制文本比较,大整数字符串不转换为 Number。已登录却缺少 customerId、企业列表无匹配或存在重复匹配均视为协议错误,不会退回列表第一项。该命令使用固定的 GET /workbuddy/customer/pc/customer/currentList,部署时必须将其加入 Gateway 的 WorkBuddy 精确白名单。
| 远端状态 | CLI state | loggedIn | 退出码 |
| --- | --- | --- | --- |
| PENDING | pending | false | 3 |
| APPROVED | authorized | true | 0 |
| 服务端确认有效的 EXCHANGED | active | true | 0 |
| DENIED | denied | false | 3 |
| EXPIRED / REVOKED | reauth_required | false | 3 |
| 无本地凭证 | unauthenticated | false | 3 |
同时接受 Gateway 的小写语义状态。EXCHANGED / active 要求 loggedIn=true,并校验服务端提供的 expiresAt 尚未到期;不能凭本地缓存推断 NCP 登录态有效。服务不可达时 stdout 为空,stderr 返回网络诊断,退出码 5。
GET/POST
- 只接受以单个
/开头的 Gateway 相对路径,拒绝绝对 URL、反斜杠、片段、用户信息、点段、多层编码的逃逸及编码路径分隔符。 --query必须是 JSON 对象,标量转为文本,数组/对象按 JSON 序列化后通过URLSearchParams编码。同名 query 替换路径中已有值。--body支持任意合法 JSON,只用于 POST;默认Content-Type: application/json。--header可以重复,同名允许字段用逗号合并。拒绝认证、Cookie、企业、Host、长度、逐跳字段和可能冲突的旧凭证字段。- 不跟随任何重定向,
3xx作为业务 HTTP 响应返回。 - JSON 和 UTF-8 文本响应正文按上游内容直接写入 stdout,不增加外层、不脱敏、不额外换行;空响应不写 stdout。最大响应 8 MiB;拒绝二进制、压缩响应、SSE、NDJSON 和非 UTF-8 文本;普通 chunked JSON 可正常使用。
- 连接超时 2.5 秒;HTTP 请求包含读响应体在内受命令总预算限制,不进行自动重试。
收到 HTTP 响应时,stdout 直接输出接口响应正文。例如接口返回:
{"rows":[],"total":0}CLI 不输出响应 status/header,也不脱敏 get/post 的响应正文;Gateway 必须保证响应内容可以安全交给调用方。HTTP 非 2xx 时仍输出响应正文,并返回退出码 4。
普通业务 403 不触碰凭证。稳定的 WB_AUTH_EXPIRED、WB_AUTH_REVOKED、WB_INVALID_KEY、WB_TOKEN_RECOVERY_FAILED、WB_REAUTH_REQUIRED 才标记本地缓存并提示重新登录;不自动换 token、不重试。若服务端以 HTTP 2xx 携带这些错误码,CLI 仍原样输出响应正文并返回 3。
本地文件与安全
Windows 使用 %USERPROFILE%\.shunong-workbuddy\,macOS/Linux 使用 ~/.shunong-workbuddy/:
settings.json 用户提供的 Gateway URL 和授权 origin,环境变量可逐项覆盖
config.json Gateway base URL、授权 requestId 及 customerId 缓存,不作为请求地址来源
credentials.json requestId、workbuddyKey、authUrl、requestExpiresAt、state
device.json Ed25519 私钥、公钥和派生 deviceId,不随 logout 删除已登录的 status 响应提供有效 customerId 时,配置内容如下:
{"gatewayBaseUrl":"https://gateway.example/","requestId":"public-request-id","customerId":123}auth status 在已登录响应提供有效 customerId 时将其加入单行 JSON 输出;字段缺失或为 null 时不输出。auth context 则要求已登录响应必须包含有效 customerId,并返回企业列表中的唯一匹配记录。customerId 支持正安全整数或正整数字符串,字符串保持原值以避免大整数精度丢失。后续命令通过 CredentialStore.load(config, deadline) 返回的 customerId 读取;只有 Gateway 和授权 requestId 均匹配才返回缓存值,否则为 undefined。GET/POST 不自动发送 CustomerId header,调用方仍不能通过 --header 覆盖它。
auth login 复用凭证时的 status 查询也会同步企业缓存。同一授权保存凭证时保留缓存,换 key、远端确认未登录、稳定重新授权错误和成功注销时清理。已登录响应缺失 customerId 或值为 null 时清理旧缓存,兼容没有该字段的响应;非空但格式无效时返回 6,不覆盖旧配置。网络失败保留原配置,配置落盘失败返回 6,不输出成功状态。
凭证保存字段白名单化,不保存 NCP token、Cookie、loginUuid 或浏览器状态。macOS/Linux 目录 0700、文件 0600。Windows 遵循系统现有文件权限,不因额外 ACL 主体阻断 CLI;凭证字段仍只保存白名单内容。
原子写入先创建同目录随机临时文件,收紧权限,再写入完整 JSON、同步数据并 rename;POSIX 额外同步父目录。写入失败不输出授权 URL。硬中断可能留下受保护的完整临时文件,但正式文件不会成为半个 JSON;临时文件名不含 key。
CLI 拒绝符号链接目录、符号链接凭证及硬链接凭证。默认诊断只包含固定阶段文案,不打印原始请求、start 响应、凭证内容或异常堆栈;显式 --debug 仅打印经过上述脱敏和 header 白名单处理的结构化日志。
设备绑定
所有授权和业务请求均携带 Ed25519 签名,覆盖方法、完整路径与 query、原始请求体、key 摘要、毫秒时间戳和随机 nonce。设备身份由公钥 SHA-256 派生,复制 key 到另一设备不能使用;复制私钥或完整克隆用户目录不在首期防护范围内。
auth login 上报主机名、系统及版本、架构、CLI/Node 版本和完整 MAC 列表。MAC 用于展示和审计,不作为可信身份;服务器不能从远程 HTTP 连接自动取得 MAC。来源 IP 由 Gateway 观察,不接受 CLI 自报。保留至多 32 个非回环、非全零、非广播的规范化 MAC,单项采集失败允许为空。
device.json 损坏不会自动替换身份。首次创建由 .device-lock 串行化;如果进程在首建过程中异常退出且未发布身份,需先确认没有 CLI 进程使用该目录,再由运维处理残留锁。不要复制或手动替换私钥文件来迁移授权。撤销设备会立即阻止后续请求,再次使用需发起新申请并在浏览器重新批准。
退出码
| 码 | 含义 | | --- | --- | | 0 | 命令成功 / 已登录 | | 2 | 参数或配置错误 | | 3 | 未登录、等待授权或需重新授权 | | 4 | 业务 HTTP 非 2xx / 授权操作被拒绝 | | 5 | 网络不可达、超时或授权服务暂时不可用 | | 6 | 协议错误、不支持的响应、本地持久化或 CLI 内部错误 |
诊断固定输出到 stderr:{"error":{"code":"...","message":"..."}}。错误文案不回显调用者或服务端输入。
验证与联调
npm test 覆盖本地模拟 Gateway、实际 Node 子进程、真实平台文件权限、授权状态、落盘失败、进程中断、请求安全、重定向和敏感信息泄漏。测试目录均使用临时隔离目录,不读取当前用户真实凭证。
npm run test:install 在临时目录打包,再以包含空格的隔离全局前缀离线安装并运行真实 sznr-cli / sznr-cli.cmd,不改用户全局安装。CI 矩阵包含 Windows/macOS/Linux 和 Node 20/22。
跨系统接口约定及待验证项见 实现与联调说明。
