You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: document app package export and import for ce 1.18.0 - #1097
CE 1.18.0 replaces YAML DSL export with app packages (.ifpkg) for every app type, and the console entries are now Export App and Import App. This PR updates the self-host docs to match, in en, zh, and ja.
Changes
New page workspace/export-import-apps.mdx, replacing workspace/app-management.mdx, with nav entries and redirects in docs.json for all three languages. It covers exporting (draft vs. published version, what an export leaves behind, secret values), creating a new app via import, updating an existing Workflow or Chatflow via import, and importing into a Dify version earlier than 1.18.0.
build/new-agent/build.mdx: import from an app package or DSL file through Create > Import App; export through Export App.
nodes/agent.mdx: invited agents become one-time copies when a workflow is imported. The Info on nodes that invite the same agent moves into the Invite an Agent tab.
build/version-control.mdx: exporting a published version as an app package.
publish/publish-to-marketplace.mdx: the Creator Center tab uploads the .ifpkg (up to 10 MB) exported with secret values off.
learn/key-concepts.mdx: one heading per concept, with the Dify DSL and Environment Variables sections rewritten. Inbound anchors #dify-app, #variables, #dify-应用, and #变量 are unchanged.
Before merging
Glossary: after docs: sync ce 1.18.0 agent, env, api, and skills changes #1095 merges, replace the Export DSL and Import DSL file rows (their keys are gone) with Export App and Import App, add Export secret values and app package, and regenerate the termbase. This lands as a commit on this branch.
Production Creator Center accepts .ifpkg uploads. Today only the dev environment does (langgenius/dify-marketplace#205, still a draft). If production doesn't by release, the Creator Center tab needs a fallback.
Re-verify at the 1.18.0 tag: the quoted UI labels, the export and import behavior the page describes, and whether Studio's Publish to Marketplace still uploads YAML.
Notes for reviewers
Only the self-host copies change. The Cloud copies follow at the Cloud 1.18.0 pass.
Capitalize Secret-type here. The repository consistently treats Secret as the environment-variable type name (for example, en/self-host/use-dify/workspace/export-import-apps.mdx:39, build/version-control.mdx:95, and nodes/http-request.mdx:44).
Update glossary with replacement app package terms
The terminology update required by the PR is still missing: writing-guides/glossary.md:300-301 still defines the removed Export DSL and Import DSL file labels, and has no entries for Export App, Import App, Export secret values, or “app package.” Add the replacement rows and regenerate the termbase before merging so the three editions have an authoritative set of labels.
The exclusions omit the Agent's persistent sandbox filesystem. At Dify 0d06488de5, AgentPackageResourceExporter packages configured skills, files, and icons, but not the sandbox snapshot; AgentDslService._create_snapshot sets home_snapshot_id=None for imported workflow Agents. Files and installed programs created in Build mode outside those configured assets therefore do not survive export/import. Readers using this procedure as a backup need to know to preserve or recreate that setup separately. Add this exclusion here and in the Chinese and Japanese versions of workspace/export-import-apps.mdx.
Document that schedules and webhook URLs are not exported
This list omits schedule settings and webhook URLs. At Dify 0d06488de5, AppDslService._append_workflow_export_data resets schedule-trigger configuration to defaults and clears webhook URLs; AppPackageService.export_app uses that exporter. Since the post-import instructions refer readers back to this list, they can publish a migrated workflow with the wrong schedule or leave callers targeting the source workflow. Document both exclusions, tell readers to restore schedules before publishing, and have them check destination webhook URLs. Apply the same correction to the Chinese and Japanese versions of this page.
…abels in the glossary
Adds persistent files in an Agent's file system to what the export leaves behind, since packages carry only the Files section. Replaces the Export DSL and Import DSL file glossary rows, whose keys #42732 removed, with Export App and Import App, adds Export Agent, Export secret values, and App package, and regenerates the termbase. Fixes the ja wording for packages exported from a Workflow or Chatflow. Verified against dify 229c3f1165.
* chore: sync main into release/1.18.0 (#1096)
* fix: point glossary rows at live i18n keys (#1083)
* fix: point glossary rows at live i18n keys
* fix: give knowledge retrieval labels their own glossary section
Move Query Text, Query Images and Metadata Filtering out of Agent Node Config, and add the metadata filtering modes Disabled, Automatic and Manual. Regenerate the termbase.
* docs: record stored strings for case-styled ui labels
State in the glossary's UI Labels intro that rows record the string stored at the key, even when the UI changes its case on screen.
* feat: set research depth by product change and add pack task analysis (#1094)
* feat: set research depth by product change and add pack task analysis
Research depth now follows what changed for the reader: a new capability runs in full even when it lands as one section of an existing page, a changed behavior runs at targeted depth, and a correction verifies the disputed claim. Filling a gap on an unchanged product gets its own line. Both research depths now gather user reports, searched by the problem a feature solves as well as its name.
Only a single-page correction skips the S4 stop.
The env-var and API rule packs gain the S3 task analysis they lacked: the env pack for variable groups an operator sets up, and the API pack for each changed tag group.
* feat: add a task-analysis step to the cli rule pack
The CLI pack went from S2 straight to S7, as the env-var and API packs did before this PR. It now runs the pipeline's task analysis for each command or concept a change adds or alters, so CLI pages answer the reader's job, not just the command's flags.
* fix: give every env variable a task analysis and walk gaps in delta depth
The env pack exempted a single variable that changes one value of an existing setup, but a single limit or default can still change what the operator gets, and the pipeline gives every behavior change at least a Delta analysis. The exemption is replaced with proportion: a single variable's analysis is usually short.
Delta depth routed documentation gaps but walked only changed steps, which a gap doesn't have. It now walks the steps the docs don't yet cover.
* feat: check and freeze the english before translating
Checking now runs in two passes. The English pass runs the editor test, the reader test, the format and terminology checks, and the pack verifiers, then stops for the owner to freeze the English. Translation and its checks follow. In the old order the reader test and the owner's review came after translation, so any English change they caused sent its sentences back through translation and the translation test.
A single-page correction still skips the stop, and the stage numbers stay as packs and hooks cite them.
* fix: report env-var scope before drafting and re-test reader-test edits
The env pack wrote user-facing descriptions (S5) before its S4 scope report, so descriptions were drafted before the owner approved the scope. The report now comes first, and descriptions are written after approval.
In the English check pass, a unit the reader test changes now goes back through the editor test before the English is frozen, so added prose doesn't skip editorial review.
* fix: load s3 pack steps and align the env summary and api check pass
The S1-S3 read loaded only the packs' S2 procedures, so the S3 steps added to the env-var, API, and CLI packs were never read at that stage; it now loads S2 and S3. The env pack's bold summary now lists the steps in their real order, task analysis included. The two-pass check now says how it applies to the API pack, which edits its three specs in one pass: the owner reviews all three languages together, and the parity check stands in for the second pass.
* fix: fold api translation into s5 and walk any changed part in delta
The API pack said its zh and ja specs are edited at S6, which the English check pass and owner review run before, so the API exception could not run as written. The pack now folds S6 into S5: all three specs are edited together while writing, so the English pass checks and the owner reviews all three, and the parity check replaces the translation pass.
Delta depth applied its prompts only to changed steps, which skips a change that affects only a prerequisite, a limit, or the outcome. It now walks whatever changed.
* fix: align the packs and guides with the english-first check order
* fix: rerun the english checks on corrections found in translation
* chore: sync main into release/1.18.0 (#1125)
* fix: point glossary rows at live i18n keys (#1083)
* fix: point glossary rows at live i18n keys
* fix: give knowledge retrieval labels their own glossary section
Move Query Text, Query Images and Metadata Filtering out of Agent Node Config, and add the metadata filtering modes Disabled, Automatic and Manual. Regenerate the termbase.
* docs: record stored strings for case-styled ui labels
State in the glossary's UI Labels intro that rows record the string stored at the key, even when the UI changes its case on screen.
* feat: set research depth by product change and add pack task analysis (#1094)
* feat: set research depth by product change and add pack task analysis
Research depth now follows what changed for the reader: a new capability runs in full even when it lands as one section of an existing page, a changed behavior runs at targeted depth, and a correction verifies the disputed claim. Filling a gap on an unchanged product gets its own line. Both research depths now gather user reports, searched by the problem a feature solves as well as its name.
Only a single-page correction skips the S4 stop.
The env-var and API rule packs gain the S3 task analysis they lacked: the env pack for variable groups an operator sets up, and the API pack for each changed tag group.
* feat: add a task-analysis step to the cli rule pack
The CLI pack went from S2 straight to S7, as the env-var and API packs did before this PR. It now runs the pipeline's task analysis for each command or concept a change adds or alters, so CLI pages answer the reader's job, not just the command's flags.
* fix: give every env variable a task analysis and walk gaps in delta depth
The env pack exempted a single variable that changes one value of an existing setup, but a single limit or default can still change what the operator gets, and the pipeline gives every behavior change at least a Delta analysis. The exemption is replaced with proportion: a single variable's analysis is usually short.
Delta depth routed documentation gaps but walked only changed steps, which a gap doesn't have. It now walks the steps the docs don't yet cover.
* feat: check and freeze the english before translating
Checking now runs in two passes. The English pass runs the editor test, the reader test, the format and terminology checks, and the pack verifiers, then stops for the owner to freeze the English. Translation and its checks follow. In the old order the reader test and the owner's review came after translation, so any English change they caused sent its sentences back through translation and the translation test.
A single-page correction still skips the stop, and the stage numbers stay as packs and hooks cite them.
* fix: report env-var scope before drafting and re-test reader-test edits
The env pack wrote user-facing descriptions (S5) before its S4 scope report, so descriptions were drafted before the owner approved the scope. The report now comes first, and descriptions are written after approval.
In the English check pass, a unit the reader test changes now goes back through the editor test before the English is frozen, so added prose doesn't skip editorial review.
* fix: load s3 pack steps and align the env summary and api check pass
The S1-S3 read loaded only the packs' S2 procedures, so the S3 steps added to the env-var, API, and CLI packs were never read at that stage; it now loads S2 and S3. The env pack's bold summary now lists the steps in their real order, task analysis included. The two-pass check now says how it applies to the API pack, which edits its three specs in one pass: the owner reviews all three languages together, and the parity check stands in for the second pass.
* fix: fold api translation into s5 and walk any changed part in delta
The API pack said its zh and ja specs are edited at S6, which the English check pass and owner review run before, so the API exception could not run as written. The pack now folds S6 into S5: all three specs are edited together while writing, so the English pass checks and the owner reviews all three, and the parity check replaces the translation pass.
Delta depth applied its prompts only to changed steps, which skips a change that affects only a prerequisite, a limit, or the outcome. It now walks whatever changed.
* fix: align the packs and guides with the english-first check order
* fix: rerun the english checks on corrections found in translation
* fix: update the next.js version in the local source web sample output (#1099)
* fix: correct the audio-to-text 400 error codes (#1101)
* fix: correct integration permission labels and install details (#1102)
* fix: correct integration permission labels and install details
* fix: keep the tool integration type singular
* docs: document deleting archived logs on cloud (#1103)
* fix: correct the knowledge api key path and note key limits (#1104)
* docs: split archived logs into download and delete (#1118)
* fix: point plugin debugging page to the integrations debugging entry (#1123)
The remote debugging page still sent readers to the old Plugins page in the top-right corner, a bug icon next to Install Plugin, and a debug dialog, with two 2024 screenshots of that UI. Since CE 1.15.0 the entry is Debugging at the bottom of the Integrations sidebar.
- Prerequisites: the requirement is now the Who can debug? permission
- Step 1: open Debugging in Integrations; outdated screenshot removed
- Step 4: find the plugin in its type's section in Integrations; outdated screenshot removed; it stays available only while the local process is connected
- Troubleshooting: drop the debug dialog and the nonexistent key regeneration; copy the current key from Debugging instead
en, zh, and ja updated together.
* docs: sync ce 1.18.0 agent, env, api, and skills changes (#1095)
* fix: point glossary rows at live i18n keys (#1083)
* fix: point glossary rows at live i18n keys
* fix: give knowledge retrieval labels their own glossary section
Move Query Text, Query Images and Metadata Filtering out of Agent Node Config, and add the metadata filtering modes Disabled, Automatic and Manual. Regenerate the termbase.
* docs: record stored strings for case-styled ui labels
State in the glossary's UI Labels intro that rows record the string stored at the key, even when the UI changes its case on screen.
* docs: document output routes on the agent node
Adds the Let It Choose a Route section to the New Agent tab: when to use routes instead of IF/ELSE, how to write route descriptions, the always-one-route behavior, and the failure case with a Fail Branch fallback. Verified against dify 2b65f0e893. Also corrects the ja beta note: the node, not its runtime, is on by default.
* docs: document ce 1.18.0 agent and app package environment variables
Covers the agent runtime backends (local, E2B, OpenShell) with setup steps, agent trajectory export, skill package and app package limits, and the new agent backend rows. Verified against dify 2b65f0e893; the OTLP anchors keep their live ids.
* docs: update service api citation fields and metadata errors
Drops the stale 400 on the metadata endpoints, adds the second 404 on PATCH and DELETE, adds doc_metadata, files, and title to retriever resources, and clarifies page and limit handling. Verified against dify 2b65f0e893.
* docs: update skill duplicate and export to use the latest draft
Duplicate and Export both take the latest saved draft, unpublished changes included. Verified against dify 2b65f0e893.
* fix: match ja ui labels for skills, speech models, and knowledge base
Aligns the ja pages and glossary rows with the ja UI strings at dify 2b65f0e893, and regenerates the termbase.
* docs: add output routes and error handling labels to the glossary
Adds Output Routes, Error Handling, and Fail Branch with their zh and ja UI strings at dify 2b65f0e893, confirmed at their render sites, and regenerates the termbase.
* feat: set research depth by product change and add pack task analysis (#1094)
* feat: set research depth by product change and add pack task analysis
Research depth now follows what changed for the reader: a new capability runs in full even when it lands as one section of an existing page, a changed behavior runs at targeted depth, and a correction verifies the disputed claim. Filling a gap on an unchanged product gets its own line. Both research depths now gather user reports, searched by the problem a feature solves as well as its name.
Only a single-page correction skips the S4 stop.
The env-var and API rule packs gain the S3 task analysis they lacked: the env pack for variable groups an operator sets up, and the API pack for each changed tag group.
* feat: add a task-analysis step to the cli rule pack
The CLI pack went from S2 straight to S7, as the env-var and API packs did before this PR. It now runs the pipeline's task analysis for each command or concept a change adds or alters, so CLI pages answer the reader's job, not just the command's flags.
* fix: give every env variable a task analysis and walk gaps in delta depth
The env pack exempted a single variable that changes one value of an existing setup, but a single limit or default can still change what the operator gets, and the pipeline gives every behavior change at least a Delta analysis. The exemption is replaced with proportion: a single variable's analysis is usually short.
Delta depth routed documentation gaps but walked only changed steps, which a gap doesn't have. It now walks the steps the docs don't yet cover.
* feat: check and freeze the english before translating
Checking now runs in two passes. The English pass runs the editor test, the reader test, the format and terminology checks, and the pack verifiers, then stops for the owner to freeze the English. Translation and its checks follow. In the old order the reader test and the owner's review came after translation, so any English change they caused sent its sentences back through translation and the translation test.
A single-page correction still skips the stop, and the stage numbers stay as packs and hooks cite them.
* fix: report env-var scope before drafting and re-test reader-test edits
The env pack wrote user-facing descriptions (S5) before its S4 scope report, so descriptions were drafted before the owner approved the scope. The report now comes first, and descriptions are written after approval.
In the English check pass, a unit the reader test changes now goes back through the editor test before the English is frozen, so added prose doesn't skip editorial review.
* fix: load s3 pack steps and align the env summary and api check pass
The S1-S3 read loaded only the packs' S2 procedures, so the S3 steps added to the env-var, API, and CLI packs were never read at that stage; it now loads S2 and S3. The env pack's bold summary now lists the steps in their real order, task analysis included. The two-pass check now says how it applies to the API pack, which edits its three specs in one pass: the owner reviews all three languages together, and the parity check stands in for the second pass.
* fix: fold api translation into s5 and walk any changed part in delta
The API pack said its zh and ja specs are edited at S6, which the English check pass and owner review run before, so the API exception could not run as written. The pack now folds S6 into S5: all three specs are edited together while writing, so the English pass checks and the owner reviews all three, and the parity check replaces the translation pass.
Delta depth applied its prompts only to changed steps, which skips a change that affects only a prerequisite, a limit, or the outcome. It now walks whatever changed.
* fix: align the packs and guides with the english-first check order
* fix: rerun the english checks on corrections found in translation
* fix: drop the uv_cache_dir row that ce 1.18.0 removes
The variable is gone from the env templates at dify 6af1bb709b, and the compose plugin daemon is still 0.6.10-local. Restore it under Plugin Daemon only if the release ships daemon 0.6.11 or later.
* docs: document client ip and crawler ssrf proxy changes for ce 1.18.0
Adds a FAQ entry for sign-in emails blocked behind Cloudflare, a load balancer, or another proxy, with the Nginx real-ip setup for each proxy type. Moves RESPECT_XFORWARD_HEADERS_ENABLED to its own heading under Nginx Reverse Proxy with its Docker Compose and source defaults, and extends the SSRF allowlist rows for self-hosted Firecrawl and WaterCrawl. Verified against dify 16a2f5abd5 (langgenius/dify#43897, #43898).
* docs: document plugin install default and password pepper for ce 1.18.0
Rewrites the integration permissions on the self-host Integrations page with the product's labels, where to find them, and the options each takes. Adds a PASSWORD_PEPPER heading next to SECRET_KEY on the environment variable page: when to set it, why it belongs in api.env, and how to undo a mistake or let members back in. Verified against dify ba5532ace0.
* fix: say only owners and admins can remove integrations
* docs: add OAUTH_TTL_DAYS and update Landlock sandbox behavior
* fix: correct worker, debug, stop, and default model docs for ce 1.18.0
* fix: require the local sandbox token for ce 1.18.0
* fix: correct webhook errors, node floor, and creator center upload for ce 1.18.0
* fix: rename the zh access point label to 访问入口
* docs: document agent tracing for ce 1.18.0
* docs: document nested workflow tools for ce 1.18.0
* fix: apply review fixes for form_id, forwarded headers, odt, and aop
Adds form_id to the human_input_form_filled and human_input_form_timeout schemas and the resumed-stream examples, and says on human_input_required that clients match these events by form_id because node_id can repeat across forms. Rewrites the RESPECT_XFORWARD_HEADERS_ENABLED warning: containers on the API's Docker networks, such as the code sandbox, can still connect directly, so untrusted workloads need network isolation and a gateway that rewrites X-Forwarded-For. Restores ODT on the document extractor page (parsed locally, or through the Unstructured API when one is configured) and qualifies the Cloudflare tip as zone-level or per-hostname Authenticated Origin Pulls with your own certificate. Verified against dify 229c3f1165 and graphon 4fa2214.
* fix: add cloudflare tunnel as a way to restrict origin access
Takes the reviewer's wording for the Cloudflare tab: zone-level or per-hostname Authenticated Origin Pulls with your own certificate, or Cloudflare Tunnel.
* docs: document app package export and import for ce 1.18.0 (#1097)
* docs: replace app management with an export and import apps page
* docs: point agent, version, and marketplace pages to app packages
* docs: restructure key concepts and rewrite the dsl and env var sections
* docs: restore size tips for oversized creator center uploads
* docs: clarify what an update import keeps and how integrations install
* docs: use the export agent label for agent exports
* docs: list workflow, swagger api, and mcp tools as left behind on export
* docs: list agent file system files as left behind and update export labels in the glossary
Adds persistent files in an Agent's file system to what the export leaves behind, since packages carry only the Files section. Replaces the Export DSL and Import DSL file glossary rows, whose keys #42732 removed, with Export App and Import App, adds Export Agent, Export secret values, and App package, and regenerates the termbase. Fixes the ja wording for packages exported from a Workflow or Chatflow. Verified against dify 229c3f1165.
* docs: rewrite the cli docs for difyctl in dify 1.18.0 (#1126)
* docs: rewrite the english cli docs for difyctl in dify 1.18.0
- Add the CE pages for the difyctl command set that ships with Dify
1.18.0, grouped in the nav as Work with Apps, Manage difyctl, and
Reference, with Get Started covering install, sign-in, and agent setup.
- Move the pre-1.18.0 pages to en/cloud/cli for Dify Cloud readers.
- Point the environment variable reference at the new Get Started page.
- docs.json: navigation for all three languages and redirects from the
retired pages. The zh and ja pages follow in a separate commit, so the
zh and ja navigation points at pages that are not in this commit.
* fix: correct the dsl example indent and reword the build apps opening
- Indent the "mode" lines in the DSL page's app list example to match
the lines around them.
- Open Build Apps with the recommendation to let the coding agent build
the app, since the page covers no hand-built path.
* translate: sync the zh and ja cli docs with the 1.18.0 rewrite
- Bring the zh and ja CE CLI pages in line with the English rewrite,
including the new pages, the Work with Apps, Manage difyctl, and
Reference nav groups, and the moved Find and Run Commands and Build
Apps pages.
- Move the pre-1.18.0 zh and ja pages to the Cloud tree.
- Point the zh and ja environment variable references at Get Started.
- Translate natural-language example values in code blocks, per the
zh and ja formatting guides.
* fix: link the cli dsl page to the merged app package pages
Removes the pending-link markers now that Key Concepts and Export and Import Apps are on the release branch, and points the zh and ja DSL links at #dify-dsl.
* fix: match the knowledge retrieval field label in workflow 101 lesson 4
The 1.18.0 tag renames the field to Knowledge Base in en; the ja page also gets the node's 知識検索 name and the field's ナレッジベース label.
* fix: scope agent tracing to agents outside workflow tools and clarify retention
Agents inside a workflow tool the app calls aren't traced, and each app also needs Capture Agent internals on. The reconcile task's retention deletes only the trace data Dify stores, not what the tracing provider already received.
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
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.
CE 1.18.0 replaces YAML DSL export with app packages (
.ifpkg) for every app type, and the console entries are now Export App and Import App. This PR updates the self-host docs to match, in en, zh, and ja.Changes
workspace/export-import-apps.mdx, replacingworkspace/app-management.mdx, with nav entries and redirects indocs.jsonfor all three languages. It covers exporting (draft vs. published version, what an export leaves behind, secret values), creating a new app via import, updating an existing Workflow or Chatflow via import, and importing into a Dify version earlier than 1.18.0.build/new-agent/build.mdx: import from an app package or DSL file through Create > Import App; export through Export App.nodes/agent.mdx: invited agents become one-time copies when a workflow is imported. The Info on nodes that invite the same agent moves into the Invite an Agent tab.build/version-control.mdx: exporting a published version as an app package.publish/publish-to-marketplace.mdx: the Creator Center tab uploads the.ifpkg(up to 10 MB) exported with secret values off.learn/key-concepts.mdx: one heading per concept, with the Dify DSL and Environment Variables sections rewritten. Inbound anchors#dify-app,#variables,#dify-应用, and#变量are unchanged.Before merging
Export DSLandImport DSL filerows (their keys are gone) with Export App and Import App, add Export secret values and app package, and regenerate the termbase. This lands as a commit on this branch..ifpkguploads. Today only the dev environment does (langgenius/dify-marketplace#205, still a draft). If production doesn't by release, the Creator Center tab needs a fallback.Notes for reviewers
release/1.18.0and with docs: sync ce 1.18.0 agent, env, api, and skills changes #1095.Closes DC-371