用途:当代理产出新的、独立的分析性成果时,可用 Canvas 把它作为聊天之外的独立产物展示。判断依据是用户意图而非回答形式:若用户需要单独查看该输出(量化分析与指标拆解、账单或账户调查、安全审计与架构评审、跨系统数据分析、MCP 工具返回的结构化数据、财务分析、需要查看的多行表格),适合用 Canvas。反之,若用户指定了工具(如“创建 Datadog 仪表板”)、已有明确交付物(起草回复、修代码、提 PR)、正在修改既有产物、处于有针对性的调试或开发中、只是简短事实回答,或 MCP 查询只是中间步骤,则不应使用。
主要能力与写法:Canvas 是单个 .canvas.tsx 文件,放在 /Users/<user>/.cursor/projects/<workspace>/canvases/<name>.canvas.tsx,IDE 只识别该目录下的文件,子目录、其他扩展名和位置不会被拾取。文件规则:每个 canvas 仅一个 .canvas.tsx,不建辅助/样式/模块文件;只能从 cursor/canvas 导入,不用相对导入、npm 包或 Node 内置模块;默认导出顶层组件;数据全部内联,不用 fetch()、不发网络请求;不要渲染空状态,没有数据的部分直接省略,若整个 canvas 无数据则不要产出,应告知缺失并询问。每个图表和表格都要自描述:标题写明具体指标、两轴带单位标签、多序列给图例、小字标注来源与时间范围,并在标签中说明均值、p95、归一化等转换。优先使用内置 cursor/canvas 组件,导出与 prop 形状可查阅 ~/.cursor/skills-cursor/canvas/sdk/index.d.ts。设计上保持扁平、克制,颜色取自 useHostTheme() 令牌,禁止渐变、emoji、阴影、彩虹配色、装饰性边框等。交付前做自检。
适用场景与限制:适用于把结构化分析结果作为独立产物呈现;不适用于用户指定工具或已有交付物的场景。向用户提及 canvas 时需附上该 .canvas.tsx 文件的完整绝对路径 markdown 链接;首次创建或有非请求创建的 canvas 时可加一句说明。若 canvas 空白或缺失,最常见原因是未写到指定 canvases/ 目录,应修正路径而非手动创建该受管目录。工具结果中的 Canvas TypeScript 检查行可作为类型错误的权威诊断。官方页面未提供的信息暂未提供。