# 架构说明

[English](./architecture.md)

> 本说明基于对 DSH 0.1.0-rc.6 宿主 API 的直接检查，相关集成假设由 `tests/api-assumptions.spec.ts` 覆盖。当前设计为 V2 薄路由。

## 总览

插件是构建在 DSH 原生 `llm` 注册表之上的策略层：

```text
DSH「模型」设置页
  └─ 提供方 / 凭据 / 模型目录 / 模态 / 推理强度 / 重试
                  │
                  ▼
          ctx.llm 官方注册表
                  │
       ┌──────────┴──────────┐
       ▼                     ▼
模型路由薄策略层          DSH 正常模型调用
关键词规则 / 受控工具
会话 request/header 写入

媒体通道（插件独立命名空间）
  └─ image_gen；视频、音频和 3D 只保留扩展方向，尚未实现
```

- **DSH 管模型，插件管策略。** 插件不注册 `mr:<id>` 文字路由，不复制 OpenAI 兼容文字适配器、模型发现、默认模型或重试机制。
- **未命中不改动。** 只有规则命中并通过精确校验后，才写入会话模型头；V1 的强制 fallback 已删除。
- **在子代理边界修复模型选择。** 子代理不会经过 api-proxy 的主会话 `installSelection`。关键词命中并通过精确校验后，插件只对 `origin: subagent` 延迟安装 DSH 官方模型选择流水线，使第一次请求就采用目标模型。安装按 Agent 幂等，插件卸载时清理，不干预主会话。
- **媒体通道隔离。** `mediaProviders` 不进入文字模型注册表，`image_gen` 仍为 Beta。
- **凭据传输明确。** 媒体端点除本机回环开发地址外必须使用 HTTPS。凭据留空时不发送 Authorization；端点 URL 不允许内嵌凭据、查询参数或锚点。

## 已验证的宿主 API 事实

1. **提供方注册：** 服务名为 `llm`；`listProviders()` 和 `listConfigurableProviders()` 读取实时目录，`llm/adapters-updated` 不带参数。
2. **精确校验：** 使用 `resolveModelInfo(provider, model, signal)` 和 `resolveCallConfig(...)`；`listModels()` 只是建议目录，不能作为有效性的最终依据。
3. **会话模型写入：** 向 `agent.session` 追加 `request/header` 是持久的模型选择写入通道，助手来源会记录 provider 和 model。
4. **默认模型：** 读取 `ctx.agentDefaultModel.currentSelection()`，本插件不写入默认模型。
5. **工具：** 使用 `ctx.tools.register(ToolDefinition)`；执行时可获得 `exec.agent`。
6. **设置：** 使用 `ctx.settings.register`、`describe()` 和 `replace()`；修订号冲突由 `SettingsConflictError` 防止旧页面覆盖新设置。
7. **凭据：** 使用 `ctx.credentials.resolve(ref)` 和 `describe(ref)`；页面和网络只传递引用名，不传递值。
8. **Web 服务：** rc.6 的服务名为 `webServer`，通过 `register` 挂载精确或前缀路由。
9. **客户端连接：** 页面通过官方 `llm.providers` 和 `llm.models` RPC 读取目录，并监听模型及设置更新事件。

## 模块职责

| 文件 | 职责 |
|---|---|
| `src/config.ts` | V2 设置结构、校验和路由/媒体类型 |
| `src/migration.ts` | V1 到 V2 的纯内存迁移与持久化投影 |
| `src/catalog.ts` | 官方目录读取和精确目标解析 |
| `src/router.ts` | 纯关键词匹配和校验后写入 |
| `src/tools.ts` | 白名单 `model_route` 与 Beta `image_gen` |
| `src/media/download.ts` | HTTPS、域名、重定向、私网、大小和超时限制 |
| `src/artifacts.ts` | 按文件魔数确认并保存图片 |
| `src/web.ts` | 设置后端和受真实路径约束的图片预览 |
| `src/index.ts` | 生命周期、监听器、工具和 Web 路由装配 |
| `src/client/index.tsx` | 模型中枢设置页和工具展示 |

## 稳定错误码

路由错误包括 `ROUTE_PROVIDER_INACTIVE`、`ROUTE_MODEL_UNRESOLVED`、`ROUTE_REASONING_INVALID`、`ROUTE_NOT_ALLOWED` 和 `ROUTE_MIGRATION_REQUIRED`。媒体错误包括 `MEDIA_PROVIDER_UNKNOWN`、`MEDIA_MODEL_NOT_ALLOWED`、`MEDIA_DOWNLOAD_BLOCKED`、`MEDIA_TOO_LARGE`、`MEDIA_NOT_IMAGE` 和 `ARTIFACT_PATH_BLOCKED`。路由失败不会写入会话模型头。

## 媒体扩展方向

1. 为新能力实现提交、轮询和取消适配器；
2. 扩展 `MEDIA_CAPABILITIES`；
3. 新增使用该能力的工具并在 `src/index.ts` 注册；
4. 增加失败测试、安全边界和中英文文档。

## 构建可复现性

`pnpm build` 依次编译宿主端、编译浏览器端，并由 `scripts/build-client.mjs` 包装成 `lib/client.js`。`lib/` 提交到仓库，使用户无需本地构建即可安装；持续集成会重新构建并检查没有差异。