AI 工作流
编排器

1.1 XteVision Prodigy 是什么？

XteVision Prodigy 是一款 自托管的、基于可视节点界面的 AI 工作流构建器，面向希望借助直观的拖放界面来组合复杂 AI 流水线的工程师、研究员和团队。它提供多模态 AI 支持、长期记忆（Wisdom）、智能体工具调用、RAG 嵌入以及多个 AI 后端的集成—all 在本地网络上运行，拥有完全的数据所有权。

1.2 核心能力

• 可视节点编辑器 — 拖放画布，用于组合 AI 工作流
• 会话认证 — 所有 AI 操作的用户注册和登录
• 长期记忆（Wisdom） — 基于 PostgreSQL 的知识库，支持自动召回和自动存储
• 智能体工具调用 — 网络搜索、浏览器自动化、文件 I/O、数据库查询等
• RAG / 嵌入 — 通过 Ollama 使用 nomic-embed-text 进行语义分块选择
• 多模态 AI — 通过图像节点提供原生视觉支持（Qwen-VL、LLaVA 等）
• 多个 AI 后端 — MLX、LM Studio、Ollama 和 GitHub Copilot（桥接）
• 文档提取 — PDF/DOCX/XLSX/PPTX/TXT/CSV 解析
• 数据库集成 — 从工作流节点直接查询 MySQL/MariaDB
• 网络搜索 — SearXNG 元搜索，可配置引擎和语言
• 触发系统 — 用布尔门控任何 AI 节点进行条件路由
• 插件驱动的架构 — 可扩展的节点目录，基于清单的发现
• HUD 控制台 — 用于工具调用、记忆事件、错误的实时抬头显示
• 工作流模板 — 预置的 JSON 工作流，便于快速部署

1.3 目标用户

• 构建多步流水线的 AI 工程师
• 需要可复现 AI 工作流的研究团队
• 需要数据本地化 AI 编排的企业
• 在原型设计智能体系统的开发者
• 集成多个 AI 后端（本地 + 云端）的团队

2.1 高层架构

┌─────────────────────────────────────────────────────────┐
│              浏览器 (LAN 上任意设备)                  │
│                    HTTPS / LAN                            │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│           Kali Linux 服务器 (192.168.1.4)                │
│  ┌──────────────────────────────────────────────────┐  │
│  │        proxy_server.py (端口 9999)                │  │
│  │  • 托管 UI (HTML/CSS/JS)                        │  │
│  │  • CORS 代理 → AI 后端                          │  │
│  │  • 认证 (PostgreSQL 中的会话令牌)            │  │
│  │  • Wisdom 长期记忆 (PostgreSQL)           │  │
│  │  • 数据库查询 (MySQL/MariaDB)                       │  │
│  │  • 文档提取 (PDF/DOCX/XLSX 等)      │  │
│  │  • 工具执行 (网络搜索、浏览器等)     │  │
│  └──────────────────────────────────────────────────┘  │
│  PostgreSQL (端口 5432)    SearXNG (端口 8888)         │
└──────────────────────┬─────────────────────────────────┘
                       │ LAN (192.168.10.3)
┌──────────────────────▼─────────────────────────────────┐
│              Apple Silicon Mac                          │
│  ┌────────────┐ ┌──────────┐ ┌──────┐ ┌──────────┐   │
│  │ MLX 服务器 │ │LM Studio │ │Ollama│ │ Copilot  │   │
│  │ 端口 5010  │ │端口 1234 │ │端口  │ │ 桥接   │   │
│  │            │ │          │ │11434 │ │端口 5015 │   │
│  └────────────┘ └──────────┘ └──────┘ └──────────┘   │
└───────────────────────────────────────────────────────┘

2.2 通信流程

1. 浏览器 → 代理服务器：带会话认证的 HTTPS 请求（X-Session-ID 请求头）
2. 代理服务器 → AI 后端：CORS 代理转发到 MLX、LM Studio、Ollama 或 Copilot 桥接
3. 代理服务器 → PostgreSQL：Wisdom 记忆、用户会话、知识库查询
4. 代理服务器 → SearXNG：网络搜索元搜索，可配置引擎
5. 代理服务器 → Playwright：用于智能体网页交互的浏览器自动化
6. 代理服务器 → 浏览器：包含工作流执行结果、SSE 流式传输的 JSON 响应

2.3 部署模型

Prodigy 面向 本地优先、网络可访问的部署 设计：

• 代理服务器运行在专用的 Kali Linux 机器上（192.168.1.4）
• AI 后端运行在 Apple Silicon Mac（192.168.10.3）上以优化 GPU/神经引擎利用率
• 可通过 HTTPS 从 LAN 上任意设备访问
• 可选反向代理用于公开访问（prodigy.xtevision.net）
• 所有数据保留在本地基础设施上（除可选的 Copilot 云端访问外）

4.1 前置条件

• Kali Linux / Debian 服务器（推荐 192.168.1.4）
• Apple Silicon Mac（192.168.10.3，用于 AI 后端）
• PostgreSQL（端口 5432，用于 Wisdom 记忆和认证）
• SearXNG（端口 8888，网络搜索可选）
• Python 3.8+（用于代理服务器）

4.2 服务器设置（Kali Linux）

步骤 1：安装 Python 依赖

pip install psycopg2-binary pymysql pypdf python-docx openpyxl \
            python-pptx chardet bcrypt playwright

# 可选：Playwright 浏览器（用于 playwright_browse 工具）
playwright install chromium

# 可选：agent-browser CLI，用于更丰富的手动浏览器自动化
npm install -g agent-browser

# 可选：文档节点内的 OCR 支持
sudo apt install tesseract-ocr poppler-utils

步骤 2：数据库设置

# 创建 Prodigy PostgreSQL 数据库和表
psql -U postgres -f postgres.sql

# 应用会话认证表
psql -U postgres -d prodigy -f sql_auth_setup.sql

步骤 3：启动服务器

cd /home/xteve/prodigy
./start.sh
# 或直接运行：
python3 proxy_server.py

步骤 4：访问应用

局域网:     http://192.168.1.4:9999
公开访问:  https://prodigy.xtevision.net
直连:  http://192.168.1.4:9999

4.3 AI 后端设置（Apple Silicon Mac）

# MLX 服务器
mlx_lm.server --model <model-path> --port 5010

# LM Studio（GUI - 自动启动）

# Ollama
ollama serve  # 端口 11434

# GitHub Copilot 桥接
cd /path/to/copilot
node copilot_bridge.mjs

4.4 首次设置

1. 注册账号：在登录界面点击“注册”创建用户
2. 登录：用你的凭据认证（会话令牌存储在 sessionStorage 中）
3. 配置 AI 后端：编辑 config.json 设置后端 URL 和默认模型
4. 导入工作流模板：使用导入按钮从 workflows/ 加载预置工作流
5. 测试节点：添加输入节点 → AI 节点 → 退出节点，然后点击运行

5.1 目录布局

prodigy/
├── index.html                    # 主 UI 入口
├── styles.css                    # 应用样式（明/暗模式）
├── config.json                   # 运行时配置（后端、SearXNG、嵌入、Wisdom 数据库）
├── proxy_server.py               # Python HTTP 服务器（端口 9999）
├── copilot_bridge.mjs            # GitHub Copilot ↔ OpenAI 桥接（端口 5015）
├── start.sh                      # 便捷启动脚本
├── postgres.sql                  # PostgreSQL 模式（knowledge_base、users、sessions）
├── sql_auth_setup.sql            # 认证表设置
├── js/
│   ├── main.js                   # 入口点
│   ├── state.js                  # 全局状态与后端配置
│   ├── constants.js              # NODE_TYPES 枚举、节流值
│   ├── utils.js                  # fetchWithTimeout、Abort 控制器、URL 辅助
│   ├── logic/
│   │   ├── execution.js          # 核心工作流引擎 — 所有节点执行逻辑
│   │   └── workflow.js           # 保存 / 加载 / 导入 / 导出
│   └── ui/
│       ├── auth.js               # 登录 / 注册 UI
│       ├── connections.js        # SVG 连接线绘制
│       ├── dashboard.js          # 仪表盘与工作流生成
│       ├── node_manager.js       # 节点创建、设置面板
│       ├── playground.js         # 画布、拖拽、平移、缩放
│       └── priority_manager.js   # 执行顺序拖放
├── workflows/                    # 预置工作流模板
│   ├── incident_triage_escalation.json
│   ├── customer_support_triage.json
│   ├── competitive_intel_brief.json
│   ├── sql_ops_assistant.json
│   ├── deep_research_sweep.json
│   ├── schema_migration_checklist.json
│   ├── db_incident_response.json
│   ├── xlsx2wisdom.json
│   ├── marketing.json
│   ├── software.json
│   ├── agency.json
│   └── developer/                # 软件交付代理模板
│       ├── software_development_agency_sota.json
│       ├── software_development_agency_enterprise_saas.json
│       ├── software_development_agency_ai_agent_platform.json
│       ├── software_development_agency_regulated_internal_tool.json
│       └── software_development_agency_parallel_specialists.json
├── plugins/                      # 节点插件（内置 + 清单）
└── logs/
    └── app.log                   # 应用日志

5.2 模块依赖

main.js（bootstrap）
  ├── state.js
  ├── constants.js
  ├── utils.js
  ├── logic/execution.js → state.js、constants.js、utils.js
  ├── logic/workflow.js → state.js、utils.js
  ├── ui/auth.js → state.js、utils.js
  ├── ui/connections.js → state.js、playground.js
  ├── ui/dashboard.js → state.js、workflow.js、node_manager.js
  ├── ui/node_manager.js → state.js、constants.js、execution.js
  ├── ui/playground.js → state.js、connections.js、constants.js
  └── ui/priority_manager.js → state.js、workflow.js

7.1 输入 / 输出节点

7.2 数据库节点

7.3 网络 / 搜索节点

7.4 AI / 推理节点

7.5 角色 / 代理节点

7.6 逻辑 / 控制节点

7.7 项目 / 通信节点

7.8 工业 / 专用节点

8.1 插件接口（IProdigyNode）

所有节点类型都通过插件注册表定义。每个节点插件提供如下元数据：

• id — 节点类型的唯一标识符
• nodeType — 用于执行路由的枚举值
• title — 在工具栏和节点面板中的显示名称
• description — 仪表盘架构师在告知 AI 哪些节点类型可用时使用
• ports — 用于连接验证的输入和输出端口定义
• runtime capabilities — 工具调用、Wisdom 集成、RAG 支持等

8.2 标准能力

class IProdigyNode:
    def Initialize(self, config): ...
    def Execute(self, input_data, ctx): ...
    def Report(self): ...
    def Hibernate(self): ...
    def UpdateConfig(self, new_config): ...

8.3 插件生命周期

1. 发现：插件在服务器启动时从 plugins/ 目录加载
2. 注册：每个插件向中央节点目录注册自己
3. 执行：工作流引擎根据 nodeType 将执行路由到适当的插件
4. 热插拔：插件可以在不重启服务器的情况下重新加载（WIP）

8.4 仪表盘集成

仪表盘工作流架构师读取实时插件注册表，并在生成工作流时使用每个插件的 description 字段。这使生成的工作流与实际节点目录保持一致，包括新的角色节点和任何未来的清单加载插件。

9.1 后端配置

后端在 config.json 的 backends 键下配置。每个后端都有一个 URL 和默认模型。

9.2 仪表盘路由策略

• 工作流生成的默认：ollama 配合 gemini-3-flash-preview:latest（低成本）
• 私有来源（上传的文档、DB 节点、Wisdom、项目工作）：优先路由到本地后端
• 公开安全的编码任务：在付费模型之前优先使用 GitHub Copilot 免费模型
• 混合敏感度的工作流：Prodigy 在云端节点前插入本地 AI Decider + Logic Switch 以门控不安全内容
• 本地重度 AI 工作：顺序执行而非并行展开，以尊重 Apple Silicon 上共享的 VRAM 预算

9.3 GitHub Copilot 桥接

桥接将 OpenAI 兼容请求转换为 GitHub Copilot SDK 调用，并独立运行在 Apple Silicon Mac 上：

cd /path/to/copilot
node copilot_bridge.mjs

# 需要时覆盖配置路径：
COPILOT_BRIDGE_CONFIG_PATH=/path/to/copilot_bridge.config.json node copilot_bridge.mjs

可用的 Copilot 模型

桥接同时支持 流式（stream: true）和非流式请求，并对每个模型 复用会话 以避免每次请求的握手开销。

桥接本地浏览器工具

• playwright_browse — 在 Apple Silicon Playwright HTTP 桥接的 /browse 之上的高级渲染页面浏览/读取工具
• agent_browser — 用于 open/click/fill/press/wait/snapshot/get/is 操作的低级结构化浏览器自动化

10.1 基本流程

1. 添加节点：点击工具栏按钮将节点添加到画布
2. 连接节点：从输出端口（节点底部）拖到输入端口（顶部）以连接节点
3. 运行：点击 运行 或启用 自动运行（每 2 秒在输入变化时重新运行）

10.2 示例工作流

网络搜索 → AI 摘要

[输入: 主题] → [SearXNG] → [AI: 总结结果] → [退出]

视觉分析

[图片上传] → [AI（视觉模型）] → [退出]

带长期记忆的文档问答

[文档] → [AI（开启 Wisdom 召回）] → [Wisdom 节点: 存储结果] → [退出]

条件路由

[输入] → [AI Decider] → true 端口  → [AI: 处理成功] → [退出]
                       → false 端口 → [AI: 处理失败] → [退出]

10.3 触发门控

将任意节点的输出连接到 AI / Brainstorm / Translator / Decider 节点的 触发 端口。下游节点仅在触发信号求值为 true 时执行。

10.4 工作流持久化

• 自动保存：工作流在每次变更时保存到 localStorage
• 导出：将当前工作流下载为 JSON 文件
• 导入：从任意 JSON 文件加载工作流

10.5 工作流模板

预置模板位于 workflows/。通过工具栏中的 导入 按钮导入。

10.6 开发代理模板

workflows/developer/ 类别包含软件交付代理模板。它们都通过在解读客户简报之前用 项目 节点锁定项目代码库，并使用角色节点加上治理门控，来减少复杂客户请求上的歧义。

11.1 概览

AI 节点可以在推理前自动从 PostgreSQL knowledge_base 表中召回相关条目，并在成功运行后存储新事实。

11.2 工作原理

• 召回：使用参数化的 ILIKE 全文搜索 — 防注入安全
• 存储：当“自动存储到 Wisdom”启用时由 AI 节点自动触发
• 直接访问：你也可以使用专用的 Wisdom 节点直接读或写
• 用户隔离：Wisdom 行按认证用户拥有；代理将 knowledge_base 和 messages 查询限定为当前用户
• 安全：users、sessions、pg_* 和 information_schema 不通过 Wisdom 查询端点暴露

11.3 配置

Wisdom 在 config.json 的 wisdom 键下配置：

{
  "wisdom": {
    "host": "192.168.1.4",
    "port": 5432,
    "database": "prodigy",
    "user": "prodigy_user",
    "password": "your-password"
  }
}

11.4 遗留共享行

如果你已有遗留共享 Wisdom 行，请运行 docs/sql_wisdom_user_isolation.sql，并决定是否将这些旧行回填到特定所有者，或让它们对普通用户不可访问。

12.1 可用工具

12.2 工具执行流程

1. AI 节点在推理期间请求工具调用
2. 代理服务器验证工具名和参数
3. 工具在服务端执行（Playwright、文件系统、数据库等）
4. 结果返回给 AI 节点以继续推理
5. 所有工具事件都记录到 HUD 控制台

12.3 浏览器自动化

在 Apple Silicon 主机上提供两个级别的浏览器自动化：

• playwright_browse：使用在 copilot_bridge.config.json 中配置的本地 HTTP 浏览器桥接。用于导航和读取渲染页面的高级 API。
• agent_browser：使用 agent-browser CLI。用于 open/click/fill/press/wait/snapshot/get/is 操作的低级结构化自动化。当配置了 playwrightCdpTarget 或 PLAYWRIGHT_CDP_TARGET 时可选使用 CDP。

13.1 会话认证

• 通过登录界面进行用户注册和登录
• 会话令牌存储在 sessionStorage 中（关闭标签页时清除）
• 令牌作为 X-Session-ID 请求头在每个请求中发送
• 密码使用 bcrypt 在 PostgreSQL 中哈希

13.2 数据隔离

• Wisdom 行按认证用户限定范围
• 知识库和消息查询按用户 ID 自动过滤
• 系统表（users、sessions、pg_*、information_schema）绝不通过查询端点暴露

13.3 后端路由隐私

• Prodigy 将 MLX、LM Studio 和 Ollama 视为 本地/私有 后端
• GitHub Copilot 被视为 第三方，只能接收公开安全内容
• 私有来源（上传的文档、DB 节点、Wisdom、项目工作）优先路由到本地后端
• 当工作流混合敏感输入与第三方 AI 步骤时，Prodigy 插入本地 AI Decider + Logic Switch 以门控不安全内容

13.4 多线程安全

服务器是 多线程 的 — 每个请求在自己的线程中运行，因此长时间运行的 AI 推理调用不会阻塞 UI 或其他请求。请求大小限制：200 MB（用于文档上传）。

14.1 端点

14.2 认证请求头

GET /health
X-Session-ID: your-session-token

14.3 AI 请求格式

POST /ai
Content-Type: application/json
X-Session-ID: your-session-token

{
  "action": "ai_inference",
  "backend": "mlx",
  "model": "your-model",
  "prompt": "Your prompt here",
  "tools": ["web_search", "fetch_webpage"],
  "wisdom_recall": true,
  "wisdom_store": true
}

14.4 代理请求格式

POST /proxy
Content-Type: application/json
X-Session-ID: your-session-token

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "headers": {}
}

15.1 主配置节

config.json 携带以下可管理的默认值：

• backends.*：AI URL 和默认模型
• embedding：嵌入端点、模型和分块设置
• wisdom：PostgreSQL/Wisdom 连接默认值
• defaults.mysql：默认 MySQL/MariaDB 节点值
• defaults.wisdom：默认 Wisdom 节点值
• searxng：URL 以及搜索引擎和语言
• proxy：代理端口、沙箱根、Playwright CDP 基址和允许列表

15.2 SearXNG 配置

每个 SearXNG 节点有两个可在节点面板中直接设置的可选数据集属性：

如果未在节点上设置，这些值回退到 config.searxng.engines / config.searxng.language。

15.3 嵌入配置

{
  "embedding": {
    "endpoint": "http://192.168.10.3:11434/api/embeddings",
    "model": "nomic-embed-text",
    "chunkSize": 500,
    "chunkOverlap": 50
  }
}

16.1 配置

通信器 节点从 config.json 中可选的 notifications 块读取默认值。节点级字段可以在运行期间覆盖这些值。

{
  "notifications": {
    "defaults": {
      "channel": "email",
      "emailTo": "team@example.com",
      "emailSubject": "Prodigy Update",
      "telegramChatId": "123456789"
    },
    "smtp": {
      "host": "smtp.example.com",
      "port": 587,
      "user": "mailer@example.com",
      "password": "",
      "fromAddress": "mailer@example.com",
      "starttls": true,
      "ssl": false,
      "timeout": 30
    },
    "telegram": {
      "botToken": "<telegram-bot-token>",
      "chatId": "123456789",
      "parseMode": "Markdown",
      "disablePreview": false
    }
  }
}

16.2 支持的渠道

• 邮件：支持 STARTTLS 的 SMTP，可配置超时
• Telegram：基于 Bot 令牌的消息传递，支持 Markdown 解析

17.1 概览

内置的 PLC / SPS 节点支持面向工业原型设计的第二运行时模型：

• 动态命名的传感器和执行器引脚，直接渲染为图形连接器
• 保留状态持久化在工作流快照中
• 多个执行引擎

17.2 执行引擎

17.3 PLC 桥接配置

对于 结构化文本 部署和 Modbus/OpenPLC 桥接，向 config.json 添加可选的 plc 块：

{
  "plc": {
    "openplcApiUrl": "http://192.168.1.50:8080/api",
    "modbusHost": "192.168.1.50",
    "modbusPort": 502,
    "inputCoilOffset": 0,
    "outputCoilOffset": 100
  }
}

后端代理使用此配置进行 ST 上传和 Modbus I/O 同步。这是用于远程 Linux/OpenPLC 端；浏览器从不直接与 Modbus 通信。

17.4 Toradex 板访问

VPN 连接的 Torizon 板与 PLC 桥接单独配置，以便在摄像头或 LiDAR 硬件存在之前可以测试 SSH 访问：

管理配置浮层暴露这些字段，并包含 测试板访问 操作。该探测首先检查到 SSH 端点的原始 TCP 可达性，然后在配置了用户时尝试非交互式 SSH 登录。

18.1 添加自定义节点

1. 在 plugins/ 创建新的插件文件
2. 实现 IProdigyNode 接口
3. 在目录中注册插件
4. 重启服务器（或启用热重载）

18.2 插件模板

class MyCustomNode:
    id = "my_custom_node"
    nodeType = "MY_CUSTOM"
    title = "My Custom Node"
    description = "Does something awesome"

    def Initialize(self, config):
        self.config = config

    def Execute(self, input_data, ctx):
        # Process input
        result = "Output based on: " + input_data
        return result

    def Report(self):
        return {"status": "ok"}

    def Hibernate(self):
        pass

    def UpdateConfig(self, new_config):
        self.config = new_config

18.3 前端扩展

前端是模块化的。关键扩展点：

• js/constants.js：为枚举添加新的节点类型
• js/ui/node_manager.js：为新节点添加设置面板
• js/logic/execution.js：为新节点类型添加执行逻辑
• js/ui/playground.js：为新节点视觉添加自定义渲染

18.4 键盘快捷键

19.1 服务器无法启动

• 端口冲突：编辑 proxy_server.py 中的 PORT = 9999
• 缺少依赖：运行前置条件章节中的 pip install 命令

19.2 登录 / 认证错误

• 确认 postgres.sql 和 sql_auth_setup.sql 已应用到 prodigy 数据库
• 验证 PostgreSQL 在 192.168.1.4:5432 运行且 prodigy 数据库存在

19.3 AI 节点无响应

• 检查后端可达：curl http://192.168.10.3:5010/v1/models
• 验证模型名称与后端报告的一致
• 检查 HUD 控制台（屏幕底部）的错误消息

19.4 Copilot 桥接无法连接

• 确保你在 Mac 上的 copilot CLI 已登录：copilot auth login
• 重启桥接：node copilot_bridge.mjs
• 桥接健康检查：curl http://192.168.10.3:5015/health
• 使用 Copilot 浏览器工具时，验证 Mac 上已安装浏览器自动化：agent-browser --help
• 如有需要，用 PLAYWRIGHT_CDP_TARGET 将桥接指向不同浏览器端点，或用 AGENT_BROWSER_BIN 指向不同 CLI 路径

19.5 文档加载器错误

• 安装 PDF 支持：pip install pypdf
• 不支持遗留格式（.doc、.xls、.ppt）— 转换为 .docx/.xlsx/.pptx
• 扫描的 PDF 需要 OCR：sudo apt install tesseract-ocr poppler-utils
• 设置 OCR 语言：export TESSERACT_LANG=eng（或 eng+chi_sim）在启动服务器之前

19.6 Wisdom 召回返回空

• 验证 prodigy PostgreSQL 数据库中是否存在 knowledge_base 表
• 验证 config.json 中的 Wisdom 配置（主机/端口/数据库/用户）

19.7 SearXNG 无结果

• 确认 SearXNG 正在运行：curl http://192.168.1.4:8888/search?q=test&format=json
• 在 SearXNG 节点设置面板中调整引擎/语言

19.8 乱码（中文 / 俄语 / 等）

代理服务器通过 chardet 自动检测编码。如果问题持续，检查源网站声明的字符集。