diffcat-cli

供 AI 智能体和本地自动化使用的 Diffcat CLI。除受控业务操作外，CLI 内置了随版本发布的中文业务知识库，可介绍功能、模块、办理方法并辅助疑难诊断。CLI 只能调用服务端登记的能力，不能传入任意 URL 或 SQL。

安装

npm install -g diffcat-cli

要求 Node.js 22 或更高版本，并需要可用的系统凭据库（Windows Credential Manager、macOS Keychain 或 Linux Secret Service）。首期不支持把长期授权以明文文件形式放入容器或 CI。

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

diffcat setup codex

安装或升级后应新建 Agent 会话，以加载当前 npm 包内的 DiffCat Skill。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 和安装脚本。

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 目录打包提交。

登录与能力授权

正式环境地址如下：

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

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

先登录并建立长期设备连接。登录本身不会获得任何业务能力：

diffcat auth login

登录后按需申请一个或多个能力，CLI 会输出独立的网页能力确认地址：

diffcat capability request \
  --capability pm.projects.read \
  --capability sales.orders.read

需要完整只读工作空间时，可以一次申请服务端维护的全部只读能力。该预设不会包含写入能力：

diffcat capability request --all-read

只有用户在网页中确认的能力才会被授予；用户当前业务权限或管理员策略不允许的能力会从授权中剔除。

常用命令

diffcat --pretty auth status
diffcat --pretty capability list
diffcat --pretty capability catalog
diffcat --pretty knowledge outline
diffcat --pretty knowledge search "项目模块怎么用"
diffcat --pretty knowledge get module.project
diffcat --pretty knowledge flow SALES_ORDER
diffcat capability request --preset master-data-read
diffcat capability request --all-read
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 @widgets.json
diffcat task list --query '{"status":"PENDING"}'
diffcat task approve 456 --comment "同意"
diffcat operation resume <operation-id>

内置知识与实时流程

知识库采用“入口大纲 → 本地检索 → 按主题加载 → 关联主题”的结构。knowledge search 只返回摘要和匹配章节，Agent 应在确认命中后再用 knowledge get 加载正文，避免一次读取整套知识。正文为中文，英文模块名、命令名和常用术语可作为检索别名。

knowledge outline、knowledge search 和 knowledge get 每次都会验证当前 profile 的真实登录状态，但不要求额外业务能力。授权过期或远程撤销后会立即失败。auth status 同时返回当前用户的只读身份摘要，便于在诊断时判断创建人、部门、角色和办理关系。

knowledge flow <流程编码或实体名> 查询数据库中当前启用定义的最新 PUBLISHED 版本，需要用户显式授予 knowledge.flows.read，并要求当前用户拥有该单据的业务菜单。返回内容只包含流程名称、版本、节点职责与策略、办理人显示名称和带标签连线；不会返回版本快照、内部动作、原始条件、内部配置或办理人 ID。无该能力或菜单时仍可读取静态基线，但不能声称已经确认当前版本、实际办理人或最新分支。

知识与诊断命令不会修改单据。对于“订单填错”等问题，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。命令非零退出码表示请求未成功，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 或脚本，只能调用服务端能力目录中的已登记能力。
• resource 与 document 的资源名会映射为固定能力 ID，最终仍由服务端目录、用户实时权限、组织策略和授权范围共同校验。
• 首期不支持无交互 CI/容器凭据；需要机器身份时应另行建设 workload identity，而不是导出个人刷新令牌。
• 高风险确认当前使用 Diffcat 本地账号密码进行二次校验；仅使用飞书或 NAS 登录且没有本地密码的用户暂时不能确认此类操作。
• Device Flow 适合不能稳定接收浏览器回调的 CLI；在浏览器与 CLI 同机且能监听 loopback 回调的场景，后续版本应优先增加 Authorization Code + PKCE，Device Flow 保留为受限的 headless fallback。