区分自动连接与工具失败，始终关闭客户端

{
  "inputRows": [
    {
      "scenario": "read success",
      "expectClose": true
    },
    {
      "scenario": "tool invalid argument",
      "expectClose": true
    },
    {
      "scenario": "auth failure",
      "expectClose": true
    }
  ],
  "referenceRows": [
    {
      "location": "finally",
      "action": "await client.close()"
    },
    {
      "secretStorage": "environment only"
    },
    {
      "logFields": [
        "phase",
        "tool",
        "redactedError"
      ]
    }
  ],
  "invalidRows": [
    {
      "closeLocation": "success path only",
      "error": "exception skips cleanup"
    },
    {
      "logField": "apiKey",
      "error": "secret exposed"
    }
  ],
  "notes": [
    "全部输入为作者自制教学资料，不含真实客户或账号。",
    "referenceRows是校验基准，不是目标模型预测或识别结果；targetProduct=not_run。"
  ],
  "files": {
    "input.json": "[\n  {\n    \"scenario\": \"read success\",\n    \"expectClose\": true\n  },\n  {\n    \"scenario\": \"tool invalid argument\",\n    \"expectClose\": true\n  },\n  {\n    \"scenario\": \"auth failure\",\n    \"expectClose\": true\n  }\n]\n",
    "reference.json": "{\n  \"identity\": \"作者验收参考，非模型返回\",\n  \"rows\": [\n    {\n      \"location\": \"finally\",\n      \"action\": \"await client.close()\"\n    },\n    {\n      \"secretStorage\": \"environment only\"\n    },\n    {\n      \"logFields\": [\n        \"phase\",\n        \"tool\",\n        \"redactedError\"\n      ]\n    }\n  ]\n}\n",
    "invalid.json": "{\n  \"identity\": \"作者构造负例，非实际错误回包\",\n  \"rows\": [\n    {\n      \"closeLocation\": \"success path only\",\n      \"error\": \"exception skips cleanup\"\n    },\n    {\n      \"logField\": \"apiKey\",\n      \"error\": \"secret exposed\"\n    }\n  ]\n}\n",
    "case.md": "# Stitch SDK连接清理：区分自动连接与工具失败，始终关闭客户端\n\nStitch SDK连接清理用成功读取和失败工具两条路径验证生命周期。官方客户端会在首次调用时连接，但连接成功并不表示工具请求成功；两条路径都需要回收客户端。\n\n## 准备只读调用样例\n\n脚本只做listTools与一次读取，写清目标项目来自练习台账。\n\n密钥从环境变量读，不放在可下载的练习JSON里。\n\n## 构造客户端\n\n按官方SDK创建StitchToolClient，记录本地阶段。\n\n构造对象不等于已经完成网络认证。\n\n## 观察自动连接\n\n首次listTools或callTool触发自动连接，按实际返回记录阶段。\n\n无需为了演示无条件重复connect造成混乱。\n\n## 区分两种失败\n\n分别保留鉴权失败和工具参数失败的错误记录。\n\n前者没有成功进入工具执行，后者不能简单叫连接断开。\n\n## 用finally清理\n\n把await client.close()放在finally中，让成功与失败路径都执行。\n\n不要仅在正常结尾close，异常抛出会绕开它。\n\n## 限制重试范围\n\n读取失败可根据错误重试，写操作失败先核对是否已生效。\n\n本课不把未知写入结果当可无限重放的连接问题。\n\n## 交付生命周期日志\n\n只记录阶段、工具名和脱敏错误，检查没有密钥。\n\n本地假客户端测试只证明控制流，不能称目标网络连接通过。\n\n身份：输入与参考为作者材料；localCli有实测记录时仅证明对应CLI运行，目标云端与模型推理未执行。\n",
    "client.ts": "import {StitchToolClient} from \"@google/stitch-sdk\";\nconst key=process.env.STITCH_API_KEY;if(!key)throw new Error(\"Set STITCH_API_KEY\");\nconst client=new StitchToolClient({apiKey:key});\ntry{const tools=await client.listTools();console.log(tools);}finally{await client.close();}\n"
  }
}