mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-22 04:15:24 -04:00
Riskey
17ce877aa5
* docs: add New Agent user guide and node tab * docs: add ENABLE_AGENT_V2 to environment variable reference * translate: add zh and ja New Agent documentation * docs: add New Agent navigation groups * feat: add limits and quotas rule to style guide * docs: add skill and file upload limits to New Agent guide * fix: redirect new-agent doc paths from UI links to self-host pages * docs: add task examples and refine New Agent pages * docs: update New Agent data security notice per legal * docs: extend security notice coverage and build note explanation Surface the legal data security Warning on the Build page and New Agent node tab (en/zh/ja), and explain the build note as the agent's memory across build chats with an example. * docs: refine New Agent guidance and cross-link from classic Agent Model note gains the older-model sandbox symptom; node opener differentiates from the classic node; Build page restructured (review bullets, Info callout, section links) with zh/ja synced; classic Agent app page (self-host) gains a New Agent Tip. * docs: document memory, permissions, and sandbox facts for New Agent Verified additions: per-conversation memory bounded by the model's context window; Editor-tier permissions for creating and managing agents; unrestricted sandbox network access; version restore excludes the sandbox environment; build note deletion and regeneration behavior. * docs: rename Roster to Agent page across New Agent docs The UI removed the Roster concept; the nav entry is now Agent. Updated pages, node tab titles, image alt text, and the ENABLE_AGENT_V2 reference entry in en/zh/ja. Agent Console button labels are unchanged in the UI and stay verbatim. * docs: add files vs knowledge guidance and restructure page openers Decision aid for uploading as Files vs connecting a knowledge base (read-in-full vs search), knowledge opener gains relevance and workspace-asset framing, overview and build intros restructured. * docs: update docker compose container list and add tool prerequisites (#843) * docs: update docker compose container list and add tool prerequisites - Add api_websocket and init_permissions to the started-container list per the current compose defaults - Remove outdated sample outputs for docker compose up and docker compose ps - Add a callout noting the clone command requires git, curl, and jq, with recovery guidance on command not found errors - Mirror all changes to zh and ja * docs: note expected exited status for init_permissions container * fix: align tools page tab titles across languages and fix anchors Shorten the Swagger and Workflow tab titles ("Swagger API as Tool" -> "Swagger API", "Workflow as Tool" -> "Workflow") in en, zh, and ja so all three languages generate the same tab anchors. Update the inbound links in output.mdx that pointed at the old Workflow-tab anchor (#workflow-as-tool, #工作流作为工具, #ワークフローをツールとして利用) to #workflow. * feat: consolidate and restructure the API reference (Phase 1) (#846) * docs: correct HITL API integration flow and sync translations - Fix the claim that the resume endpoint differs per app type (same endpoint; only the entry endpoint differs) - Tie workflow_run_id guidance to the human_input_required event (chatflow message chunks don't carry it) - Require the same user when resuming the event stream (mismatch returns 404); add include_state_snapshot and continue_on_pause guidance - Note at the capture step that a null form_token means Email delivery - Soften the upload-time validation claim to file size limits - Split long paragraphs; align zh endpoint name with the reference page * fix: correct API references against verified backend behavior Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with every change code-verified and the serious items adversarially confirmed. Applies to en/zh/ja. - Add curl samples for GET endpoints with required query params (Mintlify omits query params from generated snippets) - Document 401 once in every spec's auth scheme description - Correct wrong facts: workflow run detail returns inputs as a JSON string; DELETE /conversations requires a JSON body; audio-to-text accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log created_by_account filters by email; triggered_from values are app-run/webhook/schedule/plugin; stop endpoints' user semantics differ per app type - Remove unreachable docs: phantom text_replace SSE event, annotation 403, file preview endpoint in the workflow spec, invented score_threshold bounds - Make upload user optional (DEFAULT-USER fallback), fix upload response example, add missing invalid_param error - Declare text_to_speech.autoPlay in parameters responses (prose values, no response-field enums) * fix: complete API reference audit for knowledge and completion specs * feat: add API spec consolidation pipeline Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes. * feat: consolidate API reference into one spec per language Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered. * fix: remove dead conversation_completed error from chat specs ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list. * feat: add membership matrix and restructure nav config * feat: rename resource tags and update all references * feat: stamp per-operation availability lines * feat: wire three-group API navigation * feat: add app-type page coverage lint * docs: rewrite chatflow overview as app-type API guide * docs: polish chatflow overview zh and ja wording * docs: rewrite workflow overview as app-type API guide * docs: align workflow overview details across languages * docs: expand new agent overview into app-type API guide * docs: use task-oriented heading on new agent overview * docs: rewrite chatbot and agent overview as app-type API guide * docs: rewrite text generator overview as app-type API guide * docs: match end user link text to merged spec summary * docs: rewrite knowledge overview as app-type API guide * docs: move knowledge api guide into api reference * docs: localize ui labels on knowledge overview * docs: refresh pipeline readme for restructure modes * docs: name app-type pages in the guides sidebar * feat: rename zh completion messages tag to match resource framing * docs: prototype endpoints-first layout on chatflow overview * docs: correct detail accuracy on chatflow overview * docs: move human input flow guide into api reference Move the shared HITL API integration walkthrough from its six per-product copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first task guide in the API docs. Guides gains an App Types subgroup (expanded by default) with the flow guide after it; six redirects cover the old paths; the Human Input node docs and the chatflow overview link to the new home. * fix: update spec links to the moved human input guide * fix: let spec lint accept mdx guide pages under api-reference * docs: align chatflow zh and ja overviews to endpoints-first layout * docs: polish chatflow zh and ja mode terms and hitl wording * docs: align workflow overviews to endpoints-first layout * docs: document form expiry path in human input flow guide * docs: align new agent overviews to endpoints-first layout * docs: align chatbot and agent overviews to endpoints-first layout * docs: align text generator overviews to endpoints-first layout * docs: align knowledge overviews to endpoints-first layout * docs: correct built-in metadata examples and agent heading * docs: flatten app-type pages directly under guides * docs: make guide pages self-contained and trim reference detail * docs: add get started guide and retire developing-with-apis * docs: update new agent api behavior for latest main New Agent behavior re-verified against dify origin/main (f3ba2846): agent_thought events now stream through the Service API carrying the model's reasoning steps and tool calls; a new agent_not_published 400 fires on Send Chat Message and Get App Parameters; the files claim is softened to contents-not-processed (raw references now reach the prompt; runtime confirmation pending). Streaming-only, message_end metadata, and the endpoint surface are unchanged. * docs: audit fixes for get started and human input flow guides * docs: fix em dash spacing and ja sentence length in get started * docs: move message_end note to the send endpoint line * docs: update writing guides and API skill for app-type naming - Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー. - formatting-guide: API reference links use the language prefix with English slugs. - dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline. * feat: add operation sidebar titles and simplify API redirects - merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar. - Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions. - memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group). * docs: correct app-type naming and translations across API specs - English mode enum labels Chatflow and Workflow apps. - zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent. - ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商. - Regenerate merged openapi_service.json with per-operation sidebar titles. * docs: add streaming, errors, and end-user identity API guides - Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect. - Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance. - End User Identity: what the user field scopes and why it stays consistent. - English source with zh and ja translations. * docs: reconcile API guides and apply app-type naming - Reader-test fixes and content audit on get-started and the app-type overview pages. - zh/ja reconciled to the English source. - Workflow/Chatflow and New Agent naming applied in prose. * feat: wire API nav and redirects for consolidated guides - Rename the guides group to API Overviews and register the new guide pages. - Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide. * fix: normalize zh model-provider term to 模型供应商 Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term. * docs: use Info callouts for guide forward-link notes Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout. * refactor: remove one-time analyze mode and verification compose - Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it. - Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials). - README: drop the analyze entry and correct the redirect description. * fix: correct Chatflow naming and reasoning wording in SSE overrides - Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename. - Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought". * docs: refine API guide wording and simplify the human-input example * docs: standardize Workflow and Chatflow app-type capitalization Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense. * fix: use 供应商 for model provider in the zh Knowledge spec * fix: rename the Knowledge API nav group to "Knowledge APIs" * fix: un-deprecate Update Document by Text in the Knowledge spec * translate: un-deprecate Update Document by Text in zh/ja specs Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated. * fix: repoint tools node links to the Classic Agent tab anchor The Tool Configuration heading is now nested inside the Classic Agent tab, so #tool-configuration no longer resolves. Point the three Tools-page links (en/zh/ja) at the tab-title anchor instead. * fix: correct broken bold and dropped text in ja/zh Agent node Pre-existing classic-content translation flaws surfaced in review: the ja ReAct bold cycle was mangled and missing Thought; the zh Memory sentence had dropped text. * docs: document New Agent deployment and 1.16.0-rc1 availability Retire the sandbox-container placeholder. The availability Notes, the node-page Note, and a new environments "New Agent (Beta)" section now point to the Dify 1.16.0-rc1 release, note it's on by default on Docker Compose, and call out DIFY_AGENT_SERVER_SECRET_KEY as the one value to set. Also aligns the ja data-security Warning with the zh single-tenant wording. en/zh/ja. * fix: relink publish API Integration card to the API reference (#847) * docs: standardize workflow casing in key-concepts and environments * translate: apply Workflow/Chatflow app-type naming to zh/ja docs * translate: sync API-guide copy-edits to zh/ja * fix: correct New Agent API guide against the current runtime Verified against feat/agent-v2: the reply streams as agent_message events (not message), list-message agent_thoughts carries the turn's reasoning steps (not empty), uploaded files are surfaced to the agent as downloadable references (not ignored), and /meta tool_icons is empty for New Agent apps. Adds the 1.16.0-rc1 availability pointer to the beta note. en/zh/ja. * docs: use Tip for New Agent availability callouts and tidy API guides Switch the New Agent availability callouts (overview, build, node) from Note/Info to Tip; the node callout gains the on-by-default sentence. Tighten the API guide beta Info and restructure the get-started API-key section into bullets. zh/ja synced to the en edits. * fix: point home page API Reference card at the new API guide * fix: rename Agent nav references to Agents to match the UI The main-nav item and its page are now labeled Agents (plural), rendered as a literal in routes.ts and roster/page.tsx. Update the bolded nav/page references across the New Agent guide, node page, and environment reference. en/zh/ja. * fix: add one-hop developing-with-apis redirects for all URL forms * fix: document both New Agent reply events in the streaming contract The New Agent guide said replies stream as agent_message; the Send Chat Message SSE reference and the streaming guide said message. Verified against dify feat/agent-v2 (agent_app/app_runner.py and its unit tests): both fire — the reply streams incrementally as agent_message deltas, then the turn closes with a single message event carrying the complete answer, then message_end, with agent_thought alongside throughout. Document the full sequence on all three surfaces and tell clients to treat the closing message as the final answer rather than appending it. en/zh/ja; merged specs regenerated via the API pipeline (build + wire, coverage clean). * fix: update New Agent env docs for the bundled development secret key (#849) (#850) * fix: update New Agent secret key docs for the bundled development default feat/agent-v2 now ships a valid development key for DIFY_AGENT_SERVER_SECRET_KEY in .env.example and the Compose fallback, so the backend starts out of the box; the old claim that an invalid placeholder blocks startup no longer holds. Reframe the entry around replacing the publicly known key before production, scope the startup failure to malformed values, and soften the guide callouts from a start prerequisite to production hardening. Replace the stale remaining-variables sentence with a table covering all 11 DIFY_AGENT_* plumbing vars, defaults verified against feat/agent-v2. en/zh/ja. * chore: cover secret-value false positives in the env-var verifier Add DIFY_AGENT_SERVER_SECRET_KEY to the ignored-vars false-positives bucket (docs describe the pre-filled development key instead of reproducing it) and refresh the stale ENABLE_AGENT_V2 entry, now superseded by NEXT_PUBLIC_ENABLE_AGENT_V2 and removed from .env.example on feat/agent-v2. Fix the verifier so the ignore list also applies to the default-mismatch check, which previously bypassed it. (cherry picked from commit63b392da48) * fix: hedge the Dify Cloud edge-proxy timeout claim in the streaming guide (#851) (#852) (cherry picked from commitc0664dacc5) * docs: apply the ready-to-use vs custom knowledge rebrand to Cloud docs (#853) (#856) * docs: apply the ready-to-use vs custom knowledge rebrand to Cloud docs Cloud 1.15.0 ships the same KB creation redesign as CE 1.15.0: the two create entry points are now Create a ready-to-use knowledge base and Build a custom knowledge base, reached through Knowledge > Create. Mirror the self-host rename (305e3f9f) onto the Cloud knowledge pages in all three languages: nav group labels, page titles, create paths, and name-tied prose, plus the bridge from the custom knowledge base page to the knowledge pipeline. Remove the outdated create-entry screenshot, now unreferenced. * fix: correct list numbering and blank lines in self-host knowledge pages Fix leftovers from the self-host knowledge creation rename: the zh integrate-knowledge page had two list items numbered 7, and the zh/ja create-knowledge-pipeline pages kept a double blank line where the screenshot Frame was removed. * fix: correct grammar and formatting flagged in PR #853 review Address Copilot review feedback, applying each fix to both the cloud and self-host copies to keep the trees in sync: replace "There're" with "There are", fix "one of the knowledge base created", rewrite the comma splice on the custom knowledge base overview, add the missing space before bold Chinese text, and strip trailing whitespace from the create-entry bullets. (cherry picked from commit476c02b9d7) * feat: finish API reference Phase 1: code audit and readability overhaul (#857) (#858) * feat: retire the merge pipeline and delete the legacy source specs openapi_service.json is now the spec of record per language, edited directly. The build/relink modes, resolutions.json, and overrides/ that consolidated the five per-app-type specs are recoverable from git history when Phase 2 rebuilds the spec from the upstream-generated source. * fix: make parity_check exit nonzero on failures * docs: document the direct-edit spec workflow in skills and translation guides * fix: correct the Service API reference against the code-verified audit Applies the confirmed findings of a full per-operation audit against dify 3c8e0e2113 / graphon 0.6.0: 9 factual errors (availability lines, phantom fields, wrong enum values, inert parameters, wrong error messages), ~33 omitted-error and example-accuracy gaps, the rate_limit_error recharacterization, provider-identifier format documentation, and New Agent availability on the endpoints its Chat Features support (verified end-to-end in code). * docs: document New Agent's full endpoint surface in the API guides * translate: propagate the Service API audit fixes to zh and ja * docs: rewrite Upload File as the readability pilot Worked example of the API readability standard: contract-first description, facts on the fields (category size limits with env-var link, blacklist rule), real error triggers (415 corrected to its actual cause), template user sentence, source links on sourceable values, and a hand-written multipart cURL sample. Applied to en/zh/ja. * docs: update spec-conventions for the live link scheme and code samples * docs: apply the readability standard across the Service API reference Rewrites all 82 operations to the agreed standard in en/zh/ja: contract-first descriptions, facts on the fields, trigger-led error bullets, template sentences (user, pagination, provider identifiers), source links on sourceable values, guide links instead of inline concept re-explanations, cURL samples where the playground autogen fails (multipart, SSE), a paragraph ceiling everywhere, and restructured streaming narratives (events-by-app-type map; details stay in the event tables). Also folds in two fact corrections surfaced during review: the legacy securitySchemes text and the stale Cloudflare-timeout claim in response_mode, now using the hedged edge-proxy wording. * docs: codify the readability standard and audit method in the API skill * fix: apply the audit-verified corrections deferred from the readability pass Small factual items evidenced in the audit findings that the readability pass could not touch under its fact-freeze: real wire messages (audio 413, type_mismatch number, dynamic run-by-id 404, werkzeug 500/403 strings, annotation 404 punctuation), schema precision (format: uuid, minimum: 1, six missing Get Available Models response fields), and behavioral completeness (document download/zip/delete 404 message variants, tag_ids silent-ignore note, request-scoped batch-metadata lock wording, reasoning_chunk message_id: null, form default key absent not null). Applied to en/zh/ja; parity 0. * fix: make spec checkers target openapi_service.json explicitly After the legacy specs were deleted, the openapi_*.json globs in parity_check and lint_specs would silently pass (match nothing, report 0 issues, exit 0) if the spec of record went missing, and would pick up unintended future openapi_*.json files. Both now name openapi_service.json per language and exit 1 when it is absent. * fix: address Copilot review on pipeline tooling and example titles Normalizes example summary separators to the dominant "Request Example - Mode" form (the convention doc had drifted, and 4 em-dash outliers existed per language); lint_specs no longer re-reads the spec it already loaded; all spec reads use explicit UTF-8; coverage_matrix and swagger_diff target openapi_service.json explicitly; README and docstring usage resolve DOCS from the git root so the commands work from any directory. * fix: use context managers for all pipeline file reads Copilot flagged unclosed handles in the three checkers; applied consistently across all five pipeline scripts (merge_specs and coverage_matrix had the same pattern unflagged). * fix: report missing spec ops as coverage failures instead of crashing * fix: print the full relative path in the parity missing-file message (cherry picked from commit6aa0ae4661) * feat: retire the auto-translation pipeline (#854) (#859) * feat: retire the auto-translation pipeline * fix: drop the Dify-API translator and align the navigation guideline * fix: remove unused pipeline-era config and the translation A/B test framework * fix: retire remaining pipeline references in glossary, env-vars skill, termbase tool (cherry picked from commit267089b359) * fix: converge drifted content between the cloud and self-host trees (#862) (#864) * fix: converge drifted content between the cloud and self-host trees Eight pairs had real drift (missed cross-tree syncs, mostly #820's cleanup never carried to cloud): Introduction-heading removals and webhook rewording, the 1.15.0 integrations rename, a missing #mcp anchor, utilize->use, apostrophe and ja terminology/spacing alignment. After this, every mapped pair differs only in deliberate audience-specific content. * fix: plan-gating callouts — add conjunctions, align zh with en, drop audience restatements (cherry picked from commit5575764827) * fix: repair MT-corrupted sentences in the webapp guides (zh/ja) (#866) (#868) Five passages from the revamp-era MT batch had dropped spans or truncated sentences (workflow-webapp and chatflow-webapp, both audience trees). Each is retranslated from the current en source; everything else in the publish/webapp family verified clean against en. (cherry picked from commit51be4e7cae) * fix: align reverse invocation App signatures with the plugin SDK (#873) (#875) The Reverse Invocation App page documented App invocation signatures that predate the removal of the top-level `files` argument, so every documented signature, and the Chat example, failed against current Python SDK releases (verified against v0.9.1). Corrected across the English, Chinese, and Japanese pages: drop the removed `files` argument from the Chat, Workflow, and Completion signatures; add the required `query` argument to Chat and to the Chat example; mark `conversation_id` optional; add the optional `user` argument; and show the `response_mode` defaults (`streaming` for Chat, `blocking` for Workflow and Completion). Signatures now match the SDK runtime definitions. Closes #872 Closes DC-27 (cherry picked from commit2975506628) * docs: rewrite Go to Anything for 1.16.0 (Feature Preview commands, entry points, scopes) Full rewrite against the GA code: sidebar search button + shortcut as entry points, recents, the @ scopes with @node's pipeline-editor support, and a complete slash-command table including the Feature Preview /create and /refine (with aliases in the Command column). UI-discoverable mechanics deliberately omitted. en/zh/ja. * docs: wire Snippets and Go to Anything into the self-host nav Both pages existed without navigation entries. Snippets lands before Workflow Collaboration in the Workflow & Chatflow group; Go to Anything before Shortcut Key. All three language sections. * docs: update the env reference for 1.16.0 Add NEXT_PUBLIC_ENABLE_FEATURE_PREVIEW (default true, gates /create and /refine), API_WEBSOCKET_WORKER_AMOUNT (completing the websocket group), and the four REDIS_KEEPALIVE* vars (verified against ext_redis.py). The New Agent section drops its rc1 deploy pointer for GA. en/zh/ja; verifier reports 0 mismatches. * docs: add the Snippets feature guide Reusable node groups: the three creation paths, editor restrictions, draft/publish model, published-version insertion, and the CE permissions table. Verified against GA code including the #38134 RBAC change (inert on CE). en/zh/ja. * docs: update difyctl docs for the 1.16.0 version gate and --insecure TLS skip The four compatibility verdicts with their rendered labels, exit-6 enforcement incl. HTTP 426, the 1-hour compat cache, login-time checking, and --insecure extending to self-signed/invalid TLS certs. Every claim traced to cli/src at the GA ref. en/zh/ja. * docs: port 1.16.0 feature updates to the affected guides MCP dynamic request headers with Custom Headers/Timeouts subheadings (tools.mdx, which also gains New Agent apps in its use-tools list), the web app input placeholder (64 chars, chat-style apps), a simplified Doc Extractor PDF line, and the docker compose container list gaining agent_backend and local_sandbox. en/zh/ja. * docs: retire the rc1 deploy pointers for GA The New Agent callouts, node page, and API guide told readers to deploy the 1.16.0-rc1 pre-release; at GA the version note is redundant on a versioned release branch. Beta framing stays. en/zh/ja. * docs: document the workflow-version 403 and speech_to_text_disabled API errors Sandbox-plan gating of pinned-version execution (dify #38662, #38892) lands as a 403 on Run Workflow by ID and Send Chat Message, with the paid-plan note on the Cloud version-control page (restore/DSL-export gating UI-verified). The audio-to-text 400 replaces the stale invalid_param bullet with speech_to_text_disabled (#38653). en/zh/ja. * docs: address review feedback after merging main Name the Normal role explicitly in the snippet permissions note (en, matching zh/ja), and split an over-long ja sentence introduced by the GA trim. * fix: use the spec's ASCII colon separator in the speech_to_text_disabled bullets The zh/ja error lists separate code from description with ' : ' throughout; the new bullet used a full-width colon. Copilot review on #848. * docs: fix a garden-path sentence and mirror the Doc Extractor simplification to Cloud The MCP custom-headers fallback sentence parsed 'runs' as a verb; rephrased as an explicit conditional. The Cloud doc-extractor copies keep parity with self-host by dropping the pypdfium2 mechanism mention (same implementation both products). Copilot review on #848. * docs: document SHELLCTL_ENABLE_PATH_ISOLATION for the agent sandbox * docs: note that discarding a build draft leaves sandbox changes intact * docs: move the discard caveat into a Note callout * fix: restore localized Human Input sample strings in zh/ja specs * chore: drop stale env ignore-list entries superseded by 1.16.0 docs * docs: state why .env cannot set the sandbox isolation toggle * docs: document seven new 1.16.0 env vars (agent stream, redaction, new-user defaults, workflow generation)
111 lines
5.3 KiB
Plaintext
111 lines
5.3 KiB
Plaintext
---
|
||
title: 認証
|
||
description: CLI から Dify ホストにサインインし、token の保存場所を確認し、セッションを管理する
|
||
---
|
||
|
||
> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/cli/authenticate) を参照してください。
|
||
|
||
サインインは OAuth 2.0 デバイスフローを使ってブラウザ経由で行います。`difyctl` がパスワードを受け取ることはありません。
|
||
|
||
## サインイン
|
||
|
||
<Steps>
|
||
<Step title="ログインコマンドの実行">
|
||
|
||
Dify ホストの URL を渡します。Dify Cloud の場合は `https://cloud.dify.ai` を、セルフホスト環境では [コンソール API URL](/ja/self-host/deploy/configuration/environments#console_api_url) を使用します。
|
||
|
||
```bash
|
||
difyctl auth login --host https://cloud.dify.ai
|
||
```
|
||
|
||
`difyctl` はワンタイムコードを表示し、既定のブラウザで検証 URL を開いて待機します。
|
||
|
||
```text
|
||
! Copy this one-time code: WDJP-XKLM
|
||
Open: https://cloud.dify.ai/device
|
||
```
|
||
<Tip>
|
||
自動で開かないようにするには、`--no-browser` を渡します。
|
||
</Tip>
|
||
|
||
ブラウザが開かない場合（SSH 経由やヘッドレスセッションでは通常の動作です）、任意のデバイスで URL を自分で開きます。
|
||
</Step>
|
||
|
||
<Step title="ブラウザでのサインイン承認">
|
||
開いたブラウザタブで、Dify の認証情報を使ってサインインし、ワンタイムコードを入力します。
|
||
|
||
コードは 15 分後に失効します。失効した場合は、`difyctl auth login` を再実行して新しいコードを取得します。
|
||
</Step>
|
||
|
||
<Step title="セッションの確認">
|
||
ターミナルに戻ります。
|
||
|
||
```text
|
||
✓ Logged in to cloud.dify.ai as <your-email> (<your-name>)
|
||
Workspace: <your-workspace>
|
||
```
|
||
|
||
2 行目に表示されているのがワークスペースです。
|
||
</Step>
|
||
</Steps>
|
||
|
||
## 再サインイン
|
||
|
||
コマンドが `auth_expired`（終了コード 4）で失敗した場合、サーバー側でセッションが失効または取り消されています。
|
||
|
||
`difyctl auth login` をもう一度実行します。先にサインアウトする必要はなく、新しいサインインによって保存済みの token が更新されます。
|
||
|
||
## サインイン中のアカウントの確認
|
||
|
||
```bash
|
||
difyctl auth whoami
|
||
```
|
||
|
||
```text
|
||
<your-email> (<your-name>)
|
||
```
|
||
|
||
スクリプトから ID 情報を読み取るには、`--json` を追加します。
|
||
|
||
```bash
|
||
difyctl auth whoami --json
|
||
```
|
||
|
||
同じフィールドが JSON オブジェクトとして返され、さらにアカウント ID も含まれます。
|
||
|
||
```json
|
||
{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","email":"<your-email>","name":"<your-name>"}
|
||
```
|
||
|
||
## サインアウト
|
||
|
||
```bash
|
||
difyctl auth logout
|
||
```
|
||
|
||
```text
|
||
✓ Logged out of cloud.dify.ai
|
||
```
|
||
|
||
これによりサーバー上のセッションが取り消され、token とセッションエントリがマシンから削除されます。サーバー側の取り消しに失敗した場合でも、ローカルの認証情報は必ず消去されます。
|
||
|
||
## Token の保存場所
|
||
|
||
サインインすると OAuth bearer token が保存されます。`dfoa_` プレフィックスで識別できます。この token はあなた自身を表すため、アカウントがワークスペースでできる操作は、そのまま CLI からも実行できます。
|
||
|
||
`difyctl` は、オペレーティングシステムの認証情報ストアが利用できる場合はそこに token を保存します。macOS では Keychain、Windows では Credential Manager、Linux では Secret Service です。利用できる認証情報ストアがない場合は、`difyctl` 設定ディレクトリ内のパーミッション `0600` の `tokens.yml` ファイルにフォールバックします。
|
||
|
||
`difyctl` はサインイン時に一度ストアを選択し、以降のセッションはそれを使用します。セッションのメタデータ（ホスト、アカウント、ワークスペース）は token とともに `hosts.yml` に保存されます。
|
||
|
||
設定ディレクトリは、macOS と Linux では `~/.config/difyctl`（Linux は `XDG_CONFIG_HOME` に従います）、Windows では `%APPDATA%\difyctl` です。[`DIFY_CONFIG_DIR`](/ja/cli/reference/environment-variables) を設定すると、この場所を上書きできます。
|
||
|
||
## トラブルシューティング
|
||
|
||
| 問題 | 対処方法 |
|
||
|:---|:---|
|
||
| ブラウザがまったく開かない | ターミナルから URL をコピーし、任意のデバイスで開く。 |
|
||
| ホストが拒否される | 受け付けるのは `https://` ホストのみ。スキームのないホストは `https://` として扱われる。プレーンな `http://` ホスト、または自己署名や無効な TLS 証明書を使う `https://` ホスト（ローカル開発のみ）の場合は、`--insecure` を追加する。 |
|
||
| 後続のコマンドが `auth_expired` で失敗する | セッションが失効または取り消された。[再サインイン](#再サインイン) する。 |
|
||
|
||
その他の問題については、[トラブルシューティング](/ja/cli/troubleshooting) ページ全体を参照してください。
|