calicat-cli-operator

Calicat CLI 设计数据

当用户需要获取 Calicat 文件中的数据，且本地 calicat CLI 是执行路径时，使用此技能。

阅读此文件以了解

• 技能触发条件
• 链接形式检测
• 渐进式检索规则
• 根据用户意图进行任务路由

仅在需要时阅读其他参考资料

• 如果任务需要确认 CLI 是否已安装、检查其版本、更新 CLI，或告知其他 Agent／用户如何安装或更新 CLI，请阅读 references/cli-lifecycle.md。

链接解析

Calicat 设计链接通常有以下三种形式。

仅文件

https://www.calicat.cn/design/2066708151519244288

解析为：

• file_id = 2066708151519244288
• canvas_id = unknown
• selected_layer_id = unknown

含义：

• 用户指定了文件，但没有指定具体画布或图层。
• 如果任务针对特定画布，请先调用 get_canvas_list。

画布链接

https://www.calicat.cn/design/2066708151519244288?node-id=2066708151531827200&node-type=canvas

解析为：

• file_id = 2066708151519244288
• canvas_id = 2066708151531827200
• selected_layer_id = unknown

含义：

• 此处的 node-id 是画布 ID。
• 不要将此 node-id 当作图层 ID 传给 get_meta_data 或 get_design_data。
• 对于整个画布的操作，请直接使用该 canvas_id 调用 get_design_page_list。

图层链接

https://www.calicat.cn/design/2066708151519244288?node-id=21c84811-08c9-42f6-9dc7-82c6992a6ae8&node-type=group

解析为：

• file_id = 2066708151519244288
• selected_layer_id = 21c84811-08c9-42f6-9dc7-82c6992a6ae8
• canvas_id = unknown

含义：

• 此处的 node-id 是图层 ID。
• node-type=group 强烈表明这是类似图层的对象，而不是画布。
• 从 get_meta_data 开始，然后再决定是否读取完整设计数据。

解析规则

• 始终先从 /design/{file_id} 提取 file_id。
• 如果 node-type=canvas，将 node-id 视为 canvas_id。
• 如果存在 node-type 且其值不是 canvas，将 node-id 视为 selected_layer_id。
• 如果存在 node-id，但缺少 node-type，不要立即猜测：
  • 如果 ID 看起来像 UUID，通常是图层 ID
  • 如果 ID 是较长的数字字符串，可能是画布 ID
  • 但如果后续步骤取决于此判断，请选择最轻量且安全的 API 路径进行验证

安全解析策略

当链接含义不明确时：

• 解析 file_id。
• 检查 node-type。
• 如果仍不明确，优先发现画布，再进行大量读取。
• 不要对很可能是画布的链接强行采用图层工作流。

核心规则

优先采用渐进式检索。

大型 get_design_data 负载很容易耗尽上下文。应从能够回答下一步决策的最轻量结构端点开始：

• get_canvas_list
• get_design_page_list
• get_meta_data
• get_design_data
• get_interaction_design_data

先将其视为目录，再获取完整内容。

API 选择：get_meta_data 与 get_design_data

• get_meta_data：以 XML 格式表示层级结构，并检索简化的页面／图层结构（图层名称、ID、位置、尺寸）。用于快速检查图层轮廓、梳理画布结构，或定位特定嵌套元素，而无需加载大量样式数据。
• get_design_data：检索完整布局和深层 CSS／样式值。用于生成精确代码或进行样式分析。
• 直接获取规则：如果目标页面图层 ID 已确定（例如通过 get_design_page_list 获取），且目标是为该页面实现前端代码，则不要先调用 get_meta_data。直接对页面 ID 调用 get_design_data。

负载存储与上下文管理

get_design_data 返回的大型负载很容易超出大模型的上下文窗口。直接将庞大的 JSON 负载输出到终端会污染上下文，导致响应变慢、Token 成本升高，还可能造成 Token 溢出。

为了保持大模型上下文整洁并优化性能：

• 将输出重定向到文件：始终将大型输出负载重定向到工作区中的临时文件（例如 scratch/page_design.json 或 temp_design.json）。
  • Unix Bash/Zsh：

    calicat tools-call --name get_design_data --args '{"file_id":"123","selected_layer_id":"xyz"}' > scratch/page_design.json
    

  • PowerShell：

    $json = '{\"file_id\":\"123\",\"selected_layer_id\":\"xyz\"}'
    calicat tools-call --name get_design_data --args $json > scratch/page_design.json
    

• 严格遵循数据驱动的实现原则（不猜测、不臆造）：
  • 不要基于不完整的设计数据或占位内容开始实现完整的前端代码。代码必须严格对应实际页面设计数据和用户需求。猜测会导致设计与代码不匹配。
  • 按页面逐一实现设计布局。单个页面的 design_data 通常足够小，不会超出上下文限制。也可以先找到目标模块化组件或容器，提取其特定节点数据，再开发该部分。
• 处理超大型 JSON 文件（拆分以防 Harness 截断）：
  • 如果输出文件特别大，不要尝试在单次交互中读取或显示整个文件。直接读取超大型文件会触发 Agent Harness 截断。
  • 编写简单的解析脚本（例如使用 Python 或 NodeJS），将超大型 JSON 文件拆分成更小、结构清晰的文件（例如按单个组件、屏幕区段或布局树深度拆分），并保存到 scratch/ 下。
  • 逐个处理这些拆分后的小型 JSON 文件并据此编写代码。
• 渐进式、有针对性地读取：保存文件后，不要一次性将整个文件读入上下文。使用标准工作区文件查看工具并限制行数（例如使用带特定范围偏移量的 view_file），或编写小型脚本（例如 Python/JS）解析并筛选出编码所需的特定 UI 节点详情。

最小 CLI 接口

列出工具：

calicat tools-list

Windows Shell JSON 参数转义

如果执行环境是 Windows（PowerShell 或 CMD），将原始 JSON 对象放在单引号内传递可能会导致参数解析问题（例如引号被移除）。请遵循以下转义规则：

• PowerShell：将 JSON 字符串声明为变量，使用反斜杠 (\) 转义内部的双引号，然后传递该变量。

  $json = '{\"file_id\":\"2045068433773035520\",\"selected_layer_id\":\"e449643f-0bc3-4b75-9fa4-9db5c0b0e402\"}'
  calicat tools-call --name get_meta_data --args $json
  

• CMD：将整个参数对象用双引号括起来，并使用反斜杠 (\") 转义内部的双引号。

  calicat tools-call --name get_meta_data --args "{\"file_id\":\"2045068433773035520\",\"selected_layer_id\":\"e449643f-0bc3-4b75-9fa4-9db5c0b0e402\"}"
  

CLI 命令示例（类 Unix Bash/Zsh）

Canvas 列表：

calicat tools-call --name get_canvas_list --args '{"file_id":"123456"}'

页面列表：

calicat tools-call --name get_design_page_list --args '{"file_id":"123456","canvas_id":"canvas-id"}'

图层元数据：

calicat tools-call --name get_meta_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

图层设计数据：

calicat tools-call --name get_design_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

交互设计：

calicat tools-call --name get_interaction_design_data --args '{"file_id":"123456","selected_layer_id":"layer-uuid"}'

PRD 列表：

calicat tools-call --name get_prd_list --args '{"file_id":"123456"}'

PRD 完整内容：

calicat tools-call --name get_prd_full_content --args '{"file_id":"123456","prd_id":"prd-id"}'

按任务划分的推荐工作流

单图层设计分析

当用户提供设计 URL 并询问某个图层的设计或交互数据时使用。

工作流：

• 先解析链接结构。
• 确认链接实际指向图层，而不是画布。
• 调用 get_meta_data。
• 确认该图层看起来符合目标。
• 调用 get_design_data。
• 如果涉及交互，则调用 get_interaction_design_data。

画布级工作

在用户要求处理“这个画布”“当前画布”或画布内所有页面时使用。

工作流：

• 首先解析链接格式。
• 如果 URL 包含 node-id 和 node-type=canvas，则将 node-id 视为 canvas_id。
• 如果 URL 不包含 node-id（例如仅包含文件的链接），或 node-id 有歧义：
  • 调用 get_canvas_list，获取该文件的所有画布列表。
  • 从列表中确定目标 canvas_id（请用户选择，或根据上下文／默认值推断）。
• 使用解析出的 canvas_id 调用 get_design_page_list，获取页面列表。
• 一次处理一个页面图层。
• 对于每个页面：
  • 如果目标是实现前端代码，直接使用页面 ID 调用 get_design_data（跳过 get_meta_data）。始终将输出重定向到临时 JSON 文件，以避免污染提示词上下文。
  • 否则，如果只需检查页面骨架轮廓或在决定要获取哪些内容之前定位特定组件图层，请先调用 get_meta_data。

获取需求卡片

在用户要求获取需求、PRD、摘要或需求卡片内容时使用。

工作流：

• 解析 file_id。
• 调用 get_prd_list。
• 按标题或摘要匹配。
• 调用 get_prd_full_content。

切勿先猜测 prd_id。

完整画布前端实现

在用户要求为“所有设计”“所有页面”或“整个画布”构建前端代码时使用。

工作流：

• 解析 file_id。
• 解析 canvas_id（如果 URL 不包含 node-id，先调用 get_canvas_list 列出所有画布并选择目标）。
• 使用解析出的 canvas_id 调用 get_design_page_list，获取页面列表。
• 一次处理一个页面图层。
• 对于每个页面，直接调用 get_design_data（始终将输出重定向到临时 JSON 文件，以避免污染提示词上下文），获取完整的样式详情，然后实现／总结代码。跳过 get_meta_data。
• 只有完成当前页面后，才能继续处理下一个页面。

不要一次性获取所有页面的设计数据。

默认批次大小：

• 每步 1 个页面
• 仅当负载明显较小时才处理 2 个页面

决策启发规则

如果用户说：

• “这个链接里的图层” 使用图层路径
• “这个链接里的画布” 使用画布路径
• “这个文件里的 PRD” 使用 file_id，然后调用 get_prd_list
• “这个画布里的所有页面” 解析 canvas_id，然后调用 get_design_page_list
• “把整个设计做成前端” 不要一次性获取所有内容；必须逐页获取

故障处理

如果数据访问失败：

• 运行 calicat status。
• 如果认证状态似乎已过期，运行 calicat logout，然后运行 calicat login。
• 重新检查解析出的 file_id、canvas_id 和 node-id。
• 如果任务依赖安装／更新／版本状态，请阅读 references/cli-lifecycle.md。

输出风格

向用户汇报时：

• 明确说明解析出的 ID
• 明确说明执行过哪些 CLI 调用
• 明确说明链接指向的是文件、画布还是图层
• 如果使用渐进式获取，说明这样做是为了避免一次性加载庞大的设计 JSON