@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 <canonical-tool> --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，由两部分拼成：
- 「日常记账」档 39 项——录入与过账凭证、录入/勾选认证/红字冲销发票、报销、出报表，以及各台账的只读查看（科目、期间、汇率、税务、薪酬、合同、诉讼）；
- 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，不含任何令牌）记录：
upos login --workspace <workspace-id> # 为另一个工作区追加一个登录（完成后自动切换为当前）
upos who # 列出本机全部工作区登录及各自权限范围
upos who --json # 机器可读形式
upos use <workspace-id> # 切换当前工作区（只改指针，不触碰凭据库）
脚本与 CI 可以继续用 SSOS_WORKSPACE_ID 钉死工作区：它的语义是“本次调用使用哪个 profile”，会覆盖 upos use 设置的指针。旧版单槽登录会在下一次调用时自动迁移为 per-workspace 形式，refresh token 原样保留，无需重新登录。
推荐在需要接入的项目目录执行一次：
npx -y @xaiverdeng/upos@latest setup --auto
如果希望先将 CLI 安装到全局环境，也可以执行：
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：
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 配置。
同一台电脑上的多工作区与多账号
一次登录绑定「一个账号 + 一个工作区」。本机可以同时保存任意多份，互不覆盖：
upos login # 追加一个工作区登录（已有会话不受影响）
upos login --workspace <workdir-id> # 指定工作区
upos who # 列出本机全部 profile，标「当前」
upos use <workspace-id> # 切换后续命令默认用哪个
upos use <workspace-id> --account [email protected] # 同一工作区有多个账号时必须点名
存储分两层：凭据在系统凭据库，目录在 ~/.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），两者都设时
语义是「这个账号在这个工作区」，歧义会直接报错而不是随机挑一个。
合同证据建议
已登录后，可按合同查看每个履约义务的银行流水、发票、凭证和资料候选：
upos contracts evidence suggest <contract-id>
upos contracts evidence suggest <contract-id> --json
该命令只显示候选、匹配理由和建议分配额，不会自动核销。需要写入时，使用同一套 canonical 分配工具生成 Action Plan，再显式确认该方案。
选定候选后，可一次准备多条相互独立的分配方案：
upos contracts evidence allocate --input '[{"obligationId":"...","evidenceType":"bank_transaction","evidenceId":"...","allocatedAmount":400,"reason":"金额、方向和相对方一致"}]'
默认只生成待确认的 Action Plan。仅当明确增加 --confirm 时，CLI 才会逐条确认；单条失败不会阻止其他条目处理，重复执行使用稳定幂等键：
upos contracts evidence allocate --input '[...]' --confirm --json
申报前自检与期间失效检查
两条只读命令，都不写账。filing check 在存在 FAIL 时退出码为 1，可以直接挂进申报前脚本。
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 回答另一件事：这一期有没有在期末之后被过账或修改的凭证，以及
这些期间已经报送过哪些表。登记过报送记录时，输出会点名到具体表单，例如：
期间失效检查 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），不会再触发一次浏览器授权；令牌缺失时直接报错并
说明怎么取得。
# 发票：扫描目录里的数电票 XML（PDF 只登记文件名并提示先取数）
# 先分页读全量工作区发票台账做去重，每张发票判定为 待写入 / 已存在 / 重复
upos invoices import ./发票 # 试运行：只打印将写入的清单与目标工作区
upos invoices import ./发票 --export 预确认单.xlsx # 试运行 + 另存预确认单（.md 或真 xlsx，无额外依赖）
upos invoices import ./发票 --apply # 逐张提交，打印返回的 Action Plan id
upos action-plan confirm <plan-id> # 真正写入
汇总行统一为 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 <tool> --input '<json>'` 调用会被拒绝并指向对应命令，`upos tools` 里这些工具带 `replacedBy`
字段。**`upos local-agent invoke` 同样会被拒绝**——它是用户能敲的命令，不是协议通道；机器调用走 MCP 桥，
不经过 CLI。命令分组、示例与退出码见 `upos --help` 与 `upos help <noun>`（帮助由
`src/command-registry.mjs` 生成，不在分发器里重复维护）。
**升级说明（1.2.0）**：破坏性变更——上面五个 canonical 工具不再能从 `upos <tool> --input` 或
`upos local-agent invoke` 直接调用，必须改用对应的一级命令。这是刻意的：同一能力有两个入口时，
两个入口的行为、幂等键和错误码迟早会分叉。
DeepSeek 是模型提供商，不是独立接入目标。Hermes 需要交互式工具选择，“Z Code”名称不明确，因此不提供无人值守接入。