yida-dingtalk-openapi git:20260903.9332cafA

Immutable. This exact content is served forever at /api/v1/blob/1912d6bc87a54785.

---
name: yida-dingtalk-openapi
description: 将钉钉开放平台官方服务端 API 转成宜搭 HTTP 连接器动作，并供表单、集成自动化或 YidaCodeCanvas 自定义页面安全调用。负责官方文档核对、DingAuth 账号配置暂停与确定性回读。触发词：钉钉开放平台接口、api.dingtalk.com、x-acs-dingtalk-access-token。
---

# 钉钉开放平台连接器

## 触发条件

- 用户给出钉钉开放平台官方接口文档，要求接入宜搭连接器、表单、自动化或 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 创建连接器和动作；鉴权账号由用户在宜搭页面配置，或由用户本人在本机 TTY 运行 `--interactive` 命令。
- Canvas 页面只保存 `connectorId`、`operationId`、`connectionId`，通过 `window.__OPENYIDA_CONNECTOR_API__` 调用，不直连 `api.dingtalk.com`。

## 工作流

1. 按 [官方文档入口](references/api-contract.md#官方文档入口) 定位目标接口页；用户给了精确官方 URL 时直接使用。
2. 从目标接口页提取 method、host、path、path/query/header/body、响应、权限和幂等字段，按 [API 契约](references/api-contract.md#契约格式) 生成无密钥契约文件；每个 Action 保存自己的 `sourceUrl`。
3. 若文档属于事件订阅、Stream/WebSocket 或 HTTP 回调接收，直接说明 OpenYida 不支持并停止。
4. 创建 `DingAuth` 连接器；不得传 `--app-key` / `--app-secret`。
5. 执行 `list-actions` 回读稳定 `operationId`。
6. 执行一次 `list-connections --json`，记录 `beforeConnectionIds`。
7. 若没有可确定复用的 ACTIVE 账号，返回连接器详情 URL、建议账号名和以下两种安全操作后暂停：
   - 用户打开详情 URL，在宜搭中自行配置账号；或
   - 用户本人在本机终端运行：`openyida connector create-connection <connector-id> "<账号名>" --interactive`
8. 用户只需回复“已配置”，不要回复密钥或账号 ID。再次执行 `list-connections --json`：
   - 恰好新增一个且名称符合预期：使用该账号；
   - 没有新增，但存在唯一同名 ACTIVE 账号：复用；
   - 多个新增、同名不唯一、名称不符或状态非 ACTIVE：停止，展示低敏候选信息，不猜测。
9. 用 `connector test --account-id` 做真实只读探针；写类接口需单独确认业务副作用。
10. 页面调用时加载 `yida-canvas-data-binding`，按 [连接器映射](references/connector-mapping.md) 写入绑定并发布验证。

## 创建命令

```bash
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` 返回的 `detailUrl` 是用户自行配置鉴权的入口。不得要求用户把配置后的 ID 发给 AI；CLI 通过前后两次列表差异自行发现。

## 完成标准

- 每个 Action 都有精确官方 `sourceUrl`，契约字段可追溯且无任何凭据值。
- 连接器及动作已回读，账号归属和 ACTIVE 状态已确定。
- 只读测试返回业务可识别结果；不能仅凭 HTTP 200 宣称完成。
- Canvas 场景已通过固定平台代理调用，刷新后仍可读取真实数据。
- 若停在鉴权阶段，明确报告 connectorId、detailUrl、建议账号名和暂停原因，不宣称集成完成。

## 参考

- [官方文档入口与 API 契约](references/api-contract.md)
- [连接器与 Canvas 映射](references/connector-mapping.md)
- [钉钉开放平台文档](https://open.dingtalk.com/document/)