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

diffcat-cli

v0.5.1

Published

Security-first CLI for AI agents to invoke registered Diffcat capabilities

Readme

diffcat-cli

供 AI 智能体和本地自动化使用的 Diffcat CLI。除受控业务操作外,CLI 从云端Git快照渐进读取中文系统知识与授权源码,可介绍功能、模块、办理方法并辅助疑难诊断。CLI 只能调用服务端登记的能力,不能传入任意 URL 或 SQL。

业务知识正文统一在仓库根目录 knowledges/ 维护,经云端服务发布;CLI 不再保留旧 knowledge/ 目录、本地检索器或内置流程节点说明。包内 README、Codex/WorkBuddy Skill 及其参考文档继续提供安装、登录、授权、查询和异常处理指南,diffcat guide 仍可离线读取。

给 AI 的安装引导

用户只需发送:

请帮我安装 Diffcat CLI:https://www.npmjs.com/package/diffcat-cli,并阅读其引导说明。

本 README 同时展示在 npm 包页面并随包发布。AI 读取本节后,应在同一会话完成安装、简短介绍、发起登录和登录核验,不停在“安装成功”。安装请求包含发起登录引导;最终授权由用户在网页确认,用户明确暂不登录时不发起。安装脚本本身只提供引导,不等待登录,也不申请业务权限。

  1. 检查 Node.js 22 或更高版本。执行 npm install -g diffcat-cli@latest,再执行 diffcat --version 和 diffcat --pretty guide。guide 无需登录、不访问服务端,返回 README 正文(guide)、路径(guidePath)和操作指引路径(skillPath)。命令不可用时可用 npm root -g 定位包,读取 diffcat-cli/README.md。
  2. Codex 使用 diffcat setup codex 接入助手并核对结果;当前会话立即读取 skillPath 指向的最新版指引,WorkBuddy 使用随包连接器指引。新建 AI 会话可刷新自动加载的指引,但不是本次登录的前置条件。CLI 安装和助手接入分别核对,失败时说明可行的修复步骤。
  3. 默认用通俗中文介绍:“我可以帮您了解业务流程、查询客户和订单、查看项目及待办,也能按要求创建单据草稿或办理审批。先连接您的账号,之后告诉我想做什么就可以。”不向用户讲解内部 skills、规则、能力编号或程序术语;用户明确要求技术细节时再展开。
  4. 立即按下文检查并连接账号。登录成功后继续用户原有需求;尚无具体任务时提供两三个例子,例如“介绍采购流程”“查最近的销售订单”“看我的待办”,不要自动执行例子或为演示申请权限。

当前会话中的连接与授权

所有命令使用同一 profile,默认 default,WorkBuddy 默认 workbuddy;用户指定时沿用其选择。除非用户明确选择另一部署,否则不传 --server。已有 profile 的登录默认沿用其服务地址,避免重新登录时误切环境。云端先按“桌面、容器与云端认证”验证短期内存会话,再在所有命令中保留同一 --session-dir。

  1. 执行 diffcat --pretty auth status。有效连接直接复用;auth_required 表示尚未登录,返回下一步命令数组。确实未登录或连接已确认失效时,直接执行 diffcat auth login,不先询问“是否登录”。网络、版本、系统凭据库故障及含糊结果不能当成未登录,应针对故障排查。
  2. 桌面 auth login 自动检查环境、打开登录网页、等待确认并保存到系统凭据库;将链接及时展示给用户,维持同一长运行工具命令并继续等待,不重启以生成新链接。网页确认由用户本人完成。可用 --no-browser 只获取链接;browserOpened 为 false 时必须提供可点击链接,不得假报已打开。完成后在另一次独立工具执行中运行同一 profile 的 auth status,核验保存后的连接。登录本身不授予业务权限。
  3. 登录后 CLI 默认自动发起一次个人权限快速申请(7 天);已有权限或不需要时返回当前状态。需要更具体的权限时,先运行 diffcat permission status 或 diffcat permission catalog,再用中文说明用途并立即执行 diffcat permission request --item <权限项:级别>。权限申请由管理员在「智能接入」中审批,CLI 不打开授权网页,也不要求用户二次确认。将当前任务确实需要的多项权限合并申请,不为验证安装申请权限。
  4. 管理员批准前,permission status 显示 pending;批准后再次运行 permission status 核对实际权限。不能把“已申请”当成“已授权”。拒绝、取消或过期后停止本次申请,不自动重复提交。
  5. 登录与权限审批是两个独立步骤:登录由用户本人完成,权限由管理员审批;不要承诺合并成一次确认。

不得代替用户确认授权或索要密码、验证码、令牌、Cookie、设备私钥;不得导出访问令牌、刷新令牌或设备私钥。所有业务操作只能通过 Diffcat CLI,禁止绕过 CLI 直接访问内部 API、数据库、SQL、GraphQL 或网页自动化。安装引导与简短工具介绍可离线进行,真实业务知识、查询与办理仍须先检查连接并取得所需权限。

安装

npm install -g diffcat-cli@latest
diffcat --pretty guide

要求 Node.js 22 或更高版本。桌面长期登录需要系统持久凭据库(Windows Credential Manager、macOS Keychain 或 Linux Secret Service);Linux 固定使用 Secret Service,禁止退回执行隔离下不可持续读取的内核 keyring。容器与云端 Agent 可使用下述短期内存会话,不保存明文令牌文件。

npm 包同时包含 Agent 通用操作指南、DiffCat Codex Plugin 和 WorkBuddy CLI Connector。安装脚本会在检测到 Codex 时自动登记插件;如果安装时未检测到 Codex、npm 使用了 --ignore-scripts,或需要修复安装,可执行:

diffcat setup codex

安装或升级后当前 Agent 先读取随包最新指引并继续登录;后续新建会话可刷新自动加载的指引。CLI、各 Agent 适配清单和 Skill 使用同一个 npm 版本发布,不需要从其他仓库重复安装。

当前包按公开 npm 包配置,以便 WorkBuddy 托管运行时无需私有 Registry 凭据即可一键安装。正式发布由流水线执行 pnpm build && pnpm test && pnpm publish,不要把 Registry Token 打进安装包。npm tarball 必须同时包含 plugins/diffcat、.agents/plugins/marketplace.json、connectors/workbuddy 和安装脚本。

从源码构建时,pnpm build 会先清理本包 dist/,再执行 TypeScript 编译,防止已删除模块及旧测试的产物残留。验证安装包时应先构建、测试,再运行 npm pack --dry-run 检查文件清单。

Agent 集成

  • 通用 Agent:只要能够执行本机命令并读取 SKILL.md,即可使用 diffcat 的 JSON 命令、权限目录和指南,不依赖 Codex API。
  • Codex:npm postinstall 自动登记随包 Plugin;也可运行 diffcat setup codex 修复。
  • WorkBuddy:connectors/workbuddy 是符合官方 CLI + Skill 规范的连接器提交目录。连接器市场审核发布后,用户点击一次即可由 WorkBuddy 托管 Node 22 并安装本 npm 包。正式环境默认连接生产 API;只有用户明确选择测试或私有部署时,Skill 才通过 --server 覆盖地址并使用独立 profile。

WorkBuddy 连接器的版本必须与 npm 包版本同步。提交 WorkBuddy 审核前,应先发布对应 npm 版本,再将 connectors/workbuddy 目录打包提交。

必须使用 npm 最新正式版

CLI 在每次登录、设备码交换、刷新令牌、权限目录和业务请求中,通过 X-Diffcat-CLI-Version 上报自身 npm 包版本。服务端直接从 https://registry.npmjs.org/diffcat-cli/latest 获取公共 npm 的 latest 版本,只接受与之完全相同的正式版本;缺失、旧版、预发布版或其他版本都会收到 HTTP 426、cli_upgrade_required 和升级提示。已有登录连接也不能绕过检查,不需要配置环境变量或人工维护版本号。

遇到升级要求时,先停止业务调用,执行 npm install -g diffcat-cli@latest,检查 diffcat --version,读取 diffcat --pretty guide,在当前会话读取随包最新指引并重新检查 auth status,后续新建会话可刷新自动加载内容。不要把升级要求当成未登录,不要反复刷新、重新登录、申请权限或删除凭据;升级复用系统凭据库中的原有连接。禁止手动伪造版本请求头绕过门槛。

--version、帮助、guide 和插件修复均为本地命令,不受版本门槛限制;主动断开通过专用撤销接口执行,即使访问令牌过期也不需要先刷新。浏览器授权确认和管理页面不受 CLI 包版本约束,原有鉴权继续生效。

版本查询限时5秒,成功结果缓存60秒,并发请求共用查询;新正式版发布到 npm latest 后,下一次缓存刷新自动生效,不需要改配置或重启后端。缓存过期且 npm 无法访问或响应无效时,业务请求返回 HTTP 503、cli_release_unavailable,不使用过期版本放行。此时应稍后重试,不要重新登录、申请权限或删除凭据。安装刚发布的新版后仍不匹配时,等待短时缓存刷新再检查;持续不匹配应报告 npm 版本与本机版本,不能循环重装或降级。发布负责人应确保 latest 始终指向可安装的正式版,测试或预发布包使用其他 tag。

登录与权限申请

正式环境地址如下:

| 用途 | 地址 | | ----------------------------- | ---------------------------------- | | CLI / 服务端 API | https://diffcat-api.howcat.cn | | 后台 PC 端与 CLI 浏览器授权页 | https://diffcat.howcat.cn | | 移动端 | https://diffcat-mobile.howcat.cn |

CLI 默认使用正式 API,连接其他部署时可显式传入 --server <url>。

先执行 diffcat --pretty auth status 检查并复用已有连接;安装引导或业务请求中确认未登录时,直接打开登录页建立设备连接。登录本身不会获得任何业务权限:

diffcat auth login

登录默认自动申请一组个人权限(7 天有效),管理员批准后即可查询和创建自己的数据。不需要自动申请时使用:

diffcat auth login --no-auto-request

权限不足时查看服务端目录并申请具体权限项。数据权限使用 item:level,级别为 personal_read、personal_write、all_read_personal_write、all_write;特殊权限只写权限项编码:

diffcat permission catalog
diffcat permission quick-request
diffcat permission request \
  --item sales.order:personal_write \
  --item flow.task:personal_read
diffcat permission status

只有管理员在「智能接入」页面批准后权限才生效。临时授权到期自动失效,永久授权写入用户权限基线。不要为验证安装申请写入或全量权限,也不要假称用户已在网页确认。

常用命令

桌面、容器与云端认证

| 环境 | 支持方式 | 授权前验证 | | ---------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ | | Windows/macOS 桌面 | 原长期设备登录与系统凭据库 | auth doctor 检查目录写入、重命名、后端和独立子进程回读 | | Linux 桌面,有可解锁的 Secret Service | 长期设备登录,固定 Secret Service 后端 | 同上;后端不可用时在网页批准前停止 | | 无 Secret Service 的 Linux、容器、云端 Agent | 最长一小时、显式只读能力的内存会话 | 持久工具会话维持前台代理;另两次独立工具执行运行 session probe | | 无可验证私有目录、无法维持代理或无法跨执行通信 | 暂无可用认证方式 | 不发起授权;需运行时提供持久工具会话与安全 IPC,或接入另行设计的凭据服务 |

桌面登录会自动执行 auth doctor。诊断 JSON 使用 kind: diagnostic,业务/会话结果使用 kind: result;诊断失败有阶段与脱敏错误码。普通子进程的成功不能证明工具执行隔离已通过。常规登录在保存成功后通过另一次独立 auth status 验证即可。遇到工具执行隔离或反复丢失登录的实际故障时,再在两次真正独立的工具执行中分别运行下面的诊断探针,不能把它们合并到一次工具调用:

diffcat auth doctor --start-cross-execution
diffcat auth doctor --verify-cross-execution <第一条返回的probeId>

探针不含凭据。跨执行验证依赖调用者确认执行边界,CLI 不会把同进程或普通子进程自动标记为工具隔离验证。

云端方案不监听 Unix socket,不依赖脱离后台进程。Agent 通过工具提供的长运行会话保持以下前台命令存活;命令首次返回一行 broker-ready JSON,其中包含公开的 directory。使用新的目录,不能用后台 & 或启动器退出的方式代替进程维持:

diffcat session serve --directory /tmp/diffcat-session-<本轮唯一ID> --ttl 3600

目录由 CLI 创建为 0700,必须属于当前 POSIX 用户、不能是符号链接。现阶段 Windows 使用桌面模式,云端目录 ACL 方案未实现。--server 必须在 session serve 时指定;会话绑定该服务,后续命令通过同一目录访问,不混用桌面 profile。

在两个独立工具执行中重复探测。必须观察到相同 sessionId 和连续计数;这同时验证当前目录可访问、代理存活和加密消息可往返,不能以共享目录或 socket 创建尝试代替:

diffcat --session-dir <directory> session probe
diffcat --session-dir <directory> session probe
diffcat --session-dir <directory> auth login

云端登录立即返回 pending、授权页地址与用户码,令牌交换由代理继续进行。请用户在网页批准;即使调用登录的工具执行中断,仍可继续使用该代理。重试 auth login 返回同一事务,不重复生成授权页。批准后运行 session status,再运行真实验证连接的 auth status:

diffcat --session-dir <directory> session status
diffcat --session-dir <directory> auth status
diffcat --session-dir <directory> permission status

权限申请由管理员审批,云端不会打开权限确认网页;登录仍由用户本人在网页确认。管理员批准后再次运行 permission status,随后用独立命令查询实际业务数据,不能只以登录成功验收:

diffcat --session-dir <directory> resource list md.customers --query '{"pageSize":20}'
diffcat --session-dir <directory> resource get md.customers <id>
diffcat --session-dir <directory> auth logout

令牌与 ES256 DPoP 私钥仅存在于代理进程内存。目录保存公开会话元数据和短暂的加密请求/业务结果:每条请求使用临时 X25519 密钥交换、HKDF、AES-256-GCM,认证数据绑定会话、请求和消息方向;客户端私钥也不写盘。代理只允许固定 Agent 接口,刷新、令牌与私钥不能导出。目录权限及同一受信任 OS 用户构成访问边界,这不能隔离同 UID 的恶意进程或宿主管理员。此实现没有接入外部安全凭据服务。

本地会话期限最多 3600 秒,服务端临时连接也强制最多一小时,临时权限期限不能超过连接期限。代理正常退出、到期或 session close 会尝试撤销,并报告 cleanup.confirmed;失败必须由用户在网页断开,不能声称回滚成功。强杀、容器回收或宿主重启无法保证执行清理,服务端的一小时上限提供最终失效边界。进程内存丢失后不能从目录恢复登录,须启动新代理并重新授权;旧目录不可覆盖。远程撤销、到期或 DPoP 错配会拒绝后续请求。

session serve 是长运行命令,stdout 为逐行 JSON:启动诊断和最终关闭结果各一行。其他命令为单个 JSON 文档;不要把 pending 或代理内存快照当作远端连接已验证。云端模式不使用 ~/.config/diffcat,但也不能代替排查桌面配置目录的 ENOENT。

diffcat --pretty auth status
diffcat --pretty permission status
diffcat --pretty permission catalog
diffcat --pretty knowledge outline
diffcat --pretty knowledge search "项目模块怎么用"
diffcat --pretty knowledge get module.project
diffcat --pretty knowledge flow SALES_ORDER
diffcat permission quick-request
diffcat permission request --item sales.order:personal_write
diffcat resource list md.customers --query '{"pageSize":20}'
diffcat resource get md.materials 123 --include bomLines
diffcat document list inv.purchase_requests --query '{"status":"DRAFT"}'
diffcat document create-draft inv.purchase_requests --input @draft.json
diffcat project list --query '{"pageSize":20}'
diffcat sales-order get 123
diffcat sales-order create-draft --input @draft.json
diffcat stats query --input @metrics.json
diffcat task list --query '{"status":"PENDING"}'
diffcat task approve 456 --comment "同意"
diffcat operation resume <operation-id>

云端知识、源码与实时流程

知识采用“系统入口 → 领域 → 完整主题/章节 → 同提交源码”的结构。知识命令要求登录并取得对应的知识特殊权限;源码另需代码阅读特殊权限。已有授权不会自动扩张,按当前需求直接申请最小权限,由管理员审批。

首次查询返回 snapshotId,后续命令显式携带 --snapshot <ID>,避免分析过程中混用新旧提交。长文先用 knowledge get <ID> --outline,再用 --section sN;章节附简介、scope和必要依赖ID。knowledge related只返回一层关联;knowledge source返回实现依据,取得代码阅读授权后用 code read查看原文。

diffcat knowledge outline
diffcat knowledge search "采购" --snapshot <ID>
diffcat knowledge get procurement.purchase-request --outline --snapshot <ID>
diffcat knowledge get procurement.purchase-request --section s3 --snapshot <ID>
diffcat knowledge source procurement.purchase-request --snapshot <ID>
diffcat code symbol completePurchase --snapshot <ID>
diffcat code read nestjs/src/path/file.ts --start-line 42 --line-count 80 --snapshot <ID>

截断结果附nextOffset、nextPage或next行内位置,续读时沿用同一快照。快照仅保留当前和上一成功版本;被清理时明确报错,应从当前版本重新开始。无命中、尚未就绪、无法连接及无权限分别识别;不会回退到历史内置正文。旧主题ID由服务器固定映射到新版ID,返回迁移说明。源码提交不代表生产已部署。

knowledge flow <流程编码或实体名>仍查询实际最新PUBLISHED流程,独立要求 knowledge.flows.read 和相应业务菜单。返回发布版本的脱敏业务视图,不再混入旧包的节点说明。实际办理人、单据和启用流程通过授权实时查询核实。

知识与诊断命令不会修改单据。对于“订单填错”等问题,Agent 会先取得单号,再查询真实单据、当前身份、待办和下游影响,给出草稿修改、撤回后修改、驳回/撤销后重建或受控反冲等建议;本版本没有新增编辑、撤回、取消或重建能力。

标准输出始终是 JSON,登录提示和进度写入标准错误。写操作自动携带幂等键;也可以通过 --idempotency-key 指定。高风险审批第一次调用只创建五分钟有效的确认意图,用户在网页二次认证后再运行 operation resume。

凭据与协议

  • 登录采用 OAuth 2.0 Device Authorization Grant 风格的设备授权流程;CLI 不能读取浏览器登录态。
  • 同一台设备按服务地址在系统凭据库保存稳定的 ES256 密钥,重新登录复用设备身份;设备授权、令牌签发和能力调用都携带 DPoP proof。
  • 十分钟访问令牌、轮换刷新令牌和设备私钥只进入系统凭据库;普通配置文件不含任何令牌或私钥。
  • 刷新令牌连续 30 天未使用失效,且最长 90 天必须重新授权;检测到旧刷新令牌复用时整条授权立即撤销。
  • auth logout 同时请求服务端撤销授权并清除本机访问和刷新凭据,独立存储的设备身份密钥保留用于下次登录;用户也可在网页“已连接 Agent”中远程撤销。
  • 同一 profile 的刷新和凭据更新通过跨进程锁串行化,支持多个 AI 进程并发调用而不误触发刷新令牌复用告警。

面向 AI 的稳定输出

所有业务结果只写到 stdout,普通命令为单个 JSON 文档;桌面登录提示、浏览器授权地址和轮询进度写到 stderr。云端登录的待批准信息包含在结构化结果中,长运行 session serve 使用逐行 JSON。命令非零退出码表示请求未成功,AI 不应从自然语言日志推断成功。

写操作应让 CLI 自动生成幂等键,或由调用者提供稳定的 --idempotency-key。网络中断后不要盲目重试高风险操作,应先运行:

diffcat operation status <operation-id>
diffcat operation resume <operation-id>

资源名称

resource 支持以下基础资料资源:

sys.users                           sys.departments
sys.roles                           sys.dict_types
sys.dict_entries                    md.companies
md.currencies                       fin.exchange_rates
md.uoms                             md.encoding_rules
md.fee_subjects                     md.customers
md.customer_contacts                md.customer_invoice_profiles
md.stores                           md.contracts
md.products                         md.price_lists
md.price_list_lines                 md.warehouses
md.warehouse_members                md.suppliers
md.supplier_contacts                md.materials
md.bom_lines                        adm.supplies
fin.bank_accounts                   sales.crowdfunding_platforms

document 支持以下单据资源,每种都可 list、get 和 create-draft:

sales.orders                        sales.direct_orders
sales.consignment_reconciliations   sales.crowdfunding_orders
inv.purchase_requests               inv.inbound_orders
inv.outbound_orders                 inv.stocktake_orders
fin.expense_requests                fin.invoice_requests
fin.refund_requests                 adm.supply_entry_orders
adm.supply_issue_requests           adm.supply_purchase_requests
adm.supply_stocktake_orders

create-draft 会复用对应业务模块的 Create DTO 校验并在创建后回查状态;只有状态确认为 DRAFT 才报告成功。它不会提交单据、发起流程、记账或变更库存。

当前约束

  • 不接受任意 HTTP URL、GraphQL、SQL 或脚本,只能调用服务端登记的 Agent 能力。
  • resource 与 document 的资源名会映射为固定能力 ID,最终仍由服务端 Agent 权限项、数据范围和管理员审批结果共同校验。
  • 首期不支持无交互 CI/容器凭据;需要机器身份时应另行建设 workload identity,而不是导出个人刷新令牌。
  • 高风险确认当前使用 Diffcat 本地账号密码进行二次校验;仅使用飞书或 NAS 登录且没有本地密码的用户暂时不能确认此类操作。
  • Device Flow 适合不能稳定接收浏览器回调的 CLI;在浏览器与 CLI 同机且能监听 loopback 回调的场景,后续版本应优先增加 Authorization Code + PKCE,Device Flow 保留为受限的 headless fallback。

统计查询使用当前用户的有效卡片授权,不传 roleId,也不提供角色切换。stats list 返回可用卡片,stats query --input 使用 { "metrics": [...] };PC 个人面板为空不限制统计查询。