前言¶
在 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
