dsh-dock 0.15.0 → 0.16.0

package/features/notify/host.js

@@ -14,7 +14,7 @@
 //   systemNotify / soundNotify / soundEffect / dingtalkEnabled / dingtalkWebhook /
 //   feishuEnabled / feishuWebhook
 // 模块启停由功能坞的 features.notify 开关负责（独立菜单项），本模块不再有第二个总开关。
-import { SOUND_EFFECTS, sendJson, readBody, readDockRoot, mutateDockSection } from '../../src/host-core.js'
+import { SOUND_EFFECTS, sendJson, readBody, rejectUntrustedRequest, readDockRoot, mutateDockSection } from '../../src/host-core.js'
 import { acquireTaskTracker } from '../../src/task-track.js'
 
 // 默认配置（schema 默认值一致；settings 未挂载时的兜底）
@@ -244,6 +244,7 @@ export const feature = {
         kind: 'prefix',
         path: '/dsh-dock/notify',
         async handler(req, res) {
+          if (rejectUntrustedRequest(ctx, req, res)) return
           try {
             const url = new URL(req.url || '/', 'http://dsh.internal')
             const method = url.pathname.replace(/^\/dsh-dock\/notify\/?/, '').split('/')[0] || ''

package/features/notify/view.jsx

@@ -5,6 +5,7 @@
 //  2. HomeStat  —— 首页总揽概要（当前通知事件与推送通道）；
 //  3. Overlay   —— 全局浮层（shell.overlay 常驻，功能启用即挂载）：轮询 Host 状态，
 //                  任务结束弹通知卡片（可选提示音与浏览器系统通知），工具等待确认时弹常驻提醒卡。
+//                  结束卡常驻到「看过」（点卡直达会话 / 点进会话 / 手动 ✕），≥3 张叠放收纳。
 //
 // 与【任务动画】【运行状态】完全独立：动效在 features/animation/、任务状态一览在
 // features/runstate/，本模块只管通知（页内卡片 / 提示音 / 系统通知 / 钉钉飞书群机器人推送）。
@@ -165,16 +166,68 @@ function useNotify() {
 }
 
 // ---------- 通知卡片 ----------
+// 需确认卡片没有任何计时器：审批没处理完它就一直在（处理完由 approvalKeys
+// 对账自动收起，也可手动 ✕）。曾经的「前台看过 8 秒也收」害死人：审批还挂着
+// 等人批，提醒先没了（2026-10-20 实测漏提醒）。堆叠问题交给叠放收纳解决。
+function pageVisible() {
+	return typeof document === "undefined" || document.visibilityState === "visible";
+}
+
+// 当前正在看的会话标题（侧栏高亮行）。与【任务动画】的 currentSessionTitle 同款判定：
+// dsh 会话树行 = role="treeitem" + aria-selected，行文本即标题；侧栏在左，
+// 跳过正文区可能出现的同名高亮节点（右上搜索结果等）。
+function currentSelectedSessionTitle() {
+	if (typeof document === "undefined" || typeof window === "undefined") return "";
+	if (typeof document.querySelectorAll !== "function") return "";
+	for (const el of document.querySelectorAll('[role="treeitem"][aria-selected="true"]')) {
+		const r = el.getBoundingClientRect();
+		if (r.width > 0 && r.height > 0 && r.right <= window.innerWidth * .35) {
+			const text = (el.textContent || "").trim();
+			if (text) return text;
+		}
+	}
+	return "";
+}
+// 标题模糊对齐（与任务动画 taskOnScreen 同规则）：相等或互为子串即算同一会话
+function titleMatches(a, b) {
+	return !!a && !!b && (a === b || a.indexOf(b) !== -1 || b.indexOf(a) !== -1);
+}
+
+// 点卡片跳转会话：在侧栏会话树里找标题对上的一行，点它（优先行内的 a/button）。
+// 判定与 currentSelectedSessionTitle 同口径（左缘 35vw 内、可见）；找不到可见行
+// （抽屉收起 / 手机端 / 会话被删）返回 false，调用方保持卡片不收起。
+function openSessionByTitle(title) {
+	if (typeof document === "undefined" || typeof window === "undefined") return false;
+	if (typeof document.querySelectorAll !== "function" || !title) return false;
+	for (const el of document.querySelectorAll('[role="treeitem"]')) {
+		const r = typeof el.getBoundingClientRect === "function" ? el.getBoundingClientRect() : null;
+		if (!r || r.width <= 0 || r.height <= 0 || r.right > window.innerWidth * .35) continue;
+		if (!titleMatches((el.textContent || "").trim(), title)) continue;
+		const link = typeof el.querySelector === "function" ? el.querySelector("a,button") : null;
+		const target = link || el;
+		if (typeof target.click === "function") { target.click(); return true; }
+		return false;
+	}
+	return false;
+}
+
 function Toast(props) {
 	const t = props.t;
-	const [closing, setClosing] = useState(false);
-	const close = useCallback(() => { if (!closing) setClosing(true); }, [closing]);
-	// 停留时长（stayMs=0 常驻，仅手动关闭）
-	useEffect(() => {
-		if (!t.stayMs) return;
-		const timer = setTimeout(close, t.stayMs);
-		return () => clearTimeout(timer);
-	}, []);
+	const [closing, setClosing] = useState(!!t.closing);
+	const close = useCallback(() => { setClosing(true); }, []);
+	// 点卡片 = 跳转到对应会话。结束卡跳成功就地收起（这一看就把通知的活干完了）；
+	// 需确认卡只跳转不收——审批没处理完它就该在。找不到可见会话行（抽屉收起/
+	// 手机端/会话已删）不收起，卡片原样保留。
+	const jump = useCallback(() => {
+		if (!t.sessionTitle) return;
+		if (openSessionByTitle(t.sessionTitle) && t.kind !== "confirm") setClosing(true);
+	}, [t.sessionTitle, t.kind]);
+	// 外部要求收起（审批已处理 / 已点进会话）走同一套淡出动画
+	useEffect(() => { if (t.closing && !closing) setClosing(true); }, [t.closing, closing]);
+	// 所有卡片都没有计时器：结束卡常驻到「看过」（点卡跳转 / 点进会话 / 手动 ✕），
+	// 需确认卡常驻到审批处理完（approvalKeys 对账收起，或手动 ✕）。
+	// 曾经的 lingerMs「前台看过 8 秒也收」实测会把还挂着的审批提醒先弄丢，已移除；
+	// 卡片多了靠叠放收纳（.stacked 样式），不靠丢。
 	useEffect(() => {
 		if (!closing) return;
 		const timer = setTimeout(() => props.onClose(t.id), 240);
@@ -185,14 +238,23 @@ function Toast(props) {
 		: t.kind === "error"
 			? "var(--dk-err)"
 			: "var(--dk-warn)";
+	// 叠放收起态（collapsed）：只留标题条，正文隐藏；悬停卡片栈时整体展开
 	return (
-		<div className={"dknt-toast" + (t.kind === "confirm" ? " dknt-toast-confirm" : "") + (closing ? " out" : "")}>
+		<div className={"dknt-toast" + (t.kind === "confirm" ? " dknt-toast-confirm" : "")
+				+ (t.sessionTitle ? " clickable" : "")
+				+ (props.collapsed ? " collapsed" : "")
+				+ (closing ? " out" : "")}
+			onClick={t.sessionTitle ? jump : undefined}>
 			<div className="dknt-toast-head">
 				<span className="dknt-toast-mark" style={{ background: markColor }} />
-				<span className="dknt-toast-title" title={t.title}>{t.kind === "confirm" ? "✋ " : ""}{t.title}</span>
-				<button type="button" className="dknt-toast-close" aria-label="关闭" onClick={close}>✕</button>
+				<span className="dknt-toast-title" title={t.sessionTitle || t.title}>
+					{t.kind === "confirm" ? "✋ " : ""}{props.collapsed ? (t.sessionTitle || t.title) : t.title}
+					{!props.collapsed && t.sessionTitle && t.kind !== "confirm" ? " · " + t.sessionTitle : ""}
+				</span>
+				<button type="button" className="dknt-toast-close" aria-label="关闭"
+					onClick={(e) => { if (e && e.stopPropagation) e.stopPropagation(); close(); }}>✕</button>
 			</div>
-			{t.body ? <div className="dknt-toast-body">{t.body}</div> : null}
+			{!props.collapsed && t.body ? <div className="dknt-toast-body">{t.body}</div> : null}
 		</div>
 	);
 }
@@ -201,12 +263,14 @@ function Toast(props) {
 export function NotifyOverlay(props) {
 	const snap = useNotify();
 	const [toasts, setToasts] = useState([]);
+	const [stackHover, setStackHover] = useState(false); // 卡片栈被悬停（叠放时整体展开）
 	const prevActiveRef = useRef(null);
 	const remindedApprovalsRef = useRef(new Map()); // sessionId -> 提醒过的 approvalId 集合
 	const toastSeqRef = useRef(0);
 
 	const pushToast = useCallback((toast) => {
-		setToasts((prev) => prev.concat([toast]).slice(-4));
+		// 上限 12：结束卡现在常驻到看过才收，4 张容易见底；多了靠叠放收纳而不是丢弃。
+		setToasts((prev) => prev.concat([toast]).slice(-12));
 	}, []);
 
 	// 轮询：任务中 850ms，实时捕捉结束/待确认；空闲 6s / 出错 15s；页面切回立即刷新。
@@ -277,8 +341,11 @@ export function NotifyOverlay(props) {
 				kind: "confirm",
 				title: "任务需要确认",
 				body: lines.join("\n"),
-				// 需确认常驻到用户处理（notifyStayMs=0 同款语义），不会自动消失
-				stayMs: 0,
+				// 点卡片直达该会话去处理审批（需确认卡跳转后不收起——审批没处理完它就该在）
+				sessionTitle: task.title || "",
+				// 卡片与这批审批项绑定：approval/decided 后宿主把它们移出 approvals，
+				// 下面的对账 effect 据此自动收起卡片（处理完就不该再占着右上角）。
+				approvalKeys: fresh.filter((a) => a && a.id).map((a) => task.sessionId + "|" + a.id),
 			});
 			if (cfg.soundNotify !== false) playAskSound(cfg.soundEffect);
 			if (cfg.systemNotify && typeof document !== "undefined" && document.hidden
@@ -293,6 +360,54 @@ export function NotifyOverlay(props) {
 		}
 	}, [snap.status]);
 
+	// 审批项消失（approval/decided 后宿主把它移出 approvals）→ 对应需确认卡自动收起。
+	// 只标记 closing 走淡出，不直接删：与手动点 ✕ 的退场一致。
+	// 卡片绑定的 approvalKeys 全部不在仍待确认的集合里才收；空 keys（老数据）不动。
+	useEffect(() => {
+		const st = snap.status;
+		if (!st || !st.active) return;
+		const live = new Set();
+		for (const task of st.active) {
+			const approvals = Array.isArray(task.approvals) ? task.approvals : [];
+			for (const a of approvals) if (a && a.id) live.add(task.sessionId + "|" + a.id);
+		}
+		setToasts((prev) => {
+			let changed = false;
+			const next = prev.map((x) => {
+				if (x.kind !== "confirm" || x.closing) return x;
+				const keys = Array.isArray(x.approvalKeys) ? x.approvalKeys : [];
+				if (keys.length === 0 || keys.some((k) => live.has(k))) return x;
+				changed = true;
+				return Object.assign({}, x, { closing: true });
+			});
+			return changed ? next : prev;
+		});
+	}, [snap.status]);
+
+	// 结束卡（完成/异常）的"看过即收"：用户点进那个会话（侧栏高亮行标题与卡片
+	// 绑定的 sessionTitle 对上）就视为已看到结果，卡片自动收起。结束卡没有超时
+	// 自毁——没看过就一直挂着；这条巡检是它唯一的自动出口（另有手动 ✕ 与点卡跳转）。
+	// 侧栏选中没有事件可订阅，用轻量轮询（500ms 一次 querySelectorAll）；页面在
+	// 后台不检查（回来时若仍停在该会话，收起发生在切回后）。
+	useEffect(() => {
+		const timer = setInterval(() => {
+			if (!pageVisible()) return;
+			const current = currentSelectedSessionTitle();
+			if (!current) return;
+			setToasts((prev) => {
+				let changed = false;
+				const next = prev.map((x) => {
+					if (x.kind === "confirm" || x.closing || !x.sessionTitle) return x;
+					if (!titleMatches(x.sessionTitle, current)) return x;
+					changed = true;
+					return Object.assign({}, x, { closing: true });
+				});
+				return changed ? next : prev;
+			});
+		}, 500);
+		return () => clearInterval(timer);
+	}, []);
+
 	const handleTaskEnd = (task, record, cfg) => {
 		const reason = (record && record.endReason) || "";
 		const success = isSuccessReason(reason);
@@ -323,7 +438,9 @@ export function NotifyOverlay(props) {
 			kind: success ? "success" : (info.cls === "err" ? "error" : "warn"),
 			title,
 			body: lines.join("\n"),
-			stayMs: typeof cfg.notifyStayMs === "number" ? cfg.notifyStayMs : 8000,
+			// 绑定会话标题：点卡片直达该会话；用户点进这个会话（侧栏选中）也视为
+			// 看到了结果，巡检 effect 据此自动收起卡片。没看过就一直挂着。
+			sessionTitle: (record && record.title) || task.title || "",
 		});
 		// 提示音：任务结束时播放（完成/异常配套音）；与系统通知独立开关
 		if (cfg.soundNotify !== false) playDoneSound(success, cfg.soundEffect);
@@ -342,9 +459,17 @@ export function NotifyOverlay(props) {
 	// Host 不可用（旧宿主未重启等）：浮层整体静默，面板页会给提示
 	if (!snap.status) return null;
 	if (toasts.length === 0) return null;
+	// 卡片多了叠放收纳：≥3 张时只完整展开最新一张，其余收成"只剩标题条"；
+	// 鼠标移到卡片栈上整体展开，移开收回。跳转/收起对每张卡照常可用。
+	const stack = toasts.length >= 3 && !stackHover;
 	return (
-		<div className="dknt-toasts">
-			{toasts.map((t) => <Toast key={t.id} t={t} onClose={(id) => setToasts((prev) => prev.filter((x) => x.id !== id))} />)}
+		<div className={"dknt-toasts" + (stack ? " stacked" : "")}
+			onMouseEnter={() => setStackHover(true)}
+			onMouseLeave={() => setStackHover(false)}>
+			{toasts.map((t, i) => (
+				<Toast key={t.id} t={t} collapsed={stack && i < toasts.length - 1}
+					onClose={(id) => setToasts((prev) => prev.filter((x) => x.id !== id))} />
+			))}
 		</div>
 	);
 }
@@ -516,7 +641,7 @@ function NotifyView(props) {
 							onClick={() => patch({ notifyOnConfirm: cfg.notifyOnConfirm === false })}>
 							{cfg.notifyOnConfirm !== false ? "开" : "关"}
 						</button>
-						<span className="dknt-row-sub">工具等待你批准时弹卡片并响确认音（常驻不自动消失）</span>
+						<span className="dknt-row-sub">工具等待你批准时弹卡片并响确认音；审批处理完自动收起，没处理完就一直显示（点卡片直达会话）</span>
 					</div>
 				</div>
 			</div>,
@@ -527,16 +652,8 @@ function NotifyView(props) {
 				</div>
 				<div className="dknt-rows-narrow">
 					<div className="dknt-row">
-						<span className="dknt-row-label">停留时长</span>
-						<select className="dknt-select" value={String(cfg.notifyStayMs)}
-							onChange={(e) => patch({ notifyStayMs: Number(e.target.value) })}>
-							<option value="4000">4 秒</option>
-							<option value="8000">8 秒</option>
-							<option value="15000">15 秒</option>
-							<option value="30000">30 秒</option>
-							<option value="0">常驻（手动关闭）</option>
-						</select>
-						<span className="dknt-row-sub">卡片自动消失的时间（需确认提醒恒为常驻）</span>
+						<span className="dknt-row-label">卡片收纳</span>
+						<span className="dknt-row-sub">所有卡片都不超时自动消失：结束卡片没看过就一直挂着（后台跑完的切回来也在），点卡片直达对应会话，或点进该会话，卡片自动收起；需确认卡片挂到审批处理完。3 张及以上自动叠放成标题条，鼠标移上去整体展开</span>
 					</div>
 					<div className="dknt-row">
 						<span className="dknt-row-label">系统通知</span>
@@ -700,6 +817,13 @@ const css = [
 	".dknt-toast-confirm{border-color:color-mix(in srgb,var(--dk-warn) 55%,transparent);animation:dknt-toast-in .32s var(--ds-ease-in-out),dknt-confirm-glow 2.4s ease-in-out 0.4s infinite;}",
 	"@keyframes dknt-confirm-glow{0%,100%{box-shadow:0 10px 36px rgb(0 0 0 / .22),0 0 0 0 color-mix(in srgb,var(--dk-warn) 30%,transparent)}50%{box-shadow:0 10px 36px rgb(0 0 0 / .22),0 0 14px 2px color-mix(in srgb,var(--dk-warn) 32%,transparent)}}",
 	"@media (prefers-reduced-motion:reduce){.dknt-toast,.dknt-toast-confirm{animation:none}}",
+	// 可跳转卡片：指针 + 悬停提亮（点卡片直达对应会话）
+	".dknt-toast.clickable{cursor:pointer;}",
+	".dknt-toast.clickable:hover{border-color:var(--dk-accent);}",
+	// 叠放收纳：≥3 张时旧卡收成"只剩标题条"，悬停卡片栈整体展开
+	".dknt-toasts.stacked{gap:4px;}",
+	".dknt-toast.collapsed{padding:6px 14px;opacity:.85;margin-left:14px;}",
+	".dknt-toast.collapsed .dknt-toast-head{margin-bottom:0;}",
 	// 面板页布局
 	".dknt-root{display:flex;flex-direction:column;gap:10px;}",
 	".dknt-note{color:var(--dsw-alias-label-secondary);font-size:12px;line-height:1.6;}",
@@ -719,7 +843,6 @@ const css = [
 	".dknt-row-sub{font-size:11px;color:var(--dsw-alias-label-tertiary);}",
 	".dknt-miniswitch{cursor:pointer;flex:none;border:1px solid var(--dsw-alias-border-l2);background:transparent;color:var(--dsw-alias-label-tertiary);border-radius:999px;padding:1px 12px;font-family:inherit;font-size:11px;line-height:18px;}",
 	".dknt-miniswitch.on{color:var(--dsw-alias-state-success-primary);border-color:currentColor;}",
-	".dknt-select{background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);border:1px solid var(--dsw-alias-border-l2);border-radius:6px;padding:3px 8px;font-size:12px;font-family:inherit;}",
 	// 音效选择卡（名称 + 播放键；选中态描边）
 	".dknt-sounds{display:flex;gap:6px;flex-wrap:wrap;}",
 	".dknt-sound{flex:1;min-width:104px;display:flex;align-items:center;justify-content:space-between;gap:6px;padding:6px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:8px;background:var(--dsw-alias-bg-layer-2);cursor:pointer;font-family:inherit;transition:border-color .15s var(--ds-ease-in-out);}",

package/features/providerconfig/host.js

@@ -0,0 +1,235 @@
+// dsh-dock · 功能模块【模型提供商】· 宿主半部
+//
+// GET  /dsh-dock/providerconfig —— Provider 列表（端点 / API Key 条目 / 密钥是否已配置 / 模型数）
+// POST /dsh-dock/providerconfig —— action=listModels  拉取上游模型列表（GET {baseURL}/models）
+//                                 action=create|update|delete  维护 llm-pi-ai 的 providers 字典
+//
+// 为什么单独成模块：Provider 的增删改与凭据写入是**配置面**的操作（会写官方 settings
+// 与本地凭据库），与「调模型的模态类型/思考强度」是两件事。拆开后可以只开【模型设置】
+// 而不开【模型提供商】——不需要改 Provider 的部署（例如只用官方 DeepSeek 端点）就不必
+// 把写凭据、发起出站请求的路由挂在进程里，攻击面随功能一起关掉。
+//
+// 模型条目的整形（piAiModelWrite）与目录读取（readModelDirectory）都在 src/model-directory.js，
+// 与【模型设置】共用同一份口径，两条入口写出的条目必须一致。
+import { sendJson, readBody, rejectUntrustedRequest } from '../../src/host-core.js'
+import { PI_AI_APIS, ROUTE_KEY_RE, readModelDirectory, piAiModelWrite } from '../../src/model-directory.js'
+// 凭据引用（apiKeyEnv → 本地凭据库条目）。注意：只从本模块取 credentialRef；
+// 不同 dsh 版本导出的辅助函数不一致（isCredentialRefName 在运行期并不存在），
+// 非法环境变量名一律用 try/catch + credentialRef 兜住。
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+
+/**
+ * 并行补 Provider 的 apiKeyConfigured：apiKeyEnv 指向的条目是否已在本地凭据库配置。
+ * 凭据库不可用 / 环境变量名非法时一律降级为 false（不抛错，避免整表 500）。
+ */
+async function enrichApiKeyStatus(ctx, dir) {
+  const credentials = ctx.get('credentials')
+  if (!credentials || typeof credentials.describe !== 'function') return
+  await Promise.all((dir.providers || []).filter((p) => p.kind === 'pi-ai').map(async (p) => {
+    if (typeof p.apiKeyEnv !== 'string' || !p.apiKeyEnv) { p.apiKeyConfigured = false; return }
+    try {
+      const d = await credentials.describe(credentialRef(p.apiKeyEnv))
+      p.apiKeyConfigured = !!(d && d.configured)
+    } catch {
+      p.apiKeyConfigured = false
+    }
+  }))
+}
+
+/**
+ * 拉取 Provider 的可用模型列表：OpenAI 兼容端点 GET {baseURL}/models。
+ * Key 优先用请求里刚填的明文（还没保存就能先拉列表），否则回退到已配置的凭据库条目。
+ * 只做「列目录」，不代表该模型真能调用（额度/权限以上游为准）。
+ *
+ * 注意：baseURL 由调用方给出（新建 Provider 时还没落盘），因此这是**有意的出站请求**；
+ * 提供它的前提是它已经被浏览器信任栅栏挡过一道（见 rejectUntrustedRequest）。
+ */
+async function fetchProviderModels(ctx, body) {
+  const bad = (msg) => { const e = new Error(msg); e.statusCode = 400; return e }
+  const baseURL = typeof body.baseURL === 'string' ? body.baseURL.trim().replace(/\/+$/, '') : ''
+  if (!/^https?:\/\//i.test(baseURL)) throw bad('请先填写合法的 baseURL（http:// 或 https://）')
+  let key = typeof body.apiKey === 'string' ? body.apiKey.trim() : ''
+  if (!key && typeof body.apiKeyEnv === 'string' && body.apiKeyEnv.trim()) {
+    const credentials = ctx.get('credentials')
+    if (credentials && typeof credentials.resolve === 'function') {
+      try {
+        const got = await credentials.resolve(credentialRef(body.apiKeyEnv.trim()))
+        key = typeof got === 'string' ? got : (got && typeof got.value === 'string' ? got.value : '')
+      } catch { key = '' }
+    }
+  }
+  const headers = { accept: 'application/json' }
+  if (key) {
+    if (body.api === 'anthropic-messages') {
+      headers['x-api-key'] = key
+      headers['anthropic-version'] = '2023-06-01'
+    } else {
+      headers.authorization = 'Bearer ' + key
+    }
+  }
+  let res
+  try {
+    res = await fetch(baseURL + '/models', { headers, signal: AbortSignal.timeout(20000) })
+  } catch (e) {
+    const err = new Error(`请求 ${baseURL}/models 失败：${(e && e.message) || String(e)}`)
+    err.statusCode = 400
+    throw err
+  }
+  let text = ''
+  try { text = await res.text() } catch { text = '' }
+  if (!res.ok) {
+    const err = new Error(`上游返回 HTTP ${res.status}${text ? '：' + text.slice(0, 240) : ''}`)
+    err.statusCode = 400
+    throw err
+  }
+  let json = null
+  try { json = JSON.parse(text) } catch { /* 非 JSON：下面按空列表处理 */ }
+  let list = []
+  if (Array.isArray(json)) list = json
+  else if (json && Array.isArray(json.data)) list = json.data
+  else if (json && Array.isArray(json.models)) list = json.models
+  const models = list.map((x) => {
+    if (typeof x === 'string') return { id: x }
+    const o = x && typeof x === 'object' ? x : {}
+    return { id: String(o.id || o.model || o.name || ''), name: typeof o.name === 'string' ? o.name : undefined }
+  }).filter((m) => m.id)
+  return { ok: true, count: models.length, models, fetchedAt: Date.now() }
+}
+
+/**
+ * Provider 级增 / 改 / 删（走 llm-pi-ai 的 providers 字典，不改内核）。
+ *   body.action = 'create' | 'update' | 'delete'
+ *   body.route  = providers 字典的 key（= 路由 id）
+ *   body.profile = { displayName, api, baseURL, apiKeyEnv, defaultInput, models: [草稿...] }
+ *   body.apiKey  = 可选明文 Key（写本地凭据库，不落到配置文件）
+ *   body.revisions['llm-pi-ai'] = GET 拿到的 revision（乐观锁，撞车 409）
+ * 未在 profile 里出现的未知字段？——不会：base 以原 profile 为基础合并，用户自配的
+ * compat / description 等原样保留，只覆盖面板负责的那几个键。
+ */
+async function writeProviderConfig(ctx, body) {
+  const settings = ctx.get('settings')
+  if (!settings || typeof settings.mutate !== 'function') throw new Error('settings 服务不可用或不可写')
+  const action = body.action
+  const route = typeof body.route === 'string' ? body.route.trim() : ''
+  const revision = body.revisions && typeof body.revisions['llm-pi-ai'] === 'number'
+    ? body.revisions['llm-pi-ai'] : undefined
+  const bad = (msg) => { const e = new Error(msg); e.statusCode = 400; return e }
+
+  if (action === 'delete') {
+    if (!route) throw bad('请求缺少 route')
+    const dir = readModelDirectory(ctx)
+    const p = (dir.providers || []).find((x) => (x.route || x.id) === route)
+    if (!p) throw bad(`未找到 Provider：${route}`)
+    if (p.kind !== 'pi-ai') throw bad('内置 Provider（如 DeepSeek 官方）不能删除，只能编辑其模型')
+    try {
+      await settings.mutate('llm-pi-ai', [{ op: 'unset', path: ['providers', p.route || route] }], revision)
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e)
+      const err = new Error(`删除被拒绝：${msg}`)
+      err.statusCode = /conflict|revision/i.test(msg) ? 409 : 400
+      throw err
+    }
+    return { ok: true, deleted: p.route || route, savedAt: Date.now() }
+  }
+
+  if (action !== 'create' && action !== 'update') throw bad(`不支持的 action：${action}`)
+  if (!route || !ROUTE_KEY_RE.test(route)) throw bad('路由 key 非法：须以字母数字开头，只能含字母、数字与 . _ -')
+  const src = body.profile && typeof body.profile === 'object' && !Array.isArray(body.profile) ? body.profile : {}
+  const api = typeof src.api === 'string' ? src.api : ''
+  if (PI_AI_APIS.indexOf(api) < 0) throw bad(`api 非法：只支持 ${PI_AI_APIS.join(' / ')}`)
+  const baseURL = typeof src.baseURL === 'string' ? src.baseURL.trim() : ''
+  if (!/^https?:\/\//i.test(baseURL)) throw bad('baseURL 非法：须以 http:// 或 https:// 开头')
+  let apiKeyEnv = typeof src.apiKeyEnv === 'string' ? src.apiKeyEnv.trim() : ''
+  if (apiKeyEnv) {
+    try { credentialRef(apiKeyEnv) } catch { throw bad('apiKeyEnv 非法：须是合法的环境变量名（如 MODELSCOPE_API_KEY）') }
+  }
+  const models = Array.isArray(src.models) ? src.models : []
+  if (models.length === 0) throw bad('至少需要一个模型')
+  const seen = new Set()
+  for (const m of models) {
+    const id = m && typeof m.id === 'string' ? m.id.trim() : ''
+    if (!id) throw bad('模型 id 不能为空')
+    if (seen.has(id)) throw bad(`模型 id 重复：${id}`)
+    seen.add(id)
+  }
+
+  const base = Object.assign({}, src)
+  delete base.models
+  const displayName = typeof src.displayName === 'string' ? src.displayName.trim() : ''
+  if (displayName) base.displayName = displayName; else delete base.displayName
+  base.api = api
+  base.baseURL = baseURL
+  if (apiKeyEnv) base.apiKeyEnv = apiKeyEnv; else delete base.apiKeyEnv
+  base.models = models.map((m) => piAiModelWrite(
+    Object.assign({}, m, { id: String(m.id).trim() }),
+    { api, route, baseURL }
+  ))
+
+  const apiKey = typeof body.apiKey === 'string' ? body.apiKey.trim() : ''
+  if (apiKey) {
+    if (!apiKeyEnv) {
+      // Key 填了但 apiKeyEnv 留空：按路由 key 自动生成凭据库条目名（与客户端 dkmEnvFromRoute 一致），
+      // 不再要求用户现编一个环境变量名
+      const s = String(route || '').toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+      apiKeyEnv = (s ? (/^[0-9]/.test(s) ? 'KEY_' + s : s) : 'PROVIDER') + '_API_KEY'
+      base.apiKeyEnv = apiKeyEnv
+    }
+    const credentials = ctx.get('credentials')
+    if (!credentials || typeof credentials.set !== 'function') throw bad('凭据库不可用，无法保存 API Key')
+    try {
+      await credentials.set(credentialRef(apiKeyEnv), apiKey)
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e)
+      const err = new Error(`写入本地凭据库失败：${msg}`)
+      err.statusCode = 400
+      throw err
+    }
+  }
+
+  try {
+    await settings.mutate('llm-pi-ai', [{ op: 'set', path: ['providers', route], value: base }], revision)
+  } catch (e) {
+    const msg = e && e.message ? e.message : String(e)
+    const err = new Error(`写回官方配置被拒绝：${msg}`)
+    err.statusCode = /conflict|revision/i.test(msg) ? 409 : 400
+    throw err
+  }
+  return { ok: true, route, created: action === 'create', savedAt: Date.now() }
+}
+
+/** 功能注册表条目：index.js 组装 hostSetups 时使用。 */
+export const feature = {
+  id: 'providerconfig',
+  name: '模型提供商',
+  description: '管理模型 Provider 的端点与 API Key（增删改 + 拉取上游模型列表）',
+  defaultEnabled: false,
+  setup(ctx) {
+    const webServer = ctx.get('webServer')
+    if (webServer === undefined) throw new Error('webServer 服务不可用，无法提供模型提供商路由')
+    const handler = async (req, res) => {
+      if (rejectUntrustedRequest(ctx, req, res)) return
+      try {
+        if (req.method === 'GET') {
+          const payload = readModelDirectory(ctx)
+          await enrichApiKeyStatus(ctx, payload)
+          sendJson(res, 200, payload)
+          return
+        }
+        if (req.method === 'POST') {
+          const body = await readBody(req)
+          const action = body && typeof body === 'object' ? body.action : undefined
+          const result = action === 'listModels'
+            ? await fetchProviderModels(ctx, body)
+            : await writeProviderConfig(ctx, body)
+          sendJson(res, 200, result)
+          return
+        }
+        sendJson(res, 405, { error: `不支持的请求方法：${req.method}` })
+      } catch (e) {
+        const status = e && e.statusCode ? e.statusCode : 500
+        sendJson(res, status, { ok: false, error: e instanceof Error ? e.message : String(e) })
+      }
+    }
+    return webServer.register({ kind: 'exact', path: '/dsh-dock/providerconfig', handler })
+  },
+}