docs: document Human Input file inputs and Service API for self-host (#826) (backport to release/1.15.0)#827
Merged
Conversation
…826) * docs: document Human Input file inputs and API flow for self-host Cover the Human Input node's file-handling additions in the self-host tree: the Single File and File List field types, how file values render as `[file]` / `[N files]` placeholders in `__rendered_content`, and referencing an upstream file variable in Form Content. Add an API Integration Flow page for the Service API sequence (run, get form, upload via Upload File, submit, resume listening), register it in the self-host nav, add the Single File and File List glossary entries, and refresh the example images. Verified against dify 1.15.0 and graphon 0.5.3. Self-host only; the Cloud tree is updated separately. * docs: align Human Input API with HITL-2 form inputs Update the Human Input endpoints in the workflow and chatflow Service API specs to dify 1.15.0. Document file-mapping submit inputs, where a `file` or `file-list` value is `{transfer_method: local_file, upload_file_id}` (the id from Upload File) or `{transfer_method: remote_url, url}`, and replace the stale `text_input` type with the real `paragraph`, `select`, `file`, and `file-list` values in both the get-form response and the streaming `human_input_required` event. Make `expiration_time` nullable, drop the unenforced `action` length and pattern constraints, and align the zh delivery-method term with the product UI (提交方式). * docs: clarify WORKFLOW_FILE_UPLOAD_LIMIT as a per-field cap The old description read it as the maximum files per workflow execution. It actually bounds the max-files setting on a single file-upload field, such as a User Input or Human Input File List; the node panel's slider is capped at this value. Reword across en, zh, and ja. * feat: add code-audit step to api-reference skill Require an independent subagent audit against the codebase after writing or substantially changing endpoints. The brief pins the dify tag and the pinned graphon version, loads the skill references, and calls out the Service-API-vs-web/console controller distinction so the auditor verifies against the blueprint whose base URL matches the spec's servers. * docs: document file submission details for Human Input API Following the in-product docs PR (langgenius/dify#37981) and verified against dify 1.15.0 and graphon 0.5.3: a submitted file object carries a `type` from the field's `allowed_file_types`; a `local_file` upload must use the same `user` as the submit, since uploaded files are scoped to that user; and the get-form and submit examples now cover all four input shapes (paragraph, select, file, file-list). * feat: harden api-reference audit with data-path and example checks Add two guards to the post-writing code audit: trace opaque request fields to their resolver for ownership and cross-request rules, and diff the spec against the in-product API templates when the endpoint exists there. Add a mechanical example-and-schema consistency pass that checks example keys against schema fields and that every enum and `oneOf` branch is exercised. * docs: address PR review feedback on Human Input docs * docs: clarify Human Input API integration flow Apply reader-test findings and a code-verified correction to the integration flow page and the workflow/chatflow specs. - Spell out the submit lifecycle: a successful submit is one-shot (closes the form, resumes the run), a rejected one leaves the form open to retry, and the `action` must be one of the form's actions. - Note the form's `expiration_time` and that the resumed run streams through to completion. - Make the remote-file mapping concrete (`{transfer_method: remote_url, url}`). - Soften the file-upload `user` rule to a consistent-`user` recommendation across the run, upload, and submit (verified: the submit `user` is not matched against the run), in the page and both specs. - Mirror every change into zh and ja. * fix: correct field name in zh/ja invalid_form_data examples The zh/ja error examples still referenced `comment`; the earlier fix only caught the English message. Match the `feedback` request example. (cherry picked from commit 7694a26)
dosubot
Bot
added
size:XL
Contributor
There was a problem hiding this comment.
Pull request overview
This PR backports documentation updates to release/1.15.0 to cover Human Input file inputs and the end-to-end Service API flow for handling paused Human Input forms, including related OpenAPI spec updates, environment variable clarification, and navigation/glossary updates.
Changes:
- Expands the Human Input node docs (including file inputs,
__rendered_contentbehavior, and a full workflow example). - Adds an “API Integration Flow” page describing the Service API sequence for paused Human Input forms (Workflow + Chatflow).
- Updates OpenAPI specs and environment variable documentation to reflect current Human Input form shapes and file upload constraints; updates nav and glossary accordingly.
Reviewed changes
Copilot reviewed 18 out of 20 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| en/self-host/use-dify/nodes/human-input.mdx | Adds file field types/behavior, clarifies WebApp behavior, and includes a content review example. |
| en/self-host/use-dify/nodes/hitl-api-integration-flow.mdx | New page documenting the Service API sequence for paused Human Input forms (including file upload options). |
| en/self-host/deploy/configuration/environments.mdx | Clarifies what WORKFLOW_FILE_UPLOAD_LIMIT actually limits. |
| en/api-reference/openapi_workflow.json | Updates Human Input form/get/submit schemas and examples (including file inputs) for Workflow apps. |
| en/api-reference/openapi_chatflow.json | Updates Human Input form/get/submit schemas and examples (including file inputs) for Chatflow apps. |
| zh/self-host/use-dify/nodes/human-input.mdx | Chinese version of the Human Input node doc changes. |
| zh/self-host/use-dify/nodes/hitl-api-integration-flow.mdx | New Chinese “API Integration Flow” page for Human Input Service API usage. |
| zh/self-host/deploy/configuration/environments.mdx | Chinese clarification for WORKFLOW_FILE_UPLOAD_LIMIT. |
| zh/api-reference/openapi_workflow.json | Chinese Workflow OpenAPI updates for Human Input form and submission. |
| zh/api-reference/openapi_chatflow.json | Chinese Chatflow OpenAPI updates for Human Input form and submission. |
| ja/self-host/use-dify/nodes/human-input.mdx | Japanese version of the Human Input node doc changes. |
| ja/self-host/use-dify/nodes/hitl-api-integration-flow.mdx | New Japanese “API Integration Flow” page for Human Input Service API usage. |
| ja/self-host/deploy/configuration/environments.mdx | Japanese clarification for WORKFLOW_FILE_UPLOAD_LIMIT. |
| ja/api-reference/openapi_workflow.json | Japanese Workflow OpenAPI updates for Human Input form and submission. |
| ja/api-reference/openapi_chatflow.json | Japanese Chatflow OpenAPI updates for Human Input form and submission. |
| writing-guides/glossary.md | Adds glossary entries for Single File and File List. |
| docs.json | Registers the new Human Input integration-flow page in the sidebar nav. |
| .claude/skills/dify-docs-api-reference/SKILL.md | Adds stronger verification steps for API reference authoring/auditing. |
Comments suppressed due to low confidence (1)
ja/self-host/use-dify/nodes/human-input.mdx:96
- This section repeats the same explanation of
__action_id/__action_valueand includes a duplicate<Frame>pointing at the same image. Removing the duplicate avoids contradictory wording and duplicated images.
各ボタンには表示タイトルとアクション ID があります。ボタンがクリックされると、その ID は下流変数 `__action_id`、タイトル（ボタンテキスト）は `__action_value` として利用できます。
<Frame>
</Frame>
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Each input field becomes a variable for downstream use. For instance, pass edited content for further processing or send feedback to an LLM for content revision. | ||
| | Field Type | Description | | ||
| |:-----------|:------------| | ||
| | Paragraph | Text input. Can start empty, or pre-filled with variables (e.g., LLM output to refine) or static text (examples or default values). <br></br><br></br>No maximum length, but very long inputs may exceed downstream LLM context windows. | |
Comment on lines
+1459
to
+1466
| { | ||
| "group": "人工介入", | ||
| "expanded": false, | ||
| "root": "zh/self-host/use-dify/nodes/human-input", | ||
| "pages": [ | ||
| "zh/self-host/use-dify/nodes/hitl-api-integration-flow" | ||
| ] | ||
| }, |
Comment on lines
+2390
to
+2397
| { | ||
| "group": "人間の入力", | ||
| "expanded": false, | ||
| "root": "ja/self-host/use-dify/nodes/human-input", | ||
| "pages": [ | ||
| "ja/self-host/use-dify/nodes/hitl-api-integration-flow" | ||
| ] | ||
| }, |
Comment on lines
+20
to
+24
| - **提交方式**：请求表单如何送达接收人。 | ||
|
|
||
| - **表单内容**：接收人将看到什么信息以及他们可以与之交互的内容。 | ||
|
|
||
| - **用户动作**：接收人可以做出哪些决策，以及工作流相应如何进行。 | ||
| - **用户动作**：接收人可以做出哪些决策，以及工作流将如何相应地进行。 |
Comment on lines
40
to
42
| <Note> | ||
| 无论采用何种发送方式，请求将在收到第一个响应后关闭。 | ||
| 无论采用何种提交方式，请求都将在收到第一个响应后关闭。 | ||
| </Note> |
| 引用工作流变量以显示动态内容，例如供审核的 AI 生成文本或上游节点的任何上下文信息。 | ||
| 引用工作流变量以显示动态内容，例如供审核的 AI 生成文本，或他人在上游人工介入节点上传的待审核的文件。 | ||
|
|
||
| 在 WebApp 提交方式下，表单本身会直接展示给终端用户。表单中引用的任何变量的值都将直接显示，因此 **无需在人工介入节点之前再添加直接回复或输出节点**。 |
Comment on lines
+61
to
+63
| ## 提交方式要求 | ||
|
|
||
| 人工介入 API 仅支持通过人工介入节点的 WebApp 提交方式投递的表单。仅通过邮件投递的表单不会向 API 暴露 `form_token`。 |
Comment on lines
1888
to
1891
| "action": { | ||
| "type": "string", | ||
| "description": "ID of the action button the recipient selected. Must match one of the `id` values from the form's `user_actions` list (returned by [Get Human Input Form](/api-reference/human-input/get-human-input-form)).", | ||
| "maxLength": 20, | ||
| "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" | ||
| "description": "ID of the action button the recipient selected. Must match one of the `id` values from the form's `user_actions` list (returned by [Get Human Input Form](/api-reference/human-input/get-human-input-form))." | ||
| }, |
Comment on lines
3106
to
3109
| "action": { | ||
| "type": "string", | ||
| "description": "ID of the action button the recipient selected. Must match one of the `id` values from the form's `user_actions` list (returned by [Get Human Input Form](/api-reference/human-input/get-human-input-form)).", | ||
| "maxLength": 20, | ||
| "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" | ||
| "description": "ID of the action button the recipient selected. Must match one of the `id` values from the form's `user_actions` list (returned by [Get Human Input Form](/api-reference/human-input/get-human-input-form))." | ||
| }, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport
This will backport the following commits from
maintorelease/1.15.0: