Zulu CLI

环境

• nodejs >= 18
• ripgrep >= 12（可选，安装时会自动检测和下载）

安装

安装 Zulu CLI

npm install -g @comate/zulu

安装流程说明：

• 安装时会优先检测系统中是否已有满足版本要求（>= 12.0.0）的 ripgrep
• 如果系统已有满足条件的版本，则直接使用，不会额外下载
• 如果系统没有或版本不满足，会自动下载预编译的 ripgrep 二进制文件

手动安装 ripgrep（可选）

如果需要手动安装 ripgrep，以下是在不同操作系统和包管理器中安装 ripgrep 的常见命令：

macOS

brew install ripgrep

Windows

winget install BurntSushi.ripgrep.MSVC

Ubuntu / Debian

sudo apt update
sudo apt install ripgrep

CentOS

sudo yum install epel-release
sudo yum install ripgrep

验证安装

rg --version

网络

默认请求 https://comate.baidu.com。如果环境未知，请执行 zulu --ping 测试连通性；如果不通：

• 厂内用户可通过 export HTTP_HOST="https://comate-saas-proxy.now.baidu-int.com" 修改默认请求域名
• 私有服务或其他特殊场景可通过 export HTTP_HOST="xxxx" 指定其他 Zulu 支持的域名

使用

执行任务

zulu run [args]

约束说明：

• license 必填
• query、activate-skill、activate-command 至少有一个

补充说明：

• --retry 必须是大于等于 0 的整数
• --retry 和 --retry-query 必须同时传入
• --display legacy 不支持 --retry
• 指定 --conversation 或使用 --continue 解析到已有会话时，同一 conversation 的多个 zulu run 会按启动入队顺序严格串行执行
• 不同 conversation 的 zulu run 互不阻塞；未指定 conversation 的新会话不参与该串行队列
• --force 用于放弃排队：先向排在前面的同会话进程发 SIGTERM（对方会清理自己的 kernel 子进程），5 秒内没退出再 SIGKILL，随后本次 run 立即开始；新会话没有可抢占的进程，此时 --force 无效果
• 排队等待期间可以按 Ctrl+C（或对进程发 SIGTERM）直接放弃本次 run：退出前会撤掉自己的排队号，前面正在执行的任务不受影响

示例：

zulu run --query="你好" --license=xxxx
zulu run --query="请总结当前仓库" --license=xxxx --retry=2 --retry-query="继续"
zulu run --query="换个方向重来" --conversation=conv-abc123 --force

查询模型

zulu list-model [args]

输出结构：

[
  {
    "modelId": "...",
    "displayName": "...",
    "thinking": true,
    "image": false
  }
]

检查上下文

zulu inspect [args]

输出结构：

{
  "rules": [
    {
      "path": "..."
    }
  ],
  "mcp": [
    {
      "name": "..."
    }
  ],
  "subagents": [
    {
      "name": "...",
      "description": "..."
    }
  ],
  "commands": [
    {
      "name": "..."
    }
  ],
  "skills": [
    {
      "name": "...",
      "description": "..."
    }
  ]
}

输出模式

task

任务完成后输出一个带 Frontmatter 的 Markdown 格式，Frontmatter 中包含 conversationId，正文为最后一轮文本，适合作为 Subagent 消费。

---
conversationId: xxx
sessionStorePath: xxx
status: ok
---
[本次任务的总结性文本]

legacy

保持与当前版本一致的输出格式，用于兼容历史调用方。输出为完整 JSON，对话主结构可概括为：顶层包含 conversationInfo、messages 与 conversionId；其中 conversationInfo 描述当前会话状态，messages 为消息数组，每条消息下包含 agentInfo、tokenUsage、elements 等字段，elements 采用树形结构组织 REASON、TEXT、TOOL 等执行内容。

{
  "conversionId": "...",
  "conversationInfo": {
    "id": "...",
    "status": "Completed",
    "type": "AgentConversation",
    "utime": 1773653416551,
    "ctime": 1773653416547
  },
  "messages": [
    {
      "id": "...",
      "agentInfo": {},
      "role": "assistant",
      "status": "success",
      "tokenUsage": {
        "usagePercentage": 0.0,
        "contextUsed": 111111,
        "contextLimit": 192000,
        "needCompression": false,
        "savedPercentage": 0
      },
      "elements": [
        {
          "id": "...",
          "children": [
            {
              "type": "REASON",
              "content": "..."
            },
            {
              "type": "TOOL",
              "toolName": "...",
              "params": {},
              "toolState": "executed",
              "result": {},
              "children": []
            },
            {
              "type": "TEXT",
              "content": "..."
            }
          ]
        }
      ]
    }
  ]
}

record

任务全部完成后一次性输出完整对话记录，JSON 格式。交互方式与 legacy 相同，但结构重新定义，适合评测分析等场景。

顶层结构更扁平，仅包含 conversationId 与 messages 两个核心字段：

• conversationId：本次任务对应的会话 ID
• messages：按时间顺序排列的执行节点数组

messages 中的节点按 type 区分，常见类型如下：

• REASON：思考过程节点，通常包含 id、type、end、content、startTime、lastModifiedTime
• TEXT：输出给用户的文本节点，通常包含 id、type、end、content、startTime、lastModifiedTime
• EXCEPTION：异常节点，通常包含 id、type、content，用于表示执行过程中产生的异常信息
• TOOL：工具调用节点，除通用字段外，还包含 toolName、params、toolState、result，如存在子任务或子流程则通过 children 继续嵌套

{
  "conversationId": "",
  "messages": [
    {
      "id": "",
      "type": "REASON",
      "end": true,
      "content": "...",
      "startTime": 1773653394883,
      "lastModifiedTime": 1773653396370
    },
    {
      "id": "",
      "type": "TOOL",
      "toolName": "delegate_subtask",
      "params": {
        "agent_type": "xxx",
        "description": "xxx",
        "query": "xxx"
      },
      "toolState": "executed",
      "result": {
        "metadata": {}
      },
      "children": [
        {
          "id": "",
          "type": "REASON",
          "end": true,
          "content": "...",
          "startTime": 1773653405742,
          "lastModifiedTime": 1773653406958
        }
      ]
    },
    {
      "id": "",
      "type": "TEXT",
      "end": true,
      "content": "...",
      "startTime": 1773653581086,
      "lastModifiedTime": 1773653581808
    }
  ]
}

可以将 record 理解为“完整执行轨迹”的直接落盘版本：

• 不再像 legacy 一样按 conversationInfo、messages、elements 分层包装
• 而是直接将执行过程展开为 messages[]
• 当某个subagent内部又触发了一段完整子流程时，通过 children 表示嵌套关系

event-stream

以一行一个 JSON 的形式流式输出每一次增量数据，适用于第三方界面对 CLI 的封装。

当前事件结构分为4类事件，常见事件类型如下：

• conversation-messages：同步整轮消息列表，字段包含 conversationInfo 与 messages
• conversation-status：同步会话状态，字段包含 conversationInfo
• partial-message-data：同步助手消息级别的增量信息，字段包含 conversationInfo 与 messages
• partial-message-elements：同步助手消息内 elements 的增量结构，字段包含 conversationInfo 与 messageData

{"type":"conversation-messages","conversationInfo":{"id":"","status":"Running","type":"AgentConversation","utime":1773653613239,"ctime":1773653613239},"messages":[]}
{"type":"conversation-status","conversationInfo":{"id":"","status":"Running","type":"AgentConversation","utime":1773653613239,"ctime":1773653613239}}
{"type":"partial-message-data","conversationInfo":{"id":"","status":"Running","type":"AgentConversation","utime":1773653613243,"ctime":1773653613239},"messages":[{"id":"","v2":true,"role":"assistant","status":"inProgress","content":{},"elements":[{"id":"","discard":false,"children":[]}]}]}
{"type":"partial-message-elements","conversationInfo":{"id":"","status":"Running","type":"AgentConversation","utime":1773653613243,"ctime":1773653613239},"messageData":{"id":"","elements":[{"id":"","discard":false,"children":[{"id":"","type":"REASON","end":false,"content":"The","startTime":1773653617642,"lastModifiedTime":1773653617642}]}]}}

record-stream

以一行一个 JSON 的形式流式输出已经闭合的元素。与 event-stream 的区别是它不输出中间状态，而是在一个块（Reason、Text、ToolCall、ToolResult）结束后输出一次，适合观察执行轨迹。

{"conversationId":"", "messages":[{"id":"", "type":"TOOL", "toolName":"", "params":{}, "toolState":"", "result":{}, "children":[]}]}

Env

多轮对话说明

1. conversation 传入对话 ID 后，可继续基于本地已有历史记录发起多轮对话
2. conversation 指定的历史轮次必须在本地存在，历史记录位于 ~/.comate-engine/store，文件名前缀为 chat_session_
3. 多轮对话中途无法切换模型

调试

• 设置环境变量 DEBUG=true，debug 日志只写入 ~/.comate-engine/log/zulurun-YYYY-MM-DD.log，不输出到 stdout/stderr
• 可在 ~/.comate-engine/store 中查看对应轮次对话的详细日志

最佳实践

• Zulu CLI 使用 Turbo 模式，黑名单为空，这意味着默认会执行模型产生的指令，请注意安全风险
• 尽量明确描述任务，并根据场景选择合适的 display 输出模式
• 如需多轮对话，请妥善保存 conversationId

Dockerfile

FROM node:current-alpine3.22

RUN apk add --no-cache ripgrep
RUN npm install -g @comate/zulu

WORKDIR /app

CMD ["zulu", "--help"]