cargo-cdk

Cargo CDK — 宣告式工作區即程式碼

使用此技能在 TypeScript 中定義 Cargo 工作區（使用 @cargo-ai/cdk 的 define* 建構器），並透過 cargo-ai cdk deploy 將其與實際基礎設施同步。這是宣告式的對應技能，與指令式功能技能相對：不是對每個資源執行單一 CLI 指令，而是將整個圖表編寫一次並可重複部署，並透過提交的 cargo.state.json 將程式碼與 Cargo 建立的資源連結起來。

1) 此技能涵蓋的範圍

• 編寫每個 Cargo 資源，使用回傳控制代碼的 define* 建構器；透過將控制代碼傳遞給彼此來連接資源（依賴圖就是你的變數圖）。
• 部署圖表：plan（離線差異比對）→ deploy（建立/更新，寫入狀態）→ destroy（拆除）。以及漂移偵測（refresh）、採用（import）和復原（rollback）。
• 型別化設定檔，對應工作區的真實整合架構（cargo-ai cdk types）。

CDK 涵蓋所有資源類型 — 因此它與每個指令式功能技能（cargo-connection、cargo-storage、cargo-ai、cargo-orchestration、cargo-content、cargo-hosting……）都有重疊。選擇哪一個是首要決策：

2) CDK 還是 CLI？— 路由決策

宣告式（此技能）vs 指令式（功能技能）。

當使用者將資源視為成品管理時，使用 CDK：

• "設定 / 建立 / 啟動整個工作區（以程式碼形式 / 從範本）。"
• "讓這個可重現 / 版本控制 / 放在 git 中 / 跨環境可重複（開發 → 正式環境）。"
• "一起部署這些連接器 + 模型 + 代理"（一個由依賴關係連接的多資源圖表）。
• 任何應該可重新執行且可差異比對，且遺失定義會造成問題的情況。

當使用者進行一次性操作或探索時，使用對應的功能技能（指令式 cargo-ai <domain>）：

• "建立一個連接器"、"在此模型中新增一個欄位"、"列出連接器"、"執行此工作流程"、"查詢儲存"、"讀取此代理的記憶體。"
• 任何讀取、臨時查詢或不需要保留在程式碼中的單一變更。

如果不確定，請詢問結果是否應該提交並可重新部署。如果是 → CDK。如果是快速操作或讀取 → 功能技能（請參閱 cargo 路由器 以選擇正確的領域）。

3) 生命週期

cargo-ai cdk init <dir>     從範本（空白 | 完整）建立專案
        │
cargo-ai cdk types          為型別化設定檔產生每個工作區的型別（可選）
        │
   (編寫 define* 檔案)       匯入 .ts 檔案即註冊 — 無需清單
        │
cargo-ai cdk plan           離線：編譯圖表，與 cargo.state.json 差異比對
        │
cargo-ai cdk deploy         依賴順序建立/更新資源，寫入狀態
        │
cargo-ai cdk destroy        拆除狀態中記錄的資源

分支：cargo-ai cdk refresh（唯讀漂移報告）· deploy --refresh（重新套用程式碼以覆蓋外部編輯）· deploy --prune（刪除從程式碼中移除的資源）· cargo-ai cdk import <id> <uuid>（將現有實際資源綁定到狀態中）· cargo-ai cdk rollback（還原部署前的狀態快照）。

4) 文件層級

• Level 1 — SKILL.md（此檔案）：決策模型、生命週期、關鍵規則和路由。
• Level 2 — 指南：
  guides/authoring-resources.md、
  guides/deploy-and-state.md、
  guides/typed-config.md。
• Level 2.5 — 食譜： recipes/*.md — 可作為執行計畫的逐步操作手冊。
• 參考資料 — references/resources.md（完整的建構器目錄）、references/commands.md（每個 cargo-ai cdk 子指令和旗標）、references/troubleshooting.md 和 references/examples/full-workspace.md。

5) 閱讀行為 — 將任務對應到文件並閱讀

當任務涉及…	先閱讀此文件	提供的內容
編寫 define* 檔案、連接資源、secret()/env()、defineWorkflow 主體（工具/劇本邏輯）	guides/authoring-resources.md	建構器目錄、控制代碼/參照模型、秘密，以及工作流程主體如何編譯。
plan / deploy / destroy、狀態檔案、漂移、採用現有資源、CI	guides/deploy-and-state.md	部署生命週期、cargo.state.json 語義、漂移/匯入/回滾、非同步建置。
型別化設定檔、cargo-ai cdk types、tsconfig 配置、工作流程主體中的 integrations.*	guides/typed-config.md	cdk types 產生的內容以及如何將其整合到專案中。
特定建構器的欄位/規格/輸出	references/resources.md	每個建構器 → 規格欄位 → 接受哪些參照 → 輸出。
確切的指令旗標	references/commands.md	每個 cargo-ai cdk 子指令及其旗標。
部署錯誤 / 陷阱	references/troubleshooting.md	已知的失敗模式和修復方法。

食譜 — 當有符合的食譜時，請逐步跟隨

食譜	使用時機…
recipes/scaffold-a-workspace.md	從頭開始建立新工作區（init --template full → types → plan → deploy）。
recipes/add-connector-and-model.md	新增資料來源 + 從中來源的模型，並透過控制代碼連接。
recipes/build-an-agent.md	組合模型 + 工具 + 代理（使用 uses / models / tools）並部署。
recipes/migrate-existing-workspace.md	透過 cdk import 將已上線的工作區納入 CDK 管理。
recipes/deploy-from-ci.md	從 CI 非互動式部署（使用 token 驗證 + 已提交的狀態）。

6) 關鍵規則

• 提交 cargo.state.json。 它是從程式碼到 Cargo 建立的資源的連結 — 也是已部署劇本或代理的唯一控制代碼（它們沒有 slug）。遺失它會導致這些資源孤立；使用 cargo-ai cdk import 恢復連結。它只記錄 {hash, uuid, outputs} — 從不記錄秘密值。在 gitignore 中忽略工作檔案（cdk init 會建立此設定）：

  .cargo-ai/
  cargo.state.lock
  cargo.state.bak.json
  cargo.state.audit.jsonl
  

• 秘密： 使用 secret("ENV_VAR")（通常是 secret("HUBSPOT_API_KEY")）來傳遞憑證。該值在部署時從環境變數讀取，不會包含在內容雜湊或狀態中，因此輪換 token 不會被視為漂移。在部署前匯出環境變數 — 缺少變數會導致部署失敗，並出現未解析的 ${ENV_VAR} 佔位符。
• 透過控制代碼連接，絕不使用 .uuid。 直接傳遞 define* 控制代碼（dataset: hubspot、tools: [enrich]），或對未在程式碼中定義的資源使用 xxRef("uuid")（connectorRef、modelRef、folderRef、toolRef、agentRef……）。如果參照需要每次呼叫的選項，則包裝為 { ref, …options }（例如 models: [{ ref: contacts, readOnly: true }]）。
• 在工作區整合變更後執行 cargo-ai cdk types — 它會重新產生 .cargo-ai/，使 defineConnector/defineModel 設定（以及工作流程主體中的 integrations.*）能針對真實架構進行型別檢查。型別檢查是額外好處，絕非必要條件：沒有它也能部署。
• 從專案根目錄執行 cdk 指令。 npx/cargo-ai 會從最近的 package.json 解析；在其他地方執行會導致 .cargo-ai/ 和 cargo.state.json 放在錯誤的目錄。使用 --dir <path> 來明確指定。
• 在 CI 中使用 --yes。 deploy 和 destroy 會提示確認；非互動式執行必須傳遞 --yes。
• 將 CDK 管理的資源路由到標籤明確的資料夾。 在每個建構器上設定 folder:，使 CDK 擁有的所有資源都放在專用資料夾中，其名稱向 UI 中的任何人表示「由程式碼擁有 — 請勿手動編輯」（手動 UI 編輯會在下次 plan 時被視為漂移）。資料夾是按類型區分的，因此為每種類型指定自己的資料夾，但共用一個簡短、可識別的前綴 — 建議：🔒 CDK（例如 🔒 CDK Models、🔒 CDK Agents）。保持名稱簡短（長標籤會在資料夾樹中截斷）；鎖頭表情符號是「請勿觸碰」的提示。請參閱 guides/authoring-resources.md。

先決條件

標準的 Cargo CLI 設定（安裝、登入、輸出慣例）在所有技能中共享 — 請參閱 ../cargo/references/prerequisites.md。

兩個 CDK 特定的額外要求：

• 專案需要將 @cargo-ai/cdk 作為依賴項（用於匯入的 define* 建構器）。cargo-ai cdk init 會建立包含它的 package.json — 然後執行 npm install。
• cargo-ai cdk 領域隨 CLI 一起提供。 使用 cargo-ai cdk --help 確認；出現 unknown command 表示 CLI 版本太舊 — 執行 npm install -g @cargo-ai/cli@latest。

說明

• cargo-ai cdk --help 和 cargo-ai cdk <subcommand> --help 可查看即時旗標資訊。
• 當記錄的指令/旗標/回應與實際觀察不符時，請提交報告：cargo-ai workspaceManagement report create（請參閱 ../cargo-workspace-management/SKILL.md）。