前言¶
在 DSH（DeepSeek Harness）裏讓模型查賬號、Zone 或 DNS，常見做法是單獨維護 API Token，再把密鑰貼進對話或本地配置。Token 輪轉、權限範圍和「模型能不能看見密鑰」都要自己兜。社區插件 dsh-plugin-cloudflare（維護者 MFCJ45681，分類：聯網工具）走的是另一條路：設置頁完成 OAuth 2.0 授權碼 + PKCE 登錄，令牌用 AES-256-GCM 落在本機憑據庫，並向智能體暴露一組只讀的 cloudflare_* 工具。下面按安裝、首次連接和工具用法說明怎麼落地。
這是什麼¶
dsh-plugin-cloudflare 是面向 DSH Web 的 bundle 插件（package.json 中 dsh.client.platform 爲 web）。它做四件事：連接/斷開 Cloudflare、把令牌加密存到 ~/.dsh/cloudflare/vault.json、在設置頁提供 Cloudflare 分節、註冊 9 個只讀 cloudflare_* 工具供模型調用。項目開源協議爲 MIT，當前 npm 包版本爲 0.1.0，要求 Node.js >= 20。README 寫明已實現 OAuth、憑據庫、工具與設置頁；DNS 寫入、緩存清理、Workers/KV/R2/D1 等仍在 DESIGN.md 分期規劃中。
核心功能¶
| 能力 | 說明 |
|---|---|
| 登錄 | OAuth 2.0 授權碼流程，PKCE S256，state 雙校驗 |
| 憑據 | ~/.dsh/cloudflare/vault.json（AES-256-GCM）；主密鑰來自環境變量 CLOUDFLARE_PLUGIN_MASTER_KEY 或同目錄 master.key |
| 工具 | 9 個只讀工具：狀態、配置、授權、登出、賬號、zone、zone 詳情、DNS 記錄、能力清單 |
| UI | 設置頁 → Cloudflare 分節（狀態卡、連接參數、高級選項；跟隨宿主主題） |
工具統一返回信封 { ok, code, text, data, status, rateLimit }；失敗不拋異常，code 可區分 E_NOT_CONFIGURED、E_NOT_CONNECTED、E_INVALID_TOKEN、E_PERMISSION、E_RATE_LIMITED 等。
安全邊界（據 README）：令牌僅在宿主進程內使用，瀏覽器與工具返回值中不包含 token；界面路徑不存 client_secret；client_id 通過設置頁錄入而非工具參數（避免進入對話上下文）。HTTP 接口對方法、Content-Type、Origin、Host 等做了限制，反向代理場景可通過 allowedHosts 或 CLOUDFLARE_PLUGIN_ALLOWED_HOSTS 配置。
安裝與啓用¶
從 GitHub 安裝（README 推薦）：
dsh plugin --profile web add github:MFCJ45681/dsh-plugin-cloudflare
本地開發可用軟鏈：
dsh plugin --profile web add link:/path/to/dsh-plugin-cloudflare
也可手工把包放進 <profile>/node_modules/，並把包名寫入 <profile>/package.json 的 dsh.profile.bundles（bundles 爲加載開關，dependencies 中未聲明也可加載）。
裝完後需重啓 DSH Web（dsh web）纔會加載新 bundle。重啓後應看到：設置頁出現 Cloudflare 分節；模型側多出 9 個 cloudflare_* 工具。
第一次連接¶
默認不必先填 client_id：插件內置 private client，首次加載時加密寫入憑據庫，設置頁顯示打碼的 client_id 並標「內置」。裝完直接點 授權登錄 即可進入 Cloudflare 同意頁。
內置 client 僅所屬 Cloudflare 賬號成員能授權。若要用其他賬號，需在 Dashboard 自建 OAuth client（約 5 分鐘，一次即可）：
- Cloudflare Dashboard → Manage Account → OAuth clients → 新建；
- Response type =
code，grant =authorization_code（需自動續期可加refresh_token），token 認證選 none（PKCE）； - 回調地址與設置頁顯示完全一致，默認多爲
http://127.0.0.1:3080/plugins/cloudflare/callback（端口變化須兩邊同步）； - 設置 → Cloudflare → 高級 → 授權應用，填入自己的
client_id並保存（留空則繼續用內置）； - 點 授權登錄，選賬號並勾選權限。
「授權登錄」是普通鏈接 href="/plugins/cloudflare/start"，點擊跳轉，不易被彈窗攔截；從同意頁返回後設置頁會自動刷新。授權成功後狀態爲「已連接」，工具立即可用；access/refresh token 等加密寫在憑據庫，DSH 重啓仍有效，到期前會用 refresh token 續期。僅在設置頁登出、Cloudflare 後臺撤銷授權或 refresh 被拒時需重新授權。
典型用法¶
設置頁與 HTTP 接口¶
設置頁與工具共用一組 HTTP 路徑，例如：
GET /plugins/cloudflare/status 連接狀態（無敏感字段）
GET /plugins/cloudflare/bootstrap 狀態 + 能力 + 回調地址
POST /plugins/cloudflare/config 保存 client_id / 回調 / scope 等
GET /plugins/cloudflare/start 302 到 Cloudflare 授權頁
GET /plugins/cloudflare/callback 換碼、落盤
POST /plugins/cloudflare/logout 撤銷並刪除令牌
GET /plugins/cloudflare/accounts 賬號
GET /plugins/cloudflare/zones zone 列表
GET /plugins/cloudflare/scopes scope 目錄
模型側工具一覽¶
| 工具名 | 作用 |
|---|---|
cloudflare_auth_status |
連接狀態、賬號、scope、能力、憑據庫路徑 |
cloudflare_auth_setup |
保存公開的 client_id / 回調 / scope（不收 token 與 secret） |
cloudflare_auth_start |
生成 state + PKCE，返回授權鏈接 |
cloudflare_auth_logout |
撤銷並刪除本地令牌 |
cloudflare_accounts |
可見賬號與 id |
cloudflare_zones |
zone 列表，可按名過濾 |
cloudflare_zone |
單個 zone 詳情 |
cloudflare_dns_records |
某 zone 的 DNS 記錄，可按 type/name 過濾 |
cloudflare_capabilities |
將授權 scope 譯爲可讀能力說明 |
在對話中讓模型先調 cloudflare_auth_status 確認已連接，再按需查 cloudflare_zones、cloudflare_dns_records 等，即可在不暴露令牌明文的前提下做只讀排查。
本地體檢與環境變量¶
不聯網、不打印令牌的自檢：
node scripts/doctor.js
node scripts/doctor.js --json
憑據目錄默認爲 ~/.dsh/cloudflare，可覆蓋：
export CLOUDFLARE_PLUGIN_DATA_DIR=/some/dir
適用場景與注意¶
適合：已在 DSH Web 裏開發智能體、需要讓模型只讀查詢 Cloudflare 賬號、Zone、DNS，且希望用 OAuth + 本機加密庫管理令牌，而不是把 API Token 寫進 prompt 的團隊或個人。
注意：
- 插件以當前 DSH 進程權限運行，安裝前請自行審閱 GitHub 源碼 與 MIT 許可證。
- 當前版本工具均爲只讀；改 DNS、清緩存等寫操作未實現。
- 排錯可參考 README：回調
redirect_uri不一致、state 超時（約 10 分鐘）、同意頁無賬號（組織關閉了 OAuth）、E_PERMISSION（重新授權補 scope）、換機器後主密鑰丟失需重新授權。
DSH 生態強調「一切皆插件」；社區目錄站點 SkillHub 插件頁 爲獨立收錄，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-plugin-cloudflare 把 Cloudflare 登錄收進設置頁與 PKCE 流程，令牌落在 AES-256-GCM 憑據庫，並向模型提供 9 個只讀 cloudflare_* 工具，適合在 DSH 裏做基礎設施只讀問答與排查。安裝命令見上文；詳情與排錯表以倉庫 README 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/MFCJ45681/dsh-plugin-cloudflare
- GitHub：https://github.com/MFCJ45681/dsh-plugin-cloudflare
