周期建议：8–14 天。所有数据均为合成数据；查询只允许访问本地只读数据集。
项目背景
一个虚构的零售团队希望业务人员直接提问“最近 7 天 GMV 按渠道怎么变化”。直接让模型生成并执行 SQL 会带来三类问题：业务口径不明确，同一个“用户数”可能有多种定义；模型可能查询越界表或生成写操作；图表和结论看似专业，却没有解释使用了什么指标、过滤条件和限制。
团队需要一个安全数据分析 Agent。它必须先理解指标与数据集边界，再生成候选 SQL，经过独立安全校验后才能在只读连接上执行，最后用可核对的结果生成图表与摘要。
项目目标
交付一个本地分析工作台，走通“自然语言问题 → 指标/维度映射 → 候选 SQL → 安全验证 → 只读执行 → 图表与解释 → 追问建议”的链路。
安全校验必须独立于 SQL 生成器：即使生成器给出危险 SQL，执行层也要拒绝。
用户故事
- 作为业务用户，我希望用自然语言提问并看到采用的指标口径，从而避免误读数据。
- 作为分析师，我希望查看 SQL、过滤条件和结果限制，从而核验查询过程。
- 作为数据负责人，我希望危险或越界查询在执行前被阻止，从而保护数据完整性与边界。
- 作为管理者，我希望图表和摘要标注数据范围与限制，从而不把推测当事实。
功能要求
必须完成
- 合成数据集与指标字典
- 提供至少两个本地合成数据表，例如
sales_daily 与 traffic_daily。
- 指标字典至少定义 3 个指标，包含名称、业务含义、SQL 表达式、聚合方式、允许维度和数据集。
- 数据集元数据明确可查询表、字段、时间字段和禁止字段。
- 问题解析与澄清
- 从问题中输出指标、维度、筛选、时间范围和置信/歧义信息。
- 对一个明确问题可用规则或 Mock Provider 生成候选 SQL。
- 当指标有多种合理含义或缺少关键时间范围时，返回澄清请求，不得直接猜测并执行。
- 独立 SQL 安全校验
- 只允许单条只读查询；拒绝写操作、DDL、多语句、注释绕过和无法解析的语句。
- 只允许访问白名单表/字段，拒绝跨数据集或敏感字段。
- 查询必须有可配置行数上限；可选择拒绝无
LIMIT 查询或安全地追加上限，但行为必须一致。
- 不得仅依赖简单字符串包含判断；说明使用的解析或受限查询构造策略。
- 受限执行
- 仅在校验通过后使用只读数据库连接执行，设置超时和最大返回行数。
- 校验失败、执行超时、空结果和除零/空值场景有结构化结果。
- 查询解释
- 展示采用的指标口径、表/字段、过滤条件、分组、排序、时间范围、限制和安全校验结果。
- 用户能看到实际执行 SQL，而非只看自然语言摘要。
- 图表与洞察
- 根据结果形状生成至少表格和一种图表（折线或柱状），并说明推荐理由。
- 摘要只陈述可由结果计算得到的趋势/对比，标注数据范围，不编造原因。
- 提供至少 2 个基于当前上下文的追问建议。
- 分析记录
- 保留问题、解析结果、候选/执行 SQL、安全结论、结果摘要和时间；失败记录也可查看。
可选增强
- 使用真实 LLM Adapter 生成候选 SQL，但默认验收路径必须完全本地。
- 图表配置导出、分析报告或结果 CSV 导出。
- 更严格的 SQL AST 重写、查询成本估算或敏感值脱敏。
- 支持多轮追问继承时间范围，并清楚展示继承了哪些上下文。
非功能要求
- 可运行性：提供确定性的种子数据与初始化命令；测试不能依赖公网或外部数据库。
- 安全性：执行账户/连接为只读；所有 SQL 无论来源都必须走同一校验器；错误中不得泄露环境信息。
- 可靠性：同一问题在相同数据与规则下产生可复现结果；空值、除零和空结果不会导致服务崩溃。
- 性能：在题目种子数据规模下，安全校验与查询各应在 2 秒内完成，并有超时保护。
- 可解释性：指标映射、安全拒绝理由和图表选择都能由用户查看。
- 无障碍：图表必须有文本标题、单位和数据表替代；错误不能只靠颜色表达。
范围与限制
范围内
- 本地单用户分析工作台。
- 合成销售/流量数据、指标字典、确定性 NL2SQL、安全校验、只读执行、解释与图表。
- 有效问题、歧义问题、危险 SQL、空结果和异常数据演示。
范围外
- 连接生产数仓、上传真实经营数据、跨组织数据访问。
- 任意 SQL 控制台、写回数据、自动决策或自动发送报告。
- 训练模型、构建通用 BI 平台、保证自然语言理解覆盖所有表达。
- 复制现有分析 Agent 的源码或真实业务口径。
技术与时间限制
- 周期为 8–14 天；优先实现校验边界与可解释主路径。
- 技术栈可自选，必须有可演示 UI 和可自动测试的解析、校验、执行接口。
- 默认使用 SQLite、H2 或等价嵌入式数据库；数据库必须以只读方式进入执行阶段。
- NL2SQL 可使用确定性规则/Mock Provider；不得要求模型 API Key。
- 不要求部署。自行部署不得包含真实数据、公开写接口、产生费用或替代本地复现路径。
澄清机制
在“澄清 Issue”说明问题背景、歧义、候选方案、推荐、影响，以及未回复时采用的可逆假设。
例如“GMV 是否包含退款订单”属于指标口径问题，不能让 Agent 自行猜测。展示细节可先假设；任何会改变指标含义、开放新表、允许写入、使用真实数据或引入外部费用的事项必须等待组织者确认。若现有选项不覆盖真实情况，保留 D/or 方案并明确风险与验证方法。
交付物与证据
- 可运行源码、依赖锁文件、安全配置示例、数据库迁移/初始化和合成种子数据。
README.md：架构、启动、指标口径、示例问题、安全攻击样例、测试和限制。docs/PRD.md：角色、流程、指标决策、范围、验收映射与澄清记录。docs/PLAN.md：生成器、校验器、执行器、图表层的边界与威胁分析。- 自动化测试：至少覆盖白名单、写操作、多语句/注释、无 LIMIT、歧义、只读执行、空值和结果解释。
docs/TEST_EVIDENCE.md：命令、结果、验收映射、安全拒绝和成功分析证据。docs/AI_COLLABORATION.md：AI 参与、本人核验与拒绝项；不得粘贴私人会话全文。docs/RETROSPECTIVE.md、阶段 Issue、PR 和可解释提交历史。
公开可测试验收标准
技术讲解与追问准备
请准备讲清：指标口径放在哪里；生成器与校验器为何必须分离；SQL 解析和白名单策略能防什么、不能防什么；只读连接、超时与行数上限如何协作；图表/摘要如何避免越过数据证据；AI 建议如何被测试推翻或确认。
验收可能提供新的危险 SQL 或临时指标。你需要先分析它属于指标治理、解析、校验还是展示层，再以小步提交和回归证据完成变更。
安全与合规
- 只能使用合成、脱敏且授权的数据；不得导入生产库、客户数据、真实财务数据或雇主 SQL。
- 任何生成 SQL 都是不可信输入；校验通过也不等于业务口径正确，必须同时展示指标依据。
- 禁止写操作、自动业务决策和未经确认的外部报表发送。
- 不得提交、共享或中转数据库、Codex 或模型账号、会话、Token、API Key、Cookie、私钥。
- 本活动用于项目实践和能力反馈，不承诺就业、录用、薪资或面试结果。