@comate/zulu

v1.0.0

Published

9 hours ago

AI Coding Agent

0High
0Medium
0Low

otakustay

shenyuw27

mbear

Zulu CLI

环境

nodejs >= 18
ripgrep >= 12，需要手动安装

安装

安装 Zulu CLI

npm install -g @comate/zulu

安装 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 至少有一个

| 参数 | 别名 | 类型 | 功能 | |:---|:---|:---|:---| | --license | -l | string | License | | --query | -q | string | 用户提交的内容 | | --attach-file | | string[] | 关联文件路径 | | --attach-image | | string[] | 关联图片路径 | | --activate-skill | | string[] | 激活 Skill 名称 | | --activate-command | | string[] | 激活 Command 名称 | | --activate-subagent | | string[] | 激活 Subagent 名称 | | --activate-rule | | string[] | 激活的 Rule 路径 | | --model | -m | string | 模型名称，支持 ID 和显示名，推荐显示名 | | --conversation | -c | string | 对话 ID，用于多轮对话 | | --mode | | string | 使用模式，默认 Agent，可选 Ask 或 Plan | | --ripgrep | | string | ripgrep 的路径 | | --cwd | | string | 当前工作区路径 | | --display | -d | string | 输出模式，默认 task，可选 legacy、record、event-stream、record-stream |

示例：

zulu run --query="你好" --license=xxxx

查询模型

zulu list-model [args]

| 参数 | 别名 | 类型 | 功能 | |:---|:---|:---|:---| | --license | -l | string | SaaS 的 License | | -cwd | | string | 当前工作区路径 |

输出结构：

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

检查上下文

zulu inspect [args]

| 参数 | 别名 | 类型 | 功能 | |:---|:---|:---|:---| | --license | -l | string | SaaS 的 License | | --cwd | | string | 当前工作区路径 |

输出结构：

{
  "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

| key | value | 描述 | |:---|:---|:---| | HTTP_HOST | string | 设置服务地址，默认是 https://comate.baidu.com | | NO_PROXY | string | 设置不走代理的地址列表，支持逗号分隔 | | DEBUG | boolean | 打开调试日志 |

多轮对话说明

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

调试

设置环境变量 DEBUG=true，STDOUT 会显示 debug 级别日志
可在 ~/.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"]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme