npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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 负责凭证、设备签名和请求执行;业务技能缺失或接口未收录时说明具体缺口,不猜测路径。

企业业务任务按以下流程执行,纯连接或知识查询只执行实际需要的步骤:

  1. 在 WorkBuddy 同一受管环境中执行 auth status,检查退出码和 JSON。只有退出码 0 且布尔 loggedIn=true 才确认已授权。
  2. 未授权或需要重新授权时执行一次 auth login。命令输出授权链接后即退出;用户完成网页登录和企业授权后,再执行 auth status 确认,继续原业务任务。
  3. pending 等待页面批准及平台默认状态检测,不重复创建授权或写轮询脚本;denied 停止,用户再次要求连接时才重试。网络失败表示状态未知,不当作未登录。
  4. 需要企业数据且本任务没有可复用上下文时,执行一次 auth context,使用顶层 customerId 和 currentEnterprise;同一任务内复用,切换企业或重新授权后更新。企业详情查询失败不直接当作授权失效。
  5. 读取业务技能的单 API 文档,再使用 get/post 调用规定的方法、相对路径和参数。POST 可用于只读查询,不能按方法推断写权限;遵守业务技能边界,不因为用户确认而执行技能禁止的操作。
  6. 先检查退出码和稳定错误码,再按接口文档判断业务成功、空结果及分页完整性。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@latest

macOS/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。

跨系统接口约定及待验证项见 实现与联调说明。