# https://github.com/rocketride-org/rocketride-server 项目说明书 生成时间：2026-06-23 19:22:37 UTC ## 目录 - [RocketRide 项目概览](#page-overview) - [核心引擎与运行时](#page-engine) - [管道节点与 AI 集成生态](#page-nodes) - [客户端 SDK、工具与用户界面](#page-clients) ## RocketRide 项目概览 ### 相关页面 相关主题：[核心引擎与运行时](#page-engine), [管道节点与 AI 集成生态](#page-nodes), [客户端 SDK、工具与用户界面](#page-clients)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/README.md) - [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/core/parser/README.md) - [nodes/src/nodes/webhook/dropper/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/webhook/dropper/README.md) - [nodes/src/nodes/webhook/chat/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/webhook/chat/README.md) - [nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/preprocessor_langchain/README.md) - [nodes/src/nodes/preprocessor_code/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/preprocessor_code/README.md) - [nodes/src/nodes/summarization/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/summarization/README.md) - [nodes/src/nodes/llm_perplexity/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/llm_perplexity/README.md) - [nodes/src/nodes/tool_firecrawl/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/tool_firecrawl/README.md) - [nodes/src/nodes/accessibility_describe/README.md](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/accessibility_describe/README.md) - [packages/client-typescript/package.json](https://github.com/rocketride-org/rocketride-server/blob/develop/packages/client-typescript/package.json)
# RocketRide 项目概览 RocketRide 是一款定位为 **"开源 AIDE（AI Development Environment）"** 的 AI 开发环境，主张在你熟悉的 IDE 或 CLI 中"以光速构建、部署并驾驭生产就绪的 AI 方案"，并强调"零供应商锁定"与"深度可观测性"（资料来源：[README.md:1-15]()）。其核心是一个 **"开源数据管线构建器"**，以 C++ 高性能引擎为底座，由 Python 与 TypeScript 节点提供 AI 能力。 ## 1. 系统架构与运行原理 RocketRide 在运行时可拆解为三层：底层的 C++ 调度引擎、中间的节点（Node）层、上层的客户端。引擎负责在子进程中加载节点、转发 lane 上的载荷，并以事件流形式回报状态（资料来源：[README.md:9-15]()）。节点之间通过声明式的 "lane" 接口对接，例如 `data` 入口对应 `text / image / table / audio / video` 等出口（资料来源：[nodes/src/nodes/core/parser/README.md:5-15]()）。TypeScript 客户端包 `packages/client-typescript` 依赖 `commander`、`glob` 与 `ws`（WebSocket），承担 IDE 与引擎之间的事件通道职责（资料来源：[packages/client-typescript/package.json:14-25]()）。 ```mermaid flowchart LR A[IDE / CLI 客户端] -- WebSocket --> B[C++ 引擎] B -- 子进程加载 --> C[Python/TS 节点] C -- lane 数据 --> B B -- 状态/事件 --> A ``` ## 2. 节点生态与典型能力 节点库以"职责单一、配置 profile 化"的方式组织。下表汇总了仓库内已文档化的代表性节点（资料来源：[nodes/src/nodes/webhook/dropper/README.md:1-15]()、[nodes/src/nodes/webhook/chat/README.md:1-15]()、[nodes/src/nodes/preprocessor_langchain/README.md:1-35]()、[nodes/src/nodes/preprocessor_code/README.md:1-25]()、[nodes/src/nodes/summarization/README.md:1-35]()、[nodes/src/nodes/llm_perplexity/README.md:1-10]()、[nodes/src/nodes/tool_firecrawl/README.md:1-25]()、[nodes/src/nodes/accessibility_describe/README.md:1-25]()）： | 类别 | 代表节点 | 关键能力 | |------|---------|---------| | 入口源 | `dropper`、`chat` | Web 上传 / 对话，发布 URL 与公开授权密钥 | | 解析 | `parser` | 文档→text/table/image/audio/video 多 lane 输出 | | 文本预处理 | `preprocessor_langchain`、`preprocessor_code`、`preprocessor_llm` | 按 splitter / 语法树 / LLM 语义切块 | | 过滤增强 | `summarization`、`dictionary`、`accessibility_describe` | 摘要、术语抽取、无障碍场景描述 | | LLM 提供方 | `llm_perplexity`、`llm_deepseek`、`llm_ibm_watson` | 统一 `llm` 通道接入 | | 工具 | `tool_firecrawl` | 通过 `firecrawl` 前缀向 Agent 暴露 `scrape_url` / `map_url` | ## 3. 社区焦点与已知问题 仓库当前预发布版本为 **RocketRide VS Code Extension v1.2.0**。社区近期重点关注以下几类问题： - **视觉管线性能**：在 `examples/vision.pipe`（dropper → parse → detect → response_image）中，约 30 MP 的大图端到端耗时 28–38 s，其中模型推理仅约 0.5 s，绝大部分时间被全分辨率 PNG 反复编解码消耗（社区议题 #1338）。 - **追踪事件体积**：当 `pipelineTraceLevel: 'full'` 时，C++ 引擎会把 `model_dump()` 的全部载荷（含原始图像字节）内联进 `>DBG` FLOW 事件，单行 subprocess→parent stdout 可超过 16 MB 上限（社区议题 #1337）。 - **前端交互缺陷**：在 dropper 组件中，点击"浏览文件"按钮本身不触发文件选择器，需点击外层方块区域才能正常唤起（社区议题 #1335）。 这些问题提示用户：**大图像场景应避免 `full` 级别追踪**，并预期视觉管线存在显著的额外编解码开销。 ## 4. 使用建议 - **入门路径**：先用 `dropper` 接入文件，再用 `parser` 拆分内容，最后接 LLM 节点做摘要或问答（资料来源：[nodes/src/nodes/webhook/dropper/README.md:1-15]()）。 - **代码场景**：在 `preprocessor_code` 中保持 `language: auto`，由内容启发式判定语言，避免按扩展名错配（资料来源：[nodes/src/nodes/preprocessor_code/README.md:1-15]()）。 - **可观测性**：默认 trace 级别更适合生产；调试大对象时应临时降级为非 `full`，防止 16 MB stdout 截断。 ## 参见 --- ## 核心引擎与运行时 ### 相关页面 相关主题：[RocketRide 项目概览](#page-overview), [管道节点与 AI 集成生态](#page-nodes), [客户端 SDK、工具与用户界面](#page-clients)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/rocketride-org/rocketride-server/blob/main/README.md) - [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - [nodes/src/nodes/summarization/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/summarization/README.md) - [nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_langchain/README.md) - [nodes/src/nodes/preprocessor_code/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_code/README.md) - [nodes/src/nodes/preprocessor_llm/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_llm/README.md) - [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - [nodes/src/nodes/llm_openai_api/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_openai_api/README.md) - [nodes/src/nodes/llm_baidu_qianfan/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_baidu_qianfan/README.md) - [nodes/src/nodes/llm_perplexity/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_perplexity/README.md) - [nodes/src/nodes/llamaparse/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llamaparse/README.md) - [nodes/src/nodes/landing_ai/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/README.md) - [nodes/src/nodes/landing_ai/extract/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/extract/README.md) - [nodes/src/nodes/dictionary/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/dictionary/README.md) - [nodes/src/nodes/guardrails/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/guardrails/README.md) - [nodes/src/nodes/tool_deepl/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/tool_deepl/README.md) - [nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md) - [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx)
# 核心引擎与运行时 ## 概述与定位 RocketRide 是一个**开源的 AI 开发环境（AIDE）**，将传统 IDE 改造为可组合、可观测、可部署的 AI 运行时容器。其核心定位是"AI 应用背后的整套支撑栈"，而不仅仅局限于 Agent 本身。资料来源：[README.md]() 中明确指出："RocketRide is an open source data pipeline builder"，并且强调"backed by a battle-tested, high-throughput C++ engine"——这意味着整个体系由 C++ 高吞吐引擎承担调度与数据通路职责，再由 Python 与 TypeScript 层分别承担节点逻辑与 IDE 表现层。整体技术栈由三种语言共建：C++（核心引擎）、Python（节点与模型集成）、TypeScript（Shell UI 与 Documents 模型）。 运行时的关键设计思想是"协议化 + 通道化"：每个节点以 `protocol://` 形式注册（例如 `landing_ai_extract://` 资料来源：[nodes/src/nodes/landing_ai/extract/README.md]()），输入输出以"通道（Lane）"显式声明（例如 Parser 节点的 `data → text|table|image|audio|video` 资料来源：[nodes/src/nodes/core/parser/README.md]()），从而使引擎可以在不解析节点内部语义的前提下完成路由、缓冲与转发。 ## 架构总览 ```mermaid flowchart TB UI["Shell UI (TypeScript)
Documents / Explorer / Dropper"] -->|workspace + pipes| Engine["C++ 核心引擎
调度 / 通道路由 / 追踪"] Engine -->|subprocess| Nodes["Python 节点运行时"] Nodes --> LLM["LLM 节点族
(OpenAI / Perplexity / Qianfan / 自定义)"] Nodes --> Parse["解析节点族
(Parser / LlamaParse / Landing.ai ADE)"] Nodes --> Chunk["预处理节点族
(LangChain / tree-sitter / LLM)"] Nodes --> VS["向量与工具节点族
(Chroma / DeepL / Guardrails)"] Engine -->|FLOW 事件| Trace["追踪 / 观测通道
(pipelineTraceLevel)"] ``` 引擎位于中心，承担三件事：1) 接收 IDE 或 CLI 提交的管道定义并解析为有向图；2) 按 Lane 协议将数据分发到对应 Python 节点子进程；3) 收集节点输出并按需产出调试与追踪事件。Python 节点层则作为"能力插件"被动态加载，依赖通过 `services..json` 形式的清单文件注册，例如 Landing.ai 的 `parse/` 与 `extract/` 子包均由引擎按 `path` 字段装载（资料来源：[nodes/src/nodes/landing_ai/README.md]()）。 ## 节点运行时与协议契约 每个 Python 节点都遵循相同的运行时契约：**显式 Lane + Profile 化配置 + 可选外部依赖连接**。以 Summarization 节点为例，其要求至少一个 `llm` 通道连接，用于提供上下文长度与 tokenizer（资料来源：[nodes/src/nodes/summarization/README.md]()）；以 preprocessor_langchain 为例，它通过 `langchain_text_splitters` 动态按类名加载切分器，构造器参数会被自动过滤以避免跨 splitter 的关键字错误（资料来源：[nodes/src/nodes/preprocessor_langchain/README.md]()）。这种"运行时反射 + 严格 schema 校验"的模式在多个节点中复用，例如 ChromaDB 节点的 `serverName` 字段直接决定了对外暴露的 Agent 工具命名空间（`chroma.search` / `chroma.upsert` / `chroma.delete`），用于在同管道多实例时避免命名冲突（资料来源：[nodes/src/nodes/chroma/README.md]()）。 Profile 机制是另一条贯穿各节点的统一约定。LLM 类节点普遍通过 `profile` 字段选择模型族，例如 Baidu Qianfan 默认暴露 `ernie-4-5-turbo-128k`（资料来源：[nodes/src/nodes/llm_baidu_qianfan/README.md]()），Perplexity 默认 `sonar-pro`（资料来源：[nodes/src/nodes/llm_perplexity/README.md]()）；Guardrails 节点则用 Profile 控制启用哪些检查项（`basic` / `strict` / `custom`），并在 `strict` Profile 下默认启用 `block` 模式与 50,000 字符输入上限（资料来源：[nodes/src/nodes/guardrails/README.md]()）。这种 Profile-first 的设计让 IDE 端可以根据选定 Profile 动态生成 UI 字段表，避免暴露所有底层参数。 ## 预处理与解析路径 预处理（chunking）是引擎对接到下游 embedding / LLM 的关键一环。RocketRide 提供三种互补的预处理策略：1) **基于 LangChain 的规则切分**（`RecursiveCharacterTextSplitter` 等），按字符串长度或粗略 token 估算切分（资料来源：[nodes/src/nodes/preprocessor_langchain/README.md]()）；2) **基于 tree-sitter 的语法感知切分**，通过 `tree-sitter-python`、`tree-sitter-c`、`tree-sitter-cpp` 等语法包保证不切断函数/类边界（资料来源：[nodes/src/nodes/preprocessor_code/README.md]()）；3) **基于 LLM 的语义切分**，把"语义完整性"作为切分目标，并对超出 LLM 上下文窗口的文档先做 64KB 级别的分层预切分（资料来源：[nodes/src/nodes/preprocessor_llm/README.md]()）。三种策略输出统一的 LangChain `Document` 格式（`page_content` + metadata），从而被所有下游向量节点无缝消费。 解析侧则由 Parser、LlamaParse、Landing.ai ADE 三个能力组成。Parser 是基础提取器，自动识别内嵌内容并按 Lane 路由（资料来源：[nodes/src/nodes/core/parser/README.md]()）；LlamaParse 提供高级模式 `parse_page_with_agent` 与 `parse_page_with_lvm`，并在高级模式下绕过所有 simple-mode 开关（资料来源：[nodes/src/nodes/llamaparse/README.md]()）；Landing.ai ADE 走"Parse → Extract"两段式管线，Extract 节点消费的只是 Parse 节点产出的 Markdown 而非原文档（资料来源：[nodes/src/nodes/landing_ai/extract/README.md]()）。 ## 性能、追踪与已知问题 引擎的 C++ 实现承担了大部分性能敏感路径，例如管线追踪、stdout/子进程通道、流式分片。然而社区已经识别出两个与引擎行为直接相关的瓶颈： - **图像路径上的冗余编解码**（Issue #1338）：在 `examples/vision.pipe`（dropper → parse → detect → response_image）这条管线中，一张约 30MP 的图像端到端耗时 28–38 秒，其中模型推理仅约 0.5 秒，绝大部分耗时来自共享图像路径上的**完整分辨率 PNG 解码/编码往返**，属于引擎层与节点层之间不必要的重复工作。 - **`pipelineTraceLevel: 'full'` 的副作用**（Issue #1337）：当追踪级别设为 `'full'` 时，C++ 引擎会把每个节点的 `model_dump()` 完整负载（包括**原始图像字节**）内联进 `>DBG` FLOW 事件；一张大图即可能产生超过 16MB 的单行 stdout 输出，触发子进程→父进程通道的上限。 这两个问题都指向同一类根因——**引擎在序列化与跨进程传递时未对大体量二进制负载做裁剪或引用化处理**。使用者目前的可行缓解方式包括：在大图像场景下避免启用 `full` 级别追踪；在 Parser 之前对图像做预压缩或尺寸约束；关注 Dropper 等入口组件的 UI 行为（Issue #1335：内嵌 "Browse files" 按钮点击无响应，外部方形区域可正常触发），以便在 IDE 端把可重复使用的入口控件与一次性拖放区做区分。 ## See Also - 节点与通道协议（`protocol://` / Lane 体系） - Pipeline Trace 级别与 FLOW 事件格式 - Profile 机制与模型族管理 - 向量存储节点（Chroma）与工具节点（DeepL） --- ## 管道节点与 AI 集成生态 ### 相关页面 相关主题：[RocketRide 项目概览](#page-overview), [核心引擎与运行时](#page-engine), [客户端 SDK、工具与用户界面](#page-clients)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/rocketride-org/rocketride-server/blob/main/README.md) - [nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - [nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_langchain/README.md) - [nodes/src/nodes/preprocessor_code/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_code/README.md) - [nodes/src/nodes/landing_ai/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/README.md) - [nodes/src/nodes/landing_ai/parse/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/landing_ai/parse/README.md) - [nodes/src/nodes/llamaparse/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llamaparse/README.md) - [nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - [nodes/src/nodes/llm_anthropic/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/llm_anthropic/README.md) - [nodes/src/nodes/agent_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/agent_langchain/README.md) - [nodes/src/nodes/tool_deepl/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/tool_deepl/README.md)
# 管道节点与 AI 集成生态 RocketRide 是开源的 AI 开发环境 (AIDE),其核心是基于 C++ 引擎的数据流管线,管线由可组合的 Python 节点构成,涵盖文档解析、预处理、LLM 调用、Agent 编排、向量存储等完整生态,具备模型、工具与框架层面的零锁定 资料来源：[README.md:1-30]()。 ## 节点协议与统一模型 所有节点遵循统一的"通道(lanes)输入输出 + profile 配置"模型:输入与输出通道声明数据流向,profile 决定字段集合与默认值。例如 `preprocessor_langchain` 同时支持 `text → documents` 与 `table → documents` 两条通道,文本累积到文件关闭时一次性切分,表格按单元立即切分,每个分片附带顺序递增的 `chunkId` 资料来源：[nodes/src/nodes/preprocessor_langchain/README.md:1-30]()。`preprocessor_code` 则采用 tree-sitter 语法感知切分,语言默认基于内容正则权重启发式检测,而非文件扩展名,解析器按语言缓存以加速重复处理 资料来源：[nodes/src/nodes/preprocessor_code/README.md:1-25]()。 ## 节点生态分类 下表汇总了主要节点类别、代表实现与典型职责: | 类别 | 代表节点 | 主要职责 | |---|---|---| | 核心解析 | `core/parser` | 自动识别 PDF、表格、图像、音频、视频,按内容路由到对应输出通道 | | 文本/代码预处理 | `preprocessor_langchain`、`preprocessor_code` | 基于 LangChain 切分器或 tree-sitter 语法树产出语义块 | | 文档解析(云服务) | `landing_ai`、`llamaparse` | 调用 ADE / LlamaParse API 抽取 Markdown、表格与字段 | | LLM 接入 | `llm_anthropic`、`llm_deepseek`、`llm_kimi`、`llm_perplexity`、`llm_baidu_qianfan` | 通过统一 profile 抽象接入多家闭源/开源模型 | | Agent 编排 | `agent_langchain` | 基于 LangChain 构建可被父 Agent 调用的子 Agent | | 向量存储 | `chroma` | 提供 `local` 与 `cloud` 两种 profile,暴露 `search/upsert/delete` 工具 | | 工具节点 | `tool_deepl` | 包装 DeepL 的翻译与改写能力,带客户端前置校验 | 核心解析节点 `core/parser` 通过 `data → text/table/image/audio/video` 多通道解耦输入与下游消费,使得同一个文档可同时驱动文本索引与视觉模型 资料来源：[nodes/src/nodes/core/parser/README.md:1-15]()。 ## LLM、Agent 与工具集成 LLM 节点采用一致的"profile 字段 + 隐藏 schema"模式。`llm_anthropic` 默认 profile 为 `claude-sonnet-4-6`,通过 `modelTotalTokens` 等字段对齐上下文预算 资料来源：[nodes/src/nodes/llm_anthropic/README.md:1-30]()。`agent_langchain` 节点通过 `agent_description` 字段向父 Agent 描述自身能力,从而在多 Agent 编排中被正确选中并调用 资料来源：[nodes/src/nodes/agent_langchain/README.md:1-20]()。 Landing.ai 子包以 `landing_ai_parse://` 与 `landing_ai_extract://` 协议对接 ADE API:Parse 节点 `data → text/table`,Extract 节点消费 Parse 产生的 Markdown,按上传的 JSON Schema 抽取字段,响应 `extraction` 写入 `answers` 与 `documents` 通道 资料来源：[nodes/src/nodes/landing_ai/README.md:1-20]() 资料来源：[nodes/src/nodes/landing_ai/parse/README.md:1-15]()。LlamaParse 在独立线程中调用以规避 asyncio 事件循环冲突,提供 `parse_page`、`parse_page_with_agent`、`parse_page_with_lvm` 三种解析模式,并按文件大小动态调整超时 资料来源：[nodes/src/nodes/llamaparse/README.md:1-30]()。 Chroma 节点通过 `serverName` 字段隔离命名空间,使同一管线中的多个 Chroma 实例工具名不冲突,并集成 `VectorStoreToolMixin` 暴露工具 资料来源：[nodes/src/nodes/chroma/README.md:1-30]()。`tool_deepl` 则在客户端前置校验单次最多 50 条文本,`writing_style` 与 `tone` 互斥,同时传入会被拒绝而不会发起 HTTP 请求 资料来源：[nodes/src/nodes/tool_deepl/README.md:1-30]()。 ## 已知性能与可用性问题 社区反馈显示管线在大图像场景下存在显著瓶颈:在 `examples/vision.pipe`(dropper → parse → detect → response_image)中,模型推理仅约 0.5 秒,但 ~30 MP 图像端到端耗时 28–38 秒,主要耗时来自共享图像路径中冗余的全分辨率 PNG 解码/编码往返(#1338)。此外,启用 `pipelineTraceLevel: 'full'` 时,C++ 引擎会把每个节点的 `model_dump()` 完整载荷(包括原始图像字节)直接内联进 `>DBG` FLOW 事件,单行 stdout 即可超过 16 MB 限制(#1337)。UI 侧,Dropper 组件的 "Browse files" 按钮存在点击无响应问题,需要点击外层方形区域才能打开文件选择器(#1335)。 ## See Also - [RocketRide 主页与编辑扩展](README.md) - [Parser 节点](nodes/src/nodes/core/parser/README.md) - [Landing.ai Parse 节点](nodes/src/nodes/landing_ai/parse/README.md) - [Landing.ai Extract 节点](nodes/src/nodes/landing_ai/extract/README.md) - [LlamaParse 节点](nodes/src/nodes/llamaparse/README.md) - [Chroma 向量存储](nodes/src/nodes/chroma/README.md) - [Anthropic LLM 节点](nodes/src/nodes/llm_anthropic/README.md) - [LangChain Agent 节点](nodes/src/nodes/agent_langchain/README.md) --- ## 客户端 SDK、工具与用户界面 ### 相关页面 相关主题：[RocketRide 项目概览](#page-overview), [核心引擎与运行时](#page-engine), [管道节点与 AI 集成生态](#page-nodes)
相关源码文件 以下源码文件用于生成本页说明： - [packages/client-python/src/rocketride/client.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-python/src/rocketride/client.py) - [packages/client-typescript/src/client/client.ts](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-typescript/src/client/client.ts) - [packages/client-mcp/src/rocketride_mcp/server.py](https://github.com/rocketride-org/rocketride-server/blob/main/packages/client-mcp/src/rocketride_mcp/server.py) - [apps/vscode/src/extension.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/extension.ts) - [apps/vscode/src/engine/engine-manager.ts](https://github.com/rocketride-org/rocketride-server/blob/main/apps/vscode/src/engine/engine-manager.ts) - [apps/shell-ui/src/components/layout/Shell.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/components/layout/Shell.tsx) - [apps/shell-ui/src/lib/Documents.tsx](https://github.com/rocketride-org/rocketride-server/blob/main/apps/shell-ui/src/lib/Documents.tsx)
# 客户端 SDK、工具与用户界面 ## 概述 RocketRide 提供多语言的客户端 SDK、独立的 MCP 桥接服务，以及基于 VS Code 与浏览器 Shell 的用户界面，使用户能够在脚本、IDE、对话代理与可视化编辑环境中与核心引擎进行交互。本页介绍这些客户端组件的作用、相互关系以及常见的使用模式。 社区近期反馈主要集中在以下三类与客户端相关的问题上： - 视觉管线中大图经过多次全分辨率 PNG 编码/解码往返导致 ~30 秒级延迟（[Issue #1338](https://github.com/rocketride-org/rocketride-server/issues/1338)）； - `pipelineTraceLevel: 'full'` 会将整图字节内联到 `>DBG` FLOW 事件中，超出 16 MB 上限（[Issue #1337](https://github.com/rocketride-org/rocketride-server/issues/1337)）； - Dropper 组件中 "Browse files" 按钮在某些事件处理顺序下未触发文件选择器（[Issue #1335](https://github.com/rocketride-org/rocketride-server/issues/1335)）。 最新发布的 [VS Code Extension v1.2.0（prerelease）](https://github.com/rocketride-org/rocketride-server/releases) 同时包含 Shell UI 与 Engine Manager 的若干改进。 ## 客户端 SDK ### Python 客户端 Python 客户端是自动化与代理集成的首选入口。`packages/client-python/src/rocketride/client.py` 提供了同步与异步两种 API 风格，封装与引擎 IPC 通信、流式事件订阅与产物检索等常见操作。 ### TypeScript 客户端 `packages/client-typescript/src/client/client.ts` 是 VS Code 扩展与 Shell UI 与引擎通信的底层通道，复用了与 Python 客户端一致的协议语义，便于跨语言维护相同的错误模型与生命周期。 ## MCP 桥接服务 `packages/client-mcp/src/rocketride_mcp/server.py` 将 RocketRide 引擎能力以 MCP（Model Context Protocol）工具的形式暴露给对话代理，使得 LLM 可以在不直接调用引擎二进制的情况下触发管线运行、读取产物或访问外部节点（如 chroma、deepl）的工具接口。该服务是独立可部署的 Python 包，可与任意 MCP 兼容的客户端对接。 ## VS Code 扩展 `apps/vscode/src/extension.ts` 是扩展激活入口，负责注册命令、加载引擎、挂载 WebView 与 Shell UI，并在用户保存管线文件时通知 Engine Manager。 `apps/vscode/src/engine/engine-manager.ts` 负责引擎进程的生命周期：拉起、监控、关闭，以及在调试或排错场景下切换 `pipelineTraceLevel`。当与 Issue #1337 所述的 "full" 跟踪级别一同使用时，需要注意大图会在 FLOW 事件中内联字节，可能突破 16 MB stdout 限制。 ## Shell UI `apps/shell-ui/src/components/layout/Shell.tsx` 是浏览器端的容器组件，组合侧边栏、编辑器栈、Dropper 与调试面板等子区域。 `apps/shell-ui/src/lib/Documents.tsx` 负责编辑器文档状态，包括多文档布局树、编辑器实例与分屏比例的持久化，并通过 `WorkspaceBinding` 接入工作区持久化层（默认 500 ms 防抖写入）。 ## 客户端组件协作示意 ```mermaid flowchart LR A[Python 脚本 / 代理] -->|HTTP/IPC| B[Python SDK] C[VS Code] -->|IPC| D[TS SDK] E[MCP 客户端] -->|stdio| F[MCP Server] B --> G[Engine] D --> G F --> G G --> H[节点 / 工具] C --> I[Shell UI WebView] I --> D ``` ## 社区关注的失败模式与缓解建议 | 问题 | 表现 | 缓解建议 | | --- | --- | --- | | Issue #1338 | 大图全分辨率编码/解码往返 ~28–38 s | 在视觉管线中复用已解码的图像缓冲，避免节点边界处冗余的 PNG 编解码 | | Issue #1337 | `pipelineTraceLevel: 'full'` 内联图像字节至 FLOW 事件，超 16 MB 上限 | 调试大图时改用更精简的跟踪级别，或在客户端 SDK 截断 `model_dump()` 输出 | | Issue #1335 | Dropper "Browse files" 按钮点击无响应 | 点击外层触发容器或调整按钮事件传播顺序 | ## See Also - 引擎核心与节点协议：[nodes/src/nodes/core/parser/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/core/parser/README.md) - 向量存储节点：[nodes/src/nodes/chroma/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/chroma/README.md) - 文本预处理节点：[nodes/src/nodes/preprocessor_langchain/README.md](https://github.com/rocketride-org/rocketride-server/blob/main/nodes/src/nodes/preprocessor_langchain/README.md) 资料来源：[packages/client-python/src/rocketride/client.py]() [packages/client-typescript/src/client/client.ts]() [packages/client-mcp/src/rocketride_mcp/server.py]() [apps/vscode/src/extension.ts]() [apps/vscode/src/engine/engine-manager.ts]() [apps/shell-ui/src/components/layout/Shell.tsx]() [apps/shell-ui/src/lib/Documents.tsx]() --- --- ## Doramagic 踩坑日志 项目：rocketride-org/rocketride-server 摘要：发现 13 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add comprehensive benchmarking suite for pipeline performance and memory usage。 ## 1. 安装坑 · 来源证据：Add comprehensive benchmarking suite for pipeline performance and memory usage - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add comprehensive benchmarking suite for pipeline performance and memory usage - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/412 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Pipeline 'full' trace inlines image bytes into FLOW events - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pipeline 'full' trace inlines image bytes into FLOW events - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1337 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：perf(vision): large images spend ~30 s in redundant full-res PNG decode/encode round-trips - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：perf(vision): large images spend ~30 s in redundant full-res PNG decode/encode round-trips - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1338 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 运行坑 · 来源证据：Dropper "Browse files" button not responding to clicks - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Dropper "Browse files" button not responding to clicks - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1335 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `rocketride-server` 与安装入口 `rocketride` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 复现命令：`pip install rocketride` - 证据：identity.distribution | https://github.com/rocketride-org/rocketride-server | repo=rocketride-server; install=rocketride ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/rocketride-org/rocketride-server | README/documentation is current enough for a first validation pass. ## 7. 运行坑 · 运行可能依赖外部服务 - 严重度：medium - 证据强度：source_linked - 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。 - 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。 - 证据：packet_text.keyword_scan | https://github.com/rocketride-org/rocketride-server | matched external service / cloud / webhook / database keyword ## 8. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/rocketride-org/rocketride-server | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/rocketride-org/rocketride-server | no_demo; severity=medium ## 10. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/rocketride-org/rocketride-server | no_demo; severity=medium ## 11. 安全/权限坑 · 来源证据：Add LandingAI Agentic Document Extraction (ADE) node - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add LandingAI Agentic Document Extraction (ADE) node - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/rocketride-org/rocketride-server/issues/1253 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/rocketride-org/rocketride-server | issue_or_pr_quality=unknown ## 13. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/rocketride-org/rocketride-server | release_recency=unknown