composing-grid-canvases

组合网格画布

网格画布是一种组合，而非应用：它由一组放置项组成，每个放置项都会渲染一个组件画布（一种可复用的小部件，拥有自己的源代码、构建流程和放置契约）。用户的主页画布是其个人频道中的普通网格画布。布局以数据形式保存——发布或修改布局后会立即生效，无需构建。

三种画布共用同一生命周期：

• freeform — 独立应用（由 building-canvases 技能负责）。
• component — 可复用的小部件。源代码和构建流程与 freeform 相同，另有放置契约。可见性由其频道决定：个人频道 = 私有，团队频道 = 共享。
• grid — 由引用组件的放置项组成的布局。没有文件源代码；仅包含布局。

解析步骤：配置、分叉、构建

当网格中的某个放置项需要内容（“在这里放一个天气小部件”“放一个我的任务看板”）时，请按以下顺序处理——放置现有组件优于重复编写：

1. 搜索商店：使用 canvas-list，指定 kind=component 和 search=<what the widget shows>。当 component_meta 和 published_build_id 均已设置时，组件即可放置。如果其 configSchema 能满足请求（“里斯本的天气” → 使用现有天气组件，并设置 config: {"location": "Lisbon"}），则直接放置并配置——无需编写代码。
2. 分叉：如果某个组件很接近需求，但其配置无法满足要求，则读取其源代码（canvas-source-retrieve），创建一个新组件（使用 kind=component 调用 canvas-create），进行修改并发布。在新组件的描述中说明与原组件的区别。
3. 新建：如果没有合适的组件，则新建——请参阅下文“构建组件”。

新组件会创建在你创建它时所在的频道。除非用户要求扩大共享范围，否则请在网格所在的同一频道中创建组件。

构建组件

组件的编写方式与自由画布完全相同——加载 building-react-quill-canvases（或 building-html-canvases），以及 querying-canvas-data 和 validating-and-publishing-canvases—— 再额外遵循三项要求。展示 PostHog 数据的组件遵循与任何画布相同的可验证性规则：由洞察支持的图表需链接到已保存的洞察；即席查询需公开实际运行的精确查询（参见 querying-canvas-data 中的“可验证性”）。 请从 references/component-example.md 中完整且可构建的项目开始；其封装结构、放置约定、能力声明和防御式 ph.state 访问都是即兴发挥时容易出错的部分。

• 使用 kind=component 创建，并编写适合商店搜索的 description：说明小组件展示什么，以及其配置控制什么。用户以后会通过这段文字找到它。

• 在项目顶层的 component 键中声明放置约定：

  {
    "component": {
      "size": { "defaultW": 2, "defaultH": 1, "minW": 1, "minH": 1, "maxW": 4 },
      "configSchema": {
        "type": "object",
        "properties": { "location": { "type": "string", "description": "City to show weather for" } }
      }
    }
  }
  

  尺寸以网格单元为单位（宽度为 1–12，高度为 1–40）；minW <= defaultW <= maxW。此范围仅供参考：用户可以将放置项调整为任意大小，因此它用于确定默认值和警告，而不是拒绝放置。配置架构词汇表为允许列表——type、title、description、default、properties、required、 additionalProperties、items、enum、const、minimum、maximum、minLength、maxLength、 minItems、maxItems、format。不允许使用 $ref 和 pattern——验证会拒绝它们。

• 采用响应式设计。 为组件根元素设置 min-h-screen，使其填满放置项 iframe 的视口，并在内容需要时继续向下延伸。 根据用户拖动后的任意尺寸调整布局：2×1 的放置项应是便于快速浏览的磁贴；6×4 的放置项则应是完整的应用界面。 不要在根元素上使用 h-screen：固定的视口高度会限制弹性列，导致较高的子元素收缩并被裁切，而不是滚动。 根元素也不要使用 h-full：已发布组件的产物外壳不会为其 html、body 和 #root 元素指定明确高度，因此 height: 100% 会收缩到内容高度。 确保在 minW×minH 下也能正常显示，并将 config 视为每个放置项唯一的输入。

像构建任何画布一样，发布并等待构建完成——没有就绪构建的组件无法在网格中上线。

组合完整画布

对于完整画布的需求（“一个概览我进行中工作的主页画布”），通常需要多个小组件，而不是一个。 先规划完整的小组件集合——每个关注点对应一个放置项——然后使用上述阶梯逐一处理。 将它们一起排布：不要重叠，尺寸要匹配各小组件展示的内容，并有意填满网格，而不是把磁贴散落在角落。 批量写入布局（初始布局只发布一次，之后再做有针对性的补丁），不要为每个小组件单独写入；最后确保每个放置项都已上线或失败——绝不能处于生成中状态。

画布评论

用户会在画布上通过评论串留下反馈。 请先运行 exec search ^canvas-comments-(list|retrieve)$。 如果这两个工具都存在，请在修改画布前后用它们列出评论串，并处理尚未解决的评论——指出故障小组件的评论就是修复任务的说明。 这些工具会返回画布上的所有评论串，包括没有关联任务的评论串。如果缺少其中任一工具，请按照 working-with-task-comments 中的说明使用任务评论工具。

编辑网格

循环为读取 → 补丁，严格按照 validating-and-publishing-canvases 中对源发布的说明进行保护——用 canvas-layout-get 替代 canvas-source-retrieve，并使用 canvas-layout-patch（精细操作，必须提供保护）或 canvas-layout-publish（完整文档，用于初始布局或全面重构）进行写入。遇到 409 时，重新读取布局、重新应用更改，然后再次提交补丁。

操作：

• add_placement — 添加新框：{id, status, x, y, w, h, ...}。放置项不得重叠，也不得超出 grid.columns。
• update_placement — 将 changes 合并到具有 id 的放置项中。填充绘制好的框时，使用 {"op": "update_placement", "id": "p1", "changes": {"status": "live", "component": "<component canvas id>", "config": {...}}}。
• remove_placement、set_grid。

放置项的生命周期

放置项的 status 决定渲染器显示什么：

• pending — 用户画好了框，但尚未描述它（或提示词仍等待分派）。
• generating — Agent 任务正在填充该框；generationTaskId 关联任务，prompt 记录请求。开始处理任务中的放置项时，应设置此状态。
• live — 在 version 处渲染其 component（默认为 "latest"；也允许固定的版本 ID）。要求该组件已发布，且执行操作的用户可见。
• failed — 生成失败；保留 prompt，以便用户重试或重新描述。

当任务要求你填充某个放置项时，该项的提示词和框的尺寸就是你的任务说明：遵守绘制的 w×h，并保留放置项的 prompt 原样不动，以记录来源。

你会遇到的验证错误

布局发布会以原子方式验证；每个错误都会指出相应的放置项。常见错误：

• component_not_found — ID 错误、组件已删除、它不是组件，或执行操作的用户不可见（他人个人频道中的组件不可放置）。
• component_not_published — 该组件从未发布过放置契约。
• placement_config_invalid — config 与组件的 configSchema 不匹配。
• placement_size_out_of_contract — 警告而非错误：框的 w/h 超出组件建议范围。发布仍会成功；组件必须能够响应式渲染。
• placements_overlap / invalid_placement — 几何问题；应修正坐标，而不是移除其他小组件。

回复结尾处应使用画布工具返回的 url 字段链接到网格画布——切勿自行构造画布 URL。