@moziaverse/enterprise-cli

企业数据与操作命令行客户端。一个 npm 包提供两个职责单一的命令：

• context-cli 通过 Context API 读取已授权数据。
• action-cli 通过 Action API 执行已授权的消息投递或结构化操作。

两个命令都不直接持有底层数据源凭据。

安装

需要 Node.js 20 或更高版本。

从 npm 全局安装：

npm install --global @moziaverse/enterprise-cli

从旧包或同名的第三方 context-cli 迁移时，先清理会占用命令名的旧安装；npm 不会 跨包名自动升级，也不会可靠地为 npm alias 生成本包的两个命令：

npm uninstall --global @moziaverse/context-cli context-cli
npm install --global @moziaverse/enterprise-cli
context-cli --version
action-cli --version

配置

由管理员创建 Service Token，或由系统签发 Personal Token，然后配置：

export CONTEXT_API_URL="https://context.example.com"
export CONTEXT_API_TOKEN="..."

context-cli 与 action-cli 只读取这一套配置，不使用独立的 ACTION_* 环境变量。

也可以从标准输入传入令牌，避免令牌出现在命令参数和 Shell 历史中：

printenv CONTEXT_API_TOKEN | context-cli whoami --token-stdin

CLI 不提供 --token <value> 参数。

命令

context-cli whoami
context-cli doctor
context-cli list context://projects/example/
context-cli search "项目风险" --source projects
context-cli list context://records/resources --limit 20
context-cli list context://records/resources --limit 20 --cursor <nextCursor>
context-cli query context://records/resources --filter "labels:contains:todo" --limit 100
context-cli query context://records/resources --filter "recordId:eq:record-42"
context-cli query context://records/resources --all
context-cli read context://records/resources/record-id
context-cli read context://records/resources/record-id --format text
context-cli download context://records/resources/record-id/file --output ./record.pdf
context-cli list context://packages/skills/
context-cli download context://packages/skills/daily-review --output ./daily-review.zip

action-cli list
action-cli list records.draft.save --resource context://records/people/42
action-cli describe records.draft.save template-id --resource context://records/people/42
action-cli send message.send chat:target-id ./report.md --risk write
action-cli run records.draft.save template-id ./draft.json \
  --resource context://records/people/42 --risk write
action-cli plan records.delete template-id ./delete.json \
  --resource context://records/people/42 --risk destructive
action-cli confirm plan-id
action-cli status request-id

send/run 会在本机保存不含正文和令牌的待确认提交指纹。网络超时或进程中断后，重新执行 完全相同的命令会复用幂等键，避免消息或业务写入重复执行。自动化需要跨机器重试时，显式 传入稳定的 --idempotency-key <key>；可用 CONTEXT_ACTION_STATE_DIR 调整本地状态目录。

默认输出 JSON，可用 --format text 输出适合阅读的文本。除 download 外，两个命令的结果 都可以用 --output <path> 以 UTF-8 原子写入文件；download --output 则指定二进制附件路径。 list 和 search 统一返回 items、complete、warnings 和 nextCursor；complete 为 false 时不应默认数据已齐全，有 nextCursor 时应继续分页。query 支持时间范围、过滤、 排序、字段选择、分组聚合和游标分页。action-cli describe 返回目标所需字段、必填项、 只读项和 JSON 示例。send 只接受 Markdown，run 只接受 JSON 对象；二者默认等待 成功或失败，确需异步时使用 --detach，再通过 status 查询。省略文件或使用 - 时 均从标准输入读取。

依赖具体数据资源的 Action 必须使用 --resource 显式指定一个已经由 Context Grant 授权的 规范 URI。list 用它读取该资源当前可用的 Target；Action Grant 仍只保存稳定 Target， 不会保存人员、账号或隐藏执行身份。服务端在提交与实际执行前都会重新校验 URI 和当前授权。 不带 --resource 的 action-cli list 只列出可用 Action，不读取资源型 Action 的 Target。 具体资源 URI 应先通过 context-cli 和服务器返回的 discoveryUri 发现，CLI 不构造或解释 任一插件的 URI 层级。

Action 输入上限为 5 MiB：send 读取 Markdown，run 读取 JSON，plan 按 Action 声明的 输入类型读取 Markdown 或 JSON。JSON 的任意嵌套位置都可以使用中性的本地文件引用；相对 路径以 JSON 文件所在目录为准：

{
  "attachment": {
    "filePath": "./invoice.pdf"
  }
}

CLI 会在提交前读取文件，并替换为 fileName、mediaType 和 contentBase64。展开后的完整 JSON 仍不得超过 5 MiB；配置 CONTEXT_WORKSPACE 时，文件必须位于该工作区。可显式覆盖 fileName 或 mediaType，但 CLI 不猜测附件属于哪个业务字段，字段位置仍以 describe 返回的 Schema 为准。

destructive Action 不能直接 run/send。先执行 plan --risk destructive，查看服务端 返回的精确对象、警告和有效期；确认无误后执行 action-cli confirm <plan-id>。确认时服务端 会再次校验当前 Context Grant、Action Grant、目标状态和插件业务条件。Runner 可以自动获取 plan，但不会自动批准 confirm。

list 用于发现资源及 URI，query 用于对扁平结构化记录进行过滤和分析，read 读取单个资源的内容或摘要，stat 会真正验证文件当前是否可以生成或下载。需要读取所有 分页时可对 list、search 或 query 使用 --all；CLI 会按 nextCursor 顺序读取， 不会并行请求数据源。in 的右侧必须是 JSON 数组；判断数组字段是否包含单个元素时使用 contains，例如 sourceLists:contains:todo。

eq 和 ne 的裸值按字符串传递，所以数字形式的资源编号无需额外 JSON 引号；服务端也会 将数字过滤值与内容相同、没有前导零的字符串编号正确匹配。in 的右侧仍必须使用 JSON 数组。读取 JSON 资源时，默认 JSON 输出会保留完整资源信封；使用 --format text 可以直接 输出资源的 content，适合管道交给 jq、Python 或其他本地工具。

完整参数和版本请运行：

资源 URI 和 Action Target 明确选择要访问的数据。令牌只决定当前主体是否有权访问该 URI 或 Target；管理员拥有全部授权，但不会切换或冒充外部身份。

context-cli --help
action-cli --help
context-cli --version
action-cli --version
context-cli doctor

context-cli doctor 检查当前包中的两个命令、共享环境变量、API 连通性、令牌鉴权以及当前 可发现的 Context/Action 数量；令牌内容不会出现在输出中。

版本更新提示

两个命令在直接连接交互式终端时，每 24 小时最多查询一次 npm 的最新稳定版本。发现新版后， 更新方法会写入标准错误；JSON 标准输出保持不变。通过管道、Agent 或其他非交互方式运行时 不会发起版本检查，企业内网或离线环境中的网络失败也会静默忽略。

如需显式关闭提示，可使用任一方式：

export NO_UPDATE_NOTIFIER=1
# 或使用 npm 约定的环境变量
export npm_config_update_notifier=false

更新检查只提示，不会自动安装或修改当前版本。

Windows 与 Python

CLI 始终以 UTF-8 输出 JSON 和中文文本，不根据 Windows 系统代码页切换编码。Python 通过 subprocess 读取输出时应显式使用 UTF-8：

PowerShell：

chcp 65001 > $null
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [Console]::OutputEncoding

CMD：

chcp 65001

Git Bash：

export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

这些设置只调整终端解码方式，不改变 CLI 的 UTF-8 输出协议。

import subprocess

subprocess.run(command, text=True, encoding="utf-8", check=True)

也可以为 Python 设置 PYTHONUTF8=1。CLI 不输出 BOM，也不会调用 chcp，以保证同一 JSON 管道在 Windows、Linux 和 OCI 沙箱中保持一致。

需要避免终端编码差异或让 Agent 后续稳定读取结果时，优先使用 --output：

context-cli whoami --output .\whoami.json
action-cli list --output .\actions.json

下载时也可以通过 --output 指定文件。未指定时，CLI 使用服务端返回的文件名：Agent Runner 配置了 CONTEXT_WORKSPACE 时下载到该工作区；个人电脑未配置时下载到 ~/.context-cli/。同名文件默认不覆盖，确认覆盖时使用 --force。

退出码

• 0：成功
• 1：参数、网络或服务错误
• 2：未认证或令牌失效
• 3：没有访问权限
• 4：资源不存在

安全边界

• context-cli 只提供读取能力；action-cli 只执行插件声明且当前主体获准的 Action。
• 两个 CLI 都不接受命令参数覆盖 API 地址；地址只能由受控环境变量注入。action-cli 不接受 Webhook 或供应商凭据；写操作必须声明通用风险，服务端会与插件定义核对。Runner 自动允许只读发现、write 和 destructive plan，但不会自动批准 confirm。
• 结构化 JSON 仍由服务端按 Action 类型和目标重新校验；Action 默认只执行一次，只有插件明确声明可安全重试且抛出可重试错误时才会重新执行。
• Agent 使用按运行签发的短期令牌；个人工具使用绑定用户授权的 Personal Token；外部 Agent 使用管理员创建的 Service Token。
• 令牌只通过环境变量、标准输入或系统密钥管理工具提供，不写入命令参数。
• 所有 Context 与 Action API 访问都会在服务端执行授权并记录审计信息。

开发

npm --prefix apps/context-cli test
npm --prefix apps/context-cli run verify:package

源码位于 MoziaVerse/mozia-org-platform。