智析AgentData-Analysis-Agent 0→1 架构、搭建与联调实战报告

momo

227人浏览 · 2026-07-17 19:09:03

momo · 2026-07-17 19:09:03 发布

基于 GitHub 主分支 / v1.1.0 LTS 的源码级逆向梳理

图 1　智析Agent 当前本地运行界面（用户提供截图）

报告对象	Zafer-Liu / Data-Analysis-Agent（本地项目名：智析Agent）
分析范围	启动入口、前后端架构、Agent 核心、数据工具、图表、技能、MCP、打包发布与联调
报告日期	2026-07-17
结论性质	基于当前公开源码的工程复原；不等同于作者真实开发时间线

1. 执行摘要

2. 产品目标与完整用户旅程

3. 技术选型与架构拆解

4. 源码目录与模块职责

5. 从 0 到 1 的创建路径

6. 本地构建与启动手册

7. 前后端与 Agent 联调方法

8. 数据链路、NL2SQL 与图表链路

9. Skills、Commands、知识库与 MCP

10. 测试、验收与故障排查

11. 安全、许可与工程风险

12. 智析Agent 的二次开发路线

13. 两周 / 四周实施计划

附录 A：常用命令

附录 B：关键源码索引与参考资料

1. 执行摘要

Data-Analysis-Agent 是一个以“自然语言驱动数据分析”为核心的本地 Web Agent。用户上传 Excel/CSV、连接 SQL 数据库或其他数据源后，系统把问题转成受控工具调用：读取结构、生成并执行查询、完成统计分析、选择图表、导出 Excel/Word/PPT，并通过 SSE 将过程事件持续推送到浏览器。其本质不是“让大模型直接碰数据库”，而是一个由大模型负责规划、由应用工具负责执行的分析操作系统。[R1][R4][R6]

一句话判断

这是一个“Flask Web 应用 + OpenAI 兼容模型适配层 + ReAct/Function Calling Agent + 数据分析工具箱 + Vite 前端”的组合工程。它先把常规分析闭环做实，再逐步叠加技能、命令、知识库、MCP、工作区、异步任务与桌面打包。

1.1 最值得借鉴的设计

模型只输出工具意图，真实数据访问由应用层执行；数据权限、参数校验和错误处理因此可被工程化控制。
Agent 主循环与工具定义、工具实现分离：schemas.py 负责“模型能看到什么”，DataToolsMixin / ExportToolsMixin 负责“系统真正执行什么”。
SSE 把长流程拆成进度、思考、工具调用、工具结果、最终回答等事件，前端无需等待整段任务完成。
Skills 采用 SKILL.md 提示词扩展，而不是任意加载 Python 代码，降低了插件扩展的供应链风险。
MCP 作为外部能力扩展层，统一转换为 OpenAI function tool schema，并通过独立异步事件循环管理连接。

1.2 复刻时应优先做什么

先做单数据源的最小闭环：上传 CSV → 查看字段 → 查询 → 图表 → 回答。
再做多模型与配置管理，不要一开始就同时兼容所有供应商。
把 SQL 安全校验、只读约束、超时、行数上限放在 Agent 之前完成。
前端先只实现消息流和工具状态，技能、任务历史、团队协作可后置。
完成端到端测试后，再加入 Word/PPT、MCP、知识库、桌面安装包。

2. 产品目标与完整用户旅程

2.1 产品定位

该项目把数据分析师常见工作拆成可组合能力：数据接入、语义理解、结构探查、SQL/计算、可视化、结论解释、结果导出。README 给出的核心路径是“连接数据 → 理解意图 → 读取结构 → 生成 SQL → 执行 → 生成图表 → 输出洞察”，并支持 Excel/CSV 与 SQLite、MySQL、PostgreSQL、SQL Server 等数据库。[R1]

2.2 用户可见流程

阶段	用户动作	系统动作	可见反馈
准备	上传文件或连接数据库	保存数据源配置，解析表和字段	左侧显示“已连接”
提问	输入自然语言或 /command	解析激活项、会话、技能和数据上下文	消息进入流式状态
规划	无需额外操作	BusinessAgent 请求模型生成工具调用	显示思考/步骤状态
执行	可确认高风险导出或方案	调用 schema/query/analysis/chart/export 等工具	展示工具卡片、进度和错误
呈现	查看图表和洞察	把工具结果交还模型进行归纳	文本、表格、图表、文件下载
沉淀	保存会话、知识或工作区	写入本地运行目录	历史任务可恢复

2.3 截图与源码的对应关系

截图中的“添加数据源”与模板中的 Excel/CSV、SQL、Google Sheets、自定义 API 入口对应。[R11]
模型选择、MCP、工作目录、业务知识库、临时 Prompt、保存会话等按钮，都有独立 Flask Blueprint 或前端 feature 模块。
首页建议词中的 /data、/tree、/kmeans、/ppt、/dashboard 并非纯文本：命令和技能系统会把它们解析为受约束的执行路径。
当前前端不是典型 React/Vue SPA；它使用 Vite 构建多个入口，并按顺序加载 legacy 与 feature 模块完成渐进式模块化。[R10][R11]

图 2　Data-Analysis-Agent 分层架构（依据源码整理）

3. 技术选型与架构拆解

3.1 关键选型总表

层级	选型	主要用途	为什么适合	代价 / 注意事项
运行入口	Python + app.py	依赖检查、路径、日志、启动 WSGI	上手快，适合桌面和本地部署	启动逻辑较重，需控制副作用
Web 后端	Flask + Blueprints + CORS	API、静态页、会话、文件与任务	模块轻、可逐步拆分	大型项目需严控全局状态
生产服务	Waitress / Gunicorn	Windows / Linux WSGI	兼顾跨平台	SSE 需正确配置超时与缓冲
模型接口	OpenAI Python SDK 兼容协议	DeepSeek、OpenAI、AtlasCloud、自定义端点	一套 client 适配多家模型	各供应商 tool calling 细节仍可能不同
Agent	ReAct + Function Calling	规划、调用工具、读取结果、继续推理	可审计、可插拔	需限制循环次数与 token
数据计算	Pandas + DuckDB + SQLAlchemy	文件分析、SQL 查询、数据库适配	生态成熟，覆盖本地和远程	大数据需异步或下推数据库
SQL 安全	sqlglot	解析、规范化、检查 SQL	比字符串规则可靠	仍需数据库只读账号兜底
统计建模	SciPy / statsmodels / pmdarima	统计检验、时序、回归	常见分析覆盖充分	依赖体积较大
图表	Plotly / Pyecharts / Matplotlib	交互图、网页图、静态图	覆盖多输出格式	三套体系会增加一致性成本
前端	HTML + Vite + 模块化 JS	聊天、面板、流式事件、预览	保留旧代码同时支持构建优化	缺少统一状态框架时维护难度上升
流式传输	Server-Sent Events	单向推送 Agent 事件	实现简单，适合聊天式任务	反向交互仍需普通 HTTP
文档导出	python-docx / python-pptx / openpyxl	Word、PPT、Excel	完全本地生成	复杂排版需额外模板与校验
扩展协议	MCP stdio / SSE	接入外部工具服务	工具协议统一	必须管理信任边界和进程生命周期
桌面发布	Inno Setup / macOS DMG	Windows 安装包、macOS 镜像	面向非技术用户	CI、签名、依赖打包更复杂

3.2 为什么用 Flask，而不是一开始上微服务

此类 Agent 的早期瓶颈不是 HTTP 吞吐，而是模型延迟、数据查询与分析执行。Flask 足以承载路由、会话和 SSE，同时便于与 Pandas、数据库驱动、文档生成库直接共进程。项目通过 application factory 注册 models、datasource、chat、saved_sessions、system、output、mcp、dashboard、knowledge、workspace、jobs、skills 等 Blueprint，已经形成“模块化单体”结构。[R3]

3.3 为什么用 OpenAI 兼容协议

LLMConfigManager 为不同供应商创建统一 OpenAI client，通过 base_url、api_key 和 model 组合接入；模型连通性测试也统一调用 chat.completions.create。这样能最大化复用消息格式、流式响应和 tool calling 逻辑。[R8]

源码与 README 存在模型名称差异

README 当前列出的默认模型与 LLMConfigManager 内置模型并不完全一致。工程上应以实际运行代码为准，同时固定版本或 commit，并在发布前做一次“文档—配置—UI”一致性校验。

4. 源码目录与模块职责

4.1 建议先读的目录树

Data-Analysis-Agent/

├─ app.py # 启动入口、路径/日志/依赖/WSGI

├─ api/ # Flask Blueprints 与应用工厂

│ ├─ __init__.py # create_app(), 注册路由

│ ├─ chat.py # SSE 会话主入口

│ ├─ datasource.py # 文件、数据库、Sheets、HTTP API

│ ├─ models.py # 模型配置

│ ├─ output.py # 输出文件

│ ├─ mcp.py / knowledge.py # MCP 与知识库

│ ├─ jobs.py / saved_sessions.py # 异步任务、历史会话

│ └─ workspace.py / teams.py # 工作区与团队

├─ agent/

│ ├─ agent.py # BusinessAgent 主循环

│ ├─ prompts.py # 系统提示词

│ ├─ tools/

│ │ ├─ schemas.py # 暴露给模型的工具定义

│ │ └─ business/ # 数据与导出工具实现

│ ├─ commands/ # /data、/status、/compact 等命令

│ ├─ skills.py # SKILL.md 加载器

│ ├─ mcp_manager.py # MCP 连接与工具转换

│ └─ compaction.py / retry.py # 上下文压缩与重试

├─ Function/

│ ├─ Analyze/ # 分析算法注册

│ ├─ Charts_generation/ # 图表生成

│ ├─ Clean/ # 数据清洗

│ ├─ Knowledge/ # 知识能力

│ └─ Output/ # Excel/Word/PPT 输出

├─ LLM/llm_config_manager.py # 模型配置与 OpenAI 兼容客户端

├─ data/ # 数据源、会话、工作区、任务持久化

├─ skills/ # Prompt-only 技能目录

├─ frontend/ # Vite 入口、features、legacy

├─ templates/agent_chat.html # 主页面模板

├─ static/dist/ # 前端构建产物

├─ packaging/ # Windows/macOS 打包

├─ requirements.txt

├─ package.json

└─ .github/workflows/build-release.yml

4.2 Agent 核心拆分

文件 / 模块	职责	读源码时关注点
agent/agent.py	BusinessAgent 主循环与上下文编排	消息裁剪、阶段控制、重试、工具结果回填
agent/tools/schemas.py	OpenAI function tool schema	工具名、参数、前置调用规则、确认机制
agent/tools/business/data.py	数据、图表、清洗、分析执行	行数阈值、异步任务、知识检索
agent/tools/business/export.py	Excel/Word/PPT 导出	方案确认、文件路径和异常处理
agent/prompts.py	系统 Prompt 与业务规则	SQL、知识库、图表、输出要求
agent/skills.py	加载 SKILL.md	YAML frontmatter、热加载、启用条件
agent/commands/*	斜杠命令注册和分发	解析、可用性、命令契约
agent/mcp_manager.py	外部 MCP 工具接入	stdio/SSE、进程白名单、异步桥接

4.3 前端结构

package.json 使用 Vite 7，要求 Node 20.19+、pnpm 11.7.0。构建命令先生成 dashboard bundle，再用独立配置生成 chat-app.js。聊天入口按固定顺序 side-effect import legacy/core、消息、命令、数据源、预览、流处理、设置、任务、会话、自动保存、更新、检查点、面板等模块。[R10]

5. 从 0 到 1 的创建路径

下面不是对作者真实提交历史的断言，而是依据当前结构复原出的“最合理工程演进顺序”。照此顺序重建，可以在每一阶段都得到可演示、可验证的增量。

阶段 0：定义边界与成功标准

只做分析助手，不让模型直接获得数据库凭据。
MVP 仅支持 CSV/Excel + 一个模型供应商 + 5 种常用图表。
所有查询只读、有限行数、有限执行时间；导出文件保存在专用工作目录。
验收标准：10 个自然语言问题中，至少 8 个可得到正确字段、查询和图表。

阶段 1：搭起 Flask 骨架与静态聊天页

创建 create_app() 工厂、/api/health、/api/chat/stream、/api/datasource/upload。
页面先只有消息列表、输入框、上传按钮和模型设置。
本地开发用 Flask，生产入口预留 Waitress/Gunicorn。
此时模型可以先返回回声；目标是打通请求、日志和错误显示。

阶段 2：建立数据源抽象

设计 DataSource 接口：list_tables、get_schema、sample_rows、query、close。
文件数据源用 Pandas/DuckDB；数据库用 SQLAlchemy 或原生驱动。
建立 session_id → active datasource 映射，避免所有用户共享全局连接。
把数据源元信息与上传文件分开保存，便于清理和迁移。

阶段 3：接入统一 LLM 配置

采用 OpenAI SDK 兼容接口，配置 provider、base_url、model、api_key。
实现模型列表、保存、删除、测试连接与默认模型。
严格避免 API key 进入前端日志和错误栈；生产环境优先从密钥服务或环境变量读取。
先验证普通对话，再验证 streaming，最后验证 tool calling。

阶段 4：定义工具协议与 Agent 循环

为 get_schema、query_data、run_analysis、select_chart、generate_chart 定义 JSON Schema。
模型返回 tool_calls 后，应用校验参数、执行函数、把结果作为 tool message 回填。
设置最大回合、最大 token、重复工具检测与总耗时。
建立事件模型：status、reasoning、tool_start、tool_result、artifact、error、final。

阶段 5：实现 NL2SQL 安全链路

强制先 get_schema，再允许 query_data。
用 sqlglot 解析 SQL，只允许 SELECT/CTE，禁止 DDL/DML、多语句和危险函数。
数据库使用只读账号；设置超时、最大扫描/返回行数。
错误反馈给模型时去除敏感连接信息，只返回可修复的结构性错误。

阶段 6：图表选择与渲染

用图表注册表描述每种图的字段角色、最少字段、数据类型和最大类别数。
先 select_chart 决定图形和字段映射，再 generate_chart。
交互图可用 Plotly/Pyecharts，导出文档时补充 Matplotlib 或截图。
给所有图表生成可追溯 metadata：来源查询、字段、过滤条件、生成时间。

阶段 7：加入 SSE 流式联调

后端以 generator 持续 yield data: JSON\n\n。
前端 EventSource 不适合携带 POST body 时，可用 fetch + ReadableStream 解析 SSE。
代理层关闭响应缓冲并延长读超时；每隔一定时间发送心跳。
断开连接时取消任务或标记为可恢复。

阶段 8：扩展 Skills 与 Commands

Skills 用 SKILL.md 提供领域方法和工作流，不执行任意 Python。
Commands 用注册表管理 /data、/status、/compact、/jobs 等确定性动作。
命令与技能必须声明可用条件，例如是否已连接数据源、是否启用工作区。
每回合热加载便于本地开发，但生产环境应增加缓存与签名/审核流程。

阶段 9：知识库、MCP 与工作区

知识库先做本地文档检索，再把 query_knowledge 暴露给 Agent。
MCP 工具统一转成 mcp__server__tool 命名，限制可启动进程和参数。
工作区提供文件读写、项目说明和输出归档；团队/Hook 作为后续协作能力。
外部工具默认低权限、显式启用、记录调用审计。

阶段 10：异步任务、导出与发布

大于阈值的分析、清洗、图表、查询进入 jobs 队列，前端轮询或接收事件。
Excel/Word/PPT 采用“方案 → 用户确认 → 生成”两阶段，避免误产出。
补齐单元测试、接口测试、端到端 smoke test。
最后做 Windows 安装包、macOS DMG、CI Release，而不是在 MVP 阶段投入。

图 3　一次自然语言分析请求的端到端执行序列

6. 本地构建与启动手册

6.1 环境要求

组件	建议版本	何时需要
Python	3.11（项目 lint 目标为 3.10）	始终需要
pip / venv	随 Python	隔离依赖
Node.js	≥ 20.19	仅重建前端时需要
pnpm	11.7.0	仅重建前端时需要
浏览器	Chrome / Edge 最新稳定版	调试 SSE 与前端
数据库驱动	requirements.txt 已含常用驱动	连接 MySQL/PostgreSQL 等时

6.2 Windows 从已下载目录启动

cd D:\path\to\Data-Analysis-Agent

py -3.11 -m venv .venv

.venv\Scripts\activate

python -m pip install --upgrade pip

pip install -r requirements.txt

python app.py

# 浏览器打开：http://127.0.0.1:5001

6.3 macOS / Linux

cd /path/to/Data-Analysis-Agent

python3.11 -m venv .venv

source .venv/bin/activate

python -m pip install --upgrade pip

pip install -r requirements.txt

python app.py

# 浏览器打开：http://127.0.0.1:5001

6.4 何时需要重建前端

仓库已包含 static/dist 时，只修改 Python 或模板通常可直接运行；修改 frontend/ 下源码、Vite 入口或资源打包逻辑时，再执行前端安装与构建。package.json 的 build 会连续构建 dashboard 与 chat-app 两个入口。[R10]

corepack enable

corepack prepare pnpm@11.7.0 --activate

pnpm install --frozen-lockfile

pnpm run build

6.5 启动参数

变量	作用	建议
PORT / AGENT_PORT	监听端口，默认 5001	端口冲突时修改
BAA_HOST	监听地址	本机使用 127.0.0.1；不要无鉴权暴露公网
BAA_WSGI	选择 waitress 或 gunicorn	Windows 用 waitress，Linux 可用 gunicorn
BAA_WORKERS	Gunicorn worker 数	SSE 场景从小值压测
BAA_SKIP_DEPENDENCY_CHECK	跳过启动依赖检查	容器/受管运行环境可开启

6.6 第一次启动后的最小验收

打开模型设置，填写 API Key，点击连接测试。
上传一个不超过 10 MB、字段清晰的 CSV。
先问“列出表结构和每列类型”，确认 schema 工具工作。
再问“按月份汇总销售额”，确认查询结果。
最后问“生成月度销售趋势折线图”，确认图表选择和生成。
导出一次 Excel 或报告，确认输出目录和下载路由。

建议先固定一个小样本数据集

联调不要直接用真实生产库。准备 1,000～10,000 行、字段类型明确、包含日期/类别/数值的样本，并维护 10 个标准问题及期望答案，能大幅缩短排查时间。

7. 前后端与 Agent 联调方法

7.1 分层联调，不要一次性全链路猜错

层	独立验证	通过标准	失败时先查
启动层	python app.py	5001 可访问、无依赖报错	venv、端口、日志目录
模型层	模型连接测试	能返回短消息	base_url、key、model 名称
数据源层	上传 / 连接 / schema	表名、字段、样例正确	文件编码、驱动、权限
工具层	直接调用 get_schema/query_data	结构化结果可序列化	参数校验、SQL、行数限制
Agent 层	最小工具调用问题	工具顺序正确	prompt、tool schema、模型兼容
流式层	查看 Network 流	持续收到事件且不缓冲	SSE 格式、代理超时、心跳
渲染层	图表/文件预览	资源可加载、下载可用	静态路径、CSP、文件 URL

7.2 浏览器侧检查

打开 DevTools → Network，过滤 chat/stream 或 EventStream 请求。
确认响应 Content-Type 为 text/event-stream，并且数据不是任务完成后一次性出现。
Console 中检查 JSON 解析、模块加载、静态资源 404、CORS 与未捕获异常。
Application 中检查本地配置和会话缓存，但不要把 API Key 输出到截图或日志。

7.3 后端侧检查

为每次请求生成 request_id / session_id，日志按一次对话串联。
记录工具名、耗时、输入摘要、返回行数，不记录完整密钥或整表数据。
对 LLM、数据库、MCP、文件导出分别设置超时，并区分可重试与不可重试错误。
SSE 生成器捕获 GeneratorExit，浏览器断开时停止后续昂贵任务。

7.4 Agent 工具调用调试

BusinessAgent 引入 compaction、retry、validation、reasoning tag parsing、prompt cache、workflow stage 与 MCP discovery，说明主循环不只是“发一次请求”。调试时必须把每一轮 messages、tool_calls、tool result size 和 stop reason 记录成可读 trace。[R5]

trace_id = new_id()

emit("status", {"trace_id": trace_id, "stage": "planning"})

response = llm.chat(messages=messages, tools=tool_schemas)

for call in response.tool_calls:

validated = validate_tool_call(call)

emit("tool_start", {"name": call.name})

result = execute_tool(validated)

emit("tool_result", {"name": call.name, "summary": summarize(result)})

messages.append(as_tool_message(call, result))

# Continue until final answer, max rounds, timeout, or cancellation.

7.5 推荐的事件协议

事件	字段示例	前端行为
status	stage, text, progress	更新顶部状态
reasoning	summary	显示可公开的步骤摘要
tool_start	name, args_summary	显示工具卡片加载态
tool_result	name, preview, row_count	更新工具卡片
artifact	type, url, title	显示图表/文件
warning	code, message	非阻断提示
error	code, message, retryable	显示错误和重试按钮
final	markdown, citations	结束消息并保存会话

8. 数据链路、NL2SQL 与图表链路

8.1 数据源接入

datasource API 支持 Excel/CSV、SQL 数据库、Google Sheets 和 HTTP API；文件扩展名至少覆盖 xlsx、xls、csv。数据与配置通过 data/ 下的 source、connector、session、workspace 等模块管理。[R9][R16]

8.2 NL2SQL 的正确控制面

模型先读取 get_schema；必要时再 get_table_detail 或 sample rows。
模型生成 SQL，但应用层用 sqlglot 解析，不接受无法解析或多语句输入。
白名单只允许 SELECT / WITH；限制表、函数、时间、返回行数和参数。
数据库账号本身设为只读；应用层校验不是最后一道防线。
查询结果转为紧凑 JSON/Markdown，超大结果写入临时表或异步任务。
模型根据结果解释，而不是根据自己猜测的 SQL 结果解释。

8.3 大数据任务阈值

数据工具实现中已经给出异步化阈值示例：分析大于约 1,000 行、图表或 profile 大于约 50,000 行、清洗大于约 50,000 行、查询大于约 100,000 行时转入任务系统。阈值应视机器配置和算法复杂度压测后调整。[R7]

8.4 图表选择器

chart selector 维护图表注册表，每种图包含字段角色、约束、数据格式与描述，并使用评分逻辑选图。工具 schema 还明确要求先 select_chart 再 generate_chart，避免模型直接凭名称生成不适配图形。[R6]

问题类型	推荐图表	必须检查
时间趋势	Line / Area	日期排序、粒度、缺失期
类别比较	Bar / Column	类别数量、长标签、排序
构成占比	Stacked Bar / Pie（类别少）	总和、类别数、零值
分布	Histogram / Box	样本量、异常值、分箱
相关关系	Scatter / Bubble	数值类型、离群点、尺度
转化路径	Funnel	阶段顺序、口径一致
地理	Map	地名/经纬度、地图资源

8.5 文档导出为什么采用“两阶段”

工具定义中包含 proposal / confirmation 类工具，再进入 generate_ppt、export_report 等生成动作。这种“先给大纲和内容计划，再确认生成”的方式可减少耗时、避免用户误触，并让文件结构在执行前可审阅。[R6]

9. Skills、Commands、知识库与 MCP

9.1 Skills：提示词化的领域工作流

skills/ 包含 arima、chart、dashboard、data、decile、funnel-analysis、gru、kmeans、logistic、ppt、prophet、regression、report、sarima、screening、sql、tree、trimming、var、winsorize 等目录。加载器读取 SKILL.md 的 YAML frontmatter 和正文，将其作为提示词能力注入；它不会从技能目录动态 import 任意 Python。[R13]

这是一项重要安全取舍

Skill 作者可以指导模型如何组合已审计工具，但不能仅靠放入一个 Python 文件获得任意代码执行。如需新增真实计算能力，应在 Function/ 或 agent/tools/ 中实现并审查，再由 Skill 编排。

9.2 Commands：确定性控制面

commands 目录提供 checkpoint、clear、compact、data、help、instruction、jobs、knowledge、mcp、new、sessions、skills、status、stop、teams 等命令。命令由注册表、解析器和 dispatcher 管理，适合“无需模型推理即可确定执行”的操作。[R14]

9.3 知识库：业务口径优先于猜测

工具 schema 明确要求在涉及业务指标、口径、规则时先 query_knowledge，再进行 SQL 或分析。这是数据 Agent 从“会算”走向“算对业务口径”的关键：同名指标可能有财务、销售、运营等不同定义。[R6]

9.4 MCP：外部工具的标准化扩展

MCP manager 同时支持 stdio 和 SSE transport，通过后台异步事件循环为同步 Flask 代码提供桥接；允许启动的本地命令限制在 uvx、uv、npx、node、python、python3、deno，并把外部工具映射为 mcp__server__tool 形式的 function schema。[R12]

MCP 联调项	验证方法	风险控制
连接	单独启动 server，验证 initialize/list_tools	固定版本、限制网络
工具发现	检查 schema 是否完整、参数是否可序列化	命名冲突隔离
调用	用最小参数执行一次	超时、输出大小、脱敏
断开重连	停止 server 后恢复	指数退避、最大重试
审计	记录 server/tool/耗时/结果摘要	不记录密钥和完整敏感数据

10. 测试、验收与故障排查

10.1 最小自动化测试矩阵

类别	用例	预期
启动	缺少可选依赖 / 端口占用	给出可操作错误，不静默退出
模型	错误 key、错误 model、超时	分类错误、允许重试
上传	CSV 编码、空文件、超大文件、重复列	明确提示并清理临时文件
Schema	多表、中文列名、日期/数值混合	字段与类型稳定
SQL	SELECT、CTE、注入、DELETE、多语句	只读通过，危险语句拒绝
工具	参数缺失、类型错误、工具不存在	校验失败不执行
图表	类别过多、空数据、单点时间序列	降级或解释原因
SSE	长任务、浏览器断开、代理缓冲	连续事件、可取消
导出	路径非法、文件占用、中文字体	安全文件名、可重试
会话	保存、恢复、清空、压缩	状态一致
MCP	server 离线、慢响应、坏 schema	隔离错误，不拖垮主会话

10.2 标准验收问题

“有哪些表？每张表多少行？”——验证 schema 与元数据。
“按月汇总销售额，并计算环比。”——验证日期处理、聚合和窗口计算。
“贡献收入最高的 10 个客户是谁？”——验证排序与 Top-N。
“各地区销售额和毛利率对比，生成柱线组合图。”——验证多指标图表。
“对客户做 K=3 聚类并解释每一类。”——验证 Skill + 分析工具。
“生成一份管理层销售复盘 PPT。”——验证方案确认与文件生成。

10.3 高频故障

现象	可能原因	排查 / 修复
页面打不开	端口占用、依赖失败	查看启动日志；换 PORT；确认 venv
模型测试失败	base_url/model/key 不匹配	用供应商最小请求验证；检查代理
上传后无表	编码、文件格式、解析器	用 Pandas 单独读取；检查临时目录
模型不调用工具	模型不支持 tool calling 或 prompt 冲突	换兼容模型；缩短工具列表；检查 schema
重复调用同一工具	结果过大、模型未理解、缺少循环保护	压缩结果；加入重复调用检测和最大回合
SQL 报字段不存在	schema 过期、大小写/中文名	强制刷新 schema；引用字段名
图表空白	静态资源/数据映射/浏览器错误	检查 Console、图表 payload 和容器尺寸
SSE 最后一次性出现	代理或服务器缓冲	关闭 buffering；设置正确 MIME；发送心跳
PPT/Word 中文乱码	字体缺失	安装/嵌入企业字体；模板指定东亚字体
MCP 卡住	子进程死锁或服务超时	独立启动调试；设置调用超时和 kill

11. 安全、许可与工程风险

11.1 风险清单

风险	当前信号	建议
API Key 本地保存	配置管理器使用本地 JSON 持久化	生产改为系统钥匙串/Secret Manager；文件权限最小化
数据库误写	应用有 SQL 解析依赖但不能替代账号权限	只读账号 + sqlglot AST 校验 + 超时/限行
公网暴露	Flask/WSGI 可监听外部地址	默认 127.0.0.1；外网必须鉴权、TLS、反向代理
Prompt Injection	知识库、文件、MCP 输出会进入上下文	标记不可信内容；工具参数二次校验；最小权限
MCP 供应链	可启动本地命令并访问外部服务	只启用可信 server；固定版本；审计网络与文件权限
文件隐私	上传、缓存、输出、会话落盘	明确保留周期；一键清理；目录隔离和加密
依赖可复现性	requirements 注释提到 lock，当前安装常回退到 requirements	发布前生成并校验 lock/SBOM，做漏洞扫描
文档与代码漂移	默认模型表与代码内置项存在差异	CI 加配置一致性测试；发布说明绑定 tag
许可证	CC BY-NC 4.0	商用、SaaS、内部收费场景先获得授权

11.2 许可特别提醒

仓库当前声明采用 Creative Commons Attribution-NonCommercial 4.0 International，未经授权不得用于商业目的。即使只是在企业内部部署，也应由法务根据使用方式、收费关系和衍生分发判断，不能把“代码公开”自动理解为“可自由商用”。[R1][R15]

11.3 发布前必须补齐的工程控制

固定 Python/Node/pnpm 版本与依赖锁；生成 SBOM。
对 SQL、文件路径、MCP 参数做结构化校验，拒绝字符串拼接。
所有密钥使用脱敏日志；错误页面不回传堆栈。
输出目录采用随机不可猜文件名和过期清理。
建立数据分级：公开、内部、敏感、禁止进入外部模型。
对模型供应商的日志保留与数据使用政策做供应商评估。

12. 智析Agent 的二次开发路线

12.1 品牌与界面

修改 templates/agent_chat.html 的产品名、Logo、启动文案和建议词。
统一 static 资源与安装包名称；保留项目版本、许可证与第三方声明。
把“模型、MCP、工作目录、只读”等专业设置放入高级面板，降低业务用户认知负担。

12.2 业务能力

目标	优先修改位置	实现方式
企业指标口径	知识库 + prompts	录入指标定义、维度、过滤与例外
行业分析流程	skills/<skill>/SKILL.md	写标准步骤、输入要求、验收条件
新算法	Function/Analyze + tool schema	注册算法，限制参数，补单测
新数据源	api/datasource.py + data/connector	实现连接、schema、query、关闭
新图表	Charts_generation + chart selector	增加字段角色、约束和渲染器
新导出模板	Function/Output	企业 Word/PPT 模板、页眉页脚、主题
外部系统	MCP server	用标准协议接 CRM、工单、搜索等

12.3 推荐的改造顺序

固定可运行版本，建立自己的 fork、分支策略和 CI。
先改品牌，不改核心逻辑；做一次完整回归。
接入一个企业模型网关和一个脱敏测试数据源。
沉淀 20～50 个业务指标到知识库。
为三个高频场景写 Skill，并建立标准答案集。
再接企业数据库、MCP 和报告模板。
最后做 SSO、权限、审计、多租户与部署高可用。

不要直接在 BusinessAgent 主循环里堆业务 if/else

行业逻辑优先放知识库、Skill、Command 或独立 Tool；主循环只负责通用编排。这样才能在升级上游代码时降低冲突。

13. 两周 / 四周实施计划

13.1 两周：完成可演示的企业内测版

时间	目标	产出
第 1–2 天	环境与基线	固定版本、启动成功、依赖锁、样本数据
第 3–4 天	模型和数据源	企业模型网关、CSV + 测试数据库
第 5–6 天	核心闭环	schema、查询、图表、SSE 可观测
第 7–8 天	业务口径	20 个指标知识、2 个 Skill
第 9–10 天	导出和回归	Excel/Word/PPT 冒烟测试、10 个标准问题

13.2 四周：完成可受控试运行版

周	重点	验收
第 1 周	基线、环境、核心链路	开发机和测试机一致运行
第 2 周	业务知识、Skill、报告模板	核心场景准确率达标
第 3 周	权限、安全、审计、MCP	风险评审和渗透测试问题闭环
第 4 周	性能、部署、运维、培训	试运行、监控、回滚与用户手册

13.3 建议指标

指标	目标参考
模型工具调用成功率	≥ 95%
标准问题结果正确率	≥ 85%，关键财务口径 ≥ 95%
小数据集首个事件时间	≤ 2 秒
常规问题总响应时间	≤ 20 秒（视模型与数据库）
危险 SQL 拦截率	100%
敏感信息日志泄漏	0
导出文件成功率	≥ 98%
断线/失败可恢复率	≥ 95%

附录 A：常用命令

A.1 Python

# 进入环境

.venv\Scripts\activate # Windows

source .venv/bin/activate # macOS/Linux

# 安装与运行

pip install -r requirements.txt

python app.py

# 代码质量（以仓库配置为准）

ruff check .

python -m unittest discover

A.2 Frontend

corepack enable

corepack prepare pnpm@11.7.0 --activate

pnpm install --frozen-lockfile

pnpm run build

pnpm run lint

pnpm run format:check

A.3 生产运行思路

# Windows / cross-platform

set BAA_WSGI=waitress

set BAA_HOST=127.0.0.1

set PORT=5001

python app.py

# Linux（示例；worker 数需压测）

export BAA_WSGI=gunicorn

export BAA_WORKERS=2

export BAA_HOST=127.0.0.1

export PORT=5001

python app.py

A.4 联调记录模板

Trace ID:

Session ID:

Model provider / model:

Data source:

User question:

Expected tool sequence:

Actual tool sequence:

SQL / analysis summary:

SSE events:

Final answer:

Artifacts:

Latency:

Error and root cause:

Fix / regression case:

附录 B：关键源码索引与参考资料

以下引用均为本报告撰写时检查的 GitHub 主分支页面。主分支会变化，正式实施时应记录 tag 或 commit hash。

编号	内容	地址
R1	仓库主页与 README：定位、功能、安装、模型、数据源、图表、许可证	https://github.com/Zafer-Liu/Data-Analysis-Agent
R2	app.py：依赖检查、路径、日志、Flask 工厂、Waitress/Gunicorn、端口	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/app.py
R3	api/__init__.py：Flask application factory 与 Blueprint 注册	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/api/__init__.py
R4	api/chat.py：SSE 对话入口、激活项、数据上下文与 BusinessAgent 构建	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/api/chat.py
R5	agent/agent.py：BusinessAgent、重试、压缩、阶段、工具循环	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/agent/agent.py
R6	agent/tools/schemas.py：工具 JSON Schema、调用顺序与导出确认	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/agent/tools/schemas.py
R7	agent/tools/business/data.py：数据工具、分析、图表与异步阈值	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/agent/tools/business/data.py
R8	LLM/llm_config_manager.py：OpenAI SDK 兼容模型配置与连通性测试	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/LLM/llm_config_manager.py
R9	requirements.txt：Python 依赖栈	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/requirements.txt
R10	package.json 与 Vite 配置：Node/pnpm 版本与多入口构建	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/package.json
R11	templates/agent_chat.html：截图所示主页面与数据源/设置入口	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/templates/agent_chat.html
R12	agent/mcp_manager.py：stdio/SSE、异步桥接、命令允许列表	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/agent/mcp_manager.py
R13	agent/skills.py 与 skills/：Prompt-only SKILL.md 加载	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/agent/skills.py
R14	agent/commands/：斜杠命令注册与分发	https://github.com/Zafer-Liu/Data-Analysis-Agent/tree/main/agent/commands
R15	LICENSE：CC BY-NC 4.0	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/LICENSE
R16	api/datasource.py 与 data/：文件、数据库、Sheets、HTTP 数据源	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/api/datasource.py
R17	.github/workflows/build-release.yml：Windows/macOS 构建发布	https://github.com/Zafer-Liu/Data-Analysis-Agent/blob/main/.github/workflows/build-release.yml