chaoliu615/dsh-agnes

dsh-agnes

基于 Cordis 的 DSH 插件（标准 bundle 包），为 DSH 会话提供 Agnes AI 的图像与视频生成工具，并在设置页提供「Agnes」标签页调整默认参数。

| | |
|---|---|
| 版本 | 0.6.0 |
| 许可证 | MIT |
| 运行环境 | Node.js ≥ 20 |
| 平台 | Host（Node.js）+ Web 客户端（浏览器设置页） |

功能

- 图像生成：agnes_image_generate 工具，通过 Agnes 图像 API 实现文生图、图生图（参考图）和多图合成。
- 视频生成：agnes_video_generate 工具，通过 Agnes 视频 API 实现文生视频、图生视频和关键帧动画（异步任务 + 轮询查询）；按模型名自适应 V2.0 与 Video 2.5 / 2.5-flash 两代参数体系。
- 设置面板：设置页出现「Agnes」标签页，模型以下拉选择（目录对齐官方文档的三个接入模型），切换模型时其余默认值自适应；修改保存后落盘到 ~/.dsh/settings.yaml，无需重启即对后续工具调用生效。

安装

本包是一个 dsh bundle：manifest 声明 dsh.bundle，内含 cordis.patch.yml 配置层。用 dsh plugin add 把它装进一个 profile 即可。三种方式任选：

从 npm 安装（推荐，无需构建授权）

dsh plugin --profile web add dsh-agnes

npm 上的包是预构建产物，安装即用。

从 GitHub 安装

dsh plugin --profile web add github:chaoliu615/dsh-agnes

git 安装拉取的是源码，pnpm 会在装完后运行本包的 prepare 脚本现场构建。pnpm ≥10 默认拒绝执行依赖的构建脚本，首次安装会被拦下；按提示把包键加入该 profile 的 pnpm-workspace.yaml 后重试：

allowBuilds:
dsh-agnes: true

注意：这是允许本包的代码在你机器上于安装时执行。建议锁定 commit（github:chaoliu615/dsh-agnes#）以免后续推送悄悄改变实际运行的代码。

从 tarball 安装

pnpm pack   # 仓库内执行，得到 dsh-agnes-x.y.z.tgz
dsh plugin --profile web add ./dsh-agnes-x.y.z.tgz

需要以下 peer 依赖（DSH 环境已内置）：

- @deepseek-ai/cordis
- @deepseek-ai/dsh-credentials
- @deepseek-ai/dsh-llm
- @deepseek-ai/dsh-settings
- @deepseek-ai/dsh-shell
- @deepseek-ai/dsh-tools

凭据

在 DSH 凭据中配置 AGNES_API_KEY，用于调用 Agnes API。可用来源：

- 启动环境变量；
- $DSH_HOME/.credentials.yaml；
- 项目 / user 级 .env；
- 设置页「Agnes」标签页保存。

密钥通过进程环境传递给 curl（请求体经 stdin 写入），均不会出现在命令行中。未配置密钥时工具会抛出带指引的错误，不会发起请求。

设置页：「Agnes」标签页

插件装载后，DSH 设置页会出现「Agnes」标签页（浏览器半侧由 lib/client.js 提供，经 /plugins/dsh-agnes/client.js 伺服）。

注意：Host 只在扫描到 dsh.client 声明时才把浏览器半侧编入启动图，且扫描结果在进程内缓存。给已安装的旧版本追加浏览器半侧后，需要重启一次 web profile（dsh web）才能让标签页出现；全新安装则无需额外操作。

模型是下拉选择，选项对齐 docs/agnes-ai/ 的三个接入模型（目录见 src/models.ts，与浏览器半侧保持一致）：

- 图像：agnes-image-2.1-flash（Agnes Image 2.1 Flash）
- 视频：agnes-video-v2.0（Agnes Video V2.0）、agnes-video-2.5-flash（Agnes Video 2.5 Flash）

默认配置自适应：切换模型时，依赖字段自动暂存为该模型的推荐默认值（视频统一为 16:9 · 1280×720 · 约 5 秒），表单形态也随参数体系切换——V2.0 显示画幅像素/帧数/帧率，2.5 Flash 切换为整秒时长并把分辨率档位锁定为 720P（flash 上游唯一支持档）；历史保存的其他档位在提交时由 Host 按 720P 收敛。自适应结果可继续微调后保存。

可调整的默认参数：

| 分组 | 字段 | 默认值 | 说明 |
|---|---|---|---|
| 图像 | 图像模型 | agnes-image-2.1-flash | 下拉选择；历史配置中的未知模型名会保留为「(当前)」选项 |
| 图像 | 默认尺寸档位 | 1K（1K · 日常生成） | 1K–4K；与比例组合的输出像素实时显示在页面上 |
| 图像 | 默认宽高比 | 1:1（方形） | 8 种比例均带场景标签（壁纸/头像/海报等） |
| 视频 | 视频模型 | agnes-video-v2.0 | 下拉选择；切换即自适应下方默认值与表单形态 |
| 视频 | 画幅与清晰度 | 16:9 · 横版 + 720p · 高清（提交 1280×720） | V2.0：预设映射到底层 width/height，API 再标准化到最近档；2.5 系列：提交 aspect_ratio + size（720P/960P/2K，flash 锁定 720P）。非预设组合自动显示「自定义…」精确像素输入 |
| 视频 | 视频时长 | V2.0：约 5 秒（121 帧）；2.5：5 秒 | V2.0 用官方推荐帧数预设 81/121/241/441 + 自定义（8n+1）；2.5 系列为整秒选择器（4–12） |
| 视频 | 帧率（V2.0） | 24 · 电影感 | 24/30 预设 + 自定义（1–60）；时长提示随帧率联动；2.5 系列隐藏该行 |
设置页 UI 只引用 DSH 官方主题令牌（Theme.listTokens 的别名集），派生色用 color-mix，根节点声明 color-scheme: light dark，明暗主题下原生控件与配色自动跟随，不携带浅色硬编码回退。文案内置中英双语字典。

配置落盘

设置页的修改经 settings scope 写入 DSH 用户设置文档，持久化到 ~/.dsh/settings.yaml 的 agnes: 段（DSH 标准设置文件；文件后端为原子写入）：

agnes:
imageModel: agnes-image-2.1-flash
defaultSize: 1K
defaultRatio: 1:1
videoModel: agnes-video-2.5-flash
videoWidth: 1280
videoHeight: 720
videoNumFrames: 121
videoFrameRate: 24
video25Seconds: 5
video25Size: 720P

只写用户改过的字段；未覆盖的字段回落到组装层 config 或 schema 默认值。设置保存经 revision 栅校验，非法取值（如帧数不满足 8n+1）会在保存时报错而不是静默生效。等价的持久化方式是在 profile 的插件行里写 config（组装层），或直接编辑该文件；设置页的「重置」会清除覆盖、回到组装值/默认值。

工具每次调用都读取设置的解析值，模型名与默认参数不硬编码在代码里——修改即时生效，无需重启。

目录之外的模型名

Host 端按非空字符串校验模型名：历史配置里的旧名称（如 agnes-video-2.5）与未来上游新 ID 仍可解码运行，只是不在下拉列表中（显示为「(当前)」）。要让新模型进入下拉目录，更新插件版本即可；运行时参数体系本就按模型名自适应（名字含 2.5 走秒数制，含 flash 收敛 720P）。

工具说明

agnes_image_generate

调用 Agnes 图像 API（POST /v1/images/generations，同步返回）。模型读自设置的图像模型名称。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prompt | string | ✅ | 生成/编辑指令。文生图 = 主体+场景+风格+光照+构图+质量；图生图 = 改变要求+新风格+保留元素；多图合成 = 每张参考图的角色+组合关系 |
| size | string | — | 尺寸档位：1K / 2K / 3K / 4K；不要传精确像素（会被标准化）；省略或非法时回退设置默认值 |
| ratio | string | — | 宽高比：1:1 3:4 4:3 16:9 9:16 2:3 3:2 21:9；省略时同上 |
| image | string[] | — | 参考图：公共 HTTPS URL 或 data:image/*;base64,… Data URI；多张即多图合成 |
| return_base64 | boolean | — | true 时返回 b64_json 而非 URL；大图可能超出捕获上限，优先用 URL |

输出值：created / url / b64_json / revised_prompt；渲染文本同时标注本次实际生效的模型与尺寸。

agnes_video_generate

调用 Agnes 视频 API，支持三种模式：文生视频（仅 prompt）、图生视频（image 单张公共 HTTPS 图片 URL）、关键帧动画（keyframes ≥2 张，帧间平滑过渡）；image 与 keyframes 互斥。模型读自设置的视频模型名称。

异步任务流程：

execute → POST /v1/videos 创建任务（取 video_id / task_id）
→ 每 5 秒 GET /agnesapi?video_id=…&model_name=… 轮询
→ completed：返回视频 URL；failed：返回 error 详情
→ 总预算 900 秒，超时会提示携带 video_id 稍后重查

双参数体系自适应（按设置中的模型名分发）：模型名含 2.5（如 agnes-video-2.5 / agnes-video-2.5-flash）时自动切换到秒数制 OpenAI Videos 兼容体系——

- seconds：整数秒 4–12（默认读设置 video25Seconds；显式传 num_frames/frame_rate 时按「帧数 ÷ 帧率」四舍五入并夹取）；
- size：720P/960P/2K（读设置 video25Size；flash 仅支持 720P，其他值自动收敛）；
- aspect_ratio：由设置的 width/height 就近匹配白名单（21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16）；
- 媒体映射：单张 image → keyframe 首帧；恰好两张 keyframes → keyframe 首尾帧；三张以上 → reference 的 images（flash 上限 5 张，超出报错）；
- 查询统一附带 model_name；width/height/num_frames/negative_prompt 等 2.5 不接受的字段不会提交。

主要参数（V2.0 系列）：width / height（正整数，API 会标准化到 480p/720p/1080p 档位）、num_frames（≤441 且遵循 8n+1 规则，24fps 下 81≈3s / 121≈5s / 241≈10s / 441≈18s）、frame_rate（1–60）、seed（固定可复现）、negative_prompt（仅 V2.0 生效）、num_inference_steps；省略几何/时长参数时使用设置默认值。

输出值：video_id / task_id / status / progress / seconds / size / url（顶层与 metadata.url 兼容）/ size_mapping / error。

开发

pnpm install        # 安装依赖（含 tsdown / typescript）
pnpm check          # tsc --noEmit 类型检查bash
pnpm build          # tsdown 构建产物到 lib/，并复制浏览器半侧到 lib/client.js
pnpm test           # 无依赖冒烟测试（服务端纯函数 + 客户端 bundle 注册/渲染）

冒烟测试模拟 window/document/React 运行，覆盖请求体构建（双参数体系、参数回退、flash 收敛）、assertConfig 校验、模型目录预设，以及客户端注册与各表单形态渲染。

目录结构：

├── src/                # TypeScript 源码（index/image/video/models）
├── client/client.js    # 浏览器半侧源码（手写的惰性 CJS 工厂最终格式）
├── scripts/            # 构建辅助（copy-client.mjs）与冒烟测试（smoke.mjs）
├── lib/                # 构建产物（git 内跟踪；npm 发布与运行时入口）
├── cordis.patch.yml    # dsh.bundle 配置层，按包名引用本包
├── tsdown.config.ts    # 构建配置（prepare 脚本复用，自包含）
└── docs/
├── user/           # DSH 插件开发文档（已入库）
└── agnes-ai/       # 上游模型 API 文档本地副本（被 .gitignore 忽略，仅本地参考）

产物入口（package.json exports）：. → lib/index.js（Host），./client → lib/client.js（Web）。

本地联调：先 pnpm build，再把本目录作为本地依赖装入 profile：
bash
dsh plugin --profile demo add /path/to/dsh-agnes
dsh --profile demo --dump-config   # 应能看到 "# == dsh-agnes" 层

发布到 npm：pnpm publish（publish 前自动触发 prepare 构建，files 白名单只带 lib/ 与 cordis.patch.yml）。

License

MIT