Skip to Content
Calicat CLI 及 Skill

Calicat CLI 及 Skill 安装使用指南

📖 简介

Calicat CLI 是一个本地命令行工具，能够协助 AI 助理（如 Codex、Claude Code 等）直接获取并操作您的 Calicat 原型设计、画布页面结构、需求卡片（PRD）和交互设计等数据。

为了让 AI 助理能够高效、正确地与本地 Calicat CLI 进行协作，推荐在项目中安装 Calicat Skill（calicat-cli-operator）。该 Skill 是一套 AI 技能包，专门用于指导 AI 自动运行 Calicat CLI 命令，实现渐进式的数据解析与开发辅助。

Calicat CLI 与 Calicat MCP Server 本质上都是相同的能力，只是相比之下 CLI 更适合 Agents 高效使用。

🚀 推荐安装方式（一键 AI 装配与测试）

为了获得最流畅的开发体验，推荐直接向支持终端命令执行的 AI 助理（如 Claude Code、Codex 或 Antigravity 等）发送一个完整的引导 Prompt，让 AI 自动完成 Skill 安装、CLI 下载、环境初始化与连通性测试。

一键引导 Prompt

复制以下指令并发送给您的 AI 助理(注意：请在发送前将链接替换为您真实的 Calicat 文件或图层链接)

请使用 `npx skills add calicatcn/calicat-agent-skills --skill calicat-cli-operator` 帮我自动安装 Skill 
并根据其指引下载安装配置 Calicat CLI 
基于这个文件进行测试：`{补充你的测试文件链接}`

🛠️ Calicat Skill 简介与配置

Calicat Skill 是什么

Calicat Skill (calicat-cli-operator) 是为 AI 助手定制的技能引导。AI 在接收到 Calicat 相关任务时会自动加载该技能，从而指导 AI 如何在本地调用 Calicat CLI，以最佳实践和最安全的方式完成以下操作：

  • 解析设计链接：准确识别并提取设计链接中的 file_id、canvas_id 以及被选中的 selected_layer_id。
  • 渐进式获取结构：以分步和按需加载的方式，渐进式获取画布、页面和图层的结构，避免一次性加载过大 JSON 导致上下文（Token）溢出。
  • 读取需求与交互：指导 AI 精准抓取对应图层或文件的 PRD 需求卡片内容以及交互设计数据。
  • 维护 Calicat CLI：在必要时引导 AI 检查本地 Calicat CLI 版本、更新 CLI 或引导用户安装客户端。

Skill 手动安装与配置方法

根据您的开发工具和需求，可以选择以下几种方式手动配置该 Skill：

  • 为 Trae CN 全局配置

    • 在终端运行：npx skills add calicatcn/calicat-agent-skills --skill calicat-cli-operator -g -a trae-cn -y

  • 为 Qoder CN 全局配置

    • 在终端运行：npx skills add calicatcn/calicat-agent-skills --skill calicat-cli-operator -g -a qoder-cn -y

  • 为 Codex 全局配置

    • 在终端运行：npx skills add calicatcn/calicat-agent-skills --skill calicat-cli-operator -g -a codex -y

  • 为 Claude Code 全局配置

    • 在终端运行：npx skills add calicatcn/calicat-agent-skills --skill calicat-cli-operator -g -a claude-code -y

  • 在当前项目本地配置

    • 在项目根目录运行：npx skills add calicatcn/calicat-agent-skills --skill calicat-cli-operator

  • 从本地 Skill 源码仓库进行开发调试安装

    • 在本地开发调试时，如果您已克隆了技能仓库，可以运行：npx skills add ./calicat-agent-skills --skill calicat-cli-operator

命令行参数说明

在安装 Skill 时，可以使用以下关键参数进行配置：

  • -g / --global

    • 说明：表示全局安装。启用后，Skill 会被安装到 AI 助理的全局配置路径中，使您在任何项目目录下均可使用。若不指定此参数，Skill 将默认安装在当前运行命令的项目根目录下。

  • -a / --agent

    • 说明：指定目标 AI 客户端（Agent）类型。skills 工具需要根据不同客户端的配置目录和格式进行写入。目前 skills 支持为 60 多种 Agents 添加 Skill。
    • 常见取值：
      • trae-cn：Trae (国内版)
      • qoder-cn：Qoder (国内版)
      • codex：Cursor / Windsurf / VSCode 等使用的 Codex
      • claude-code：Anthropic 官方命令行工具 Claude Code
    • 更多客户端：关于支持的全部 Agent 列表和具体参数，请参考 Skills 官方支持的 Agent 列表 。

  • -y / --yes

    • 说明：自动确认所有交互提示，跳过确认步骤，直接开始安装。

💻 Calicat CLI 手动安装与更新

如果您希望手动安装或管理 CLI 客户端，可以参考以下操作：

CLI 安装命令

根据您的操作系统，在本地终端中运行对应的安装脚本：

  • macOS / Linux
curl -fsSL https://www.calicat.cn/cli/install.sh | bash
  • Windows (PowerShell)
powershell -ExecutionPolicy Bypass -c "irm https://www.calicat.cn/cli/install.ps1 | iex"

CLI 更新方法

Calicat CLI 在执行 login、status、tools-list 等常用命令时，会每 24 小时在后台检查一次新版本并进行提示。您也可以使用以下命令进行管理：

  • 手动检查更新

    • calicat update --check

  • 执行版本更新

    • calicat update
    • (提示：在 Windows 系统上更新时会弹出独立的更新窗口显示进度，安装完成后建议重启终端以生效)

CLI 卸载方法

如需清理或彻底卸载 CLI，请在终端中运行以下命令：

  • macOS / Linux 卸载

    • rm -f ~/.local/bin/calicat
    • rm -rf ~/.calicat-cli

  • Windows (PowerShell) 卸载

    • Remove-Item "$HOME\\.calicat-cli" -Recurse -Force
    • Remove-Item "$HOME\\.calicat-cli\\bin\\calicat.exe" -Force -ErrorAction SilentlyContinue

  • 仅清除登录状态（保留客户端）

    • calicat logout

⚙️ Calicat CLI 常用命令与使用流程

在本地终端安装并配置好 Calicat CLI 后，其核心的使用步骤和常用命令如下：

基础管理命令

  • 登录 Calicat 账号

    • calicat login

  • 检查当前登录状态与 CLI 版本

    • calicat status

  • 列出当前支持的所有工具接口

    • calicat tools-list

数据读取与交互命令

通常情况下，AI 助理在加载 Skill 后会自动调用以下底层接口进行数据交互，无需您手动运行。如果需要手动调试或验证，可以使用以下命令：

  • 获取画布列表

    • calicat tools-call --name get_canvas_list --args '{"file_id":"您的文件ID"}'

  • 获取画布中的页面列表

    • calicat tools-call --name get_design_page_list --args '{"file_id":"您的文件ID","canvas_id":"画布ID"}'

  • 获取图层元数据（轻量骨架结构）

    • calicat tools-call --name get_meta_data --args '{"file_id":"您的文件ID","selected_layer_id":"图层ID"}'

  • 获取图层详细设计数据（较大 JSON）

    • calicat tools-call --name get_design_data --args '{"file_id":"您的文件ID","selected_layer_id":"图层ID"}'

  • 获取交互设计数据

    • calicat tools-call --name get_interaction_design_data --args '{"file_id":"您的文件ID","selected_layer_id":"图层ID"}'

  • 获取 PRD 需求卡片列表

    • calicat tools-call --name get_prd_list --args '{"file_id":"您的文件ID"}'

  • 读取 PRD 需求卡片完整内容

    • calicat tools-call --name get_prd_full_content --args '{"file_id":"您的文件ID","prd_id":"需求ID"}'

💡 AI 使用 CLI 的最佳实践

为了在与 AI 助理交互时获得最佳的效果，并避免超出上下文 Token 限制，建议引导 AI 遵循以下开发原则：

  • 渐进式读取数据

    • AI 应当先通过 get_meta_data 获取图层骨架元数据。在确认目标图层无误后，再通过 get_design_data 拉取详细的设计 JSON。

  • 分批处理页面

    • 针对整个画布或多页面的前端代码生成任务， AI 应当分批次（默认每次处理 1 个页面）逐步拉取，绝不建议一次性加载整个画布下所有页面的完整设计数据。

  • 合理定位画布

    • 当用户的设计链接中缺少 canvas_id 时，AI 应当先调用 get_canvas_list 获取所有画布列表，通过比对名称或活跃状态定位到正确的画布，避免盲目猜测。
MCP Server 配置指引画布操作