# Henji Model Adaptation > 面向 Henji-AI 的模型与供应商适配工作流。用于“新增供应商”“给现有供应商新增模型”“模型和供应商都要新增”“校对参数顺序/隐藏参数/默认请求值”这类需求；先输出确认清单，用户确认后再实施。 Use when this capability is needed. - Skill: `tomevault-io/henji-model-adaptation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/henji-model-adaptation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/henji-model-adaptation/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/henji-model-adaptation --- # Henji Model Adaptation 按最小上下文加载执行。 ## 1. 识别场景并路由 - 先读取 `references/intake-checklist.md`，输出精简确认清单并等待用户确认。 - 若用户需求是“新增供应商”，读取 `references/new-provider.md`。 - 若用户需求是“现有供应商新增模型”，读取 `references/new-model-existing-provider.md`。 - 若用户需求是“新模型且未接入对应供应商”，先读取 `references/new-provider.md`，再读取 `references/new-provider-and-model.md`。 ## 2. 按需补充读取 - 先做“同模型多端点归并判定”： - 若 API 文档里的多个端点共享同一个模型名称/版本，只是输入素材或子能力不同，默认按“一个模型”处理，不默认拆成多个模型文件。 - 只有在名称/版本相同但计费、轮询契约、结果结构、核心参数集合明显不同，且无法通过 schema + `endpoints.selector` + `request.builder` 在一个模型内稳定表达时，才考虑拆分成多个模型。 - 先做“功能能力来源”判定： - 不要把“功能标签/筛选项”与“独立端点/独立 mode”混为一谈。 - 某个功能（例如首尾帧）即使没有独立端点、没有显式 `mode`，只要 API 文档表明它可通过同一端点内的可选字段激活（例如第 2 张图映射为 `end_image`），也应视为该模型具备此功能。 - 这类能力需要同时落到 3 处： - `meta.tags`：保证模型能被功能筛选命中； - `inputLimits` / `requirements`：保证输入数量与约束正确； - `request.builder`：把 UI/上传素材转换成 API 所需字段。 - 先做“自动切换 vs 显式 mode”判定： - 若路由差异仅由是否上传图片/视频、上传数量（如 0/1/2 张）决定，且用户侧不需要主动选择子能力，优先做自动切换，不新增 `mode` 参数。 - 若路由虽然可由素材数量自动判定，但为了让用户清楚当前处于哪个子模式，允许保留一个可见的 `mode` 参数，并通过 linkage/autoSwitch 自动更新其值；这类情况按“显式展示 + 自动切换”处理，不算纯手动模式。 - 若存在 3 种及以上子能力、允许多张参考图、同时支持视频编辑/参考生视频/延长视频等复杂分支，或不同分支的参数显隐/约束/价格差异明显，必须显式设计 `mode` 参数。 - 若仅有“文生图 + 图像编辑”两种能力，且差异只在“有无上传图片”，默认自动切换。 - 若仅有“文生视频 + 首帧图生视频 + 首尾帧视频”三种能力，且可由上传图片数量 0/1/2 张唯一确定，默认可采用两种方案： - 简单场景：纯自动切换，不暴露 `mode`； - 更重视用户心智可见性时：暴露 `mode`，默认显示“文/图生视频”，上传 2 张图后自动切到“首尾帧”。 - 一旦再引入“多参考图”“视频编辑”“视频参考”这类分支，则升级为显式 `mode` 主导。 - 设计参数顺序时，读取 `references/param-order-patterns.md`。 - 处理“不展示参数/固定默认请求值”时，读取 `references/hidden-default-params.md`。 - 判断图片/视频/音频差异时，读取 `references/modality-differences.md`。 - 涉及比例/分辨率时，优先执行“智能比例 + 本地转具体值”的规则（见 `references/param-order-patterns.md`）。 ## 3. 执行规则 - 在输出确认清单前，先自行归纳： - 这是“一个模型多个端点”还是“多个独立模型”； - 应采用“自动路由”“显式展示 + 自动切换”还是“显式 `mode`”； - 依据是什么（输入素材种类/数量、参数差异、价格差异、轮询契约差异）； - 各项“功能筛选标签”来自哪里：独立端点 / 显式 mode / 同端点内可选字段。 - 输出确认清单时，默认带上你的预判结论，用户只需要改例外项，不需要从头重复描述。 - 信息不足时，停止编码并向用户补充最小必要信息。 - 若用户未提供价格或计费规则，必须先追问价格，再继续模型实现。 - 优先复用同供应商、同模态、同模型家族的现有模型定义；仅将其作为起点，以官方 API 文档为准。 - 对接已接入的 provider 时，先核对该 provider 在仓库里的既有 route 写法与 runtime 约定，再决定 `endpoints` 填什么；不要只按文档标题猜路径，也不要漏掉现有 provider 统一前缀（例如部分 PPIO 路由实际要走 `/async/...`）。 - 参数展示层可以做统一交互，但最终请求参数必须转换为 API 文档要求的字段和值。 - Henji-AI 当前产品约定：新增模型默认不暴露 `output_format` / `outputFormat`，也不向 API 传递该字段；即使文档支持，也先按“不显示且不请求”处理，除非用户后续明确推翻这条约定。 - 若参数是否显示依赖“是否已上传图片/视频”，先核对前端显隐/联动实际使用的运行时字段名；当前仓库里，参数面板显隐通常依赖 `uploadedImages` / `uploadedVideos`，而 `uploadedFilePaths` 更偏向请求构建。 - 严格走项目主链路：`GenerationService -> src/commands/aiRuntime.ts -> src-tauri/src/ai_runtime/*`。 - 禁止在业务 UI 写模型/供应商硬编码分支。 - 牢记 runtime 约束：`endpoints.selector` 与 `request.builder` 都会被序列化后在 Rust JS 沙箱独立执行，不能依赖模型文件顶层 helper/闭包变量；需要的工具函数应内联在函数体内。 - 若模型在 `scripts/generate-model-manifest.cjs` 有 `CUSTOM_BUILDER_OVERRIDES`，修改模型 builder 时必须同步检查 override，避免 manifest 与源码行为不一致。 - 多端点模型除“自动切路由”外，还要检查“分支参数契约”： - 文档只在部分端点定义的参数，应只在对应分支显示/发送； - 不要把分支不支持的参数继续展示在 UI 上，再靠 builder 静默忽略； - 文档未定义字段默认不发送。 - 无论是否多端点，都要单独检查“功能筛选一致性”： - `meta.tags` 是否完整覆盖模型对外宣称的能力（如 `start-end-frame`、`reference-mode`、`motion-control`）； - 文案、筛选标签、输入约束、builder 映射是否一致； - 不要出现“请求层已支持某能力，但 tags 没标，导致功能筛选缺失”的情况。 - 改动参数默认值后，必须做一次“首屏默认值一致性”检查： - 模型 schema 的 `default` 与 UI 首次渲染显示值必须一致； - 若出现“默认值回到首项”的现象，优先排查下拉组件回退策略是否错误地回退到首个 option，而不是 `param.default`； - 同时检查 linkage 的 `autoSwitch/reset` 是否在初始化阶段覆盖了默认值。 ## 4. 完成标准 - 通过 `npm run build`。 - 新增能力不引入跨层调用与 UI 直连模型 API。 - 新增参数满足顺序约定，并明确“显示/请求”策略。 - 需要验证运行中的 Tauri 进程已加载新 manifest（重启 `npm run tauri:dev` 或执行 manifest reload 命令）。 - 默认值改动需通过“冷启动可见验证”：重启开发进程后确认参数面板初始显示值正确（不是仅看请求 builder 兜底）。 --- > Source: [henjicc/Henji-AI](https://github.com/henjicc/Henji-AI) — distributed by [TomeVault](https://tomevault.io).