cven-data-delivery-agent
项目摘要
cven-data-delivery-agent 是面向数据研发交付的可审计 Agent 工作台。项目把 Hive→StarRocks 建表迁移和 JOIN 右侧发散检查从一次性对话生成，重构为具有状态、工具、人工检查点、持久化记录和验证制品的完整工程流程。
问题背景
数据研发交付中存在大量规则明确但容易遗漏的步骤。Hive 的 string 字段不能在缺少真实长度时直接猜测 StarRocks 类型；复杂 JOIN 出现行数放大时，也不应为全部输入生成无差别重复检查。一次性模型回答可以给出草稿，却无法证明执行顺序、真实数据结果和最终制品之间的责任边界。
作者职责
- 将实际数据研发规则整理为产品范围、状态机和验收条件。
- 设计 Hive→StarRocks 与 JOIN 发散两条确定性工具链。
- 实现 FastAPI 编排、SQLite 运行仓库和稳定错误接口。
- 实现 Next.js 工作台、人工回填、制品、校验、轨迹和历史页面。
- 建立 Python、React、API、构建、敏感扫描、Docker 与 HTTP 冒烟门禁。
Agent 架构
浏览器通过 Next.js 同源代理访问 FastAPI。FastAPI 维护 received → analyzing → waiting_for_human → generating → validating → completed/failed 状态机，调用规则工具并把每次运行的输入、检查点、制品、校验结果和工具轨迹保存到 SQLite。Docker Compose 运行独立 Web 与 API 容器，API 不直接暴露公网端口。
确定性规则工具
Hive 工作流解析源表、普通字段、分区字段、注释与类型，为所有 string 字段生成最大长度检查 SQL。人工回填后，长度乘四、向上取整到 100，最小 100；不超过 2000 使用 VARCHAR(n)，超过阈值保留 STRING，TIMESTAMP 映射为 DATETIME。最终输出独立 StarRocks DDL 与取数 SQL，并检查字段完整性、明细键前缀、引擎和源表保留。
JOIN 工作流只分析 JOIN 右侧输入，从 ON 等值条件提取真实字段和复合键。右侧子查询已按全部 ON 键 GROUP BY，或 DISTINCT 输出只包含关联键时，Agent 记录跳过原因；其余输入生成 GROUP BY ... HAVING COUNT(*) > 1 检查 SQL，不使用位置编号。
人工与模型边界
Agent 不连接生产数据库，不自动执行 SQL，也不伪造字符串最大长度。需要真实数据结果时，运行进入 waiting_for_human；只有检查点字段完整回填后才能恢复。首版正确性由确定性工具保证，模型适配被限制为后续可选的摘要或风险说明，不能改写类型映射或绕过人工确认。
工作台与交付证据
工作台提供两个合成场景、SQL 编辑、目标表配置、状态展示、人工检查点、制品标签页、JOIN 右侧判定、结构校验、工具轨迹和运行历史。Hive 场景可完成真实暂停与恢复；JOIN 场景会为未收敛的商户快照生成复合键检查，并跳过已按订单标识聚合的状态子查询。
验证
后端测试覆盖 DDL 解析、字符串边界、复合键、收敛识别、状态转换、持久化与 API；前端测试覆盖 API 错误、人工检查点和恢复操作。质量门禁继续执行 Python 格式、Lint、类型检查、前后端测试、公开内容扫描和 Next.js 生产构建。双容器实际以非 root、只读根文件系统、no-new-privileges 和全部 capabilities 移除方式运行，并完成 Hive 暂停/恢复、JOIN 分析、SQLite 重启持久化和 HTTP 冒烟。
公开边界
全部场景使用 demo_ 合成表和虚构字段。项目不保存数据库地址、Cookie、Token、公司域名、真实表名、业务数据或生产指标。生成 SQL 是待审查制品，结构校验不代表已在目标数据库执行。
已知限制
- 首版不提供生产数据库连接和自动执行能力。
- 首版不实现登录、多租户、权限审批和运行保留策略。
- 模型适配接口尚未进入核心流程，避免模型输出影响确定性规则。
后续演进
在不扩大公开数据边界的前提下，可增加受控模型建议层、规则版本、运行对比、审批记录和更多合成数据研发场景。