Agnes AI 接入 wangyemen/agnes-ai-for-dsh

agnes-ai-for-dsh

DeepSeek Harness 的 Agnes AI 集成插件 ——提供 LLM 供应商接入（多模态）、图像/视频生成工具，以及设置面板。

功能

| 组成 | 说明 |
| 供应商 | agnes-ai，通过 llm-pi-ai 适配器接入（OpenAI 兼容 Chat Completions） |
| 对话模型 | agnes-2.5-flash、agnes-3.0-flash、agnes-2.5-pro、agnes-2.5-pro-beta，均支持图像输入 |
| 工具 | agnes_image_generation、agnes_video_generation、agnes_record_generation |
| 设置面板 | 在「设置」中新增 Agnes AI 分区：展示实时配置与模型目录，并可直接就地配置模型 —— 每个模型一个按钮，无需手改 cordis.patch.yml |

安装

dsh plugin install agnes-ai-for-dsh

或在 profile 的 package.json 中加入依赖后重新安装：

{
"dependencies": {
"agnes-ai-for-dsh": "git+https://github.com/wangyemen/agnes-ai-for-dsh.git"
}
}

然后把该 bundle 加入 dsh.profile.bundles，并重启 DSH。

配置

供应商已由 cordis.patch.yml 预声明，因此只需提供 API Key：

1. 打开 设置 → 模型。
2. 找到 Agnes AI，填入 API Key。
3. Key 由 DSH 凭据系统保存，引用名为 AGNES_AI_API_KEY。

默认使用中国站端点：

https://api.agnes-ai.cn/v1

如需国际站，把 baseURL 改为 https://apihub.agnes-ai.com/v1 —— 可在 cordis.patch.yml 中修改，也可直接在「设置 → 模型」里改。

模型配置

首次安装时，cordis.patch.yml 只声明下面四个模型，全部免费：

| 类别 | 模型 |
| 对话 | agnes-2.5-flash、agnes-3.0-flash |
| 图像 | agnes-image-2.5-flash |
| 视频 | agnes-video-2.5-flash |

模型目录里其余条目默认故意不配置 —— 两个付费 Pro 对话模型、上一代图像模型、付费视频模型。「设置 → Agnes AI」会列出每个模型的状态和对应按钮：

- 未加入配置 → 启用：把该模型写进 provider 的 models 数组；
- 已启用 → 取消配置：再把它移出去；
- 一键配置：当完全没有 provider 声明时出现，写入完整默认配置（上面四个模型）；
- 恢复默认：移除用户层数组，回落到 cordis.patch.yml。

写入走的是 ctx.remote.settings.mutate() —— 内置「模型」页面用的同一个 Remote 调用，并以面板上次读到的 revision 做并发保护。因此并发改动会返回 settings/conflict，面板提示重试，而不是静默丢弃两次写入中的一次。

三个需要知道的后果：

1. 写入落在设置的用户层，而用户层的 models 数组会整体替换 patch 层。点过第一次按钮之后，再改 cordis.patch.yml 就不会影响模型列表了，除非点「恢复默认」。
2. provider 能服务的只有语言模型。 图像和视频模型声明出来是为了让面板能跟踪它们、并让 id 可见；它们的条目只有 id 与 name，因为 models 条目（PiAiModelProfile）除 id 外没有必填字段。它们也会出现在模型选择器里，在那里被当作对话模型选中会失败 —— 它们只供 agnes_image_generation / agnes_video_generation 使用。
3. API Key 不是模型。 一键配置只写 provider 声明，凭据仍要在「设置 → 模型」里填写。

使用

启用后，模型即可调用两个媒体工具：

- agnes_image_generation —— 文生图、图生图、多图合成。参数： model、prompt、size（1K–4K）、可选 ratio、可选 image（输入图 URL）、可选 return_base64。
- agnes_video_generation —— 异步视频生成并自动轮询。参数： model、prompt，可选 seconds、mode、size、aspect_ratio 以及各模式专属的媒体字段。

视频为异步任务：工具先创建任务，再轮询 GET /agnesapi?video_id=…&model_name=… 直至完成。agnes-video-2.5-flash 仅支持 720P；agnes-video-2.5 支持 720P、1080P、1K、2K。

维护者须知

工具 schema

宿主的 defineTool 不接受原生 JSON Schema —— 它要求一种「属性表 DSL」，每个条目可自带 required: true，由它自己编译成 object 为根的 JSON Schema。

该 DSL 不是合法 JSON Schema。一旦未经转换就发给供应商，供应商会拒绝 整个请求（WorkBuddy 返回 HTTP 400，code 11129，「工具定义不合规」），于是该会话的每一次模型回复都失败，而不只是那一个工具。这不是假设： ESM 模块里的裸 require() 抛错被静默吞掉、由恒等 fallback 原样注册 DSL，就是这样发生的一次真实事故。

防线在 src/tools.ts：

- compileParameters() 在本插件内完成编译，正确性不依赖宿主 helper。
- assertValidCompiledSchema() / assertAllToolSchemas() 在加载时校验 编译后的形状，非法即抛错 —— 让错误在插件启动时暴露，而不是污染每个请求。
- 注册前会复查 defineTool 实际产出的参数，若原始 DSL 残留则拒绝注册。

verify.mjs 会用真实 defineTool 完整验证上述各点。

设置面板如何写配置

src/client/index.ts 通过生成的 Remote 命名空间 remote.settings 写入，不需要自己的专用通道：

writeSettings(NS, [{ op: 'set', path: ['providers', 'agnes-ai', 'models'], value: next }], revision)

remote.settings 一律经 ctx.reflect 获取、从不写进 inject，这样运行时缺少它时面板仍能渲染，缺少写入通道时也只报自己的拒绝，而不会让整个分区消失。

只有 unset 能恢复继承：空的 set 意味着「一条没有任何模型的路由」，而不是「用默认列表」。

按钮背后的纯函数（enableModelOps、disableModelOps、setProviderOp、 restoreModelsOp）由 bundle 导出，verify-client.mjs 用桩化的 __ModuleLoader__ 加载 bundle，直接验证这几个函数 —— 其中还包括一条交叉校验：cordis.patch.yml 与 DEFAULT_MODEL_IDS 必须声明同一组模型，防止 patch 与面板两边走偏。

模型条目用 maxTokens，不是 defaultMaxTokens

defaultMaxTokens 是provider 级的兜底值。写在 models 条目里属于未知字段，会被忽略，于是落到路由默认值 32768。单个模型的输出上限要写在它自己的 maxTokens 上。

构建

npm install
npm run build

lib/ 是提交进仓库的：本包从 git 安装，而消费方 profile 不会执行构建脚本。
改动 src/ 后务必先构建再提交，否则发布的是过期的 lib/。

验证

node verify.mjs # 编译后的工具 schema 对照真实 defineTool
node verify-apply.mjs # apply() 实际注册了什么
node verify-output.mjs # 每个工具返回值都是 lossless JSON
node verify-client.mjs # 面板的读与写路径，桩化 module table

许可证

MIT