docs: add dedicated Dify onboarding and usage guide

docs.json

@@ -70,6 +70,13 @@
                   "zh-Hans/concepts/async-tasks"
                 ]
               },
+              {
+                "group": "生态集成",
+                "icon": "puzzle-piece",
+                "pages": [
+                  "zh-Hans/integrations/dify"
+                ]
+              },
               {
                 "group": "AI 聊天",
                 "icon": "comments",
@@ -812,6 +819,13 @@
                   "en/concepts/async-tasks"
                 ]
               },
+              {
+                "group": "Integrations",
+                "icon": "puzzle-piece",
+                "pages": [
+                  "en/integrations/dify"
+                ]
+              },
               {
                 "group": "AI Chat",
                 "icon": "comments",

en/integrations/dify.mdx

@@ -0,0 +1,99 @@
+---
+title: "Use Ace Data Cloud in Dify"
+description: "Connect a chat model, run your first workflow, and check usage and errors."
+---
+
+Connect an Ace Data Cloud chat model to Dify, then use it in an **LLM** node, Chatflow, or Agent. You need a Dify workspace where you are an owner or administrator, an Ace Data Cloud API key, and access to the selected model.
+
+## Choose the installation path
+
+| Path | Availability | What you configure |
+| --- | --- | --- |
+| Dify's **OpenAI-API-compatible** provider | Available in the [official Marketplace](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible) | Base URL, model ID, and API key |
+| **Ace Data Cloud** model provider | Submitted for Marketplace review; publication has not been verified | Model ID and API key; the endpoint is fixed |
+
+<Note>
+The Ace Data Cloud provider is [awaiting review](https://github.com/langgenius/dify-plugins/pull/3219). It is not currently confirmed as a searchable, published Marketplace entry or a default-installed provider. Use the official compatibility provider for the available installation path. The retired collection of first-party Dify tool plugins is not required.
+</Note>
+
+## Prepare an API key
+
+1. Sign in to the [Ace Data Cloud console](https://platform.acedata.cloud/console/applications). Activate the chat service you want to use and check its current balance and [model pricing](https://platform.acedata.cloud/models).
+2. Create a key in **Credentials**. A service key is limited to its service; a global key can be used across services that your account can access. For an initial `gpt-4.1-mini` test, use a key authorized for that chat model.
+3. Store the key in Dify's provider credential settings. Keys are shared within the Dify workspace; use a separate development key when testing. Do not put a key in prompts, screenshots, workflow exports, or source control.
+
+Dify's model credits do not pay for requests made with your Ace Data Cloud key. Those requests use your Ace Data Cloud account balance.
+
+## Configure the available compatibility provider
+
+Open **Integrations → Model Provider**. In versions with the older navigation, open **Settings → Model Providers**. Install [OpenAI-API-compatible](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible), then choose **Add Model**.
+
+| Field | Initial value |
+| --- | --- |
+| Model name / ID | `gpt-4.1-mini` |
+| Model type | LLM |
+| API Base URL / endpoint | `https://api.acedata.cloud/v1` |
+| API key | Your Ace Data Cloud key |
+| Completion mode | Chat |
+| API type, if shown | Chat Completions API |
+| Context token limit | `4096` for the initial test |
+| Maximum output tokens | `1024` for the initial test |
+
+The Base URL ends in `/v1`. Dify appends `/chat/completions`; do not append it yourself or use `/openai/v1`. The initial token limits are conservative test settings, not claims about the model's maximum capacity.
+
+Leave optional reasoning, web search, structured output, image input, and tool-calling options disabled for the first text test. Save the model. The compatibility provider may send a small model request while validating the credentials, which can consume API usage.
+
+### Use the Ace Data Cloud provider after publication
+
+Once the named provider is available, install **Ace Data Cloud** from the official Marketplace. On its provider card, choose **Add Model**, enter the exact model ID and API key, and set context and output limits within the model's documented limits. You do not enter a Base URL: the plugin uses `https://api.acedata.cloud/v1/chat/completions`.
+
+The submitted provider validates the key and model ID with a read-only `/v1/models` request. Saving it does not generate a paid answer, but also does not prove that your balance, model entitlement, or every optional feature will work. Confirm those with a short real request.
+
+Both paths in this guide use **Chat Completions**. Do not select image-generation, embedding, or Messages-only models, such as `claude-opus-5-5` and `claude-sonnet-5-5`, for this configuration. A model appearing in `/v1/models` does not establish support for this protocol or for every optional feature.
+
+## Run your first workflow
+
+Create a blank **Workflow** and connect these nodes:
+
+```text
+Start → LLM → Output
+```
+
+1. In **Start**, add a required text input named `question`.
+2. In **LLM**, select the provider and `gpt-4.1-mini`. Set the user prompt to the **Start → question** variable using the variable picker. Set maximum output tokens to `64` and turn retries off for this first check.
+3. In **Output** (called **End** in older versions), add an output named `answer` and select **LLM → text** as its value. A successful workflow without an Output node may return no data to its caller.
+4. Run a preview with the question `Reply only DIFY_OK`. Confirm that the LLM node succeeds, the output contains `DIFY_OK`, and the run reports token usage.
+5. For a **Chatflow**, use an **Answer** node instead of Output and insert **LLM → text**. Publish only after preview and usage checks succeed.
+
+## Enable tools or images
+
+Enable **Tool calling** only for a model that supports it. Enable **Streaming tool calls** separately when supported. Use the configured model in an **Agent** node and add one appropriate tool. In the run trace, verify the tool name and arguments, the tool result, and the final answer. Tool selection and a successful final response are separate checks.
+
+Enable **Image input** only for a vision-capable model. Add a small image through Dify's supported file input and ask a simple question about it. Treat a successful text request as text validation only; it does not validate images, structured output, or other features.
+
+## Check usage and cost
+
+After the first request, open [Ace Data Cloud usage](https://platform.acedata.cloud/console/usages). Filter by the test key and time window. Match the model, status, and request details to the Dify run, then check the recorded deduction. Save a request or trace ID for support without sharing the API key.
+
+Charges are recorded in **Credits**. Their USD value is `Credits × (package price / package amount)` using your current package. The named provider reports token usage but does not publish a fixed USD estimate; Dify can display zero estimated cost even when the API request is billable. The Ace Data Cloud usage record is authoritative. Retries, loops, and Agent tool turns can each result in additional model requests.
+
+## Troubleshoot
+
+| Symptom | Check |
+| --- | --- |
+| Cannot find Ace Data Cloud in the Marketplace | Publication is still pending. Use the available compatibility provider or check the submission status above. |
+| Save fails, or HTTP 400/401 | Confirm the exact Base URL, key, key scope, model ID, and Chat Completions mode. |
+| HTTP 403 | Check model access, service activation, and content-policy restrictions. |
+| HTTP 429 | Reduce concurrent requests and wait before retrying. |
+| HTTP 5xx or a timeout | Check [service status](https://status.acedata.cloud), the request trace, and network access from the Dify server to `api.acedata.cloud:443`. Avoid repeated blind retries. |
+| Tools do not run | Verify model support, the provider's tool settings, and the Agent node's configured tools. |
+| Workflow succeeds but returns no answer | Map **LLM → text** into **Output → answer**, or the Chatflow's **Answer** node. |
+| Dify shows zero cost | Check the Ace Data Cloud deduction; Dify's estimate is not the billing ledger. |
+
+## Validation scope and maintenance
+
+The submitted provider passed unit tests, official package and serverless installation checks, and a real packaged-CLI call. `gpt-4.1-mini` was also verified for text, streaming tool calls, and tool-result continuation. This does not certify full Dify Community Edition/Cloud UI installation, Marketplace publication, every model, or every optional feature.
+
+Keep the provider updated through Dify's plugin manager. Recheck model IDs and prices when changing models, and validate a small workflow before applying an update to production. For support, use [the provider repository](https://github.com/AceDataCloud/dify-model-provider/issues) or `dev@acedata.cloud`.
+
+For protocol details, see [Chat Completions](/en/guides/openai/openai_chat_completions) and Dify's [model provider documentation](https://docs.dify.ai/en/use-dify/workspace/model-providers).

zh-Hans/integrations/dify.mdx

@@ -0,0 +1,99 @@
+---
+title: "在 Dify 中使用 Ace Data Cloud"
+description: "连接聊天模型、运行第一个工作流，并核对用量和排查错误。"
+---
+
+将 Ace Data Cloud 聊天模型接入 Dify，用于 **LLM** 节点、Chatflow 或 Agent。你需要 Dify 工作区的所有者或管理员权限、Ace Data Cloud API Key，以及所选模型的访问权限。
+
+## 选择安装路径
+
+| 路径 | 当前可用状态 | 需要配置 |
+| --- | --- | --- |
+| Dify 的 **OpenAI-API-compatible** 供应商 | 可从[官方 Marketplace](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible) 安装 | Base URL、模型 ID 和 API Key |
+| **Ace Data Cloud** 模型供应商 | 已提交 Marketplace 审核，尚未验证上架 | 模型 ID 和 API Key；接口地址固定 |
+
+<Note>
+Ace Data Cloud 专属供应商正在[等待审核](https://github.com/langgenius/dify-plugins/pull/3219)，目前尚未确认能在市场搜索、安装，也不是默认预装。需要立即接入时，使用已有的官方兼容供应商。此前退役的第一方 Dify 工具插件集合不是接入前提。
+</Note>
+
+## 准备 API Key
+
+1. 登录 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)，开通需要的聊天服务，检查余额和[模型当前价格](https://platform.acedata.cloud/models)。
+2. 在**凭据**中创建 Key。服务 Key 只适用于对应服务；全局 Key 可用于账户有权访问的多个服务。首次使用 `gpt-4.1-mini` 测试时，确认 Key 有权调用该聊天模型。
+3. 将 Key 存入 Dify 的模型供应商凭据设置。Key 会在工作区内共享，测试时建议使用单独的开发 Key。不要把 Key 写入提示词、截图、工作流导出文件或代码仓库。
+
+使用 Ace Data Cloud Key 的请求消耗 Ace Data Cloud 账户余额，Dify 的模型额度不会代付这些请求。
+
+## 配置当前可安装的兼容供应商
+
+打开 **Integrations → Model Provider（集成 → 模型供应商）**。旧版导航中位于**设置 → 模型供应商**。安装 [OpenAI-API-compatible](https://marketplace.dify.ai/plugin/langgenius/openai_api_compatible)，然后选择**添加模型**。
+
+| 字段 | 首次测试填写值 |
+| --- | --- |
+| 模型名称 / ID | `gpt-4.1-mini` |
+| 模型类型 | LLM |
+| API Base URL / 接口地址 | `https://api.acedata.cloud/v1` |
+| API Key | 你的 Ace Data Cloud Key |
+| 对话类型 | Chat（对话） |
+| API 类型（如有） | Chat Completions API |
+| 上下文 Token 限制 | `4096` |
+| 最大输出 Token 数 | `1024` |
+
+Base URL 以 `/v1` 结尾。Dify 会拼接 `/chat/completions`，不要自己添加，也不要使用 `/openai/v1`。上面的 Token 数是保守的测试设置，不代表模型最大容量。
+
+首次文本测试先关闭可选的思考、联网搜索、结构化输出、图片输入和工具调用，然后保存模型。兼容供应商验证凭据时可能发送一个小型模型请求，因此也可能产生 API 用量。
+
+### 专属供应商上架后的配置
+
+当官方 Marketplace 出现 **Ace Data Cloud** 后，安装该供应商，在供应商卡片中选择**添加模型**，填写准确的模型 ID 和 API Key，并在模型文档支持的范围内设置上下文和输出限制。无需填写 Base URL；插件使用固定的 `https://api.acedata.cloud/v1/chat/completions`。
+
+当前提交的插件通过只读 `/v1/models` 请求验证 Key 和模型 ID。保存配置不会生成付费回答，但也不证明余额、模型权限及所有可选能力都可用。请用一个简短的真实请求确认。
+
+本指南的两条路径都使用 **Chat Completions**。不要在这里填写生图、Embedding 或仅支持 Messages 的模型，例如 `claude-opus-5-5`、`claude-sonnet-5-5`。模型出现在 `/v1/models` 列表中，不代表它支持这一协议或全部可选功能。
+
+## 运行第一个工作流
+
+创建空白 **Workflow（工作流）**，连接以下节点：
+
+```text
+开始 → LLM → 输出
+```
+
+1. 在**开始**节点添加必填文本输入 `question`。
+2. 在 **LLM** 节点选择刚配置的供应商和 `gpt-4.1-mini`。使用变量选择器，将用户提示词设为**开始 → question**。首次检查将最大输出 Token 数设为 `64`，并关闭重试。
+3. 在**输出（Output）**节点添加名为 `answer` 的输出，值选择 **LLM → text**。旧版中该节点叫 **End（结束）**。工作流成功但没有输出节点时，调用方可能收不到数据。
+4. 在预览中输入 `Reply only DIFY_OK`。确认 LLM 节点成功，输出包含 `DIFY_OK`，运行记录中显示 Token 用量。
+5. 如果使用 **Chatflow**，通过**回答（Answer）**节点输出 **LLM → text**。预览和用量检查通过后再发布应用。
+
+## 启用工具或图片
+
+仅对支持工具调用的模型启用**工具调用**；支持流式工具调用时再单独开启对应选项。在 **Agent** 节点选择该模型，并添加一个适当的工具。查看运行轨迹中的工具名称和参数、工具返回结果及最终回答。模型选择了工具与最终回答成功，需要分别确认。
+
+仅对支持视觉的模型开启**图片输入**。通过 Dify 支持的文件输入添加一张小图片，并提出一个简单问题。文本调用成功只证明文本链路，不能作为图片、结构化输出或其他功能的验证结果。
+
+## 核对用量与费用
+
+首调后打开 [Ace Data Cloud 用量](https://platform.acedata.cloud/console/usages)，按测试 Key 和时间范围筛选。将模型、状态和请求详情与 Dify 运行记录对应，检查实际扣减。需要支持时保留请求或 trace ID，不要发送 API Key。
+
+用量以 **Credits** 计量。USD 换算为 `Credits ×（套餐价格 / 套餐额度）`，应使用你的当前套餐。专属供应商会返回 Token 用量，但不提供固定 USD 估价，因此 Dify 可能显示零预估费用；这不代表 API 免费。以 Ace Data Cloud 用量记录为准。重试、循环和 Agent 的多个工具轮次，都可能增加模型请求。
+
+## 排查问题
+
+| 现象 | 检查方法 |
+| --- | --- |
+| 在市场中搜不到 Ace Data Cloud | 专属供应商仍待发布。可先使用官方兼容供应商，或查看上面的审核状态。 |
+| 保存失败，或 HTTP 400/401 | 检查 Base URL、Key、Key 范围、模型 ID 和 Chat Completions 模式。 |
+| HTTP 403 | 检查模型权限、服务开通状态及内容策略限制。 |
+| HTTP 429 | 降低并发，等待后再试。 |
+| HTTP 5xx 或超时 | 查看[服务状态](https://status.acedata.cloud)、请求 trace，并确认 Dify 服务器能访问 `api.acedata.cloud:443`。避免连续盲目重试。 |
+| 工具没有执行 | 检查模型是否支持、供应商工具选项是否开启，以及 Agent 节点是否已配置工具。 |
+| 工作流成功但没有回答 | 将 **LLM → text** 映射到**输出 → answer**，或 Chatflow 的**回答**节点。 |
+| Dify 显示零费用 | 核对 Ace Data Cloud 实际扣减；Dify 估价不是账单。 |
+
+## 验证范围与维护
+
+提交的专属供应商已通过单元测试、官方包检查、serverless 安装检查和插件包 CLI 的真实调用。`gpt-4.1-mini` 还验证了文本、流式工具调用及工具结果续聊。这些结果不代表已完成 Dify Community Edition／Cloud 界面安装、官方上架，也不代表所有模型和可选能力均已通过验证。
+
+通过 Dify 插件管理器保持供应商版本更新。更换模型时重新检查 ID 和价格，将更新应用到生产前，先测试一个小型工作流。需要帮助时使用[供应商仓库](https://github.com/AceDataCloud/dify-model-provider/issues)或联系 `dev@acedata.cloud`。
+
+协议详情见 [Chat Completions](/zh-Hans/guides/openai/openai_chat_completions) 和 [Dify 模型供应商文档](https://docs.dify.ai/en/use-dify/workspace/model-providers)。