---
name: yida-integration
description: 创建和管理宜搭集成自动化，负责触发、保存发布、查询启停及日志；通知、数据、分支、连接器参数按需加载通用节点技能。
---

# 集成自动化

本技能负责逻辑流的触发、完整 spec、保存发布和结果核对。节点参数统一由 `use_skill("yida-flow-node-config", "集成自动化；所需节点类别或配置项")` 提供，按需读取。

## 使用范围与限制

表单或流程事件后的自动通知、跨表新增／更新、创建待办、调用连接器等动作，默认使用本技能。不要把提交后的自动动作塞进表单字段 JS 或自定义页面按钮；只有用户明确要求一次性人工触发工具页时才采用该方式。

审批、办理等人工流程配置使用 `yida-process-rule`。先解析目标应用、表单和已有逻辑流；目标或资源归属不明确时保持零写入。当前入口未封装的触发或节点必须报告具体缺口，不能改变用户要求的触发语义。

## 严格禁止 (NEVER DO)

- 不要在未加载本技能内容的情况下编写逻辑流定义，节点格式复杂且易出错。
- 不要编造 `formUuid` 或 `fieldId`，必须从已有记录或 `yida-get-schema` 获取。
- 不要用此技能配置审批流程，应使用 `yida-process-rule`。
- 不得把 `integration update` 的 fail-closed 结果降级为 `integration create --process-code --replace`。

## 严格要求 (MUST DO)

- **创建/发布前必须确认**：执行集成自动化创建或发布操作前，必须向用户展示逻辑流配置摘要（触发条件、节点列表、通知对象），获得用户明确同意后再执行。
- 创建前先确认触发表单的 `formUuid` 和相关字段 ID。
- 创建成功后记录逻辑流 ID 到 `<projectRoot>/.cache/<项目名>-schema.json`。
- `--spec` JSON 文件必须先用结构化文件写入工具创建到 `<projectRoot>/.cache/openyida/<项目名或任务名>/integration/`；不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向写文件，也不要写仓库根目录或系统临时目录。
- 连接器 action schema 只能来自 CLI 的平台只读发现或固定已证 preset；不得使用 `--connector-inputs` 自行声明未知字段类型，未知连接器、动作或输入字段必须停止且保持零写入。
- 连接器嵌套输入使用完整路径赋值，如 `Body.userid`、`Path.unionId`；只有 schema 中唯一的叶子名可以使用短名称。
- 需要宜搭 `systemToken` 的连接器动作使用 `--connector-system-token-app <appType>`，或在 spec 中声明 `secretBindings`；凭据只能由 CLI 校验官方目标后安全绑定，不能写入普通 assignment、页面源码或命令文本。
- `integration create --publish` 的成功只证明控制面保存、启用和配置回读；`runtimeVerified=false` 时不得宣称连接器已执行或通知已送达。需要运行验收时，必须按授权范围真实触发并独立读回业务结果。
- 参考官方示例时不要只看默认页面 schema；逻辑流本体必须通过集成自动化接口或命令查询、创建。
- 分析已有应用时，先执行不带筛选的 `integration list --json` 获取全部已知触发类型；不得只看表单事件就声称已完成自动化盘点。
- 新建逻辑流必须先由 CLI 创建绑定，再保存内容；禁止绕过 `createLogicflow.json` 直接用 `saveProcess` 冒充新建。首个写入前完成完整运行与设计配置的本地构建。
- 本技能不读写 memory；真实逻辑流 ID 从命令结果取得并按上方要求记录，不依赖跨会话记忆判断平台状态。

## 命令选择

| 用户目标 | 执行动作 |
| --- | --- |
| 创建新自动化 | 使用 `integration create`，由 CLI 生成 `processCode` |
| 字段与字段比较，如当前库存低于库存下限 | 尚未通过平台保存及运行验收，不能作为已支持能力交付；输入格式与限制见 [条件与变量](../yida-flow-node-config/references/conditions-variables.md) |
| 批量取数、新增或复制子表多行 | 使用 `integration create --spec`，读取通用技能的数据操作说明 |
| 整图替换已有自动化 | 校验 `appType/formUuid/processCode`，明确告知“CLI 无法读取原有节点定义；本次将整体覆盖，原节点不保留”，获得确认后使用 `integration create ... --process-code <code> --replace` |
| 更新已有自动化 | 使用 `integration update` 获取 capability 结果，并按结果报告当前状态 |
| 查询、启停或检查日志 | `integration list/enable/disable/check/diagnose` |
| 目标或归属不明确 | 先只读确认，不写入 |

`PLATFORM_PROBE_REQUIRED` 表示当前安全更新能力尚未证明，保持 `remoteWrites=0`。

## 命令格式

```bash
openyida integration create <appType> <formUuid> <flowName> [选项]
openyida integration update <appType> <formUuid> <processCode> --spec <desired-spec.json> [--publish]
openyida integration list <appType> [--flow-types 1,2,3,5,6] [--form-uuid <uuid>] [--status y|n] [--json]
openyida integration enable <appType> <formUuid> <processCode>
openyida integration disable <appType> <formUuid> <processCode>
openyida integration check <appType...> [--json] [--output result.xlsx] [--no-progress]
openyida integration diagnose --text "<异常信息>" [--json]
openyida integration diagnose --file <异常文件> [--json]
```

| 参数 | 含义 |
| --- | --- |
| `appType` | 目标应用 ID |
| `formUuid` | 自动化绑定的真实表单 ID |
| `flowName` | 新建自动化名称 |
| `processCode` | 已有逻辑流 ID，从查询结果取得 |

`update` 当前仍受安全更新检查限制，见上方命令选择。创建选项、参数默认值及完整示例见 [CLI 选项与示例](references/cli-options.md)；多节点 JSON 见 [spec 编排示例](references/spec-authoring.md)；批量节点见 [批量数据示例](references/batch-data.md)。

## 节点选择

| 类别 | 自动化当前可直接配置 | 差异或限制 |
| --- | --- | --- |
| 发起/触发 | 表单事件、流程完成或节点事件 | 不设置发起页字段权限；当前 create 不创建定时、应用或卡片触发 |
| 人工处理 | 无审批、办理、抄送人工节点 | 需要审批时用 `initiateApproval` 发起目标流程，在目标流程中配置审批人 |
| 流转控制 | `route` | 当前 spec 不支持并行、循环 |
| 数据操作 | `getSelf/dataRetrieve/dataCreate/dataUpdate`，含批量取数/新增 | 当前 spec 不支持删除；流程表单新增用发起审批 |
| 通知 | `sendMessage`，成员/角色/成员字段 | 当前 spec 不支持邮件或卡片 |
| 扩展执行 | `connector/initiateApproval` | 连接器需发现真实 action schema；当前 spec 不支持代码或 AI |

平台设计器有该节点，不代表当前 CLI 的 spec 支持。不要把流程的原生 props 放入自动化 spec，也不要把尚未封装的节点当作可任意透传。

## 基本步骤

1. 确认目标应用、触发表单、真实字段与触发时机；已有资源复用，不编造 `formUuid/fieldId`。
2. 从通用节点 Skill 选取所需配置。简单通知可用命令选项，多节点、角色通知和批量数据优先使用 `--spec`。
3. 用结构化文件写入工具创建 `<projectRoot>/.cache/openyida/<任务名>/integration/spec.json`，不要用 shell heredoc、重定向或写到仓库根目录。
4. 展示触发条件、节点、通知对象和目标写入范围，按上方严格要求获得用户明确同意后创建或发布。默认保存草稿，`--publish` 才启用。
5. CLI 在首个远端写入前验证 spec、连接器 schema 和字段，然后创建绑定、保存双 JSON，并按需要发布和回读。
6. 将返回的 `processCode` 等真实 ID 记入 `<projectRoot>/.cache/<项目名>-schema.json`；按 CLI 返回的验证等级报告结果。

```bash
openyida integration create <appType> <formUuid> <flowName> --spec <specFile> [--publish]
# 整图替换仅在已明确授权时使用
openyida integration create APP_XXX FORM_XXX "替换已有自动化" --process-code LPROC-XXX --replace --spec <specFile>
```

需要 spec 外层、公式展示字段或安全凭据绑定时，按上方链接读取 spec 编排示例。

## 最小 spec 与触发设置

```json
{
  "events": ["insert"],
  "nodes": [
    {
      "type":"sendMessage",
      "title":"新的申请",
      "content":"请查看申请详情",
      "toRoles":[{"roleCode":"<真实角色ID>","roleName":"财务"}]
    }
  ]
}
```

事件支持 `insert/update/delete/comment`、`processFinish/activityTask`。spec 使用流程事件时同时设置 `approvalActions`（`agree/disagree/terminated` 中的实际操作），节点事件另有 `approvalNodeIds`。只用命令选项创建时使用 `--events/--approval-actions/--approval-node-ids`；这些选项不会自动补入 spec。自动化“发起审批”的发起人，与目标流程审批角色是两项配置。

需要 `systemToken` 的连接器节点使用安全绑定片段，实际凭据由 CLI 读取，不能放进 `assignments`、命令文本或页面源码：

```json
{
  "secretBindings": [
    { "target": "body.systemToken", "provider": "yidaSystemToken", "appType": "<真实目标appType>" }
  ]
}
```

将片段放在 connector 节点内；完整连接器及安全绑定示例见上方 spec 编排说明。

## 查询、启停与日志

```bash
openyida integration list <appType> --json
openyida integration enable <appType> <formUuid> <processCode>
openyida integration disable <appType> <formUuid> <processCode>
openyida integration check <appType...> --json
openyida integration diagnose --text "<异常信息>" --json
```

盘点应用时，先执行未筛选的 `integration list`；默认分页覆盖触发类型 `1/2/3/5/6`。读到定时、应用事件、手动/卡片触发要保留其语义，不能改成表单事件后声称等价。启停后回读精确匹配的目标和状态。

`check` 分页读取异常日志，可加 `--output result.xlsx`；`diagnose` 可离线分析文本。无异常日志不代表业务条件命中或目标数据写入正确。

节点完整结构和接口参数见 [节点结构参考](references/integration-node-schemas.md)，常见应用示例见 [创建示例](references/examples.md)。只使用标准 CLI 选项时不必加载底层 JSON；编排多节点读取 spec 说明，排查 payload 时再读对应节点结构。

## 验证与异常

发布成功要求列表中 `formUuid + processCode` 唯一匹配、状态为 `y`，且详情非空；返回 `verificationLevel=PLATFORM_LIST_EXACT_DETAIL_PRESENT`。角色、批量节点、赋值等已启用的投影校验也必须通过。此等级不证明完整运行图已回读，不能据此解锁 `integration update`。

| 结果 | 处理 |
| --- | --- |
| `INTEGRATION_FULL_REPLACEMENT_REQUIRES_REPLACE` | 已获得整图替换确认时，补 `--replace` 重试一次；未授权先展示替换摘要 |
| `INTEGRATION_CONNECTOR_SCHEMA_UNVERIFIED` / `INTEGRATION_CONNECTOR_ACTION_NOT_FOUND` | 停止；需要平台只读发现或固定已证 preset，不能用 `--connector-inputs` 自行声明参数 |
| `INTEGRATION_CONNECTOR_REQUIRED_INPUT_MISSING` / `INTEGRATION_CONNECTOR_ASSIGNMENT_*` | 按真实 schema 修正参数，不绕过校验 |
| `INTEGRATION_PUBLISH_READBACK_UNVERIFIED` / `INTEGRATION_READBACK_*` | 报告未验证，保留资源，不将写响应当作成功 |
| 写入超时或结果未知 | 先只读核对状态，不能直接重试新增/更新 |
| 参数缺失、节点结构错误 | 停止，展示错误详情；从已有查询补齐真实参数，无法确定时询问用户，不猜测 |
| 登录态失效或权限不足 | 停止，运行 `openyida auth status` 核对；刷新失败时按 CLI 提示重新登录 |
| 未知错误 | 保留完整错误与资源 ID，停止；先只读核对是否已写入，再决定后续处理 |
| 权益不足 | 保留服务端错误；有明确依据才说明所需版本、权益包或官方购买入口 |

安全更新、保存顺序、输出口径和运行验收限制见 [spec 编排的保存与验证规则](references/spec-authoring.md#保存与验证规则)。`PLATFORM_PROBE_REQUIRED` 时必须保持 `remoteWrites=0`，保留 probe artifact 和 blocker；仅有列表或详情存在性不足以解锁更新，也不得降级为通用 JSON Patch。

连接器凭据只由 CLI 安全绑定，不写入页面、普通赋值或命令文本。保存或启用成功只证明控制面配置；`runtimeVerified=false` 时不能宣称连接器已执行或通知已送达。需要运行验收时再按授权范围触发并独立读回，不把本地测试当作运行证据。