google-sheets

Google Sheets 写入

每当你需要将结构化数据写入现有电子表格时，都使用此技能。

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 已在 https://app.hyperfx.ai/apps 启用 Google Sheets 集成。

如何运行此技能中的工具

此技能中的每个工具都使用其规范名称。使用你的界面提供的调用方式运行：

界面	查找工具	运行工具
MCP 客户端（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>")，然后运行 describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>"，然后运行 hyperai describe <name>	hyperai call <name> --json '{...}'

如果找不到工具，说明其集成尚未连接或未在工作区启用：请停止操作，并告知用户需要连接哪个集成。

核心规则

绝不要仅凭猜测的列字母向 Google Sheets 写入数据。

始终：

1. 检查工作簿和目标工作表
2. 找到实际的标题行
3. 按标题名称映射字段
4. 验证目标范围
5. 写入数据
6. 读取部分行，确认数据对齐

需要避免的关键故障

• 不要假设第 1 行就是真正的标题行。
• 不要假设列 A 是第一个业务／数据列。
• 不要将 Total、备注、公式、合并标签或间隔列等辅助单元格当作真正的标题。
• 未检查现有数据和布局前，不要覆盖较大的范围。
• 读取回写入的单元格前，不要声称操作成功。

必需工作流

第 1 步：检查工作簿结构

从以下工具开始：

• google_sheets_get
• 如有需要，使用 google_sheets_worksheets_list

确认：

• 工作表标题
• 行数／列数
• 是否有多个候选标签页

第 2 步：读取足够的上下文以找到真正的标题

结构未知时，读取不止一行。

典型模式：

• google_sheets_values_get(..., range="Sheet1!A1:Z5")

查找：

• 真正的列标签
• 真正表格前的辅助列
• 标题行、总计、公式、空白分隔行

如果第一行包含 Total、Notes 或其他非记录元数据等标签，不要仅以该行为依据确定写入范围。

第 3 步：建立标题映射

根据实际工作表标题名称映射源字段，不要凭记忆。

示例：

• 源字段 business_name -> 工作表标题 Business Name
• 源字段 contact_email -> 工作表标题 Owner (s) Email

如果缺少必需标题或标题存在歧义，请停止并询问用户，不要猜测。

第 4 步：选择最安全的写入策略

使用：

• google_sheets_values_update 写入一个已验证的连续范围
• google_sheets_values_batch_update 写入多个已验证的范围

优先使用较窄的写入范围，而不是大范围覆盖。

如果要向具有固定列的现有表格追加记录，请先根据标题映射计算准确的目标列。

写入规则

• 只写入已明确映射的列。
• 保持无关列不变。
• 如果工作表在表格前包含辅助列，请从实际映射到的列开始写入，不要从列 A 开始。
• 如果某字段有意留空，只在已验证的对应列中写入空值。
• 除非用户明确要求使用公式或 Sheets 解析行为，否则使用 RAW。

必须验证

写入后立即：

1. 读取回写入的准确范围
2. 检查至少 2-3 个示例行
3. 确认每个字段都位于预期标题下

如果读回的数据未对齐，请承认问题，并在报告成功前修正。

推荐工具模式

1. google_sheets_get
2. 在 A1:Z5 等用于发现标题的范围内调用 google_sheets_values_get
3. 可选：使用 google_sheets_values_batch_get 读取现有数据和目标区域
4. 调用 google_sheets_values_update 或 google_sheets_values_batch_update
5. 在写入范围内调用 google_sheets_values_get 进行验证

示例思维方式

不佳：

• “我在开头附近看到了 Business Name，所以会写入 A2:F51。”

良好：

• “第一行可见内容中，A 列包含 Total: 7，而 Business Name 实际位于 B 列，因此我会将写入范围从 B 列开始映射，并在写入后进行验证。”