CLI 参考 - OpenYida Docs

OpenYida 提供丰富的 CLI 命令，支持应用全生命周期管理。

环境与认证

# 环境检测
openyida env

# 登录
openyida login [--qr]              # --qr 使用终端二维码
openyida login --wukong            # 悟空环境专用

# 退出登录
openyida logout

# 登录态管理
openyida auth status               # 查看登录状态
openyida auth login                # 执行登录
openyida auth refresh              # 刷新登录态
openyida auth logout               # 退出登录

# 组织管理
openyida org list                  # 列出可访问的组织
openyida org switch --corp-id <id> # 切换组织

# 初始化工作目录
openyida copy [--force]            # 复制 project 目录（空目录时直接铺入内容）
openyida copy -skills              # 复制 yida-skills 到 AI 工具 skills 目录

# 诊断工具
openyida doctor [--fix]            # 环境诊断
openyida doctor --monitor          # 健康监控
openyida doctor --report <format>  # 生成报告 (json|markdown|html)

应用管理

# 创建应用
openyida create-app "<名称>" [desc] [icon] [color] [themeColor]

# 导出应用
openyida export <appType> [output] # 生成迁移包

# 导入应用
openyida import <file> [name]      # 从迁移包重建应用

# 更新应用信息
openyida update-app <appType> --name "<名称>" [--desc "<描述>"] [--icon "<图标>"] [--icon-color "<颜色>"]

选项	缩写	说明
`--name`	`-n`	应用名称（至少需要一个更新字段）
`--desc`	`-d`	应用描述
`--icon`		图标名称（如 `xian-yingyong`）
`--icon-color`		图标颜色（默认：`#0089FF`）

表单管理

# 创建表单
openyida create-form create <appType> "<表单名>" <字段JSON> \
  [--layout <布局>] \
  [--theme <主题>] \
  [--label-align <对齐>]

# 更新表单
openyida create-form update <appType> <formUuid> <修改JSON>

# 获取表单 Schema
openyida get-schema <appType> <formUuid>  # 任何涉及字段 ID 的操作前必须执行

# 更新表单配置
openyida update-form-config <appType> <formUuid> <isRenderNav> <title>

宜搭字段 ID 由平台随机生成（如 textField_eftt1aa5m、selectField_fix024y92），无法从字段名称推断。在执行任何涉及字段 ID 的操作前（包括创建/更新数据、配置查询条件、编写自定义页面），必须先运行 openyida get-schema 获取真实字段 ID。

支持的字段类型

create-form 命令仅接受以下字段类型。使用不支持的类型会返回错误。

基础字段

内置字段，无需安装任何插件。

类型	说明
`TextField`	单行文本
`TextareaField`	多行文本
`NumberField`	数字
`RateField`	评分
`DateField`	日期
`RadioField`	单选按钮
`SelectField`	下拉单选
`CheckboxField`	复选框
`MultiSelectField`	下拉多选
`CascadeSelectField`	级联选择
`CascadeDateField`	级联日期
`EmployeeField`	成员选择
`DepartmentSelectField`	部门选择
`AssociationFormField`	关联表单
`AssociationQuery`	关联查询
`AttachmentField`	附件
`ImageField`	图片
`AddressField`	地址
`CountrySelectField`	国家/地区选择
`TableField`	子表单/明细
`SerialNumberField`	流水号

高级字段

内置字段，部分功能可能需要开通。

类型	说明
`EditorField`	富文本编辑器
`DigitalSignatureField`	数字签名
`LocationField`	GPS 定位

插件字段

使用前需要从插件中心安装对应插件。

类型	所需插件
`TimeZoneDateField`	国际化时区组件
`CC_AIButtonField`	AI 组件
`CC_PG_ESignField`	智能财务组件
`CC_TeambitionProjectLinksField`	Teambition 插件
`CC_TeambitionTaskLinksField`	Teambition 插件
`CC_MoneyField`	智能财务组件
`CC_PhoneNumberField`	扩展组件
`CC_ChineseIdField`	扩展组件
`YidaDingtalkAgentField`	钉钉相关插件

插件字段在未安装对应插件的情况下会创建失败。请先从插件中心安装所需插件后再使用这些字段类型。

MobileField、EmailField 等字段类型不受支持，使用时会被拒绝。请仅使用上表中列出的类型。

页面管理

# 创建自定义页面
openyida create-page <appType> "<页面名>" [--datasource <jsonOrFile>]

# 编译并发布页面
openyida publish <源文件路径> <appType> <formUuid> [--skip-lint]

# 页面分享配置
openyida save-share-config <appType> <formUuid> <url> <isOpen> [openAuth]
openyida get-page-config <appType> <formUuid>
openyida verify-short-url <appType> <formUuid> <url>

数据管理

创建或更新数据前，必须先运行 openyida get-schema 获取真实字段 ID。写入数据后，使用 openyida data query form <appType> <formUuid> --size 1 抽查一条记录，确认 formData 中字段有实际值。若所有字段值为空，说明字段 ID 有误，需通过 get-schema 重新获取。

# 统一数据管理
openyida data <action> <resource> [args]

# 表单数据
openyida data query form <appType> <formUuid> [--page N] [--size N] [--search-json JSON]
openyida data get form <appType> --inst-id <id>
openyida data create form <appType> <formUuid> --data-json <JSON>  # JSON 键可以是字段 ID 或字段标签
openyida data update form <appType> --inst-id <id> --data-json <JSON>

# 流程数据
openyida data query process <appType> <formUuid> [--instance-status STATUS]
openyida data get process <appType> --process-inst-id <id>
openyida data create process <appType> <formUuid> --process-code <code> --data-json <JSON>

# 任务管理
openyida data query tasks <appType> --type <todo|done|submitted|cc>
openyida data execute task <appType> --task-id <id> --process-inst-id <id> --out-result <AGREE|DISAGREE>

# 子表单
openyida data query subform <appType> <formUuid> --inst-id <id> --table-field-id <fieldId>

全局任务中心

查询当前用户的全局任务中心数据，无需指定 appType。

# 待办任务
openyida task-center todo [--page N] [--size N] [--keyword TEXT]

# 我创建的
openyida task-center created [--page N] [--size N] [--keyword TEXT] [--no-detail]

# 我已处理
openyida task-center done [--page N] [--size N] [--keyword TEXT]

# 抄送我的
openyida task-center cc [--page N] [--size N] [--keyword TEXT]

# 我代提交的
openyida task-center proxy [--page N] [--size N] [--keyword TEXT]

任务类型

类型	说明	API 接口
`todo`	待办任务（需要我处理的）	`getTodoTasksInCorp`
`created`	我创建的（我发起的流程）	`getMyCreateInCorp`
`done`	我已处理（我已经处理过的）	`getDoneTasksInCorp`
`cc`	抄送我的	`getNotifyMeInCorp`
`proxy`	我代提交的（代理提交的流程）	`getSubmitAgentInCorp`

可选参数

参数	说明	默认值
`--page N`	页码	`1`
`--size N`	每页条数（最大 100）	`20`
`--keyword TEXT`	搜索关键词	—
`--no-detail`	不返回详情（仅 `created` 类型支持）	—

与 openyida data query tasks 不同，task-center 命令查询的是全局任务中心数据，不需要传入 appType 参数。

流程管理

# 创建流程表单（一体化）- 新建表单并配置流程
openyida create-process <appType> <formTitle> <fieldsJsonFile> <processDefinitionFile>

# 复用已有表单创建流程
openyida create-process <appType> --formUuid <formUuid> <processDefinitionFile>

# 配置并发布流程
openyida configure-process <appType> <formUuid> <processDefinitionFile> [processCode]

流程定义详情页 URL 属性

流程定义 JSON 文件支持以下可选属性，用于自定义用户查看流程实例时的详情页 URL。

属性	类型	说明
`processDetailUrl`	`string`	自定义 Web/PC 端流程详情页 URL。优先级最高，覆盖其他 Web 端详情 URL 设置。
`processMobileDetailUrl`	`string`	自定义移动端流程详情页 URL。优先级最高，覆盖其他移动端详情 URL 设置。
`customDetailPageUrl`	`string`	统一的自定义详情页 URL，同时适用于 Web 和移动端。移动端会自动追加 `?procInsId=`。
`detailUrls`	`object`	按平台区分的详情页 URL 对象。支持 `web`（或 `pc`）和 `mobile` 键。

Web 端详情 URL 的解析顺序：

processDetailUrl
detailUrls.web 或 detailUrls.pc
customDetailPageUrl
平台默认值

移动端详情 URL 的解析顺序：

processMobileDetailUrl
detailUrls.mobile
customDetailPageUrl（自动追加 ?procInsId=）
平台默认值

示例 — 使用 detailUrls：

{
  "detailUrls": {
    "web": "https://example.com/process/detail",
    "mobile": "https://m.example.com/process/detail"
  }
}

示例 — 使用 customDetailPageUrl（Web 和移动端共用同一 URL）：

{
  "customDetailPageUrl": "https://example.com/custom-detail"
}

权限管理

# 查询表单权限
openyida get-permission <appType> <formUuid>

# 保存表单权限
openyida save-permission <appType> <formUuid> \
  [--data-permission <json>] \
  [--action-permission <json>]

连接器管理

# 列出连接器
openyida connector list [--page N] [--size N]

# 创建连接器
openyida connector create "<名称>" "<域名>" --operations <file> [选项]

# 查看连接器详情
openyida connector detail <connector-id>

# 删除连接器
openyida connector delete <connector-id> [--force]

# 动作管理
openyida connector add-action --connector-id <id> --operations <file> [--confirm]
openyida connector list-actions <connector-id>
openyida connector delete-action <connector-id> <operation-id> [--force]
openyida connector test --connector-id <id> --action <actionId> [选项]

# 鉴权账号管理
openyida connector list-connections <connector-id>
openyida connector create-connection <connector-id> "<名称>" [选项]

# 智能创建
openyida connector smart-create --curl "<curl命令>" [--name <name>] [--desc <desc>]

# 辅助工具
openyida connector parse-api --curl "<curl命令>" --output <file>
openyida connector gen-template [输出路径]

报表管理

# 创建报表
openyida create-report <appType> "<报表名称>" <图表定义JSON或文件路径>

# 追加图表
openyida append-chart <appType> <reportId> <图表定义JSON或文件路径>

CDN 管理

# 配置 CDN
openyida cdn-config

# 上传图片
openyida cdn-upload <文件路径>

# 刷新缓存
openyida cdn-refresh <路径>

闪记转 PRD

使用 AI 将钉钉闪记（会议录音转文字）转化为结构化的 PRD 文档。

# 从文件读取
openyida flash-to-prd --file <文件路径> [--name <项目名>] [--max-tokens <数量>]

# 从标准输入读取
cat meeting.txt | openyida flash-to-prd --name <项目名> [--max-tokens <数量>]

参数

参数	缩写	说明	默认值
`--file`	`-f`	闪记文件路径	—
`--name`	`-n`	项目名称（未指定时自动从内容中推断）	—
`--max-tokens`	—	AI 响应的最大 token 数	`8000`

该命令从指定文件或标准输入读取闪记内容，对文本进行预处理（包括会议元数据提取和发言人识别），然后调用宜搭 AI 服务生成结构化的 PRD。输出的 PRD 文件保存到项目的 prd/ 目录。

输出

命令在 stdout 输出 JSON 格式的结果：

{
  "success": true,
  "projectName": "我的项目",
  "prdFile": "/path/to/prd/我的项目.md",
  "contentLength": 4096,
  "meetingRecognition": {
    "metaFields": 3,
    "a1Sections": 2,
    "speakers": 5
  }
}

运行此命令前需要先登录。如果尚未认证，请先运行 openyida login。

集成与自动化

创建集成逻辑流，在表单事件触发时自动执行通知、数据查询、数据新增等操作。

openyida integration create <appType> <formUuid> "<流程名称>" [选项]

必填参数

参数	说明
`<appType>`	应用 ID
`<formUuid>`	触发表单 UUID
`<flowName>`	集成流程名称

选项

选项	说明	默认值
`--process-code <code>`	已有流程编码（省略则新建）	—
`--receivers <id1,id2>`	通知接收人用户 ID（逗号分隔）	—
`--title <text>`	通知标题	流程名称
`--content <text>`	通知正文	—
`--events <types>`	触发事件（逗号分隔）：`insert`、`update`、`delete`	`insert`
`--data-form-uuid <uuid>`	”获取单条数据”节点的表单 UUID	—
`--data-condition <mapping>`	数据节点字段映射（`bFieldId:bFieldName:aFieldId[:componentType]`），可多次指定	—
`--add-data-form-uuid <uuid>`	”新增数据”节点的表单 UUID	—
`--add-data-assignment <mapping>`	新增数据节点字段赋值（`目标字段ID:valueType:value`），`valueType` 可选：`processVar`（引用触发表单字段）、`literal`（固定值）、`column`（公式），可多次指定	—
`--publish`	创建后立即发布流程	仅保存草稿

示例

# 创建新提交通知流程
openyida integration create APP_XXX FORM-YYY "新订单提醒" \
  --receivers "user1,user2" \
  --events insert \
  --title "新订单" \
  --content "有新订单提交，请及时查看"

# 创建并立即发布
openyida integration create APP_XXX FORM-YYY "自动通知" \
  --receivers "user1" \
  --publish

钉钉 CLI (dws)

代理执行钉钉 CLI 命令，支持通讯录、日历、待办、审批、考勤等功能。

openyida dws <command> [args]

dws 命令需要单独安装钉钉 CLI。如果未安装，OpenYida 会在首次使用时提示安装。

常用命令

命令	说明
`contact user search --keyword "<姓名>"`	搜索联系人
`calendar event list`	列出日历事件
`todo task create --title "<标题>" --executors "<用户ID>"`	创建待办任务
`approval instance list`	列出审批实例
`attendance record list`	查询考勤记录
`chat robot send --content "<消息>"`	发送机器人消息

特殊命令

# 安装钉钉 CLI
openyida dws install

# 显示帮助
openyida dws help

输出格式

默认使用表格输出（适合人类阅读）。添加 -f json 参数使用 JSON 输出（适合 AI Agent）。

openyida dws contact user search --keyword "悟空" -f json

导出对话记录

将当前 AI 工具的对话记录导出为 Markdown 文档。

openyida export-conversation [选项]

选项

选项	缩写	说明	默认值
`--output`	`-o`	输出文件路径	自动生成路径
`--input`	`-i`	输入对话文件（JSON/JSONL）	—
`--latest`	—	只导出最新对话	默认启用
`--list`	—	列出可用的对话记录	—

示例

# 导出当前对话记录
openyida export-conversation

# 导出到指定路径
openyida export-conversation -o output.md

# 列出可用对话
openyida export-conversation --list

# 从指定输入文件导出
openyida export-conversation -i conversation.json -o result.md

全局选项

选项	说明
`--help`, `-h`	显示帮助信息
`--version`, `-v`	显示版本号
`--qr`	使用终端二维码登录
`--force`	强制操作，跳过确认
`--skip-lint`	在 `publish` 时跳过宜搭编码规范预检

环境变量

变量	说明	示例
`OPENYIDA_LANG`	设置语言	`zh`, `en`, `ja`
`LANG` / `LC_ALL`	系统语言	`zh_CN.UTF-8`
`AGENT_WORK_ROOT`	悟空工作区根路径（动态 UUID）	`~/.real/users/user-xxx/`

退出码

码	含义
0	成功
1	一般错误
2	参数错误
3	登录失败/未登录
4	网络错误
5	API 错误

开始使用

功能特性

架构设计

使用指南

社区

​环境与认证

​应用管理

​表单管理

​支持的字段类型

​基础字段

​高级字段

​插件字段

​页面管理

​数据管理

​全局任务中心

​任务类型

​可选参数

​流程管理

​流程定义详情页 URL 属性

​权限管理

​连接器管理

​报表管理

​CDN 管理

​闪记转 PRD

​参数

​输出

​集成与自动化

​必填参数

​选项

​示例

​钉钉 CLI (dws)

​常用命令

​特殊命令

​输出格式

​导出对话记录

​选项

​示例

​全局选项

​环境变量

​退出码

环境与认证

应用管理

表单管理

支持的字段类型

基础字段

高级字段

插件字段

页面管理

数据管理

全局任务中心

任务类型

可选参数

流程管理

流程定义详情页 URL 属性

权限管理

连接器管理

报表管理

CDN 管理

闪记转 PRD

参数

输出

集成与自动化

必填参数

选项

示例

钉钉 CLI (dws)

常用命令

特殊命令

输出格式

导出对话记录

选项

示例

全局选项

环境变量

退出码