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 读取本节后,应在同一会话完成安装、简短介绍、发起登录和登录核验,不停在“安装成功”。安装请求包含发起登录引导;最终授权由用户在网页确认,用户明确暂不登录时不发起。安装脚本本身只提供引导,不等待登录,也不申请业务权限。
- 检查 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。 - Codex 使用
diffcat setup codex接入助手并核对结果;当前会话立即读取skillPath指向的最新版指引,WorkBuddy 使用随包连接器指引。新建 AI 会话可刷新自动加载的指引,但不是本次登录的前置条件。CLI 安装和助手接入分别核对,失败时说明可行的修复步骤。 - 默认用通俗中文介绍:“我可以帮您了解业务流程、查询客户和订单、查看项目及待办,也能按要求创建单据草稿或办理审批。先连接您的账号,之后告诉我想做什么就可以。”不向用户讲解内部 skills、规则、能力编号或程序术语;用户明确要求技术细节时再展开。
- 立即按下文检查并连接账号。登录成功后继续用户原有需求;尚无具体任务时提供两三个例子,例如“介绍采购流程”“查最近的销售订单”“看我的待办”,不要自动执行例子或为演示申请权限。
当前会话中的连接与授权
所有命令使用同一 profile,默认 default,WorkBuddy 默认 workbuddy;用户指定时沿用其选择。除非用户明确选择另一部署,否则不传 --server。已有 profile 的登录默认沿用其服务地址,避免重新登录时误切环境。云端先按“桌面、容器与云端认证”验证短期内存会话,再在所有命令中保留同一 --session-dir。
- 执行
diffcat --pretty auth status。有效连接直接复用;auth_required表示尚未登录,返回下一步命令数组。确实未登录或连接已确认失效时,直接执行diffcat auth login,不先询问“是否登录”。网络、版本、系统凭据库故障及含糊结果不能当成未登录,应针对故障排查。 - 桌面
auth login自动检查环境、打开登录网页、等待确认并保存到系统凭据库;将链接及时展示给用户,维持同一长运行工具命令并继续等待,不重启以生成新链接。网页确认由用户本人完成。可用--no-browser只获取链接;browserOpened为 false 时必须提供可点击链接,不得假报已打开。完成后在另一次独立工具执行中运行同一 profile 的auth status,核验保存后的连接。登录本身不授予业务权限。 - 登录后 CLI 默认自动发起一次个人权限快速申请(7 天);已有权限或不需要时返回当前状态。需要更具体的权限时,先运行
diffcat permission status或diffcat permission catalog,再用中文说明用途并立即执行diffcat permission request --item <权限项:级别>。权限申请由管理员在「智能接入」中审批,CLI 不打开授权网页,也不要求用户二次确认。将当前任务确实需要的多项权限合并申请,不为验证安装申请权限。 - 管理员批准前,
permission status显示pending;批准后再次运行permission status核对实际权限。不能把“已申请”当成“已授权”。拒绝、取消或过期后停止本次申请,不自动重复提交。 - 登录与权限审批是两个独立步骤:登录由用户本人完成,权限由管理员审批;不要承诺合并成一次确认。
不得代替用户确认授权或索要密码、验证码、令牌、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_platformsdocument 支持以下单据资源,每种都可 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_orderscreate-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 个人面板为空不限制统计查询。
