Dify 插件开发实验01开发环境与首个工具插件——从零开发第一个 Dify 插件需要什么Dify 实验系列 · 插件开发 01/12 | 实验编号DIFY-106-01基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。客服工单 SaaS 的客服每天要建几十张工单用户报障进来客服点「创建工单」系统要记下创建时间排障时前后端各说各的时间运维要拿一个基准时间去对齐日志看板上的定时任务还要按固定节奏触发调度。这些动作全都依赖同一个东西——一个可靠的「当前时间」。我们第一次接这类需求时第一反应也是「时间嘛写个脚本取一下不就行了」。真正动手才发现——「能取到时间」和「做成一个谁都能用的标准件」是两回事本地 Python 环境装不上 SDK、daemon 端口对不上、签名校验过不去每一步都在提醒你——插件开发的地基不是写代码而是先把「本地开发 → 远程安装」这条链路打通。这不是个例。任何系统里「记录、对齐、调度」都逃不开时间戳电商下单要打时间戳、日志平台要对齐各服务时钟、定时报表要按调度基准触发。时间这种「人人都会用、处处都要用」的能力恰恰值得做成一个标准件——而不是每个业务各写各的。2. 场景痛点这个流程的痛点在客服团队身上体现得最直接手工填时间不可靠建单时间靠客服手工填填错一个字段工单时效统计就失真后续 SLA 考核跟着全错——时间错了整个业务判断都建立在错误地基上。时区口径混乱服务器跑 UTC、客服在国内、客户在国外同一张工单三个时间口径排障时「这条记录到底几点创建的」要来回换算——换算一次就多一次出错的机会。格式五花八门有人写「2026-08-05 15:59:50」有人写「08/05 下午 4 点」时间字段进了系统没法直接比较、排序——格式不统一数据就废了一半。调度基准各写各的每个定时任务各自实现时间获取逻辑想统一时区策略就要改遍所有任务——越分散越没人敢动。本质上时间戳是系统里最基础的信息却因为「太简单」而被每个人各自实现一遍——最该统一成标准件的能力反而最混乱。3. 方案为什么是插件选插件这条路我们实际对比过Dify 内置节点里没有「获取当前时间」这类基础工具但插件机制正好补这个位。平台原生扩展点插件是 Dify 官方的一等公民装进控制台后所有工作流/Agent 都能用一次开发、处处受益本实验是最好的练手对象get_current_time无外部依赖、参数少、结果确定正好把「脚手架 → 代码 → 本地调试 → 打包 → 安装 → 使用」全生命周期完整走一遍为后续实验打地基02/03 实验直接复用它——环境不打通后续所有「本地开发 → 远程安装」的假设都不成立。这篇文章我们就用它搭第一个工具插件打通插件开发的环境地基与全生命周期。4. 整体架构Dify 服务器Docker Compose本地开发机remote debug上传安装验证应用workflowdify106_01_验证应用开始无输入工具节点 get_current_time文本输出拼接时间戳文案结束plugin 项目源码dify-plugin SDKdify plugin 命令产物 .difypkgapiFastAPIplugin_daemon插件运行时端口 5003web控制台插件管理页控制台「插件」PostgreSQL / Redis链路很清晰本地开发 → 远程调试 → 打包上传 → 工作流消费。其中环境三件套Python 版本/daemon 对接/签名强制是整个链路的地基——地基不打通后面每一步都走不动。5. 模块设计5.1 环境三件套本实验核心本地 Python 环境Python 3.14 装不了 SDKgevent/tiktoken 无 wheel实测用 uv 管理 cpython-3.11.15 建 venvSDK 用dify-plugin 0.7.4——注意 PyPI 包名是dify-plugin不是 dify-plugin-sdk后者 404。daemon 对接PLUGIN_DAEMON_KEY从 daemon 容器 env 拿docker inspect值为 SERVER_KEYdaemon 只监听50035002 拒绝docker 已映射本地 127.0.0.1:5003 可达。签名强制FORCE_VERIFYING_SIGNATUREtrue时需第三方签名方案——generate/sign 生成密钥对 公钥白名单部署 compose override 加环境变量 重启 daemon之后签名包才能安装。5.2 插件声明manifest.yamlname:dify106_01_time_toolversion:0.1.0type:pluginicon:icon.svgplugins:tools:-provider/time_tool.yamlmeta:arch:-amd64-arm64runner:entrypoint:mainlanguage:pythonversion:3.125.3 工具声明tools/get_current_time.yamlidentity:name:get_current_timedescription:human:获取当前时间可选时区UTC、UTC8、UTC-5、UTC9llm:Get current time. Parameter timezone is optional,must be one of UTC,UTC8,UTC-5,UTC9. Returns JSON with time,timezone,utc_offset.parameters:-name:timezonetype:stringrequired:falseform:llmllm_description:Optional timezone. Must be one of: UTC, UTC8, UTC-5, UTC9. Default is UTC.extra:python:source:tools/get_current_time.py注意参数必填form: llmdescriptionhuman/llm是顶层字段provider 的才在 identity 内。5.4 工具实现tools/get_current_time.py 核心classGetCurrentTimeTool(Tool):def_invoke(self,tool_parameters:dict[str,Any]):tz_keytool_parameters.get(timezone)orUTCif_SUPPORTED_TZ.get(tz_key)isNone:yieldself.create_text_message(json.dumps({error:unsupported_timezone,...}))returnnowdatetime.now(timezone(timedelta(seconds_SUPPORTED_TZ[tz_key])))result{time:now.strftime(fmt),timezone:tz_key,utc_offset:f{_SUPPORTED_TZ[tz_key]//3600:d}h}yieldself.create_text_message(json.dumps(result,ensure_asciiFalse))6. 运行验证输入预期结果workflow 运行timezoneUTC8输出含精确到秒的当前时间戳通过实测{time: 2026-08-05 15:59:50, timezone: UTC8, utc_offset: 8h}agent 应用提问「现在几点」触发 get_current_time 并回答正确通过实测两次调用均触发工具卸载 → 重装列表消失 → 重装后冒烟恢复通过uninstall 200同 sha 复用7. 实战坑坑现象修复daemon 端口5002 拒绝连接daemon 只监听 5003docker 映射后本地 127.0.0.1:5003 可达实测Python 3.14 装 SDKgevent/tiktoken 无 wheel 装不上3.11.15 venvuv 管理 dify-plugin 0.7.4实测PyPI 包名dify-plugin-sdk 404包名是 dify-plugin示例仓库 dify-plugin-sdks / dify-official-plugins实测Windows CLI 下载被墙GitHub releases HTTP 000用容器内 /app/commandlinepackage/signature 全有实测icon 引用打包报 tool icon not foundyaml 写 icon.svg不带 _assets/ 前缀实测签名强制FORCE_VERIFYING_SIGNATUREtrue 下签名包装不上第三方签名方案generate/sign 公钥白名单 compose override 重启 daemon实测tool yaml 字段参数缺 form: llm 校验不过参数必填 form: llmdescription 是顶层字段实测UI 节点空白手写 DSL 缺 UI 渲染字段打开空白照 UI 导出格式补 height/width/selected/desc/dragging实测8. 实验文档及源码获取实验文档完整操作步骤DIFY-106-01插件开发环境与首个工具插件.md源码可直接导入dify106_01_验证应用.ymlworkflow、dify106_01_验证对话.ymlagent插件包签名安装包控制台上传用dify106_01_time_tool.signed.difypkg全部源码目录dify-106/dsl文章聚焦核心配置与采坑点实验的完整分步操作节点搭建/参数表/调试指引见实验文档原文。下一篇Dify 插件开发实验02参数与凭证体系——插件参数和凭证如何声明、配置与管理 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。