GPU_GUARD_MONOREPO/docs/superpowers/specs/2026-04-12-model-channel-management-design.md

模型渠道管理设计文档

日期: 2026-04-12 范围: Neta-monorepo 后端 + 前端 参照: AI_flow_BackEnd 模型渠道管理实现

---

1. 目标

为 Neta-monorepo 新增集中式 LLM 模型渠道管理能力，参照 AI_flow 的三级结构（供应商 → 渠道 → 模型），同时适配 Neta 的 provider:model 运行时机制。改造 Agent 和 Skill 的模型配置为渠道级联选择器。

核心价值:

• API Key 集中管理，一处修改全局生效
• 支持同一供应商多套渠道（如测试/生产各一套 Key）
• 渠道启停、连通性测试等运维能力
• Agent/Skill 编辑时通过选择器引用，避免手动填凭证

---

2. 数据模型

2.1 新增表: netaclaw_model_channel

字段	类型	约束	说明
id	int	PK, auto	主键
name	varchar(100)	unique	渠道名称，如"Anthropic-生产"
supplier	varchar(50)	indexed	供应商类型代码
baseUrl	varchar(500)	not null	API 基础地址
apiKey	varchar(500)	nullable	API 密钥
models	json	not null	模型列表 [{name, capability}]
description	text	nullable	描述
status	int	indexed, default 1	0=禁用 1=启用
createTime	datetime	auto	创建时间
updateTime	datetime	auto	更新时间
deleteTime	datetime	nullable	软删除时间

models JSON 结构:

[
  { "name": "claude-sonnet-4-20250514", "capability": "text" },
  { "name": "claude-sonnet-4-20250514", "capability": "multimodal" }
]

2.2 系统参数 (base_sys_param)

新增 2 条参数记录:

keyName	name	dataType	data (JSON)
model_suppliers	AI模型供应商	0	[{"value":"openai","label":"OpenAI","tagType":""},{"value":"anthropic","label":"Anthropic","tagType":"purple"},{"value":"deepseek","label":"DeepSeek","tagType":"success"},{"value":"zhipu","label":"智谱AI","tagType":"success"},{"value":"tongyi","label":"通义千问","tagType":"warning"},{"value":"minimax","label":"MiniMax","tagType":"danger"},{"value":"volcengine","label":"火山引擎","tagType":"warning"},{"value":"ollama","label":"Ollama","tagType":"info"},{"value":"azure","label":"Azure OpenAI","tagType":""}]
model_capabilities	模型能力类型	0	[{"value":"text","label":"纯文本"},{"value":"multimodal","label":"多模态"},{"value":"vision","label":"视觉"}]

供应商和能力类型均通过系统参数表管理，前端不做硬编码。供应商配置包含 tagType 字段用于渲染标签颜色，后续可在参数列表页面自由扩展新供应商或新能力类型。

2.3 Agent modelConfig 字段语义扩展

新格式 (选择渠道时):

{ "channelId": 5, "modelId": "claude-sonnet-4-20250514", "contextWindow": 200 }

自定义格式 (channelId 为 0 或 null 时，回退手动模式):

{ "channelId": 0, "apiUrl": "https://...", "apiKey": "sk-xxx", "modelId": "custom-model", "contextWindow": 200 }

兼容性: 已有 Agent 的 modelConfig 中无 channelId，视为自定义配置模式，无需数据迁移。

---

3. 后端架构

3.1 新增文件

文件	路径	说明
Entity	packages/backend/src/modules/netaclaw/entity/model_channel.ts	TypeORM 实体
Service	packages/backend/src/modules/netaclaw/service/model_channel.ts	业务逻辑
Controller	packages/backend/src/modules/netaclaw/controller/admin/model_channel.ts	Admin API

3.2 API 端点

端点	方法	功能	来源
/admin/netaclaw/model_channel/page	POST	分页查询	@CoolController 自动生成
/admin/netaclaw/model_channel/add	POST	新增渠道	@CoolController 自动生成
/admin/netaclaw/model_channel/update	POST	更新渠道	@CoolController 自动生成
/admin/netaclaw/model_channel/delete	POST	删除渠道	@CoolController 自动生成
/admin/netaclaw/model_channel/info	GET	渠道详情	@CoolController 自动生成
/admin/netaclaw/model_channel/allModels	GET	所有启用渠道的模型列表	自定义方法
/admin/netaclaw/model_channel/testConnection	POST	测试渠道连通性	自定义方法

3.3 Service 关键方法

allModels():

• 查询所有 status=1 的渠道
• 标准化 models 字段（兼容旧格式字符串数组 → {name, capability} 对象）
• 返回渠道列表及其模型

testConnection(id: number):

• 根据 supplier 类型初始化对应 LLM 客户端
• 发送简单测试请求验证连通性
• 返回 { success, elapsed, message }
• 供应商到 Provider 的映射:
  • openai/azure → OpenAI SDK
  • anthropic → Anthropic SDK
  • deepseek → OpenAI SDK (自定义 baseUrl)
  • zhipu/tongyi/minimax/volcengine → OpenAI SDK (自定义 baseUrl)
  • ollama → OpenAI SDK (本地 baseUrl)

resolveForAgent(channelId: number, modelId: string):

• 查询渠道获取 supplier、baseUrl、apiKey
• 将 supplier 映射为 Neta 的 provider 名称
• 返回 { provider, model, apiKey, baseUrl } 供 Agent 运行时使用
• supplier → provider 映射规则:
  • openai → openai
  • anthropic → anthropic
  • deepseek → deepseek
  • 其他 (zhipu/tongyi/minimax/volcengine/ollama/azure) → openai（均使用 OpenAI 兼容协议）

3.4 运行时改造

文件: packages/backend/src/modules/netaclaw/runtime/agent.ts

在 runAgent() 函数中，执行前解析模型配置:

1. 读取 Agent 的 modelConfig
2. 若 channelId > 0，调用 resolveForAgent(channelId, modelId) 获取凭证
3. 若 channelId 为 0/null 或无该字段，使用 modelConfig 中的 apiUrl/apiKey（向后兼容）
4. 构建 provider:model 格式字符串传入运行时

3.5 Entity 注册

在 packages/backend/src/entities.ts 中添加新 Entity 的导入。

---

4. 前端架构

4.1 新增文件

文件	路径	说明
模型渠道管理页	packages/frontend/src/modules/agent/views/model-channel.vue	渠道 CRUD 页面
渠道选择器组件	packages/frontend/src/modules/agent/components/model-channel-selector.vue	级联选择器

4.2 模型渠道管理页面 (model-channel.vue)

布局:

• 顶部工具栏: 新增渠道按钮、供应商筛选下拉、关键词搜索、查询/重置
• 数据表格: 渠道名称、供应商(Tag)、Base URL、模型汇总(按能力分组计数)、状态(Switch)、操作(编辑/测试/删除)
• 分页控件
• 编辑抽屉 (600px 宽度):
  • 渠道名称 (必填)
  • 供应商类型 (下拉，选项从 model_suppliers 参数加载，必填)
  • Base URL (必填)
  • API Key (密码输入)
  • 描述
  • 模型列表 (表格式编辑: 模型名 + 能力类型下拉)
  • 添加单行 + 批量导入按钮
• 批量导入对话框: 默认能力类型 + 文本域(逗号/换行分隔模型名)

供应商 Tag 颜色: 从 model_suppliers 参数的 tagType 字段读取，不硬编码。

API 调用:

• 参数加载: GET /admin/base/sys/param/dataByKey?key=model_suppliers
• 参数加载: GET /admin/base/sys/param/dataByKey?key=model_capabilities
• 分页查询: POST /admin/netaclaw/model_channel/page
• 新增: POST /admin/netaclaw/model_channel/add
• 更新: POST /admin/netaclaw/model_channel/update
• 删除: POST /admin/netaclaw/model_channel/delete
• 测试: POST /admin/netaclaw/model_channel/testConnection

4.3 渠道选择器组件 (model-channel-selector.vue)

Props:

• modelValue?: { channelId?, modelId?, apiUrl?, apiKey?, contextWindow? } (v-model)
• capabilityFilter?: string (按能力类型过滤可选模型)

Emits:

• update:modelValue
• change

UI:

• 渠道选择下拉 (显示: "渠道名称（N个模型）")
• 额外选项: "自定义配置（手动输入）" (value=0)
• 模型选择下拉 (filterable，显示: 模型名 + 能力类型 Tag)
• 自定义模式时展示: API URL + API Key + Model ID 手动输入框

数据流:

1. 初始化时调用 GET /admin/netaclaw/model_channel/allModels 获取所有启用渠道
2. 按 capabilityFilter 过滤渠道和模型
3. 用户选择渠道 → 展示该渠道的模型列表
4. 用户选择模型 → emit { channelId, modelId }
5. 若选「自定义配置」→ 展示手动输入表单 → emit { channelId: 0, apiUrl, apiKey, modelId }

4.4 改造: Agent 编辑页

文件: packages/frontend/src/modules/agent/views/agent-edit.vue

「模型配置」Tab 改造:

• 移除原有 apiUrl/apiKey/modelId/contextWindow 4 个输入框
• 替换为 <model-channel-selector v-model="form.modelConfig" />
• 选择器下方保留 contextWindow 输入框
• 保留「填入默认」按钮（从 netaclaw 配置读取默认渠道）和「清空」按钮

4.5 改造: Skill 模型配置

文件: packages/frontend/src/modules/agent/components/skill-model.vue

• 将手动输入替换为 <model-channel-selector :capability-filter="skillType" />
• Skill 类型为 multimodal 时只展示 multimodal 能力的模型
• Skill 类型为 llm 时展示 text 能力的模型

4.6 路由配置

文件: packages/frontend/src/modules/agent/config.ts

新增路由:

{ path: '/agent/model-channel', meta: { label: '模型管理' } }

---

5. 文件变更清单

操作	位置	文件
新增	backend	src/modules/netaclaw/entity/model_channel.ts
新增	backend	src/modules/netaclaw/service/model_channel.ts
新增	backend	src/modules/netaclaw/controller/admin/model_channel.ts
新增	frontend	src/modules/agent/views/model-channel.vue
新增	frontend	src/modules/agent/components/model-channel-selector.vue
修改	frontend	src/modules/agent/views/agent-edit.vue
修改	frontend	src/modules/agent/components/skill-model.vue
修改	frontend	src/modules/agent/config.ts
修改	backend	src/modules/netaclaw/runtime/agent.ts
修改	backend	src/entities.ts
数据	database	base_sys_param 表新增 2 条参数记录

---

6. 兼容性

• 无数据迁移: 已有 Agent 的 modelConfig 中无 channelId，自动视为自定义配置模式
• 渐进式采用: 新建/编辑 Agent 时可选择渠道或自定义，不影响已有 Agent 运行
• 运行时兼容: channelId 有值走渠道查询，无值走原有 apiUrl/apiKey 逻辑