@sunshaobei/dsh-mcp-manager 0.0.0-stage → 0.4.0

package/lib/client/core/state.d.ts

@@ -0,0 +1,120 @@
+/**
+ * dsh-mcp-manager — 客户端状态类型与工厂。
+ *
+ * 所有可变状态收进单一 McpState 对象，在 apply() 内创建，经参数传递到各模块。
+ * 禁止模块级全局变量，确保连续挂载/卸载无残留。
+ *
+ * 跨端 DTO 形状（服务器列表条目 / 浮窗 UI 配置）的物理定义在 src/shared/dto.ts
+ * （D5）：这里只做薄 re-export，客户端不得自带等值副本——一致性锁
+ * test/e2e/cross-end-lock.test.ts 与 test/integration/service-contract.test.ts 盯这条。
+ */
+import { API } from "./constants.js";
+import type { ClientUiConfig, McpServerListEntry, ServerState } from "../../shared/interface.js";
+import type { ISessions } from "@deepseek-ai/dsh-api-session-controller/client";
+import type { LocaleRuntime } from "@deepseek-ai/dsh-client-locale/client";
+import type { SlotRegistry } from "@deepseek-ai/dsh-client-ui-renderer/client";
+export type { ClientUiConfig, McpServerListEntry } from "../../shared/interface.js";
+/** 各状态计数（六态键的物理定义在 shared/status.ts，宿主与客户端同一份）。 */
+export type McpCounts = Partial<Record<ServerState, number>>;
+/** MCP 管理器客户端全部可变状态。 */
+export interface McpState {
+    /** 模态面板遮罩层根元素。 */
+    overlay: HTMLElement | undefined;
+    /** 模态面板卡片根元素。 */
+    card: HTMLElement | undefined;
+    /** 模态面板 body 容器。 */
+    bodyEl: HTMLElement | undefined;
+    /** 模态面板是否打开。 */
+    open: boolean;
+    /** 打开面板时的焦点归属（R6 关还焦：close 时恢复；非元素/已卸载则跳过）。 */
+    panelOpener: HTMLElement | undefined;
+    /** 当前激活的 tab（servers / quick）。 */
+    activeTab: string;
+    /** 服务器列表。 */
+    servers: McpServerListEntry[];
+    /** 各状态计数。 */
+    counts: McpCounts;
+    /** 正在编辑的服务器名称（undefined 表示新建）。 */
+    editingName: string | undefined;
+    /** 正在编辑的服务器原始数据。 */
+    editing: McpServerListEntry | undefined;
+    floatPill: HTMLElement | undefined;
+    floatPanel: HTMLElement | undefined;
+    floatOpen: boolean;
+    currentCwd: string | undefined;
+    /**
+     * 是否已解析出当前会话（#1028）。false = **未知**，与「已知但无 cwd」是两态：
+     * 未知时不得向宿主上报 `cwd:""`，否则会把「读不到」变成「清空项目级绑定」。
+     */
+    sessionResolved: boolean;
+    /** 未知态的一次性告警闸（可观测性：未知态无 UI 表现，不告警等于静默失效）。 */
+    warnedUnknownSession: boolean;
+    /**
+     * 连续未知帧计数（#1028 告警口径）。官方会话快照要等 mainView 持有才就绪，
+     * 故**首帧未知是竞态不是故障**（每次冷启动必现）；用它把噪声与真失联分开。
+     */
+    unknownSessionFrames: number;
+    projectRoot: string | undefined;
+    updateFloatState: (() => void) | undefined;
+    mcpUiConfig: ClientUiConfig;
+    API: typeof API;
+}
+/** 创建初始状态对象。 */
+export declare function createState(): McpState;
+/**
+ * 跨模块动作回调集合。
+ * index.ts 装配，避免 feature 模块间循环依赖——各模块通过 actions 调用
+ * 其他模块的功能（如 servers.ts 调用 actions.refresh / actions.resetForm）。
+ */
+export interface UiActions {
+    refresh: () => Promise<boolean>;
+    resetForm: () => void;
+    beginEdit: (server: McpServerListEntry) => void;
+    switchTab: (tab: string) => void;
+    close: () => void;
+    showPanel: () => void;
+    toggleFloat: (force?: boolean) => void;
+}
+/**
+ * locale 服务最小面：官方 `LocaleRuntime`（dsh-client-locale，宿主 ctx.locale）的 Pick。
+ * 成员一律必选——官方类上本就是必选方法，服务本体缺失由 `ctx.get("locale")` 的
+ * `| undefined` 表达；index.ts 里既有的 typeof 守卫（H4）是运行时防御，原样保留。
+ *
+ * 官方形状对齐说明：官方 `register` 两个重载都返回 disposer `() => void`，本包调用点
+ * **既成事实地丢弃**该返回值（只把 subscribe 的 unsub 存进 effect 卸载），此处仅把返回
+ * 类型按官方补齐，**不新增任何清理/生命周期逻辑**。`getSnapshot` 官方必返 `LocaleSnapshot`，
+ * 本包只在 typeof 守卫里探测成员存在，从不读返回值，故面里只带方法类型不带结果。
+ */
+export type McpLocaleService = Pick<LocaleRuntime, "register" | "subscribe" | "getSnapshot" | "bind">;
+/**
+ * slots 服务最小面：官方 `SlotRegistry`（dsh-client-ui-renderer，宿主 ctx.slots）的
+ * inject/register Pick，与 index.ts 的行配置装配面同源同形。
+ *
+ * 官方形状对齐说明：官方 `inject(key, callback)` 与 `register(options, component)` **都**
+ * 返回 disposer `() => void`；本类型此前把 inject 误写成返回 void（index.ts 的局部声明
+ * 反而写对了），此处一律以官方为准。成员不再 optional：服务本体缺失已由
+ * `ctx.get("slots")` 的 `| undefined` 表达，调用点本就先判空再调（G2 零行为改动）。
+ */
+export type McpSlotsService = Pick<SlotRegistry, "inject" | "register">;
+/**
+ * 客户端上下文最小面（S2：get 重载 + effect + sessions?；H6 不反向依赖未清洁形状）。
+ * get("locale"/"slots")返回上两个官方派生面，未声明服务时为 undefined；其余名回落 unknown。
+ */
+export interface McpClientContext {
+    get(name: "locale"): McpLocaleService | undefined;
+    get(name: "slots"): McpSlotsService | undefined;
+    get(name: string): unknown;
+    effect: (fn: () => () => void, label?: string) => void;
+    /**
+     * 官方会话服务（#1028：不再自建镜像面——rc.2 的 `SessionListState` 已无 `current`，
+     * 自建形状会与官方静默分叉）。未注入时为 undefined。
+     */
+    sessions?: ISessions;
+}
+/**
+ * 客户端 HTTP 请求选项最小面（P3-b/B6：api 二选一选 A 泛型）。
+ * 继承 DOM RequestInit（method/headers/body/signal），仅增 timeoutMs 兜底预算。
+ */
+export interface ApiRequestOptions extends RequestInit {
+    timeoutMs?: number;
+}

package/lib/client/float/float.d.ts

@@ -0,0 +1,126 @@
+/**
+ * dsh-mcp-manager — 客户端右上角浮窗。
+ *
+ * 浮窗胶囊（状态点 + 摘要计数）挂在会话滚动容器右上角，点击展开下拉面板
+ * 展示项目/全局 MCP 服务器列表 + 快捷操作（连接/断开/禁用）。
+ * 跨模块动作（showPanel / refresh）经 actions 注入，不直接引用 panel 模块。
+ */
+import type { McpClientContext, McpServerListEntry, McpState, UiActions } from "../core/state.js";
+import type { ClientUiConfig, FloatBreakpoint, ViewportPoint } from "../../shared/interface.js";
+/** 胶囊状态点配色：失败红 / 有连接绿 / 否则中性灰（与历史三态一致）。 */
+export declare function pillDotColor(fail: boolean, connected: number): string;
+/**
+ * 胶囊的 title / aria-label：一台服务器都没有时不设（保留宿主默认 tooltip），
+ * 有失败时追加失败计数，否则 aria 给出「已连/总数」（无总数时 title 保持朴素）。
+ */
+export declare function pillHints(total: number, bad: number, connected: number): {
+    title: string;
+    aria: string;
+};
+/** 渲染浮窗胶囊（状态点 + 摘要计数 + 失败/中性态）。 */
+export declare function renderPill(state: McpState): void;
+/**
+ * 一行上的动作描述：按钮外观 + 打到哪个口 + 请求形状 + 失败告警的稳定标识。
+ * tag 是 console 文案用的动作名（与 i18n 文案解耦：翻界面不改日志）。
+ */
+interface RowAction {
+    className: string;
+    label: string;
+    url: string;
+    method: "POST" | "PATCH";
+    tag: string;
+    /** 只有 PATCH 动作带载荷（连接/断开是纯 POST，历史形状如此）。 */
+    body?: string;
+}
+/** 主操作（每行恰好一个）：connected → 断开；disabled → 启用；其余 → 连接。 */
+export declare function primaryRowAction(server: McpServerListEntry, state: McpState, cwdQuery: string): RowAction;
+/** 禁用动作（仅非 disabled 行有）：URL 不带 cwd（历史形状如此，勿补）。 */
+export declare function disableRowAction(server: McpServerListEntry, state: McpState): RowAction;
+/** 请求 init：带载荷的 PATCH 补 content-type；纯 POST 不带头（历史形状）。 */
+export declare function rowRequestInit(action: RowAction): {
+    method: string;
+    headers?: Record<string, string>;
+    body?: string;
+};
+/**
+ * 按状态分桶（桶序 = STATUS_ORDER，固定六态先建空桶）。未知状态归 stopped 桶——
+ * 六态是唯一合法取值域，落到兜底桶而不是丢弃该行。
+ */
+export declare function bucketServersByStatus(list: McpServerListEntry[]): Map<string, McpServerListEntry[]>;
+/** 行级 stagger 序号：动画关闭返回 undefined（该行不加 dm-stagger、不进序）。 */
+export declare function nextStagger(staggerBase: {
+    n: number;
+}, animate: boolean): number | undefined;
+/** 浮窗标题的项目名：项目根末段；无项目根回落「全局会话」。 */
+export declare function floatProjectName(state: McpState): string;
+/** 需要置顶提醒的服务器（失败 + 重连中）。 */
+export declare function needsAttention(server: McpServerListEntry): boolean;
+/** 渲染浮窗下拉面板（健康摘要 + 失败优先 + scope 分组）。 */
+export declare function renderFloatPanel(state: McpState, actions: UiActions): void;
+/** 切换浮窗展开/收起（Apple Fluid：锚点→对角 scale；先渲染后定位）。 */
+export declare function toggleFloat(state: McpState, actions: UiActions, force?: boolean): void;
+/** 水平锚点判定：left-* 贴左缘，其余贴右缘（胶囊与面板共用同一口径）。 */
+export declare function anchorsLeft(position: string | undefined): boolean;
+/** Fluid 展开原点：锚点所在的那个角（胶囊贴边角 → 面板向对角展开）。 */
+export declare function transformOriginFor(isLeft: boolean, anchorBottom: boolean): string;
+/** 下拉面板定位（fixed 跟随胶囊，避免被滚动容器裁剪；四角感知 + 视口终 clamp）。 */
+export declare function placePanel(state: McpState): void;
+/** 会话滚动容器：聊天消息实际滚动的区域（shell 的 data-conversation-scroll）。 */
+export declare function conversationHost(): Element;
+/** 全局 overlay 层：下拉面板挂这里（fixed 定位，避免被滚动容器裁剪）。 */
+export declare function panelHost(): Element;
+/**
+ * 当前会话是否空白会话（空白会话用另一档垂直偏移）。取不到会话面一律判非空白。
+ *
+ * #1028：与 core/session.ts 共用 core/current-session.ts 单一接缝，判定改用官方口径
+ * `retainedBy.mainView`；`blank` 直读官方 `SessionSummary.blank`，不从 cwd 空串推。
+ */
+export declare function isBlankSession(ctx: McpClientContext): boolean;
+/** 从 settings.yaml 读取的配置决定新/老会话垂直偏移。 */
+export declare function floatTopOffset(ctx: McpClientContext, state: McpState): number;
+/** 胶囊位置配置白名单：只认四个锚点，其余（含缺省）回落 top-right（历史行为）。 */
+export declare function floatPositionOf(cfg: ClientUiConfig): ClientUiConfig["position"];
+/** 胶囊定位入参（锚点 + 偏移）：位置白名单归一、水平偏移缺省 8、垂直偏移按会话形态。 */
+export declare function pillAnchors(cfg: ClientUiConfig, ctx: McpClientContext, state: McpState): {
+    isLeft: boolean;
+    isBottom: boolean;
+    offsetX: number;
+    offsetY: number;
+};
+/** 底部锚点是否改用 composer seat 上缘当下边界（#128：仅非 wide 断点）。 */
+export declare function usesComposerSeat(isBottom: boolean, bp: FloatBreakpoint): boolean;
+/** 底部锚点的容器下边界：composer seat 贴底时改用 seat 上缘（胶囊上移到输入区上方）。 */
+export declare function dockedBottomEdge(containerRect: {
+    top: number;
+    bottom: number;
+}): number;
+/** 胶囊定位纯计算的入参（DOM 读口在调用面，坐标算式在这里，可直测）。 */
+interface PillPlacementInput {
+    rect: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    width: number;
+    height: number;
+    isLeft: boolean;
+    isBottom: boolean;
+    offsetX: number;
+    offsetY: number;
+    /** 底部锚点下边界（已含 composer seat 改写，见 dockedBottomEdge）。 */
+    bottomEdge: number;
+    viewportW: number;
+    viewportH: number;
+}
+/**
+ * 胶囊终坐标（纯计算）：水平按锚点贴容器左右缘、垂直按锚点（bottom 从下边界上推、
+ * clamp 到视口上缘；top 从容器顶下移），最后统一走视口 clamp。
+ */
+export declare function pillPlacement(input: PillPlacementInput): ViewportPoint;
+/**
+ * 挂载浮窗：胶囊继续挂在会话滚动容器（scrollBody）内并钉住右上角，下拉面板
+ * fixed 跟随。返回 disposer 函数。
+ */
+export declare function mountFloat(ctx: McpClientContext, state: McpState, actions: UiActions): () => void;
+export {};

package/lib/client/float/panel.d.ts

@@ -0,0 +1,29 @@
+/**
+ * dsh-mcp-manager — 客户端模态面板生命周期。
+ *
+ * 面板的打开/关闭/tab 切换/数据刷新。
+ * 跨模块渲染（renderServers / buildQuickAdd / renderPill / renderFloatPanel）
+ * 直接 import 用到的模块——本模块是 feature 模块的汇聚点，构成单向依赖图：
+ * panel → servers / quick-add / float。
+ */
+import type { McpState, UiActions } from "../core/state.js";
+/**
+ * 刷新服务器列表与浮窗摘要（单飞：in-flight 复用；#111 变更点驱动）。
+ * 返回 true=成功；false=失败（调用方按退避重试）。
+ */
+export declare function refresh(state: McpState, actions: UiActions): Promise<boolean>;
+/** 切换面板 tab（servers / quick）。 */
+export declare function switchTab(state: McpState, actions: UiActions, tab: string): void;
+/** 关闭模态面板（Fluid：卡片中心收束 + 遮罩淡出；完成后再 hidden）。
+ *
+ * R1 状态同翻：state.open=false 的同一同步块内摘除 aria-modal（不经 300ms
+ * 动画回调——动画被打断/定时器漂移时标记与状态永久错位，见 #947）。
+ * R2 常驻壳无标记：hidden 元素仍被 querySelector 命中，故必须摘属性而非
+ * 置 "false"（裸 [aria-modal] 存在检查仍命中 "false"，且关闭态留 "false"
+ * 语义错误）。R6 关还焦：同步把焦点还给打开者（便宜且安全）。
+ */
+export declare function close(state: McpState): void;
+/** 打开模态面板（首次调用时创建 DOM 结构；Fluid：中心 scale 0.78→1）。 */
+export declare function showPanel(state: McpState, actions: UiActions): void;
+/** C4：卸载配对清理（index.ts effect disposer 调用）——移除 Escape keydown 监听。 */
+export declare function disposePanel(state: McpState): void;

package/lib/client/float/quick-add.d.ts

@@ -0,0 +1,38 @@
+/**
+ * dsh-mcp-manager — 客户端「快速接入」页：多源 mcp.json 编辑器与保存执行面。
+ *
+ * 手填表单已整体移除（v0.4.0）：添加/编辑一律经「多源 mcp.json 编辑器」
+ * （beginEdit 打开 openJsonEditor，保存走 performSaveRequest）。跨模块动作
+ * （refresh / switchTab）经 actions 注入，不直接引用 panel 模块，避免循环依赖。
+ */
+import type { McpState, UiActions } from "../core/state.js";
+import type { McpManagerServerInput, McpServerListEntry } from "../../shared/interface.js";
+/** 当前保存归属（project/global）：按 projectRoot 回落，无 DOM 依赖。 */
+export declare function formScopeValue(state: McpState): string;
+/** 当前会话 cwd（POST body 携带，宿主据此切换项目级 MCP）。 */
+export declare function currentCwdBody(state: McpState): Record<string, string>;
+/** 是否处于编辑态（editingName 已设）。 */
+export declare function isEditing(state: McpState): boolean;
+/** 重置编辑态（表单已移除，只清编辑面）。 */
+export declare function resetForm(state: McpState): void;
+/** 迁移式保存判据：正在编辑，且（改名 或 改归属）。宿主 PATCH 按 (scope,name) 定位且
+ * 强制沿用定位名，故这两类改动必须走 POST+DELETE（见 performSaveRequest）。 */
+export declare function isMigratedEdit(state: McpState, server: McpManagerServerInput, payload: Record<string, unknown>): boolean;
+/** JSON 写请求的公共 init（PATCH / POST 共用）。 */
+export declare function jsonWriteInit(payload: Record<string, unknown>): {
+    method: "POST" | "PATCH";
+    headers: Record<string, string>;
+    body: string;
+};
+/**
+ * 保存执行面（三种落点）与中止信号。
+ * C11 迁移式保存：宿主 PATCH 按 (scope,name) 定位且强制沿用定位名——编辑改名/改归属
+ * 会 404 not found 无引导。先 POST 新条目再 DELETE 旧条目，任何失败即抛（保留原条目），
+ * 避免半迁移脏数据。
+ * @returns false = 已中止（大声失败），调用方不得 refresh。
+ */
+export declare function performSaveRequest(state: McpState, server: McpManagerServerInput, payload: Record<string, unknown>): Promise<boolean>;
+/** 进入编辑模式：记录编辑态并弹出大号 JSON 编辑器（行内编辑太小，弃用表单填充）。 */
+export declare function beginEdit(state: McpState, actions: UiActions, server: McpServerListEntry): void;
+/** 构建「快速接入」页面（多源 mcp.json 编辑器）。 */
+export declare function buildQuickAdd(state: McpState, actions: UiActions): HTMLElement;

package/lib/client/float/servers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * dsh-mcp-manager — 客户端「服务器列表页」渲染。
+ *
+ * 按状态分级展示服务器卡片（端点 / 错误 / 工具列表 / 操作按钮）。
+ * 跨模块动作（refresh / resetForm / beginEdit）经 actions 注入，不直接引用
+ * panel/quick-add 模块，避免循环依赖。
+ */
+import type { McpServerListEntry, McpState, UiActions } from "../core/state.js";
+/** 服务器端点摘要：streamable-http 显示 URL，stdio 显示 command + args。 */
+export declare function endpointOf(server: McpServerListEntry): string;
+/** 操作按钮（统一失败提示）。 */
+export declare function actionButton(label: string, onClick: () => void | Promise<void>, primary?: boolean, danger?: boolean): HTMLElement;
+/** 工具折叠组：interactive 出 checkbox（可逐个禁用），否则出纯文本工具名。 */
+export declare function serverToolsDetails(server: McpServerListEntry, toolCount: number, opts: {
+    tools: boolean;
+    openTools?: Set<string>;
+}, state: McpState, actions: UiActions, interactive: boolean): HTMLElement;
+/** 一个操作按钮的规格（label / 主按钮样式 / 执行体）。 */
+interface ActionSpec {
+    label: string;
+    primary: boolean;
+    danger?: boolean;
+    run: () => void | Promise<void>;
+}
+/** JSON 写请求 init（PATCH enabled 用；形态与 quick-add 同款）。 */
+export declare function jsonPatchInit(enabled: boolean): {
+    method: "PATCH";
+    headers: Record<string, string>;
+    body: string;
+};
+/** POST 后刷新（连接/断开/重连三个动作的执行体同式）。 */
+export declare function postThenRefresh(state: McpState, actions: UiActions, url: string): () => Promise<void>;
+export declare function statusActions(server: McpServerListEntry, state: McpState, actions: UiActions, scopeQuery: string, cwdQuery: string): ActionSpec[];
+/** 禁用动作（非 disabled 行才有）：PATCH 后若正在编辑该条目则重置表单。 */
+export declare function disableAction(server: McpServerListEntry, state: McpState, actions: UiActions, scopeQuery: string, cwdQuery: string): ActionSpec;
+/** 删除动作：先确认（未确认即中止），DELETE 后若正在编辑该条目则重置表单。 */
+export declare function deleteAction(server: McpServerListEntry, state: McpState, actions: UiActions, scopeQuery: string): ActionSpec;
+/** 需要置顶提醒的服务器（失败 + 重连中）。 */
+export declare function needsAttention(server: McpServerListEntry): boolean;
+/** 按状态分桶（桶序 = STATUS_ORDER；未知状态归 stopped 桶，不丢行）。 */
+export declare function bucketByStatus(list: McpServerListEntry[]): Map<string, McpServerListEntry[]>;
+/** 卡片根类名：失败 / 重连中加 --fail 修饰。 */
+export declare function serverCardClass(server: McpServerListEntry): string;
+/** 卡片头部：名称 / transport 徽标 / scope 徽标 / 状态徽标 / 工具计数。 */
+export declare function serverCardHeader(server: McpServerListEntry, toolCount: number): HTMLElement;
+/** 渲染单台服务器卡片。 */
+export declare function renderServer(server: McpServerListEntry, state: McpState, actions: UiActions, opts?: {
+    tools: boolean;
+    openTools?: Set<string>;
+}): HTMLElement;
+/** 渲染服务器列表页（#362 交互拍板 1a：项目级 / 全局级两大分组，各自内部再按状态）。
+ * 单池（#767）后两大分组的服务器都经中间层，工具 checkbox 一律可用。 */
+export declare function renderServers(state: McpState, actions: UiActions): void;
+export {};

package/lib/client/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * dsh-mcp-manager — 浏览器端客户端入口（装配层）。
+ *
+ * 仅含装配逻辑，不含业务实现。业务实现在 constants/dom/servers/quick-add/
+ * panel/float/session/settings-card 各模块中。
+ *
+ * 挂载浏览器端：注入样式 + 右上角浮窗（会话跟随）+ 管理面板 + 插件行配置页。
+ * 失败策略：只 warn 不抛，绝不让 GUI 启动失败。
+ *
+ * 客户端干净模块：只导出 apply/inject，契约外壳（IIFE/load/Symbol.toStringTag 装配）
+ * 由 scripts/build/build-client.ts 统一生成——源码不写任何 loader 痕迹。
+ * 样式：独立 style.css（见同目录），build-client 的 .css text-loader 构建期内联为字符串。
+ *
+ * React 由 dsh web 的 factory require("react") 注入（build-client externals 路径）；
+ * 插件行配置页由宿主 React 渲染，故客户端必须提供 React 组件。
+ */
+import { type McpClientContext } from "./core/state.js";
+import { type McpLocaleKey } from "./locales.js";
+declare module "@deepseek-ai/dsh-client-ui-slots" {
+    interface LocaleNamespaceMap {
+        /** dsh-mcp-manager 浮窗/面板/表单/设置卡文案。 */
+        mcpManager: McpLocaleKey;
+    }
+}
+export declare function apply(ctx: McpClientContext): void;
+export declare const inject: string[];

package/lib/client/locales.d.ts

@@ -0,0 +1,123 @@
+/**
+ * dsh-mcp-manager — 客户端文案字典（issue #348：复用官方 dsh-client-locale）。
+ *
+ * 双语平衡：`zh` 为 key 源；`en` 必须覆盖全部 key（编译期锁平衡）。
+ * 动态数据用 `{name}` 占位模板，渲染期由 t 插值。
+ * 不进字典：console 日志、placeholder 示例值（context7/npx/URL/JSON 样例）、
+ * 服务器名等动态数据（官方原则：数据不翻译）。
+ */
+/** 简体中文字典（key 源）。 */
+export declare const zh: {
+    readonly stConnected: "运行中";
+    readonly stConnecting: "连接中";
+    readonly stReconnecting: "重连中";
+    readonly stStopped: "未连接";
+    readonly stDisabled: "已停用";
+    readonly stFailed: "失败";
+    readonly connect: "连接";
+    readonly disconnect: "断开";
+    readonly reconnect: "重连";
+    readonly enable: "启用";
+    readonly enableAndConnect: "启用并连接";
+    readonly disable: "禁用";
+    readonly edit: "编辑";
+    readonly delete: "删除";
+    readonly save: "保存";
+    readonly cancel: "取消";
+    readonly refresh: "刷新";
+    readonly close: "关闭";
+    readonly cancelEdit: "取消编辑";
+    readonly saveFail: "保存失败：{msg}";
+    readonly actionFail: "操作失败：{msg}";
+    readonly loadFail: "加载失败：{msg}";
+    readonly floatAriaLabel: "MCP 管理器";
+    readonly floatTitle: "MCP 管理器（点击展开）";
+    readonly floatManage: "管理";
+    readonly floatGlobalSession: "全局会话";
+    readonly groupProject: "项目级";
+    readonly groupGlobal: "全局";
+    readonly badgeScopeProject: "项目";
+    readonly badgeScopeGlobal: "全局";
+    readonly serverMeta: "{status} · {tools} 工具";
+    readonly toolsCount: "工具（{n}）";
+    readonly toolsCountPlain: "{n} 工具";
+    readonly statusGroupCount: "{status}（{n}）";
+    readonly groupAttention: "需关注（{n}）";
+    readonly healthRunning: "运行中 {n}";
+    readonly healthConnecting: "连接中 {n}";
+    readonly healthStopped: "未连接 {n}";
+    readonly healthFailed: "失败 {n}";
+    readonly floatEmptyTitle: "还没有 MCP 服务器";
+    readonly floatEmptyCta: "去添加";
+    readonly panelTitle: "MCP 管理器";
+    readonly tabServers: "服务器";
+    readonly tabQuickAdd: "快速接入";
+    readonly countsConnected: "运行中 {n}";
+    readonly countsConnecting: "连接中 {n}";
+    readonly countsFailed: "失败 {n}";
+    readonly countsSummary: "共 {n} 台 · {parts}";
+    readonly countsSummaryOnly: "共 {n} 台";
+    readonly addServer: "添加服务器";
+    readonly editServer: "编辑服务器：{name}";
+    readonly nameLabel: "服务器名称（唯一，作为 mcp__<name>__ 前缀）";
+    readonly ownershipLabel: "归属";
+    readonly transportLabel: "传输类型";
+    readonly commandLabel: "命令（stdio）";
+    readonly argsLabel: "参数（逗号分隔）";
+    readonly envLabel: "环境变量（每行 KEY=VALUE，支持 ${ENV} 引用，值为空则继承父环境）";
+    readonly cwdLabel: "工作目录（可选）";
+    readonly urlLabel: "URL（streamable-http）";
+    readonly headersLabel: "请求头（每行 KEY: VALUE，支持 ${ENV} 引用）";
+    readonly enabledLabel: "启用（保存后立即连接）";
+    readonly scopeProjectOpt: "项目级（<项目>/.dsh/dsh-mcp-manager/mcp.json，随会话切换）";
+    readonly scopeGlobalOpt: "全局（本机配置）";
+    readonly transportStdioOpt: "stdio（本地子进程）";
+    readonly transportHttpOpt: "streamable-http（远程）";
+    readonly envPlaceholder: "每行 KEY=VALUE，如\nCONTEXT7_API_KEY=${CONTEXT7_API_KEY}";
+    readonly headersPlaceholder: "每行 KEY: VALUE，支持 ${ENV} 引用，如\nAuthorization: Bearer ${CONTEXT7_API_KEY}";
+    readonly cwdPlaceholder: "可选工作目录";
+    readonly sourcesTitle: "mcp.json 配置文件（保存即互斥同步）";
+    readonly srcGlobalAgents: "全局 .agents/mcp.json";
+    readonly srcGlobalDsh: "全局 .dsh/mcp.json";
+    readonly srcProjectAgents: "项目 .agents/mcp.json";
+    readonly srcProjectDsh: "项目 .dsh/mcp.json";
+    readonly srcNotExists: "尚不存在，保存时创建";
+    readonly srcNeedSession: "需要项目会话后可用";
+    readonly srcUngrouped: "其他（未声明来源）";
+    readonly srcQuickSetup: "快速配置该来源";
+    readonly srcEdit: "编辑";
+    readonly srcSave: "保存并同步";
+    readonly srcSavedOk: "已保存并同步：{names}";
+    readonly srcMutexRemoved: "互斥移除同名：{names}";
+    readonly srcActivateThis: "启用此来源";
+    readonly jsonNameFixed: "JSON 里的 name 不可改（如需改名请删除后新建）";
+    readonly pasteTitle: "粘贴 mcpServers JSON 导入";
+    readonly importJson: "导入 JSON";
+    readonly importFromFile: "从 mcp.json 文件导入";
+    readonly importPathPlaceholder: "或填 mcp.json 文件路径导入，如 ~/.claude/mcp.json";
+    readonly importedOk: "已导入：{names}";
+    readonly importedNone: "（无）";
+    readonly importSkipped: "跳过（已存在）：{names}";
+    readonly importFail: "导入失败：{msg}";
+    readonly serversEmpty: "还没有配置 MCP 服务器。切到「快速接入」页添加，或粘贴 mcpServers JSON 导入。";
+    readonly confirmDelete: "删除 MCP 服务器「{name}」？";
+    readonly settingsLoading: "MCP 管理器：加载中…";
+    readonly settingsName: "MCP 管理器（dsh-mcp-manager）";
+    readonly settingsDescription: "浮窗位置 / 水平·垂直·空白偏移";
+    readonly anchorLabel: "锚点";
+    readonly posTopRight: "右上（top-right）";
+    readonly posTopLeft: "左上（top-left）";
+    readonly posBottomRight: "右下（bottom-right）";
+    readonly posBottomLeft: "左下（bottom-left）";
+    readonly offsetX: "水平偏移";
+    readonly offsetY: "垂直偏移";
+    readonly blankY: "空白偏移";
+    readonly zIndexBase: "层级基准";
+    readonly settingsHint: "保存即热更新：浮窗位置与偏移即时生效并持久化（无需重启 dsh web）。";
+    readonly savingNow: "保存中…";
+    readonly settingsSavedOk: "已保存——浮窗位置即时生效（无需重启）";
+};
+/** 字典 key 并集（LocaleNamespaceMap 声明合并用）。 */
+export type McpLocaleKey = keyof typeof zh;
+/** 英文词典：必须与 zh key 完整对齐。 */
+export declare const en: Record<McpLocaleKey, string>;

package/lib/client/settings/settings-card.d.ts

@@ -0,0 +1,47 @@
+/**
+ * dsh-mcp-manager — 插件行配置页（SettingsCard）。
+ *
+ * 浮窗位置 / 偏移编辑区，React 组件（经 build-client externals 注入）。
+ * 读/写走 /api/dsh-mcp/config（GET 读 / POST 写），保存后经 SSE 热更新。
+ * 注册面：plugins.row.config，由 index.ts 装配。
+ */
+import * as React from "react";
+import type { PluginConfigViewProps } from "@deepseek-ai/dsh-client-ui-plugin-manager/client";
+/**
+ * plugins.row.config owner 传给组件的视图与表单能力：官方 `PluginConfigViewProps`
+ * （dsh-client-ui-plugin-manager，plugins.row.config / plugins.bundle.config /
+ * plugins.item 三个 seat 的 owner 形状）原样透传，不另立镜像。
+ *
+ * 事实记录：**本组件不读 props.form**——页面读写走自身的 /api/dsh-mcp/config
+ * （GET 读 / POST 写，见下 SettingsPage），props.form 只是类型面上随 owner 契约到达。
+ * 换官方类型不改变渲染行为，也不因「用上了 form」而新增任何读取。
+ */
+export type SettingsCardProps = PluginConfigViewProps;
+/**
+ * summary 由插件行自身呈现；此组件不发配置/健康请求，也不返回嵌套 page DOM。
+ * page 挂载独立表单组件，切换视图时也不会跨分支改变 Hook 顺序。
+ *
+ * 【R3 原语层接入：只迁 Button】
+ * 保存按钮改用 <Button className="dm-set-save">——Button 原语在共享块里**一条规则都不出**
+ * （视觉由调用点传入的领域类承担），故这是纯增益：拿到 dsu-btn / data-dsu-btn 钩子与恒定
+ * 的 type="button"，像素零变化。
+ *
+ * 下面四族**刻意不迁**，理由逐条钉住（防止被当成漏项「顺手补上」）：
+ *   1. dm-set-field + dm-set-input：dm-set-field 是 inline-flex 纵向堆叠（标签在上），
+ *      dsu-field 是 nowrap 横排；dm-set-input min-width 88 + padding 5px 8px，dsu-input 是
+ *      margin-left 6 + padding 2px 6px。NumberField 的输入期钳制虽与本卡 numInput 等价，
+ *      但整体搬过去就是视觉改版，不在收敛范围。
+ *   2. dm-set-row：flex + align-center + margin 0，dsu-field-row 多一条 margin-bottom 8px。
+ *   3. dm-set-card：dsu-surface-card 带 max-width 560 + box-shadow + bg-base（本卡是
+ *      bg-layer-3 + border-l2），两档都会改这张卡的观感。
+ *   4. dm-set-hint / dm-set-foot / dm-set-saved / dm-set-error：本卡领域件，T1 无同构原语
+ *      （saved/error 是纯文字反馈行，不是 Badge/Status 点）。
+ * 另：dm-set-head / -headText / -name / -description / -chevron / -chevronOpen 六条规则在
+ * 本卡**零渲染**，但被 test/e2e/smoke.test.ts 的 #219 视觉锚点断言按 CSS 文本钉住，
+ * 删它必须改那条断言——属改判据而非收敛，故原样保留（决策权留给维护者）。
+ *
+ * 【边界】本文件只管这张 React 卡。浮窗（src/client/float/**、index.ts 的 panelHtml
+ * 命令式 DOM 链路、1300+ 条 dm-float-* 规则）不是 React，接不了原语层，是独立议题：
+ * 本轮一字不动。
+ */
+export declare function SettingsCard(props: SettingsCardProps): React.ReactElement | null;