跳到主内容
智客 ZICQ

技能库 智客分类:文档办公 n8n-binary-and-data-official

N8n Binary And Data Official

处理 n8n 中的文件,图像,附件,或二进制数据时使用, 或当一个AI代理需要将用户加载的文件作为工具输入或返回生成的文件时使用. 关于数据表(chemas, dedup,持久状态),请参见单独的n8n-data-tables-official技能. 在"file","image","PDF","attachment","binary","upload","download"上触发,与文件聊天,代理工具需要文件,视觉/多模式,或任何处理非JSON文件数据.

1308 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

处理 n8n 中的文件,图像,附件,或二进制数据时使用, 或当一个AI代理需要将用户加载的文件作为工具输入或返回生成的文件时使用. 关于数据表(chemas, dedup,持久状态),请参见单独的n8n-data-tables-official技能. 在"file","image","PDF","attachment","binary","upload","download"上触发,与文件聊天,代理工具需要文件,视觉/多模式,或任何处理非JSON文件数据.

何时用

处理 n8n, OR 中的文件, 图像, 附件, 或二进制数据, 当一个 AI 代理需要将一个用户加载的文件作为工具输入或返回生成的文件时. 关于数据表(chemas, dedup,持久状态),请参见单独的n8n-data-tables-official技能. 在"文件","i"上触发

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:n8n Binary and Data、Non-negotiables、Strong defaults、Binary basics、Setting binary、Reading binary。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/AGENT_TOOL_BINARY.md、references/MERGE_FOR_CONTEXT.md、references/BINARY_BASICS.md、references/CDN_REQUIREMENT.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data.

n8n Binary and DataNon-negotiablesStrong defaultsBinary basicsSetting binaryReading binaryAgent tool gymnasticsMerge for keeping binary in contextCDN requirement for chat surfacesData TablesReference filesAnti-patterns

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
n8n-binary-and-data-official
description
Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 4
  • references/AGENT_TOOL_BINARY.md
  • references/MERGE_FOR_CONTEXT.md
  • references/BINARY_BASICS.md
  • references/CDN_REQUIREMENT.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「n8n-binary-and-data-official」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-714bea9b2227444c-N8n-%E4%BA%8C%E8%BF%9B%E5%88%B6%E5%92%8C%E6%95%B0%E6%8D%AE%E5%AE%98%E6%96%B9.html
请存为 .cursor/skills/n8n-binary-and-data-official/SKILL.md 或 .claude/skills/n8n-binary-and-data-official/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/n8n-io/skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/n8n-io/skills' --list

npx skills add 'https://github.com/n8n-io/skills' --skill 'n8n-binary-and-data-official'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: n8n-binary-and-data-official description: Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data. --- # n8n Binary and Data n8n handles two kinds of data: JSON (in `$json`) and binary (in `$binary`), flowing side-by-side. Binary has sharp edges around agent tools, storage, and display contexts (chat surfaces, message rendering). For tabular storage (Data Tables), see the **`n8n-data-tables-official`** skill. ## Non-negotiables 1. **Binary is in `$binary`, not `$json`.** Don't read file contents from `$json`. 2. **Binary cannot cross the agent tool boundary in either direction.** Tool parameters are JSON only (via `fromAi()`), and tool results are JSON only. Pre-stage binary in storage and pass keys/URLs through JSON. The agent's `passthroughBinaryImages: true` lets the LLM *see* uploaded images for vision, but it does NOT enable tools to receive them. See `references/AGENT_TOOL_BINARY.md`. ## Strong defaults - **Merge nodes keep binary in context.** When a side computation strips binary, merge it back rather than re-fetching. See `references/MERGE_FOR_CONTEXT.md`. ## Binary basics In n8n, each item has two slots: ```ts { json: { ... }, // your data binary: { // your files data: { // 'data' is the typical key; can be any name data: '', mimeType: 'application/pdf', fileName: 'invoice.pdf', fileExtension: 'pdf', }, }, } ``` `$binary.` reads the named property. Most file-handling nodes have a `binaryPropertyName` parameter, the key inside `$binary`. ### Setting binary File-producing nodes (HTTP Request with binary response, Read Files, etc.) populate `$binary` automatically. To produce binary in a Code node: ```ts return [{ json: { ... }, binary: { data: { data: Buffer.from(content).toString('base64'), mimeType: 'text/plain', fileName: 'output.txt', }, }, }] ``` ### Reading binary ```ts // In a Code node const buffer = await this.helpers.getBinaryDataBuffer(0, 'data') const text = buffer.toString('utf-8') ``` Most workflows don't need to read binary directly. Pass it through to consumer nodes (email attachments, file uploads, etc.). See `references/BINARY_BASICS.md` for more. ## Agent tool gymnastics Agent tools (sub-workflows wired into a LangChain Agent, or workflows exposed as MCP tools) have a constraint: parameters and results are JSON, not binary. Affects both directions. **Inbound (user uploads → tool consumes):** the chat trigger gives `files[]`. The agent can have `passthroughBinaryImages: true` for vision, but `fromAi()` can't pass binary to a tool. So: 1. Pre-stage uploaded files: hash a key, upload to private storage. 2. Inject the keys into the agent's system prompt: "Files passed in: [{originalFileName, fileName}]. Use EXACTLY the `fileName` field when calling tools." 3. The tool's `fromAi('imageName', '...', 'string')` receives the key. The sub-workflow downloads from storage. **Outbound (tool produces → agent returns):** a tool generates a file. It can't return raw binary. 1. Generate binary internally. 2. Upload to storage, get back URL/key. 3. Return JSON: `{ ok: true, file_id: '...', url: '...' }`. 4. The agent embeds the URL in its response, or another tool fetches by key. For the full pattern including the async-via-webhook variant for long-running tools, see `references/AGENT_TOOL_BINARY.md`. ## Merge for keeping binary in context A JSON-only operation (Edit Fields, Code, IF) often strips binary from the item. To keep it: ``` [Source with binary] ─┬─→ [Edit Fields: transform JSON] ─┐ │ ├─→ [Merge: by position] ─→ [Email with attachment] └─────────────────────────────────────┘ ``` Merge combines the streams, and binary survives. See `references/MERGE_FOR_CONTEXT.md`. ## CDN requirement for chat surfaces When a workflow generates an image and the user wants it embedded in a chat message (Slack, Discord, Teams, Telegram, embedded webhook chat, etc.): - **Binary on the item isn't enough.** Chat surfaces don't read `$binary`; they render messages that reference images by URL (or via platform-specific file upload APIs). - **The image must live somewhere a URL can fetch.** Upload to a CDN or object store first. - **The user configures this storage.** Not built into n8n. Common options span object storage (S3, R2, GCS, Azure Blob, Vercel Blob, Supabase Storage) and drive-style services (Dropbox, Google Drive, OneDrive, Box). Ask the user what they use rather than defaulting to S3. See `references/CDN_REQUIREMENT.md`. ## Data Tables For Data Tables, see the **`n8n-data-tables-official`** skill. Distinct surface with its own gotchas (default columns, no foreign keys, no JSON column type, manual-mapping UI quirk). ## Reference files | File | Read when | |---|---| | `references/BINARY_BASICS.md` | First time handling binary, or reading/writing the `$binary` slot | | `references/AGENT_TOOL_BINARY.md` | Agent tool needs a user-uploaded file, or produces a file (the boundary in either direction) | | `references/MERGE_FOR_CONTEXT.md` | Binary disappears after a JSON transform and needs to re-attach | | `references/CDN_REQUIREMENT.md` | Showing images in a chat surface or other places that need URL-referenced images | ## Anti-patterns | Anti-pattern | What goes wrong | Fix | |---|---|---| | Trying to read file content from `$json` | Binary isn't in `$json` | Use `$binary` | | Building an agent tool that returns binary directly | Tool output is JSON-only, so binary doesn't survive | Upload to storage, return key/URL in JSON (see `AGENT_TOOL_BINARY.md`) | | Trying to pass uploaded chat files into a tool via `fromAi` | `fromAi` doesn't carry binary, so the tool gets nothing | Pre-stage uploads to storage, inject keys in the system prompt, and have the tool download by key | | Setting `passthroughBinaryImages: true` and assuming tools can now see the file | The flag only affects what the LLM sees, not what tools receive | Still need the upload-and-pass-key pattern for tools | | Losing binary after a JSON transform | The transform's output item doesn't have binary | Use Merge to combine the JSON output with the binary stream | | Storing image in n8n binary and expecting a chat surface to display | Chat surfaces need URL-accessible images (or a platform-native file upload), not raw `$binary` | Upload to CDN, embed URL or use the platform's file API | | Hardcoding binary base64 in a Code node | Massive workflow JSON, slow, leaky | Reference binary via `$binary` properly, or upload to storage and reference by URL |

相关技能

文档办公

Ontology

为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…

文档办公

Nano Pdf

使用纳米-pdf CLI编辑带有自然语言指令的PDF.

文档办公

Word / DOCX

创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…

文档办公

Api Gateway

通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…