# @comate/zulu 中文文档 规范地址：https://npmcn.com/package/%40comate/zulu/ 版本：1\.7\.21 npm 元数据更新时间：2026-09-24T06:10:27.052Z 中文译文更新时间：2026-11-10T12:21:38.477Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40comate/zulu 原文对照：https://npmcn.com/package/%40comate/zulu/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：88 MB，3329 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=20\.10\.0 - 运行依赖：7 个 - 首次发布：2025-07-24T08:08:49.719Z - 最新版本发布：2026-09-22T12:25:55.710Z - 近 30 天下载量：2947（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：119（近 12 个月 102 个） ## 中文简介 AI 编码代理 ## 安装 ```sh npm install @comate/zulu ``` 也可以使用：`pnpm add @comate/zulu`、`yarn add @comate/zulu`、`bun add @comate/zulu` ## README # Zulu CLI ## 环境 - nodejs >= 18 - ripgrep >= 12（可选，安装时会自动检测和下载） ## 安装 ### 安装 Zulu CLI ```shell npm install -g @comate/zulu ``` **安装流程说明：** - 安装时会优先检测系统中是否已有满足版本要求（>= 12.0.0）的 `ripgrep` - 如果系统已有满足条件的版本，则直接使用，**不会额外下载** - 如果系统没有或版本不满足，会自动下载预编译的 ripgrep 二进制文件 ### 手动安装 ripgrep（可选） 如果需要手动安装 ripgrep，以下是在不同操作系统和包管理器中安装 `ripgrep` 的常见命令： #### macOS ```shell brew install ripgrep ``` #### Windows ```shell winget install BurntSushi.ripgrep.MSVC ``` #### Ubuntu / Debian ```shell sudo apt update sudo apt install ripgrep ``` #### CentOS ```shell sudo yum install epel-release sudo yum install ripgrep ``` #### 验证安装 ```shell rg --version ``` ## 网络 默认请求 `https://comate.baidu.com`。如果环境未知，请执行 `zulu --ping` 测试连通性；如果不通： - 厂内用户可通过 `export HTTP_HOST="https://comate-saas-proxy.now.baidu-int.com"` 修改默认请求域名 - 私有服务或其他特殊场景可通过 `export HTTP_HOST="xxxx"` 指定其他 Zulu 支持的域名 ## 使用 ### 执行任务 ```shell 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 | 当前工作区路径 | | `--retry` | | string | 最大自动重试次数；当最后一轮返回不是文本或执行报错时，CLI 会继续追加一轮重试 | | `--retry-query` | | string | 每次自动重试时追加发送的 query，需与 `--retry` 同时使用，例如传 `继续` | | `--display` | `-d` | string | 输出模式，默认 `task`，可选 `legacy`、`record`、`event-stream`、`record-stream` | | `--force` | | boolean | 强制执行：杀掉同会话排在前面的进程后立即执行本次 run，不排队等待 | 补充说明： - `--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：退出前会撤掉自己的排队号，前面正在执行的任务不受影响 示例： ```shell zulu run --query="你好" --license=xxxx zulu run --query="请总结当前仓库" --license=xxxx --retry=2 --retry-query="继续" zulu run --query="换个方向重来" --conversation=conv-abc123 --force ``` ### 查询模型 ```shell zulu list-model [args] ``` | 参数 | 别名 | 类型 | 功能 | | :-- | :-- | :-- | :-- | | `--license` | `-l` | string | SaaS 的 License | | `-cwd` | | string | 当前工作区路径 | 输出结构： ```json [ { "modelId": "...", "displayName": "...", "thinking": true, "image": false } ] ``` ### 检查上下文 ```shell zulu inspect [args] ``` | 参数 | 别名 | 类型 | 功能 | | :-- | :-- | :-- | :-- | | `--license` | `-l` | string | SaaS 的 License | | `--cwd` | | string | 当前工作区路径 | 输出结构： ```json { "rules": [ { "path": "..." } ], "mcp": [ { "name": "..." } ], "subagents": [ { "name": "...", "description": "..." } ], "commands": [ { "name": "..." } ], "skills": [ { "name": "...", "description": "..." } ] } ``` ## 输出模式 ### `task` 任务完成后输出一个带 Frontmatter 的 Markdown 格式，Frontmatter 中包含 `conversationId`，正文为最后一轮文本，适合作为 Subagent 消费。 ```md --- conversationId: xxx sessionStorePath: xxx status: ok --- [本次任务的总结性文本] ``` ### `legacy` 保持与当前版本一致的输出格式，用于兼容历史调用方。输出为完整 JSON，对话主结构可概括为：顶层包含 `conversationInfo`、`messages` 与 `conversionId`；其中 `conversationInfo` 描述当前会话状态，`messages` 为消息数组，每条消息下包含 `agentInfo`、`tokenUsage`、`elements` 等字段，`elements` 采用树形结构组织 `REASON`、`TEXT`、`TOOL` 等执行内容。 ```json { "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` 继续嵌套 ```json { "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` ```json {"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）结束后输出一次，适合观察执行轨迹。 ```json {"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 | 打开调试日志，仅写入 `~/.comate-engine/log/zulurun-YYYY-MM-DD.log` | ## 多轮对话说明 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 ```dockerfile FROM node:current-alpine3.22 RUN apk add --no-cache ripgrep RUN npm install -g @comate/zulu WORKDIR /app CMD ["zulu", "--help"] ``` ## 常见问题 ### @comate/zulu 是什么？ AI 编码代理 ### 如何安装 @comate/zulu？ 在项目目录运行 npm install @comate/zulu，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 zulu，可以用 npx zulu 直接运行。 ### @comate/zulu 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/comate\_\_zulu 是否存在。 ### @comate/zulu 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @comate/zulu 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.10\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @comate/zulu 可以商用吗？ @comate/zulu 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @comate/zulu 的下载量有多少？ 根据 npm 官方下载统计，@comate/zulu 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,947 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @comate/zulu 还在维护吗？ 最新版本 1\.7\.21 发布于 2026/09/22（1 个月前）；至今共发布 119 个版本，其中过去 12 个月发布了 102 个；首次发布于 2025/07/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。