@dimina-kit/devtools 0.4.0-dev.20260612152115 → 0.4.0-dev.20260615070430

package/README.md

@@ -42,6 +42,12 @@ launch({
   rendererDir,
   apiNamespaces: ['my'],
   brandingProvider: () => ({ appName: '我的开发工具' }),
+  headerAvatarProvider: () => {
+    const user = getCurrentUser()
+    return user
+      ? { displayName: user.name, displayInitial: user.name, avatarUrl: user.avatarUrl }
+      : null
+  },
   icon: '/path/to/icon.png',
   menuBuilder: (mainWindow, menuCtx) => {
     // menuCtx 是 MenuContext（只读 menu 相关状态）
@@ -181,6 +187,10 @@ src/
 | `preloadPath`      | `string`             | 内置                | 统一的 host 级 preload 入口；native-host simulator（WCV）自动跑其 `.cjs` sibling（`cjsSiblingPreloadPath`） |
 | `apiNamespaces`    | `string[]`           | `[]`                | 自定义 API 命名空间（如 `['qd']`） |
 | `brandingProvider` | `() => { appName }`  | —                   | 品牌信息 provider                  |
+| `headerAvatarProvider` | `() => HeaderAvatarInfo \| null \| Promise<HeaderAvatarInfo \| null>` | — | 内置 header 头像 slot 的宿主数据源；返回 `null` / `undefined` 时隐藏 |
+| `headerAvatarActionHandler` | `() => void \| Promise<void>` | — | 内置 header 头像 slot 的点击处理；未提供时点击无业务副作用 |
+| `headerActionsProvider` | `() => HeaderActionInfo[] \| null \| Promise<HeaderActionInfo[] \| null>` | — | 内置 header 三栏里的少量宿主命令按钮 |
+| `headerActionHandler` | `(id: string) => void \| Promise<void>` | — | 处理 `headerActionsProvider` 返回按钮的点击 |
 | `headerHeight`     | `number`             | —                   | **已废弃，运行时忽略**：头部栏恒为 40px（`HEADER_H`）；需要自定义工具栏请用 host toolbar WCV |
 
 ### WorkbenchAppConfig（扩展 WorkbenchConfig）
@@ -208,6 +218,78 @@ src/
 | `instance.registerSimulatorApi(name, handler)` | 注册 simulator 自定义 API，小程序里 `wx.<name>()` 调用（详见下方"Simulator 自定义 API"）。返回 `Disposable` |
 | `instance.ipc` | `IpcRegistry` 实例，`instance.ipc.handle(channel, fn)` 注册自定义 IPC；已绑定 `senderPolicy` 网关 |
 | `instance.registerTrustedWindow(win)` | 把 host 自有弹窗 `BrowserWindow` 加入受信 sender 集，否则其发起的 `instance.ipc` 调用会被网关拒绝。窗口关闭即移除 |
+| `instance.refreshHeaderAvatar()` | 通知 main renderer 重新调用 `headerAvatarProvider`，用于宿主登录态 / 头像变更后刷新内置 header 头像 |
+| `instance.refreshHeaderActions()` | 通知 main renderer 重新调用 `headerActionsProvider`，用于宿主 action 文案 / disabled 状态变化后刷新 |
+
+### Header Avatar
+
+`headerAvatarProvider` 是内置 project header 头像 slot 的唯一数据源。devtools 会通过 `app:getHeaderAvatar` 拉取一个可序列化 DTO 并在固定 header toolbar 内渲染；宿主不需要、也不应该依赖 renderer 内部组件。
+
+该 slot 只承载当前账号 / 身份入口，不是通用业务按钮扩展点。少量必须贴合内置 header 三栏布局的命令按钮使用下方的 `headerActionsProvider`；完整自定义工具栏、复杂状态展示、表单/筛选器、可变高度内容仍应使用 host toolbar WCV（`instance.context.views.hostToolbar.loadURL/loadFile` + `send/onMessage`），由宿主拥有内容、样式和高度。
+
+```typescript
+launch({
+  headerAvatarProvider: () => {
+    const user = qdmpSession.currentUser()
+    return user
+      ? {
+          displayName: user.nickname,
+          displayInitial: user.nickname,
+          avatarUrl: user.avatarUrl,
+          tooltip: user.nickname,
+        }
+      : null
+  },
+  onSetup(instance) {
+    qdmpSession.onUserChanged(() => instance.refreshHeaderAvatar())
+  },
+})
+```
+
+`HeaderAvatarInfo` 字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `displayName` | 用户名；用于 tooltip / aria 文本和 fallback 首字 |
+| `displayInitial` | 可选 fallback 文本；头像图片缺失或加载失败时取首字显示 |
+| `avatarUrl` | 头像图片 URL 或 data URL |
+| `tooltip` | 可选 tooltip 覆盖；默认用 `displayName` |
+
+### Header Actions
+
+`headerActionsProvider` 用于把少量宿主命令渲染到内置 project header 的三栏中。它不是 host toolbar WCV 的替代品：只适合 1-4 个短文本命令，且按钮高度固定、宽度受 header 约束。
+
+placement 对应内置 header 的三个区域：
+
+| placement | 渲染位置 |
+| --- | --- |
+| `left` | 左区最右侧，位于头像 / 面板显隐 controls 之后 |
+| `center` | 中区最右侧，位于编译模式 / 重新编译 / 编译状态之后 |
+| `right` | 右区最左侧，位于布局 controls / 设置按钮之前 |
+
+```typescript
+launch({
+  headerActionsProvider: () => [
+    { id: 'open', label: '打开', placement: 'left' },
+    { id: 'bindApp', label: '绑定应用', placement: 'left' },
+    { id: 'preview', label: '真机预览', placement: 'center' },
+    { id: 'upload', label: '上传', placement: 'right' },
+  ],
+  headerActionHandler: async (id) => {
+    await commands.run(id)
+  },
+})
+```
+
+`HeaderActionInfo` 字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 稳定 action id；点击时传给 `headerActionHandler` |
+| `label` | 短按钮文案 |
+| `tooltip` | 可选 tooltip 覆盖；默认用 `label` |
+| `placement` | `left` / `center` / `right`；默认 `right` |
+| `disabled` | 可选禁用态 |
 
 ### 内置面板 ID
 

package/dist/main/api.d.ts

@@ -16,5 +16,5 @@ export { IpcRegistry } from './utils/ipc-registry.js';
 export type { SenderPolicy } from './utils/ipc-registry.js';
 export { UpdateManager, createGitHubReleaseChecker } from './services/update/index.js';
 export type { UpdateManagerOptions, GitHubReleaseCheckerOptions, PickAssetContext, VersionScheme, } from './services/update/index.js';
-export type { WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
+export type { WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, HeaderAvatarInfo, HeaderAvatarProvider, HeaderActionInfo, HeaderActionPlacement, HeaderActionsProvider, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
 //# sourceMappingURL=api.d.ts.map

package/dist/main/app/app.d.ts

@@ -15,6 +15,10 @@ export interface WorkbenchAppInstance {
     registerTrustedWindow: (win: BrowserWindow) => Disposable;
     /** Registers a simulator custom API into this context's registry. */
     registerSimulatorApi: (name: string, handler: SimulatorApiHandler) => Disposable;
+    /** Ask the main renderer to re-read the header avatar provider. */
+    refreshHeaderAvatar: () => void;
+    /** Ask the main renderer to re-read the header actions provider. */
+    refreshHeaderActions: () => void;
     automationServer?: AutomationServer;
     updateManager?: UpdateManager;
     dispose: () => Promise<void>;

package/dist/main/app/app.js

@@ -149,6 +149,10 @@ function createContext(config, mainWindow, rendererDir) {
         appName: config.appName,
         apiNamespaces: config.apiNamespaces,
         brandingProvider: config.brandingProvider,
+        headerAvatarProvider: config.headerAvatarProvider,
+        headerAvatarActionHandler: config.headerAvatarActionHandler,
+        headerActionsProvider: config.headerActionsProvider,
+        headerActionHandler: config.headerActionHandler,
         // The host-supplied ProjectsProvider / template types in `shared/types`
         // are structurally compatible with the main-process equivalents —
         // these casts are safe; we re-narrow at the workspace-service /
@@ -352,6 +356,8 @@ export async function createDevtoolsRuntime(config = {}) {
         // teardown, so a single dispose leaves no dead entry behind.
         registerTrustedWindow: (win) => context.registry.add(registerTrustedWindow(context, win)),
         registerSimulatorApi: (name, handler) => context.registry.add(toDisposable(context.simulatorApis.register(name, handler))),
+        refreshHeaderAvatar: () => context.notify.headerAvatarChanged(),
+        refreshHeaderActions: () => context.notify.headerActionsChanged(),
         dispose: () => disposeContext(context),
     };
     if (config.onSetup) {

package/dist/main/index.bundle.js

@@ -467,7 +467,13 @@ var WindowChannel = {
   NavigateBack: "window:navigateBack"
 };
 var AppChannel = {
-  GetBranding: "app:getBranding"
+  GetBranding: "app:getBranding",
+  GetHeaderAvatar: "app:getHeaderAvatar",
+  InvokeHeaderAvatar: "app:invokeHeaderAvatar",
+  HeaderAvatarChanged: "app:headerAvatarChanged",
+  GetHeaderActions: "app:getHeaderActions",
+  InvokeHeaderAction: "app:invokeHeaderAction",
+  HeaderActionsChanged: "app:headerActionsChanged"
 };
 var AutomationChannel = {
   GetPort: "automation:port"
@@ -995,6 +1001,12 @@ function createRendererNotifier(ctx) {
     hostToolbarHeightChanged(height) {
       sendToMain(ViewChannel.HostToolbarHeightChanged, height);
     },
+    headerAvatarChanged() {
+      sendToMain(AppChannel.HeaderAvatarChanged);
+    },
+    headerActionsChanged() {
+      sendToMain(AppChannel.HeaderActionsChanged);
+    },
     editorOpenFile(payload) {
       sendToMain(EditorChannel.OpenFile, payload);
     },
@@ -3107,7 +3119,11 @@ function createWorkbenchContext(opts) {
     rendererDir: opts.rendererDir,
     apiNamespaces: opts.apiNamespaces ?? [],
     appName: opts.appName ?? "Dimina DevTools",
-    brandingProvider: opts.brandingProvider
+    brandingProvider: opts.brandingProvider,
+    headerAvatarProvider: opts.headerAvatarProvider,
+    headerAvatarActionHandler: opts.headerAvatarActionHandler,
+    headerActionsProvider: opts.headerActionsProvider,
+    headerActionHandler: opts.headerActionHandler
   };
   ctx.registry = new DisposableRegistry3();
   ctx.connections = createConnectionRegistry();
@@ -3207,10 +3223,70 @@ function installAppMenu(ctx) {
 }
 
 // src/main/ipc/app.ts
+function readString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function normalizeHeaderAvatar(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const avatar = {};
+  const displayName = readString(raw.displayName);
+  const displayInitial = readString(raw.displayInitial);
+  const avatarUrl = readString(raw.avatarUrl);
+  const tooltip = readString(raw.tooltip);
+  if (displayName) avatar.displayName = displayName;
+  if (displayInitial) avatar.displayInitial = displayInitial;
+  if (avatarUrl) avatar.avatarUrl = avatarUrl;
+  if (tooltip) avatar.tooltip = tooltip;
+  return avatar.displayName || avatar.displayInitial || avatar.avatarUrl ? avatar : null;
+}
+function readPlacement(value) {
+  return value === "left" || value === "center" || value === "right" ? value : void 0;
+}
+function normalizeHeaderAction(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const id = readString(raw.id);
+  const label = readString(raw.label);
+  if (!id || !label) return null;
+  const action = { id, label };
+  const tooltip = readString(raw.tooltip);
+  const placement = readPlacement(raw.placement);
+  if (tooltip) action.tooltip = tooltip;
+  if (placement) action.placement = placement;
+  if (typeof raw.disabled === "boolean") action.disabled = raw.disabled;
+  return action;
+}
+function normalizeHeaderActions(value) {
+  if (!Array.isArray(value)) return [];
+  const actions = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    const action = normalizeHeaderAction(item);
+    if (!action || seen.has(action.id)) continue;
+    seen.add(action.id);
+    actions.push(action);
+  }
+  return actions.slice(0, 8);
+}
 function registerAppIpc(ctx) {
   return new IpcRegistry(ctx.senderPolicy).handle(AppChannel.GetBranding, async () => {
     if (ctx.brandingProvider) return ctx.brandingProvider();
     return { appName: ctx.appName };
+  }).handle(AppChannel.GetHeaderAvatar, async () => {
+    if (!ctx.headerAvatarProvider) return null;
+    return normalizeHeaderAvatar(await ctx.headerAvatarProvider());
+  }).handle(AppChannel.InvokeHeaderAvatar, async () => {
+    await ctx.headerAvatarActionHandler?.();
+  }).handle(AppChannel.GetHeaderActions, async () => {
+    if (!ctx.headerActionsProvider) return [];
+    return normalizeHeaderActions(await ctx.headerActionsProvider());
+  }).handle(AppChannel.InvokeHeaderAction, async (_event, id) => {
+    const actionId = readString(id);
+    if (!actionId) return;
+    await ctx.headerActionHandler?.(actionId);
   });
 }
 
@@ -8819,6 +8895,10 @@ function createContext(config, mainWindow, rendererDir2) {
     appName: config.appName,
     apiNamespaces: config.apiNamespaces,
     brandingProvider: config.brandingProvider,
+    headerAvatarProvider: config.headerAvatarProvider,
+    headerAvatarActionHandler: config.headerAvatarActionHandler,
+    headerActionsProvider: config.headerActionsProvider,
+    headerActionHandler: config.headerActionHandler,
     // The host-supplied ProjectsProvider / template types in `shared/types`
     // are structurally compatible with the main-process equivalents —
     // these casts are safe; we re-narrow at the workspace-service /
@@ -8955,6 +9035,8 @@ async function createDevtoolsRuntime(config = {}) {
     // teardown, so a single dispose leaves no dead entry behind.
     registerTrustedWindow: (win) => context.registry.add(registerTrustedWindow(context, win)),
     registerSimulatorApi: (name, handler) => context.registry.add(toDisposable8(context.simulatorApis.register(name, handler))),
+    refreshHeaderAvatar: () => context.notify.headerAvatarChanged(),
+    refreshHeaderActions: () => context.notify.headerActionsChanged(),
     dispose: () => disposeContext(context)
   };
   if (config.onSetup) {

package/dist/main/ipc/app.d.ts

@@ -1,4 +1,6 @@
 import type { WorkbenchContext } from '../services/workbench-context.js';
 import type { Disposable } from '@dimina-kit/electron-deck/main';
-export declare function registerAppIpc(ctx: Pick<WorkbenchContext, 'brandingProvider' | 'appName' | 'senderPolicy'>): Disposable;
+type AppIpcContext = Pick<WorkbenchContext, 'brandingProvider' | 'appName' | 'headerAvatarProvider' | 'headerAvatarActionHandler' | 'headerActionsProvider' | 'headerActionHandler' | 'senderPolicy'>;
+export declare function registerAppIpc(ctx: AppIpcContext): Disposable;
+export {};
 //# sourceMappingURL=app.d.ts.map

package/dist/main/ipc/app.js

@@ -1,11 +1,91 @@
 import { AppChannel } from '../../shared/ipc-channels.js';
 import { IpcRegistry } from '../utils/ipc-registry.js';
+function readString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizeHeaderAvatar(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const avatar = {};
+    const displayName = readString(raw.displayName);
+    const displayInitial = readString(raw.displayInitial);
+    const avatarUrl = readString(raw.avatarUrl);
+    const tooltip = readString(raw.tooltip);
+    if (displayName)
+        avatar.displayName = displayName;
+    if (displayInitial)
+        avatar.displayInitial = displayInitial;
+    if (avatarUrl)
+        avatar.avatarUrl = avatarUrl;
+    if (tooltip)
+        avatar.tooltip = tooltip;
+    return avatar.displayName || avatar.displayInitial || avatar.avatarUrl ? avatar : null;
+}
+function readPlacement(value) {
+    return value === 'left' || value === 'center' || value === 'right' ? value : undefined;
+}
+function normalizeHeaderAction(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const id = readString(raw.id);
+    const label = readString(raw.label);
+    if (!id || !label)
+        return null;
+    const action = { id, label };
+    const tooltip = readString(raw.tooltip);
+    const placement = readPlacement(raw.placement);
+    if (tooltip)
+        action.tooltip = tooltip;
+    if (placement)
+        action.placement = placement;
+    if (typeof raw.disabled === 'boolean')
+        action.disabled = raw.disabled;
+    return action;
+}
+function normalizeHeaderActions(value) {
+    if (!Array.isArray(value))
+        return [];
+    const actions = [];
+    const seen = new Set();
+    for (const item of value) {
+        const action = normalizeHeaderAction(item);
+        if (!action || seen.has(action.id))
+            continue;
+        seen.add(action.id);
+        actions.push(action);
+    }
+    return actions.slice(0, 8);
+}
 export function registerAppIpc(ctx) {
     return new IpcRegistry(ctx.senderPolicy)
         .handle(AppChannel.GetBranding, async () => {
         if (ctx.brandingProvider)
             return ctx.brandingProvider();
         return { appName: ctx.appName };
+    })
+        .handle(AppChannel.GetHeaderAvatar, async () => {
+        if (!ctx.headerAvatarProvider)
+            return null;
+        return normalizeHeaderAvatar(await ctx.headerAvatarProvider());
+    })
+        .handle(AppChannel.InvokeHeaderAvatar, async () => {
+        await ctx.headerAvatarActionHandler?.();
+    })
+        .handle(AppChannel.GetHeaderActions, async () => {
+        if (!ctx.headerActionsProvider)
+            return [];
+        return normalizeHeaderActions(await ctx.headerActionsProvider());
+    })
+        .handle(AppChannel.InvokeHeaderAction, async (_event, id) => {
+        const actionId = readString(id);
+        if (!actionId)
+            return;
+        await ctx.headerActionHandler?.(actionId);
     });
 }
 //# sourceMappingURL=app.js.map

package/dist/main/services/notifications/renderer-notifier.d.ts

@@ -65,6 +65,10 @@ export interface RendererNotifier {
      * placeholder div resizes (closes the host-toolbar dynamic-height loop).
      */
     hostToolbarHeightChanged(height: number): void;
+    /** Ask the main renderer to re-fetch the host-provided header avatar DTO. */
+    headerAvatarChanged(): void;
+    /** Ask the main renderer to re-fetch the host-provided header actions. */
+    headerActionsChanged(): void;
     /**
      * Ask the main renderer's Monaco editor to open a project file at a position.
      * Drives the "click a console file link → open in editor" pipeline.

package/dist/main/services/notifications/renderer-notifier.js

@@ -1,4 +1,4 @@
-import { ProjectChannel, WindowChannel, SettingsChannel, PopoverChannel, WorkbenchSettingsChannel, EditorChannel, ViewChannel, } from '../../../shared/ipc-channels.js';
+import { ProjectChannel, WindowChannel, SettingsChannel, PopoverChannel, WorkbenchSettingsChannel, EditorChannel, ViewChannel, AppChannel, } from '../../../shared/ipc-channels.js';
 /** Safely resolve a WebContents, skipping destroyed / missing targets. */
 function liveWebContents(wc) {
     if (!wc)
@@ -39,6 +39,12 @@ export function createRendererNotifier(ctx) {
         hostToolbarHeightChanged(height) {
             sendToMain(ViewChannel.HostToolbarHeightChanged, height);
         },
+        headerAvatarChanged() {
+            sendToMain(AppChannel.HeaderAvatarChanged);
+        },
+        headerActionsChanged() {
+            sendToMain(AppChannel.HeaderActionsChanged);
+        },
         editorOpenFile(payload) {
             sendToMain(EditorChannel.OpenFile, payload);
         },

package/dist/main/services/workbench-context.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserWindow } from 'electron';
-import type { CompilationAdapter, WorkbenchConfig } from '../../shared/types.js';
+import type { CompilationAdapter, HeaderActionsProvider, HeaderAvatarProvider, WorkbenchConfig } from '../../shared/types.js';
 import type { BridgeRouterHandle } from '../ipc/bridge-router.js';
 import type { ConsoleForwarder } from './console-forward/index.js';
 import type { NetworkForwarder } from './network-forward/index.js';
@@ -35,6 +35,14 @@ export interface WorkbenchContext {
     }> | {
         appName: string;
     };
+    /** Host-injected profile provider for the built-in header avatar slot. */
+    headerAvatarProvider?: HeaderAvatarProvider;
+    /** Host-injected click handler for the built-in header avatar slot. */
+    headerAvatarActionHandler?: () => void | Promise<void>;
+    /** Host-injected compact action provider for the built-in project header. */
+    headerActionsProvider?: HeaderActionsProvider;
+    /** Host-injected click handler for the built-in project header actions. */
+    headerActionHandler?: (id: string) => void | Promise<void>;
     /** Unified lifecycle manager for all overlay WebContentsViews */
     views: ViewManager;
     /** Owns BrowserWindow instances (main + settings) and their sender-id checks. */
@@ -175,6 +183,10 @@ export interface CreateContextOptions extends Pick<WorkbenchConfig, 'adapter' |
     preloadPath: string;
     rendererDir: string;
     brandingProvider?: WorkbenchContext['brandingProvider'];
+    headerAvatarProvider?: WorkbenchContext['headerAvatarProvider'];
+    headerAvatarActionHandler?: WorkbenchContext['headerAvatarActionHandler'];
+    headerActionsProvider?: WorkbenchContext['headerActionsProvider'];
+    headerActionHandler?: WorkbenchContext['headerActionHandler'];
     /** Host-supplied project list backend. Defaults to LocalProjectsProvider. */
     projectsProvider?: ProjectsProvider;
     /** Templates injected by the host; same-id overrides a built-in. */

package/dist/main/services/workbench-context.js

@@ -18,6 +18,10 @@ export function createWorkbenchContext(opts) {
         apiNamespaces: opts.apiNamespaces ?? [],
         appName: opts.appName ?? 'Dimina DevTools',
         brandingProvider: opts.brandingProvider,
+        headerAvatarProvider: opts.headerAvatarProvider,
+        headerAvatarActionHandler: opts.headerAvatarActionHandler,
+        headerActionsProvider: opts.headerActionsProvider,
+        headerActionHandler: opts.headerActionHandler,
     };
     ctx.registry = new DisposableRegistry();
     // Empty connection registry as a first-class context field. Connections are