# 安全数据分析 Agent > 周期建议：8–14 天。所有数据均为合成数据；查询只允许访问本地只读数据集。 ## 项目背景 一个虚构的零售团队希望业务人员直接提问“最近 7 天 GMV 按渠道怎么变化”。直接让模型生成并执行 SQL 会带来三类问题：业务口径不明确，同一个“用户数”可能有多种定义；模型可能查询越界表或生成写操作；图表和结论看似专业，却没有解释使用了什么指标、过滤条件和限制。 团队需要一个安全数据分析 Agent。它必须先理解指标与数据集边界，再生成候选 SQL，经过独立安全校验后才能在只读连接上执行，最后用可核对的结果生成图表与摘要。 ## 项目目标 交付一个本地分析工作台，走通“自然语言问题 → 指标/维度映射 → 候选 SQL → 安全验证 → 只读执行 → 图表与解释 → 追问建议”的链路。 安全校验必须独立于 SQL 生成器：即使生成器给出危险 SQL，执行层也要拒绝。 ## 用户故事 - 作为业务用户，我希望用自然语言提问并看到采用的指标口径，从而避免误读数据。 - 作为分析师，我希望查看 SQL、过滤条件和结果限制，从而核验查询过程。 - 作为数据负责人，我希望危险或越界查询在执行前被阻止，从而保护数据完整性与边界。 - 作为管理者，我希望图表和摘要标注数据范围与限制，从而不把推测当事实。 ## 功能要求 ### 必须完成 1. **合成数据集与指标字典** - 提供至少两个本地合成数据表，例如 `sales_daily` 与 `traffic_daily`。 - 指标字典至少定义 3 个指标，包含名称、业务含义、SQL 表达式、聚合方式、允许维度和数据集。 - 数据集元数据明确可查询表、字段、时间字段和禁止字段。 2. **问题解析与澄清** - 从问题中输出指标、维度、筛选、时间范围和置信/歧义信息。 - 对一个明确问题可用规则或 Mock Provider 生成候选 SQL。 - 当指标有多种合理含义或缺少关键时间范围时，返回澄清请求，不得直接猜测并执行。 3. **独立 SQL 安全校验** - 只允许单条只读查询；拒绝写操作、DDL、多语句、注释绕过和无法解析的语句。 - 只允许访问白名单表/字段，拒绝跨数据集或敏感字段。 - 查询必须有可配置行数上限；可选择拒绝无 `LIMIT` 查询或安全地追加上限，但行为必须一致。 - 不得仅依赖简单字符串包含判断；说明使用的解析或受限查询构造策略。 4. **受限执行** - 仅在校验通过后使用只读数据库连接执行，设置超时和最大返回行数。 - 校验失败、执行超时、空结果和除零/空值场景有结构化结果。 5. **查询解释** - 展示采用的指标口径、表/字段、过滤条件、分组、排序、时间范围、限制和安全校验结果。 - 用户能看到实际执行 SQL，而非只看自然语言摘要。 6. **图表与洞察** - 根据结果形状生成至少表格和一种图表（折线或柱状），并说明推荐理由。 - 摘要只陈述可由结果计算得到的趋势/对比，标注数据范围，不编造原因。 - 提供至少 2 个基于当前上下文的追问建议。 7. **分析记录** - 保留问题、解析结果、候选/执行 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 和可解释提交历史。 ## 公开可测试验收标准 | ID | Given / 前置条件 | When / 操作 | Then / 可观察结果 | 验证方式 | |---|---|---|---|---| | AC-01 | 指标字典已载入 `gmv` 等指标 | 查看指标详情 | 可见含义、表达式、聚合、允许维度和数据集，内容与执行映射一致 | API/UI + 单元测试 | | AC-02 | 合成数据含最近 7 天多个渠道记录 | 提问“最近 7 天 GMV 按渠道趋势” | 解析出正确指标、维度和时间，候选 SQL 通过校验并返回可核对结果 | 集成测试 | | AC-03 | 任意来源提供 `DELETE FROM sales_daily` | 请求校验或执行 | 在数据库执行前被拒绝，返回稳定规则码，种子数据未改变 | 安全测试 | | AC-04 | 候选 SQL 含多语句、注释绕过或访问非白名单表/字段 | 请求执行 | 所有变体均被独立校验器拒绝并说明命中规则 | 参数化自动化测试 | | AC-05 | 候选只读 SQL 没有行数限制 | 请求执行 | 系统按文档约定拒绝或安全追加上限，实际返回不超过上限 | 自动化测试 | | AC-06 | 用户问题中的“用户数”可对应两个指标 | 提交问题 | 返回结构化澄清选项且不执行 SQL、不生成误导图表 | 自动化测试 | | AC-07 | 查询返回时间序列结果 | 打开分析结果 | 显示实际 SQL、指标口径、过滤、图表和数据表；摘要只陈述可计算事实 | UI/API 复现 | | AC-08 | 数据含空值、分母为零或无匹配日期 | 分别执行相关分析 | 返回明确空值/空结果处理，不出现崩溃、Infinity 或虚构结论 | 自动化测试 | | AC-09 | 全新环境且无模型/数据库云凭证 | 按 README 初始化、启动并运行测试 | 主路径与危险路径均可本地复现，执行连接不能写入业务表 | 人工复现 + 命令证据 | ## 技术讲解与追问准备 请准备讲清：指标口径放在哪里；生成器与校验器为何必须分离；SQL 解析和白名单策略能防什么、不能防什么；只读连接、超时与行数上限如何协作；图表/摘要如何避免越过数据证据；AI 建议如何被测试推翻或确认。 验收可能提供新的危险 SQL 或临时指标。你需要先分析它属于指标治理、解析、校验还是展示层，再以小步提交和回归证据完成变更。 ## 安全与合规 - 只能使用合成、脱敏且授权的数据；不得导入生产库、客户数据、真实财务数据或雇主 SQL。 - 任何生成 SQL 都是不可信输入；校验通过也不等于业务口径正确，必须同时展示指标依据。 - 禁止写操作、自动业务决策和未经确认的外部报表发送。 - 不得提交、共享或中转数据库、Codex 或模型账号、会话、Token、API Key、Cookie、私钥。 - 本活动用于项目实践和能力反馈，不承诺就业、录用、薪资或面试结果。