# Input & Output Nodes

> Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: `crates/cheng-nodes/src/nodes/builtin/io`

These are the nodes that put data into a workflow. `io/input_text` carries literal text or a JSON
literal you type into the canvas; `io/file_upload` turns an upload into durable artifact references;
`io/read_file` reads a path the server can already see. The distinction that matters is inline value
versus artifact: an artifact port hands downstream nodes a reference instead of the bytes, so large
payloads never travel through the execution record. `io/file_upload` deliberately does no OCR,
parsing, or transcription — it routes each upload to a typed artifact port and leaves the conversion
to the media nodes.

## Text Input — `io/input_text`

Multi-line text / JSON input, outputs text, JSON value and AgentContext

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `text` | string | — | `""` | Plain text content (supports multi-line input). Control: `textarea` |
| `json_text` | string | — | `""` | JSON format content (ignored when empty). Control: `code-editor` |

### Outputs

| Field | Type | Description |
|---|---|---|
| `text` | string | Raw content of the text field (String) |
| `length` | integer | Character length of the text field (Number) |
| `json_value` | any | Parsed result of json_text (null if JSON is invalid) |
| `context` | object (port) | AgentContext output (can connect directly to Agent / Output nodes). Connection port, not a form field. |

## File Upload — `io/file_upload`

Route uploaded files to durable artifact references for documents, images, audio and video. OCR/parsing/transcription are dedicated downstream nodes.

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `files_json` | array<any> \| object \| string | — | `null` | Upload files via picker or drag-and-drop; returns artifact references. Control: `file-upload` |
| `allowed_category` | enum | — | `auto` | Restrict allowed file category. Control: `select`. Options: `auto` (自动检测), `image` (图片), `document` (文档), `audio` (音频), `video` (视频), `other` (其他) |
| `max_file_size_mb` | integer | — | `50` | Maximum size per file (MB). Control: `number` |
| `enable_ocr` | boolean | — | `false` | Deprecated and ignored. Connect image_artifact to io/ocr instead. Control: `switch` |
| `parse_documents` | boolean | — | `false` | Deprecated and ignored. Connect document_artifact to io/document_to_text instead. Control: `switch` |
| `llm_inline_max_bytes` | integer | — | `0` | 已废弃：不再产生需要离线存储的内联正文。保留以兼容旧工作流字段。 |

### Outputs

| Field | Type | Description |
|---|---|---|
| `artifacts` | array<object> (port) | All uploaded files as durable artifact references. Connection port, not a form field. |
| `first_artifact` | object (port) | Reference to the first uploaded file. Connection port, not a form field. |
| `document_artifact` | object (port) | First document artifact; connect to io/document_to_text.artifact. Connection port, not a form field. |
| `image_artifact` | object (port) | First image artifact; connect to io/ocr.artifact. Connection port, not a form field. |
| `audio_artifact` | object (port) | First audio artifact; connect to io/speech_to_text.artifact. Connection port, not a form field. |
| `video_artifact` | object (port) | First video artifact; connect to io/video_extract_audio.artifact. Connection port, not a form field. |
| `file_count` | integer | Number of files routed |
| `total_size` | integer | Total size of all files (bytes) |
| `errors` | array<string> | Error messages during processing |
| `llm_text` | string (port) | Bounded manifest (filename, type, size, artifact URI) for ai/llm.user_message. Connection port, not a form field. |
| `document_base64` | string | Deprecated: see `document_artifact`. Always None. |
| `document_filename` | string | Deprecated. Always None. |
| `document_text` | string | Deprecated. Always None. |
| `audio_base64` | string | Deprecated: see `audio_artifact`. Always None. |
| `audio_filename` | string | Deprecated. Always None. |
| `video_file_path` | string | Deprecated: see `video_artifact`. Always None. |
| `image_base64` | string | Deprecated: see `image_artifact`. Always None. |
| `image_filename` | string | Deprecated. Always None. |
| `file_paths` | string | Deprecated. Always None. |
| `chat_input_raw` | string | Deprecated. Always None. |
| `user_message_rich` | object | Deprecated: rich multimodal parts are materialized at the LLM node. Always None. |
| `ocr_text` | string | Deprecated: OCR is a dedicated node now. Always None. |
| `ocr_structured_json` | string | Deprecated. Always None. |
| `ocr_status` | string | Deprecated. Always None. |
| `ocr_results_json` | string | Deprecated. Always None. |

## Read File — `io/read_file`

Read a bounded range of a file as plain text from an artifact reference or local path. Connect to LLM text inputs.

### Inputs

| Field | Type | Required | Default | Description |
|---|---|:-:|---|---|
| `artifact` | object (port) | — | `null` | Artifact reference to read (preferred over file_path). Connection port, not a form field. |
| `file_path` | string | — | `null` | Absolute or relative local path (legacy; mutually exclusive with artifact). Control: `text` |
| `prefix` | string | — | `null` | Optional prefix prepended to content |
| `suffix` | string | — | `null` | Optional suffix appended to content |
| `start_byte` | integer | — | `0` | Byte offset to start reading from |
| `max_bytes` | integer | — | `16384` | Maximum bytes to read in this window (default 16 KiB, hard cap 1 MiB) |
| `start_line` | integer | — | `null` | 1-based start line (enables line mode) |
| `max_lines` | integer | — | `null` | Maximum lines to read in line mode |

### Outputs

| Field | Type | Description |
|---|---|---|
| `content` | string | Bounded plain-text content (with prefix/suffix) |
| `source_artifact` | object | Artifact that was read, if any |
| `bytes_read` | integer | 实际读取的字节数 |
| `total_bytes` | integer | 文件总字节数 |
| `truncated` | boolean | Whether more content exists beyond this window |
| `file_path` | string | Resolved path (legacy file_path input only) |
| `error` | string | 错误信息；成功时为 null |

## Next steps

- [Media Input Nodes](/docs/nodes-media-input)
- [Canvas Basics](/docs/editor-canvas-basics)
- [Variables & Data Mapping](/docs/editor-variables-and-mapping)