算子库构建与发布指南 (Authoring Libraries)

在 Griptape Nodes 生态中，所有算子均以“算子库 (Libraries)”的形式组织、打包并分发。本篇文档系统涵盖算子库清单清单文件 (griptape_nodes_library.json) 编写、元数据声明规范、依赖管理（结合现代 uv 工具链）、文档编写约定，以及向官方标准库提交开源 PR 贡献算子的全套工业级流程。

算子库清单核心规范 (`griptape_nodes_library.json`)

通过创建清单文件 griptape_nodes_library.json，将一组相关算子打包为一个具备独立命名空间与依赖关系的算子库：

{
  "name": "Library Name",
  "library_schema_version": "0.11.0",
  "settings": [
    {
      "description": "本算子库中节点所需的 API 密钥凭证",
      "category": "app_events.on_app_initialization_complete",
      "contents": {
        "secrets_to_register": ["MY_SERVICE_API_KEY", "MY_OTHER_API_KEY"]
      }
    }
  ],
  "metadata": {
    "author": "Author Name",
    "description": "算子库功能描述",
    "library_version": "1.0.0",
    "engine_version": "0.55.0",
    "tags": ["AI", "Image Processing"],
    "dependencies": {
      "pip_dependencies": ["pillow", "requests"],
      "pip_install_flags": ["--upgrade"]
    },
    "declarations": [
      { "type": "lifecycle_stage", "stage": "STABLE" },
      {
        "type": "model_catalog",
        "providers": {
          "anthropic": {
            "display_name": "Anthropic",
            "terms_url": "https://www.anthropic.com/legal/commercial-terms",
            "models": {
              "claude_opus_byok": {
                "display_name": "Claude Opus 4 (BYOK)",
                "family": "Claude 4",
                "provider_model_id": "claude-opus-4",
                "key_support": "REQUIRES_CUSTOMER_KEY"
              }
            }
          }
        }
      }
    ]
  },
  "widgets": [
    {
      "name": "MyWidget",
      "path": "widgets/MyWidget.js",
      "description": "专为算子打造的自定义前端 UI 小部件"
    }
  ],
  "categories": [
    {
      "image": {
        "title": "Image Processing",
        "description": "图像处理类算子",
        "color": "border-purple-500",
        "icon": "Image"
      }
    }
  ],
  "nodes": [
    {
      "class_name": "MyImageNode",
      "file_path": "image/my_image_node.py",
      "metadata": {
        "category": "image",
        "description": "利用 AI 处理并增强图像素材",
        "display_name": "AI Image Processor",
        "icon": "image",
        "group": "processing",
        "declarations": [
          { "type": "model_usage", "model_ids": ["claude_opus_byok"] }
        ]
      }
    }
  ],
  "workflow_nodes": [
    {
      "node_type": "UpscaleAndTag",
      "workflow_path": "workflows/upscale_and_tag.py",
      "metadata": {
        "category": "image",
        "description": "对图像进行无损放大并智能打标",
        "display_name": "Upscale and Tag"
      }
    }
  ],
  "workflows": ["workflows/example_workflow.py"],
  "is_default_library": false
}

字段模块架构解析

settings：向引擎注册算子所需的全局敏感凭证/API 密钥；
- 使用 secrets_to_register 数组声明依赖的密钥环境变量名；
- 统一将事件类别设为 app_events.on_app_initialization_complete；
- 业务代码中通过 GriptapeNodes.handle_request(GetSecretValueRequest(key=...)) 安全提取。
metadata.dependencies：算子库装载时自动通过 pip 安装的第三方开源轮子包；
metadata.declarations / 节点级 metadata.declarations：强类型身份属性（生命周期阶段、执行原生 Python 标记）以及库级 AI 模型目录与节点引用——详见下文库与节点声明体系；
beta_features：允许最终用户在编辑器设置中按需实验性开启的特性开关；
widgets：注册前端 JavaScript 自定义沉浸式小部件（详见自定义前端小部件）；
categories：在画布添加菜单中定义分类卡片的颜色边框与图标；
nodes：枚举所有算子 Python 类名、相对文件路径与元数据；
advanced_library_path：可选的高级生命周期钩子 Python 文件，继承 AdvancedNodeLibrary（详见高级算子库架构）；
workflow_nodes：直接由保存好的工作流文件直接映射生成的节点（无需手写 Python 类）；
workflows：算子库附带的开箱即用官方模板工作流路径。

工作流原生节点映射 (`workflow_nodes`)

在 Griptape Nodes 中，一个算子节点不一定非要是手写的 Python 类。只需将 workflow_nodes 条目指向一个既有的工作流文件，引擎即可全自动解析生成对应的节点类型：

"workflow_nodes": [
  {
    "node_type": "UpscaleAndTag",
    "workflow_path": "workflows/upscale_and_tag.py",
    "metadata": {
      "category": "image",
      "description": "对图像进行无损放大并智能打标",
      "display_name": "Upscale and Tag"
    }
  }
]

拓扑规范与参数自动衍生规则

背后的工作流必须且只能包含一个 Start Flow 起点节点与一个 End Flow 终点节点，引擎据此全自动推导生成的参数表面：

Start Flow 节点上除了系统控制端口外的所有参数，全部自动转化为新节点的 输入端口 (Inputs)；
End Flow 节点上除了系统控制端口外的所有参数，全部自动转化为新节点的 输出端口 (Outputs)；
新节点自带 Flow In 与 Flow Out 控制流插槽，内部原工作流的控制连线对外部调用方彻底黑盒隐藏；
End Flow 节点内建的 Status 状态监控参数（was_successful、result_details）不会外露；
若多个起点或终点存在同名参数，引擎会自动加前缀消歧（如 Start_Flow.prompt、Start_Flow_2.prompt）；若一个名称同时出现在起点与终点，则融合成一个既可输入亦可输出的统一端口。

运行时行为：当此节点在外部运行触发时，引擎会在底层启动一个子流 (Subflow)，将节点的输入参数精准灌入内部的 Start Flow 端口并执行，结束后将 End Flow 的最终产出映射复制回节点的输出端口。子流在同一会话中会被高效复用，用户的存盘文件仅记录此节点引用，不会拷贝冗余的工作流代码。

关键前置操作：在打包交付前，必须在图形编辑器中完整存盘一次该工作流。引擎依赖存盘时编辑器注入在头部元数据中的静态签名；纯手工编写且未带有效头部的裸 .py 文件会被视为非法文件并拒绝注册。

库与节点声明体系 (Declarations)

声明体系为算子库与独立算子赋予了强类型机器可读的元数据标签。每一个声明对象均通过 type 鉴别器选定对应的结构：

1. `lifecycle_stage`（生命周期阶段）

用于标注算子库或独立节点的成熟度与工业级可用阶段：

取值枚举	语义说明
`STABLE`	成熟稳定版；推荐用于生产级工作流。
`BETA`	功能已完全就绪，正在进行工程硬化与边缘场景验证。
`ALPHA`	早期技术实现；未来版本可能发生破坏性接口变更。
`LABS`	实验室探索性阶段；未来可能整体重构或废弃。
`DEPRECATED`	已废弃；旧工作流应尽快平滑迁移至替代算子。

库级缺省：若库清单中未显式声明，界面会如实标为“未提供生命周期状态”，不会盲目假设为 STABLE；
节点级继承：节点未显式声明则无条件继承所属库的生命周期阶段；节点级声明享有最高覆盖优先级。

2. `model_catalog`（第三方 AI 模型目录）

在算子库级别统一声明本库所有算子可能消费的商业或开源 AI 模型清单，以 provider -> model 字典形式结构化呈现。各模型必须显式标注其 key_support 认证模式：

`key_support` 枚举	认证接入含义
`REQUIRES_CUSTOMER_KEY`	强制要求用户提供自备私有密钥 (BYOK)。
`SUPPORTS_CUSTOMER_KEY_OR_GRIPTAPE_KEY`	既支持用户自备密钥，亦支持 Griptape 官方托管点数统一鉴权。
`REQUIRES_GRIPTAPE_KEY`	仅支持 Griptape 平台托管统一密钥。
`NO_KEY_REQUIRED`	纯本地推理（如 Ollama、Local Diffusers），无需任何网络 API 密钥。

{
  "type": "model_catalog",
  "providers": {
    "anthropic": {
      "display_name": "Anthropic",
      "terms_url": "https://www.anthropic.com/legal/commercial-terms",
      "models": {
        "claude_opus_byok": {
          "display_name": "Claude Opus 4 (BYOK)",
          "family": "Claude 4",
          "provider_model_id": "claude-opus-4",
          "key_support": "REQUIRES_CUSTOMER_KEY"
        }
      }
    },
    "ollama": {
      "display_name": "Ollama",
      "key_support": "NO_KEY_REQUIRED",
      "notes": "本地离线运行时；模型在运行时动态枚举"
    }
  }
}

模型消费引用声明

model_usage：节点绑定声明特定消费的一组具体模型 Key：
```
{ "type": "model_usage", "model_ids": ["claude_opus_byok"] }
```
model_provider_usage：节点在运行时动态枚举该供应商旗下的所有模型：
```
{ "type": "model_provider_usage", "provider_ids": ["anthropic", "ollama"] }
```

3. `arbitrary_python_execution`（原生 Python 脚本执行安全声明）

专门用于标记该算子允许在运行期执行用户现场填写的原生 Python 脚本（例如代码沙盒执行节点）。这是重大的安全性身份事实——前端 UI 可以在执行此类算子前向最终用户弹出清晰的安全风险告警：

"declarations": [
  { "type": "arbitrary_python_execution", "executes_arbitrary_python": true }
]

实验性特性开关体系 (Beta Features)

允许开发者向用户提前试发尚未完全冻结的新功能，由用户在编辑器的 Beta Features 设置界面中自主选择启用：

"beta_features": [
  {
    "id": "sharpen_after_upscale",
    "name": "超分后画面锐化增强",
    "description": "为 Upscale Image 算子提供额外的后处理细节锐化调节参数",
    "owner": "@your-github-handle",
    "remove_by": "2027-03-31"
  }
]

remove_by 约束：必须指定 YYYY-MM-DD 截止日期，且距当前日期不得超过 180 天（强制倒逼新功能或转正或下线）；
代码中消费逻辑：调用 self.is_beta_feature_enabled("<id>") 探测开关状态；
设计铁律：所有参数必须在 __init__ 中正常注册，仅通过 hide_parameter_by_name() 动态控制显隐！唯有这样，开启了该特性的用户保存的工作流，才能被未开启特性的用户平稳打开而不触发反序列化结构崩溃。

基于现代 `uv` 工具链的工程化依赖隔离 (uv Integration)

推荐采用由 Rust 驱动的高性能包管理工具 uv 管理算子库依赖，具备极速装载与强复现保障：

标准工程目录拓扑

library-name/
├── pyproject.toml              # uv/hatch 构建与运行时依赖配置
├── uv.lock                     # 锁定的确定性依赖版本清单
├── LICENSE                     # 开源授权文件
├── README.md                   # 详尽使用说明文档
├── CHANGELOG.md                # 版本演进发布日志
├── .gitignore
└── library_name/
    ├── griptape_nodes_library.json  # 算子库清单
    └── node_file.py

`pyproject.toml` 标准配置样板

[project]
name = "library-name"
version = "1.0.0"
description = "自定义算子库工程描述"
authors = [
    {name = "Your Name", email = "email@example.com"}
]
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests",
    "pillow",
]

[dependency-groups]
dev = ["griptape-nodes-engine", "pytest", "pyright", "ruff"]

[tool.uv.sources]
griptape-nodes-engine = { git = "https://github.com/griptape-ai/griptape-nodes-engine", rev = "latest" }

[tool.hatch.build.targets.wheel]
packages = ["library_name"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

⚠️ 关键禁止事项：严禁将 griptape-nodes-engine 写入 [project] dependencies 运行时依赖！ 引擎本身是加载你的宿主环境，而非你库底下的一个普通从属包。将其误写入运行时依赖会导致在安装时拉入第二套引擎副本，污染 Python 导入优先级并引发难以排查的内核版本漂移。引擎开发桩必须且只能声明在 [dependency-groups] dev 中。

算子库文档编写规范 (Documentation Patterns)

一个工业级算子库必须在 README 中至少覆盖：

核心特性速览与多模型对比矩阵（对比各模型速度、生成画质与上下文 Tokens 上限）；
uv 极速安装与自动安装双路径指引；
出厂常见故障排查表 (Troubleshooting)：重点收录“未捕获 write_bytes() 造成宏解析变量丢失”及“图像参数未采用 ParameterImage 造成 Base64 WebSocket 拥塞”两大高频排查指引。

向官方标准库贡献算子全流程 (Contributing to Standard Library)

当你编写的算子具备普适通用价值时，推荐直接向官方核心库发起 Pull Request：

检出特性分支：git checkout -b feature/add-my-awesome-node；
放置源码文件：放入 libraries/griptape_nodes_library/griptape_nodes_library/<category>/ 对应目录；
更新主库清单：在 libraries/griptape_nodes_library/griptape_nodes_library.json 中自增库小版本号、登记新增的 pip 第三方依赖并在 nodes 数组中挂载该算子；
撰写标准参考文档：在 docs/nodes/<category>/<node_name>.md 创建文档并在 mkdocs.yml 的 nav 导航栏中登记；

执行本地工业级门禁扫描：

make format        # 自动代码格式化
make check/lint    # Ruff 静态代码规范校验
make check/types   # Pyright 严格类型检查

提交代码并发起 PR：提交 Git Commit 并使用 gh pr create 发起代码审查。

算子库构建与发布指南 (Authoring Libraries)

算子库清单核心规范 (griptape_nodes_library.json)