V5｜Agentic 数据分析师

状态：待开发。全部任务默认未完成；本文件是勾选状态的唯一来源。 依据：原始总纲第 40 节；以下故事、编号、接口与验收细则为本次实施设计。

阶段目标

复用 V4 受控能力，支持多步分析、多轮上下文与有预算的工具编排。

• 进入条件：V4 验收完成，统一执行入口和策略不可绕过。
• 规模 / 质量约束：复杂分析具有状态、证据、预算与停止条件；此阶段才引入 LangGraph。
• 阶段依赖：V0 → V1 → V2 → V3 → V4 → V5 → V6。故事内任务按编号顺序执行，故事间按下列依赖执行。
• 建议路径均为规划位置，尚未存在；实现时允许简化文件拆分，但必须更新学习站真实代码索引。
• 完成标准：本期任务全部满足 通用 DoD，证据登记到 验收记录。

V5-S01｜工具契约与受控执行入口

用户故事：作为平台开发者希望 Agent 只能调用已有受控服务，而不能直接接触数据库。

依赖：V4-S06。
建议落点：server/agent/tools、server/execution。
学习目标：工具边界、最小能力、错误契约。

开发任务

• V5-S01-T01 为 SchemaSearch、SemanticSearch、ValueSearch、VerifiedQuery、SQLGenerate、SQLExecute、SQLRepair、Chart 定义类型化工具输入输出。
• V5-S01-T02 适配 V4 服务并注入 AuthorizationContext、trace_id、deadline、调用预算；SQLExecute 复用完整安全入口。
• V5-S01-T03 移除工具层直接数据库连接与任意代码执行能力；测试模型伪造角色、SQL、工具参数与超限调用。

验收场景

工具得到的 SQL 不因由 Agent 产生就获准执行；用户身份与预算不能由模型覆盖；每次工具调用有追踪记录。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V5-S02｜分析任务拆解与状态图

用户故事：作为业务用户希望复杂问题被拆为可检验的步骤，并在失败时获得明确说明。

依赖：V5-S01。
建议落点：server/agent/graph、server/planner。
学习目标：状态图、检查点、幂等与循环终止。

开发任务

• V5-S02-T01 引入 LangGraph，定义分析状态、节点、边、checkpoint 与终止状态；复用 V4 QueryPlan 作为子任务计划。
• V5-S02-T02 将“销售下降但毛利率提升”拆为同期指标、筛选城市、产品/客户结构对比与综合解释，记录依赖图。
• V5-S02-T03 实现总步数、总 token、总成本、总超时和用户取消；中断恢复时核验身份/语义版本，避免重复执行已完成节点。

验收场景

一个分支失败不会生成完整成功答案；循环工具选择达到预算后停止；恢复执行可追溯哪些证据被复用。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V5-S03｜多轮分析与上下文继承

用户故事：作为业务用户希望从城市排名追问区域、同期和品类，且系统清楚哪些条件被覆盖。

依赖：V5-S02。
建议落点：server/agent/session、server/api、apps/web。
学习目标：结构化会话、槽位合并、上下文隔离。

开发任务

• V5-S03-T01 保存指标、维度、时间、过滤、版本与结果引用的结构化会话，不将整段历史直接当授权或计划。
• V5-S03-T02 定义“只看华东”“再和去年比”“换成订单量”等合并/覆盖/重置规则，歧义时展示澄清。
• V5-S03-T03 实现会话过期、删除、切换用户与撤权后的访问隔离；前端展示本轮生效条件并支持新建分析。

验收场景

年度排名→华东→同比的时间条件正确继承；换指标会校验原维度是否兼容；用户之间无法通过 session_id 越权读取。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V5-S04｜条件触发的多候选 SQL

用户故事：作为平台负责人希望在疑难问题上提高质量，同时控制模型与数据库成本。

依赖：V5-S02。
建议落点：server/agent/candidates、server/evaluation。
学习目标：选择偏差、置信度、成本收益实验。

开发任务

• V5-S04-T01 仅对 HIGH complexity 或 LOW confidence 触发有限候选，定义候选上限和共享预算。
• V5-S04-T02 按语法、schema、语义、策略、执行、结果与成本评分；每个执行候选都经过 V4 安全链路。
• V5-S04-T03 比较单候选与多候选在复杂子集上的正确率、时延与成本；记录候选分歧并在不可判定时澄清。

验收场景

简单题只生成一条候选；安全失败候选不参与执行投票；多个答案不一致时不能仅凭多数票宣布业务正确。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

V5-S05｜结果综合与分析体验

用户故事：作为业务用户希望看到分析步骤、图表与依据，区分相关线索和因果结论。

依赖：V5-S03、V5-S04。
建议落点：apps/web、server/agent/synthesis、altassql-book/stages。
学习目标：证据引用、部分完成、因果边界。

开发任务

• V5-S05-T01 实现任务进度、步骤详情、取消、恢复和部分失败展示，图表复用 V4 结果渲染能力。
• V5-S05-T02 将总结关联到子查询结果与时间口径，标注数据局限；“原因”分析表述为可验证贡献或相关线索。
• V5-S05-T03 构建多轮、复杂分解、工具失败、循环预算和权限变更回归集，输出 V4/V5 收益报告与学习导读。

验收场景

每个关键结论可点到证据；缺失分支明确显示不完整；没有实验或因果设计时不将相关性写成已证明原因。

完成后应提供：相关测试或演示命令、实际结果、真实代码入口和一段“为什么这样做”的说明。仅创建文件不满足验收。

阶段演示与复盘

1. 从本期故事选一条完整用户流程，按输入 → 中间产物 → 输出演示。
2. 演示上述验收中的一个失败/拒绝场景，解释负责处理的模块。
3. 固定环境和数据版本，提交本期验收报告；未达到的目标登记阻塞原因。
4. 在学习站 stages/v5.md 补充已实现代码入口、调用关系、实测结果及面试复述。
5. 复查本期 5 个用户故事、15 个开发任务的证据，再由执行者勾选。

复盘问题：本期解决了上一期哪类具体失败？增加了什么复杂度？有什么证据证明收益？下一期需要解决什么剩余问题？