pi-dingtalk0.3.0

pi-dingtalk

在钉钉里使用你的 Pi 会话：发消息、传图片和文件、接收回复，或通过表单补充信息。插件复用已绑定的 Pi 会话，不需要另建 Gateway 或单独的模型服务。

支持仅私聊、仅群聊，或同时启用两种聊天方式。

能做什么

你想做的事	支持情况
在群里与 Pi 对话	在已配置的群中 @ 机器人，由指定操作者发起请求
私聊机器人	指定操作者直接发消息，无需 @；仅用私聊时不需要群标识
让 Pi 看图、回传图片	支持 PNG/JPEG；理解图片需要视觉模型
收发文件、处理文本	支持私聊接收文件、文本读取与生成、向原聊天发送附件；不承诺解析 PDF/Office 正文
阅读逐步生成的回答	可开启答案卡及正文增量更新，不发送思考过程
填写选项或补充信息	支持最多8字段的交互表单，提交后继续原任务

不支持群内接收用户上传的文件、语音或视频。表单不是通用审批系统，提交不会自动授权与原任务无关的操作。

开始前需要准备什么

Pi 环境

• 一套已安装、已配置可用模型的 Pi。
• Node.js 环境满足所用 Pi SDK 的要求；插件使用宿主提供的 SDK，不需要另装一份。
• 已在 Linux、Node.js 22/24 下完成自动测试，并用 Pi SDK1.5.0 验证包加载。Windows/macOS 的兼容性尚未完成验证。

同一主机上，使用同一机器人账号的进程必须共享状态目录，避免重复连接。不支持跨主机或不同 PID 命名空间共享账号锁。

钉钉应用

由应用管理员启用机器人的 Stream 接收模式，并开通所用的机器人消息、媒体和卡片 API 权限。使用群聊时，还需将机器人加入目标群。

准备以下信息：

配置项	填写内容
clientId	钉钉应用标识
clientSecret	该应用的密钥，只写入凭据文件
robotCode	机器人编码
conversationId	启用群聊时填写目标群的 openConversationId，不是群名称；仅私聊时无需填写
requesterId	允许操作机器人的用户标识，需与消息回调的 senderStaffId 对应，不是昵称

应用标识、密钥和机器人编码应对应同一应用。插件只接受指定操作者的请求，不向群内所有人开放。

首次连接：先跑通文字聊天

1. 安装插件

在系统终端执行：

pi install npm:pi-dingtalk

Pi 会安装插件及其运行依赖。使用个人级安装即可，不必在每个项目重复安装；不要同时通过本地路径、Git 和 npm 加载多份插件。

2. 填写配置和凭据

默认配置位置是 <agentDir>/dingtalk/config.json。常规个人安装的 agentDir 为 ~/.pi/agent；使用自定义目录时以实际路径为准。也可通过 PI_DINGTALK_CONFIG 指定配置文件。

下面以群聊文字回复为例。创建 config.json，替换示例标识：

{
  "schemaVersion": 1,
  "clientId": "YOUR_CLIENT_ID",
  "conversationId": "YOUR_OPEN_CONVERSATION_ID",
  "requesterId": "YOUR_REQUESTER_ID",
  "credentialsFile": "credentials.json",
  "groupEnabled": true,
  "dmEnabled": false,
  "replyMode": "text"
}

根据聊天方式调整配置：

聊天方式	配置要点
仅群聊	groupEnabled: true、dmEnabled: false，填写 conversationId
仅私聊	groupEnabled: false、dmEnabled: true，省略 conversationId
群聊与私聊	两个开关均为 true，填写 conversationId

三种方式都需要指定操作者。省略群标识是删除 conversationId 字段，不是填写空字符串或 null。不填写 groupEnabled 时，插件按是否提供群标识判断是否启用群聊。

然后在同一目录创建 credentials.json：

{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "robotCode": "YOUR_ROBOT_CODE"
}

两个文件的 clientId 必须相同。不要把凭据放入聊天、命令参数或仓库。

配置目录应由运行 Pi 的用户持有。POSIX 系统上目录使用 0700，凭据和业务状态文件使用 0600；普通配置可使用同属主、组及其他用户不可写的 0644，插件保存时会改为 0600。可信配置根目录可以使用符号链接。Windows 不使用 POSIX UID 判断权限，但仍需妥善限制目录访问。

3. 在 Pi 中绑定并启动

安装和配置完成后，新开或重新加载 Pi 会话。选择一条已持久保存、工具权限符合预期的会话用于钉钉；钉钉请求默认可调用该会话已启用的宿主工具。

在该会话中执行：

/dingtalk bind
/dingtalk autostart on
/dingtalk start
/dingtalk status

状态应显示“已连接”和“当前会话绑定：是”。bind 关联当前会话，不创建另一条会话；autostart on 设置以后加载此会话时自动连接，start 才立即连接。

4. 从钉钉验证回复

用配置中的操作者账号发一条简单文字：群聊需 @ 机器人，私聊直接发送。确认钉钉客户端实际收到 Pi 的回复。

连接成功只说明接收通道已建立，不代表模型一定可用，也不代表回复已经显示在手机上。未收到回复时，查看 /dingtalk status 的任务、投递和最近失败原因。

按需开启功能

先跑通文字。需要增加功能时，先在原绑定会话停止接入并等待任务结束，再修改 config.json 中对应的字段、重新加载并启动；插件不会替你重启服务。

**/dingtalk stop 会同时关闭自动连接。**维护后如需恢复自动连接，再执行 /dingtalk autostart on。如果改变了绑定的群目标（包括从群聊切换到仅私聊），先在原配置下执行 /dingtalk unbind，再改配置、重新加载并绑定；不要直接编辑状态文件。

想开启的功能	配置	使用条件
私聊	dmEnabled: true	只允许指定操作者；可单独使用，也可与群聊同时启用
接收图片	imagesEnabled: true	支持 PNG/JPEG；看图需视觉模型
回传图片	再加 imageSendEnabled: true	发送到本轮原聊天，不支持任意收件人
私聊接收文件	filesEnabled: true	群内上传的文件不在接收范围
发送文件	再加 fileSendEnabled: true	依赖 filesEnabled
读取和生成文本文件	再加 artifactToolsEnabled: true	依赖文件发送；不生成原生 PDF/Office 二进制文件
答案卡	replyMode: "card"	需可用的卡片模板和权限
回答增量显示	再加 streamingEnabled: true	必须同时使用卡片回复模式
交互表单	formsEnabled: true	需可用的表单模板和回调权限
精确引用	textQuotesEnabled: true	只引用同渠道可核对的文本，不猜历史内容

答案卡与表单模板

插件内置默认模板，也允许分别指定答案卡和表单的模板 ID。配置字段分别是 answerCardTemplateId 和 formTemplateId；未指定时使用默认值，但模板是否可用仍取决于所在企业的权限。默认 ID、字段结构、回调要求和配置示例见模板使用指南。

• 使用默认模板：先确认应用具有所需的卡片和回调权限，再开启对应功能，用一条新请求验证显示与提交。
• 使用自己的模板：在钉钉卡片平台准备与插件数据结构一致的模板，取得模板 ID 后填写到相应的模板配置中。仅更换 ID 不能让任意模板兼容插件。
• 模板不可用：检查模板 ID、企业可用范围、应用权限及表单回调配置。排查期间使用 replyMode: "text"，暂停卡片和表单，不影响基础文字聊天。

图片与文件使用提示

直接在钉钉中说明要 Pi 做什么，例如分析本轮图片、原样回传图片或读取本轮文本附件，不需要记住原生工具参数。

类型	默认限制
图片	每轮接收、发送各最多10张；单张10MiB，整批24MiB
文件	单个20MiB；每轮最多16个、合计64MiB
文本读取或生成	单次最多1MiB

超限会明确提示，不会静默只处理其中一部分。

生图由宿主已安装的工具提供，不绑定特定服务或固定产物目录。目前可衔接 openai_generate_image 的结构化图片结果；插件只接纳本轮实际调用成功、路径及图片信息可以核对的产物，不会根据聊天中的任意路径读取并发送文件。其他生图工具需提供对应结果适配，不能仅凭工具名称或一段路径文字发送文件。

调整回执与等待时间

在 Pi 中执行 /dingtalk config 打开设置菜单；没有交互界面时使用以下命令：

/dingtalk config show
/dingtalk config receipts on
/dingtalk config image-wait 8000
/dingtalk config reply text

• 收件回执可用 receipts on/off 开关；关闭后仍会发送任务结果、错误通知和文件保存提示。
• image-wait 是私聊连续图片的等待窗口，范围0～60000毫秒，默认8000。
• 卡片模式使用 reply card，再按需设置 streaming on/off；文字模式不支持流式卡片。
• 四种回执文案分别使用 receipt-text、queued-text、image-text、group-image-text 设置，前面加 /dingtalk config 。文案最多300字符，可用 {count}、{waitSeconds}，填 default 恢复默认。
• 文字短消息合批通过 messageBatchWaitMs 配置，范围0～2000毫秒。

回执设置和文案可立即生效；图片等待时间、回复方式与流式设置在下次连接生效。普通偏好保存不会自动重启接入，也不需要逐次备份配置。

一键切换绑定会话

打开你希望接管钉钉的目标 Pi 会话（需已持久保存、已加载插件），执行一次：

/dingtalk switch

插件会协调原接收器退出、转移绑定并立即连接新会话，不需要回原会话手动解绑。尚未绑定时也可用此命令完成绑定和连接；已绑定当前会话时不会重复迁移或创建第二条连接。

• 保留机器人、群目标、操作者、自动连接开关和工具模式。新会话使用自己的模型、上下文及宿主工具；零工具模式不会被切换操作解除。
• 原聊天历史、私聊隔离记录和待关联附件仍留在原会话，不重放旧消息；已有分叉会话继续遵循原隐私继承规则。旧会话仍可在 Pi 中正常使用。
• 原会话或目标会话有任务、排队消息、图片合并等待或发送操作时，结束后再重试；不会强行中断任务、杀进程或删除仍被占用的锁文件。
• 支持同进程和同主机不同进程，需共享状态目录及 PID 命名空间；运行中的原接收器也必须是支持 switch 的版本。0.1.0 原接收器需先升级并重新加载。
• 交接最多等待30秒。超时先查看两端状态，不代表可以强制抢锁。若绑定已转移但新连接失败，错误提示会说明；排除问题后在目标会话执行 /dingtalk start，不会自动切回旧会话。

使用独立更新确认卡集成时，须同步更新其回调与通知发送脚本：新通知跟随新绑定，旧待确认卡不转移授权，切回原会话也不会让旧卡重新生效。标准npm核心不自动修改这些运维脚本。

日常使用

以下命令在 Pi 的绑定会话中执行，不是钉钉远程管理命令。

命令	用途
/dingtalk status	查看连接、任务、投递及最近错误
/dingtalk status json	获取机器可读诊断，不输出凭据
/dingtalk config、config show	修改或查看常用设置
/dingtalk switch	一键把钉钉绑定到当前会话并连接，保留原自动连接和工具模式
/dingtalk start	立即连接，不改变自动连接设置
/dingtalk stop	停止桥接并关闭自动连接，不默认取消模型任务
/dingtalk autostart on/off	控制以后加载原会话时是否自动连接
/dingtalk tools off	钉钉请求使用零工具模式，不清空宿主工具，也不影响其他 Web 任务
/dingtalk tools restore	停止且空闲时恢复配置中的钉钉工具及宿主工具使用
/dingtalk unbind	停止后解除绑定，不删除历史或重放消息

新绑定默认允许使用宿主已启用的工具，插件只管理自己的工具。旧绑定明确选择过的零工具模式会保留。插件与 Pi 共享操作系统权限，不是独立沙箱。

关闭网页或重启后会怎样？

关闭网页不等于关闭 Pi 会话。已运行的连接会继续通过会话保活接收消息，并在网络断开时重连。

重启 Pi、pi-web 或容器后，需要先打开原绑定会话；若开启了自动连接，插件会在会话加载后连接。无人加载会话期间钉钉不在线属于预期，不需要额外启动器。

停止时会等待网络、发送任务和必要的私聊结算完成。显示“正在停止”时可以继续查询状态，不要为加速停止而另开一个接收器。

能否压缩、分叉或切换历史？

可以压缩；分叉和切换历史需等当前钉钉任务结束。

私聊与公开上下文保持隔离，Web 主动输入不会广播到群。来源明确的纯私聊摘要仅供私聊使用，公开摘要仅供公开渠道使用；混有私聊与公开内容、或来源无法确认的摘要不会直接提供给钉钉渠道，因此压缩后可能缺少部分旧上下文。

分叉会继承隐私标记，但不复制待处理附件，也不自动迁移机器人绑定。外部创建的 fork 会从 Pi 父会话链补取隐私标记；父会话已丢失且没有继承标记时会报错，不能靠删除隐私索引解除限制。

常见问题

现象或错误	该怎么做
机器人未回复	确认使用指定操作者账号；群聊需在正确群中 @，私聊需开启 dmEnabled。再检查 Pi 中的绑定、连接、模型及投递状态
重启后机器人不在线	打开原绑定会话，检查自动连接设置，必要时执行 /dingtalk start
图片、文件或表单不可用	检查功能开关及其依赖、应用权限和模型能力；模板不可用时先用文字聊天
account_locked	另一实例持有账号，先在那里停止，不要直接抢锁
lock_update_busy	可能正在更新锁，或异常退出留下 .mutex；先核对进程状态再处理
state_write_failed	原文件未被替换；处理磁盘或权限问题后可重试
state_commit_unknown	关键状态的保存结果需核对，不要据此自动重复外发

**投递“未知”不等于“确定未发送”。**同一次请求不会自动更换工具 ID 重试。你可以明确发起新的发送请求，但可能重复前次实际已送达的内容；先检查钉钉客户端再决定是否重发。

历史发送记录不会自动重放。不要删除状态目录来“恢复”消息，其中还保存着会话绑定、去重和私聊隔离信息。

更新与卸载

更新前，在原绑定会话执行 /dingtalk stop，等待正在处理的任务结束。然后在系统终端执行：

pi update npm:pi-dingtalk

更新后重新启动 Pi，打开原绑定会话，执行 /dingtalk start 并从钉钉验证回复。如需以后自动连接，再执行 /dingtalk autostart on。

不再使用时，先停止桥接，再移除安装声明：

pi remove npm:pi-dingtalk

配置和业务数据与安装包分开保存，不要把删除状态目录作为常规升级或排障步骤。更换安装来源时，不要同时保留两份插件；降级前检查状态格式是否兼容，并完整保留隐私索引及其 .log。

原生图片与文件工具参数参考

用户通常直接用自然语言提出需求；以下供工具集成与排障使用。

• 原生图片发送使用 source:{kind,value}：received 选择本轮接收图，all 表示本轮全部图片；approved_file 选择批准目录图；generated 选择本轮已关联的生成图片。
• dingtalk_read_file 的 received 编号文件附件，received_image 编号图片，generated_image 读取本轮已关联生成图。
• 不得传入任意本地文件路径绕过来源关联，也不能跨私聊与群聊取附件。

许可证

采用 MIT 许可证。第三方依赖遵循各自许可证，见 第三方许可声明。