前言¶
在 DSH 里做智能体，常见做法是注册一堆模型工具，让 agent 直接调 API。图像、视频生成往往还要单独处理凭据、输出路径和异步轮询，和 harness 的设置页、会话工作区也对不齐。下面介绍社区插件 dsh-agnes（维护者 Lennon-lylt）：把 Agnes 的生成能力接到 DSH 上，用设置页管配置和 API Key，用 bundled skill + 独立 CLI 执行生成，agent 通过 shell 跑命令完成调用，而不是在宿主侧注册模型工具。
这是什么¶
dsh-agnes 是 DeepSeek Harness 的「模型推理」类插件，一句话定位：Agnes AI 图像 / 视频生成 —— 设置页负责配置，真正的调用走一个 bundled skill。
- 仓库：github.com/Lennon-lylt/dsh-agnes
- 社区目录：skillhub.cn/plugins/Lennon-lylt/dsh-agnes
- 当前包版本（资料中的
package.json）：0.6.1，面向 DSH 0.2.x 线；registry 上的dsh-agnes@0.6.0面向 0.1.x，README 明确建议不要在市场里对旧包点升级，以免与 0.2.x 不兼容。 - 许可证：MIT；Node >= 20。
Host 半边注册 agnes 设置命名空间、配置/凭据两条同源路由，以及 bundled skill（skills/agnes/SKILL.md，其中的 {{CLI}} 会替换成安装目录下 CLI 的绝对路径）。不注册任何模型工具 —— 能力在 skill 里，由 agent 用 shell 执行 lib/cli.mjs。
核心功能¶
设置页与配置存储¶
Client 半边在 settings.section 注册 设置 → Agnes，可配置 API Key、模型、尺寸、输出目录、轮询参数等。页面按顺序探测传输：ctx.remote.settings → settingsScope（0.1.x）→ 宿主半边路由 /api/dsh-agnes.settings（配置）与 /api/dsh-agnes.credential（凭据）。在 DSH 0.2.0-rc.2 的 Web 客户端里，前两条对插件上下文常为 undefined，实际多走第三条同源 /api 通道。
配置落在插件自有文件：<DSH_HOME>/storages/agnes/config.json，结构为 { version, revision, values }。读取优先级：内置默认值 → DSH 设置命名空间（较低）→ 该文件（最高）。页面 POST 写入时带 revision 做冲突检测；手工改文件后宿主按 mtime 重读。
API Key 的存放与 CLI 读取顺序¶
权威来源是 DSH 凭据存储；保存时宿主会镜像到 <DSH_HOME>/storages/agnes/api-key（0600），供独立 CLI 进程读取。环境变量 AGNES_API_KEY 优先级最高。CLI 取用顺序：环境变量 → Key 文件（CLI 读不到 DSH 凭据存储）。
执行体：纯 Node CLI¶
lib/cli.mjs 是无 Cordis、无 DSH ctx 的纯 Node 进程，读同一份设置与 Key 文件，复用 lib/agnes-api.mjs。stdout 只输出一个 JSON 对象（过程信息走 stderr）：成功 { ok: true, files|task }，失败 { ok: false, error, kind, hint } 且退出码 1。
产物会立即从 Agnes 返回的 URL 下载落盘（URL 会过期，不作为交付物）。落盘顺序：
--out → 设置里的输出目录 → <当前工作目录>/agnes-output/<日期>/ → <DSH_HOME>/agnes-output/<日期>/；回退时结果里 fellBack: true。
Skill 与 agent 侧用法¶
安装并在设置页填好 API Key 后，skill 已挂在 skill 目录；agent 需要时读取 SKILL.md 并执行 CLI。README 中的示例如下（路径中的 <插件目录> 在安装时会被替换成真实绝对路径）：
node "<插件目录>\lib\cli.mjs" image --prompt "雨夜霓虹下的古镇，国风插画" --size 2K --aspect 16:9
node "<插件目录>\lib\cli.mjs" image --prompt "改成线稿风格" --images .\photo.png
node "<插件目录>\lib\cli.mjs" video --prompt "无人机掠过雪山" --size 720P --wait=180000
node "<插件目录>\lib\cli.mjs" task list
node "<插件目录>\lib\cli.mjs" models
node "<插件目录>\lib\cli.mjs" config
子命令还包括 task status/wait/cancel --id <taskId> 等，详见仓库 README。
与 Agnes API 行为相关的实现取舍（资料中的实测摘要）¶
以下来自插件 README 记载的 2026-10 实测，用于理解 CLI/skill 的设计，而非第三方 SLA：
| 能力 | 说明 |
|---|---|
| 文生图 | POST /v1/images/generations，默认多返回 URL；支持像素对与 2K/4K + aspect_ratio |
| 图生图 | 图片端点接受 base64 data URI 作为 image 输入 |
| 文生视频 | POST /v1/videos 异步；轮询 GET /agnesapi?video_id=..&model_name=.. |
| 视频首帧 | 视频 image 只接受公网 URL；data URI 会被静默丢弃 —— 插件侧若要用本地图作首帧，需先经图生图等方式换取公网 URL |
安装与启用¶
请用 DSH 安装器，不要手工把包目录拷进 profiles/<profile>/node_modules（会导致 profile 不一致，harness 无法启动）。官方 README 给出的命令如下：
dsh plugin --profile web add dsh-agnes
若从本地目录安装：
dsh plugin --profile web add file:D:\path\to\dsh-agnes
装好后重启 DSH 让 profile 重新组合，打开 设置 → Agnes 填入 API Key。桌面端热装载对宿主半边即时生效；浏览器里已加载的旧客户端包需 刷新页面（F5） 后新设置页才生效。
本地目录安装前：若开发自检建过指向 profile node_modules 的 junction，安装前须删掉该 node_modules 链接，否则安装器整树复制可能 ENOENT（README 有具体错误样例与 cmd /c rmdir 示例）。
卸载或回滚应使用安装器或市场 UI；手工残留需同时清理目录与 profile manifest 声明。
典型用法流程¶
- 按上一节安装插件并重启 DSH，在 设置 → Agnes 配置 API Key 与模型、输出目录等。
- 在 agent 会话中，由模型根据 bundled skill 在 shell 里调用
cli.mjs（例如文生图、图生图、文生视频及task wait）。 - 在会话工作区或配置的输出目录查看
agnes-output/<日期>/下的文件；需要排查时用node .../cli.mjs config查看解析后的配置（不含密钥）。
开发者可在仓库内运行 README 列出的自检脚本（如 scripts/selfcheck.mjs、scripts/client-page.check.mjs、带 AGNES_API_KEY 的 scripts/smoke.mjs），安装前建议至少跑 schema 自检。
适用场景与注意¶
适合谁：已在 DSH 0.2.x 上使用 Web profile、希望 agent 通过 skill + CLI 调用 Agnes 做图像/视频生成，并希望在 harness 设置页统一管理 Key 与默认模型的开发者。
权限与安全：插件与 CLI 以当前 DSH 进程及 agent shell 的权限运行；API Key 会写入 DSH 凭据存储，并可能镜像到本地 Key 文件。安装前应阅读源码与 MIT 许可证，自行评估是否接受明文 Key 文件或改用 AGNES_API_KEY 环境变量。
生态说明：DSH 社区插件目录（如 SkillHub）是独立站点，与 DeepSeek / 幻方无官方从属关系；本文事实来自 GitHub README 与提供的 package 元数据。
排错提示：若设置页提示无可用设置传输，可展开探测报告，查看 /api/dsh-agnes.settings 是否为非 JSON（常见于宿主半边未装载或路由未注册）；页面带错误边界，避免白屏。更多对照表见仓库 README「设置页排错」一节。
结尾¶
dsh-agnes 把 Agnes 生成能力拆成「DSH 内配置 + skill 引导的 CLI 执行」，适配 0.2.x 的设置与 /api 路由，并处理输出落盘与视频首帧 URL 等 API 细节。进一步了解可访问 社区目录页 与 GitHub 仓库。
