快速上手

前置需求：Node ≥ 22、從你自己的後端取得的 teamsync-worker CLI（GET /starters/cli.tgz，任何部門成員都能下載；安裝時 npm 需要能連到 registry 或鏡像 — 見步驟 1）、單獨存成一個檔案且權限恰為 0600 的部門管理者 JWT（CLI 拒絕其他權限，也拒絕字面值 test-token），以及你的後端 origin（HTTPS、僅 origin）。若要不用 CLI 開始，請改從範本起步：範本與原始碼下載。

1. 取得 CLI 並建立骨架

BASE=https://<backend-origin>/private/module/edge-workers
export JWT=$(cat ~/.tsw/jwt)                 # the same token you keep in the 0600 file
curl -sS -H "Authorization: Bearer $JWT" -o cli.tgz "$BASE/starters/cli.tgz"
npm install --global ./cli.tgz               # the CLI that matches this backend's builder
teamsync-worker init department-api          # TypeScript (default); --language javascript for JS
cd department-api
npm ci --ignore-scripts

你會得到官方範本：五個操作的 users CRUD（listUsers、createUser、getUser、updateUser、deleteUser），示範 handler 契約、zod 驗證、靜態 JSON 資料、游標分頁與儲存介面。module.name 由目錄名稱推導，而且 init 會寫入 .gitignore，把 .teamsync/（生成的檔案、本機 dev 儲存、dev-secrets.json）排除在 git 之外。

2. 編輯、生成、本機把關

一起編輯 teamsync.worker.json（manifest — API 的唯一權威）與 src/，然後：

teamsync-worker generate    # .teamsync/generated.d.ts + openapi.preview.json
teamsync-worker validate    # runs the REAL platform builder locally — same reject codes as submission
teamsync-worker test        # node --test over tests/ in a sandboxed env

生成的 handler 輸入型別是 {request, params, query, operationId, config, secrets, storage}。validate 在本機通過，就代表提交時的建置也會通過，前提是 CLI 來自你要提交的那個後端：它委派給該後端的權威 builder，而不是自己重新實作，所以兩邊套用同一個 builder 政策（後端 5.22.0 為 department-worker-project-v2.10）。

3. 在 workerd 裡跑起來

teamsync-worker dev         # prints: teamsync-worker dev listening at http://127.0.0.1:<port>

真正的生成 router + 你的 bundle 跑在 workerd 裡，SQLite Durable Object 持久化在 .teamsync/dev-storage（目錄 0700、檔案 0600）。本機文件在 <origin>/_teamsync/docs。（僅限內部呼叫通道 — 存取模式與公開通道無法在本機重現。）如果你的 handler 會呼叫 context.secrets.get("NAME")，請先建立 .teamsync/dev-secrets.json：名稱／值組成的 JSON 物件，檔案權限 0600。dev 啟動時會把它同步進本機 Durable Object，之後不會再讀，所以編輯後要重啟（CLI 參考；已部署的機密值在管理 Worker 機密管理）。

curl -s http://127.0.0.1:<port>/users
# {"items":[]}

4. 提交 → 不可變修訂版

teamsync-worker submit --backend https://<backend-origin> --jwt-file ~/.tsw/jwt
# → 201: note version.id and worker.latest_revision

這一步會確定性打包（只有 4 個根檔案 + src/** 會進壓縮檔；.DS_Store、._*、__MACOSX/、Thumbs.db、desktop.ini 等作業系統垃圾檔會自動略過）、在伺服器端建置、把壓縮檔與 bundle 上傳到 artifact store（雲端為 R2），並建立狀態 ready 的修訂版 N。此時還沒有部署任何東西。管理者可以用 GET /worker/versions/{version_id}/source 再次下載任何版本的壓縮檔（範本與原始碼下載）。

5. 部署 → 輪詢

teamsync-worker deploy --backend … --jwt-file … \
  --version <version.id> --base-revision <worker.latest_revision> --wait

--wait 會輪詢票證直到終態；只有 completed 才回傳 exit code 0。一次部署最多可能要 10 分鐘才回報就緒，但 --wait 預設在 240 秒後放棄（deployment wait timed out，exit 1，部署本身會繼續進行）：請加上 --timeout-ms 720000，或稍後用 teamsync-worker status <ticket> 查看（部署與輪詢）。completed 也代表新 release 已在簽章控制通道上回應過 — 與閘道呼叫走的是同一條 dispatcher 路徑。遇到 409 就重新讀取 Worker 並使用它觀察到的修訂版 — 永遠不要盲目重送過期的部署（版本與部署）。

6. 呼叫

部門的第一次部署起始為 teamsync_internal：只有經過驗證的閘道能到達。以任何部門成員身分呼叫：

curl -s -H "Authorization: Bearer $JWT" \
  "https://<backend>/private/module/edge-workers/worker/invoke/users"

在部門管理者選擇其他存取模式之前，公開 URL 一律回 403 access_denied — 例如以 {"base_revision": 0, "mode": "public", "ip_allowlist": []} 呼叫 PUT /worker/access-policy（管理存取政策）。之後：

curl -s https://<dispatcher>/public/<script_name>/users        # public lane

（模式不再是 teamsync_internal 後，實際的公開 base URL 是下方 OpenAPI 文件的 servers[0].url）。已存有政策的 Worker 在後續部署中保留原政策。存取也可以逐操作設定（逐操作存取）。

7. 契約

teamsync-worker openapi --backend … --jwt-file … --out openapi.json

或在 TeamSync 網頁的 部門 Worker → API 文件 查看，它顯示的是同一份 GET /worker/openapi.json 文件。文件反映已部署修訂版、即時存取政策與即時操作設定，並附 ETag，任何一項改變時它也會跟著改變。

狀態碼速查

接下來看哪裡

Worker 機密、服務帳號、逐操作存取與地端部署各有獨立頁面：Worker 機密、服務帳號、逐操作存取、Edge Workers 地端部署。