智能问数 · 核心交付
交付概览
项目由三块组成：前端对话页、后端网关（内含问数编排与护栏包）和链路评估台。对话在前端完成，问数和执行在后端完成，回看单独放在评估台。各部分的定位、技术栈和功能如下。
前端展示层
- 简介：
frontend/。给问数一个可对话的页面：登录、选择数据源、发送问题，看到任务状态、表格、图表和回答。 - 技术栈：Vue 3、TypeScript、Vite、Vue Router、Element Plus、ECharts、marked、DOMPurify、Vitest。
- 功能描述：五条路由——登录、对话、数据集、Skills、本域账号；未登录进登录页，账号页只对管理员开放。对话以 SSE 接收增量文本、任务板、确认卡片、完成和错误事件；发送前必须已绑定数据源，换源清空上一轮上下文。回答先按 Markdown 解析再经 DOMPurify 净化；查询结果渲染成表格，作图结果用 ECharts 画柱状图和折线图。页面不执行 SQL，也收不到 SQL 原文。
后端 AI 应用层
- 简介：
backend/。接收一轮问题，完成拆解、等待、查询、计算、素材和回答；执行 SQL 或 Python 时由护栏放行或拦截。模型只通过这一层接触数据和代码执行。 - 技术栈：Python 3.12+、FastAPI / Starlette、Uvicorn、Pydantic 与 pydantic-settings、httpx、SQLite、psycopg 3、PyYAML、cryptography、Docker CLI；hatchling 打包。
- 功能描述：
- 网关
- 一轮对话走 SSE：
/v1/chat接收提问并推送过程。 - 两层时限：
TTS_REQUEST_TIMEOUT_MS默认 60 秒，管每次模型调用；TTS_CHAT_WALL_TIMEOUT_MS默认 20 分钟，管整轮。回退回路、五阶段查询波次和写回答都接墙钟。 - 等待和批准分开：
/v1/clarify恢复等待，/v1/confirm批准副作用。 - 会话和资源：
/v1/auth/*会话登录；/v1/admin/users本域账号；/v1/workspaces、/v1/sources、/v1/datasets、/v1/skills管理工作区、来源、文件快照和 Skills。 - 探活与评估读口：
/live、/ready；/v1/eval/*供评估台读链路。
- 一轮对话走 SSE：
- 问数编排
- 原问拆成任务图：拆解轮产出 query / compute，挂到任务板。
- 歧义停在等待：相关任务先不启动。
- 查询经意图编译：query 由
IntentQuery编译后送进只读子进程；没有依赖的子问最多 4 路并行。 - 计算限定闭集：compute 只做闭集运算。
- 回答只读素材：素材回指结果与字段，回答轮据此成文。
- 解析不出则回退：意图解析不出，或表结构不是 SQLite 文件时，走最多 10 步的闭集工具回路。
- 护栏包
tts_sandbox- 执行层单独成包：运行期只依赖 Pydantic。wheel 只含执行层，不含网关、回路和前端。
- 公开六个符号：
Guard、Principal、ExecResult、ErrorCode、GuardPolicy、AuditSink。 - SQL 只读且限表：只放行
SELECT/WITH，表名须在白名单内。 - Python 先静态检查：按允许清单拦截。
- 每次决定写审计。
- 执行器
- SQLite 出进程：查询在独立子进程里用
query_only连接执行。 - PostgreSQL 只读事务：在独立 worker 里执行，问前核验权限。
- Python 进固定容器：镜像摘要固定；无网络、只读根文件系统、非 root、256 MB 内存、1 CPU、64 进程、10 秒超时。
- 没有容器就拒绝：返回
SANDBOX_UNAVAILABLE，不改到网关进程内执行。
- SQLite 出进程：查询在独立子进程里用
- 工具可见性
- 模型只看见五个工具：
get_schema、sample_data、plot、export、run_python。 run_sql和confirm对模型不可见。- 导出先等人确认：先挂起，确认入口批准后执行一次，重复提交幂等。
- 模型只看见五个工具：
- 落盘
- 一轮四份记录：
runs.jsonl、chains.jsonl（五阶段事件，版本 2.0）、transcript.jsonl、taskboard.json。 - 护栏审计单独一条流。
- 来源凭据加密：用
TTS_PROVENANCE_KEY保存。
- 一轮四份记录：
- 网关
链路评估台
- 简介：
review/。离线回看一轮问数停在哪一段，并查看黄金集夜间批次。页面不登录到模型、不执行 SQL。 - 技术栈：Vue 3、TypeScript、Vite、Vue Router（hash 路由）、Vitest；Python 脚本导出链路。
- 功能描述：
- 真实运行记录：管理员登录后，按数据源通过
/v1/eval/*读取工作区里的chains.jsonl；公司之间靠登录态隔离。 - 黄金集批次：按夜间时间槽（01 / 03 / 05 点）打开批次，逐题查看正文、判分结果和逐步链路；黄金集的
origin=golden_eval，和真人提问的分母分开。 - 两套标注：链路版本 2.0 按拆解、等待、任务、素材、回答五段标注；更早的记录仍用四类检查。标注存在当前浏览器，可导入导出。
- 离线包：
scripts/export_chains.py从工作区导出记录包；public/business.sqlite可以在仓外复算参考 SQL。
- 真实运行记录：管理员登录后，按数据源通过