Workova 文档

Appearance

CLI 使用指南 ​

这页适合 3 类人：

  • 想用命令行操作 Workova 的高级用户
  • 想把 Workova 接进脚本或自动化流程的人
  • 想了解 CLI 能力边界的开发者

先说一个最重要的现实情况：

仓库里的 CLI 现在已经有真实实现，但不是所有旧文档里的说法都还成立。
这页只按当前 desktop/apps/cli 代码、node dist/index.js --help 和 contracts:list 的结果来讲。

CLI 是什么 ​

如果你平时主要用图形界面，可以把 CLI 理解成：

  • 用终端命令来操作 Workova
  • 适合批量处理、脚本调用、自动化集成
  • 适合不想每次都点页面的高级用户

当前实现里，CLI 不是第二套 runtime，而是优先复用桌面端 runtime 的能力。

这样做的好处很直接：

  • 图形界面和命令行不会各跑各的逻辑
  • 后面做自动化接入时，不容易出现“网页能用、CLI 不能用”的分裂问题

先记住当前真实命令语法 ​

当前 CLI 用的是扁平命令路径：

bash
workova <domain>:<action>

例如：

bash
workova runtime:health
workova auth:status
workova agent:list
workova run:start "帮我总结今天的工作"
workova mcp:list

不是旧文档里那种：

bash
workova auth login
workova run start
workova mcp list

这种“空格分层子命令”当前并没有实现，写脚本时一定要注意。

先跑哪几条命令最合适 ​

1. 看运行时是否正常 ​

bash
workova runtime:health

2. 看当前实际登记了哪些命令 ​

bash
workova contracts:list

3. 看当前登录态 ​

bash
workova auth:status

4. 看单条命令支持什么参数 ​

bash
workova run:start --help

如果你是第一次接触 Workova CLI，这 4 条命令比背一长串参数更有用。

当前没有统一的全局参数层 ​

这是现在最容易误解的点。

像下面这些参数，不能再写成“所有命令都支持”：

  • --output
  • --json
  • --profile
  • --yes
  • --timeout
  • --verbose

更准确的说法是：

  • --profile 主要属于 config:*
  • --output 主要属于 exec
  • --stream 只在部分运行类命令里有意义

会话连续对话怎么理解 ​

CLI 里，聊天不是一次性问答，而是支持继续已有会话。

第一次发起时：

bash
workova chat:send "帮我先写一版活动方案" --agent writer

继续同一段会话时：

bash
workova chat:send "再把预算部分补上" --conversation conv_123

你可以把 conversationId 理解成这段会话的编号。

当前 CLI 主要分成哪些领域 ​

从当前 desktop/apps/cli/src/index.ts 可以确认，主要分组有：

  • contracts:*、config:*
  • runtime:*、auth:*、account:*
  • agent:*、conversation:*、chat:*、run:*
  • workflow:*、workflow-run:*、picker:*
  • automation:*
  • channel:*、coord:*、memory:*
  • mcp:*、skill:*、plugin:*
  • permission:*、browser:*、app:*
  • ipc:*
  • exec

如果你想看按类别整理好的表，继续看：

当前执行模型怎么理解 ​

当前命令可以分成两类：

  • 本地执行
  • 通过桌面 runtime bridge 执行

当前能确认完全本地执行的只有很少一部分：

  • contracts:list
  • runtime:contracts
  • config:list
  • config:get
  • config:set
  • config:reset
  • plugin:validate

除这几条之外，大多数命令都依赖 bridge。

bridge 找不到时会怎样 ​

CLI 当前会优先尝试这些入口：

  • WORKOVA_BRIDGE_URL
  • WORKOVA_GUI_APP_PATH
  • WORKOVA_RUNTIME_BRIDGE_BIN

如果这些都不可用，大多数 runtime 命令会失败。

例外是少量账号相关命令会尝试降级，例如：

  • auth:*
  • account:*
  • runtime:health
  • runtime:capabilities

其中账号类回退通常还依赖：

bash
WORKOVA_API_BASE_URL

一个最稳妥的使用习惯 ​

如果你要写脚本，建议固定按这个顺序：

  1. 先跑 workova contracts:list
  2. 再跑目标命令的 --help
  3. 输入内容优先放到 --input-file
  4. 再决定要不要写成自动化脚本

当前限制 ​

这页现在已经比旧版准确很多，但仍有 2 个限制：

  1. 不是每条命令都适合现在就对外承诺成长期稳定接口
  2. 很多命令是否能跑通，取决于桌面 runtime bridge 是否可达

相关文档 ​

内容通过 Markdown 维护，适合持续迭代。

Copyright © Workova