Plugin SDK + Runtime 重構計畫
目標：每個訊息連接器都是使用同一穩定 API 的外掛（內建或外部）。
外掛不直接從 src/** 匯入。所有依賴透過 SDK 或 runtime。
為何現在
- 目前的連接器混合使用多種模式：直接核心匯入、dist-only 橋接、自訂輔助。
- 這讓升級變得脆弱，並阻礙乾淨的外部外掛介面。
目標架構（兩層）
1) Plugin SDK（編譯時、穩定、可發布）
範圍：型別、輔助函式和設定工具。無執行時狀態、無副作用。
內容（範例）：
- 型別：
ChannelPlugin、轉接器、ChannelMeta、ChannelCapabilities、ChannelDirectoryEntry。 - 設定輔助：
buildChannelConfigSchema、setAccountEnabledInConfigSection、deleteAccountFromConfigSection、applyAccountNameToChannelSection。 - 配對輔助：
PAIRING_APPROVED_MESSAGE、formatPairingApproveHint。 - 安裝引導輔助：
promptChannelAccessConfig、addWildcardAllowFrom、安裝引導型別。 - 工具參數輔助：
createActionGate、readStringParam、readNumberParam、readReactionParams、jsonResult。 - 文件連結輔助：
formatDocsLink。
發布：
- 以
openclaw/plugin-sdk發布（或從 core 匯出為openclaw/plugin-sdk）。 - Semver 搭配明確的穩定性保證。
2) Plugin Runtime（執行介面、注入）
範圍：所有觸及核心執行時行為的部分。
透過 OpenClawPluginApi.runtime 存取，外掛永不匯入 src/**。
提議的介面（最小但完整）：
export type PluginRuntime = {
channel: {
text: {
chunkMarkdownText(text: string, limit: number): string[];
resolveTextChunkLimit(cfg: OpenClawConfig, channel: string, accountId?: string): number;
hasControlCommand(text: string, cfg: OpenClawConfig): boolean;
};
// ... 省略完整介面定義
};
logging: {
shouldLogVerbose(): boolean;
getChildLogger(name: string): PluginLogger;
};
state: {
resolveStateDir(cfg: OpenClawConfig): string;
};
};說明：
- Runtime 是存取核心行為的唯一途徑。
- SDK 刻意精簡且穩定。
- 每個 runtime 方法對應一個既有的核心實作（無重複）。
遷移計畫（分階段、安全）
第 0 階段：鷹架
- 引入
openclaw/plugin-sdk。 - 在
OpenClawPluginApi中加入上述介面的api.runtime。 - 過渡期維持既有匯入（加上淘汰警告）。
第 1 階段：橋接清理（低風險）
- 以
api.runtime取代逐擴充套件的core-bridge.ts。 - 先遷移 BlueBubbles、Zalo、Zalo Personal（已很接近）。
- 移除重複的橋接程式碼。
第 2 階段：輕量直接匯入外掛
- 將 Matrix 遷移至 SDK + runtime。
- 驗證安裝引導、目錄、群組提及邏輯。
第 3 階段：重量直接匯入外掛
- 將 MS Teams 遷移（最大的 runtime 輔助集合）。
- 確保回覆/打字語義匹配現行行為。
第 4 階段：iMessage 外掛化
- 將 iMessage 移至
extensions/imessage。 - 以
api.runtime取代直接核心呼叫。 - 保持設定鍵、CLI 行為和文件不變。
第 5 階段：強制
- 新增 lint 規則 / CI 檢查：
extensions/**不匯入src/**。 - 新增外掛 SDK/版本相容檢查（runtime + SDK semver）。
相容性與版本
- SDK：semver、發布、記載變更。
- Runtime：每個 core 發布版本化。新增
api.runtime.version。 - 外掛宣告必要的 runtime 範圍（如
openclawRuntime: ">=2026.2.0"）。
測試策略
- 轉接器層級的單元測試（runtime 函式以真正的核心實作執行）。
- 逐外掛的黃金測試：確保無行為偏差（路由、配對、白名單、提及閘門）。
- 在 CI 中使用的單一端對端外掛範例（安裝 + 執行 + 冒煙）。
待決問題
- SDK 型別託管於何處：獨立套件或核心匯出？
- Runtime 型別發布：在 SDK 中（僅型別）或在 core 中？
- 如何為內建 vs 外部外掛公開文件連結？
- 過渡期是否允許 in-repo 外掛有限地直接匯入核心？
成功標準
- 所有頻道連接器都是使用 SDK + runtime 的外掛。
extensions/**不匯入src/**。- 新連接器範本僅依賴 SDK + runtime。
- 外部外掛可在不存取核心原始碼的情況下開發和更新。