Dify Knowledge MCP 接入指南

默认全局模式：OpenCode 默认使用全局配置（User Scope），Skill 与 MCP 配置写入用户全局配置目录（对齐 XDG_CONFIG_HOME），各项目自动生效，无需在每个项目重复安装，也不会在 HOME 根目录写入配置或绑定。
同一官方入口：无论首次接入、后续升级还是重启后收敛，均在终端运行同一条官方接入命令；已配置过的机器再次运行不会重复索要凭据。
显式项目选择：如需仅在单个项目启用，可显式指定 DIFY_PROJECT_ROOT 环境变量（或传入 --scope project --project-root）指定目标项目目录。
Bridge 后台代理：客户端统一连接本机后台代理服务（http://127.0.0.1:8789/mcp），免去客户端配置 Bearer Token 或私钥的风险。
完全退出并重启：安装器就绪状态（prepared / active）仅代表本地配置已就绪，不等于客户端已加载。更新完成后必须完全退出并重启 OpenCode / Agent 客户端；重启后可再次运行同一接入入口收敛状态，并在新会话中通过 dify_knowledge_health 验证。
历史事务安全保留：若检测到旧 HOME 未决状态（preserved_unresolved），系统会安全保留而不直接清理；保留不等于处理完成，也不表示旧 pending 已解决。
既有官方直连配置默认原样保留：若全局配置中存在 2026-08-27 发布片段的历史官方直连条目（type: "remote"、URL 精确为 https://dify-mcp.speedstarsunblocked.online/mcp、且仅有 headers.Authorization），安装器默认不改写、不读取其中凭据，原样保留该条目并继续正常完成更新，输出 legacy_official_direct_preserved（同时附 credentialPreserved: true）。除 enabled: true 外，还接受不改变端点与凭据边界的 enabled 缺省或 true（显式 false／非 boolean 拒绝）、oauth 缺省或严格 false（true 或对象拒绝）、timeout 缺省或正整数；其他键、headers 多键或不同 URL 仍拒绝。该条目不属于安装器所有权，卸载或回滚不会删除或修改它及其兄弟配置；本页面不要求你手动编辑配置或复制 token。
可选清除迁移（须显式要求）：如你希望清除该条目中存储的明文凭据并切换到本地环回形态，才需要显式授权。Windows/Linux 官方已验证的授权方式为环境变量 DIFY_MIGRATE_LEGACY_DIRECT=confirm-redact（或命令行 --migrate-legacy-direct；仅授权该精确分类，不涉及任何 token 或配置值）：PowerShell 可先设置 $env:DIFY_MIGRATE_LEGACY_DIRECT = "confirm-redact"，Shell 可在运行官方升级命令前加上 DIFY_MIGRATE_LEGACY_DIRECT=confirm-redact。终端交互确认（默认 No）为便捷路径，仅在具备附加控制台时可用，不宣称已在所有包装方式（如 irm | iex）下全面验证。迁移会将该条目改写为安全本地环回形态（http://127.0.0.1:8789/mcp、oauth: false），并永久丢弃旧 Authorization 头部且不可恢复，须由管理员轮换该旧凭据；本页面不提供复制该凭据或手动编辑配置的步骤。迁移成功后该条目仍按 external-satisfied 原样保留（无所有权、卸载不删除），输出 legacy_official_direct_migrated。默认保留与可选迁移都不得被理解为旧 HOME pending 已解决。
配置冲突安全拒绝与下一步处置：若配置不兼容，安装器会输出结构化 failed JSON（如 status: "failed", failureReason: "...", configurationState: "preserved_unresolved"）并安全拒绝修改，绝不索要配置正文或 Token，绝不盲目覆盖或删除用户已有配置：

• unmanaged_dify_configuration_requires_review：未受管条目仅在 type 为 remote、enabled 为 true、URL 精确为 http://127.0.0.1:8789/mcp、oauth 缺省或 false 且无附加键，并满足已认证发布模板时，可按 external-satisfied 原样保留，输出 external_official_preserved；安装器不获取其所有权，后续卸载时亦不会删除。包含 headers（即使为空）、未知键或其他 URL 仍拒绝。本页面未读取亦无法读取本机状态，亦不承诺所有旧配置均可自动迁移。下一步：若被拒绝，仅提供结构化失败原因供排查；严禁盲删配置、严禁在聊天中索要、回显或粘贴包含敏感凭据的配置正文与 Token。
• legacy_official_direct_preserved：检测到精确的历史官方直连条目，安装器默认原样保留并继续完成更新（不改写、不读取其中凭据）；卸载与回滚不会删除或修改它。可选：如你确认接受旧凭据不可恢复、并由管理员轮换，才通过官方已验证的环境变量 DIFY_MIGRATE_LEGACY_DIRECT=confirm-redact（或 --migrate-legacy-direct），或具备附加控制台时的交互确认，授权清除迁移，输出 legacy_official_direct_migrated；交互路径不宣称已在所有包装方式下验证；安装器不会回显或复制该 Authorization 值。
• legacy_official_direct_migration_consent_required：仅在显式请求迁移但交互确认被拒绝时出现，安装器保持原文件零变更。下一步：如确需清除，重新运行并明确回答 Yes 或设置上述环境变量；否则无需处理。
• legacy_global_dify_configuration_requires_review：检测到低优先级的历史配置文件（如旧 config.json）中包含 dify-knowledge，安装器不自动处理。下一步：在本地核对历史配置，备份后由用户手动确认迁移；安装器解析器读取文件仅用于检测冲突，绝不会回显或复制敏感值（如 Authorization headers），严禁自动迁移带有敏感 headers 的历史配置。
• inherited_dify_configuration_conflict_review_both_global_files：多个全局配置文件（如 opencode.json 与 opencode.jsonc）都定义了 dify-knowledge，且内容不一致。若两份都是相同的本地安全条目（loopback 地址、无认证头），安装器会正常继续并保持两份文件逐字不变；只有内容不一致时才会停止。下一步：在本地核对这两个全局文件，备份后统一保留一份有效配置；严禁声称旧 pending 事务已解决。