stitch-sdk-bug-bash

Stitch SDK Bug Bash

此技能提供了一套框架和说明，帮助你使用真实 API 密钥查找 Stitch SDK 中的 bug。它将引导你探索标准功能边界情况，以及常规路径之外的棘手场景。

---

思路：对抗式探索

使用此技能时，不要只验证 SDK 是否正常工作，还要试着让它出错！

• 传入无效或临界参数。
• 尝试对已删除或过期的句柄执行操作。
• 尽可能模拟意外的 API 响应，或找出可能导致投影失败的边界情况。

---

覆盖范围

1. 根节点与初始化（Stitch）

• 零配置：验证存在 STITCH_API_KEY 时，无需显式配置即可使用单例。
• 无效配置：向 StitchToolClient 传入空 API 密钥或无效的基础 URL，并验证首次调用会因身份验证或连接问题而明确失败，而不是出现笼统的噪声错误。

2. 项目生命周期（Project）

• 句柄创建：验证 stitch.project('invalid-id') 不会抛出异常（延迟实例化），但对其进行首次调用时会安全地失败。
• 工厂方法与 API：验证通过工厂方法创建项目句柄不会触发 API 调用，但 project.listScreens() 等方法会触发调用。

3. 屏幕生命周期（Screen）

• 交接：验证 Project.generate() 返回的 Screen 实例能正确填充属性，无需再次获取数据。
• 投影中的空值安全：测试返回空数组或缺少可选字段的工具或场景。验证 SDK 句柄会将其处理为 undefined 或空数组，而不会因访问 null 属性而崩溃！

4. 设计系统（DesignSystem）

• 应用：创建一个设计系统，并将其应用于屏幕列表。验证列表为空或无效时，SDK 会妥善失败！
• 句柄：验证 project.designSystem('ds-id') 能正确接收 projectId，并将其注入 ds.apply(...) 等调用中。

---

棘手场景矩阵（标准功能边界情况）

场景	尝试操作	预期行为
过期句柄	创建一个屏幕，删除项目，然后尝试编辑该屏幕句柄。	返回明确的 API 错误，指出资源未找到，并包装在 StitchError 中。
空提示词	调用 project.generate('') 或传入仅包含空白字符的内容。	安全地拒绝请求或返回明确的 API 错误；代码生成过程中不会崩溃。
对 null 的投影	强制执行一次 API 调用，使其返回的响应缺少预期的投影字段（如果可以模拟或找到此类工具回退场景）。	SDK 应使用可选链（例如 raw?.prop），并返回 undefined，而不是抛出 TypeError: cannot read property of undefined。
超大数组	向 ds.apply() 传入数百个屏幕 ID。	检查是否能妥善处理负载限制，或给出明确的错误消息。

诊断规范

• 始终在 try/catch 中封装测试调用。
• 记录错误，并检查 error.code 或 error.name，以确认它是 StitchError 还是通用原始错误。
• 如果执行时抛出原始 TypeError 或出现“cannot read property of undefined”，这就是 SDK 投影逻辑中的高优先级 Bug！

---

测试模板：完整工作流 Bash

使用此模板运行快速的端到端 Bash 会话。

import { stitch } from "@google/stitch-sdk";

async function bash() {
  const apiKey = process.env.STITCH_API_KEY;
  if (!apiKey) throw new Error("STITCH_API_KEY is required");

  console.log("🚀 Starting Bug Bash...");

  let project;
  try {
    // 1. Create a fresh project
    project = await stitch.createProject({
      displayName: `Bug Bash ${new Date().toISOString()}`,
    });
    console.log(`✓ Created Project: ${project.id}`);

    // 2. Try to break generate with empty prompt
    try {
      await project.generate({ prompt: "" });
      console.log("✗ BUG: Generate with empty prompt should have failed!");
    } catch (e) {
      console.log("✓ Generate with empty prompt failed safely as expected.");
    }

    // 3. Create a design system
    const ds = await project.createDesignSystem({
      name: "Bash Style",
      variables: { primaryColor: "#ff0000" },
    });
    console.log(`✓ Created Design System: ${ds.id}`);

    // 4. List screens (should be empty)
    const screens = await project.listScreens();
    console.log(`✓ Listed screens: found ${screens.length}`);

    // 5. Apply design system to empty list
    try {
      await ds.apply({ selectedScreenIds: [] });
      console.log("✓ Applied design system to empty list (handled).");
    } catch (e) {
      console.log("✗ Did applying to empty list fail? Inspect error.");
    }
  } catch (error) {
    console.error("💥 Bash failed with error:", error);
  } finally {
    // 6. Cleanup
    if (project) {
      console.log(`🧹 Cleaning up project ${project.id}...`);
      // Assuming we have a deleteProject binding or we just leave it if not available
      // await project.delete();
    }
  }
}

bash();