钉钉开放平台连接器
触发条件
- 用户给出钉钉开放平台官方接口文档，要求接入宜搭连接器、表单、自动化或 Canvas 页面。
- 需求包含
api.dingtalk.com、DingAuth或x-acs-dingtalk-access-token。
WHEN NOT
- 普通第三方或自建 HTTP API 使用
yida-connector。 - 已有连接器且只需从前后端代码提取动作时使用
yida-connector-safe-actions。 - 只在历史平台 JSX 页面绑定已有连接器数据源时使用
yida-data-source-connectors。
核心原则
- 只以用户指定的钉钉官方文档为接口契约；页面较多时按本次业务所需接口逐项读取，不复制整站目录。
- OpenYida 不支持钉钉事件订阅、Stream/WebSocket 或 HTTP 回调接收；遇到此类需求时直接说明不支持并停止，不生成连接器动作。
- App Key、App Secret、access token 永远不进入聊天、源码、JSON、命令参数或日志。
- AI 创建连接器和动作；鉴权账号由用户打开
accountManageUrl，在宜搭页面自行配置。 - 不需要
systemToken的 Action 可由 Canvas 通过window.__OPENYIDA_CONNECTOR_API__调用。需要systemToken的宜搭 OpenAPI 必须改用yida-integration，由 CLI 在服务端安全绑定；页面源码和 Action 默认值都不保存该凭据。
工作流
- 按 官方文档入口 定位目标接口页；用户给了精确官方 URL 时直接使用。
- 从目标接口页提取 method、host、path、path/query/header/body、响应、权限和幂等字段，按 API 契约 生成无密钥契约文件；每个 Action 保存自己的
sourceUrl。 - 按 入参依赖 检查每个必填参数的真实语义、固定值和“调用其他接口获取”链接。所有前置接口也必须生成宜搭自定义连接器 Action，通过连接器调用；不得改用
curl、临时脚本或页面直连。依赖值未解析时不得创建或调用主 Action。 - 若文档属于事件订阅、Stream/WebSocket 或 HTTP 回调接收，直接说明 OpenYida 不支持并停止。
- 创建
DingAuth连接器；不得传--app-key/--app-secret。 - 创建结果必须满足
readbackVerified=true；CONNECTOR_READBACK_MISMATCH是阻断错误，即使list-actions能看到动作也不得继续。记录数字管理 IDconnectorId和页面运行时内部名connectorName（必须以Http_开头）。 - 执行
list-actions回读稳定operationId。 - 执行一次
list-connections --json，记录beforeConnectionIds。 - 若没有可确定复用的 ACTIVE 账号，返回授权账号地址
accountManageUrl、连接器详情地址detailUrl和建议账号名后暂停；用户打开accountManageUrl，在宜搭中自行添加授权账号。 - 用户只需回复“已配置”，不要回复密钥或账号 ID。再次执行
list-connections --json：
- 恰好新增一个且名称符合预期：使用该账号；
- 没有新增，但存在唯一同名 ACTIVE 账号：复用；
- 多个新增、同名不唯一、名称不符或状态非 ACTIVE：停止，展示低敏候选信息，不猜测。 - 读接口用
connector test --account-id做真实探针；写接口先展示目标与副作用，用户确认后只调用一次。宜搭 OpenAPI 额外传--system-token-app <appType>，CLI 只在内存中注入body.systemToken。HTTP 200 只表示请求到达；CLI 还必须确认响应契约和钉钉errcode。 - 不需要
systemToken的页面调用加载yida-canvas-data-binding，页面 binding 写connectorName: "Http_*"，Body 传对象。需要systemToken时加载yida-integration，创建服务端自动化；嵌套 assignment 使用Body.userid等完整路径。发布回读只证明控制面配置，真实触发与业务读回成功后才能报告业务完成。
创建命令
openyida connector create "<名称>" "api.dingtalk.com" \
--auth "钉钉开放平台验证" \
--operations .cache/openyida/<任务>/connector/operations.json \
--json
openyida connector list-actions <connector-id> --json
openyida connector list-connections <connector-id> --json
connector create --json 返回 accountManageUrl 和 detailUrl。添加授权账号时优先把 accountManageUrl 交给用户；detailUrl 用于查看连接器定义。不得要求用户把配置后的 ID 发给 AI；CLI 通过前后两次列表差异自行发现。
完成标准
- 每个 Action 都有精确官方
sourceUrl，契约字段可追溯且无任何凭据值。 - 每个必填入参都已解析为用户输入、固定值、页面运行态值或前置 Action 输出；不能只按字段名猜语义。
- 连接器返回
readbackVerified=true，数字connectorId与Http_*connectorName均已记录；页面只使用connectorName。 - Action Header 均为
required=false，固定Content-Type有非空默认值，可选 Header 不保存空默认项。 - 连接器及动作已回读，账号归属和 ACTIVE 状态已确定。
- 只读测试返回业务可识别结果；不能仅凭 HTTP 200 宣称完成。
- 集成自动化发布返回
controlPlaneVerified=true；runtimeVerified=false时继续执行真实触发与业务读回，不宣称钉钉动作已经完成。 - Canvas 场景已通过固定平台代理调用，刷新后仍可读取真实数据。
- 若停在鉴权阶段，明确报告 connectorId、accountManageUrl、detailUrl、建议账号名和暂停原因，不宣称集成完成。
参考
- 官方文档入口与 API 契约
- 连接器与 Canvas 映射
- 钉钉开放平台文档
