using-coze-cli

name	using-coze-cli
version	0.3.2
description	Coze CLI（coze 命令）统一入口与共享基础，使用任何 coze 能力前必读（登录授权、组织/空间、配置、错误码与权限排查）。四个子模块：coze code（创建/迭代网页·App·小程序·Agent·工作流等编程项目、发需求、预览、部署、环境变量/域名/数据库）、coze session（Claw 对话、PPT、播客、长任务产物）、coze generate（图片/语音 TTS/视频生成）、coze file（本地文件转在线链接）。触发场景（满足任一即触发，无需用户显式点名 coze）：想做网页/App/小程序、开发或迭代项目、上线部署；生成图片/语音/视频；做 PPT/播客；把本地文件转成在线链接；登录授权/No permission/切换组织空间；输入以 /coze-cli、/coze 开头（前缀仅作路由）。
metadata	{"requires":{"bins":["coze"]},"cliHelp":"coze --help"}

Coze CLI 共享规则

本技能指导你如何通过 coze 命令完成基础配置和上下文管理，以及有哪些通用注意事项。

适用场景

• coze code（核心）：创建 Coze 编程项目（网页 / App / 小程序 / Agent / 工作流 / skill / 助手），并先按用户意图识别项目类型；发送需求 message 迭代开发、轮询状态、获取 preview、部署上线；以及环境变量 / 域名 / 默认会话技能 / 模型 / 工具 / 数据库 / Git 与远程仓库管理。
• coze generate：文本生成图片、语音合成（TTS）、视频生成。
• coze file：上传本地文件，将在线可访问链接返回给用户。
• coze session（Claw）：创建/找回 session、发送 session message、监听 reply、查询 progress、处理文件 / PPT / 播客产物。
• 用户输入以 /coze-cli 或 /coze 开头时，必须优先把这条消息视为显式路由到 Coze CLI skill；前缀只用于路由，不属于最终发给底层命令的正文。

模块化阅读顺序

本文件只保留 Coze CLI 的共享基础规则。进入具体命令族时，优先继续阅读对应模块文档：

• coze session *：先读 coze-claw/MODULE.md
• coze code *：先读 coze-code/MODULE.md
• coze file *：先读 coze-file/MODULE.md
• coze generate *：先读 coze-generate/MODULE.md

约束：

• 根 SKILL.md 只放共享规则，不堆积 Claw 专用长任务编排细节。
• Claw 相关的 agent 执行约束、恢复策略、长任务规则，尽量收敛到 coze-claw/ 目录内。

必须遵守的执行原则

1. 用户明确指定 Coze CLI 时，禁止私自改用别的能力

• 如果用户明确要求"用 Coze CLI 生成语音/图片/视频"，就必须优先把 Coze CLI 路径跑通。
• 禁止在未充分排查 Coze CLI 正确用法前，擅自改用 Agent 宿主、自带 TTS、第三方生成接口或 Web 页面手工下载流程。
• 只有在 Coze CLI 明确报错、能力缺失，且已经向用户解释并获得同意时，才允许退回到其他方案。

2. 优先使用 --format json

• 需要结构化解析结果时，优先增加 --format json。
• 注意：coze code message send --format json 输出 NDJSON 事件流，必须按行解析，不能直接整段 JSON.parse()；应找 finish: true 的行获取最终结果。
• 注意：coze session message --wait --format json、coze session watch --format json、coze session progress watch --format json 也会输出事件流，必须按行/事件解析，不能整段 JSON.parse()。
• coze session message --wait --format json 的最终 reply 事件是 reply_completed，不是 finish: true。
• 补充：coze session message --wait --format json 如果命中后台 progress_id，事件流后会额外给出一个稳定的 task 快照对象，至少包含 task_id、progress_id、task_status，后续优先改用 coze session task * 跟进。
• --format 默认值为 text，text 模式下输出人类可读的格式化文本。
• JSON 输出的顶层对象可能携带 _notice 字段（非业务数据）；两类子字段：_notice.skill 表示本机 skills 与 CLI 版本不一致，_notice.update 表示有 CLI 新版本可用。看到后在完成当前任务之余执行其 command 字段给出的修复命令（如 coze self skill install 或 coze upgrade），解析业务数据时忽略该字段即可。输出为数组时该提示会改走 stderr 单行文本。默认情况下 skill 不一致会被静默自动修复（skill.mode=auto），通常看不到 _notice.skill；仅当用户改为 skill.mode=notify、或自动同步失败时才会出现该提示。CI 环境（CI 环境变量为非 false/0 值）下不产生这两类提示；COZE_CLI_NO_SKILL_NOTIFIER 跳过本次 skill 检查（既不同步也不提示），COZE_CLI_NO_UPDATE_NOTIFIER 跳过本次升级检查。

3. 对用户交付 Coze Session 结果时，必须回传最终 reply，不要只回状态

• 对 coze session *，message sent、watching、progress started、task finished、已完成/耗时 xx s 都只是过程状态，不是最终用户可见结果。
• 短任务：拿到 reply_completed.content/files 后，必须把回复正文或产物链接整理回给用户。
• 长任务前置回复：如果 message --wait --format json 在命中 progress_id / task_id 之前，已经出现了有语义的 reply_update.content 或 reply_completed.content，必须先把这段前置回复回给用户，再继续进入后台任务跟进。
  • 典型场景：先回复“我先加载 PPT 技能/我先读一下风格参考”，随后才启动 progress。
  • 禁止把这类前置回复吞掉，只给用户返回“开始生成了/任务已启动/稍后给你链接”。
• 长任务 follow-up：如果当前回合已经拿到 task_id / progress_id，要么按 coze-claw/MODULE.md 的 follow-up 规则立即创建独立后台任务，要么在同一回合明确告知“当前还没有创建后台 follow-up 任务”并给出下一步选项；禁止没创建也说“我会继续盯着/完成后自动回你”。
• 长任务：如果命中 progress_id / task_id，任务终态后必须继续：
  • 优先读取 coze session replies <message_id> -s <session_id> --format json
  • 或读取终态 coze session task show/refresh/watch 里的 reply_content 和 artifacts
• 只要已经有 session_id、message_id、task_id 这些恢复主键，即使等待过程被中断，也必须补查结果并回给用户。
• 禁止在用户侧只留下“已经发出去”“正在等结果”“已完成”而没有实际 reply 内容的收尾。

3.1 对 Coze Session，默认复用上一次 session，除非用户明确要求新建

• 只要用户没有明确表达“新建话题”“新增话题”“开一个新会话”“不要沿用之前上下文”这类意图，就应优先复用上一次成功使用的 session_id。
• 当前 CLI 会把最近一次成功使用的 session_id 持久化到本地配置；Agent 可用 coze session current --format json 读取，用 coze session use <session_id> --format json 显式切换。
• coze session message、coze session watch、coze session replies、coze session podcast message、coze session ppt edit 在省略 -s/--session-id 时，会默认复用当前本地 session。
• 推荐顺序：
  1. 先执行 coze session current --format json 读取本地默认 session_id
  2. 用 coze session status -s <session_id> --format json 确认该 session 仍可用
  3. 如果需要切换到指定会话，执行 coze session use <session_id> --format json
  4. 如果本地没有最近 session_id，再用 coze session list --limit 20 --format json 找最近一个可复用 session，并在确认后 coze session use <session_id> --format json
  5. 只有在用户明确要求新开话题，或确实没有可复用 session 时，才执行 coze session create --format json
• 禁止因为“发起新请求”就默认创建新 session，这会丢失连续对话上下文，也会增加 agent 自己维护上下文的负担。

4. 对用户交付文件时，必须返回在线链接，不要返回本地路径

• 本地路径如 /tmp/foo.mp3、./output/image.png、相对路径或沙箱路径，对用户不可直接访问。
• 生成文件后，必须继续执行 coze file upload <path>。
• 最终返回给用户的应是上传后的在线 URL，而不是本地文件路径。

5. 不确定命令用法时，使用 --help 或 --man 查看

• 任何命令都支持 --help 查看简要帮助，--man 查看完整手册（含参数说明、示例、错误码）。
• 当不确定某个命令的参数、选项或用法时，先执行 <command> --help 或 <command> --man 获取准确信息，不要凭猜测拼命令。
• 示例：

  coze code project create --help
  coze code deploy --man
  coze generate video create --help
  

6. 显式路由前缀只用于命中 skill，不得透传给底层 prompt

• 当用户输入以 /coze-cli 或 /coze 开头时，首个 token 仅作 skill 路由用途。
• 在调用 coze session message、coze session podcast message 或其他 Coze CLI 子命令前，必须剥离该前缀。
• 示例：
  • /coze-cli 制作一个介绍潮汕美食的 PPT -> 制作一个介绍潮汕美食的 PPT
  • /coze-cli @PPT 制作介绍海南美食的 PPT -> @PPT 制作介绍海南美食的 PPT
• 禁止把 /coze-cli、/coze 原样拼进最终发送给 Claw 的 message。

安装 CLI

npm install -g @coze/cli

如果找不到包，可执行：

npm config set registry https://registry.npmjs.org/

安装/升级后 CLI 会自动静默执行 coze self skill install，把自带 skills 安装到本机 AI agents。coze self 是 CLI 工具自身的能力集合（区别于操作 Coze 平台资源的命令）；若运行命令时提示 skills 缺失或版本不一致，手动执行：

coze self skill install

登录与身份验证

避坑：OAuth 授权超时与阻塞问题

• coze auth login 的 OAuth 激活链接和设备码通常输出在 stderr，需要合并捕获。
• 致命问题：设备码有 10 分钟有效期，且命令会前台阻塞等待。如果 Agent 同步等待该命令执行，可能会卡死流程，且用户往往来不及操作。
• 补充问题：部分 Agent 宿主会回收 detached/nohup 子进程，导致 coze auth login 在用户完成授权前就异常消失，表面上看像“用户已授权但 CLI 一直未登录”。
• 当前推荐顺序：
  1. 优先在一个可持续持有的 PTY/TTY 会话里直接运行 coze auth login
  2. 读取并返回授权链接给用户
  3. 保持该会话存活，等待 Authentication successful. Credentials saved.
  4. 成功后再执行 coze auth status --format json
• 只有在确认宿主不会回收 detached 子进程时，才使用下面的 nohup + 退出码文件方案。
• 推荐方案：后台执行 + 轮询获取链接 + 进程自记录退出码：

  # 0. 清理上次残留的临时文件（避免误读旧状态）
  rm -f /tmp/coze-login.log /tmp/coze-login.pid /tmp/coze-auth-exit-code.txt
  
  # 1. 后台启动登录命令，让进程自己记录退出码
  nohup bash -c '
    coze auth login
    EC=$?
    echo $EC > /tmp/coze-auth-exit-code.txt
    exit $EC
  ' > /tmp/coze-login.log 2>&1 &
  echo $! > /tmp/coze-login.pid
  
  # 2. 轮询等待授权链接出现（最多等待 30 秒）
  for i in $(seq 1 15); do
    if grep -q "user_code=" /tmp/coze-login.log 2>/dev/null; then
      break
    fi
    sleep 2
  done
  
  # 2.1 检查是否成功获取到链接
  if ! grep -q "user_code=" /tmp/coze-login.log 2>/dev/null; then
    echo "获取授权链接超时，请检查网络连接或重试"
    cat /tmp/coze-login.log 2>/dev/null
  fi
  
  # 3. 提取并返回授权链接
  grep "user_code=" /tmp/coze-login.log | grep -oE 'https://[^ ]+'
  

• 为什么让进程自己记录退出码：
  • wait 命令只能在启动进程的 shell 中使用，无法在后台子 shell 中跨进程等待。
  • 通过 bash -c '...; EC=$?; echo $EC > file' 让进程自己捕获并记录退出码。
  • 退出码精确反映本次授权结果，不受上次登录状态影响：
    • 退出码 0：用户完成授权
    • 非零退出码：授权失败（常见值：1 一般失败、2 认证错误、4 参数错误，具体原因看 JSON 输出中的错误码）
• 授权流程（必须遵守）：
  1. 先检查授权状态：在发起任何需要认证的操作前，必须先执行 coze auth status 确认是否已完成授权。
  2. 若未授权，后台执行并轮询获取链接：
     • 使用上述后台执行 + 轮询方案获取授权链接。
     • 一旦获取到链接，立即返回给用户。
     • 同时启动后台轮询任务自动检查授权状态。
  3. 检查退出码确认授权结果：
     • 进程结束后，退出码会自动写入 /tmp/coze-auth-exit-code.txt。
     • 通过轮询检查该文件确认授权结果：

       # 轮询检查退出码文件（最长等待 10 分钟）
       for i in $(seq 1 60); do
         if [ -f /tmp/coze-auth-exit-code.txt ]; then
           exit_code=$(cat /tmp/coze-auth-exit-code.txt)
           if [ "$exit_code" = "0" ]; then
             echo "授权成功"
           else
             echo "授权失败（退出码: $exit_code）"
           fi
           break
         fi
         sleep 10
       done
       
       # 兜底：如果轮询结束仍未获得退出码，说明进程异常
       if [ ! -f /tmp/coze-auth-exit-code.txt ]; then
         echo "授权超时或进程异常退出"
         # 检查后台进程是否仍在运行
         if [ -f /tmp/coze-login.pid ] && kill -0 "$(cat /tmp/coze-login.pid)" 2>/dev/null; then
           echo "登录进程仍在运行，尝试终止"
           kill "$(cat /tmp/coze-login.pid)" 2>/dev/null
         fi
       fi
       

  4. 授权完成后，再启动后续任务：
     • 授权是所有后续操作的前置条件。在确认已登录之前，不要创建任何后台任务或发起项目创建/部署等后续操作。
• 如果提示 [Auth] No API token found，先执行：

coze auth status

检查登录状态

• coze auth status 返回当前凭证状态。--format json 输出结构化数据，至少包含 logged_in，登录成功时通常还会返回 user 和 token_expires_at。
• Token 过期后 CLI 会在执行命令时自动尝试刷新，无需手动重新登录。

登出

• coze auth logout 清除本地凭证。

长时间命令处理

避坑：长耗时命令超时问题

• 部分命令（AI 生成、部署、OAuth 登录等）可能耗时数分钟甚至更久，超过沙箱超时限制（通常 600 秒）会导致命令被强制中断。
• 不同命令的阻塞行为不同，需要区分处理。

长耗时命令速查表

长耗时命令	默认行为	--wait	对应的轮询命令
coze auth login	同步阻塞（等待用户浏览器授权）	—	轮询退出码文件（见上文"登录与身份验证"）
coze code message send	非阻塞（发送后立即返回 status:'sent'）	✅ 加后阻塞等待 AI 回答流完成	coze code message status -p <project_id>
coze code project create	非阻塞（后台子进程执行 AI 生成）	✅ 加后变阻塞	coze code message status -p <project_id>
coze code deploy <id>	触发部署后立即返回	✅ 加后内置轮询(3s)	coze code deploy status <project_id>
coze code deploy fix <id>	非阻塞（后台子进程执行修复）	✅ 加后变阻塞	coze code message status -p <project_id>
coze generate video create	提交任务后立即返回 taskId	✅ 加后内置轮询(2s/5min超时)	coze generate video status <task_id>
coze generate audio	同步阻塞（SSE 流式返回）	—	—
coze generate image	同步阻塞（单次 API 调用）	—	—
coze session message	提交后立即返回 message_id	✅ 加后变阻塞并输出事件流	coze session replies <message_id>
coze session task show/refresh/watch	单次查询 / 主动刷新 / 持续观察本地恢复任务	—	coze session replies <message_id> / coze session progress poll <progress_id>
coze session watch	持续监听 websocket	—	必须加 --timeout，超时后用 replies 补偿
coze session progress watch	持续监听后台任务	—	必须加 --timeout，或改用 progress poll

coze code message status 和 coze code deploy status 本身都是单次查询，不会自动轮询。需要在脚本中循环调用。 coze code message cancel -p <project_id> 可取消进行中的消息任务。

场景一：命令支持非阻塞——不加 --wait 直接使用

project create、deploy fix 默认就是非阻塞的（通过 detached 子进程后台执行），deploy、generate video create 默认提交后立即返回。这些命令返回后，通过上表中对应的轮询命令检查结果即可。

# 示例：项目创建 + 轮询（默认非阻塞）
coze code project create --type web --message "需求描述"
# 命令立即返回 project_id，然后轮询消息状态
for i in $(seq 1 60); do
  result=$(coze code message status -p <project_id> --format json)
  status=$(echo "$result" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  echo "[$(date +%H:%M:%S)] 状态: $status"
  if [ "$status" = "done" ] || [ "$status" = "completed" ]; then
    echo "处理完成！"
    echo "$result"
    break
  elif [ "$status" = "failed" ]; then
    echo "处理失败"
    break
  fi
  sleep 30
done

注意：这些命令加 --wait 后会变成同步阻塞，应按场景二处理。推荐不加 --wait，改用对应轮询命令手动轮询。

场景二：命令处于阻塞状态——需要 nohup 后台执行

以下情况命令会同步阻塞，如果预计耗时较长可能超出沙箱超时限制，必须通过 nohup 后台执行，再用对应轮询命令检查结果：

• 本身始终阻塞的命令：generate audio、generate image、auth login 没有 --wait 选项，始终同步阻塞。
• 加了 --wait 的命令：message send --wait、project create --wait、deploy --wait、deploy fix --wait、generate video create --wait 加上 --wait 后会变成同步阻塞（其中 message send 不加 --wait 时为非阻塞，发送后立即返回，用 message status 轮询）。

# 示例：阻塞型 message send --wait 后台执行 + 轮询
# 注意：message send 不加 --wait 时为非阻塞（发送即返回），无需 nohup，直接调用后用 message status 轮询即可；
#       只有加了 --wait（同步等待 AI 回答流完成）且预计耗时较长时，才需要下面的 nohup 后台执行方案。
rm -f /tmp/coze-message.log /tmp/coze-message-exit-code.txt

nohup bash -c '
  coze code message send "需求描述" -p <project_id> --wait
  EC=$?
  echo $EC > /tmp/coze-message-exit-code.txt
  exit $EC
' > /tmp/coze-message.log 2>&1 &

# 通过 message status 轮询进度（对应轮询命令见上表）
for i in $(seq 1 60); do
  result=$(coze code message status -p <project_id> --format json 2>/dev/null)
  status=$(echo "$result" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  echo "[$(date +%H:%M:%S)] 状态: $status"
  if [ "$status" = "done" ] || [ "$status" = "completed" ]; then
    echo "处理完成！"
    echo "$result"
    break
  elif [ "$status" = "failed" ]; then
    echo "处理失败"
    break
  fi
  sleep 30
done

# 兜底：轮询结束仍未完成时检查后台进程退出码
if [ "$status" != "done" ] && [ "$status" != "completed" ]; then
  if [ -f /tmp/coze-message-exit-code.txt ]; then
    exit_code=$(cat /tmp/coze-message-exit-code.txt)
    echo "后台进程已退出，退出码: $exit_code"
  else
    echo "任务可能仍在进行中，请稍后再次执行轮询命令检查"
  fi
fi

核心原则：任何可能长时间阻塞的命令，都应后台执行或使用其内置的非阻塞模式，然后通过对应的轮询命令检查结果，避免沙箱超时中断。

组织与空间上下文

核心行为

• 切换组织时会自动清空 Space ID，需要重新选择工作空间。
• 指定不存在的组织 ID 会报错且不修改配置。
• 切换到个人账户有三种等价写法：coze organization use（省略 org_id）、coze organization use ""（显式空串）、coze organization unset（别名 coze organization reset）。均会清空 organizationId/enterpriseId（及 spaceId），且不再校验个人账户是否可用。
• CLI 的自动上下文补全仅作用于空间：未配置空间时，首次执行需要上下文的命令会自动选择第一个可用空间（结果可能不是期望的，建议始终显式设置）。组织不会自动选择——未显式设置组织时按上文的个人账户模式处理。

遇到 No permission 的修正顺序

1. coze config list — 查看当前配置
2. coze organization list — 查看可用组织
3. coze organization use <org_id> — 切换到正确的组织（或 coze organization unset / coze organization use 切换到个人账户）
4. coze space list — 查看当前组织下的空间
5. coze space use <space_id> — 切换到正确的空间

环境变量覆盖

• COZE_ORG_ID、COZE_SPACE_ID 环境变量可临时覆盖配置，无需修改持久化配置。
• --org-id、--space-id 全局参数也可以临时覆盖。
• 项目访问链接的域名由项目类型决定：web / app / miniprogram（coze 3.0 项目）使用 www.coze.cn，其它类型（agent / workflow / skill / assistant 等）使用 code.coze.cn。各命令输出的 URL（如 project_url、部署/预览链接）已由 CLI 据此生成，直接透传即可。
• COZE_CLI_PLATFORM 环境变量仅在无法获知项目类型的少数场景作为域名回退依据（取值 ecs / vefaas 时回退到 www.coze.cn，否则 code.coze.cn），不再覆盖按类型决定的链接。

配置管理概要

• coze config get <keys...> — 获取配置值
• coze config set <key> <value> — 设置配置值
• coze config delete <keys...> — 删除配置值
• coze config list — 列出所有配置

详细用法参见各业务模块 reference 文档中的配置相关章节。

安全规则

• 禁止输出密钥（token、API Key 等）到终端明文。
• 写入/删除操作前必须确认用户意图。
• 用 --dry-run 预览危险请求（如适用）。

代理配置

如果需要通过代理访问 Coze API：

export HTTPS_PROXY=http://your-proxy:8080
export HTTP_PROXY=http://your-proxy:8080

CLI 会自动识别并使用配置的代理。

升级与补全

升级 CLI

CLI 默认开启后台自动升级（auto 模式）：检查走本地缓存零阻塞，发现新版后台静默安装、下次启动生效，通常无需手动干预。也可随时手动触发：

coze upgrade          # 升级到最新版本
coze upgrade --force  # 强制升级（即使已是最新）
coze upgrade --tag beta  # 升级到指定渠道

升级策略与渠道用 coze config set 调整：

coze config set upgrade.mode notify    # 仅提示，不自动安装
coze config set upgrade.mode off       # 完全关闭升级检查
coze config set upgrade.channel beta   # 切换升级渠道（npm dist-tag）

CI 环境、dev/本地构建版本、设置 COZE_CLI_NO_UPDATE_NOTIFIER 时自动跳过升级检查；版本检查每 4h 最多联网一次，后台升级失败后 10min 内不重试。

Shell 自动补全

coze completion --setup    # 安装补全脚本
coze completion --cleanup   # 移除补全脚本

支持的 Shell：bash, zsh, fish, powershell。

退出码参考

Agent 在判断命令执行结果时，应根据退出码判断：

退出码	名称	含义
0	SUCCESS	成功
1	FAILURE	一般失败（包含所有业务错误：E3xxx 资源类 / E4xxx 配额类 / E5xxx 服务端类，退出码均为 1）
2	AUTH_ERROR	认证/授权错误（E2xxx，含 PERMISSION_DENIED（E2003）权限不足）
4	INPUT_ERROR	输入参数错误（E1xxx）

退出码只有以上 4 个（源码 ExitCode），映射规则：E1xxx → 4、E2xxx → 2、其余（含 E3xxx/E4xxx/E5xxx）→ 1。具体业务错误需解析 JSON 输出中的错误码（code 字段），不要依赖退出码细分。

退出码处理建议

• 退出码 2：认证类先执行 coze auth login 重新登录；若 JSON 错误码为 E2003（PERMISSION_DENIED），按"组织与空间上下文"章节的修正顺序排查。
• 退出码 4：检查参数拼写和格式。
• 退出码 1：解析 JSON 输出中的具体错误码（E3xxx/E4xxx/E5xxx）定位原因；E5xxx 网络/服务端类可重试一次。

业务模块导航

模块	触发场景	入口
coze-code	创建项目、发送需求、部署应用、环境变量/域名/技能管理	coze code *
coze-claw	Claw Session 对话、回复监听、后台 progress、文件/PPT/播客产物	coze session *
coze-generate	生成图片、语音合成(TTS)、视频生成	coze generate *
coze-file	上传本地文件获取在线访问地址	coze file upload

典型错误速查（基础类）

错误 1：用户要求用 Coze CLI，但 agent 改用别的 TTS

• 问题：偏离用户指令，且掩盖了 Coze CLI 实际可用路径。
• 修正：先补上 --output-path，完整跑完 Coze CLI 生成与上传闭环。

错误 2：OAuth 登录卡死或用户来不及授权

• 问题：直接后台执行 coze auth login 后继续发起后续任务，导致后续任务因未授权而全部失败；或前台阻塞等待导致 Agent 卡死；或使用 wait 在后台子 shell 中跨进程等待导致失败。
• 修正：
  1. 用 bash -c 包装命令，让进程自己记录退出码到文件。
  2. 轮询获取授权链接，拿到后立即返回给用户。
  3. 轮询检查退出码文件，判断本次授权结果（0=成功，非0=失败）。

错误 3：未使用 --format json 导致输出无法解析

• 问题：Agent 需要从输出中提取 projectId、taskId 等结构化数据，但默认 text 格式不方便解析。
• 修正：Agent 场景下始终加 --format json，然后按 JSON 解析输出。

错误 4：忽视退出码直接认为命令成功

• 问题：命令可能返回非零退出码表示失败，但 Agent 只看了 stdout 输出。
• 修正：始终检查命令退出码，非零时根据退出码参考表排查问题。