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

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

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

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

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

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

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

▲ 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 就能把它选中。

▲ 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/ 之外的工作流

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

▲ 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 就能沿着官方路径稳定工作。