指南OneMux

Cline 上線實務:設定工作階段並安全復原

實用指南:設定 ClineCore 工作階段、將執行階段設定與供應商設定分開,並設計安全的重試與復原規則。

AI

摘要 · TL;DR

ClineCore 將執行階段選項(例如後端模式、功能、工具政策與自動化)和各工作階段所設定的供應商與模型分開。本指南說明如何明確區分這些設定,並以工作階段 ID 和持久化狀態為基礎設計復原機制,而非盲目重複執行工作。

重點

  • 將執行階段、工具權限,以及供應商/模型設定視為彼此獨立的決策。
  • 重試前,先利用工作階段 ID 和持久化訊息調查故障。
  • 重試可能造成副作用重複發生;請依工作流程定義檢查點與復原規則。
  • API 參考文件說明工作階段操作,但未規定重試語意、檢查點格式或供應商相容性保證。
文章目錄 (9)

ClineCore 可讓應用程式控制工作階段建立、執行階段選擇、工具權限與工作階段歷史記錄。若要在正式環境中執行工作流程,關鍵的設計決策不只是要不要重試失敗的呼叫,而是如何在再次執行工作前,確認先前已經發生了什麼事。

以下設定僅供說明,並非經過測試的部署配方。ClineCore API 參考文件說明了本文討論的選項與方法;確切的型別與行為,請參閱您安裝的 SDK 版本。

將執行階段設定與模型設定分開

實用的設定邊界可分為三部分:

  • **執行階段:**後端選擇、用戶端識別,以及選用的遠端或 hub 連線設定。
  • **執行政策:**工具政策、功能,以及是否啟用自動化 API。
  • **工作階段模型設定:**特定工作階段的供應商 ID、模型 ID、憑證、工作區路徑與工具可用性。

如此一來,即使更換模型,也更容易獨立管理執行階段政策。但這不代表不同供應商的欄位可以互換:providerId、modelId 和 apiKey 仍須符合所選供應商的要求。API 參考文件並未保證與所有供應商或端點相容。

建立執行階段並啟動工作階段

事前準備:安裝您打算部署的 Cline SDK 版本,透過應用程式的密鑰管理方式提供憑證,並決定代理可以使用哪些工具。請勿將憑證放入日誌或工作階段中繼資料。

import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({
  clientName: "repo-maintenance-worker",
  backendMode: "auto",
  toolPolicies: {},
  automation: false,
})

const session = await cline.start({
  prompt: "Inspect the repository and report failing tests. Do not modify files.",
  source: "scheduled-check",
  interactive: false,
  sessionMetadata: { jobId: "job-123" },
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "Follow the task scope and report actions taken.",
    cwd: process.cwd(),
    workspaceRoot: process.cwd(),
    enableTools: true,
    enableSpawnAgent: false,
    enableAgentTeams: false,
  },
})

console.log(session.sessionId)

以上供應商與模型值取自 API 參考文件中的範例;這不代表我們推薦這些設定,也不代表範例以外的供應商相容性。參考文件列出 backendMode 的值為 auto、local、hub 和 remote,另有選用的 hub 與 remote 設定。文件並未說明哪種模式最適合特定部署環境。請審慎選擇,並在您的環境中驗證連線與權限。

空的 toolPolicies 物件並不等於安全政策。請依據已安裝 SDK 支援的政策型別,設定明確的預設政策和各工作階段政策。若用戶端提供工具執行器或核准回呼,請使用 capabilities,並測試受限操作是否確實遭到拒絕。

依據工作階段狀態制定重試規則

網路錯誤或工作者逾時,不代表代理一定在完成工作之前就已停止。重複提交原始提示,可能會重複執行編輯、外部呼叫或其他副作用。API 參考文件列出 get、readMessages、getAccumulatedUsage、abort、stop 和 restore,但未說明自動重試、恰好一次執行或檢查點內容。

較安全的作業流程如下:

  1. **立即記錄工作階段 ID。**將其與工作 ID 一起持久化,讓重新啟動的工作者能找到相同工作階段。
  2. **判斷故障類型。**區分已確認的終止性故障,以及無法確定工作是否完成的逾時或連線中斷。
  3. **重新提交前先檢查。**使用 get 和 readMessages 檢查工作階段中繼資料與持久化訊息。若有需要,可將累計用量視為作業上的線索,但不能據此證明某項操作已完成。
  4. **審慎選擇復原方式。**若工作階段仍在執行,請判斷要等待、呼叫 abort,還是呼叫 stop。若要繼續工作,send 可接受工作階段 ID 和後續提示。如果有可用且適用的檢查點,API 提供 restore;其必要輸入與語意請參閱 SDK 文件。
  5. **確保副作用可安全重複執行。**對代理工作階段狀態以外的操作,視情況使用應用程式層級的冪等鍵、去重機制或人工核准步驟。

避免以無條件重試迴圈包裝 start。如果初始請求可能已建立工作階段,但呼叫端未收到回應,再次呼叫 start 就可能建立另一項工作。API 參考文件未記載 start 的冪等鍵,因此請勿假設它具備此功能。

排解常見的正式環境故障

工作階段啟動時使用了錯誤的執行階段

記錄選取的後端模式,以及不含機密的工作階段識別資訊。確認 backendMode、hub 和 remote 選項符合工作者執行所在的環境。參考文件將這些列為執行階段選擇選項,但未說明自動容錯移轉行為;請確認您所用 SDK 版本中的 auto 實際行為,不要依賴未經確認的備援機制。

工具無法使用或權限意外開放

檢查工作階段的 config,以及適用的預設和工作階段層級 toolPolicies 或 capabilities。參考文件將這些設定描述為工具政策,以及由用戶端負責的執行器/核准控制。不過,提供的 API 摘要未說明政策優先順序;請確認已安裝 SDK 文件中的優先順序,並測試允許與拒絕兩種情況。

工作階段執行期間工作者失去連線

請將工作階段 ID 和工作 ID 保存在應用程式的持久化狀態中。重新啟動後,先檢查現有工作階段,再決定要透過 send 繼續、停止工作階段,或從檢查點還原。不要只因為沒有收到回應就推斷工作已完成。

供應商或模型設定失敗

請依據所選設定的供應商文件與 Cline 文件,驗證供應商 ID、模型 ID、憑證及任何端點需求。ClineCore 參考文件展示了一種供應商/模型設定格式,但不保證任意 OpenAI 相容端點或供應商專屬參數都能原封不動地使用。

正式環境檢查清單

  • 持久化儲存工作階段 ID,並避免在日誌和中繼資料中存放機密。
  • 明確設定工具權限,並測試核准與拒絕流程。
  • 區分操作失敗與操作結果不明的情況。
  • 重新提交工作前,先檢查工作階段歷史記錄。
  • 確保外部副作用具備冪等性,或在重播前要求核准。
  • 在實際部署環境中驗證後端與供應商的行為。
  • 依照 SDK 文件記載的生命週期,在正常關閉時釋放執行階段資源。

實務原則很簡單:先確認要重試的內容,再進行重試。ClineCore 提供工作階段與復原相關 API,但要在正式環境中安全運作,仍須仰賴應用程式持久化追蹤工作、妥善設計權限,以及處理重複副作用。

常見問題

ClineCore 哪些設定獨立於模型供應商?

執行階段選項(例如 `clientName`、`backendMode`、選用的 hub 或 remote 設定、capabilities、tool policies 和 automation)與工作階段的供應商及模型欄位彼此分開。各選項的確切行為,請以使用中的 SDK 版本為準。

ClineCore.start 逾時後,我應該重試嗎?

不要盲目重試。逾時無法說明工作階段是否已建立。請在取得工作階段 ID 時將其持久化,並在開始新工作前檢查現有工作階段。所提供的 API 參考文件未記載 `start` 的冪等鍵。

ClineCore 能否還原失敗的工作階段?

API 參考文件列出 `restore` 方法,但提供的摘要未說明其必要輸入或檢查點語意。請先參閱已安裝的 SDK 文件,再以此方法設計復原流程。

這項設定是否適用於任何 OpenAI 相容供應商?

引用的 ClineCore 參考文件並未證實這一點。供應商相容性和接受的參數取決於該端點與所選供應商設定是否有文件記載的支援;請先驗證,不要假設它們可以互換。

相關文章