Document & Table Nodes

Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: crates/cheng-nodes/src/nodes/builtin/document, crates/cheng-nodes/src/nodes/builtin/table

Structured content, in two shapes. Documents are block-based: document/ops_hub dispatches by operation the way the file hub does, while the individual nodes create, query, and update blocks explicitly. Tables are record-based, with a query node, a node that applies record operations, and a node that renders a table into LLM context. The format_for_llm and build_llm_context nodes exist because raw document or table JSON is a poor prompt — they produce the bounded, readable form a model should actually see. Shadow-session internals are hidden and driven by the hub.

Document Operations Hub — `document/ops_hub`

Document operations hub node: control Agent document capabilities with toggle switches

Inputs

Field	Type	Required	Default	Description
`operation`	string	—	`""`	Operation type
`document_id`	string	—	—	Document ID (common to most operations)
`config`	object (port)	—	—	Unified config object (can input JSON text directly). Connection port, not a form field. Control: `text`
`workspace_id`	string	—	—	Workspace ID (used by create operation, set by user on canvas)
`allow_query`	boolean	✅	`true`	Whether to allow querying documents (read-only). Control: `switch`
`allow_format`	boolean	✅	`true`	Whether to allow formatting documents (read-only). Control: `switch`
`allow_discovery`	boolean	✅	`true`	Whether to allow document discovery (list/search) (read-only). Control: `switch`
`allow_diff`	boolean	✅	`true`	Whether to allow diff preview of proposed edits (read-only). Control: `switch`
`allow_update`	boolean	✅	`false`	Whether to allow updating document blocks (medium side-effect). Control: `switch`
`allow_batch`	boolean	✅	`false`	Whether to allow batch document operations (mixed side-effect). Control: `switch`
`allow_create`	boolean	✅	`false`	Whether to allow creating new documents (medium side-effect). Control: `switch`
`allow_duplicate`	boolean	✅	`false`	Whether to allow duplicating documents (medium side-effect). Control: `switch`
`allow_import`	boolean	✅	`false`	Whether to allow importing documents from text (medium side-effect). Control: `switch`
`allow_delete_document`	boolean	✅	`false`	Whether to allow hard-deleting documents (high risk). Control: `switch`
`allow_rollback`	boolean	✅	`false`	Whether to allow restoring/rolling back a document from a snapshot (high risk). Control: `switch`

Outputs

Field	Type	Description
`operation`	string	Actual operation type executed
`requires_review`	boolean	Whether this operation staged a shadow that must be reviewed.
`shadow_id`	string	Shadow session ID, when a write operation is staged for review.
`document_id`	string	Document ID associated with the staged review.
`change_summary`	string	Summary lifted from shadow apply output for Agent final/review handling.
`error`	string	Error message (operation prohibited or execution failed)
`result`	any	Operation result (JSON-serialized sub-node output)
`preview_context`	string	Preview lifted from shadow apply output for Agent final/review handling.

Create Document — `document/create`

Create a new document in workspace, supports AgentContext pass-through

Inputs

Field	Type	Required	Default	Description
`context`	object (port)	—	`null`	AgentContext port. Connection port, not a form field.
`title`	string	—	`null`	Optional title for the document.
`initial_content`	string	—	`null`	Initial content for the first block (optional).
`block_type`	string	—	`paragraph`	Block type for initial content (default: paragraph).
`priority`	enum	—	`normal`	Initial block priority. Control: `select`. Options: `low`, `normal`, `medium`, `high`, `critical`
`tags`	string	—	`null`	Initial block tags (comma-separated)

Outputs

Field	Type	Description
`context`	object (port)	AgentContext port. Connection port, not a form field.
`string`	string	Formatted success message with title and document_id
`document_id`	string	ID of the created document.
`title`	string	Title of the created document.
`root_block_id`	string	ID of the root block.
`success`	boolean	Whether creation was successful.
`error`	string	Error message if creation failed.

Query Document — `document/query`

Get document content, optionally return as block structure or Markdown format

Inputs

Field	Type	Required	Default	Description
`document_id`	string	✅	—	Select document to query (from current workspace). Control: `dynamic-select`
`include_content`	boolean	—	`true`	Whether to include full block content (default: true).
`as_markdown`	boolean	—	`false`	Optional: return content as markdown instead of blocks.

Outputs

Field	Type	Description
`success`	boolean	Whether the query was successful.
`found`	boolean	Whether the document was found.
`document_id`	string	Document ID (if found).
`title`	string	Document title.
`blocks`	array<object>	All blocks in the document.
`markdown`	string	Full document content as markdown (if as_markdown=true).
`plain_text`	string	Plain text content.
`block_count`	integer	Number of blocks.
`character_count`	integer	Total character count.
`error`	string	Error message if query failed.
`content_type`	string	Content type (richtext/markdown).
`root_block_id`	string	Root block ID.

Update Document Block — `document/update_block`

Update content or type of a specific block in document, supports AgentContext pass-through

Inputs

Field	Type	Required	Default	Description
`context`	object (port)	—	`null`	AgentContext port. Connection port, not a form field.
`document_id`	string	✅	—	Select document to update. Control: `dynamic-select`
`block_id`	string	✅	—	ID of the block to update.
`content`	string	✅	—	New content for the block.
`block_type`	string	—	`null`	New block type (optional, keeps existing if not provided).
`language`	string	—	`null`	Language for code blocks (optional).
`priority`	enum	—	`null`	Block priority. Control: `select`. Options: `low`, `normal`, `medium`, `high`, `critical`
`tags`	string	—	`null`	Block tags (comma-separated)

Outputs

Field	Type	Description
`context`	object (port)	AgentContext port. Connection port, not a form field.
`string`	string	Formatted success message with document_id and block_id
`success`	boolean	Whether the update was successful.
`block_id`	string	Updated block ID.
`block_type`	string	Updated block type.
`content`	string	Updated content.
`document_version`	integer	New document version after update.
`error`	string	Error message if update failed.

Extract Document Items — `document/extract_items`

Extract document block tags + lines into Loop-ready items

Inputs

Field	Type	Required	Default	Description
`document_id`	string	✅	—	Select a document, searchable by name. Control: `dynamic-select`
`extract_target`	enum	—	`tags`	Which payload to emit: tags, lines, pairs, objects, groups. Control: `select`. Options: `tags` (Just the tag list.), `lines` (Just the line list.), `pairs` (`{ tag, line }` pairs.), `objects` (Structured object whose keys are tags, values are selected lines.), `groups` (Full `{ tag, lines }` candidate pool.)
`combine_mode`	enum	—	`list`	Combination mode: list, sequential, random, selected, zip, cartesian. Control: `select`. Options: `list` (Simple flat list.), `sequential` (Iterate in document order (tags × lines, document-order interleaved).), `random` (One random pick per tag.), `selected` (Use `selection_map` to pick one line per tag.), `zip` (Align lines across tags by index.), `cartesian` (Cartesian product across tags.)
`tag_filter`	string	—	`null`	Filter tags (comma-separated, case-insensitive substring match)
`tag_policy`	enum	—	`first_tag`	How to handle blocks with multiple tags. Control: `select`. Options: `first_tag` (Use only the first tag of a block as its group label.), `all_tags` (The same block belongs to every tag it carries.)
`untagged_policy`	enum	—	`skip`	How to handle blocks without tags. Control: `select`. Options: `skip` (Skip blocks without tags (default).), `group` (Group untagged blocks under the synthetic tag `_untagged`.)
`selection_map`	object	—	`null`	User selection per tag (populated by popup widget). Control: `document-extract-selector`. Shown when `document_id`
`random_seed`	string	—	`null`	Optional seed for reproducible random selection
`max_items`	integer	—	`0`	Maximum number of items to emit (0 = unlimited). Control: `number`
`delimiter`	string	—	`,`	Delimiter used to join item texts into formatted_text
`strict`	boolean	—	`false`	Error out when selection_map references missing lines. Control: `switch`

Outputs

Field	Type	Description
`items`	any	Standard Loop items array
`formatted_text`	string	Items joined into a single string
`groups`	array<object>	Tag → candidate lines pool
`count`	integer	Items count.
`document_title`	string	Document title (if any).
`success`	boolean	Whether the node executed successfully.
`error`	string	Fatal error message (if any).
`warnings`	array<string>	Non-fatal warnings.

Format Document (LLM) — `document/format_for_llm`

Read and format document for LLM use, supports priority and tag filtering

Inputs

Field	Type	Required	Default	Description
`context`	object (port)	—	`null`	AgentContext port. Connection port, not a form field.
`document_id`	string	✅	—	Select a document to read, searchable by name. Control: `dynamic-select`
`priority_filter`	enum	—	`all`	Filter blocks by priority. Control: `select`. Options: `all` (所有优先级), `high_only` (仅高优先级（High + Critical）), `critical_only` (仅 Critical), `normal_and_above` (Normal 及以上（Normal + High + Critical）)
`tag_filter`	string	—	`null`	Filter by tags (comma-separated, e.g.: core concepts,API)
`sort_order`	enum	—	`original`	Block sort order. Control: `select`. Options: `original` (按文档原始顺序), `priority_desc` (按优先级降序（Critical -> High -> Normal -> Low）), `priority_asc` (按优先级升序（Low -> Normal -> High -> Critical）)
`output_format`	enum	—	`markdown`	Output format. Control: `select`. Options: `markdown` (Markdown 格式), `plain_text` (纯文本), `structured` (结构化（包含块信息）)
`include_metadata`	boolean	—	`true`	Whether to include block tags and priority info in output
`system_prompt`	string	—	`null`	Custom system prompt (optional). Control: `textarea`
`max_chars`	integer	—	`0`	Maximum character limit (0 means unlimited)

Outputs

Field	Type	Description
`context`	object (port)	AgentContext port. Connection port, not a form field.
`formatted_content`	string	Formatted document content
`preview_content`	string	Preview-friendly document summary with title, character count, and content excerpt
`blocks`	array<object>	Structured block list
`title`	string	文档标题
`block_count`	integer	处理的块数量
`filtered_block_count`	integer	过滤后的块数量
`character_count`	integer	总字符数
`truncated`	boolean	是否被截断
`success`	boolean	是否成功
`error`	string	错误信息

Query Table — `table/query`

Get table data, including column definitions and records

Inputs

Field	Type	Required	Default	Description
`table_id`	string	✅	—	ID of the table to query.
`record_ids`	array	—	`null`	Optional list of specific record IDs to fetch. If not provided, fetches all records (paginated).
`include_schema`	boolean	—	`true`	Whether to include column definitions (default: true).
`page`	integer	—	`1`	Page number for pagination (1-based, default: 1).
`page_size`	integer	—	`100`	Number of records per page (default: 100, max: 1000).

Outputs

Field	Type	Description
`success`	boolean	Whether the query was successful.
`found`	boolean	Whether the table was found.
`table`	object	Table metadata (if found).
`columns`	array<object>	Column definitions (if include_schema=true).
`records`	array<object>	Records data.
`total_records`	integer	Total number of records in the table.
`page`	integer	Current page number.
`total_pages`	integer	Total number of pages.
`error`	string	Error message if query failed.
`markdown`	string	Markdown formatted table (columns + records), suitable for preview node.
`agent_context`	object (port)	AgentContext port (can be directly connected to Agent node's context input). Connection port, not a form field.

Apply Table Operations — `table/apply_record_ops`

Batch apply table record insert, update, delete operations

Inputs

Field	Type	Required	Default	Description
`table_id`	string	✅	—	Table ID to apply operations to.
`operations`	array<enum>	✅	—	List of operations to apply.
`summary`	string	—	`null`	Optional summary of changes (for logging/audit).

Outputs

Field	Type	Description
`success`	boolean	Whether all operations were successful.
`results`	array<object>	Results for each operation.
`summary`	string	Summary of changes.
`table_id`	string	Table ID.
`records_affected`	integer	Number of records affected.
`records_inserted`	integer	Number of records inserted.
`records_updated`	integer	Number of records updated.
`records_deleted`	integer	Number of records deleted.
`error`	string	Error message if the overall operation failed.

Build Table LLM Context — `table/build_llm_context`

Build context information for LLM table editing

Inputs

Field	Type	Required	Default	Description
`table_id`	string	✅	—	Table ID to build context for.
`selected_record_ids`	array	—	`null`	Optional list of selected record IDs. If provided, only these records will be included in the context.
`instruction`	string	✅	—	User's editing instruction/request.
`format`	string	—	`json`	Output format: "json", "markdown", or "csv".
`max_records`	integer	—	`100`	Maximum records to include in context (0 = unlimited).

Outputs

Field	Type	Description
`success`	boolean	Whether context building was successful.
`table_id`	string	Table ID.
`table_name`	string	Table name.
`system_prompt`	string	System prompt for LLM.
`table_context`	string	Table context (formatted table data).
`user_prompt`	string	User instruction (formatted).
`tools_json`	string	Tool definitions JSON for LLM function calling.
`llm_context`	string	Integrated LLM context as JSON string. Connect this to ReAct agent's `task` input.
`agent_context`	object (port)	AgentContext port (can be directly connected to Agent node's context input). Connection port, not a form field.
`records_included`	integer	Number of records included.
`column_count`	integer	Number of columns.
`error`	string	Error message if building failed.
`warnings`	array<string>	Warnings generated during context building.

Document & Table Nodes

Document Operations Hub — document/ops_hub

Inputs

Outputs

Create Document — document/create

Inputs

Outputs

Query Document — document/query

Inputs

Outputs

Update Document Block — document/update_block

Inputs

Outputs

Extract Document Items — document/extract_items

Inputs

Outputs

Format Document (LLM) — document/format_for_llm

Inputs

Outputs

Query Table — table/query

Inputs

Outputs

Apply Table Operations — table/apply_record_ops

Inputs

Outputs

Build Table LLM Context — table/build_llm_context

Inputs

Outputs

Next steps

Document Operations Hub — `document/ops_hub`

Create Document — `document/create`

Query Document — `document/query`

Update Document Block — `document/update_block`

Extract Document Items — `document/extract_items`

Format Document (LLM) — `document/format_for_llm`

Query Table — `table/query`

Apply Table Operations — `table/apply_record_ops`

Build Table LLM Context — `table/build_llm_context`