@kmchai/cortico-world-voice 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.3.0
+
+- 系统 Config tab 移除「音色与情绪」组;音色、情绪控制、默认情绪、默认表演指令、语速与副语言标签移到「模型」页。
+- 朗读风格按模型保存进 `worlds.voice.modelStyles[model]`;切换模型时面板读回该模型的音色、风格与参数,不用先保存。旧全局字段保留为没有模型设置时的回落。
+- `voice_style` 在选定模型后只写当前模型的风格;没有模型时仍写全局回落值。
+- 服务返回的 Ming 3.0 模型参数(模板、语言、指令语言、音高、音量、生成与分块参数)在模型页显示;IndexTTS2 的中文参数名继续保留。
+- 文本过滤、合成与 `tts.voice` 事件都使用当前模型生效的风格。
+
+## 0.2.1
+
+- 新增 World 页的「模型」面板:模型与音色在面板里选,不再占系统 Config tab 的字段。
+- 按服务 `/v1/models` 返回的参数元数据渲染字段:开关、枚举、数字与文本;IndexTTS2 的参数带中文名。
+- 模型专属参数存进 `worlds.voice.modelOptions[model]`,请求时作为 `options` 发给服务;空对象删掉该模型的条目。
+- 面板显示当前模型的提示词片段;目录缓存在进程内,服务不可达时保留上一次结果并报错。
+- 新增 `scripts/build-webui.mjs`(esbuild)与 `dist/webui.js` / `dist/webui.css`。
+
 ## 0.2.0
 
 分层:协议、进程托管与 HTTP 网关移到 `@kmchai/cortico-world-service`;语音只保留工具、概率朗读、文本过滤、情绪与标签语义、队列和本机播放,经 HTTP 调服务。

package/README.md

@@ -34,7 +34,6 @@ corepack pnpm add "D:/path/to/cortico-world-voice" --ignore-workspace
       "serviceUrl": "http://127.0.0.1:9883",
       "serviceTokenSecret": "",
       "model": "ming3-tts",
-      "voice": "4016",
       "playback": "local",
       "autoSpeak": true,
       "autoProbability": 0.3
@@ -45,6 +44,10 @@ corepack pnpm add "D:/path/to/cortico-world-voice" --ignore-workspace
 
 `serviceUrl` 默认为 `http://127.0.0.1:9883`。`serviceTokenSecret` 填部署 `.env` 里的变量名,值只在请求时读取;服务监听非回环地址时必须配令牌。后端条目、模型 profile 与上游密钥都配在服务 World 里,见[服务包 README](https://github.com/Kmch-AI/cortico-world-service#readme)。
 
+## 模型面板
+
+World 页的「模型」tab 选模型与音色,并按服务 `/v1/models` 返回的参数元数据渲染字段。同一页的「声音与情绪」按模型保存情绪控制方式、默认情绪、默认表演指令、语速与副语言标签策略;切换模型时读回该模型自己的设置。模型设置存 `worlds.voice.modelStyles[model]`,模型参数存 `worlds.voice.modelOptions[model]`;合成时作为 `options` 发给服务。模型专属的文本与情绪写法显示在同页的「模型提示词」折叠区。系统 Config tab 只留服务地址、触发、过滤与输出。
+
 ## 工具
 
 | 工具 | 作用 |
@@ -78,7 +81,7 @@ corepack pnpm add "D:/path/to/cortico-world-voice" --ignore-workspace
 
 ## 情绪、语速与标签
 
-语音只把语义字段发给服务,由服务的模型 profile 决定怎么落到具体模型:
+情绪与语速设置按模型保存在「模型」页,不再出现在系统 Config tab。语音只把语义字段发给服务,由服务的模型 profile 决定怎么落到具体模型:
 
 | `emotionMode` | 语音发送 | `audiocpp-ming3` profile 的落点 |
 |---|---|---|
@@ -92,10 +95,10 @@ OpenAI 兼容条目把 `instructions` / `emotion` / `speed` 直接放进请求
 
 `response_format` 每次都带;`model` 与 `voice` 配了才带,工具参数里的音色优先于配置默认值。
 
-- 情绪来源:工具参数 > 正文里的 `[emotion:开心]` 标记 > `defaultEmotion`。
-- `voice_style` 读写长期风格(情绪、指令、音色、语速),写回 `worlds.voice`。
+- 情绪来源:工具参数 > 正文里的 `[emotion:开心]` 标记 > 当前模型的 `defaultEmotion`。
+- `voice_style` 读写当前模型的长期风格(情绪、指令、音色、语速),写进 `modelStyles[model]`;还没选模型时写到全局回落值。
 - 副语言标签:`[Breathing] [Cough] [Sigh] [Laughter] [Surprise-ah] [Surprise-oh] [Dissatisfaction-hnn] [Uhm] [Confirmation-en] [Question-ei] [Question-ah] [Question-en] [Question-oh] [Question-huh]`。
-  `paralinguistic: auto` 保留标签,由服务里的模型决定演不演;`keep` 一律保留,`strip` 一律删除。表外 `[...]` 会从朗读文本里剥掉,防止被念出来。
+  `paralinguistic: auto` 只在当前模型支持标签(Ming 3.0 系)时保留,IndexTTS2 与通用模型剥掉;`keep` 一律保留,`strip` 一律删除。表外 `[...]` 会从朗读文本里剥掉,防止被念出来。
 
 ## 文本过滤
 
@@ -121,8 +124,8 @@ OpenAI 兼容条目把 `instructions` / `emotion` / `speed` 直接放进请求
 |---|---|
 | `POST /v1/audio/speech` | 合成音频;体 `{model?, input, voice?, response_format, speed?, instructions?, emotion?}`。 |
 | `GET /health` | 探活;World 页的服务灯每 15 秒刷新。 |
-| `GET /v1/models` | 模型下拉。 |
-| `GET /v1/audio/voices?model=` | 音色下拉。 |
+| `GET /v1/models` | 模型、音色与请求参数元数据。 |
+| `GET /v1/audio/voices?model=` | 当前模型的音色表。 |
 
 服务不可达时:模型与音色下拉保留上一次读到的表,服务灯变红,`voice_speak` 回失败。语音 0.2.0 不保留直连后端的回退路径。服务不重试上游,语音也不重试。
 
@@ -137,7 +140,7 @@ OpenAI 兼容条目把 `instructions` / `emotion` / `speed` 直接放进请求
 | `httpApi` / `httpPort` / `httpToken` / `httpPlay` | 删除;服务的网关取代本地语音接口。 |
 | `singUrl` / `singToken`、`voice_sing`、`【唱】` | 删除;唱歌由服务的 `/v1/audio/sing` 与网关接入。 |
 | `model` / `voice` / `format` / `timeoutMs` | 保留,含义不变。 |
-| `emotionMode` / `defaultEmotion` / `defaultInstruct` / `speed` / `paralinguistic` | 保留;语音只发语义字段,由服务的模型 profile 映射到具体模型。 |
+| `emotionMode` / `defaultEmotion` / `defaultInstruct` / `speed` / `paralinguistic` | 移到「模型」页,按模型保存;旧全局值仍作为没有模型设置时的回落。 |
 | 触发、过滤、输出配置 | 保留。 |
 
 ## 验证
@@ -149,7 +152,7 @@ pnpm smoke:player out.wav                 # 本机播放器,音量 0
 pnpm smoke:chain http://127.0.0.1:9883    # 触发→过滤→经服务合成→tts.voice 全链路
 ```
 
-装进 Cortico 后应看到:World 页多一张「Kmch AI · 语音」卡,服务灯、队列灯与 `service` / `model` / `voice` 徽标;服务在线时灯亮;让 bot 调 `voice_speak` 能听见;说「念给我听」会绕过概率;`playback: event` 时时间线出现 `tts.voice`。
+装进 Cortico 后应看到:World 页多一张「Kmch AI · 语音」卡,服务灯、队列灯与 `service` / `model` / `voice` 徽标;「模型」tab 能选模型与音色,按模型调整声音与情绪,并按服务参数渲染字段、保存;服务在线时灯亮;让 bot 调 `voice_speak` 能听见;说「念给我听」会绕过概率;`playback: event` 时时间线出现 `tts.voice`。
 
 ## 许可
 

package/describe.json

@@ -126,7 +126,7 @@
       "key": "worlds.voice.envPrompt",
       "title": "语音 · 环境提示词",
       "role": "envPrompt",
-      "content": "语音由 Voice 提供:它只把文字变成声音,从对方的扬声器念出来,不负责把回复发到聊天渠道;可见的回复仍然走渠道自己的发送工具。\n\n自动朗读现在是 {{voice.auto}}(音色 {{voice.voice}},情绪 {{voice.emotion}},指令 {{voice.instruct}})。自动朗读开着时,普通回复不必调用语音工具;关着时,想出声就调用 voice_speak。\n\n需要出声的时候:\n- 对方明确要语音、要你念出来、要听你的声音时,调用 voice_speak,把要念的正文放进 text。它会绕过概率,必定出声。\n- 这一句需要特定情绪、语气、音色或语速时,调用 voice_speak 并填对应参数。想让同样的语气之后一直生效,调用 voice_style;它影响之后的自动朗读。\n- 某一句只用于别的渠道(例如语音条),不要在本机播放:voice_speak 带 silent: true,音频随回执交给渠道。\n- 对方让你安静、停下时调用 voice_hush。\n\n文本规则:\n- text 只放真正要念的正文,不要放动作描写、Markdown、代码、网址或解释。\n- 可以在正文里放 [Laughter]、[Sigh]、[Breathing]、[Uhm]、[Question-ei] 这类副语言标签;模型支持时会被演出来,不会被念出字面。不确定模型是否支持时不要加,免得被原样念出来。\n- 不要把控制标记写进可见的回复正文;语音参数只放在工具调用里。\n"
+      "content": "语音由 Voice 提供:它只把文字变成声音,从对方的扬声器念出来,不负责把回复发到聊天渠道;可见的回复仍然走渠道自己的发送工具。\n\n自动朗读现在是 {{voice.auto}}(音色 {{voice.voice}},情绪 {{voice.emotion}},指令 {{voice.instruct}})。自动朗读开着时,普通回复不必调用语音工具;关着时,想出声就调用 voice_speak。\n\n需要出声的时候:\n- 对方明确要语音、要你念出来、要听你的声音时,调用 voice_speak,把要念的正文放进 text。它会绕过概率,必定出声。\n- 这一句需要特定情绪、语气、音色或语速时,调用 voice_speak 并填对应参数。想让同样的语气之后一直生效,调用 voice_style;它影响之后的自动朗读。\n- 某一句只用于别的渠道(例如语音条),不要在本机播放:voice_speak 带 silent: true,音频随回执交给渠道。\n- 对方让你安静、停下时调用 voice_hush。\n\n文本规则:\n- text 只放真正要念的正文,不要放动作描写、Markdown、代码、网址或解释。\n- {{voice.modelPrompt}}\n- 不要把控制标记写进可见的回复正文;语音参数只放在工具调用里。\n"
     }
   ]
 }

package/dist/webui.css

@@ -0,0 +1 @@
+.vx-top{display:flex;flex-wrap:wrap;align-items:end;gap:10px}.vx-pick{display:flex;flex:1 1 160px;min-width:0;flex-direction:column;gap:4px}.vx-pick-label{font:var(--text-detail)/1.2 var(--sans);color:var(--ink-soft)}.vx-pick select.field{width:100%;box-sizing:border-box}.vx-top>.btn{margin-left:auto;align-self:end}.vx-params{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:12px 18px;margin-top:14px}.vx-params:empty{display:none}.vx-field{display:flex;min-width:0;flex-direction:column;gap:5px}.vx-head{display:flex;align-items:baseline;gap:7px}.vx-label{font:13px/1.3 var(--sans);color:var(--ink)}.vx-name{font:11px/1.3 var(--mono);color:var(--ink-soft)}.vx-field>.field,.vx-field>label.check{width:100%;box-sizing:border-box}.vx-desc{font:12px/1.4 var(--sans);color:var(--ink-soft)}.vx-params+.actions{margin-top:14px}.vx-prompt{margin:0;padding:10px 12px;max-height:260px;overflow:auto;white-space:pre-wrap;overflow-wrap:anywhere;font:12px/1.55 var(--mono);color:var(--ink-soft);background:var(--sheet-2);border:1px solid var(--line);border-radius:8px}

package/dist/webui.js

@@ -0,0 +1 @@
+var B={zh:{title:"\u6A21\u578B",model:"\u6A21\u578B",voice:"\u97F3\u8272",refresh:"\u5237\u65B0",save:"\u4FDD\u5B58",saved:"\u5DF2\u4FDD\u5B58",loading:"\u8BFB\u53D6\u4E2D\u2026",promptTitle:"\u6A21\u578B\u63D0\u793A\u8BCD",styleTitle:"\u58F0\u97F3\u4E0E\u60C5\u7EEA",paramsTitle:"\u6A21\u578B\u53C2\u6570",emotionMode:"\u60C5\u7EEA\u63A7\u5236",defaultEmotion:"\u9ED8\u8BA4\u60C5\u7EEA",defaultInstruct:"\u9ED8\u8BA4\u8868\u6F14\u6307\u4EE4",speed:"\u8BED\u901F",paralinguistic:"\u526F\u8BED\u8A00\u6807\u7B7E",emotionModeOptions:[{value:"instruct",label:"\u81EA\u7136\u8BED\u8A00"},{value:"categorical",label:"\u60C5\u7EEA\u6807\u7B7E"},{value:"basic",label:"\u8BED\u901F"},{value:"tags",label:"\u6B63\u6587\u6807\u7B7E"},{value:"none",label:"\u4E0D\u53D1\u9001"}],paralinguisticOptions:[{value:"auto",label:"\u81EA\u52A8"},{value:"keep",label:"\u4FDD\u7559"},{value:"strip",label:"\u5220\u9664"}]},en:{title:"\u6A21\u578B",model:"Model",voice:"Voice",refresh:"Refresh",save:"Save",saved:"Saved",loading:"Loading\u2026",promptTitle:"Model prompt",styleTitle:"Voice and emotion",paramsTitle:"Model parameters",emotionMode:"Emotion control",defaultEmotion:"Default emotion",defaultInstruct:"Default direction",speed:"Speed",paralinguistic:"Paralinguistic tags",emotionModeOptions:[{value:"instruct",label:"Natural language"},{value:"categorical",label:"Emotion label"},{value:"basic",label:"Speed"},{value:"tags",label:"Inline tags"},{value:"none",label:"Send nothing"}],paralinguisticOptions:[{value:"auto",label:"Auto"},{value:"keep",label:"Keep"},{value:"strip",label:"Strip"}]}};function j(e){return e.toLowerCase().startsWith("zh")?B.zh:B.en}var D={template_name:"\u6A21\u677F",language:"\u8BED\u8A00",instruction_schema:"\u6307\u4EE4\u8BED\u8A00",pitch:"\u97F3\u9AD8",volume:"\u97F3\u91CF",guidance_scale:"\u5F15\u5BFC\u5F3A\u5EA6",sigma:"\u566A\u58F0\u5C3A\u5EA6",raw_text:"\u6574\u6BB5\u53D1\u9001",trim_silence:"\u4FEE\u526A\u9759\u97F3",emotion_alpha:"\u60C5\u7EEA\u5F3A\u5EA6",emotion_text:"\u60C5\u7EEA\u63CF\u8FF0",use_emotion_text:"\u4F7F\u7528\u6587\u5B57\u60C5\u7EEA",use_random_emotion:"\u968F\u673A\u60C5\u7EEA",duration_scale:"\u65F6\u957F\u7F29\u653E",interval_silence_ms:"\u5206\u6BB5\u9759\u97F3",do_sample:"\u91C7\u6837",top_p:"top_p",top_k:"top_k",temperature:"\u6E29\u5EA6",length_penalty:"\u957F\u5EA6\u60E9\u7F5A",num_beams:"beam \u6570",repetition_penalty:"\u91CD\u590D\u60E9\u7F5A",max_tokens:"\u6700\u5927 token",seed:"\u79CD\u5B50",text_chunk_size:"\u6587\u672C\u5206\u5757\u5927\u5C0F",text_chunk_mode:"\u5206\u5757\u6A21\u5F0F"};var Q={voice:"",emotionMode:"instruct",defaultEmotion:"",defaultInstruct:"",speed:1,paralinguistic:"auto"};function Z(e,t){return Object.prototype.hasOwnProperty.call(t,e.name)?t[e.name]:e.default}function O(e){return e==null?"":Array.isArray(e)?e.map(t=>String(t)).join(", "):String(e)}function $(e){return typeof e=="number"&&Number.isFinite(e)?String(e):typeof e=="string"&&e.trim()&&Number.isFinite(Number(e))?e.trim():""}function ee(e,t,l){let n=e.ui,i=n.h("div","vx-field"),f=n.h("div","vx-head"),p=D[t.name];p&&p!==t.name?f.append(n.h("span","vx-label",p),n.h("span","vx-name",t.name)):f.append(n.h("span","vx-label",t.name)),i.append(f);let m=Z(t,l),c;switch(t.type){case"bool":{let a=n.checkbox("",{checked:m===!0});i.append(a.el),c=()=>a.checked;break}case"enum":{let a=t.values??[],r=O(m),u=[{value:"",label:"\u2014"},...a.map(y=>({value:y,label:y}))];r&&!a.includes(r)&&u.push({value:r,label:r});let x=n.select({options:u,value:r});i.append(x),c=()=>x.value||void 0;break}case"int":case"float":{let a=n.input({type:"number",value:$(m)});t.min!==void 0&&(a.min=String(t.min)),t.max!==void 0&&(a.max=String(t.max)),a.step=t.type==="int"?"1":"any",i.append(a),c=()=>{let r=a.value.trim();if(!r)return;let u=Number(r);if(Number.isFinite(u))return t.type==="int"?Math.trunc(u):u};break}case"string_list":case"path_list":{let a=n.input({type:"text",value:O(m)});i.append(a),c=()=>{let r=a.value.split(/[,，]/).map(u=>u.trim()).filter(Boolean);return r.length>0?r:void 0};break}default:{let a=n.input({type:"text",value:O(m)});i.append(a),c=()=>a.value.trim()||void 0;break}}return t.description&&i.append(n.h("div","vx-desc",t.description)),{param:t,el:i,read:c}}function M(e,t,l){let n=e.ui.h("div","vx-field"),i=e.ui.h("div","vx-head");return i.append(e.ui.h("span","vx-label",t)),n.append(i,l),n}function te(e,t,l){let n=e.ui,i=n.h("div","vx-params"),f=n.select({options:t.emotionModeOptions.map(({value:r,label:u})=>({value:r,label:u})),value:l.emotionMode}),p=n.input({type:"text",value:l.defaultEmotion}),m=n.input({type:"text",value:l.defaultInstruct}),c=n.input({type:"number",value:String(l.speed)});c.min="0.5",c.max="2",c.step="0.05";let a=n.select({options:t.paralinguisticOptions.map(({value:r,label:u})=>({value:r,label:u})),value:l.paralinguistic});return i.append(M(e,t.emotionMode,f),M(e,t.defaultEmotion,p),M(e,t.defaultInstruct,m),M(e,t.speed,c),M(e,t.paralinguistic,a)),{el:i,read:()=>{let r=Number(c.value);return{voice:l.voice,emotionMode:f.value,defaultEmotion:p.value.trim(),defaultInstruct:m.value.trim(),speed:Number.isFinite(r)?Math.min(2,Math.max(.5,r)):l.speed,paralinguistic:a.value}}}}function ne(e){let t=j(e.language),l=e.ui,n=null,i="",f=[],p=!1,m=l.sheet({title:t.title}),c=l.h("div","vx-top"),a=l.select({onChange:()=>K(a.value)}),r=l.select({}),u=l.h("label","vx-pick");u.append(l.h("span","vx-pick-label",t.model),a);let x=l.h("label","vx-pick");x.append(l.h("span","vx-pick-label",t.voice),r);let y=l.button(t.refresh,{size:"sm",onClick:()=>{H("refresh")}});c.append(u,x,y);let Y=l.section(t.styleTitle),V=l.h("div","vx-section"),k=l.section(t.paramsTitle);k.hidden=!0;let S=l.h("div","vx-params"),L=l.button(t.save,{variant:"primary",size:"sm",onClick:()=>{J()}}),P=l.msgline(),F=l.actions();F.append(L),m.body.append(c,Y,V,k,S,F,P),e.root.append(m.el);let _=l.foldSheet("voice-model-prompt",{title:t.promptTitle,defaultOpen:!1}),I=l.h("pre","vx-prompt");_.body.append(I),e.root.append(_.el);let T=null;function g(o,s=o){let d=l.h("option");return d.value=o,d.textContent=s,d}function b(o,s){P.textContent=o,P.classList.toggle("bad",s)}function v(){let o=n!==null&&n.models.length>0;a.disabled=p||!o,r.disabled=p||!o||!i,L.disabled=p||!o||!i,y.disabled=p}function w(o){return n?.settings?.[o]}function z(o){return w(o)?.style??(n?.model===o?n.style:void 0)??Q}function A(){let s=n?.models.find(E=>E.id===i)?.voices??[],d=w(i)?.voice??(n?.model===i?n.voice:""),h=[...s];d&&!h.includes(d)&&h.unshift(d);let C=h.map(E=>g(E));d||C.unshift(g("","\u2014")),r.replaceChildren(...C.length>0?C:[g("","\u2014")]),r.value=d}function R(){T=te(e,t,z(i)),V.replaceChildren(T.el)}function W(){let o=n?.models.find(d=>d.id===i),s=w(i)?.options??(n?.model===i?n.options:{});f=[],S.replaceChildren();for(let d of o?.parameters??[]){let h=ee(e,d,s);f.push(h),S.append(h.el)}k.hidden=(o?.parameters?.length??0)===0}function N(){let o=n?.prompts?.[i]??(n?.model===i?n.prompt:"");I.textContent=o,_.note.textContent=i||"\u2014"}function K(o){i=o,A(),R(),W(),N(),v()}function U(o){n=o,i=o.model,X(),R(),W(),N(),v(),b(o.error??"",o.error!==void 0)}function X(){let o=n?.models??[],s=o.map(d=>g(d.id,d.label||d.id));!i&&o.length>0?s.unshift(g("","\u2014")):i&&!o.some(d=>d.id===i)&&s.unshift(g(i,i)),a.replaceChildren(...s),a.value=i,A()}function q(){let o={};for(let s of f){let d=s.read();d!==void 0&&(o[s.param.name]=d)}return o}function G(){return{...T?.read()??z(i),voice:r.value}}async function H(o){if(!p){p=!0,v(),b(t.loading,!1);try{let s=await e.invoke(o,[]);e.signal.aborted||U(s)}catch(s){e.signal.aborted||b(s instanceof Error?s.message:String(s),!0)}finally{p=!1,e.signal.aborted||v()}}}async function J(){if(p||!n)return;let o={model:i,voice:r.value,style:G(),options:q()};p=!0,v(),b("",!1);try{let s=await e.invoke("save",[o]);e.signal.aborted||(U(s),b(t.saved,!1))}catch(s){e.signal.aborted||b(s instanceof Error?s.message:String(s),!0)}finally{p=!1,e.signal.aborted||v()}}v(),H("state")}var ie={panels:{model:{mount:ne}}},de=ie;export{de as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmchai/cortico-world-voice",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Cortico World: voice tools, probabilistic reading, emotion and paralinguistic tags, text filtering and local playback; speech is synthesized by the Kmch AI service over HTTP",
   "author": "kmchai",
@@ -49,23 +49,29 @@
       "requires-extension",
       "experimental"
     ],
-    "describe": "describe.json"
+    "describe": "describe.json",
+    "webUiClient": "dist/webui.js",
+    "webUiStyle": "dist/webui.css"
   },
   "files": [
     "src",
+    "dist/webui.js",
+    "dist/webui.css",
     "README.md",
     "CHANGELOG.md",
     "describe.json"
   ],
   "scripts": {
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.webui.json",
+    "build:webui": "node scripts/build-webui.mjs",
     "smoke:player": "tsx scripts/smoke-player.ts",
     "smoke:chain": "tsx scripts/smoke-chain.ts"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "cortico": "^0.2.12",
+    "esbuild": "^0.28.2",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"

package/src/ENV_PROMPT.md

@@ -10,5 +10,5 @@
 
 文本规则:
 - text 只放真正要念的正文,不要放动作描写、Markdown、代码、网址或解释。
-- 可以在正文里放 [Laughter]、[Sigh]、[Breathing]、[Uhm]、[Question-ei] 这类副语言标签;模型支持时会被演出来,不会被念出字面。不确定模型是否支持时不要加,免得被原样念出来。
+- {{voice.modelPrompt}}
 - 不要把控制标记写进可见的回复正文;语音参数只放在工具调用里。

package/src/config.ts

@@ -1,13 +1,11 @@
 /** `worlds.voice` 的默认值、配置组与界面文案。 */
 import type { ConfigGroup } from 'cortico/core/types.ts';
 import { pick, type Language, type LanguageTable } from 'cortico/core/language.ts';
-import type { VoiceConfigSection } from './types.ts';
+import type { VoiceConfigSection, VoiceModelStyle } from './types.ts';
 
 export const VOICE_ID = 'voice';
-/** 配置里 `x-options` 用的动态音色表。 */
-export const VOICE_OPTIONS_KIND = 'voice.voices';
-/** 配置里 `x-options` 用的动态模型表。 */
-export const VOICE_MODELS_KIND = 'voice.models';
+/** World 定义、WebUI 与配置页共用同一个显示名。 */
+export const VOICE_LABEL = 'Kmch AI · 语音';
 
 export const VOICE_DEFAULTS: VoiceConfigSection = {
   enabled: false,
@@ -16,6 +14,8 @@ export const VOICE_DEFAULTS: VoiceConfigSection = {
   serviceTokenSecret: '',
   model: '',
   voice: '',
+  modelOptions: {},
+  modelStyles: {},
   format: 'wav',
   timeoutMs: 180_000,
 
@@ -50,32 +50,49 @@ export const VOICE_DEFAULTS: VoiceConfigSection = {
   shareAudio: false,
 };
 
+/**
+ * 当前模型的朗读风格。模型页保存的值优先,缺省字段回落到旧的全局值,
+ * 这样升级前已有的配置仍然有效。
+ */
+export function modelStyle(cfg: VoiceConfigSection, model = cfg.model): VoiceModelStyle {
+  const saved = cfg.modelStyles?.[model] ?? {};
+  return {
+    voice: saved.voice ?? cfg.voice,
+    emotionMode: saved.emotionMode ?? cfg.emotionMode,
+    defaultEmotion: saved.defaultEmotion ?? cfg.defaultEmotion,
+    defaultInstruct: saved.defaultInstruct ?? cfg.defaultInstruct,
+    speed: saved.speed ?? cfg.speed,
+    paralinguistic: saved.paralinguistic ?? cfg.paralinguistic,
+  };
+}
+
+/** 把模型风格盖到配置上,给过滤、合成与提示词读取。 */
+export function styledConfig(cfg: VoiceConfigSection, model = cfg.model): VoiceConfigSection {
+  return { ...cfg, ...modelStyle(cfg, model) };
+}
+
 const TEXT = {
   zh: {
-    label: '语音',
+    label: 'Kmch AI · 语音',
     envTitle: '语音 · 环境提示词',
     lampService: '语音服务',
     lampQueue: '朗读队列',
     servicePage: '服务设置',
+    modelPanel: '模型',
+    modelSaveShape: '保存失败:参数格式不对。',
+    modelSaveModel: '保存失败:模型 id 不能为空。',
+    modelSaveVoice: '保存失败:音色必须是字符串。',
+    modelSaveStyle: '保存失败:朗读风格格式不对。',
+    modelSaveOptions: '保存失败:模型参数必须是对象。',
+    modelUnknownMethod: '未知的面板方法。',
     connection: '连接',
     connectionDesc: '语音服务的 HTTP 地址与令牌。',
     serviceUrl: '服务地址',
     serviceUrlDesc: 'Kmch AI · 服务 的网关地址。',
     serviceTokenSecret: '服务令牌变量名',
     serviceTokenSecretDesc: '部署 .env 里的变量名,留空表示服务不校验。',
-    model: '模型',
-    voice: '音色',
     format: '音频格式',
     timeoutMs: '超时(毫秒)',
-    style: '音色与情绪',
-    styleDesc: '',
-    emotionMode: '情绪控制',
-    emotionModeDesc: 'instruct 折成自然语言指令;categorical 只发情绪标签;basic 只发语速;tags 只用正文标签;none 不发。',
-    defaultEmotion: '默认情绪',
-    defaultInstruct: '默认表演指令',
-    speed: '语速',
-    paralinguistic: '副语言标签',
-    paralinguisticDesc: 'auto 保留,由服务与模型决定;strip 一律从朗读文本里删掉。',
     triggers: '触发',
     triggersDesc: '',
     autoSpeak: '自动朗读',
@@ -111,30 +128,26 @@ const TEXT = {
     shareAudio: '回执带音频附件',
   },
   en: {
-    label: 'Voice',
+    label: 'Kmch AI · 语音',
     envTitle: 'Voice · environment prompt',
     lampService: 'Speech service',
     lampQueue: 'Speech queue',
     servicePage: 'Service settings',
+    modelPanel: '模型',
+    modelSaveShape: 'Save failed: invalid arguments.',
+    modelSaveModel: 'Save failed: the model id must not be empty.',
+    modelSaveVoice: 'Save failed: voice must be a string.',
+    modelSaveStyle: 'Save failed: invalid voice style.',
+    modelSaveOptions: 'Save failed: model options must be an object.',
+    modelUnknownMethod: 'Unknown panel method.',
     connection: 'Connection',
     connectionDesc: 'Where the speech service is and which token it expects.',
     serviceUrl: 'Service URL',
     serviceUrlDesc: 'Gateway address of Kmch AI · Service.',
     serviceTokenSecret: 'Service token variable',
     serviceTokenSecretDesc: 'Name in the deployment .env; empty means the service does not check.',
-    model: 'Model',
-    voice: 'Voice',
     format: 'Audio format',
     timeoutMs: 'Timeout (ms)',
-    style: 'Voice and emotion',
-    styleDesc: '',
-    emotionMode: 'Emotion control',
-    emotionModeDesc: 'instruct turns it into natural language; categorical sends a label; basic sends speed; tags uses inline tags only; none sends nothing.',
-    defaultEmotion: 'Default emotion',
-    defaultInstruct: 'Default direction',
-    speed: 'Speed',
-    paralinguistic: 'Paralinguistic tags',
-    paralinguisticDesc: 'auto keeps them and lets the service and model decide; strip removes them from the spoken text.',
     triggers: 'Triggers',
     triggersDesc: '',
     autoSpeak: 'Automatic speech',
@@ -192,28 +205,11 @@ export function voiceConfigGroups(language: Language): ConfigGroup[] {
         properties: {
           [`${p}serviceUrl`]: { type: 'string', title: t.serviceUrl, description: t.serviceUrlDesc, 'x-hot': true },
           [`${p}serviceTokenSecret`]: { type: 'string', title: t.serviceTokenSecret, description: t.serviceTokenSecretDesc, 'x-hot': true },
-          [`${p}model`]: { type: 'string', title: t.model, 'x-options': VOICE_MODELS_KIND, 'x-hot': true },
-          [`${p}voice`]: { type: 'string', title: t.voice, 'x-options': VOICE_OPTIONS_KIND, 'x-hot': true },
           [`${p}format`]: { type: 'string', title: t.format, enum: ['wav', 'mp3'], 'x-hot': true },
           [`${p}timeoutMs`]: { type: 'integer', title: t.timeoutMs, minimum: 1000, maximum: 600_000, 'x-hot': true },
         },
       },
     },
-    {
-      id: 'world:voice-style',
-      owner: 'world:voice',
-      schema: {
-        type: 'object',
-        title: t.style,
-        properties: {
-          [`${p}emotionMode`]: { type: 'string', title: t.emotionMode, description: t.emotionModeDesc, enum: ['instruct', 'categorical', 'basic', 'tags', 'none'], 'x-hot': true },
-          [`${p}defaultEmotion`]: { type: 'string', title: t.defaultEmotion, 'x-hot': true },
-          [`${p}defaultInstruct`]: { type: 'string', title: t.defaultInstruct, 'x-hot': true },
-          [`${p}speed`]: { type: 'number', title: t.speed, minimum: 0.5, maximum: 2, multipleOf: 0.05, 'x-hot': true },
-          [`${p}paralinguistic`]: { type: 'string', title: t.paralinguistic, description: t.paralinguisticDesc, enum: ['auto', 'keep', 'strip'], 'x-hot': true },
-        },
-      },
-    },
     {
       id: 'world:voice-triggers',
       owner: 'world:voice',

package/src/definition.ts

@@ -1,15 +1,13 @@
 import { describeTools, type WorldDefinition } from 'cortico/world.ts';
-import { VOICE_DEFAULTS, VOICE_ID } from './config.ts';
-import { currentOptions } from './options.ts';
+import { VOICE_DEFAULTS, VOICE_ID, VOICE_LABEL } from './config.ts';
 import { VOICE_TOOL_DECLS } from './tools.ts';
 import type { VoiceConfigSection } from './types.ts';
 import { VoiceWorld } from './world.ts';
 
 export const VOICE: WorldDefinition<VoiceConfigSection> = {
   id: VOICE_ID,
-  label: 'Voice',
-  defaults: () => ({ ...VOICE_DEFAULTS }),
-  configOptions: (kind) => currentOptions(kind),
+  label: VOICE_LABEL,
+  defaults: () => ({ ...VOICE_DEFAULTS, modelOptions: {}, modelStyles: {} }),
   create: (ctx) => new VoiceWorld({
     cfg: ctx.cfg,
     timezone: ctx.timezone,

package/src/models.ts

@@ -0,0 +1,66 @@
+/**
+ * 模型能力与提示词片段。
+ *
+ * 服务返回的模型 id 决定两件事:正文里能不能写副语言标签,以及环境提示词
+ * 该怎么描述文本与情绪。按 id 前缀匹配,大小写不敏感;空模型与未知模型按
+ * 通用 OpenAI 兼容模型处理。
+ */
+
+interface ModelInfo {
+  /** 模型 id 的前缀,小写。 */
+  readonly match: readonly string[];
+  /** 给人看的名字;未知模型为空。 */
+  readonly label: string;
+  /** 是否支持 `[Laughter]` 这类副语言标签。 */
+  readonly tags: boolean;
+  /** 环境提示词里的文本与情绪写法。 */
+  readonly prompt: string;
+}
+
+const MING3: ModelInfo = {
+  match: ['ming3', 'ming-3', 'ming_3'],
+  label: 'Ming 3.0',
+  tags: true,
+  prompt: '支持 [Laughter] [Sigh] [Breathing] [Uhm] [Question-ei] 等副语言标签;情绪可用 instruct/emotion.',
+};
+
+const INDEXTTS2: ModelInfo = {
+  match: ['index-tts2', 'index_tts2', 'index-tts2.5', 'index_tts2_5', '2.5'],
+  label: 'IndexTTS2',
+  tags: false,
+  prompt: '情绪用自然语言(emotion_text),不要写 [Laughter] 这类方括号标签;采样/时长参数在语音模型页配置,不要写进正文.',
+};
+
+const GENERIC: ModelInfo = {
+  match: [],
+  label: '',
+  tags: false,
+  prompt: '用 instructions 描述语气;不要用方括号标签,除非确认模型支持.',
+};
+
+const KNOWN: readonly ModelInfo[] = [MING3, INDEXTTS2];
+
+function normalize(model: string): string {
+  return typeof model === 'string' ? model.trim().toLowerCase() : '';
+}
+
+function profileOf(model: string): ModelInfo | null {
+  const id = normalize(model);
+  if (!id) return null;
+  return KNOWN.find((info) => info.match.some((prefix) => id.startsWith(prefix))) ?? null;
+}
+
+/** 当前模型是否支持副语言标签;未知与空模型按通用模型处理,返回 false。 */
+export function modelSupportsTags(model: string): boolean {
+  return profileOf(model)?.tags ?? GENERIC.tags;
+}
+
+/** 给人看的模型名;未知或空模型返回空串,由调用方退回模型 id。 */
+export function modelLabel(model: string): string {
+  return profileOf(model)?.label ?? '';
+}
+
+/** 环境提示词里的文本与情绪写法;空模型与未知模型用通用片段。 */
+export function modelPrompt(model: string): string {
+  return (profileOf(model) ?? GENERIC).prompt;
+}

package/src/panel.ts

@@ -0,0 +1,48 @@
+/**
+ * 「模型」面板的数据形状。服务端经由 `World.webUi().invoke` 构造,浏览器端只
+ * `import type` 这些声明;面板不接触服务地址与令牌。
+ */
+import type { VoiceModel, VoiceModelStyle } from './types.ts';
+
+/** 一个模型在面板里的已保存状态。 */
+export interface PanelModelSetting {
+  voice: string;
+  style: VoiceModelStyle;
+  options: Record<string, unknown>;
+}
+
+export interface PanelModelState {
+  /** `worlds.voice.model`。 */
+  model: string;
+  /** 当前模型的音色。 */
+  voice: string;
+  /** 当前模型的环境提示词片段,来自 `models.ts`。 */
+  prompt: string;
+  /** 每个模型的环境提示词片段,切换模型时立即更新。 */
+  prompts: Record<string, string>;
+  /** 当前模型已保存的请求参数。 */
+  options: Record<string, unknown>;
+  /** 当前模型生效的朗读风格;没有专属设置时回落到全局值。 */
+  style: VoiceModelStyle;
+  /** 服务目录;服务不可达时是上一次可用的结果。 */
+  models: VoiceModel[];
+  /** 每个模型的音色、风格与请求参数;面板切模型时不用等保存。 */
+  settings: Record<string, PanelModelSetting>;
+  /** 最近一次读取服务目录失败的原因。 */
+  error?: string;
+}
+
+/** `invoke('model','save', [save])` 的请求体。 */
+export interface PanelModelSave {
+  model: string;
+  voice: string;
+  style?: Partial<VoiceModelStyle>;
+  options: Record<string, unknown>;
+}
+
+/** 只认普通对象:数组、null 与类对象都不算。 */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}

package/src/service.ts

@@ -5,7 +5,8 @@
  * 令牌只从 secret() 现读,不写日志、不留副本。
  */
 import type {
-  AudioFormat, ModelOption, ServiceHealth, TtsAudio, TtsRequest, VoiceConfigSection, VoiceOption,
+  AudioFormat, ModelParameter, ModelParameterType, ServiceHealth, TtsAudio, TtsRequest,
+  VoiceConfigSection, VoiceModel, VoiceOption,
 } from './types.ts';
 
 const PROBE_TIMEOUT_MS = 8000;
@@ -37,6 +38,9 @@ export class ServiceClient implements SpeechService {
     };
     const model = cfg.model.trim();
     if (model) body.model = model;
+    // 只带当前模型自己的参数;其他模型的配置不混进这次请求。
+    const options = cfg.modelOptions?.[model];
+    if (options && Object.keys(options).length > 0) body.options = options;
     const voice = (req.voice ?? '').trim() || cfg.voice.trim();
     if (voice) body.voice = voice;
     const instruct = (req.instruct ?? '').trim();
@@ -96,7 +100,7 @@ export class ServiceClient implements SpeechService {
     }
   }
 
-  async models(): Promise<ModelOption[]> {
+  async models(): Promise<VoiceModel[]> {
     const payload = await this.request(
       this.endpoint('/v1/models'),
       { method: 'GET', headers: this.headers() },
@@ -105,9 +109,9 @@ export class ServiceClient implements SpeechService {
       (res) => this.readJson(res),
     ) as { data?: unknown } | unknown[] | null;
     const raw = Array.isArray(payload) ? payload : Array.isArray(payload?.data) ? payload.data : [];
-    return raw.flatMap((item): ModelOption[] => {
-      const option = optionOf(item);
-      return option ? [option] : [];
+    return raw.flatMap((item): VoiceModel[] => {
+      const model = modelOf(item);
+      return model ? [model] : [];
     });
   }
 
@@ -234,6 +238,83 @@ function optionOf(item: unknown): { value: string; label: string } | null {
   return { value, label };
 }
 
+const PARAMETER_TYPES = new Set<ModelParameterType>([
+  'string', 'enum', 'bool', 'int', 'float', 'string_list', 'path', 'path_list',
+]);
+
+function firstString(...values: unknown[]): string {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+
+/** 目录里的音色/取值可能写成字符串,也可能写成对象;只留去重后的字符串。 */
+function stringItems(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const item of value) {
+    const text = typeof item === 'string'
+      ? item.trim()
+      : item && typeof item === 'object' && !Array.isArray(item)
+        ? firstString(
+          (item as Record<string, unknown>).value,
+          (item as Record<string, unknown>).id,
+          (item as Record<string, unknown>).name,
+          (item as Record<string, unknown>).label,
+        )
+        : '';
+    if (text && !out.includes(text)) out.push(text);
+  }
+  return out;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function parameterOf(item: unknown): ModelParameter | null {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const o = item as Record<string, unknown>;
+  const name = firstString(o.name);
+  const type = firstString(o.type) as ModelParameterType;
+  if (!name || !PARAMETER_TYPES.has(type)) return null;
+  const description = firstString(o.description);
+  const values = stringItems(o.values);
+  const min = finiteNumber(o.min);
+  const max = finiteNumber(o.max);
+  return {
+    name,
+    type,
+    ...(description ? { description } : {}),
+    ...(values.length ? { values } : {}),
+    ...(o.default !== undefined ? { default: o.default } : {}),
+    ...(min !== undefined ? { min } : {}),
+    ...(max !== undefined ? { max } : {}),
+  };
+}
+
+/** 服务目录的一项:模型 id、显示名、音色与请求参数;不认识的字段不带走。 */
+function modelOf(item: unknown): VoiceModel | null {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const o = item as Record<string, unknown>;
+  const id = firstString(o.id, o.value, o.name);
+  if (!id) return null;
+  const label = firstString(o.display_name, o.displayName, o.label);
+  const parameters = Array.isArray(o.parameters)
+    ? o.parameters.flatMap((entry): ModelParameter[] => {
+      const parameter = parameterOf(entry);
+      return parameter ? [parameter] : [];
+    })
+    : [];
+  return {
+    id,
+    ...(label ? { label } : {}),
+    voices: stringItems(o.voices),
+    ...(parameters.length ? { parameters } : {}),
+  };
+}
+
 /** 音频回应只接受 wav / mpeg;octet-stream 按请求的格式归一。 */
 function normalizeMime(raw: string | null, format: AudioFormat): string | null {
   const type = (raw ?? '').split(';')[0]!.trim().toLowerCase();

package/src/speech/tags.ts

@@ -57,10 +57,15 @@ export function stripUnknownTags(text: string): string {
 }
 
 /**
- * auto 保留标签,由服务里的模型决定演不演;keep 一律保留;strip 一律删掉。
+ * auto 只在当前模型支持标签时保留;keep 一律保留;strip 一律删掉。
  */
-export function keepsParalinguistic(mode: 'auto' | 'keep' | 'strip'): boolean {
-  return mode !== 'strip';
+export function keepsParalinguistic(
+  mode: 'auto' | 'keep' | 'strip',
+  tagsSupported: boolean,
+): boolean {
+  if (mode === 'strip') return false;
+  if (mode === 'keep') return true;
+  return tagsSupported;
 }
 
 const EMOTION_MARKERS: ReadonlyArray<RegExp> = [

package/src/speech/text.ts

@@ -1,4 +1,5 @@
 /** 把一段回复变成能念的正文:取 `<tts>`、去代码/网址/Markdown/动作标记/符号。 */
+import { modelSupportsTags } from '../models.ts';
 import type { VoiceConfigSection } from '../types.ts';
 import {
   canonicalizeTags,
@@ -86,7 +87,9 @@ export function filterSpeech(raw: string, cfg: VoiceConfigSection): FilteredSpee
 
   text = canonicalizeTags(text);
   text = stripUnknownTags(text);
-  if (!keepsParalinguistic(cfg.paralinguistic)) text = stripParalinguisticTags(text);
+  if (!keepsParalinguistic(cfg.paralinguistic, modelSupportsTags(cfg.model))) {
+    text = stripParalinguisticTags(text);
+  }
 
   if (cfg.filterEmoji) text = text.replace(EMOJI_RE, '').replace(SYMBOL_RE, '');
 

package/src/types.ts

@@ -7,6 +7,17 @@ export type EmotionMode = 'instruct' | 'categorical' | 'basic' | 'tags' | 'none'
 export type ParalinguisticMode = 'auto' | 'keep' | 'strip';
 export type PlaybackMode = 'local' | 'event' | 'none';
 
+/** 单个模型的朗读风格;缺省字段回落到 `worlds.voice` 上的全局同名值。 */
+export interface VoiceModelStyle {
+  voice: string;
+  emotionMode: EmotionMode;
+  defaultEmotion: string;
+  defaultInstruct: string;
+  /** 语速倍率;1 为原速。 */
+  speed: number;
+  paralinguistic: ParalinguisticMode;
+}
+
 /** `config.json` 的 `worlds.voice` 段。 */
 export interface VoiceConfigSection {
   enabled: boolean;
@@ -17,11 +28,16 @@ export interface VoiceConfigSection {
   /** 服务令牌的环境变量名;空表示服务不校验。 */
   serviceTokenSecret: string;
   model: string;
+  /** 旧的全局音色;只作为没有模型专属设置时的回落值。 */
   voice: string;
+  /** 模型专属的 request 参数,按模型 id 分组;由「模型」面板写回,不进 ConfigGroup。 */
+  modelOptions: Record<string, Record<string, unknown>>;
+  /** 模型专属的朗读风格;由「模型」面板写回,不进 ConfigGroup。 */
+  modelStyles: Record<string, Partial<VoiceModelStyle>>;
   format: AudioFormat;
   timeoutMs: number;
 
-  // 音色与情绪
+  // 朗读风格的全局回落值(旧配置仍可用;界面上已移到模型页)
   emotionMode: EmotionMode;
   defaultEmotion: string;
   defaultInstruct: string;
@@ -90,7 +106,36 @@ export interface SelectOption {
 }
 
 export type VoiceOption = SelectOption;
-export type ModelOption = SelectOption;
+
+/** 服务 `GET /v1/models` 里 `parameters[].type` 的取值。 */
+export type ModelParameterType =
+  | 'string'
+  | 'enum'
+  | 'bool'
+  | 'int'
+  | 'float'
+  | 'string_list'
+  | 'path'
+  | 'path_list';
+
+/** 模型请求参数的元数据;服务按模型给出,面板据此渲染字段。 */
+export interface ModelParameter {
+  name: string;
+  type: ModelParameterType;
+  description?: string;
+  values?: string[];
+  default?: unknown;
+  min?: number;
+  max?: number;
+}
+
+/** 服务目录里的一项模型;音色与请求参数元数据随模型走。 */
+export interface VoiceModel {
+  id: string;
+  label?: string;
+  voices: string[];
+  parameters?: ModelParameter[];
+}
 
 /** `GET /health` 的摘要;`ok` 只表示网关有回应,`ready` 表示至少有一个服务能合成。 */
 export interface ServiceHealth {

package/src/world.ts

@@ -14,11 +14,12 @@ import type {
   Logger, ToolDef, ToolOutcome, World, WorldHost, WorldLamp, WorldWebUiDecl,
 } from 'cortico/core/types.ts';
 import { nullLogger, nowIso } from 'cortico/core/util.ts';
-import { VOICE_DEFAULTS, VOICE_ID, VOICE_MODELS_KIND, VOICE_OPTIONS_KIND, voiceConfigGroups, voiceText } from './config.ts';
+import { modelStyle, styledConfig, VOICE_DEFAULTS, VOICE_ID, voiceConfigGroups, voiceText } from './config.ts';
 import type { AudioPlayer } from './audio/player.ts';
 import { createPlayer } from './audio/player.ts';
 import { SpeechQueue, type SpeechJob } from './audio/queue.ts';
-import { registerOptions, unregisterOptions } from './options.ts';
+import { modelPrompt } from './models.ts';
+import { isPlainObject, type PanelModelSetting, type PanelModelState } from './panel.ts';
 import { ServiceClient, type SpeechService } from './service.ts';
 import { splitSpeech, truncateSpeech } from './speech/chunk.ts';
 import { buildInstruct, resolveStyle } from './speech/style.ts';
@@ -26,14 +27,14 @@ import { filterSpeech } from './speech/text.ts';
 import { EventPoller, eventTypes, hasKeyword, latestUserText, splitList, VoiceTap } from './triggers.ts';
 import { VOICE_TOOL_DECLS } from './tools.ts';
 import type {
-  ModelOption, ServiceHealth, TtsAudio, TtsRequest, VoiceConfigSection, VoiceOption,
+  EmotionMode, ParalinguisticMode, ServiceHealth, TtsAudio, TtsRequest, VoiceConfigSection,
+  VoiceModel, VoiceModelStyle,
 } from './types.ts';
 
 const ENV_PROMPT_FILE = fileURLToPath(new URL('./ENV_PROMPT.md', import.meta.url));
 const DEDUPE_WINDOW_MS = 5000;
 const HEALTH_INTERVAL_MS = 15_000;
 const HEALTH_TTL_MS = 15_000;
-const CATALOG_TTL_MS = 10 * 60_000;
 
 export interface VoiceWorldDeps {
   fetch: typeof fetch;
@@ -130,18 +131,11 @@ export class VoiceWorld implements World {
   private tempSeq = 0;
   private serviceState: ServiceState | null = null;
   private probing = false;
-  private voices: VoiceOption[] = [];
-  private voicesAt = 0;
-  private voicesSignature = '';
-  private voicesLoading = false;
-  private models: ModelOption[] = [];
-  private modelsAt = 0;
-  private modelsSignature = '';
-  private modelsLoading = false;
+  private catalog: VoiceModel[] | null = null;
+  private catalogError: string | undefined;
+  private catalogLoad: Promise<void> | null = null;
   private readonly lastSpoken = new Map<string, number>();
   private lastFailureAt = 0;
-  private readonly modelOptions = (): readonly ModelOption[] => this.models;
-  private readonly voiceOptions = (): readonly VoiceOption[] => this.voices;
 
   constructor(private readonly opts: VoiceWorldOptions) {
     this.log = opts.log ?? nullLogger();
@@ -149,7 +143,7 @@ export class VoiceWorld implements World {
     this.service = this.deps.service ?? new ServiceClient({
       fetch: this.deps.fetch,
       secret: (name) => this.opts.secret(name),
-      cfg: () => this.cfg,
+      cfg: () => this.styled,
     });
     this.player = this.deps.createPlayer(this.log);
     this.queue = new SpeechQueue({
@@ -173,13 +167,19 @@ export class VoiceWorld implements World {
     return this.opts.cfg;
   }
 
+  /** 当前模型的配置视图:模型专属的朗读风格盖在全局值上。 */
+  private get styled(): VoiceConfigSection {
+    return styledConfig(this.cfg, this.cfg.model);
+  }
+
   envPromptVars(): Record<string, string> {
-    const cfg = this.cfg;
+    const cfg = this.styled;
     return {
-      'voice.auto': cfg.autoSpeak ? `${Math.round(cfg.autoProbability * 100)}%` : 'off',
+      'voice.auto': this.cfg.autoSpeak ? `${Math.round(this.cfg.autoProbability * 100)}%` : 'off',
       'voice.voice': cfg.voice || 'default',
       'voice.emotion': cfg.defaultEmotion || 'neutral',
       'voice.instruct': cfg.defaultInstruct || 'none',
+      'voice.modelPrompt': modelPrompt(this.cfg.model),
     };
   }
 
@@ -202,7 +202,7 @@ export class VoiceWorld implements World {
   webUi(language: Language = 'zh'): WorldWebUiDecl {
     const t = voiceText(language);
     this.maybeRefresh();
-    const cfg = this.cfg;
+    const cfg = this.styled;
     const stats = this.queue.stats();
     const serviceLamp: WorldLamp = this.serviceState === null
       ? { label: t.lampService, state: this.started ? 'loading' : 'offline' }
@@ -224,8 +224,22 @@ export class VoiceWorld implements World {
         { label: 'model', value: cfg.model || '—', tone: 'plain' },
         { label: 'voice', value: cfg.voice || '—', tone: 'plain' },
       ],
+      panels: [{ id: 'model', title: t.modelPanel, getMethods: ['state'] }],
       config: voiceConfigGroups(language),
       links: [{ label: t.servicePage, href: '#/provider/world:service' }],
+      invoke: async (panel, method, args) => {
+        if (panel !== 'model') throw new Error(t.modelUnknownMethod);
+        switch (method) {
+          case 'state':
+            return this.modelPanelState();
+          case 'refresh':
+            return this.refreshModelPanel();
+          case 'save':
+            return this.saveModelPanel(language, args);
+          default:
+            throw new Error(t.modelUnknownMethod);
+        }
+      },
       promptDocs: [{
         key: 'worlds.voice.envPrompt',
         title: t.envTitle,
@@ -237,11 +251,177 @@ export class VoiceWorld implements World {
           { name: 'voice.voice', description: 'Current voice id.' },
           { name: 'voice.emotion', description: 'Standing emotion.' },
           { name: 'voice.instruct', description: 'Standing direction.' },
+          { name: 'voice.modelPrompt', description: 'How to write text and emotion for the current model.' },
         ],
       }],
     };
   }
 
+  // ———————— 模型面板 ————————
+
+  /**
+   * 第一次读面板时拉一次目录;之后直接回缓存。刷新失败保留上一次可用的目录,
+   * 只把错误一起交回面板。
+   */
+  private async modelPanelState(): Promise<PanelModelState> {
+    if (!this.catalog) await this.loadCatalog(this.cfg.model);
+    return this.panelSnapshot();
+  }
+
+  private async refreshModelPanel(): Promise<PanelModelState> {
+    if (this.catalogLoad) await this.catalogLoad;
+    await this.loadCatalog(this.cfg.model);
+    return this.panelSnapshot();
+  }
+
+  private panelSnapshot(): PanelModelState {
+    const cfg = this.cfg;
+    const settings = this.panelSettings();
+    const current = settings[cfg.model];
+    const style = current?.style ?? modelStyle(cfg, cfg.model);
+    return {
+      model: cfg.model,
+      voice: style.voice,
+      prompt: modelPrompt(cfg.model),
+      prompts: Object.fromEntries(Object.keys(settings).map((id) => [id, modelPrompt(id)])),
+      options: current?.options ?? {},
+      style,
+      models: this.catalog ?? [],
+      settings,
+      ...(this.catalogError ? { error: this.catalogError } : {}),
+    };
+  }
+
+  /** 目录里每个模型的音色、风格与参数;当前模型与已保存过设置的模型也各带一条。 */
+  private panelSettings(): Record<string, PanelModelSetting> {
+    const ids = new Set((this.catalog ?? []).map((model) => model.id));
+    if (this.cfg.model.trim()) ids.add(this.cfg.model.trim());
+    for (const id of Object.keys(this.cfg.modelStyles ?? {})) if (id.trim()) ids.add(id);
+    for (const id of Object.keys(this.cfg.modelOptions ?? {})) if (id.trim()) ids.add(id);
+    const out: Record<string, PanelModelSetting> = {};
+    for (const id of ids) {
+      const style = modelStyle(this.cfg, id);
+      const saved = this.cfg.modelOptions?.[id];
+      out[id] = {
+        voice: style.voice,
+        style,
+        options: isPlainObject(saved) ? { ...saved } : {},
+      };
+    }
+    return out;
+  }
+
+  private loadCatalog(selected: string): Promise<void> {
+    if (this.catalogLoad) return this.catalogLoad;
+    this.catalogLoad = this.fetchCatalog(selected).finally(() => {
+      this.catalogLoad = null;
+    });
+    return this.catalogLoad;
+  }
+
+  /**
+   * 先取模型表,再尽力为当前模型补一次更细的音色表。模型表是权威来源,已经带
+   * 音色与参数;补音色失败只损失一次补全,不能让整份目录跟着作废。
+   */
+  private async fetchCatalog(selected: string): Promise<void> {
+    let models: VoiceModel[];
+    try {
+      models = await this.service.models();
+    } catch (error) {
+      this.catalogError = this.catalogFailure(error);
+      this.markService({ ok: false, detail: this.catalogError });
+      return;
+    }
+
+    const id = selected.trim() || this.cfg.model.trim() || models[0]?.id || '';
+    let catalog = models;
+    if (id) {
+      try {
+        const voices = await this.service.voices(id);
+        const names = [...new Set(voices.map((voice) => voice.value.trim()).filter(Boolean))];
+        if (names.length > 0) {
+          catalog = models.map((model) => (model.id === id ? { ...model, voices: names } : model));
+        }
+      } catch (error) {
+        this.log.debug('音色表读取失败,保留模型表里的音色', {
+          err: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    this.catalog = catalog;
+    this.catalogError = undefined;
+    this.markService({ ok: true });
+  }
+
+  /** 错误要回面板,但不能把配置里的服务地址(可能带令牌)一起带出去。 */
+  private catalogFailure(error: unknown): string {
+    const message = error instanceof Error ? error.message : String(error);
+    const url = this.cfg.serviceUrl.trim();
+    return url && message.includes(url) ? message.split(url).join('[service]') : message;
+  }
+
+  private saveModelPanel(language: Language, args: unknown[]): PanelModelState {
+    const t = voiceText(language);
+    const raw = args[0];
+    if (!isPlainObject(raw)) throw new Error(t.modelSaveShape);
+    const model = typeof raw.model === 'string' ? raw.model.trim() : '';
+    if (!model) throw new Error(t.modelSaveModel);
+    if (typeof raw.voice !== 'string') throw new Error(t.modelSaveVoice);
+    if (raw.style !== undefined && !isPlainObject(raw.style)) throw new Error(t.modelSaveStyle);
+    if (!isPlainObject(raw.options)) throw new Error(t.modelSaveOptions);
+
+    const style = this.readModelStyle(raw.style, model, raw.voice.trim(), t.modelSaveStyle);
+    const nextStyles: VoiceConfigSection['modelStyles'] = { ...(this.cfg.modelStyles ?? {}) };
+    nextStyles[model] = style;
+
+    const nextOptions: VoiceConfigSection['modelOptions'] = { ...(this.cfg.modelOptions ?? {}) };
+    // 空对象表示删掉这个模型的条目,回到服务的默认参数。
+    if (Object.keys(raw.options).length === 0) delete nextOptions[model];
+    else nextOptions[model] = { ...raw.options };
+    // 配置层对对象做深合并,删掉的键不会随 patch 传播;先让活引用指向新对象再写盘。
+    this.cfg.modelStyles = nextStyles;
+    this.cfg.modelOptions = nextOptions;
+    this.opts.persist({ model, modelStyles: nextStyles, modelOptions: nextOptions });
+    return this.panelSnapshot();
+  }
+
+  /** 面板传来的风格字段逐个校验;没给的字段沿用这个模型当前生效的值。 */
+  private readModelStyle(
+    raw: Record<string, unknown> | undefined,
+    model: string,
+    voice: string,
+    shapeError: string,
+  ): VoiceModelStyle {
+    const current = modelStyle(this.cfg, model);
+    if (!raw) return { ...current, voice };
+
+    const emotionModes: readonly EmotionMode[] = ['instruct', 'categorical', 'basic', 'tags', 'none'];
+    const paralinguisticModes: readonly ParalinguisticMode[] = ['auto', 'keep', 'strip'];
+    const emotionMode = raw.emotionMode ?? current.emotionMode;
+    if (typeof emotionMode !== 'string' || !emotionModes.includes(emotionMode as EmotionMode)) {
+      throw new Error(shapeError);
+    }
+    const paralinguistic = raw.paralinguistic ?? current.paralinguistic;
+    if (typeof paralinguistic !== 'string' || !paralinguisticModes.includes(paralinguistic as ParalinguisticMode)) {
+      throw new Error(shapeError);
+    }
+    const defaultEmotion = raw.defaultEmotion ?? current.defaultEmotion;
+    if (typeof defaultEmotion !== 'string') throw new Error(shapeError);
+    const defaultInstruct = raw.defaultInstruct ?? current.defaultInstruct;
+    if (typeof defaultInstruct !== 'string') throw new Error(shapeError);
+    const rawSpeed = raw.speed ?? current.speed;
+    if (typeof rawSpeed !== 'number' || !Number.isFinite(rawSpeed)) throw new Error(shapeError);
+    return {
+      voice,
+      emotionMode: emotionMode as EmotionMode,
+      defaultEmotion: defaultEmotion.trim().slice(0, 40),
+      defaultInstruct: defaultInstruct.trim().slice(0, 500),
+      speed: Math.min(2, Math.max(0.5, rawSpeed)),
+      paralinguistic: paralinguistic as ParalinguisticMode,
+    };
+  }
+
   outputTap() {
     const cfg = this.cfg;
     if (!cfg.autoSpeak) return undefined;
@@ -252,7 +432,6 @@ export class VoiceWorld implements World {
   async start(host: WorldHost): Promise<void> {
     this.host = host;
     this.started = true;
-    this.registerCatalogOptions();
     this.log.info('语音 World 启动', {
       service: serviceHost(this.cfg.serviceUrl),
       playback: this.cfg.playback,
@@ -271,7 +450,6 @@ export class VoiceWorld implements World {
 
   async stop(): Promise<void> {
     this.started = false;
-    this.unregisterCatalogOptions();
     if (this.healthTimer) clearInterval(this.healthTimer);
     this.healthTimer = null;
     this.poller?.stop();
@@ -302,7 +480,7 @@ export class VoiceWorld implements World {
     const cfg = this.cfg;
     if (!cfg.autoSpeak) return;
 
-    const filtered = filterSpeech(raw, cfg);
+    const filtered = filterSpeech(raw, this.styled);
     if (!filtered.text) return;
 
     const userText = cfg.explicitTrigger
@@ -343,7 +521,7 @@ export class VoiceWorld implements World {
   // ———————— 工具 ————————
 
   private async handleSpeak(args: Record<string, unknown>): Promise<ToolOutcome> {
-    const filtered = filterSpeech(asString(args.text), this.cfg);
+    const filtered = filterSpeech(asString(args.text), this.styled);
     if (!filtered.text) return { text: 'voice_speak failed: there is nothing to say.', failed: true };
     const silent = args.silent === true || this.cfg.playback === 'none';
     const share = this.cfg.shareAudio || silent;
@@ -394,27 +572,47 @@ export class VoiceWorld implements World {
 
   private async handleStyle(args: Record<string, unknown>): Promise<ToolOutcome> {
     const has = (key: string): boolean => Object.prototype.hasOwnProperty.call(args, key);
-    const patch: Partial<VoiceConfigSection> = {};
-    if (has('emotion')) patch.defaultEmotion = asString(args.emotion).slice(0, 40);
-    if (has('instruct')) patch.defaultInstruct = asString(args.instruct).slice(0, 500);
-    if (has('voice')) patch.voice = asString(args.voice).slice(0, 200);
+    const model = this.cfg.model.trim();
+    if (!model) {
+      // 还没选模型时写到全局回落值;模型页仍可之后覆盖。
+      const patch: Partial<VoiceConfigSection> = {};
+      if (has('emotion')) patch.defaultEmotion = asString(args.emotion).slice(0, 40);
+      if (has('instruct')) patch.defaultInstruct = asString(args.instruct).slice(0, 500);
+      if (has('voice')) patch.voice = asString(args.voice).slice(0, 200);
+      if (has('speed')) {
+        const speed = asNumber(args.speed);
+        if (speed !== undefined) patch.speed = Math.min(2, Math.max(0.5, speed));
+      }
+      if (Object.keys(patch).length > 0) {
+        this.opts.persist(patch);
+        return { text: `Voice style updated. ${this.styleSummary()}` };
+      }
+      return { text: this.styleSummary() };
+    }
+
+    const current = modelStyle(this.cfg, model);
+    const next: VoiceModelStyle = { ...current };
+    if (has('emotion')) next.defaultEmotion = asString(args.emotion).slice(0, 40);
+    if (has('instruct')) next.defaultInstruct = asString(args.instruct).slice(0, 500);
+    if (has('voice')) next.voice = asString(args.voice).slice(0, 200);
     if (has('speed')) {
       const speed = asNumber(args.speed);
-      if (speed !== undefined) patch.speed = Math.min(2, Math.max(0.5, speed));
+      if (speed !== undefined) next.speed = Math.min(2, Math.max(0.5, speed));
     }
-    if (Object.keys(patch).length > 0) {
-      this.opts.persist(patch);
-      if (patch.voice !== undefined) void this.refreshVoices(true);
+    if (Object.keys(next).some((key) => next[key as keyof VoiceModelStyle] !== current[key as keyof VoiceModelStyle])) {
+      const modelStyles: VoiceConfigSection['modelStyles'] = { ...(this.cfg.modelStyles ?? {}), [model]: next };
+      this.cfg.modelStyles = modelStyles;
+      this.opts.persist({ modelStyles });
       return { text: `Voice style updated. ${this.styleSummary()}` };
     }
     return { text: this.styleSummary() };
   }
 
   private styleSummary(): string {
-    const cfg = this.cfg;
+    const cfg = this.styled;
     return `Voice: ${cfg.voice || 'default'}; emotion: ${cfg.defaultEmotion || 'neutral'}; `
       + `direction: ${cfg.defaultInstruct || 'none'}; speed: ${cfg.speed}; `
-      + `automatic: ${cfg.autoSpeak ? `${Math.round(cfg.autoProbability * 100)}%` : 'off'}.`;
+      + `automatic: ${this.cfg.autoSpeak ? `${Math.round(this.cfg.autoProbability * 100)}%` : 'off'}.`;
   }
 
   private spokenOutcome(audio: TtsAudio | undefined, seconds: number, silent: boolean): ToolOutcome {
@@ -448,7 +646,7 @@ export class VoiceWorld implements World {
     style: { emotion?: string; instruct?: string; voice?: string; speed?: number },
     signal: AbortSignal,
   ): Promise<TtsAudio> {
-    const cfg = this.cfg;
+    const cfg = this.styled;
     const resolved = resolveStyle(cfg, style);
     const request: TtsRequest = {
       text,
@@ -494,7 +692,7 @@ export class VoiceWorld implements World {
         origin: 'internal',
         senderKey: this.id,
         text: `Spoken line: ${chunk.slice(0, 100)}`,
-        meta: { source: job.source, voice: this.cfg.voice, emotion: this.cfg.defaultEmotion },
+        meta: { source: job.source, voice: this.styled.voice, emotion: this.styled.defaultEmotion },
         blobs: [{
           bytes: audio.bytes,
           mime: audio.mime,
@@ -527,7 +725,7 @@ export class VoiceWorld implements World {
     } catch { /* 只归档,失败就只留日志 */ }
   }
 
-  // ———————— 状态与目录 ————————
+  // ———————— 状态 ————————
 
   private markService(state: Pick<ServiceState, 'ok' | 'detail'>): void {
     const previous = this.serviceState;
@@ -540,8 +738,6 @@ export class VoiceWorld implements World {
 
   private async probe(): Promise<void> {
     if (this.probing) return;
-    // 探活会刷新目录;每次探活都重新登记,停用后重新启用的实例也能接上。
-    this.registerCatalogOptions();
     this.probing = true;
     try {
       const health: ServiceHealth = await this.service.health();
@@ -554,9 +750,6 @@ export class VoiceWorld implements World {
     } finally {
       this.probing = false;
     }
-    // 探活顺带刷新目录;读不到时 refresh 会保留上一次的表。
-    await this.refreshVoices(true);
-    await this.refreshModels(true);
   }
 
   private maybeRefresh(): void {
@@ -565,56 +758,6 @@ export class VoiceWorld implements World {
     if (!this.probing && (this.serviceState === null || now - this.serviceState.at > HEALTH_TTL_MS)) {
       void this.probe();
     }
-    if (now - this.voicesAt > CATALOG_TTL_MS) void this.refreshVoices();
-    if (now - this.modelsAt > CATALOG_TTL_MS) void this.refreshModels();
-  }
-
-  private async refreshVoices(force = false): Promise<void> {
-    const cfg = this.cfg;
-    const signature = `${cfg.serviceUrl.trim()}|${cfg.model.trim()}`;
-    if (this.voicesLoading && !force) return;
-    if (!force && signature === this.voicesSignature && this.deps.now() - this.voicesAt < CATALOG_TTL_MS) return;
-    this.voicesLoading = true;
-    try {
-      const list = await this.service.voices(cfg.model);
-      if (signature !== `${this.cfg.serviceUrl.trim()}|${this.cfg.model.trim()}`) return;
-      this.voices = list;
-      this.voicesSignature = signature;
-      this.voicesAt = this.deps.now();
-    } catch (error) {
-      this.log.debug('音色表读取失败', { err: error instanceof Error ? error.message : String(error) });
-    } finally {
-      this.voicesLoading = false;
-    }
-  }
-
-  private async refreshModels(force = false): Promise<void> {
-    const signature = this.cfg.serviceUrl.trim();
-    if (this.modelsLoading && !force) return;
-    if (!force && signature === this.modelsSignature && this.deps.now() - this.modelsAt < CATALOG_TTL_MS) return;
-    this.modelsLoading = true;
-    try {
-      const list = await this.service.models();
-      if (signature !== this.cfg.serviceUrl.trim()) return;
-      this.models = list;
-      this.modelsSignature = signature;
-      this.modelsAt = this.deps.now();
-    } catch (error) {
-      this.log.debug('模型表读取失败', { err: error instanceof Error ? error.message : String(error) });
-    } finally {
-      this.modelsLoading = false;
-    }
-  }
-
-  /** 下拉读的是缓存表;服务读不到时保留上一次的结果。当前值由框架补入。 */
-  private registerCatalogOptions(): void {
-    registerOptions(VOICE_MODELS_KIND, this.modelOptions);
-    registerOptions(VOICE_OPTIONS_KIND, this.voiceOptions);
-  }
-
-  private unregisterCatalogOptions(): void {
-    unregisterOptions(VOICE_MODELS_KIND, this.modelOptions);
-    unregisterOptions(VOICE_OPTIONS_KIND, this.voiceOptions);
   }
 
   private syncPoller(): void {
@@ -655,4 +798,4 @@ export class VoiceWorld implements World {
   }
 }
 
-export { VOICE_DEFAULTS, VOICE_ID, VOICE_MODELS_KIND, VOICE_OPTIONS_KIND };
+export { VOICE_DEFAULTS, VOICE_ID };

package/src/options.ts

@@ -1,36 +0,0 @@
-/**
- * 配置页的模型与音色下拉要读运行中实例从服务探到的目录,但
- * `WorldDefinition.configOptions` 是静态签名。实例启动或探活时把读取函数注册进来;
- * 只支持 `voice.models` 与 `voice.voices` 两种 kind,未知 kind 返回空。
- * 读的是已经缓存的表,不在配置页里发请求;服务不可达时保留上次的表,没有就是空表。
- * 当前值不在表里时由框架补入,这里不重复做。
- */
-import { VOICE_MODELS_KIND, VOICE_OPTIONS_KIND } from './config.ts';
-import type { SelectOption } from './types.ts';
-
-export const OPTION_KINDS = [VOICE_MODELS_KIND, VOICE_OPTIONS_KIND] as const;
-export type OptionKind = (typeof OPTION_KINDS)[number];
-
-type Provider = () => readonly SelectOption[];
-
-const providers = new Map<OptionKind, Provider>();
-
-function isOptionKind(kind: string): kind is OptionKind {
-  return kind === VOICE_MODELS_KIND || kind === VOICE_OPTIONS_KIND;
-}
-
-/** 实例启动或探活时登记;同一 kind 后登记的覆盖先前的。 */
-export function registerOptions(kind: OptionKind, provider: Provider): void {
-  providers.set(kind, provider);
-}
-
-/** 实例停止时撤销自己登记的那一项;已有更新实例登记时不动它。 */
-export function unregisterOptions(kind: OptionKind, provider: Provider): void {
-  if (providers.get(kind) === provider) providers.delete(kind);
-}
-
-/** 未知 kind 返回空数组,框架继续查询其他 World。 */
-export function currentOptions(kind: string): SelectOption[] {
-  if (!isOptionKind(kind)) return [];
-  return [...(providers.get(kind)?.() ?? [])];
-}