DeepSeek Harness 接入 UCloud，不需要再写一套云 API 封装层。更稳妥的做法是：把 ucloud-cli 的 bundled skill 注册到 DSH，让 Agent 根据规则书调用官方 CLI，再由 CLI 访问 UCloud API。

这套方案解决的核心问题是：如何让 AI Agent 操作真实云资源，同时避免插件层接触密钥、重复维护 API 客户端，并把执行边界控制在可审计的规则内。

一、场景背景：云厂商接入 Agent 时最容易踩的三个坑

云厂商或企业内部平台接入 DeepSeek Harness 这类 Agent 框架时，常见方案通常有两类：

1. 二次封装 SDK / API Client
   把常用云资源操作封装成工具，例如创建云主机、绑定 EIP、配置安全组等。

2. 直接把 OpenAPI 文档交给模型
   让模型根据接口文档自行构造请求、调用 API。

这两类方案各有问题。

方案	优点	主要风险
二次封装 SDK / API Client	工具边界明确，调用体验好	插件层可能接触密钥；新产品、新接口需要持续适配；鉴权、参数映射和错误处理维护成本高
直接使用 OpenAPI 文档	覆盖面广，理论上能调用更多接口	调用顺序、错误修复、停止条件容易交给模型自行判断，执行边界不稳定

UCloud 采用的是第三种方式：规则搬家。

也就是不在 DeepSeek Harness 插件里重新实现 UCloud API Client，也不做一个受限命令包装器，而是把随 ucloud-cli 发布的 skill 规则书注册到 DSH。Agent 负责按规则理解用户意图、查帮助、查文档、调用 CLI；真实鉴权和 API 访问仍由官方 CLI 完成。

User request
           → bundled ucloud-cli skill
           → DSH Bash tool
           → official ucloud CLI
           → UCloud API

在 DSH 官方插件目录 DSH HUB（dshhub.org）中搜索 ucloud，只返回一个插件：@ucloud-ai/ucloud-dsh-plugin。入口非常集中，说明能力不是拆成一堆零散工具，而是收束到一套 skill 规则中。

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

README 中对边界的定义很明确：

“It registers the complete bundled skill and its references; it does not implement a second UCloud API client or a restricted command wrapper.”

也就是说，这个插件注册的是完整 bundled skill 及其 references，不实现第二套 UCloud API 客户端，也不实现受限命令包装器。

二、技术方案：插件只注册 Skill，执行交给官方 CLI

2.1 仓库结构：skill/ 才是行为核心

ucloud-dsh-plugin 的结构非常克制：

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

其中：

• lib/ 和 src/：负责 Cordis 插件注册，把 skill 挂进 DSH 的 skill 池；
• skill/：定义 Agent 如何理解 UCloud 任务、如何查 CLI、如何回退文档、如何处理错误；
• test/：只验证 Skill 注册、打包引用文件和 bundle metadata，不访问真实云账号。

测试边界也写得很清楚：

“Tests only validate Skill registration, packaged references, and bundle metadata. They do not execute ucloud or access a UCloud account.”

这意味着插件的职责不是替代官方 CLI 做云端正确性验证，而是把规则安全、完整地注册进 DSH。真实资源操作由官方 CLI 和 UCloud API 负责。

2.2 SKILL.md：写给 Agent 的工作守则

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

SKILL.md 的 frontmatter description 用来告诉 DSH：什么情况下应该触发这个 skill。

触发条件并不局限于用户明确说出某个云产品名。当用户表达以下意图时，都可能触发 UCloud skill：

• 部署 Web 应用；
• 发布站点；
• 绑定 EIP；
• 准备云主机；
• 把服务跑到云上。

这样用户不需要说“调用 ucloud 插件”，只要表达“把服务部署起来”，DSH 就有机会选择这个 skill。

2.3 执行顺序：先查 help，再查文档，最后才兜底 OpenAPI

references/cli-usage.md 把 Agent 的执行顺序拆成三步：

1. 优先查看本地 CLI help
   先通过 ucloud --help 或具体子命令 --help 判断命令结构、参数名和可用选项。

2. 再查 CLI 文档和产品文档
   当本地 help 不足以判断时，再参考 CLI 文档与产品文档。

3. 仍不明确时，查询 doc-sources.md 索引的官方 API 文档
   ucloud api 这类直接调用 OpenAPI 的方式是兜底路径，不是默认路径。

这个顺序很重要。它避免模型一上来就自己拼 API 请求，也避免在参数不确定时盲目执行。

2.4 鉴权边界：插件不读取、不保存、不打印密钥

安全规则中有一条非常关键：

“不要将 UCLOUD_PUBLIC_KEY 或 UCLOUD_PRIVATE_KEY 直接放入命令字符串、CLI flag、日志、计划或面向用户的摘要中。”

因此：

• 插件不读取 UCloud 密钥；
• 插件不保存 UCloud 密钥；
• Agent 不应该把密钥写入命令字符串；
• 密钥不应该出现在日志、计划、摘要或对话输出中。

README 中也给出了责任边界：

“The package does not read or manage UCloud credentials. Authentication remains the responsibility of the official CLI and its existing profile/OAuth state.”

也就是说，认证仍然由官方 CLI 的 profile / OAuth 状态负责。插件层只注册规则，不接管凭据。

三、核心指标：从文件规模看规则设计重点

这套方案最值得关注的不是代码量，而是规则文件的分布。

3.1 products/ 只显式覆盖少量基础产品

skill/references/products/ 下只有三个产品规则文件：

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

$ ls skill/references/products/
       eip.md       # 435 字节
       security.md  # 296 字节
       uhost.md     # 915 字节

三个文件合计约 1.6KB，主要覆盖云主机、公网 IP 和安全规则这类基础资源。

文件	规则重点	作用
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 的默认登录用户。

▲ uhost.md 全文 915 字节，products/ 目录的内容非常克制

3.2 其他产品能力依赖 CLI 回退和官方文档

products/ 只有三个文件，并不等于只支持三个产品方向。

更准确的理解是：

• products/ 只写少量高频、容易混淆、需要统一行为的规则；
• 当 CLI 子命令不存在或能力不足时，工作流允许回退到 ucloud api --local-file；
• 回退前需要先到 UCloudDoc-Team/api 仓库查找对应接口文档。

因此，能力覆盖不是靠在 products/ 下写满所有产品规则，而是靠官方 CLI、API 文档和规则化回退机制共同完成。

3.3 error-handling.md 是可控性的关键文件

error-handling.md 约 15K 字符，是 references 中体量最大的文件，也是工程实践价值最高的部分。

它开头给出了五条基本原则：

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

这些规则把 Agent 的错误处理边界写清楚了：不是所有失败都重试，也不是所有错误都交给用户，而是在“可安全修复”和“必须停止”之间做明确区分。

文件中还覆盖了多类真实云资源操作中常见的问题，例如：

• 缺失 ProjectId 时如何补齐；
• 如何通过 ListRegions 解析公共参数；
• 计费方式按“按小时预付 → 按小时后付 → 按月预付”的顺序回退；
• 根据镜像发行版反推默认登录用户名。

其中，针对 299 IAM permission error 的处理逻辑尤其关键。

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

这个决策树能减少误报。只有补齐 ProjectId 后仍然报 299，才更可能是真实权限不足。否则，很多“权限错误”其实可能是公共参数缺失导致的。

四、优刻得相关能力：把三层责任拆开

这套接入方式的核心不是“插件能写多少代码”，而是把责任拆到正确的位置。

层级	负责内容	说明
DeepSeek Harness 插件	注册 skill、分发 references	插件是薄壳，不重新实现 API Client
skill/references	行为规则、产品映射、错误处理、安全边界	Agent 按规则查 help、查文档、调用 CLI、处理错误
ucloud-cli	鉴权、命令执行、访问 UCloud API	凭据留在官方 CLI profile / OAuth 状态中

和传统薄封装方案相比，差异很明显：

维度	薄封装路线	规则搬家路线
鉴权责任	密钥往往要经过插件层	密钥留在官方 CLI，插件不碰凭据
能力跟版	新产品、新接口通常需要插件发版	继续维护 CLI 和规则文件，能力可复用
可控性	能力写死在代码里	规则写在文本里，可审计、可 Fork、可裁剪
错误处理	依赖封装代码实现	错误诊断、修复、停止条件写进 references

zhun.ai 将 ucloud-dsh-plugin 标为“真实资源操作”，也说明它不是单纯的演示壳，而是面向真实资源、真实权限和真实执行路径的插件。

五、适用 / 不适用场景

适用场景

这套方案适合以下情况：

1. 希望 Agent 使用官方 CLI，而不是重新实现云 API 客户端
   已有 CLI 能力可以继续复用，减少重复开发。

2. 不希望插件层接触密钥
   凭据仍由官方 CLI 的 profile / OAuth 状态管理，插件不读取、不保存密钥。

3. 希望云产品能力跟随官方 CLI 演进
   新接口、新产品优先通过 CLI 和 API 文档承接，而不是每次都改插件代码。

4. 需要可审计、可裁剪、可 Fork 的规则层
   文本规则比黑盒封装更容易审查和调整。

5. 希望 Agent 在真实执行前有明确的查询、诊断和停止规则
   例如先查 help、再查文档、无法明确诊断时不盲目重试。

不适用场景

以下情况不太适合直接采用这种方式：

1. 没有稳定的官方 CLI
   如果 CLI 本身能力不足、参数不稳定或文档缺失，规则搬家效果会受限。

2. 需要在插件层实现强约束的审批流
   例如所有创建、删除、变更操作必须经过企业内部审批系统，此时还需要额外控制层。

3. 希望完全屏蔽命令行细节
   如果目标是把所有云操作抽象成固定 GUI / API 工具，规则书 + CLI 的方式可能不够产品化。

4. 要求离线完成全部参数推理
   这套方案依赖 CLI help、产品文档和 API 文档，完全离线环境下需要提前同步文档和规则。

六、FAQ

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

直接交给模型会让调用顺序、错误修复和停止条件变得不稳定。规则书方式先规定查 help、查文档、回退 OpenAPI、错误诊断、自动修复和停止边界，再把执行交给官方 CLI。

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

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

Q3：Agent 可以把密钥写到命令里吗？

不可以。UCLOUD_PUBLIC_KEY 和 UCLOUD_PRIVATE_KEY 不应出现在命令字符串、CLI flag、日志、计划或面向用户的摘要中。

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

不能简单这样理解。products/ 只承载少量显式规则，例如 UHost、EIP、安全组等基础规则。更多产品能力通过官方 CLI、ucloud api --local-file 回退路径和官方 API 文档完成。

Q5：为什么测试只验证注册，不直接访问云账号？

因为插件职责是把 skill 和 references 正确注册到 DSH，不是替代官方 CLI 做云端验证。真实云资源操作的正确性由 ucloud-cli 和 UCloud API 共同保证。

Q6：299 IAM permission error 应该怎么处理？

先判断请求是否缺少 ProjectId。如果接口要求 ProjectId 且请求未携带，先补齐后重试；如果已携带 ProjectId 仍然报 299，再判断为真实权限问题并提示用户补权限。

Q7：这种方式和二次封装最大的区别是什么？

二次封装通常把能力写进插件代码，可能需要处理鉴权、参数映射和接口升级。规则搬家方式把鉴权和执行留给官方 CLI，把 Agent 行为约束写进 skill/references，插件本身只负责注册和分发。

七、参考链接

• DSH HUB：https://dshhub.org
• UCloud DSH Plugin：@ucloud-ai/ucloud-dsh-plugin
• UCloud API 文档索引：UCloudDoc-Team/api
• ucloud-cli：用于认证、命令执行和访问 UCloud API

结论

UCloud 接入 DeepSeek Harness 的工程价值在于责任拆分清晰：插件不重新实现 API Client，不接管密钥；Agent 根据 skill/references 执行查询、诊断、修复和停止；真实认证和云资源操作仍由官方 ucloud-cli 完成。

对于已经具备成熟 CLI 的云平台或内部平台，这种“规则搬家”比“二次封装”更轻，也更容易审计和维护。关键不是多写一层代码，而是把行为规则、安全边界和错误处理写清楚，让 Agent 沿着官方工具链稳定执行。