為Roomcord打造迷你應用程式

在團隊日常工作的房間中加入工作流程。從starter、poll或approvals範例開始，為房間建立應用程式。

什麼是迷你應用程式

迷你應用程式是位於單一Roomcord房間中的小型應用程式。房間以集合中的記錄保存應用程式資料。應用程式的函式在伺服器的沙箱中執行，也是唯一能修改這些記錄的程式碼。房間成員與安裝在房間中的AI代理可呼叫這些函式，客戶端則依據應用程式的結構描述顯示通用畫面。

開始之前

電腦上已安裝Node.js與npm。
擁有公司Roomcord for Enterprise伺服器的帳號。
在發布應用程式的房間中具備管理員角色。只有房間管理員可以推送與核准應用程式。

快速開始

本指南使用@fulldivevr/workcord-cli的4.1.0版。命令列工具名稱為workcord。每個指令都會將JSON輸出至stdout。

安裝CLI。
```
npm i -g @fulldivevr/workcord-cli
```
登入。驗證碼會寄到電子郵件信箱，CLI會要求輸入該驗證碼。如果公司自行架設伺服器，請向管理員索取其來源位址，並在這個指令中加入一次 --base-url <origin>。登入時會儲存伺服器設定。
```
workcord auth login --email [email protected] --save
```
找出房間的id。
```
workcord rooms list
```
從範本建立新的應用程式資料夾。
```
workcord app init my-app
```
在電腦上執行伺服器的檢查與應用程式測試，不需要伺服器。
```
workcord app test my-app
```
將應用程式儲存為房間的待核准草稿。結果包含draftId。
```
workcord app push my-app --room <roomId>
```

核准草稿。應用程式隨即安裝在該房間中。

workcord app drafts --room <roomId>
workcord app approve <draftId> --room <roomId>

呼叫函式。

workcord app call my-app addEntry --room <roomId> --data '{"title":"Dune"}'
workcord app describe my-app --room <roomId>

推送升級版本之前，請執行workcord app validate my-app --room <roomId>。這會加入需要房間才能執行的檢查，包括版本與既有記錄。

套件格式

套件是一個資料夾：

my-app/
  manifest.json      id, version, name, summary, icon, collections, functions
  GUIDE.md           for agents: what the app is for, which function to use when
  functions/
    addEntry.js      one file per function in the manifest
  tests/
    entries.json     one scenario or a list of scenarios

manifest.json宣告集合與函式。每個集合都有JSON Schema，每次寫入都必須符合該結構描述。每個函式都有description、input結構描述與callers清單。
callers指定誰可以呼叫函式：members、admins或agents。代理依據description選擇函式。
GUIDE.md說明代理如何使用應用程式。
tests/至少包含一個測試情境。推送之前與核准之前，檢查都會執行每個情境。

函式結構

函式檔案只能有一個export default，不能有其他import或export。函式接收事件與執行上下文：

export default async (event, ctx) => {
  const { title, notes } = event.data;
  return ctx.db.entries.insert({ title, notes, status: 'open' });
};

event.data是經過結構描述檢查的輸入。
event.caller是發出呼叫的使用者或代理，由引擎設定，因此應用程式的程式碼不負責驗證身分。
ctx.db.<collection>提供get、query、insert、update與delete。每次呼叫都會回傳Promise。
throw new AppError(code, message)會將該錯誤碼與訊息回傳給呼叫者。

每次寫入都會保存記錄的版本，刪除記錄時也會保留其歷程。

限制

限制	數值
每次函式呼叫的總耗時	1 s
每次呼叫的記憶體	32 MB
堆疊	512 KB
函式結果	256 KB，JSON格式
記錄	256 KiB，JSON格式
套件	512 KB，JSON格式
每個應用程式的集合數	1至20
每個應用程式的函式數	50
全部測試情境的總耗時	10 s

函式沒有網路、檔案系統、計時器，也不能匯入其他程式碼。函式無法呼叫其他應用程式或讀取其他房間。這些工作由代理執行。

誰可以發布

只有房間管理員可以推送與核准應用程式。房間中的代理可以儲存草稿，但必須由管理員核准。核准後的應用程式只會安裝在該房間中。每個新版本的version都必須高於該房間過去核准的所有版本。

範例與完整指南

公開儲存庫 fulldiveVR/roomcord-mini-apps 提供三個入門範例：starter、poll與approvals。

完整指南涵蓋集合、查詢、顯示提示、測試情境、升級與錯誤碼。