跳轉到主要內容
OpenYida 提供豐富的 CLI 命令,支持應用全生命週期管理。

環境與認證

# 環境檢測
openyida env

# 多環境管理
openyida env list                  # 列出所有環境,高亮當前激活環境
openyida env add <name>            # 交互式添加私有化部署環境
openyida env switch <name>         # 切換激活環境
openyida env remove <name>         # 刪除環境(public 不可刪)
openyida env show [name]           # 顯示環境詳細配置

# 登錄
openyida login [--qr]              # --qr 使用終端二維碼
openyida login --agent-qr         # Agent QR handoff

# 退出登錄
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 update                    # 檢查並更新到最新版本

應用管理

# 創建應用
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> [--force]

# 獲取表單 Schema
openyida get-schema <appType> <formUuid>  # 任何涉及欄位 ID 的操作前必須執行

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

# 列出應用內的表單頁面
openyida list-forms <appType> [--keyword <關鍵>]
宜搭欄位 ID 由平台隨機生成(如 textField_eftt1aa5mselectField_fix024y92),無法從欄位名稱推斷。在執行任何涉及欄位 ID 的操作前(包括建立/更新資料、設定查詢條件、撰寫自訂頁面),必須先執行 openyida get-schema 取得真實欄位 ID。
更新已有資料的表單時,CLI 會在修改前進行安全檢查。如果偵測到已有記錄且未設定 --force,指令會輸出包含 requiresConfirmation: true 的 JSON 回應並退出,不會進行任何修改。傳入 --force 可跳過確認並繼續更新。確認回應包含以下欄位:
欄位類型說明
successboolean需要確認時始終為 false
requiresConfirmationboolean始終為 true
formUuidstring正在更新的表單 UUID
appTypestring應用 ID
existingDataCountnumber表單中已有的記錄數
messagestring可讀的確認訊息
hintstring顯示 --force 用法的提示

列出表單頁面

查詢指定應用內的所有表單頁面,支援按關鍵詞過濾。指令將 JSON 陣列輸出到 stdout。
openyida list-forms <appType> [--keyword <關鍵>]
參數說明
<appType>應用 ID(例如 APP_XXXXX
選項說明預設值
--keyword <關鍵詞>按表單名稱、UUID、類型或路徑名稱過濾(不區分大小寫)

輸出

指令在 stdout 輸出 JSON 陣列。每個條目包含以下欄位:
欄位類型說明
formUuidstring表單唯一標識
formNamestring本地化的表單名稱
formTypestring表單類型(如 displayprocess
pathNamestring表單的 URL 路徑名稱
輸出範例:
[
  {
    "formUuid": "FORM-AAA",
    "formName": "客戶資訊",
    "formType": "display",
    "pathName": "customer-info"
  },
  {
    "formUuid": "FORM-BBB",
    "formName": "費用報銷",
    "formType": "process",
    "pathName": "expense"
  }
]
使用範例:
# 列出應用內所有表單
openyida list-forms APP_XXXXX

# 按關鍵詞過濾
openyida list-forms APP_XXXXX --keyword "客戶"
系統導航項目(如內建的任務檢視)會自動排除,輸出僅包含使用者建立的表單頁面。
執行此指令前需要先登入。如尚未認證,請先執行 openyida login

支援的欄位類型

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數位簽名
LocationFieldGPS 定位

外掛欄位

使用前需要從外掛中心安裝對應外掛。
類型所需外掛
TimeZoneDateField國際化時區元件
CC_AIButtonFieldAI 元件
CC_PG_ESignField智慧財務元件
CC_TeambitionProjectLinksFieldTeambition 外掛
CC_TeambitionTaskLinksFieldTeambition 外掛
CC_MoneyField智慧財務元件
CC_PhoneNumberField擴充元件
CC_ChineseIdField擴充元件
YidaDingtalkAgentField釘釘相關外掛
外掛欄位在未安裝對應外掛的情況下會建立失敗。請先從外掛中心安裝所需外掛後再使用這些欄位類型。
MobileFieldEmailField 等欄位類型不受支援,使用時會被拒絕。請僅使用上表中列出的類型。

頁面管理

# 創建自定義頁面
openyida create-page <appType> "<頁面名>" [--mode dashboard] [--open|--no-open]

# 編譯併發布頁面
openyida publish <源文件路> <appType> <formUuid> [--health-check] [--force] [--open|--no-open]

# 頁面分享配置
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]

# 預覽流程實例(視覺化流程圖)
openyida process preview <appType> <processInstanceId> [--output <path>]

流程實例預覽

為執行中或已完成的流程實例產生互動式 HTML 流程圖。流程圖會醒目顯示節點狀態——已完成(綠色)、當前節點(藍色脈衝)、未到達(灰色)、被跳過(虛線)——並在懸停時顯示審批人詳情和時間戳記。
openyida process preview <appType> <processInstanceId> [--output <path>]
參數說明
<appType>應用程式 ID(例如 APP_XXXXX
<processInstanceId>要視覺化的流程實例 ID
選項別名說明預設值
--output-o產生的 HTML 檔案輸出路徑在當前目錄自動產生
該命令會取得流程實例詳情和審批操作紀錄,然後產生基於 SVG 的 HTML 檔案並在預設瀏覽器中開啟。 範例:
openyida process preview APP_XXXXX proc-inst-id-xxx
openyida process preview APP_XXXXX proc-inst-id-xxx --output flowchart.html
執行此命令前需要先登入。如果尚未認證,請先執行 openyida login

流程定義詳情頁 URL 屬性

流程定義 JSON 檔案支援以下可選屬性,用於自訂使用者查看流程實例時的詳情頁 URL。
屬性類型說明
processDetailUrlstring自訂 Web/PC 端流程詳情頁 URL。優先級最高,覆蓋其他 Web 端詳情 URL 設定。
processMobileDetailUrlstring自訂行動端流程詳情頁 URL。優先級最高,覆蓋其他行動端詳情 URL 設定。
customDetailPageUrlstring統一的自訂詳情頁 URL,同時適用於 Web 和行動端。行動端會自動附加 ?procInsId=
detailUrlsobject按平台區分的詳情頁 URL 物件。支援 web(或 pc)和 mobile 鍵。
Web 端詳情 URL 的解析順序:
  1. processDetailUrl
  2. detailUrls.webdetailUrls.pc
  3. customDetailPageUrl
  4. 平台預設值
行動端詳情 URL 的解析順序:
  1. processMobileDetailUrl
  2. detailUrls.mobile
  3. customDetailPageUrl(自動附加 ?procInsId=
  4. 平台預設值
範例 — 使用 detailUrls
{
  "detailUrls": {
    "web": "https://example.com/process/detail",
    "mobile": "https://m.example.com/process/detail"
  }
}
範例 — 使用 customDetailPageUrl(Web 和行動端共用同一 URL):
{
  "customDetailPageUrl": "https://example.com/custom-detail"
}

錯誤處理與重試

如果流程設定失敗但表單已建立完成,命令會輸出重試提示,並附帶 --formUuid 參數,方便你複用已建立的表單而無需重新建立:
openyida create-process <appType> --formUuid <formUuid> <processDefinitionFile>
適用場景:
  • 流程定義檔案存在錯誤,需要修正後重試。
  • 網路或 API 臨時故障導致設定步驟中斷。
命令會將 JSON 結果輸出到 stdout。成功時:
{
  "success": true,
  "formUuid": "FORM-XXXXX",
  "formTitle": "Order Form",
  "appType": "APP_XXXXX",
  "fieldCount": 5,
  "processCode": "TPROC-XXXXX",
  "url": "https://www.aliwork.com/APP_XXXXX/workbench/FORM-XXXXX"
}
失敗時(例如流程設定失敗):
{
  "success": false,
  "formUuid": "FORM-XXXXX",
  "formTitle": "Order Form",
  "appType": "APP_XXXXX",
  "fieldCount": 5,
  "error": "Failed to configure process: <error details>"
}
當輸出中包含 formUuid 的失敗訊息時,使用 --formUuid 參數重試即可避免重複建立表單。

整合與自動化

建立和管理邏輯流(整合&自動化),支援表單事件觸發、訊息通知、資料操作等場景。
# 建立邏輯流
openyida integration create <appType> <formUuid> <flowName> [選項]

參數

參數必填說明
appType應用 ID(如 APP_XXXX
formUuid觸發表單 UUID(如 FORM-XXXX
flowName邏輯流名稱

選項

選項預設值說明
--process-code <code>自動產生已有邏輯流的 processCode(LPROC-xxx 格式)
--receivers <userId,...>接收釘釘工作通知的使用者 ID,多個用逗號分隔
--title <title>同 flowName通知標題,支援 #{fieldId-ComponentType}# 引用表單欄位
--content <content>"表單有新記錄提交,請及時查看。"通知內容,支援欄位變數引用
--events <insert,update>insert觸發事件:insert/update/delete/comment,多個用逗號分隔
--add-data-form-uuid <formUuid>新增資料節點的目標表單 UUID
--add-data-assignment <targetFieldId:valueType:value>新增資料的欄位賦值,可多次傳入。valueType 可選 processVar/literal/column
--publish不發佈儲存後立即發佈(開啟狀態),否則僅儲存為草稿

輸出

{
  "success": true,
  "published": false,
  "processCode": "LPROC-XXXX",
  "flowName": "新增記錄通知",
  "appType": "APP_XXX",
  "formUuid": "FORM-XXX",
  "formEventTypes": ["insert"]
}
執行此命令前需要先登入。使用 --publishpublishedtrue;若發佈失敗,publishedfalse 並附帶 warning 欄位。

權限管理

# 查詢表單權限
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-tokensAI 回應的最大 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> "<流程名稱>" [options]

必填參數

參數說明
<appType>應用程式 ID
<formUuid>觸發表單 UUID
<flowName>整合流程名稱

選項

選項說明預設值
--process-code <code>已有流程編碼(省略則新建)
--receivers <id1,id2>通知接收人使用者 ID(逗號分隔)
--title <text>通知標題流程名稱
--content <text>通知正文
--events <types>觸發事件(逗號分隔):insertupdatedeleteinsert
--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

自更新

檢查 npm 上是否有更新版本的 OpenYida,並全局安裝。
openyida update
該命令會查詢 npm registry 獲取最新發佈版本。如果有更新的版本,會執行 npm install -g openyida@latest 進行升級。如果已是最新版本,會列印確認資訊並退出。
OpenYida 在每次運行命令時也會在後台自動檢查更新。update 命令可以讓你手動觸發檢查並立即安裝。

全局選項

選項說明
--help, -h顯示幫助信息
--version, -v顯示版本號
--qr使用終端二維碼登錄
--force強制操作,跳過確認
--health-checkRun a health check after publishing a custom page

環境變量

變量說明示例
OPENYIDA_LANG設置語言zh, en, ja
LANG / LC_ALL系統語言zh_CN.UTF-8
AGENT_WORK_ROOT悟空工作區根路徑(動態 UUID)~/.real/users/user-xxx/
OPENYIDA_ENDPOINT強制指定宜搭服務地址(優先級最高)https://yida.example.com
OPENYIDA_LOGIN_URL強制指定登錄頁地址https://yida.example.com/login
OPENYIDA_ENV快速切換環境(不修改配置文件,適合 CI/CD)my-private-env
OPENYIDA_DWS_ENDPOINT私有化釘釘 OpenAPI 網關地址https://oapi.example.com

端點解析優先級

當確定宜搭服務地址時,按以下順序解析:
  1. OPENYIDA_ENDPOINT 環境變量
  2. 當前激活環境的配置(通過 openyida env switch 設置)
  3. Cookie 中緩存的 base_url
  4. 默認公有雲地址(https://www.aliwork.com
登錄頁地址解析順序:
  1. OPENYIDA_LOGIN_URL 環境變量
  2. 當前激活環境的配置
  3. 默認登錄頁地址(https://www.aliwork.com/workPlatform

退出碼

含義
0成功
1一般錯誤
2參數錯誤
3登錄失敗/未登錄
4網絡錯誤
5API 錯誤