dsh-media-forge

Readme

# dsh-media-forge 媒体工坊

[English](#english) | 中文

DSH（[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)）插件：**agent + skills 工作流的生图 / 生视频 API 接入器**，带侧边栏管理面板。

把任意生图、图生图、生视频 API 的 Key 交给对话中的 Agent——它会自己调研该模型的调用方法、实测一条可用请求，然后把调用知识（含 API Key 与可选的提示词模板）沉淀为一条**可复用的技能（skill）**。之后你在侧边栏勾选技能，即可在当前对话中让 AI 直接按模板优化提示词并生成媒体。

## 功能

1. **技能自动沉淀**：用户把 API Key 发给 Agent，Agent 调研 API → 实测 → 调用 `media_forge_save_skill` 保存为技能。API Key 写入技能并存储在本地，下次会话直接复用，无需重新配置。
2. **模板化提示词生成**：技能里可以带「提示词模板」一节。生成时 AI 按模板优化出最终提示词再调用 `media_forge_generate_media`；用户直接给出提示词时也可以原样使用。支持文生图、图生图（编辑）、文生视频等任意 REST 生成 API。
3. **侧边栏技能面板**：插件在侧边栏底部（设置项上方）增加「媒体工坊」入口。面板中勾选本次对话要加载的生成技能，可同时勾选多个；选中的技能会注入 Agent 上下文供 AI 阅读。

> **安全提示**：API Key 会明文保存在本地技能文件（`$DSH_HOME/media-forge/skills.json`）中，插件 UI 底部有灰色小字常驻提醒。请勿分享技能文件或包含密钥的截图，以免泄露。

## 安装

需要 Node.js ≥ 22 与已安装的 `dsh` CLI。

```sh
# 方式一：本地目录安装
dsh plugin --profile my-profile add ./dsh-media-forge

# 方式二：tarball（无需授权构建脚本）
pnpm pack
dsh plugin --profile my-profile add ./dsh-media-forge-0.1.0.tgz
```

git 直装（`dsh plugin --profile my-profile add github:you/dsh-media-forge`）会拉取源码并通过 `prepare` 脚本构建，pnpm ≥ 10 需要在 profile 的 `pnpm-workspace.yaml` 里为该包授权 `allowBuilds`（详见上游[打包与安装教程](https://github.com/deepseek-ai/deepseek-harness)）。

启动 Web UI 即可看到侧边栏入口：

```sh
dsh --profile my-profile
```

## 使用方法

### 第一步：创建技能

在对话中把 API 信息交给 Agent，例如：

> 这是我的 SiliconFlow API Key：`sk-xxx`。帮我接入 Seedream 生图模型：先去查这个模型的 API 文档，实测一张图确认能用，然后保存成媒体工坊技能，技能里写上高质量生图的提示词模板。

Agent 会依次完成：搜索 API 文档 →（用 shell 等自有工具）实测一条请求 → 调用 `media_forge_save_skill` 保存。保存后的技能：

- 注册为一条运行时 agent skill，Agent 可按名字查阅；
- 其名称与描述同步到侧边栏面板；
- 若带有机器可读的 recipe（endpoint / headers / bodyTemplate / responsePath 等），后续可直接由 `media_forge_generate_media` 执行，无需再手写请求。

### 第二步：在侧边栏选择技能

点击侧边栏底部「媒体工坊」打开面板：

- 每行一个技能，点击即可勾选 / 取消，支持多选；
- 已选数量显示在面板标题与侧边栏入口角标上；
- 勾选的技能在下一条消息发出时注入当前对话（选择变化或技能被编辑后会自动刷新注入内容）；
- 面板底部灰色小字是 API Key 存储位置的常驻安全提醒。

### 第三步：生成

直接在对话中提需求即可，例如：

> 用 seedream 技能生成一张赛博朋克风格的猫，横构图。

> 我想要这张图的冬季版本（附图），用技能里的模板帮我优化提示词再生成。

Agent 会读取已注入的技能内容：有提示词模板时先按模板产出最终提示词，再调用 `media_forge_generate_media` 执行生成；产物默认保存到 `<会话目录>/media-forge/<技能名>-<时间戳>.<扩展名>`，也可以在请求里指定输出路径。

### 技能维护

对话中即可管理技能，无需手动编辑文件：

> 列出媒体工坊里的技能 / 删除 demo-image 这个技能 / 把 seedream 技能的提示词模板改成偏写实的风格再重新保存

## 提供给 Agent 的工具

| 工具 | 作用 |
| --- | --- |
| `media_forge_list_skills` | 列出已保存技能（名称、描述、是否可直接执行） |
| `media_forge_save_skill` | 保存 / 更新一条技能（markdown 正文 + 可选 machine-readable recipe） |
| `media_forge_delete_skill` | 按名称删除技能 |
| `media_forge_generate_media` | 按技能 recipe 执行生成：替换提示词占位符 → 请求 API → 提取媒体（URL / base64 / 二进制）→ 落盘 |

recipe 的 `bodyTemplate` 中所有 `{{PROMPT}}` 会被替换为 JSON 转义后的最终提示词（`endpoint` 中的 `{{PROMPT}}` 则做 URL 编码替换），`extraBody` 可在模板之上补充 size、seed 等参数。

## 存储

- 技能文件：`$DSH_HOME/media-forge/skills.json`（`DSH_HOME` 环境变量可重定向）
- 生成产物：默认 `<会话工作目录>/media-forge/`

## 开发

架构、构建与扩展方法见 [DEVELOPMENT.md](./DEVELOPMENT.md)。

## English

A DSH (deepseek-harness) plugin: an agent + skills workflow for media-generation APIs, with a sidebar panel. Hand an image/video generation API key to the agent; it researches the API, verifies a working request, and saves the knowledge (key + optional prompt template) as a reusable skill. Select saved skills in the sidebar to load them into the current conversation, then generate media with template-optimized or verbatim prompts via the `media_forge_generate_media` tool.

Note: API keys are stored in plain text in the local skill file (`$DSH_HOME/media-forge/skills.json`); do not share skill files or screenshots that may expose your key.