基于 GitHub 主分支 / v1.1.0 LTS 的源码级逆向梳理
图 1 * 智析* Agent 当前本地运行界面（用户提供截图）
|----------|------------------------------------------------|
| 报告对象 | Zafer-Liu / Data-Analysis-Agent（本地项目名：智析Agent） |
| 分析范围 | 启动入口、前后端架构、Agent 核心、数据工具、图表、技能、MCP、打包发布与联调 |
| 报告日期 | 2026-07-17 |
| 结论性质 | 基于当前公开源码的工程复原；不等同于作者真实开发时间线 |
目录
-
执行摘要
-
产品目标与完整用户旅程
-
技术选型与架构拆解
-
源码目录与模块职责
-
从 0 到 1 的创建路径
-
本地构建与启动手册
-
前后端与 Agent 联调方法
-
数据链路、NL2SQL 与图表链路
-
Skills、Commands、知识库与 MCP
-
测试、验收与故障排查
-
安全、许可与工程风险
-
智析Agent 的二次开发路线
-
两周 / 四周实施计划
附录 A：常用命令
附录 B：关键源码索引与参考资料
1. 执行摘要
Data-Analysis-Agent 是一个以"自然语言驱动数据分析"为核心的本地 Web Agent。用户上传 Excel/CSV、连接 SQL 数据库或其他数据源后，系统把问题转成受控工具调用：读取结构、生成并执行查询、完成统计分析、选择图表、导出 Excel/Word/PPT，并通过 SSE 将过程事件持续推送到浏览器。其本质不是"让大模型直接碰数据库"，而是一个由大模型负责规划、由应用工具负责执行的分析操作系统。R1R4R6
|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| 一句话判断 这是一个"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 模块完成渐进式模块化。R10R11
图 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 等模块管理。R9R16
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，未经授权不得用于商业目的。即使只是在企业内部部署，也应由法务根据使用方式、收费关系和衍生分发判断，不能把"代码公开"自动理解为"可自由商用"。R1R15
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。
结语
智析Agent 已经具备较完整的数据 Agent 工程骨架。真正决定能否进入生产的，不是再增加多少模型或图表，而是能否把业务口径、数据权限、SQL 安全、工具可观测性、测试样本和部署治理做成稳定体系。建议以本报告的"分层联调 + 标准问题集 + 最小权限"作为二次开发主线。