範本與原始碼下載

誰： 範本與 CLI 下載是任何部門成員；某個版本的原始碼是部門管理者。端點： GET /starters、GET /starters/cli.tgz、GET /starters/{starter_id}/{language}/source.zip、GET /starters/{starter_id}/{language}/department-worker.tar.gz，以及 GET /worker/versions/{version_id}/source。路徑相對於 {BASE}/private/module/edge-workers；每個呼叫都帶 Authorization: Bearer <jwt>（驗證與角色）。範本路由在你的部門還沒有 Worker 時就能用；下載版本原始碼則需要已有 Worker。

BASE=https://<backend-origin>/private/module/edge-workers
export JWT=<your TeamSync JWT>        # JWT only: an API key is not accepted

首次隨後端 v5.13.0（範本與 CLI 下載）與 v5.14.0（版本原始碼下載）發佈。

後端提供什麼

任何部門成員都能呼叫：持有效 JWT、所屬部門存活的使用者，沒有角色門檻。API 金鑰不被接受（這些路由只讀取 Bearer JWT），服務帳號則以 403 拒絕，與所有 Edge Workers 路由相同。這些檔案在建置後端映像檔時產生，而且每個範本都先經過建置你的提交所用的同一個權威 builder 驗證，所以範本一定通過這個後端的 builder，CLI 也帶著這個後端的 builder 政策。因此目錄只會在後端重新部署時改變。

starter_id 是 department-users-api（唯一的範本），language 是 javascript 或 typescript。5.22.0 的後端兩種語言都提供。

範本目錄

curl -sS -H "Authorization: Bearer $JWT" "$BASE/starters"

{
  "builder_policy_version": "department-worker-project-v2.10",
  "starters": [
    { "id": "department-users-api", "language": "javascript",
      "title": "Department Users API",
      "description": "A manifest-first, multi-operation department Worker example.",
      "source_zip":      { "size_bytes": N, "sha256": "…" },
      "project_archive": { "size_bytes": N, "sha256": "…" } },
    { "id": "department-users-api", "language": "typescript", /* same shape */ }
  ],
  "cli": { "version": "0.1.0", "size_bytes": N, "sha256": "…" }
}

伺服器不會送出大小或 SHA-256 與目錄不符的檔案，你也可以對自己下載的檔案做同樣檢查：sha256sum <file> 必須印出目錄中的 sha256（macOS：shasum -a 256 <file>）。

不用 CLI 就開始

編輯原始碼。 下載 zip，解壓縮到新的空目錄（zip 沒有最上層資料夾）：

curl -sS -H "Authorization: Bearer $JWT" -o starter.zip \
  "$BASE/starters/department-users-api/typescript/source.zip"
mkdir department-api && unzip starter.zip -d department-api

一起編輯 teamsync.worker.json（manifest）與 src/。若要換成自己的模組名稱，請一次全部改掉：manifest 的 module.name、package.json 的 name，以及 package-lock.json 的根 name 與 packages[""].name。任何不一致都會被 builder 拒絕（project_identity_mismatch、package_lock_invalid；validate 會印出代碼），而 teamsync-worker init 建立骨架時會替你改寫。提交必須是確定性壓縮檔格式（提交版本）：用 CLI 的 pack 產生（見下方「從你的後端取得 CLI」）。範本自帶的 README.zh-TW.md 還描述了一條網頁路線：在 部門 Worker 頁面下載範本、編輯後，把專案資料夾（或 .zip）拖進上傳對話框，由瀏覽器為你建立 department-worker.tar.gz。

原封不動上傳範本。 現成的壓縮檔在映像檔建置時已被這個後端的 builder 接受，所以可以照下載的樣子直接提交。這是看到一個可運作的 Worker 最快的方式：

curl -sS -H "Authorization: Bearer $JWT" -o department-worker.tar.gz \
  "$BASE/starters/department-users-api/typescript/department-worker.tar.gz"
curl -sS -H "Authorization: Bearer $JWT" \
  -F "project=@department-worker.tar.gz;type=application/gzip" \
  "$BASE/worker/versions"                       # manager only → 201, a ready revision

部署是另一個步驟（部署與輪詢）。

從你的後端取得 CLI

teamsync-worker 是私有套件 @teamsync/department-workers，不在公開的 npm registry 上。每個後端提供與自己 builder 相符的那一份：

curl -sS -H "Authorization: Bearer $JWT" -o cli.tgz "$BASE/starters/cli.tgz"
npm install --global ./cli.tgz
teamsync-worker --help

• 需要 Node ≥ 22。npm 必須能連到 registry 或公司鏡像，因為安裝這個 tarball 會下載它的四個執行期依賴（esbuild、miniflare、typescript-parser、zod）。
• 使用你要提交的那個後端提供的 CLI：這樣 validate 跑的就是該後端伺服器端建置所用的同一個 builder 與 builder 政策（目錄把政策回報為 builder_policy_version）。
• npm 接受任何 .tgz 檔名；伺服器把下載檔名取為 cli.tgz。
• 每個指令、旗標與結束行為：CLI 參考。

下載你部署過的內容

GET /worker/versions/{version_id}/source 會逐位元組回傳你部門 Worker 某個版本所儲存的 department-worker.tar.gz。

curl -sS -H "Authorization: Bearer $JWT" -o department-worker.tar.gz \
  "$BASE/worker/versions/<version_id>/source"
sha256sum department-worker.tar.gz              # must equal project_digest of that version

• 誰： 部門管理者。能透過 GET /worker/versions/{version_id} 讀取版本的成員，不能下載它的原始碼。
• 哪些版本： 你部門 Worker 的任何版本，只要該列儲存了壓縮檔，不論狀態，已被取代的也可以。其他部門或公司的版本，回應與不存在的 id 完全相同。
• 完整性： 送出之前，後端會讀取該物件（最多 2 MiB，即專案壓縮檔上限），並以版本的 project_digest 檢查它的 SHA-256。project_digest 欄位在版本的回應中（GET /worker/versions、GET /worker/versions/{version_id}），所以你也能核對自己的副本。
• 回應： 200，Content-Type: application/gzip、Content-Disposition: attachment; filename="department-worker.tar.gz"、Cache-Control: private, no-store。
• 重新提交或編輯： 這個檔案是提交格式，所以能原封不動送到 POST /worker/versions（得到新的修訂版，絕不覆寫）。要編輯就用 tar -xzf 解到空目錄。壓縮檔只含 pack 會出貨的內容：teamsync.worker.json、package.json、package-lock.json、tsconfig.json 與 src/**。CLI 的 validate、test、pack 還需要 README.md、.teamsyncignore 與非空的 tests/，所以先從範本的 source.zip 複製過來。
• 稽核： 下載不會被記成稽核事實；伺服器只寫一行日誌，內含公司、部門、使用者與版本 id。

各個檔案的內容

範本是五個操作的 users CRUD（listUsers、createUser、getUser、updateUser、deleteUser），示範 handler 契約、zod 驗證、靜態 JSON 資料、游標分頁與儲存介面。

錯誤

帶代碼的 detail 物件是 {code, message}；其他列是純字串（錯誤）。端點總覽：端點。

操作者備註

範本檔案放在 EDGE_WORKER_STARTERS_DIR 指定的目錄（預設 /opt/teamsync/edge-worker-starters，API 行程啟動時讀取）。映像檔建置時會把 catalog.json、cli.tgz，以及每個範本的 <starter_id>/<language>/source.zip 與 <starter_id>/<language>/department-worker.tar.gz 放進去；若權威 builder 拒絕某個範本，建置就會失敗。每個請求都會重新讀取並重新驗證 catalog.json，也會重新檢查它要送出的檔案，所以自訂映像檔必須保留該目錄（或把這個變數指向一份副本），否則 /starters* 路由會回 503。見環境變數。