snowman

snowman

使用 scripts/snowman.py 执行 Snowflake 查询，并暂存用户要求的变更，以便手动执行。其词法过滤器会拒绝写入语句和已知的副作用结构。它无法证明 UDF 或外部函数是否为只读。请使用最小权限连接和可信的读取函数。

加载项目上下文

从当前目录开始向上查找并加载 .snowman/context.md。如果文件不存在，请先按照引导流程操作。除使用 --connection <name> 进行引导发现外，查询都需要上下文。上下文就绪后，让包装器从中解析连接。

上下文记录项目架构和连接名称，不记录凭据。请将其纳入版本控制。数据库范围只是关注提示，并非访问限制。若用户的问题需要查询其他数据库，请照常查询。

执行查询

所有 SQL 查询都必须通过包装器执行：

python3 <skill-dir>/scripts/snowman.py "<SQL>"

<skill-dir> 是此技能的目录。每次调用只提交一条语句。包装器会在同一会话中追加 DESCRIBE RESULT，以获取列类型。它会应用所选上下文中的 default_warehouse。如果未设置，则使用指定连接的仓库配置。

标准输出只包含 CSV 数据，或使用 --json 时输出紧凑的 JSON 数组。类型、截断提示和产物路径会写入标准错误。解析时请分开处理这两个流。CSV 单元格可能包含换行符或以 # 开头的行。空 CSV 单元格表示 NULL，"" 表示空字符串，嵌套值则为紧凑 JSON。受预览限制影响时，空结果仍会在标准错误中保留可用的列名和类型，并在标准输出中输出 CSV 表头或 JSON []。

默认最多返回 50 行，每个单元格保留 200 个字符并附加截断标记，数据输出上限为 16,000 UTF-8 字节。使用 --max-rows、--max-cell 和 --max-output 修改这些限制。设为 0 可取消对应限制。JSON 会保留嵌套对象和数组；若内容被截断，单元格将变为缩短后的 JSON 文本。

任何被截断的结果都会将完整行和架构保存为 JSON。请根据标准错误中的 # full result: 路径，在本地检查所需字段，而不要重新运行查询或将整个文件加载到上下文中。解析或恢复结果时，请参阅输出详情。

处理失败

查看 BLOCKED: 后的原因。这说明查询执行前发生了拒绝，原因可能涉及 SQL、上下文或配置问题。修复设置问题，或重新组织经授权的读取操作。仅在用户提出要求时暂存变更。切勿绕过包装器来规避拒绝。如果 PATH 中缺少 snow，请先安装 Snowflake CLI，再重试。

查询处理失败后，请在本地检查报告的 # raw CLI stdout: 文件。该文件会保留收到的输出，以供恢复。不要自动重新运行。

查询需要网络访问。请使用环境允许的执行模式。如果诊断结果指出沙盒限制了网络访问，请通过其审批流程申请网络访问。仅凭 DNS 错误无法确定原因。

遇到身份验证失败时，请转达包装器给出的提示，并按照身份验证设置操作。包装器会将项目根目录及其上级目录中最近的 .env 传递给 snow。切勿载入或打印该文件、索要密钥或编辑连接凭据。

选择环境

如果存在 environments: 映射，查询将使用 default_env。用户要求使用其他环境时，请传入 --env <name>，并在更新中注明所选环境。选择仅对当前查询生效。单账户上下文使用 connection:，且不接受 --env。

在多环境项目中暂存变更时，必须明确指定 --env。如果用户没有说明变更的目标环境，请在暂存前询问。若目标环境已明确说明，则直接沿用，无需再次确认。

暂存请求的更改

当用户请求执行 DML 或 DDL 时，准备好 SQL 并将其暂存：

python3 <skill-dir>/scripts/snowman.py --stage "<SQL>" --name <purpose-slug>

对于多环境项目，添加所选的 --env。暂存需要上下文，且可接受多条语句。使用 kebab-case 为脚本命名，以体现其用途。包装器会在 .snowman/staged/ 下写入一个被 git 忽略的文件，并打印其路径和手动运行命令，其中包含连接信息和已配置的仓库。告知用户这两项信息，以及任何破坏性关键词警告。用户负责执行并清理脚本。Snowman 不会执行这些操作。

高效探索

• 从已知范围中最窄的部分着手。对于指定的表，检查该表。仅当数据库或架构名称缺失时，才去发现它们。
• 使用筛选条件、LIMIT 或 SAMPLE 限定探索性读取的范围。预览限制只会减少输出，不会降低查询成本。在生产环境中使用更小的样本和更严格的筛选条件。 在执行耗费较大的查询前，说明已配置的仓库；如果上下文中未配置仓库，则验证 CURRENT_WAREHOUSE()。
• 优先使用 SHOW TERSE，并通过 ->> SELECT "col" FROM $1 投影元数据。对于 rows 和 bytes，使用普通的 SHOW，因为 TERSE 会省略这些信息。如果 TERSE 未能缩减对象的输出，则显式投影列。
• 选择问题所需的列。仅在相关时调查顺带发现的异常，否则在回答中简要提及。
• 在调查过程中将相关查询放在一起执行。仅将范围广且彼此独立的工作交由他人处理，而不要逐个查询或逐张表委派。
• 说明第一个查询的目的；如果发现导致方向改变，则更新说明；回答时先给出发现，而不是直接倾倒行数据。

如果需要探索、分析概况、检验假设、调查或暂存示例，请加载 工作流。如果需要解释 SQL 拒绝执行的原因，请阅读防护措施详情。