【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载RocketRide 的节点体系庞大nodes/src/nodes/下数百个 Python 节点其文档质量依赖一套契约驱动的工程化机制每个节点的 README 必须严格遵循 readme-schema.md 定义的章节结构章节的必需性由 services*.json 元数据决定并用 validate-node-readme.py 做确定性校验。本文以 nodes/AGENTS.md 这份目录级 Agent 指南为骨架完整讲解节点文档的书写规范、生成区维护、校验器实现原理与节点测试框架帮助读者含 AI Agent在 RocketRide 仓库中编写、校验并发布合格的节点文档。一、nodes/目录的文档契约总览nodes/AGENTS.md 是整个nodes/目录的守门人指南全文只讲一件事节点文档不是自由发挥而是受约束的工程产物。它确立了四条核心规则每个节点 README 必须遵循统一 Schema即docs/development/nodes/readme-schema.md中定义的章节结构。README 的必需章节由services*.json决定节点的服务定义文件决定了哪些章节是强制CORE、哪些是条件触发CONDITIONAL、哪些是可选OPTIONAL而不是由作者主观判断。生成区禁止手改每个 README 末尾的ROCKETRIDE:GENERATED:PARAMS区域由nodes:docs-generate构建任务维护手写区域与生成区域严格分离。写完必须校验使用python3 ../scripts/validate-node-readme.py src/nodes/name检查另有全量校验入口./builder docs:validate。配合阅读的三份规范文档是docs/development/nodes/readme-schema.md —— README 章节 Schemadocs/development/nodes/services-schema.md ——services.json契约docs/development/nodes/testing.md —— 节点自动化测试框架。二、Node README Schema分层要求与固定顺序2.1 三级要求体系readme-schema.md 将每个章节划分为三个等级CORE每个节点 README 必须出现无例外。包括标题摘要、## What it does、## Configuration。CONDITIONAL当services*.json声明了触发条件时必须出现未声明时禁止出现。一个条件章节在没有触发条件时出现说明 README 与元数据不一致fix whichever one is wrong。OPTIONAL从不强制。出现时必须位于固定槽位并遵守其规则。章节顺序是固定的。手写区域内除了 Schema 定义的章节外不允许出现其他##标题——任何节点专属内容必须放进## Notes。校验器中的CANONICAL_ORDER列表见 validate-node-readme.py是这一顺序的机器可读表达About → What it does → Example pipelinesPARKED→ Connections → Lanes → As a tool → Profiles → Configuration → Authentication → Requirements → Limitations → Notes → Upstream docs2.2 手写区与生成区的两段式结构一个合规的节点 README 由手写区域全部正文和生成区域组成。生成区域是文档末尾的!-- ROCKETRIDE:GENERATED:PARAMS START/END --块包含## Schema、## Dependencies、## Source三节由nodes:docs-generate从services*.json重新生成永远不能手改且不受本文档章节规则的约束。设计上有意让生成区独占字段引用职责生成的## Schema表每行对应一个字段机器拥有、不会漂移因此手写区域不重复字段表——手写配置内容只写生成无法知道的东西即使用指导。以 accessibility_describe/README.md 为例其末尾的生成区自动列出了全部字段accessibility.prompt、accessibility.spatialFormat、modelTotalTokens等及默认值而手写区只讲解字段的用法与取舍。三、逐节详解从标题到 Upstream docs0. 标题 摘要 —— CORE# db_postgres A RocketRide database node that answers natural-language questions against PostgreSQL — as a pipeline node via lanes or as an agent tool.H1 必须是节点目录名校验器会做精确比对第一段是 12 句的纯语言摘要不含营销词汇说明节点是什么、何时选用面向在 100 节点中做选择的读者。1.## About Vendor—— OPTIONAL包装第三方服务/产品的节点使用。24 句、不超过 80 词介绍该产品是什么、以什么著称。永恒散文规则不得出现模型名、版本、价格、速率限制等随厂商节奏变化的内容——那些属于## Profiles或生成的## Schema。若存在本节约## Upstream docs也必须存在。2.## What it does—— CORE25 句散文说明节点在管道内做什么、扮演哪些角色lanes 数据流、agent tool、或两者兼有、何时优于同类节点。只讲 RocketRide 视角厂商背景归## About。3.## Example pipelines当前处于 PARKED 状态Schema 文档中该节的完整定义以注释形式保留PARKED要求至少一个示例第一个是随节点发布的示例——example.pipe最小可运行管道example.png同一管道在画布上的截图二者必须描绘同一条管道通过裸相对文件名引用并配套 shields.io 下载徽章stylefor-the-badge品牌色41b6e6。校验器当前将其视为允许在该槽位出现、但不再强制要求的章节若出现则要求包含至少一条a → b流程线见 validate-node-readme.py。恢复该机制的条件取消注释、重编号、解开配套校验已完整记录在 Schema 文档的注释块中。4.## Connections—— CONDITIONAL触发条件服务条目声明了invoke对象。ConnectionRequiredDescription每行对应一个 invoke 键min ≥ 1 时为 yes...连接名必须与invoke键完全一致。5.## Lanes—— CONDITIONAL触发条件服务条目声明了非空lanes对象。Lane inLane outDescription每行对应一个 in→out 对......一个输入对应多个输出时每个输出单独一行输入无输出时写—车道名必须与services*.json中的声明逐字一致。6.## As a tool—— CONDITIONAL触发条件tool∈classType。描述当节点作为工具连接给 Agent 时Agent 能看到什么工具服务器名 每个暴露函数的表格。参数与返回值在表格下方补充说明。这是面向 Agent 的契约是全文件准确度要求最高的一节。7.## Profiles—— CONDITIONAL触发条件preconfig.profiles中除custom外包含 ≥ 2 个条目。详细布局规则见下文第四节。8.## Configuration—— CORE配置面板的使用指导。生成的## Schema表已列出每个字段不要重复字段表。本节包含一段关于如何配置节点的话profile 给了你什么、大多数用户可忽略什么每个复杂字段一个###子节以字段标题命名涵盖字段控制什么、合法值与默认值带来什么、何时改以及为什么改、与其他字段的交互、合适的取值示例。一个字段被视为复杂当满足任一条件行为不能从名字看出、与其他字段交互、错误值会静默或昂贵地失败、取值需要技巧提示词、描述、连接串。多服务目录超过一个带protocol的services*.json需按服务拆分## Connections与## Configuration内容###-per-service主服务在前同名实现的品牌预设除外可只写一次并在## Notes中说明预设差异。9.## Authentication—— OPTIONAL凭证设置需要哪个 key/token、必需 scope、获取位置、期望格式。保持结构性说明scope、格式不复制会过时的厂商 UI 操作步骤。10.## Requirements—— CONDITIONAL触发条件gpu∈capabilities。说明硬件/运行时要求GPU、VRAM、本地模型下载、CPU 回退行为。11.## Limitations—— CONDITIONAL触发条件nosaas、noremote、security、filesystem任一 ∈capabilities。用平实的语言说明节点能在哪里/不能在哪里运行以及安全相关行为文件系统访问、网络访问、SaaS 排除。12.## Notes—— OPTIONAL唯一的自由格式节故障排查、兼容性怪癖、算法细节、测试说明等任何真正节点专属的内容。用###子节且不得重复结构化章节已拥有的内容。13.## Upstream docs—— OPTIONAL## About存在时本节约为必选否则可选。以项目符号列出厂商或底层库的文档链接。这是最后一个手写章节其后紧跟生成区域。四、Profiles 布局的精细规则## Profiles是规则最细的章节。每个声明过的 profile 必须恰好出现一次Profile单元格要么写 profile 的声明键代码形式如gpt-5-5要么逐字复刻声明中的title也可两者兼有Profile 1 (profile-1)custom永远写作custom。引言句必须点名声明的默认 profileDefault: **Profile 1** (profile-1).其所在行标记**(default)**。4.1 普通布局单表对classType不含llm、或合并元数据声明 ≤ 6 个 profile 的节点使用一张普通表格禁止details块。4.2 大 LLM 布局可见表 折叠表对classType含llm且合并元数据声明 6 个profile 的节点必须使用双表格可见表最多 6 行6 是上限不是配额。声明默认值排第一然后按最近两个可识别的发布组最新组在前选取若某节点前端聚合多家厂商目录如llm_bedrock、llm_ollama、llm_gmi_cloud发布组按厂商分别解读且绝不允许同一厂商的旧代可见而新代被折叠。details折叠表其余全部 profile。custom与标记deprecated的 profile 必须在这里。标准形状Profile后的列可适配但两张表列一致## Profiles Default: **GPT-5.2** (openai-5-2). | Profile | Model | Context | Output | | ------- | ----- | ------- | ------ | | openai-5-2 **(default)** | gpt-5.2 | 400,000 | 128,000 | | gpt-5-6-sol | gpt-5.6-sol | 1,050,000 | 128,000 | details summarystrongView 2 more models/strong/summary | Profile | Model | Context | Output | | ------- | ----- | ------- | ------ | | openai-5-4 | gpt-5.4 | 400,000 | 128,000 | | custom | _(user-specified)_ | editable | editable | /details配套规则折叠摘要文本必须恰好是View N more modelsN 折叠表行数/summary之后与/details之前必须保留空行CommonMark 渲染嵌套表格所必需大布局的默认值不能是custom或 deprecated默认必须可见而这两类必须折叠。4.3 多服务目录每个服务各有各的默认值每个带protocol的服务在引擎眼里是独立节点如llm_openai_api的 Nebius 品牌预设、cloud_tts的 OpenAI 与 ElevenLabs 两个供应商、store_elasticsearch的 Elasticsearch 与 OpenSearch 两个后端因此其preconfig.default是关于该服务的事实。合并表格中必须标记每个服务的默认行并在引言中点名Primary default: **Primary A** (primary-a). Secondary default: **Secondary A** (secondary-a).需用一句话说明每个默认值属于哪个注册两个未解释的**(default)**标记读起来像自相矛盾。大布局中主服务的默认值仍领衔可见表任何服务的默认值都不得被折叠。五、校验器实现原理validate-node-readme.pyscripts/validate-node-readme.py 是这套契约的确定性执行者——Deterministic, no LLM纯规则、可重复。其工作流程如下。5.1 解析与合并JSONC 与多服务节点目录下所有services*.json都会被读取并合并validate-node-readme.py文件是JSONC允许//注释和尾逗号先经strip_jsonc()清洗再解析没有protocol的条目是共享片段如core的services.common.*.json被忽略有protocol的条目逐一合并classType、capabilities取并集lanes、invoke、fields、preconfig.profiles深度合并并按文件顺序记录所有服务各自的默认值_defaults。5.2 触发式计算required_sections()validate-node-readme.py依据合并后的元数据计算必需集与禁止集章节触发条件否则What it does/Configuration恒有—Connections存在invoke禁止Lanes存在非空lanes禁止As a tooltool∈classType禁止Profiles除custom外 ≥ 2 个 profile禁止Requirementsgpu∈capabilities禁止Limitationsnosaas/noremote/security/filesystem任一 ∈capabilities禁止5.3 主要检查项标题与摘要H1 等于目录名其后紧跟非标题的摘要段落章节存在性/禁止性/未知性必需章节必须出现条件未触发章节出现即 FAILREADME and metadata disagree未知##标题 FAIL应移入## Notes顺序出现的章节索引必须严格递增About规则必须是第一节、≤ 80 词、且Upstream docs必须存在表格对账Connections首列覆盖全部invoke键、Lanes首列覆盖全部声明车道多余行不报错Profiles 全量对账每个声明 profile 恰好出现一次missing / duplicate / unknown 分别报错默认值在引言中出现键 加粗标题且只在对应行标记语义列Model/Context tokens/Output tokens的渲染值必须与model/modelTotalTokens/modelOutputTokens元数据一致忽略 Markdown 装饰与千位分隔符大布局规则一可见表 一折叠表、可见行 ≤ 6、默认值可见且居首、custom/deprecated 折叠、View N more models的 N 与实际隐藏行数一致、details周围空行存在生成区存在时必须是最后一个区域且形状未被修改START/END 标记配对、END 之后无内容复杂字段告警WARN 而非 FAIL带textareawidget 或大枚举 6 项的字段若在## Configuration下没有对应###子节给出告警。5.4 运行方式# 校验单个节点 python3 scripts/validate-node-readme.py nodes/src/nodes/node # 校验整个节点语料阻塞式属于 docs:test 的一部分 ./builder docs:validate # 批量模式 python3 scripts/validate-node-readme.py --all nodes/src/nodes校验器检查的是结构而非事实散文是否准确描述代码属于评审关注点PR 上的 CodeRabbit 发布文档审查。测试用例见 tests/test_validate_node_readme.py它通过 fixture 节点覆盖了大 LLM 布局强制details、可见行数上限、默认值标记、标题加粗、自定义/废弃行折叠、缺失/重复/未知行、隐藏行计数、空行要求、语义列匹配、多服务默认值等全部路径。六、services.json契约文档的元数据源头services-schema.md 说明一个节点由nodes/src/nodes/node/下的一个或多个services*.json定义一份文件承担三重职责注册节点protocol、class、可执行体、声明连接lanes、描述配置 UIpreconfig、profiles、fields、shape由画布自动渲染。6.1 顶层键速查KeyRequired用途title✓画布瓦片上的显示名protocol✓端点协议如llm_openai://classType✓节点是什么如[llm]、[tool]、[store]驱动目录分组与行为capabilities✓引擎行为标志如[invoke]registerfilter、endpoint或省略注册对应类型工厂node/path运行时python与模块路径nodes.llm_openaiprefix✓URL ⇄ 路径转换时增删的前缀description字符串数组拼接描述节点icon定义旁的 SVG 文件名自动发现、自动主题化tile画布瓦片渲染提示lanes数据流端口tool 节点通常没有preconfig默认 profile 命名profiles合并进配置fields画布渲染RJSF的配置字段 Schemashape字段到 UI 分区的布局test自动化测试用例见 testing.md6.2 lanes数据流端口lanes把每个输入lane 映射到它产生的输出lane 列表lanes: { image: [text] // 消费 image产出 text }两个节点可接线当且仅当上游输出类型匹配下游输入类型。无lanes的节点多数tool节点不流动数据而是绑定到 Agent 的工具通道。完整的 lane 类型本体论与 wire-vs-bind 规则见 docs/development/nodes/index.md。6.3 preconfig / profiles预设配置preconfig持有默认 profile 名与命名 profiles 映射。profile 是合并进节点配置的预设值包除非 profile 是absolutepreconfig: { default: gemini-2.5-flash, profiles: { gemini-2.5-flash: { title: Gemini 2.5 Flash, model: gemini-2.5-flash, modelTotalTokens: 1048576, apikey: } } }6.4 fields画布渲染的配置 Schemafields是 JSON-Schema 风格的字段描述画布用RJSFReact JSON Schema Form渲染成表单控件。常用键type、title、description、default、format如textarea、enum。两个动态特性使用频繁Profile 选择器enum用引用模式[*preconfig.profiles.*.title]从 profiles 拉取选项配合conditional按所选 profile 切换可见字段accessibility_describe.profile: { title: Vision Model, type: string, default: gemini-2.5-flash, enum: [*preconfig.profiles.*.title], conditional: [ { value: gemini-2.5-flash, properties: [accessibility_describe.gemini-2.5-flash] } ] }属性组properties数组声明某 profile/对象一起显示的字段集合。shape把字段编排进配置面板的分区shape: [ { section: Pipe, title: Accessibility Describe, properties: [accessibility_describe.profile] } ]6.5 画布如何消费这些定义可视化构建器apps/shared/src/components/canvas/将其变成编辑器节点图用ReactFlow渲染配置面板用RJSFNodeConfigPanel把fields/shape渲染进侧栏并从canvas/components/rjsf-widgets/挂接自定义控件API-key、select、OAuth 等服务端校验。字段默认值通过getDefaultFormState从 Schema 解析而非硬编码。无需任何中心注册把services*.json连同 SVG放进nodes/src/nodes/node/即可被构建自动发现。完整示例accessibility_describe/services.json 是紧凑而完整的范本——元数据 lanesimage → text 三个 Gemini profiles 带条件 profile 选择器的fields 单节shapetest用例适合与本文对照阅读。七、节点测试把测试写进services.jsontesting.md 定义的框架支持直接在service*.json的test属性中声明自动化测试。前提仅支持node: python的节点。7.1 快速开始{ test: { profiles: [default], cases: [ { text: Hello world, expect: { text: { contains: Hello } } } ] } }# 契约测试无需服务器 ./builder nodes:test # 完整集成测试启动服务器、执行用例 ./builder nodes:test-full7.2 配置 Schema属性类型必填说明requiresstring[]否必须设置的环境变量缺失则跳过测试profilesstring[]否来自preconfig.profiles的 profile 名每个 profile 作为独立测试运行controlsstring[]否附加的控制节点 provider如[llm_openai]chainstring[]否管道链*代表被测节点默认[*]outputsstring[]否捕获的输出 lanes省略时从用例的expect键自动推断timeoutnumber否超时秒数默认 60requiresLibsobject/string[]否必须存在的原生库如{Linux: [libGLESv2.so.2]}纯数组适用于所有 OS缺失则跳过casesobject[]是测试用例数组7.3 用例与输入格式每个用例声明输入 lane 与期望输出。文本类 lane 直接内联内容文件类 lane 给testdata/相对路径{ text: What is the capital of France?, expect: { text: { notEmpty: true } } } { image: ocr/sample.png, expect: { text: { contains: Hello World } } } { audio: audio/sample.mp3, expect: { ... } } { documents: docs/sample.pdf, expect: { ... } }lane 类型推断text/questions/answers/table/classifications/tags为内联字符串或对象image/audio/video/documents为文件路径_source为特殊内部源 lane。任何 lane 都可用显式文件引用text: { file: text/sample.txt }。7.4 匹配器体系值匹配器equals、contains、matches正则、beginsWith、endsWith结构匹配器notEmpty、minLength、maxLength、type、hasProperty、noError数值匹配器greaterThan、lessThan嵌套匹配器property路径导航可传数组做多检查、each数组全部项匹配、any至少一项匹配。已知 lane 有内容路径捷径text→[0]、questions→[0].questions[0].text、documents→[0].page_content等因此text: { contains: hello }等价于text: { property: { path: [0], contains: hello } }。路径语法支持.property对象属性、[0]数组索引及组合[0].questions[0].text。多个匹配器可组合property可与内容匹配器共存内容匹配器查 lane 内容路径property查原始结果的显式路径。7.5 测试执行与 Mock契约测试./builder nodes:test或nodes:test-contracts直接跑pytest nodes/test/test_contracts.py -v可按节点名过滤-k llm_openai校验services*.json结构必填字段、lane 名、模块存在性无需启动服务器。集成测试./builder nodes:test-full自动启动测试服务器执行用例支持透传 pytest 参数--pytest-v -s、-k question、-m slow、--pytest-patternllm。Mock 支持集成测试设置ROCKETRIDE_MOCK环境变量启用外部服务LLM 供应商、向量库等的 mock 实现使 CI 无需真实 API key 即可运行mock 模块位于nodes/test/mocks/。八、实操案例以 accessibility_describe 为例把整条链路串起来看一个真实节点元数据accessibility_describe/services.json 声明protocol: accessibility_describe://、classType: [image]、lanes: { image: [text] }因此其 README 的## Lanes是必选、## As a tool是禁止classType 无tool。README 手写区accessibility_describe/README.md 按 Schema 依次给出摘要、## About Google Gemini≤ 80 词、## What it does、## Lanes表、## Profiles单表 默认值引言因 profile 仅 3 个且非 llm 大类、## Configuration对textarea复杂字段逐一给出###子节System Instructions、Analysis Prompt、Hazard Priority、Spatial Format每个都讲清默认值、回退链、与其他字段的交互、## AuthenticationGoogle AI API key拒绝sk-前缀的 OpenAI key、## Notes请求与失败行为base64 数据 URL、temperature 0.3、最多 1024 输出 token、1 次初始请求 3 次重试、1/2/4 秒退避、## Upstream docs。生成区## Schema表自动列出 6 个字段及默认值、## Dependenciesgoogle-genai 1.14.0、## Source。测试services.json 的test块用images/ocr_test_text.png、images/ocr_test_mixed.png两个图片用例断言textlanenotEmptytimeout: 30。如此便构成闭环改元数据 → 重新生成参数区 → 校验器验证结构 → 测试验证行为。修改流程应始终为先写或改services*.json真相源→ 跑nodes:docs-generate刷新生成区 → 跑validate-node-readme.py校验手写区 → 跑nodes:test验证行为。九、常见违规与规避条件章节错位services*.json没有lanes却写了## Lanes——要么删章节要么补元数据手改生成区ROCKETRIDE:GENERATED:PARAMS块被编辑后形状漂移——改回nodes:docs-generate重新生成绝不手改未知##标题在固定章节序列之外自创章节——移入## NotesProfiles 对账失败profile 行缺失/重复/未知、默认值未在引言点名或未标记、语义列值与元数据不符——回到preconfig.profiles修正复杂字段无说明textarea/大枚举字段没有###子节——在## Configuration下补充校验器以 WARN 提示但这是发布质量基线About 超标超过 80 词或缺少配套## Upstream docs。结语RocketRide 的节点文档不是写了就行而是一套以services*.json为真相源、以 readme-schema.md 为结构契约、以 validate-node-readme.py 为强制执行器、以 testing.md 为行为保障的完整工程体系。对人工作者和 AI Agent 而言遵循 nodes/AGENTS.md 给出的这条路径——按 Schema 写作、让元数据决定章节、不碰生成区、写完即校验——就能稳定产出结构一致、可被画布和搜索引擎正确消费的节点文档。赞分享【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载相关推荐GitHub Actions Importer核心功能解析规划、测试、自动化迁移全流程GitHub Actions Importer核心功能解析规划、测试、自动化迁移全流程 GitHub Actions Importer 是一款强大的工具能够Rocket.Chat 服务端 REST API 开发指南AJV Schema 驱动的自动 OpenAPI 文档与端点校验Rocket.Chat 服务端 REST API 开发指南AJV Schema 驱动的自动 OpenAPI 文档与端点校验 本文面向在 Rocket.Chat即时通讯后端前端Claude Code Haha 文档站工程指南React 文档站点与站点 AGENTS.md 契约全解读Claude Code Haha 文档站工程指南React 文档站点与站点 AGENTS.md 契约全解读 本文以 site/AGENTS.md https:人工智能AI 应用桌面应用代码智能体MCP Clients上一篇Casibase完全指南如何快速构建企业级AI知识数据库下一篇PyTorch 自定义算子注册实战RegisterOperators API 全解基于 aten/src/ATen/core/op_registration创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考