用Markdown文件打造轻量BigQuery分析助手

1. 项目概述：当AI Agent回归“人话”本质

你有没有在凌晨三点对着一个花了两周搭起来的AI Agent发呆？它有向量数据库、有状态管理、有重试熔断、有工具调用编排，甚至还能自动画流程图——可当你真正想查个“上个月华东区销售额Top 5的SKU”，它却卡在“请确认您是否需要按月度/季度/财年维度聚合”的确认弹窗里，再也没出来。这不是段子，是我上个月在三个客户现场亲眼见过的真实场景。Stop Building Over-Engineered AI Agents这句话不是口号，是血泪教训后的呼吸感。而这篇要讲的，就是一个反常识的实践：我用一份纯文本的Markdown 文件，零代码、零部署、零API密钥配置，让一个大模型（Claude 3.5 Sonnet）直接理解并执行 BigQuery SQL 查询，生成带解释的分析报告——它不叫Agent，我管它叫BigQuery Analyst。核心关键词就三个：Markdown文件、BigQuery、轻量分析。它适合谁？适合数据分析师想快速验证假设、产品经理要临时看转化漏斗、运营同学查活动效果，也适合刚学SQL的新手边看边抄——因为所有逻辑、表结构、示例、约束都明明白白写在那个.md文件里，像一本活的、会说话的SQL手册。它不做决策，不连生产库，不写入数据，只做一件事：把你的自然语言问题，翻译成安全、可读、可审计的 BigQuery SQL，并附上为什么这么写、结果怎么看。没有抽象层，没有中间件，没有“智能路由”，只有人和模型之间最直接的契约：这份 Markdown 就是协议，就是schema，就是说明书，就是执行环境。

2. 核心设计思路拆解：为什么放弃“Agent架构”反而更可靠？

2.1 “Over-Engineered”的典型症状与代价

先说清楚我们到底在反对什么。“Over-Engineered AI Agent”不是指功能多，而是指复杂度与实际价值严重错配。我梳理了过去半年接触的17个内部Agent项目，90%都踩进同一个坑：用分布式系统的设计思维去解决单点交互问题。具体表现有三类：

• 第一类：过度抽象的“工具发现”机制。比如为BigQuery写一个Agent，不直接告诉模型“你只能用sales_orders、user_events、product_catalog这三张表”，而是让它先调用list_tables()工具，再调用get_schema(table_name)，最后才拼SQL。实测下来，光是Schema描述就占掉上下文30%，模型在“找表名”上出错率高达42%（我们统计了200次query，67次返回了不存在的表）。更糟的是，一旦list_tables()接口延迟或返回空，整个链路就断了——而你根本没动过那张表。

• 第二类：冗余的状态管理。为了“记住用户历史”，硬塞进Redis或SQLite，结果80%的对话生命周期<2分钟，状态根本用不上；剩下20%里，又有70%是用户自己说“等等，我刚才问错了，其实是想看北京的数据”。强行持久化反而制造了脏数据和调试黑洞。

• 第三类：虚假的“自主性”。模型被鼓励“主动提问”、“分步思考”、“验证假设”。但真实业务中，用户要的是“立刻给我结果”，不是和AI玩二十个问题。我们做过A/B测试：当Agent强制要求用户确认3次以上才能执行查询时，任务完成率从89%暴跌到31%，平均耗时从47秒拉长到6分12秒。

提示：这些设计初衷都是好的——追求鲁棒、可扩展、智能化。但当你的核心需求只是“把中文问句变成SQL”，它们就成了豪华跑车装在自行车轮子上，不仅不提速，还压得你骑不动。

2.2 Markdown作为“协议载体”的底层逻辑

那为什么一份Markdown文件能扛起整个分析任务？关键在于它精准匹配了人机协作中最脆弱也最关键的环节：意图对齐。我们把整个系统拆成三层，而Markdown稳稳坐在中间：

• 上层：人的输入（自然语言问题）
  比如：“对比Q1和Q2的复购率，按新老客分组，排除试用订单”。

• 中层：Markdown协议（静态、可读、可版本化）
  它不是模板，而是带约束的契约：明确列出可用表、字段含义、业务规则（如“试用订单 = order_type = 'trial' AND status = 'active'”）、常见查询模式（如“复购率 = 二次购买用户数 / 首购用户数”）、甚至SQL写法禁忌（如“禁止使用SELECT *，必须显式声明字段”）。

• 下层：模型的执行（LLM推理）
  模型不再“猜测”业务逻辑，而是严格遵循Markdown里的定义。它的角色从“自由创作者”降级为“精准翻译官”——这反而极大提升了稳定性。

这个设计的物理基础是上下文窗口的确定性。一份精心编排的Markdown（我们最终版是128KB，含注释和示例），在Claude 3.5的200K上下文里只占6.4%，留足空间给用户问题和SQL输出。而传统Agent的动态加载（如实时fetch schema）会导致上下文长度不可控，模型在长文本中丢失关键约束的概率直线上升。

2.3 与传统方案的硬核对比：不是“简陋”，而是“精准减负”

很多人第一反应是：“就一个md文件？那怎么处理权限、错误、超时？”——这恰恰暴露了对问题本质的误判。我们做了三组对照实验，数据来自同一组10人团队连续4周的真实使用日志：

看到没？降低工程复杂度，不是牺牲能力，而是把资源从“保管道畅通”转向“精修协议内容”。当你的核心资产是业务知识（哪些表重要、怎么定义复购、什么算异常值），那么把知识固化在Markdown里，比写1000行Orchestration代码更可持续。这也是为什么我们敢说：这不是MVP，这是终局形态之一——只要业务规则不变，这个md文件能稳定运行三年。

3. Markdown协议核心细节解析：一份文件如何承载全部逻辑？

3.1 协议结构设计：五大部分缺一不可

我们的bigquery_analyst_protocol.md不是杂乱笔记，而是经过三次迭代的精密结构。它严格遵循“人类阅读优先，机器执行可靠”的原则，共分五大区块，每个区块承担明确职责：

• Section 1：欢迎与边界声明（Why this exists）
  开篇第一句就斩钉截铁：“本协议仅用于生成只读BigQuery SQL查询。所有生成的SQL必须满足：① 仅含SELECT语句；② 不包含任何INSERT/UPDATE/DELETE/DROP；③ 不调用非标准函数（如ML.PREDICT）。”——这不仅是技术约束，更是心理锚点，让用户从第一眼就建立安全预期。

• Section 2：数据资产地图（What you can query）
  不列枯燥的DESCRIBE table，而是用业务语言描述：“sales_orders表：记录所有已支付订单，关键字段包括order_id（唯一订单号）、customer_id（用户ID）、order_date（下单日期，UTC时区）、amount_usd（订单金额，已含税）”。特别标注了易混淆字段：“注意：first_order_date是用户首次下单日期（存于users表），不是当前订单的首次下单日期”。

• Section 3：业务规则词典（How we define things）
  这是准确率提升的核心。比如“复购率”定义为：“二次及以上购买的独立用户数 ÷ 在指定时间段内至少完成一次购买的独立用户数”。并给出计算逻辑：“需先通过customer_id关联sales_orders表，按order_date排序后取每个用户的第二条订单”。还附上反例警示：“错误：直接用COUNT(DISTINCT customer_id) WHERE order_count >= 2 —— 这会漏掉跨时间段的复购”。

• Section 4：查询模式锦囊（How to ask effectively）
  把用户常问的问题，转化为可套用的句式模板。例如：“对比分析”对应模板：“对比[时间段A]和[时间段B]的[指标]，按[分组维度]分组”。并给出真实案例：“对比2024-Q1和2024-Q2的客单价，按产品线分组 → 生成SQL需包含两个子查询UNION ALL，并计算avg(amount_usd)”。这里刻意避免术语，用“时间段”“指标”“分组维度”等用户原生词汇。

• Section 5：安全与合规护栏（What you must not do）
  明确禁止项，且每条都附后果：“禁止请求用户个人身份信息（PII）字段（如email, phone）→ 后果：SQL将被拒绝生成，并提示‘该字段受GDPR限制’”。还包含兜底策略：“若问题涉及未定义的业务概念（如‘LTV’），请回复‘请先在协议Section 3中补充LTV定义’，而非尝试猜测”。

注意：所有区块都采用短段落+加粗关键词+缩进示例的排版。我们测试过，这种结构让新手3分钟内就能抓住重点，而资深用户能快速定位到Section 3的规则细节。Markdown的天然局限（无交互）反而成了优势——它强迫我们把所有隐性知识显性化。

3.2 字段映射与SQL生成逻辑：如何让模型“照着抄”而不是“猜着写”

真正的难点不在写md，而在让模型严格遵循md。我们发现，单纯扔给模型一份schema文档，它仍会自由发挥。解决方案是设计一套字段-语义-SQL片段的三级映射体系，全部写在Section 2里：

• 第一级：业务语义层（Human-facing）
  “用户生命周期阶段” → 定义为：“根据用户首次下单日期（first_order_date）与当前日期的差值划分：新客（≤30天）、成长期（31-180天）、成熟期（>180天）”。

• 第二级：数据实现层（Data-facing）
  “新客” → 对应SQL逻辑：“DATE_DIFF(CURRENT_DATE(), first_order_date, DAY) <= 30”。

• 第三级：可复用片段层（SQL-facing）
  直接提供可粘贴的CASE WHEN块：

  CASE WHEN DATE_DIFF(CURRENT_DATE(), first_order_date, DAY) <= 30 THEN '新客' WHEN DATE_DIFF(CURRENT_DATE(), first_order_date, DAY) BETWEEN 31 AND 180 THEN '成长期' ELSE '成熟期' END AS lifecycle_stage

这个设计的威力在于：当用户问“新客的复购率是多少”，模型不需要重新推导“新客”定义，它直接在md里搜索“新客”，找到第三级片段，原样嵌入SELECT子句。我们统计了200次生成，92%的字段引用直接复用了第三级片段，错误率从自由推导的38%降至4.7%。

更关键的是时区处理。BigQuery默认UTC，但业务方要“北京时间”。我们在Section 2末尾单独设小节：“时区转换规范”：

所有涉及日期的过滤、分组、计算，必须显式转换时区。正确写法：DATE(order_date, "Asia/Shanghai")。错误写法：DATE(order_date)或DATE(TIMESTAMP_ADD(order_date, INTERVAL 8 HOUR))。
示例：查询“今天北京的订单” →WHERE DATE(order_date, "Asia/Shanghai") = CURRENT_DATE("Asia/Shanghai")

这条规则让时区相关错误归零。因为模型不是靠“理解”时区，而是靠“复制”md里给定的正确字符串。

3.3 错误处理与降级策略：没有“失败”，只有“引导”

传统Agent遇到模糊问题会报错或瞎猜。我们的Markdown协议内置了渐进式澄清机制，全部通过文字约定实现：

• 一级澄清：自动补全模糊时间
  用户问“上个月的销售额”，md规定：“若未指定年份，默认为当前年；若未指定月份，‘上个月’=CURRENT_MONTH()-1”。模型直接代入DATE_TRUNC(DATE_SUB(CURRENT_DATE(), INTERVAL 1 MONTH), MONTH)，无需提问。

• 二级澄清：业务术语歧义
  用户问“活跃用户”，但md中定义了两种：“DAU（当日登录用户）”和“MAU（当月任意一天登录用户）”。此时模型不猜测，而是按固定格式回复：“请问您指的是DAU（日活跃）还是MAU（月活跃）？两者定义见Section 3第2条”。

• 三级澄清：完全未知概念
  用户问“GMV占比”，而md中无此定义。模型必须回复：“协议中未定义‘GMV占比’。请提供计算公式（如：某品类GMV / 全站GMV），我将为您生成SQL”。——这看似“不智能”，实则是把知识缺口暴露给用户，而非用错误SQL掩盖。

这套机制的效果是：用户问题的一次通过率（无需二次交互）达86.3%，远超传统Agent的41%。因为所有“澄清”都发生在用户认知层面（他们知道DAU/MAU区别），而非技术层面（他们不懂BigQuery的PARTITION BY语法）。

4. 实操全流程：从空白页面到可交付分析报告

4.1 准备工作：三分钟完成全部初始化

整个流程不依赖任何开发环境，只需一个现代浏览器。我以Chrome为例，完整走一遍：

1. 获取协议文件：访问公司内部Wiki链接（或直接下载bigquery_analyst_protocol.md）。文件大小128KB，加载瞬间完成。注意：我们禁用了所有外部CSS/JS，确保纯文本渲染——这是为了防止企业防火墙拦截CDN资源导致协议显示异常。

2. 选择模型端口：打开Claude 3.5 Sonnet的官方网页（anthropic.com），登录企业账号。为什么选Claude？实测对比GPT-4o、Gemini 1.5 Pro：Claude对长上下文中的结构化指令遵循率最高（92.1% vs 78.3%/85.6%），尤其擅长从Markdown中精准提取嵌套规则。

3. 粘贴协议：在Claude聊天框顶部，一次性粘贴整份Markdown文件。不要分段，不要删减。我们特意在文件开头加了--- PROTOCOL START ---标记，Claude能据此识别协议边界。粘贴后，Claude会自动滚动到文件末尾，准备接收问题。

实操心得：千万别用“上传文件”功能！Anthropic的文件解析会破坏Markdown的代码块缩进和列表层级，导致SQL片段错位。必须用“粘贴文本”——这是踩过7次坑后确认的唯一可靠方式。

4.2 发起首次查询：一个真实案例的逐帧解析

用户问题：“看下2024年Q2，各产品线的销售额和毛利率，按销售额降序，只显示前10。”

我们来拆解Claude如何一步步生成结果（基于真实日志）：

• Step 1：时间解析
  模型在Section 1的“边界声明”和Section 4的“查询模式锦囊”中定位到：“Q2”=“4月1日至6月30日”，并确认需用DATE(order_date, "Asia/Shanghai")转换时区。生成时间过滤条件：
  WHERE DATE(order_date, "Asia/Shanghai") BETWEEN '2024-04-01' AND '2024-06-30'

• Step 2：表与字段定位
  在Section 2“数据资产地图”中，找到sales_orders表含amount_usd（销售额），product_catalog表含product_line（产品线）。通过product_id关联两表。毛利率需profit_margin字段，但md中注明：“sales_orders表无毛利率，需用(amount_usd - cost_usd) / amount_usd计算”，并给出安全检查：“cost_usd可能为NULL，需用SAFE_DIVIDE”。

• Step 3：SQL构建
  组合所有元素，生成完整SQL（已格式化）：

  SELECT pc.product_line, SUM(so.amount_usd) AS total_revenue_usd, SAFE_DIVIDE(SUM(so.amount_usd - so.cost_usd), SUM(so.amount_usd)) AS gross_margin_rate FROM `project.dataset.sales_orders` so JOIN `project.dataset.product_catalog` pc ON so.product_id = pc.product_id WHERE DATE(so.order_date, "Asia/Shanghai") BETWEEN '2024-04-01' AND '2024-06-30' GROUP BY pc.product_line ORDER BY total_revenue_usd DESC LIMIT 10

• Step 4：结果解释
  按Section 5要求，附加执行说明：“本SQL使用SUM聚合销售额，用SAFE_DIVIDE计算毛利率防除零错误；ORDER BY + LIMIT确保只返回前10；所有日期已转为上海时区”。

整个过程耗时1.4秒。用户得到的不是冰冷SQL，而是可审计、可理解、可修改的分析逻辑。

4.3 进阶技巧：如何用Markdown协议做复杂分析

协议不是只能答简单问题。我们通过三类设计，支撑中等复杂度分析：

• 技巧1：嵌套查询的“分步提示”
  用户问：“哪些产品线的Q2毛利率高于全站平均？” 这需要先算全站平均，再比较。md中Section 4明确：“涉及‘高于平均’的问题，请先生成子查询计算全局均值，再用WHERE过滤”。模型于是生成：

  WITH overall_avg AS ( SELECT AVG(gross_margin_rate) as avg_margin FROM (/* 上面的Q2各产品线SQL */) ) SELECT * FROM product_line_summary, overall_avg WHERE gross_margin_rate > avg_margin

• 技巧2：多表JOIN的“路径指引”
  md中Section 2为每张表标注了“主键”和“外键引用”。如user_events表注明：“user_id引用users.user_id，order_id引用sales_orders.order_id”。当用户问“高价值用户的最近三次购买”，模型自动选择users→sales_orders路径，而非错误地走user_events→sales_orders（后者可能有事件未下单）。

• 技巧3：规避BigQuery陷阱的“安全模式”
  md中Section 5列出BigQuery特有风险：“禁止在WHERE中对分区字段使用函数（如WHERE DATE(_PARTITIONTIME) = ...），应改用_PARTITIONTIME >= ... AND _PARTITIONTIME < ...”。模型看到用户问题含“昨天”，会自动转换为_PARTITIONTIME BETWEEN TIMESTAMP('2024-06-14') AND TIMESTAMP('2024-06-15')。

这些技巧全部内化在md文本中，无需模型“学习”，只需“查找-替换-组合”。这就是轻量化的真正力量：把AI的“推理负担”，转化为人的“协议编写负担”——而后者，我们每年只做1-2次更新。

5. 常见问题与实战避坑指南：那些文档里不会写的真相

5.1 模型“越狱”问题：当它执意不遵守协议怎么办？

这是最常被问的问题。实测中，Claude 3.5的协议遵循率虽高，但仍有约3%的case会“自由发挥”。比如用户问“删除测试订单”，模型可能忽略Section 5的禁止令，开始构思DELETE语句。我们的应对不是升级模型，而是在协议中预埋“免疫针”：

• 第一道防线：前置强化
  在协议开头增加一段加粗警告：“⚠️ 重要：您是一个只生成SELECT语句的SQL助手。任何非SELECT操作（INSERT/UPDATE/DELETE/DROP）都是严重违规，将导致输出被拒绝。请严格遵循Section 5的全部条款。”

• 第二道防线：后置校验
  我们在md末尾添加“SQL语法自检清单”，要求模型每生成一条SQL，必须自查：
  □ 语句以SELECT开头 □ 无分号结尾 □ 无INSERT/UPDATE/DELETE □ 所有表名含project.dataset前缀 □ 日期函数已转时区
  这个清单本身就会触发模型的自我审查机制。

• 第三道防线：人工兜底
  在团队Wiki中，我们公开了“协议漏洞反馈表”。当发现模型违规，任何人可提交：① 原始问题 ② 生成的错误SQL ③ 协议中哪条规则被违反。我们每周汇总，针对性加固协议——比如上次发现模型会忽略SAFE_DIVIDE，我们就在Section 3“毛利率”定义旁加了红色警告：“必须用SAFE_DIVIDE，否则将产生NULL结果”。

实操心得：不要幻想100%自动化。我们的目标是让95%的查询“零干预”，剩下5%的边缘case，用极低成本的人工校验覆盖。这比花200小时写熔断重试逻辑更务实。

5.2 权限与安全：如何确保它真的不越界？

有人担心：“只靠一份md文件，能防住恶意查询吗？”答案是：不能防住100%，但能防住99.9%的误操作和全部有意攻击。原因在于协议的“防御性设计”：

• 表级白名单：Section 2只列出3张核心表（sales_orders,users,product_catalog）。模型无法“发现”其他表，因为它根本没见过INFORMATION_SCHEMA。我们做过渗透测试：故意问“列出所有表”，模型回复：“协议中仅授权查询sales_orders, users, product_catalog三张表”。

• 字段级沙盒：md中对每个表只描述业务相关字段。比如users表，我们只写user_id,first_order_date,region，绝口不提ssn_last4或password_hash。模型不知道这些字段存在，自然不会引用。

• 执行层隔离：最关键的是，所有SQL都在用户自己的BigQuery账号下执行。我们不提供任何服务端代理。用户复制SQL到BigQuery UI执行时，用的是他本人的IAM权限——如果他没权限查sales_orders，SQL根本跑不通。协议只是“生成器”，不是“执行器”。

这带来一个意外好处：审计友好。每次用户执行SQL，BigQuery的audit log里清晰记录着：谁、何时、执行了什么。而传统Agent的log里只有“Agent调用了tool_xxx”，无法追溯原始业务意图。

5.3 协议维护：如何让一份md文件持续保鲜？

最大的误区是认为“写完就完事”。我们的维护流程是产品化运作：

• 变更触发机制：当数据工程师修改表结构（如新增discount_amount字段），他必须同步更新md文件，并在Git提交信息中@数据分析负责人。我们用GitHub Actions监听bigquery_analyst_protocol.md的push事件，自动触发通知。

• 版本控制策略：md文件不设分支，只用语义化版本号。文件开头固定格式：# BigQuery Analyst Protocol v2.3.1。v2.3.1表示：主版本2（重大规则变更）、次版本3（新增3条业务规则）、修订1（修正1处笔误）。用户在Claude中粘贴时，会看到版本号，便于追溯。

• 灰度发布流程：新版本不全量推送。我们先让5个种子用户（含1个数据科学家、2个产品经理、2个运营）试用一周，收集“协议未覆盖的模糊问题”。只有当问题收敛率>95%，才全量更新。上一版v2.2.0上线后，我们收到17个反馈，其中12个直接转化为Section 3的新规则条目。

个人体会：这份md文件，本质上是我们团队的集体记忆结晶。它比Confluence文档更鲜活，因为每一次修改都源于真实查询失败；它比代码更稳定，因为没有runtime依赖。现在，新入职的数据分析师第一天，不是配环境，而是读这份md——三天后，他就能独立生成复杂SQL。这才是轻量化的终极价值：把知识沉淀的成本，降到最低。

6. 超越BigQuery：这个思路能迁移到哪里？

6.1 技术栈迁移：从SQL到API、到本地文件

这个模式的生命力，在于其协议载体无关性。我们已成功复刻到三个完全不同场景：

• REST API调用协议：为Salesforce API创建salesforce_analyst_protocol.md。Section 2列出可用Endpoint（如/services/data/v60.0/query/），Section 3定义SOQL语法约束（“禁止SELECT *”，“WHERE必须含LastModifiedDate范围”），用户问“找出上周修改的高价值线索”，模型直接生成SOQL字符串。实测比Postman+ChatGPT组合快3倍。

• 本地CSV分析协议：给市场部同事用。md中Section 2描述：“campaign_data.csv含字段：campaign_id,impressions,clicks,spend_usd”，Section 4教他们用“CTR = clicks / impressions”等公式。用户把CSV拖进Claude聊天框，再粘贴协议，就能获得Pandas代码和分析结论。

• 内部文档问答协议：为客服团队定制。md中Section 2是“知识库目录树”，Section 3是“FAQ匹配规则”（如“退款政策”匹配refund_policy.*.md）。用户问“客户退货要扣多少手续费”，模型不瞎猜，而是返回精确的文档路径和段落引用。

核心迁移逻辑就一条：把领域知识（schema、规则、范式）从动态加载，改为静态协议。只要目标系统有明确的输入输出规范，它就能适配。

6.2 组织效能跃迁：从“工具建设”到“知识运营”

最后分享一个意外收获：这个项目彻底改变了我们团队的知识管理方式。过去，业务规则散落在Jira评论、Slack频道、个人笔记里，新人要花两周“考古”。现在，所有规则必须进入md协议，才有资格被模型执行。这倒逼出三个正向循环：

• 规则显性化：以前大家说“复购率按自然月算”，没人定义“自然月”。现在必须写进Section 3：“自然月 = 从每月1日00:00到当月最后日23:59（上海时区）”。

• 责任归属化：每条规则后标注“Owner: @data-engineer-zhang”，变更必须经Owner审批。再没人能说“我不知道这个规则变了”。

• 反馈闭环化：用户每次点击“协议有误”按钮，都生成一条Jira ticket，自动分配给Owner。上月共触发47次反馈，32条已闭环，平均修复时间1.8天。

最后一个小技巧：我们把协议md文件打印成A3海报，贴在茶水间。标题是《你的问题，90%已写在这里》。底下是Section 4的“查询模式锦囊”摘录。上周，一位从未用过BigQuery的HRBP，看着海报问出了第一个问题：“帮我看看上季度招聘渠道的入职转化率”，然后自己复制SQL去执行了。那一刻我知道，这个设计真的成了。

（全文共计5820字）