dsh-dock 0.15.0 → 0.16.0

package/features/visionproxy/host.js

@@ -8,7 +8,7 @@
 // 其编辑 UI 在模型设置页内（见 features/modelconfig/view.js）。
 import { BlockAssembler } from '@deepseek-ai/dsh-llm'
 import { readDockRoot } from '../../src/host-core.js'
-import { readModelDirectory } from '../modelconfig/host.js'
+import { readModelDirectory } from '../../src/model-directory.js'
 
 /** 递归判断内容块里是否有图片（含 tool-result 嵌套，与官方 contentHasImage 同构）。 */
 function contentHasImageDeep(content) {

package/index.js

@@ -15,17 +15,22 @@
 //   - animation   任务动画（v0.5.0）：会话任务追踪 + 动效配置持久化（参照 @wycto/dsh-task-pulse）
 //   - notify      任务通知：完成/异常/需确认通知 + 提示音/系统通知/钉钉飞书推送（从任务动画拆出）
 //   - runstate    运行状态：进行中任务与最近完成一览（从任务动画拆出；只读，无配置段）
+//   - tts         语音朗读：把会话回复读出来（浏览器 TTS；宿主半部只管配置 + 共享任务追踪）
+//   - modelconfig 模型设置：模型目录的输入模态与思考强度（写回官方配置）
+//   - providerconfig 模型提供商：Provider 增删改 + API Key + 拉取上游模型列表
 //   - mobile      手机适配：窄屏排版/Tab 栏/抽屉/遮罩/键盘（宿主经 tapIndex 注入 index.html）
 //   - mobile-relay 远程访问：账号密码登录的远程入口（网关 + 账号 + 浏览模式目录选择器）
-import { DockConfig, sendJson, readBody, migrateNotifyConfig, migrateModelsFeatureId, migrateImportedFeatures, migrateImportedSections, bindDockConfig, readDockRoot, mutateDockSection } from './src/host-core.js'
+import { DockConfig, sendJson, readBody, rejectUntrustedRequest, migrateNotifyConfig, migrateModelsFeatureId, migrateImportedFeatures, migrateImportedSections, bindDockConfig, readDockRoot, mutateDockSection } from './src/host-core.js'
 import { injectWelcomeAck } from './src/welcome-ack.js'
 import { feature as fModels } from './features/modelconfig/host.js'
+import { feature as fProviderConfig } from './features/providerconfig/host.js'
 import { feature as fVisionProxy } from './features/visionproxy/host.js'
 import { feature as fBalance } from './features/balance/host.js'
 import { feature as fTokenlog } from './features/tokenlog/host.js'
 import { feature as fAnimation } from './features/animation/host.js'
 import { feature as fNotify } from './features/notify/host.js'
 import { feature as fRunState } from './features/runstate/host.js'
+import { feature as fTts } from './features/tts/host.js'
 import { feature as fMobileRelay } from './features/mobile-relay/host.js'
 import { feature as fMobile } from './features/mobile/host.js'
 
@@ -62,12 +67,14 @@ export function apply(ctx, config) {
   // 规划中的功能缺省 false，等实现后移除 roadmap 并打开。
   const FEATURES = [
     fModels,
+    fProviderConfig,
     fVisionProxy,
     fBalance,
     fTokenlog,
     fAnimation,
     fNotify,
     fRunState,
+    fTts,
     fMobileRelay,
     fMobile,
   ]
@@ -193,6 +200,7 @@ export function apply(ctx, config) {
         kind: 'exact',
         path: '/dsh-dock/features',
         handler: async (req, res) => {
+          if (rejectUntrustedRequest(ctx, req, res)) return
           try {
             if (req.method === 'POST') {
               const body = await readBody(req)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-dock",
-  "version": "0.15.0",
-  "description": "DeepSeek Harness 功能坞插件（dsh-dock）：模块化功能中枢——每个功能一个 features/ 模块（可单独提取成包发布，又可经 dockBridge 装回面板）。含用量记录（LLM 调用记账/费用统计，支持各模型自定义单价、多段分时价与周末/节假日谷价）、模型设置、图片理解代理、模型余额、任务动画（19 种运行动画 + 桌面伙伴 3D 场景）、任务通知（完成/异常/需确认通知、提示音、系统通知、钉钉/飞书推送）、运行状态（进行中任务与最近完成一览）；侧栏入口 + 可拖拽弹窗（最大化/最小化/缩放）。",
+  "version": "0.16.0",
+  "description": "DeepSeek Harness 功能坞插件（dsh-dock）：模块化功能中枢——每个功能一个 features/ 模块（可单独提取成包发布，又可经 dockBridge 装回面板）。含用量记录（LLM 调用记账/费用统计，支持各模型自定义单价、多段分时价与周末/节假日谷价）、模型设置、图片理解代理、模型余额、任务动画（19 种运行动画 + 桌面伙伴 3D 场景）、任务通知（完成/异常/需确认通知、提示音、系统通知、钉钉/飞书推送）、运行状态（进行中任务与最近完成一览）、语音朗读（浏览器 TTS 读回复：回合下方喇叭按钮 + 自动朗读）；侧栏入口 + 可拖拽弹窗（最大化/最小化/缩放）。",
   "type": "module",
   "main": "index.js",
   "files": [
@@ -43,7 +43,7 @@
   "scripts": {
     "build:client": "node scripts/build-client.mjs",
     "test:client": "node scripts/test-client-views.mjs",
-    "test:host": "node scripts/test-task-host.mjs && node scripts/test-tokenlog-host.mjs && node scripts/test-legacy-import.mjs && node scripts/test-mobile-host.mjs && node scripts/test-mobile-relay-host.mjs && node scripts/test-mobile-relay.mjs && node scripts/test-welcome-ack.mjs",
+    "test:host": "node scripts/test-task-host.mjs && node scripts/test-tokenlog-host.mjs && node scripts/test-route-trust-host.mjs && node scripts/test-tts-host.mjs && node scripts/test-legacy-import.mjs && node scripts/test-mobile-host.mjs && node scripts/test-mobile-relay-host.mjs && node scripts/test-mobile-relay.mjs && node scripts/test-welcome-ack.mjs",
     "dev:client": "node scripts/watch-client.mjs",
     "dev:link": "node scripts/dev-link-deps.mjs"
   },

package/src/client.jsx

@@ -8,8 +8,8 @@
 // 在浏览器端 require("dsh-dock").dockBridge.register(def) 把自己的视图注册进本面板；
 // dock 未安装时该包走自己的独立面板——「单独成包发布」与「完美集成功能坞」两全。
 //
-// 面板挂载在 settings.section：设置 → 功能坞；侧栏底部另有「功能坞」入口按钮
-// （sidebar.footer.action），点击弹出居中功能面板（shell.overlay）。
+// 面板挂载在 settings.section：设置 → 功能坞；侧栏「··· 更多」弹出菜单里另有「功能坞」
+// 菜单项（settings.launcher.menu.item），点击弹出居中功能面板（shell.overlay）。
 // 弹层窗口：默认大窗，支持最大化/最小化、标题栏拖动、右下角缩放（几何页内记忆）。
 import react from "react";
 import {
@@ -20,21 +20,23 @@ import {
 } from "./shared.js";
 import { feature as fTokenlog } from "../features/tokenlog/view.jsx";
 import { feature as fModelconfig } from "../features/modelconfig/view.js";
+import { feature as fProviderConfig } from "../features/providerconfig/view.js";
 import { feature as fHeartbeat } from "../features/heartbeat/view.js";
 import { feature as fTheme } from "../features/theme/view.js";
 import { feature as fBalance } from "../features/balance/view.js";
 import { feature as fAnimation } from "../features/animation/view.jsx";
 import { feature as fNotify } from "../features/notify/view.jsx";
 import { feature as fRunState } from "../features/runstate/view.jsx";
+import { feature as fTts } from "../features/tts/view.jsx";
 import { feature as fGames } from "../features/games/view.jsx";
 import { feature as fMobileRelay } from "../features/mobile-relay/view.jsx";
 import { feature as fMobile } from "../features/mobile/view.js";
 
 const name = "dsh-dock";
-const DOCK_VERSION = "0.15.0";
+const DOCK_VERSION = "0.16.0";
 
 // ---- 内置功能注册表：新功能 = features/<id>/ 加模块 + 这里 import 一行 ----
-const BUILTIN_FEATURES = [fTokenlog, fModelconfig, fHeartbeat, fTheme, fBalance, fAnimation, fNotify, fRunState, fGames, fMobileRelay, fMobile];
+const BUILTIN_FEATURES = [fTokenlog, fModelconfig, fProviderConfig, fHeartbeat, fTheme, fBalance, fAnimation, fNotify, fRunState, fTts, fGames, fMobileRelay, fMobile];
 // 规划占位（路线图）：接入后移除并建 features/<id>/ 模块
 const PLANNED_FEATURES = [];
 const PLANNED_NOTES = {};
@@ -123,15 +125,16 @@ const SHELL_CSS = [
 	".dock-switch.on{color:var(--dsw-alias-state-success-primary);border-color:var(--dsw-alias-state-success-primary);}",
 	".dock-badge{flex:none;border:1px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);border-radius:999px;padding:3px 10px;font-size:12px;}",
 	".dock-body{border-top:1px solid var(--dsw-alias-border-l1);padding-top:8px;color:var(--dsw-alias-label-secondary);display:flex;flex-direction:column;gap:4px;}",
-	// 侧栏入口按钮（docke2- 前缀）+ 功能坞弹出面板（dockm- 前缀，仿 dsh 设置的居中模态：遮罩 + 对话框，左导航 + 右内容）
-	// 侧栏入口按钮（docke2- 前缀）：与 dsh 设置按钮（.VOzbGW_trigger）几何逐条对齐——
-	// 宽栏同为整宽左对齐行按钮（高 42、margin 4/-2、padding 0 10px 0 8px、圆角 12），窄栏同为 36 圆钮居中，
-	// 使两按钮上下成列、左右边缘完全对齐（此前右对齐/叠放都会错位）。
-	".docke2-btn{box-sizing:border-box;cursor:pointer;display:flex;align-items:center;gap:8px;border:none;background:transparent;color:var(--dsw-alias-label-primary);border-radius:12px;width:calc(100% + 4px);height:42px;margin:4px -2px;padding:0 10px 0 8px;font-family:inherit;font-size:14px;line-height:22px;transition:background .15s var(--ds-ease-in-out),color .15s var(--ds-ease-in-out);}",
-	".docke2-btn:hover{background:var(--dsw-alias-interactive-bg-hover);}",
-	".docke2-btn.docke2-on{color:var(--dk-accent);background:var(--dk-accent-soft);}",
-	".docke2-btn.docke2-rail{width:36px;height:36px;margin:8px 0 10px;padding:0;border-radius:50%;justify-content:center;gap:0;}",
-	".docke2-label{white-space:nowrap;overflow:hidden;}",
+	// 「··· 更多」菜单里的功能坞菜单项（docke2-mi- 前缀）+ 功能坞弹出面板（dockm- 前缀，仿 dsh 设置的居中模态：遮罩 + 对话框，左导航 + 右内容）
+	// 菜单行指标仿宿主内置菜单项（ui-primitives Menu.module.css 的 .item/.itemIcon/.itemLabel）：
+	// 整宽块级行（按钮直接落在菜单视口的 flex 列里）、gap 6、min-height 34、padding 6px 8px、
+	// 圆角 --dsw-radius-md、字号 13/行高 20；悬停与键盘聚焦（宿主菜单走真实焦点）同款高亮背景。
+	".docke2-mi-item{display:flex;align-items:center;gap:6px;box-sizing:border-box;width:100%;min-height:34px;padding:6px 8px;border:none;border-radius:var(--dsw-radius-md);background:transparent;cursor:pointer;font-family:inherit;font-size:13px;line-height:20px;color:var(--dsw-alias-label-primary);text-align:left;}",
+	".docke2-mi-item:hover{background:var(--dsw-alias-interactive-bg-hover);}",
+	".docke2-mi-item:focus-visible{background:var(--dsw-alias-interactive-bg-hover);outline:none;}",
+	".docke2-mi-icon{display:inline-flex;flex:none;width:14px;height:14px;align-items:center;justify-content:center;color:var(--dsw-alias-menu-icon);}",
+	".docke2-mi-icon svg{width:14px;height:14px;}",
+	".docke2-mi-label{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}",
 	// 遮罩固定用深色半透明：亮色主题下宿主 bg-layer-1 是纯白，白底遮罩会让弹窗与页面完全无层次
 	".dockm-backdrop{position:fixed;inset:0;z-index:200;display:flex;align-items:center;justify-content:center;background:rgba(15,17,21,.45);backdrop-filter:blur(4px);pointer-events:auto;animation:dockm-fade .15s var(--ds-ease-in-out);}",
 	"@keyframes dockm-fade{from{opacity:0}to{opacity:1}}",
@@ -300,18 +303,24 @@ function DockIcon(props) {
 		react.createElement("rect", { x: 9, y: 9, width: 4.4, height: 4.4, rx: 1.2 }));
 }
 
-function DockEntry(props) {
-	const wide = !!props.wide;
+// 「··· 更多」菜单里的功能坞菜单项（settings.launcher.menu.item）。
+// 协议约束：恰好一个 role="menuitem" 按钮；宿主 Menu 不会因点击自动关闭，激活时先
+// dismiss()（关闭菜单，宿主负责焦点回还），再切换功能坞弹层；它不是 disclosure 触发器，
+// 不带 aria-expanded/aria-haspopup。开合状态与旧侧栏入口同源：panelNav.open + subscribePanel。
+function DockMenuItem(props) {
 	const [open, setOpen] = react.useState(panelNav.open);
 	react.useEffect(() => subscribePanel(() => setOpen(panelNav.open)), []);
 	return react.createElement("button", {
 		type: "button",
-		className: "docke2-btn" + (open ? " docke2-on" : "") + (wide ? "" : " docke2-rail"),
-		title: "功能坞",
-		"aria-label": "功能坞",
-		"aria-expanded": open,
-		onClick: () => setPanelOpen(!open)
-	}, react.createElement(DockIcon, { size: wide ? 16 : 18 }), wide ? react.createElement("span", { className: "docke2-label" }, "功能坞") : null);
+		role: "menuitem",
+		className: "docke2-mi-item",
+		onClick: () => {
+			if (typeof props.dismiss === "function") props.dismiss();
+			setPanelOpen(!open);
+		}
+	}, react.createElement("span", { className: "docke2-mi-icon" },
+		react.createElement(DockIcon, { size: 14 })),
+	react.createElement("span", { className: "docke2-mi-label" }, "功能坞"));
 }
 
 // ---- 功能坞弹出面板：shell.overlay（仿 dsh 设置：居中模态 = 遮罩 + 对话框） ----
@@ -651,6 +660,23 @@ function FeatureOverlays() {
 	return react.createElement(react.Fragment, null, items);
 }
 
+// ---- 回合尾（会话每条回复下方）：已启用功能挂在这儿的组件（如【语音朗读】的喇叭按钮） ----
+// 宿主 ui-chat 的 conversation.chat.turnTail 是 list 座位，只对「已完成回合」渲染，
+// 每个条目收到 { turn, seq, openFile } + 会话标准 kit（sessionId / useChat ...）。
+// 组件自己判断有没有内容可渲染，没内容返回 null（宿主不会留空隙）。
+function FeatureTurnTail(props) {
+	const [, force] = react.useReducer((n) => n + 1, 0);
+	react.useEffect(() => subscribeFeatureState(() => force()), []);
+	const items = [];
+	for (const f of allModules()) {
+		if (f.planned || !stateOf(f.id).enabled || typeof f.TurnTail !== "function") continue;
+		items.push(react.createElement(FeatureBoundary, { key: f.id, label: f.name },
+			react.createElement(f.TurnTail, Object.assign({}, props, { ctx: ctxRef.current, feature: f }))));
+	}
+	if (items.length === 0) return null;
+	return react.createElement(react.Fragment, null, items);
+}
+
 // ---- 插件应用：注册四处 UI（入口按钮 / 弹层 / 设置页 / 会话区 chips），注入样式 ----
 // ctx 以 ref 供视图组件使用（timer/theme 等服务按需自取；重装/HMR 时更新）
 const ctxRef = { current: null };
@@ -665,9 +691,9 @@ export function apply(ctx) {
 	const slots = ctx.get("slots");
 	if (slots === undefined) return;
 
-	slots.inject("sidebar.footer.action", () => slots.register(
-		{ name: "sidebar.footer.action", id: "dsh-dock", order: 1, label: "功能坞" },
-		(props) => react.createElement(DockEntry, props)));
+	slots.inject("settings.launcher.menu.item", () => slots.register(
+		{ name: "settings.launcher.menu.item", id: "dsh-dock", order: 1, label: "功能坞" },
+		(props) => react.createElement(DockMenuItem, props)));
 	slots.inject("shell.overlay", () => slots.register(
 		{ name: "shell.overlay", id: "dsh-dock-panel", order: 21, label: "功能坞面板" },
 		() => react.createElement(DockModal, null)));
@@ -682,6 +708,10 @@ export function apply(ctx) {
 	slots.inject("conversation.input.left", () => slots.register(
 		{ name: "conversation.input.left", id: "dsh-dock-chips", order: 10, label: "功能坞" },
 		(zone) => react.createElement(DockChips, Object.assign({}, zone, { ctx: ctxRef.current }))));
+	// 已完成回合的下方（回复动作区之前）：已启用功能挂的组件（【语音朗读】的喇叭）
+	slots.inject("conversation.chat.turnTail", () => slots.register(
+		{ name: "conversation.chat.turnTail", id: "dsh-dock-turn-tail", order: 40, label: "功能坞" },
+		(owner) => react.createElement(FeatureTurnTail, owner)));
 }
 
 export const inject = ["timer"];

package/src/host-core.js

@@ -118,6 +118,36 @@ export const DockConfig = z.object({
     // 一次性迁移标记：animation 段的旧通知配置已搬到本段（搬完置 true，避免每次启动重复写）
     migratedFromAnimation: z.boolean().default(false),
   }).default({}).volatile(),
+  // 【语音朗读】模块：把会话回复用浏览器语音合成（TTS）读出来。
+  // 行为配置（是否自动朗读、朗读哪些内容）放这里跨设备共享；
+  // 音色（voiceURI）虽然也存这一份，但**音色列表是每台设备/浏览器各自的**，
+  // 客户端用之前会拿本机 getVoices() 校验，取不到就按语言回落默认音色（见 features/tts/view.jsx）。
+  tts: z.object({
+    /** 会话（回合）结束后自动朗读最后一条回复。 */
+    autoPlay: z.boolean().default(false),
+    /** 任务以出错/中止结束时是否也朗读（默认读，方便不看屏幕也知道挂了）。 */
+    autoPlayOnFinish: z.boolean().default(true),
+    /** 新任务结束时打断正在读的内容，改读新的。 */
+    interruptOnNew: z.boolean().default(true),
+    /** 语速（0.5~2.0）。 */
+    rate: z.number().default(1),
+    /** 音调（0~2）。 */
+    pitch: z.number().default(1),
+    /** 音量（0~1）。 */
+    volume: z.number().default(1),
+    /** 指定音色（speechSynthesis voiceURI；空 = 按语言自动挑）。 */
+    voiceURI: z.string().default(''),
+    /** 强制朗读语言（如 zh-CN / en-US；空 = 按文本自动判定）。 */
+    lang: z.string().default(''),
+    /** 朗读时跳过代码块（``` 围栏与 `行内代码` 只留文字）。 */
+    skipCode: z.boolean().default(true),
+    /** 朗读时跳过 Markdown 表格（逐格念出来没有意义）。 */
+    skipTables: z.boolean().default(true),
+    /** 单次朗读字数上限（0 = 不限；自动朗读建议设限，手动点喇叭一般读全文）。 */
+    maxChars: z.number().default(0),
+    /** 自动朗读时只读回复的前 N 句（0 = 不限）。眼睛不舒服想听结论的人通常只要前几句。 */
+    maxSentences: z.number().default(0),
+  }).default({}).volatile(),
 })
 
 // ── 本地配置镜像（替代已移除的 settings.get） ─────────────────────────────
@@ -448,6 +478,60 @@ export function sendJson(res, status, value) {
   res.end(JSON.stringify(value))
 }
 
+/** 「信任栅栏缺失」只告警一次，避免每个请求刷一条日志。 */
+let warnedNoTrustSurface = false
+
+/**
+ * 浏览器信任栅栏：**每个自行注册的 `webServer` 路由都必须先调它**。
+ *
+ * 为什么必须：`webServer` 的命名路由由载体直接派发给 handler（见 dsh 的
+ * `packages/host/webserver` —— 匹配到路由就 `route.handler(req, res)`），载体本身
+ * 「不拥有认证或 Origin 策略」；`/api` 的 Host/Origin 校验与会话认证由 Connection 在
+ * 它自己的 FetchHandler 上做，**管不到插件注册的命名路由**。所以不检查的插件路由就是
+ * 一扇对任何能连到端口的人都敞开的门，dsh-access 这类门禁插件也拦不到（它只有
+ * exact 表 / fallback / connection-request / upgrades 四个缝）。
+ *
+ * 做法与官方插件一致：`dsh-host-open-in-app`、`dsh-experimental-inspector` 都在自己的
+ * 路由入口调 `connection.requestRejection(req)`，值即 401（Host 可信但无会话）或
+ * 403（Host/Origin 栅栏拒绝）。Connection 不可用时按 fail-closed 处理——dsh-dock 的
+ * 路由本身就是 web 专用的。
+ *
+ * @returns {boolean} true = 已拒绝并写完响应，调用方必须立即 return。
+ */
+export function rejectUntrustedRequest(ctx, req, res) {
+  const connection = ctx && typeof ctx.get === 'function' ? ctx.get('connection') : null
+  const requestRejection = connection && typeof connection.requestRejection === 'function'
+    ? connection.requestRejection.bind(connection)
+    : null
+  if (requestRejection === null) {
+    if (!warnedNoTrustSurface) {
+      warnedNoTrustSurface = true
+      console.warn('[dsh-dock] connection 服务不可用：/dsh-dock 路由将按未受信请求一律拒绝（401）')
+    }
+    sendJson(res, 401, { ok: false, error: { code: 'untrusted', message: '浏览器信任栅栏不可用，已拒绝请求' } })
+    return true
+  }
+  let rejection
+  try {
+    rejection = requestRejection(req)
+  } catch (error) {
+    // 栅栏自身异常：宁可拒绝，也不放行一个身份未知的请求。
+    console.warn('[dsh-dock] 浏览器信任栅栏判定异常，已按拒绝处理:', (error && error.message) || String(error))
+    sendJson(res, 403, { ok: false, error: { code: 'untrusted', message: '请求来源无法判定，已拒绝' } })
+    return true
+  }
+  if (rejection === undefined) return false
+  sendJson(res, rejection, {
+    ok: false,
+    error: {
+      code: 'untrusted',
+      message: rejection === 401 ? '未登录或浏览器会话已失效' : '请求来源不被信任',
+    },
+  })
+  if (typeof req.resume === 'function') req.resume()
+  return true
+}
+
 /** 解析 POST 请求体 JSON（限长 2MB）。 */
 export function readBody(req) {
   return new Promise((resolve, reject) => {

package/src/model-directory.js

@@ -0,0 +1,275 @@
+// dsh-dock · 模型目录共享层（宿主侧）
+//
+// 把官方 settings 里的 llm-deepseek / llm-pi-ai 两个命名空间归一成一份「Provider →
+// 模型目录」视图，并承担写回时的条目整形。之所以独立成 src/ 而不是留在某个功能模块里：
+//   - 【模型设置】只编辑单个模型的模态类型与思考强度（用目录视图 + 写模型条目）；
+//   - 【模型提供商】管理 Provider 本身的增删改与凭据（用目录视图 + 写 Provider 配置）；
+//   - 【图片理解代理】要按目录挑视觉模型（只读目录）。
+// 三个模块共用同一份归一化逻辑，避免各自复刻一遍口径。
+import { walkPath } from './host-core.js'
+
+/** 官方 schema 接受的输入模态（写回配置的 input 只允许这两个）。 */
+export const HOST_MODALITIES = ['text', 'image']
+/** pi-ai 路由支持的 API 协议。 */
+export const PI_AI_APIS = ['openai-completions', 'openai-responses', 'anthropic-messages']
+/** Provider 路由 key（= settings 里 providers.<route> 的 key），须能安全用作对象键与凭据寻址。 */
+export const ROUTE_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+/** pi-ai 支持的思考档位（升序）。 */
+export const PI_AI_LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+/** deepseek 官方支持的思考档位。 */
+export const DEEPSEEK_LEVELS = ['off', 'low', 'high', 'max']
+
+/** deepseek-official 内置默认值（与 balance 模块同款兜底）。 */
+export const DEEPSEEK_DEFAULTS = {
+  apiKeyEnv: 'DEEPSEEK_API_KEY',
+  baseURL: 'https://api.deepseek.com',
+}
+
+function providerKindOf(entry) {
+  if (entry.settingsNs === 'llm-deepseek') return 'deepseek'
+  if (entry.settingsNs === 'llm-pi-ai') return 'pi-ai'
+  return 'other'
+}
+
+/** 正整数或 undefined（目录数字字段透传）。 */
+function posInt(v) {
+  return Number.isInteger(v) && v > 0 ? v : undefined
+}
+
+/** 字符串数组透传（仅保留非空字符串）。 */
+export function strList(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x) : []
+}
+
+/** 把 pi-ai 模型条目归一为面板视图（raw = 原始条目，保存时原样回传保留未知字段）。 */
+function piAiModelView(entry, routeDefaultInput) {
+  const input = strList(entry.input).filter((m) => HOST_MODALITIES.includes(m))
+  const raw = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : {}
+  return {
+    id: typeof entry.id === 'string' ? entry.id : '',
+    name: typeof entry.name === 'string' ? entry.name : undefined,
+    contextWindow: posInt(entry.contextWindow),
+    maxTokens: posInt(entry.maxTokens),
+    input: input.length > 0 ? input : (strList(routeDefaultInput).length > 0 ? strList(routeDefaultInput) : ['text']),
+    inputInherited: input.length === 0,
+    efforts: raw.reasoningEfforts === undefined ? 'inherit' : raw.reasoningEfforts === false ? 'off' : 'custom',
+    effortMap: raw.reasoningEfforts && typeof raw.reasoningEfforts === 'object' ? raw.reasoningEfforts : null,
+    tags: strList(entry.dockTags),
+    raw,
+  }
+}
+
+/** 把 deepseek 目录模型归一为面板视图。 */
+function deepSeekModelView(entry) {
+  const input = strList(entry.inputModalities).filter((m) => HOST_MODALITIES.includes(m))
+  const raw = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : {}
+  return {
+    id: typeof entry.id === 'string' ? entry.id : '',
+    name: typeof entry.name === 'string' ? entry.name : undefined,
+    contextWindow: posInt(entry.contextWindow),
+    maxTokens: posInt(entry.maxTokens),
+    input: input.length > 0 ? input : ['text'],
+    inputInherited: input.length === 0,
+    tags: strList(entry.dockTags),
+    raw,
+  }
+}
+
+/**
+ * 读模型目录：按"已配置"口径枚举 Provider，
+ * 输出各 Provider 的模型列表（含输入类型 / 思考强度）与各 settings 命名空间的 revision。
+ */
+export function readModelDirectory(ctx) {
+  const llm = ctx.get('llm')
+  const settings = ctx.get('settings')
+  const entries = (llm && llm.listConfigurableProviders ? llm.listConfigurableProviders() : []) || []
+  let views = []
+  try {
+    views = (settings && settings.describe ? settings.describe({ redactSecrets: true }) : []) || []
+  } catch {
+    // settings 未挂载
+  }
+  const descOf = (ns) => views.find((v) => v && String(v.ns) === ns)
+
+  let sel = null
+  try {
+    sel = (ctx.get('agentDefaultModel') && ctx.get('agentDefaultModel').currentSelection()) || null
+  } catch {
+    // 服务缺失
+  }
+
+  const providers = []
+  for (const e of entries) {
+    const kind = providerKindOf(e)
+    if (kind === 'other') continue // 官方之外的适配器暂不编辑（无稳定 schema）
+    const desc = descOf(e.settingsNs)
+    if (!desc) continue
+    const profileUser = desc.user ? walkPath(desc.user, e.settingsPath) : undefined
+    const profileBase = desc.base ? walkPath(desc.base, e.settingsPath) : undefined
+    const isDefaultProvider = !!(sel && sel.provider === e.provider)
+    // deepseek 官方始终可编辑（schema 默认目录兜底）；其余按"已配置"口径
+    const configured = kind === 'deepseek' || isDefaultProvider
+      || (profileUser && typeof profileUser === 'object')
+      || (profileBase && typeof profileBase === 'object')
+    if (!configured) continue
+
+    const resolved = walkPath(desc.value, e.settingsPath) // schema 默认已套上的合成视图
+    if (kind === 'deepseek') {
+      const section = resolved && typeof resolved === 'object' ? resolved : {}
+      const models = Array.isArray(section.models) ? section.models : []
+      providers.push({
+        id: e.provider,
+        displayName: (profileUser && profileUser.displayName) || e.displayName || e.provider,
+        api: 'deepseek',
+        baseURL: (profileUser && profileUser.baseURL) || section.baseURL || DEEPSEEK_DEFAULTS.baseURL,
+        apiKeyEnv: (profileUser && profileUser.apiKeyEnv) || DEEPSEEK_DEFAULTS.apiKeyEnv,
+        kind,
+        settingsNs: e.settingsNs,
+        settingsPath: [...e.settingsPath],
+        thinking: section.thinking === 'disabled' ? 'disabled' : 'enabled',
+        defaultEffort: DEEPSEEK_LEVELS.includes(section.reasoningEffort) ? section.reasoningEffort : undefined,
+        effortLevels: DEEPSEEK_LEVELS.slice(),
+        models: models.map(deepSeekModelView),
+      })
+    } else {
+      const route = e.settingsPath[1] || e.provider
+      const profile = (profileUser && typeof profileUser === 'object' ? profileUser
+        : (profileBase && typeof profileBase === 'object' ? profileBase : resolved)) || {}
+      const resolvedProfile = (resolved && typeof resolved === 'object' ? resolved : {}) || {}
+      const models = Array.isArray(profile.models) ? profile.models : []
+      providers.push({
+        id: e.provider,
+        route,
+        displayName: profile.displayName || e.displayName || e.provider,
+        api: typeof profile.api === 'string' ? profile.api : undefined,
+        baseURL: typeof profile.baseURL === 'string' ? profile.baseURL : undefined,
+        apiKeyEnv: typeof profile.apiKeyEnv === 'string' ? profile.apiKeyEnv : undefined,
+        kind,
+        settingsNs: e.settingsNs,
+        settingsPath: [...e.settingsPath],
+        // 用户层原始配置：编辑表单按它回填，未知字段（自配 compat/description 等）原样保留。
+        rawProfile: profileUser && typeof profileUser === 'object' && !Array.isArray(profileUser) ? profileUser : {},
+        apis: PI_AI_APIS.slice(),
+        defaultInput: strList(resolvedProfile.defaultInput),
+        models: models.map((m) => piAiModelView(m && typeof m === 'object' ? m : { id: String(m) }, resolvedProfile.defaultInput)),
+      })
+    }
+  }
+
+  const revisions = {}
+  for (const ns of ['llm-pi-ai', 'llm-deepseek']) {
+    const d = descOf(ns)
+    if (d && d.revision !== undefined) revisions[ns] = d.revision
+  }
+  return { generatedAt: Date.now(), default: sel, revisions, providers }
+}
+
+/**
+ * 给目录视图补运行时视角的输入模态（llm.resolveModelInfo，与官方投影同源：
+ * entry.input → 内置目录 → 路由默认）。面板据此展示「原图直发 vs 走视觉代理」，
+ * 避免"条目留空但目录继承多模态"的模型被误分组。
+ * 注意：功能启用后 llm.resolveModelInfo 被本插件包装（虚拟多模态），此处须取原函数保真。
+ */
+export async function enrichRuntimeInput(ctx, dir) {
+  const llm = ctx.get('llm')
+  const resolve = llm && (llm.__dockOrigResolveModelInfo
+    || (typeof llm.resolveModelInfo === 'function' ? llm.resolveModelInfo.bind(llm) : null))
+  if (!resolve) return
+  await Promise.all((dir.providers || []).flatMap((p) => (p.models || []).map(async (m) => {
+    try {
+      const info = await resolve(p.id, m.id)
+      if (info && Array.isArray(info.inputModalities)) {
+        m.runtimeInput = info.inputModalities.filter((x) => HOST_MODALITIES.includes(x))
+      }
+    } catch {
+      // 单模型解析失败不影响整表（面板回退用 input 展示）
+    }
+  })))
+}
+
+/** 校验面板数字草稿并落到条目上（空 = 删除字段，继承默认）。 */
+function setPosInt(entry, field, value) {
+  if (value === undefined || value === null || value === '') {
+    delete entry[field]
+    return
+  }
+  const n = Number(value)
+  if (!Number.isInteger(n) || n <= 0) throw new Error(`模型 ${entry.id} 的 ${field} 须为正整数`)
+  entry[field] = n
+}
+
+/**
+ * 校验面板提交的模型草稿，产出写回 pi-ai 的模型条目（不合法直接抛错）。
+ * 基于原条目（raw）合并编辑：未知字段（用户自配 compat/description 等）原样保留。
+ * 启用思考（custom）时的兜底（2026-08-22 事故修复）：
+ *   不在 pi-ai 内置目录里的模型没有 catalog compat，检测默认 supportsDeveloperRole=true，
+ *   而 pi-ai 对 reasoning 模型会把 system 改写成 developer 角色 → 百炼等 OpenAI 兼容端点 400。
+ *   故凡启用思考一律显式 supportsDeveloperRole:false（system 全端点通用）；
+ *   百炼/阿里云家族 baseURL 再补 thinkingFormat:'qwen'（与目录内模型一致，思考参数用 qwen 格式）。
+ *
+ * 【模型设置】（编辑已有 Provider 的模型）与【模型提供商】（新建/更新 Provider 时随带模型）
+ * 共用这一份整形逻辑，两条入口写出的条目必须一致。
+ */
+export function piAiModelWrite(m, p) {
+  if (!m || typeof m.id !== 'string' || !m.id) throw new Error('模型 id 不能为空')
+  const raw = m.raw && typeof m.raw === 'object' && !Array.isArray(m.raw) ? m.raw : {}
+  const entry = Object.assign({}, raw)
+  entry.id = m.id
+  if (typeof m.name === 'string' && m.name) entry.name = m.name
+  else delete entry.name
+  setPosInt(entry, 'contextWindow', m.contextWindow)
+  setPosInt(entry, 'maxTokens', m.maxTokens)
+  const input = Array.isArray(m.input) ? m.input.filter((x) => HOST_MODALITIES.includes(x)) : []
+  if (input.length > 0) entry.input = input // 留空 = 继承路由/目录默认
+  else delete entry.input
+  const tags = strList(m.tags)
+  if (tags.length > 0) entry.dockTags = tags // 标注（如 video），官方校验忽略、随配置持久化
+  else delete entry.dockTags
+  if (m.effortsMode === 'off') {
+    entry.reasoningEfforts = false
+  } else if (m.effortsMode === 'custom') {
+    const levels = m.effortLevels || {}
+    const map = {}
+    let real = 0
+    for (const lv of PI_AI_LEVELS) {
+      if (!levels[lv]) continue
+      if (lv === 'off') map.off = null // 支持关闭：不发参数
+      else { map[lv] = lv; real += 1 }
+    }
+    if (real === 0) throw new Error(`模型 ${m.id} 至少要勾选一个思考档位（off 之外）`)
+    entry.reasoningEfforts = map
+    // 目录路由（用户层未写 api/baseURL，靠 pi-ai 内置目录提供）视作 openai 兼容
+    const apiOk = !p.api || (typeof p.api === 'string' && p.api.indexOf('openai') === 0)
+    if (apiOk) {
+      const compat = Object.assign({}, entry.compat)
+      compat.supportsDeveloperRole = false
+      // 百炼/阿里云家族（路由 id 或 baseURL 命中）思考参数用 qwen 格式，与目录内模型一致
+      if (/qwen|dashscope|aliyuncs/i.test(String(p.route || '') + ' ' + String(p.baseURL || ''))) {
+        compat.thinkingFormat = 'qwen'
+      }
+      entry.compat = compat
+    }
+  } else {
+    delete entry.reasoningEfforts // inherit = 不写该字段，跟随内置目录
+  }
+  return entry
+}
+
+/** 校验并产出写回 deepseek 官方的目录模型条目（raw 未知字段保留）。 */
+export function deepSeekModelWrite(m) {
+  if (!m || typeof m.id !== 'string' || !m.id) throw new Error('模型 id 不能为空')
+  const raw = m.raw && typeof m.raw === 'object' && !Array.isArray(m.raw) ? m.raw : {}
+  const entry = Object.assign({}, raw)
+  entry.id = m.id
+  if (typeof m.name === 'string' && m.name) entry.name = m.name
+  else delete entry.name
+  setPosInt(entry, 'contextWindow', m.contextWindow)
+  setPosInt(entry, 'maxTokens', m.maxTokens)
+  const input = Array.isArray(m.input) ? m.input.filter((x) => HOST_MODALITIES.includes(x)) : []
+  if (input.includes('image')) entry.inputModalities = input // 纯文本留空走 schema 默认 ['text']
+  else delete entry.inputModalities
+  const tags = strList(m.tags)
+  if (tags.length > 0) entry.dockTags = tags
+  else delete entry.dockTags
+  return entry
+}