# @xaiverdeng/upos 中文文档 规范地址：https://npmcn.com/package/%40xaiverdeng/upos/ 版本：2\.3\.0 npm 元数据更新时间：2026-11-02T22:25:58.226Z 中文译文更新时间：2026-11-02T22:32:57.914Z 软件包许可：未声明 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40xaiverdeng/upos 原文对照：https://npmcn.com/package/%40xaiverdeng/upos/?lang=original 项目主页：https://finlaw.cloud/ 源码仓库：https://github.com/Xaiver03/ssos ## 关键信息（来自 npm 元数据） - 包体积（解压后）：613 kB，18 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=20\.19\.0 - 运行依赖：1 个 - 首次发布：2026-08-25T07:56:43.089Z - 最新版本发布：2026-11-02T22:25:58.075Z - 已发布版本数：25（近 12 个月 25 个） ## 中文简介 官方UpOS CLI与一个命令的UpOS MCP设置 ## 安装 ```sh npm install @xaiverdeng/upos ``` 也可以使用：`pnpm add @xaiverdeng/upos`、`yarn add @xaiverdeng/upos`、`bun add @xaiverdeng/upos` ## README # @xaiverdeng/upos 创业OS公开 CLI。它只发现并调用服务端授权的工具，不包含数据库、部署、PM2、任意 shell 或管理员命令。 > **2.0.0：canonical 工具名归一化。** 底层工具全部收敛到 10 个动词（`list_` / `get_` / `search_` / `plan_` / `extract_` / `analyze_` / `trace_` / `review_` / `propose_` / `apply_`）。 一级命令（`upos invoices`、`upos bank`、`upos filing`、`upos payroll` …）**不受影响**； 只有直接写 `upos --input` 的脚本需要改。典型变化： `query_vat_invoices` → `list_vat_invoices`，`find_contract_candidates` → `search_contract_candidates`，`post_journal_entry` → `apply_journal_entry_post`， `draft_vat_invoice` → `plan_vat_invoice`，`propose_contract_upsert` → `propose_contract`。 2.0 CLI 收到旧名时会直接告诉你新名与对应的一级命令；完整对照表（当前每枚工具一行，随工具面 增减同步）见仓库的 `docs/audits/2026-10-30-tool-rename-map.json`。当前工具数以 `upos tools` 的输出为准，本文不写死。 `upos login` 默认请求 **46 项** permission-point，由两部分拼成： 1. 「日常记账」档 39 项——录入与过账凭证、录入/勾选认证/红字冲销发票、报销、出报表，以及各台账的只读查看（科目、期间、汇率、税务、薪酬、合同、诉讼）； 2. CLI 自身命令额外需要的 7 项——`payroll:manage`、`tax:manage`、`tax:file`、`contracts:create`、`contracts:review`、`employees:edit`、`employees:view`。少了这七项，`upos payroll recalc`、`upos filing correct`、`upos contracts import` 会被自己刚签发的令牌拒绝。 它**不**请求成员与角色的管理权限，**不**请求工资发放确认与跨境审批，也**不**请求删除发票或删除会计科目——发票只能走红字冲销（服务端对 `DELETE /api/invoices/:id` 无条件返回 409），会计科目删除没有对应的 CLI 命令，把这两项放进披露列表只会让人以为能删。唯一带删除语义的是作废**草稿**凭证：已复核或已过账的凭证服务端直接拒绝，必须按其受控更正流程处理。 被服务端保留给真人所有者操作、不可委派给机器凭据或自定义角色的三个权限码（工作区计费、删除工作区、转移所有权）不在请求之列——授权端点对整笔这类请求返回 `invalid_scope`，而不是静默少给几项，所以带上它们只会让每一次 `upos login` 在用户点同意之前就失败。最终授权仍严格取决于所选工作区中当前用户角色的有效权限；服务端会在**每一次请求**上重算角色与策略版本，角色一变，已签发的令牌下一次调用即失效。请求更宽的权限集合不会提升角色权限。需要主动缩小本机授权范围时，可用 `SSOS_PERMISSION_SCOPES` 显式指定 permission-point scope。 **升级说明（2.1.0）**：请求的权限集合被重写。旧的 48 项里混进了不属于本 CLI 职责的成员与角色管理权限，也漏掉了 `tax:manage`、`invoices:verify`、`invoices:analyze` 等命令真正要用的码；`invoices:delete` 更是一个永远返回 409 的假承诺。本次改为「日常记账档 + CLI 自身命令所需」的并集（46 项），并由测试钉住两件事：默认请求必须覆盖所有一级命令所需的权限，且不得包含任何无法执行的码。 **这次升级会让每个已登录的机器重新授权一次。** 两套集合互不包含（旧集合有 `members:remove` 等新集合不要的码，新集合有 `tax:view`、`fx:view` 等旧集合没有的码），所以本地判定为「权限合同需要补齐」：交互运行时自动打开一次授权页，非交互运行（脚本、CI）会直接报 `User CLI OAuth scope upgrade requires explicit 'upos login'`，显式跑一次 `upos login` 即可。之后不会再反复打开授权页。 CLI 会分别保存“本次请求过的权限合同”和“角色实际获准的权限”：旧授权范围较窄时，显式执行一次 `upos login` 会打开浏览器补齐授权；权限合同已经核对过时只刷新会话，不会反复打开授权页。只有希望主动重新核对工作区或权限时才使用 `upos login --force`。 一个账号可以同时在多个工作区保持登录：每次登录的凭据按「工作区 + 设备」各存一份，互不覆盖。要给指定工作区新建会话用 `upos login --workspace <工作区 UUID>`（显式指定优先于当前已登录的工作区）；`upos who` 列出本机已保存的会话，`upos use <工作区 UUID>` 切换后续命令默认使用哪一个。脚本与非交互场景里的 `SSOS_WORKSPACE_ID` 只用于挑选对应工作区的会话，不会改动这个默认值。首次运行新版本时，旧版单槽会话会原地迁移成按工作区存放，刷新令牌不变，也不需要重新登录。 ## 多工作区登录（per-workspace profile） 每次 OAuth 登录都绑定到「一个账号 + 一个工作区」；第二个工作区（或第二个账号）需要第二把授权，各自独立刷新、互不顶掉。登录凭据按 `{clientId}:{userId}:{workspaceId}` 存放在系统凭据库，当前使用哪个 profile 由凭据目录旁的普通配置文件（`upos-profiles.json`，不含任何令牌）记录： ```bash upos login --workspace # 为另一个工作区追加一个登录（完成后自动切换为当前） upos who # 列出本机全部工作区登录及各自权限范围 upos who --json # 机器可读形式 upos use # 切换当前工作区（只改指针，不触碰凭据库） ``` 脚本与 CI 可以继续用 `SSOS_WORKSPACE_ID` 钉死工作区：它的语义是“本次调用使用哪个 profile”，会覆盖 `upos use` 设置的指针。旧版单槽登录会在下一次调用时自动迁移为 per-workspace 形式，refresh token 原样保留，无需重新登录。 推荐在需要接入的项目目录执行一次： ```bash npx -y @xaiverdeng/upos@latest setup --auto ``` 如果希望先将 CLI 安装到全局环境，也可以执行： ```bash npm install -g @xaiverdeng/upos@latest cd /path/to/your-project upos setup --auto ``` 全局安装只提供 `upos` 命令；`upos setup --auto` 才会完成 Agent、MCP bridge 与 Skill 的一键接入。以上两种方式最终写入同一份配置，不需要同时执行。 该命令会发现 PATH 中的 Codex、Claude Code、OpenClaw，以及当前项目中的 Cursor、VS Code Copilot、OpenCode 配置标记；也会检查 Kimi Code 和 Zed 的本机配置。它会注册同一个公开 MCP bridge，并安装统一的 `ssos-tools` Agent Skill： ```text npx -y @xaiverdeng/upos-agent@latest mcp ``` Skill 写入当前项目的 `.agents/skills/ssos-tools/SKILL.md`；检测到 Claude Code 时也写入其 `.claude/skills/ssos-tools/SKILL.md` 兼容路径。已有同名 `ssos` MCP 配置或 Skill 不会被静默覆盖。首次工具调用时在浏览器完成 OAuth 2.0 + PKCE 登录；密码、API Key 和 access token 都不会写入 Agent 配置。 ## 同一台电脑上的多工作区与多账号 一次登录绑定「一个账号 + 一个工作区」。本机可以同时保存任意多份，互不覆盖： ```bash upos login # 追加一个工作区登录（已有会话不受影响） upos login --workspace # 指定工作区 upos who # 列出本机全部 profile，标「当前」 upos use # 切换后续命令默认用哪个 upos use --account a@b.com # 同一工作区有多个账号时必须点名 ``` 存储分两层：凭据在系统凭据库，目录在 `~/.local/share/ssos/upos-profiles.json`（只放工作区名、邮箱、 权限点、槽位，不含令牌）。 **槽位规则（1.1.0 起）**：凭据键是 `{clientId}:{userId}:{workspaceId}`，一个账号一个工作区一枚， 互不覆盖。旧版本用过两种键——只有工作区的 `{clientId}:{workspaceId}`（1.0.18 之前）和 `{clientId}:{workspaceId}:{userId}`（1.0.18）——**两种都会在第一次运行时自动改名到新键**， refresh token 原样搬过去，不需要重新登录： - 记录先写入新键，成功后才删除旧键，中途中断可以重跑； - 目录里用 `slotFormat: 2` 记住「已经迁移过」，之后每次调用不再多读凭据库； - 只要目录里还留着被取代的旧行（没有 userId 的那种），会被清掉。 **升级说明（1.1.0）**：这是**破坏性变更**——旧版本写的键不再被读取，但迁移在上面兜住了， 所以终端用户只需要正常用一次 `upos …`（或 `upos who`），不需要重新登录；只有在旧版把同一个 工作区授权给多个账号、且目录被删过的机器上，才需要重新 `upos login`。 脚本里可以用 `SSOS_WORKSPACE_ID` 钉工作区、`SSOS_ACCOUNT` 钉账号（邮箱或 userId），两者都设时 语义是「这个账号在这个工作区」，歧义会直接报错而不是随机挑一个。 ## 合同证据建议 已登录后，可按合同查看每个履约义务的银行流水、发票、凭证和资料候选： ```bash upos contracts evidence suggest upos contracts evidence suggest --json ``` 该命令只显示候选、匹配理由和建议分配额，不会自动核销。需要写入时，使用同一套 canonical 分配工具生成 Action Plan，再显式确认该方案。 选定候选后，可一次准备多条相互独立的分配方案： ```bash upos contracts evidence allocate --input '[{"obligationId":"...","evidenceType":"bank_transaction","evidenceId":"...","allocatedAmount":400,"reason":"金额、方向和相对方一致"}]' ``` 默认只生成待确认的 Action Plan。仅当明确增加 `--confirm` 时，CLI 才会逐条确认；单条失败不会阻止其他条目处理，重复执行使用稳定幂等键： ```bash upos contracts evidence allocate --input '[...]' --confirm --json ``` ## 申报前自检与期间失效检查 两条只读命令，都不写账。`filing check` 在存在 FAIL 时退出码为 1，可以直接挂进申报前脚本。 ```bash upos filing check --start-date 2026-07-01 --end-date 2026-09-30 upos filing restatement --start-date 2026-07-01 --end-date 2026-09-30 ``` `filing check` 按已过账凭证重算七条等式：资产负债平衡（含未结转损益）、利润构成、 亏损不应有应纳税额、本期借贷平衡、无收入却有营业成本、增值税销售额与营业收入同源、 留存收益等于累计损益。 `filing restatement` 回答另一件事：这一期有没有在期末之后被过账或修改的凭证，以及 这些期间**已经报送过哪些表**。登记过报送记录时，输出会点名到具体表单，例如： ```text 期间失效检查 2026-07-01 ~ 2026-09-30 已报送：financial_statements 2026-Q3（2026-10-27 00:15:08） 该期间已报送 1 份（financial_statements 2026-Q3），且有 3 张凭证在期末之后被过账或修改，需重新报送并说明差异 ``` 登记报送本身用 `apply_filing_submission_record` 工具（写操作，需确认），区分 `tax_return`（税务申报表）与 `financial_statement`（财务报表报送）两类。 ## 发票、流水与凭证缺口 整理发票和流水不再需要手拼 canonical JSON。这三条命令复用 `upos local-agent token` 换来的本机令牌 （`SSOS_LOCAL_AGENT_TOKEN` + `SSOS_WORKSPACE_ID`），**不会**再触发一次浏览器授权；令牌缺失时直接报错并 说明怎么取得。 ```bash # 发票：扫描目录里的数电票 XML（PDF 只登记文件名并提示先取数） # 先分页读全量工作区发票台账做去重，每张发票判定为 待写入 / 已存在 / 重复 upos invoices import ./发票 # 试运行：只打印将写入的清单与目标工作区 upos invoices import ./发票 --export 预确认单.xlsx # 试运行 + 另存预确认单（.md 或真 xlsx，无额外依赖） upos invoices import ./发票 --apply # 逐张提交，打印返回的 Action Plan id upos action-plan confirm # 真正写入 ``` 汇总行统一为 `N 张待写入、M 张已存在、K 张重复、J 张跳过（红票/PDF）、F 张失败`。 `--export` 写出的预确认单含工作区、批次时间、扫描目录、汇总计数，以及每行的状态列 （待写入 / 已存在 / 重复 / 跳过 / 失败）；Excel 版是手写 zip 容器 + inlineStr 的真 xlsx， 不是 CSV 改名。不指定 `--export` 时不会落任何文件。 # 流水：走上传腿拿到 fileUrl，再生成批量导入计划 upos bank import ./流水.csv --account # 试运行：不上传、不写入 upos bank import ./流水.xlsx --account --apply # 上传并打印预计导入/无效行/重复行 # 凭证缺口：只读清单，不创建或修改任何凭证 upos vouchers draft --limit 50 ``` **同一能力只有一个用户可见入口。** `apply_vat_invoice_create`、`extract_bank_transaction_import`、 `apply_bank_transaction_import`、`list_vat_invoices`、`list_invoice_linked_entries` 已由上面三条命令接管， 再通过 `upos --input ''` 调用会被拒绝并指向对应命令，`upos tools` 里这些工具带 `replacedBy` 字段。**`upos local-agent invoke` 同样会被拒绝**——它是用户能敲的命令，不是协议通道；机器调用走 MCP 桥， 不经过 CLI。命令分组、示例与退出码见 `upos --help` 与 `upos help `（帮助由 `src/command-registry.mjs` 生成，不在分发器里重复维护）。 **升级说明（1.2.0）**：破坏性变更——上面五个 canonical 工具不再能从 `upos --input` 或 `upos local-agent invoke` 直接调用，必须改用对应的一级命令。这是刻意的：同一能力有两个入口时， 两个入口的行为、幂等键和错误码迟早会分叉。 DeepSeek 是模型提供商，不是独立接入目标。Hermes 需要交互式工具选择，“Z Code”名称不明确，因此不提供无人值守接入。 ``` ## 常见问题 ### @xaiverdeng/upos 是什么？ 官方UpOS CLI与一个命令的UpOS MCP设置 ### 如何安装 @xaiverdeng/upos？ 在项目目录运行 npm install @xaiverdeng/upos，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 upos，可以用 npx upos 直接运行。 ### @xaiverdeng/upos 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/xaiverdeng\_\_upos 是否存在。 ### @xaiverdeng/upos 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @xaiverdeng/upos 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @xaiverdeng/upos 可以商用吗？ @xaiverdeng/upos 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @xaiverdeng/upos 还在维护吗？ 最新版本 2\.3\.0 发布于 2026/11/03（今天）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2026/08/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。