dsh-agnes-omni

Readme

# dsh-agnes-omni

**Agnes 全模态插件** for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness)

免费接入 [Agnes AI](https://agnes-ai.com) 全模态模型，让 DSH 代理具备「看图 + 生图」能力，并打通「在对话里直接发图片」的链路。

## 功能

| 组件 | 说明 |
| --- | --- |
| `agnes_vision`（工具） | 视图/视觉功能：把图片交给 Agnes 全模态免费模型（`agnes-2.5-flash`）做图像理解，返回文字回答。适合看图、截图/图片 OCR、识别物体场景、分析图表界面。 |
| `agnes_image`（工具） | 文生图 / 图生图编辑：用 `agnes-image-2.1-flash` 按提示词生成图片（可传参考图做编辑），并把结果下载到会话工作区。 |
| 视觉桥（bridge） | ① 为模型路由声明 `image` 输入模态，让带图消息通过发送入口的检查；② 在 `agent/pre-step` 把用户消息里的图片块解码保存到 `工作区/.agnes/`，替换成带本地路径的文本标记，模型随即调用 `agnes_vision` 分析。支持图片的两种持久化形态（附件引用与内联 base64）。 |

> 原理：DeepSeek 等纯文本适配器会拒绝图片内容块（`UNSUPPORTED_CONTENT`），视觉桥在图片到达适配器之前把它转成「本地路径 + 调用 agnes_vision」的文本，因此对话里**粘贴/拖拽图片即可发送**，并自动获得 Agnes 的视觉分析。

## 安装

本插件是标准 DSH **bundle**，安装到某个 profile：

```sh
# 从 GitHub 安装
dsh plugin --profile <profile> add github:WUMU1111111/dsh-agnes-omni

# 或本地目录 / npm 包
dsh plugin --profile <profile> add ./dsh-agnes-omni
dsh plugin --profile <profile> add dsh-agnes-omni
```

若从 Git 安装且需要构建（本插件无构建步骤，一般无需），pnpm 可能要求先在 profile 的
`pnpm-workspace.yaml` 中 allowBuilds 该包，见[官方发布文档](https://github.com/deepseek-ai/deepseek-harness/blob/HEAD/docs/user/develop/basic/publish.md)。

卸载：`dsh plugin --profile <profile> remove dsh-agnes-omni`

## 配置密钥（重要：密钥不入库）

插件**不包含任何密钥**。每次调用通过 DSH 凭据服务解析 `AGNES_API_KEY`
（与 DeepSeek 官方适配器同一机制），按需从以下任一来源读取：

1. 编辑 `$DSH_HOME/.credentials.yaml`：

   ```yaml
   AGNES_API_KEY: sk-xxxxxxxxxxxxxxxxxxxx
   ```

2. 或在启动 DSH 的环境中导出同名变量：

   ```sh
   export AGNES_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx   # PowerShell: $env:AGNES_API_KEY="..."
   ```

> 获取密钥：[Agnes AI 官网](https://agnes-ai.com) 免费注册。改密钥只需改上面一处，无需动代码。
> `.credentials.yaml` 和 `.env` 均不应提交到任何仓库。

## 使用

- **看图**：在对话里粘贴/拖拽图片直接发送 → 代理自动用 `agnes_vision` 分析；也可直接给代理图片的本地路径或 URL。
- **生图**：对代理说「生成一张……的图」→ `agnes_image` 生成并保存到工作区。
- **图生图**：给参考图路径 + 说明要改什么。
- 提示词建议按 `[主体]+[场景]+[风格]+[光线]+[构图]+[质量]` 用英文描述，效果更稳定。

## 可选配置

桥的行配置 `targetProvider` 指定要声明 image 模态的路由（默认 `deepseek-official`）：

```yaml
- id: agnes-vision-bridge
  name: dsh-agnes-omni/bridge
  config:
    targetProvider: deepseek-official
```

## 安全说明

- 源码与 README 中**不含任何密钥**；所有请求的鉴权头来自运行时的凭据解析。
- 图片按内容哈希（sha256 前 16 位）落盘在会话工作区 `.agnes/` 下，同图只写一次。
- 主站不可达时自动回退国内节点 `api.agnes-ai.cn`。

## 仓库结构

```
dsh-agnes-omni/
├── package.json       # bundle 清单（dsh.bundle）
├── cordis.patch.yml   # 插件行（tools + bridge）
├── index.js           # agnes_vision + agnes_image 工具
├── bridge.js          # 模态补丁 + pre-step 视觉桥
└── README.md
```

## License

MIT