pyspur

PySpur：给 AI 工程师用的可视化工作流调试台，迭代速度提升 10 倍

痛点切入：当调 Prompt 变成一场噩梦

你有过这样的经历吗？凌晨两点，你坐在电脑前，第 37 次修改 AI Agent 的 prompt，盯着终端里那一行行冷冰冰的 JSON 输出，试图从中找出为什么 agent 总是在第三步犯迷糊。日志像瀑布一样刷过，错误藏在某个你不经意就会错过的角落，好不容易定位到问题，改了，再跑，又出新的 bug。就这样循环往复，直到天亮。

这是每一位 AI 工程师都经历过的 Prompt Hell（提示词地狱）。构建一个可靠的 AI Agent，远不只是写几行 prompt 那么简单：工作流步骤之间的隐藏依赖让人防不胜防，JSON 输出是否符合预期只能靠肉眼看，循环执行的 Agent 更是调试的重灾区。

PySpur 就是来解决这个问题的。它出身于一支真实踩过坑的团队：2024 年初，他们上线了一款 AI 平面设计 Agent，迅速积累了数千用户，却在可靠性上焦头烂额——现有的调试工具根本不够用。团队最终决定自己造一个工具，这就是 PySpur 的由来。

图1：用 PySpur 定义测试用例，确保 Agent 行为可复现

核心理念：用测试驱动重新定义 AI Agent 开发

PySpur 的开发哲学借鉴了软件工程中成熟的测试驱动开发（TDD）理念——不是凭感觉调参，而是先定义测试用例，明确 Agent 在各种输入下应该如何表现，再开始构建工作流。

整个开发流程分为四个阶段：定义测试用例、构建 Agent、疯狂迭代、部署上线。每个阶段 PySpur 都提供了对应的可视化工具，让开发者从繁琐的终端操作中解放出来。

图2：通过图形界面或 Python 代码构建 AI Agent

架构解析：前后端分离的模块化设计

后端（Python/FastAPI）：基于 FastAPI 构建，提供完整的 RESTful API 层。核心模块包括：

• pyspur/execution/：工作流执行引擎，负责任务调度与执行上下文管理
• pyspur/nodes/：节点工厂模式实现，支持通过装饰器注册自定义 Python 节点
• pyspur/models/management/alembic/：数据库迁移层，基于 SQLAlchemy + Alembic 管理 PostgreSQL schema
• pyspur/api/：细粒度的 API 端点（workflow_run、rag_management、evals 等 15+ 个独立模块）

前端（TypeScript/React + Xyflow）：界面基于 Xyflow（原 React Flow）实现节点图编辑器。UI 组件库使用 HeroUI，代码编辑器采用 CodeMirror，状态管理使用 Redux Toolkit。

技术栈亮点：

• LLM 接入：通过 litellm 统一封装，支持 100+ LLM 供应商（OpenAI、Anthropic、DeepSeek、Ollama 等），无需修改代码即可切换
• 向量数据库：支持 ChromaDB、Pinecone、Qdrant 等多种向量数据库，RAG 流程开箱即用
• 数据库：开发用 SQLite，生产用 PostgreSQL 17，ORM 层使用 SQLAlchemy
• 异步任务：基于 asyncio 原生异步，任务执行与实时日志推送结合

图3：PySpur 的模块化节点体系，支持多种集成

核心功能：从工作流设计到评估的全链路覆盖

1. 可视化工作流编辑器

拖拽式节点编辑器，基于 Xyflow 构建。用户可以在画布上自由组合 LLM 调用、工具执行、条件分支、循环等节点，实时预览 Agent 的执行路径。与传统的代码配置相比，这种方式让复杂工作流的全局视图一目了然。

2. 人在环路断点机制

这是 PySpur 最具特色的功能之一。Agent 运行到关键节点时可以自动暂停，等待人工审批后再继续。这对需要质量把关的生产工作流至关重要——比如在客服 Agent 发送邮件之前，暂停等待主管确认。

图4：人在环路断点，在关键节点暂停等待人工审批

3. 节点级调试

PySpur 提供了比传统日志输出精细得多的调试能力。每个节点的输入、输出、执行时间、Token 消耗都能单独查看，支持单步执行，彻底告别盲调时代。

图5：节点级调试界面，每个节点的执行细节一览无余

4. 带记忆的循环

PySpur 的循环节点不是简单的 for 循环，而是带有状态记忆的迭代执行——每次迭代的上下文会累积保存，供下一次迭代使用。这是构建 ReAct 风格 Agent 的核心能力，也是让 Agent 能够真正思考的关键机制。

图6：带记忆的循环节点，适合构建 ReAct 风格 Agent

5. RAG 全流程支持

PySpur 内置了完整的 RAG（检索增强生成）流程：从文档解析（PDF、Word、PPT）、分块策略、嵌入模型选择，到向量数据库存储（ChromaDB/Pinecone/Qdrant），再到查询与结果注入，全部可在界面中可视化配置，无需写一行代码。

图7：RAG 分块配置界面，支持多种文档格式和分块策略

6. 多模态支持

Agent 可以接收并处理视频、图像、音频、PDF 等多模态输入。视频内容可以被转录后用于后续分析，图片可以直接喂给支持视觉的 LLM（如 GPT-4V、Claude Vision），极大扩展了 Agent 的应用场景边界。

图8：多模态输入支持，处理视频、图像、音频等多种格式

7. 自动化评估

PySpur 内置了评测框架，支持在 MMLU、GSM8K、Math 等标准数据集上评估 Agent 表现。所有评估结果持久化存储，支持历史对比，帮助开发者量化 Agent 能力的改进与退化。

图9：自动化评估界面，在标准数据集上量化 Agent 能力

上手门槛：多种接入方式，总有一款适合你

方式一：pip 一键安装（最简单）

pip install pyspur
pyspur init my-project
pyspur serve --sqlite

运行后在 http://localhost:6080 打开浏览器即可。

方式二：Docker Compose 一键部署（生产推荐）

docker compose up

包含后端（FastAPI + PostgreSQL）、前端（Nginx 托管静态资源），开箱即用。

方式三：本地开发调试

克隆仓库后，通过 Dev Container 或本地环境配置，进入 frontend/ 和 backend/ 目录分别启动开发服务。由于支持热重载，开发体验与标准 Web 开发无异。

图10：迭代开发界面，实时查看 Agent 执行结果

图11：工作流可一键部署为 API，无缝集成到其他系统

当前局限与争议点

1. Windows 不支持：官方文档明确标注了 Windows/PC 开发不受支持，仅提供 Unix 类系统开发指南。Windows 用户只能通过 WSL2 或 Docker 运行。

2. 版本尚处于 Beta（v0.1.18）：虽然功能已经相当丰富，但作为 Beta 版本，生产环境使用需自行评估稳定性风险。数据库 schema 仍在频繁变更（已记录 15 个 migration 版本），意味着数据迁移可能带来额外维护成本。

3. 前端依赖较重：项目采用 React + TypeScript + Xyflow + HeroUI + Redux Toolkit 的重型前端栈，对前端开发能力要求较高，也是 bug 报告的主要来源之一。

4. 部署仍需一定技术门槛：虽然 Docker Compose 简化了部署，但配置 LLM API Key、多供应商环境变量、PostgreSQL 连接等，对于完全没有 DevOps 经验的开发者来说仍有一定门槛。

行业意义：为什么 PySpur 值得关注

PySpur 代表了 AI Agent 开发工具链的一个新兴方向——从代码即一切向可视化加测试驱动转型。随着 AI Agent 应用场景的爆发，如何高效地构建、调试和部署 Agent 已成为刚需。传统的做法是写 Python 代码加大量 print 调试，这种方式在 Agent 规模扩大后很快会遇到瓶颈。

PySpur 的出现填补了这一空白：它不是要替代代码，而是给代码插上可视化翅膀。开发者可以继续用 Python 写自定义节点，同时享受图形化调试和管理的便利。这种代码优先、可视化辅助的思路，在同类工具（如 LangFlow、Dify、Flowise 等）中也有体现，但 PySpur 凭借其对测试驱动开发的深度支持、对循环和断点的原生设计，以及对 100+ LLM 供应商的统一封装，在 AI 工程师群体中赢得了良好口碑。

从增长曲线看，项目自 2024 年 9 月上线以来，已积累 5700+ Stars、400+ Forks，贡献者活跃度较高（核心团队 Srijan Patel 和 Jean Kaddour 分别贡献了 1500+ 和 1200+ commits），文档覆盖 7 种语言，这些信号都表明项目处于健康发展的状态。

如果你正在构建 AI Agent，或者已经被 Prompt 调优折磨得夜不能寐，PySpur 值得一试。它不能解决所有问题，但至少能让你在调试 Agent 时，不用再一个人对着黑屏终端干瞪眼了。

图12：PySpur 路线图中的自我提升功能——让 Agent 能够自主改进自身