# UCloud 接入 DeepSeek Harness，为什么我更看好“规则搬家”而不是“二次封装”？

> 作者/来源: UCloud 运营管理员
> 发布时间: 2026-08-27T09:48:56.707Z
> 分类: AI专区
> 原文链接: http://117.50.162.249:3000/yun/articles/2761

---

先说结论：UCloud 接入 DeepSeek Harness，最值得看的不是“做了多少封装”，而是它把责任边界切得很清楚——插件只负责注册和分发规则，真正的执行交给官方 CLI，凭据也留在 CLI 里。对需要长期维护云能力的团队来说，这种做法比再造一层 API 客户端更稳。

## 一、先看业务背景：接入云能力时，团队最怕什么

我在评估这类方案时，通常先看两个问题：

- 插件层要不要碰密钥；
- 新产品、新接口上线后，谁来维护映射和错误处理。

传统薄封装的优点是上手快，但后期会把鉴权、参数映射、异常修复都压到插件里。直接把 OpenAPI 丢给模型也能跑，但执行顺序、回退逻辑和安全边界容易失控。

UCloud 在 DSH HUB 里的做法更克制：搜索 “ucloud”，只返回 1 个结果，@ucloud-ai/ucloud-dsh-plugin，入口非常集中。这个信号本身就说明，它不是铺开一堆工具，而是把能力收束到一套规则里。

![](https://ucloud-blog.cn-bj.ufileos.com/imagebed/0998212176103711-6f38bae239f6f00ba3a9d722fc635065.jpg)

▲ DSH 官方插件目录 http://dshhub.org 搜索「ucloud」只有 1 个结果，卡片标注 skills 分类，收录日期 2026-08-15

## 二、核心痛点：不是能不能用，而是后面会不会越来越难维护

这类接入最容易踩的坑有三个：

- 插件层自己管理密钥，权限边界会越来越复杂；
- 为了“更智能”再封一层客户端，后面接口变化就得跟着改；
- 让模型直接读文档发请求，容易把安全和执行顺序交给模型自己猜。

README 里的边界划得很明确：它注册的是完整 bundled skill 和 references，不实现第二套 UCloud API client，也不实现受限 command wrapper。换句话说，壳代码只是挂载，真正决定 Agent 行为的是 skill/。

## 三、我怎么判断这套方案：先看仓库结构，再看执行路径

仓库结构很克制，真正影响行为的部分都集中在 skill/：

```
<code class="language-text">ucloud-dsh-plugin/
├─ lib/ # cordis 插件壳
├─ src/ # <span>注册逻辑</span>
├─ skill/ # 规则书正本
│ ├─ SKILL.md # 227 行
│ └─ references/ # 7 个 md 配套
├─ test/ # 只验证注册，不调云
└─ README.md
</code>
```

这里最关键的一点是：test/ 只验证 Skill registration、packaged references 和 bundle metadata，不执行 ucloud，也不访问 UCloud 账号。这个测试范围说明得很直白——插件负责把规则安全挂进 DSH，云端正确性还是交给官方 CLI 和 UCloud API。

## 四、真正的行为核心，不在壳代码，而在规则书

SKILL.md 的触发条件写得很宽：当用户想部署 WEB 应用、发布站点、绑定 EIP、准备云主机等，即使没明确说出产品名，也可以触发。对使用者来说，这意味着不用刻意说“调用 ucloud 插件”，只要需求像“把服务跑起来”，DSH 就能把它选中。

![](https://ucloud-blog.cn-bj.ufileos.com/imagebed/0998212176103647-aa68cac154db63b73702d908474c17b4.jpg)

▲ SKILL.md 全文 227 行，frontmatter 里的 description 是触发它的关键依据

### 4.1 执行顺序不是直接调用，而是先查再执行

references/cli-usage.md 把顺序拆得很清楚：

- 先看本地 --help；
- 再查 CLI 文档和产品文档；
- 还不明确时，再去 doc-sources.md 索引的官方 API 文档。

ucloud api 这种直接调 OpenAPI 的方式被放在兜底位置，不是默认路径。这个设计会让很多操作先经历多轮查询，再进入真正执行，但好处也明显：流程更稳，边界更清楚。

### 4.2 安全规则的核心，是密钥不落字

规则里有一条很硬：不要把 UCLOUD_PUBLIC_KEY 或 UCLOUD_PRIVATE_KEY 直接放进命令字符串、CLI flag、日志、计划或面向用户的摘要中。

这意味着什么？

- 凭据留给官方 CLI 管；
- 执行交给 Bash 工具；
- Agent 只负责按规则办事。

README 里也把责任边界讲得很明确：它不读取也不管理 UCloud 凭据，认证仍由官方 CLI 的 profile/OAuth 状态负责。

## 五、为什么我更看重 products/ 之外的工作流

![](https://ucloud-blog.cn-bj.ufileos.com/imagebed/0998212176103510-f0f14b0a5f2717413e2a925e166fd3b7.jpg)

这里有个很诚实的边界：skill/references/products/ 里只有三个文件。

![](https://ucloud-blog.cn-bj.ufileos.com/imagebed/0998212176103484-c1d4fe2f3e9508667c3a983cccac5f3f.jpg)

▲ references/ 目录下的 products/ 子目录，只有 uhost / eip / security 三个 md

```
<code class="language-text">$ ls skill/references/products/
eip.md # 435 字节
security.md # 296 字节
uhost.md # 915 字节
</code>
```

三个文件加起来约 1.6KB，分别覆盖三类基础规则：

| 文件 | 规则重点 | 作用 |
|---|---|---|
| `uhost.md` | 命名归一、CloudInit 前提、默认登录用户 | 把 CVM/ECS/EC2/VM/云主机统一映射到 UHost |
| `eip.md` | 默认开 EIP | 支持公网的实例默认绑定 EIP，计费类创建前先提示 |
| `security.md` | 默认走安全组 | 同时支持安全组和防火墙时，优先安全组 |

uhost.md 里最关键的是命名统一：CVM、ECS、EC2、VM、云主机全部映射到 UHost，同时明确了 CloudInit 的前提，以及 Ubuntu、Debian、RedHat、Rocky 的默认登录用户。

这也解释了另一个问题：如果 products/ 只有三个文件，其他产品能力从哪来？答案不在这里，而在顶层工作流。遇到子命令不存在或能力不足时，会回退到 ucloud api --local-file，再先去 UCloudDoc-Team/api 仓库找对应接口文档。也就是说，其他产品更多依赖 CLI 回退和官方文档，而不是写死在规则文件里。

## 六、错误处理是这套方案里最有价值的部分

error-handling.md 体量最大，约 15K 字符，是整个 references 里最厚的文件。它的价值不在于“写得长”，而在于把失败后的动作顺序写得很明确：

- 调用失败时，先基于 help、API 定义、payload、已知默认值和最近的 lookup 结果诊断；
- 能安全且具体修复，就自动修复；
- 没有具体诊断，就不要盲目重试；
- 修不了，就停下来报告错误详情；
- 报告时给出用户下一步可以做什么。

里面还有很多实战里常见的修复示例，比如补缺失的 ProjectId、通过 ListRegions 解析公共参数、按“按小时预付 → 按小时后付 → 按月预付”的顺序回退、根据镜像发行版反推默认登录用户名。

最值得看的，是专门针对 299 IAM permission error 的决策树：

| 判断路径 | 处理方式 |
|---|---|
| 请求里缺 ProjectId，且接口要求 ProjectId | 先补 ProjectId，再重试 |
| 已带 ProjectId，但仍然报 299 | 进入真实权限错误判断 |
| 确认不是参数缺失 | 提示用户补权限 |

这套判断很实用。很多时候，加完 ProjectId 再报 299，才是真正的权限不足。这样能减少误报，也避免在错误路径上反复打扰用户。

## 七、为什么我会选这种方案，而不是薄封装

如果把两种路线放在一起看，差异很明显：

| 维度 | 薄封装路线 | 规则搬家路线 |
|---|---|---|
| 鉴权责任 | 密钥往往要经过插件层 | 密钥留在官方 CLI，插件不碰凭据 |
| 能力跟版 | 新产品、新接口都要插件发版 | 继续维护 CLI 即可，规则可复用 |
| 可控性 | 能力写死在代码里 | 规则写在文本里，可直接 Fork 和裁剪 |

我更认可后者的原因很简单：它把鉴权、能力演进和执行细节交给了更该负责的那一层。插件负责分发规则，CLI 负责执行，Agent 负责按规则调用。

## 八、实际使用建议

如果你也在做类似选型，我会给出这几个判断标准：

- 先确认插件层是否读取和管理密钥；
- 再看执行顺序是不是“先查文档，再执行，再兜底”；
- 看 products/ 只是基础规则，还是完整产品目录；
- 看失败后是盲目重试，还是能按规则诊断、修复和停止。

如果你的团队希望 Agent 使用官方 CLI 的能力，而不是重新实现一套云 API 客户端，这种方案会更合适。

## 九、适合 / 不适合场景

### 适合

- 希望 Agent 走官方 CLI 路径；
- 不想让插件层接触密钥；
- 希望后续能力演进尽量跟着厂商维护；
- 需要可审计、可裁剪、可 Fork 的规则层。

### 不适合

- 期望一个插件覆盖所有产品、所有接口，而且完全不用再看 CLI 文档；
- 依赖大量写死在 products/ 里的显式规则；
- 更倾向于代码级硬封装，而不是规则驱动的工作流。

## FAQ

### Q1：为什么不直接把 OpenAPI 文档交给模型？

因为这样做，执行边界和调用顺序容易失控。先把查文档、回退、修复和停止条件写清楚，再把执行交给官方 CLI，稳定性会更高。

### Q2：这个插件会管理 UCloud 凭据吗？

不会。认证仍由官方 CLI 负责，插件层不读取也不保存 UCLOUD_PUBLIC_KEY 或 UCLOUD_PRIVATE_KEY。

### Q3：products/ 只有三个文件，说明支持不完整吗？

不完全是。products/ 只承载少量显式规则，更多产品能力通过 CLI 回退和官方 API 文档完成。它更像规则入口，不像完整产品目录。

### Q4：为什么测试只验证注册，不直接打云？

因为插件的职责是把 skill 安全挂进 DSH，而不是替代官方 CLI 做云端验证。云端正确性由 CLI 和 UCloud API 共同保证。

## 总结

这套接入方式最有参考价值的地方，不在于“写了多少代码”，而在于“把哪一层责任留给谁”。UCloud 把鉴权和执行交给官方 CLI，把行为边界交给 skill 规则书，把插件本身压缩成一个负责注册和分发的壳。

对云厂商来说，这是一种很值得借鉴的接入思路：不一定非要再造一层封装，只要规则写对，Agent 就能沿着官方路径稳定工作。