@tinyaxis/voice-brief-cinnamon 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geequlim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# Voice Brief Cinnamon
+
+Voice Brief 的 Cinnamon 桌面扩展子包。源码使用 TypeScript 编写，由 `tsc` 编译为 Cinnamon 可加载的 GJS JavaScript；扩展运行时不依赖 Node.js。
+
+扩展启用后监听 `$XDG_RUNTIME_DIR/voice-brief/cinnamon.sock`，接收一行 NDJSON 格式的 Voice Brief Hook 事件。Hook Server 启动后，扩展通过 `voice-brief runtime configure` 按自身动画常量设置播放启动延迟；收到单向的 `playback.ready` 时在主显示器依次执行头像与完整对话入场动画。合成和排队事件不会产生可见中间态，播放结束、失败或跳过时关闭。
+
+## 开发
+
+- `src/extension.ts`：扩展生命周期入口。
+- `src/dialogue-overlay.ts`：桌面对话展示与事件生命周期。
+- `src/lib/protocol.ts`：Hook 协议输入校验。
+- `src/lib/hook-server.ts`：Gio Unix Socket 服务。
+- `assets/`：Cinnamon 扩展元数据和样式。
+- `dist/voice-brief@tinyaxis/`：生成的可安装扩展目录，不提交到仓库。
+
+构建扩展：
+
+```bash
+yarn workspace @tinyaxis/voice-brief-cinnamon build
+```
+
+构建、安装到当前用户并让 Cinnamon 重载扩展：
+
+```bash
+yarn tiny develop/voice-brief/cinnamon
+```
+
+### 视觉冒烟测试
+
+扩展安装并启用后，可以直接向 Hook Socket 注入测试事件，不会请求 TTS 或播放语音：
+
+```bash
+yarn tiny develop/voice-brief/cinnamon/smoke
+yarn tiny develop/voice-brief/cinnamon/smoke/entrance
+yarn tiny develop/voice-brief/cinnamon/smoke/dialogue
+yarn tiny develop/voice-brief/cinnamon/smoke/multiline
+yarn tiny develop/voice-brief/cinnamon/smoke/no-session
+```
+
+默认读取 `~/.config/voice-brief/personas/甜妹助理.md`。可以通过 `VOICE_BRIEF_SMOKE_PERSONA` 指定其他人设文件，通过 `VOICE_BRIEF_CINNAMON_SOCKET` 指定其他 Socket。
+
+## 测试
+
+```bash
+yarn workspace @tinyaxis/voice-brief-cinnamon test
+```

package/extension/voice-brief@tinyaxis/dialogue-overlay.js

@@ -0,0 +1,683 @@
+"use strict";
+const DialogueGio = imports.gi.Gio;
+const DialogueGLib = imports.gi.GLib;
+const DialogueClutter = imports.gi.Clutter;
+const DialoguePango = imports.gi.Pango;
+const St = imports.gi.St;
+const Main = imports.ui.main;
+const FINAL_WIDTH = 1800;
+const CARD_INSET_X = 18;
+const CARD_INSET_Y = 14;
+const CONTENT_GAP = 16;
+const AVATAR_ENTER_DURATION_MS = 220;
+const AVATAR_ENTER_SETTLE_DURATION_MS = 120;
+const AVATAR_ENTER_HOLD_MS = 420;
+const AVATAR_ENTER_OVERSHOOT_SCALE = 1.24;
+const DIALOGUE_EXPAND_DURATION_MS = 190;
+const PANEL_EMPHASIS_SCALE_Y = 1.06;
+const PANEL_EMPHASIS_EXPAND_DURATION_MS = 90;
+const PANEL_EMPHASIS_SETTLE_DURATION_MS = 110;
+const PLAYBACK_START_DELAY_MS = AVATAR_ENTER_DURATION_MS +
+    AVATAR_ENTER_SETTLE_DURATION_MS +
+    AVATAR_ENTER_HOLD_MS +
+    DIALOGUE_EXPAND_DURATION_MS +
+    PANEL_EMPHASIS_EXPAND_DURATION_MS +
+    PANEL_EMPHASIS_SETTLE_DURATION_MS;
+const CONTENT_FADE_DURATION_MS = 130;
+const EXIT_COLLAPSE_DURATION_MS = 200;
+const EXIT_PANEL_FADE_DURATION_MS = 110;
+const EXIT_AVATAR_HOLD_MS = 360;
+const EXIT_AVATAR_PULSE_DURATION_MS = 120;
+const EXIT_AVATAR_DURATION_MS = 150;
+const EXIT_AVATAR_OVERSHOOT_SCALE = 1.22;
+const DEFAULT_ACCENT_COLOR = '#eb4272';
+const AVATAR_LAYOUT_STYLE = 'width: 96px; height: 96px;';
+const HIDE_HOT_KEY_NAME = 'voice-brief-hide-overlay';
+class DialogueOverlay {
+    $root;
+    $surface;
+    $avatar;
+    $dialoguePanel;
+    $dialogueHideButton;
+    $nameLabel;
+    $contextLabel;
+    $textLabel;
+    $avatarTimeoutId;
+    $briefId;
+    $dismissedBriefIds = new Set();
+    $escapeHotKeyRegistered = false;
+    $layout;
+    $pendingBriefIds = new Set();
+    $phase = 'idle';
+    $position;
+    $screenMargin;
+    constructor(position, screenMargin) {
+        this.$position = position;
+        this.$screenMargin = screenMargin;
+        this.$root = new St.Widget({
+            layout_manager: new DialogueClutter.FixedLayout(),
+            reactive: false,
+        });
+        this.$root.set_pivot_point(0.5, 0.5);
+        this.$surface = new St.Widget({ style_class: 'voice-brief-dialogue-surface' });
+        this.$surface.set_pivot_point(0.5, 0.5);
+        this.$surface.set_offscreen_redirect(DialogueClutter.OffscreenRedirect.ALWAYS);
+        this.$dialoguePanel = new St.BoxLayout({
+            style_class: 'voice-brief-dialogue-panel',
+            vertical: true,
+        });
+        const header = new St.BoxLayout({
+            style_class: 'voice-brief-dialogue-header',
+            x_expand: true,
+        });
+        this.$nameLabel = new St.Label({
+            style_class: 'voice-brief-dialogue-name',
+            y_align: DialogueClutter.ActorAlign.START,
+        });
+        this.$contextLabel = new St.Label({
+            style_class: 'voice-brief-dialogue-runtime voice-brief-dialogue-context-label',
+            x_align: DialogueClutter.ActorAlign.FILL,
+            x_expand: true,
+            y_align: DialogueClutter.ActorAlign.START,
+        });
+        this.$contextLabel.clutter_text.ellipsize = DialoguePango.EllipsizeMode.END;
+        this.$contextLabel.clutter_text.line_wrap = false;
+        this.$textLabel = new St.Label({
+            style_class: 'voice-brief-dialogue-text',
+            x_expand: true,
+        });
+        this.$textLabel.clutter_text.ellipsize = DialoguePango.EllipsizeMode.NONE;
+        this.$textLabel.clutter_text.line_wrap = true;
+        this.$textLabel.clutter_text.line_wrap_mode = DialoguePango.WrapMode.WORD_CHAR;
+        this.$dialogueHideButton = new St.Button({
+            style_class: 'voice-brief-dialogue-hide-button',
+            label: '[Esc] 隐藏',
+            reactive: true,
+            can_focus: true,
+        });
+        this.$dialogueHideButton.connect('clicked', () => this.$dismissCurrentBrief());
+        const dialogueHideControl = new St.Bin({
+            child: this.$dialogueHideButton,
+            style_class: 'voice-brief-dialogue-hide-row',
+            x_align: St.Align.END,
+            x_expand: true,
+            x_fill: false,
+        });
+        header.add_child(this.$nameLabel);
+        header.add_child(this.$contextLabel);
+        this.$dialoguePanel.add_child(header);
+        this.$dialoguePanel.add_child(this.$textLabel);
+        this.$dialoguePanel.add_child(dialogueHideControl);
+        this.$dialoguePanel.set_offscreen_redirect(DialogueClutter.OffscreenRedirect.ALWAYS);
+        this.$avatar = new St.Bin({
+            style_class: 'voice-brief-dialogue-avatar',
+            y_align: DialogueClutter.ActorAlign.CENTER,
+        });
+        this.$avatar.set_pivot_point(0.5, 0.5);
+        this.$root.add_child(this.$surface);
+        this.$root.add_child(this.$dialoguePanel);
+        this.$root.add_child(this.$avatar);
+        this.$root.hide();
+        Main.layoutManager.addChrome(this.$root, {
+            visibleInFullscreen: true,
+            affectsInputRegion: false,
+            affectsStruts: false,
+        });
+        Main.layoutManager.trackChrome(this.$dialogueHideButton, {
+            visibleInFullscreen: true,
+            affectsInputRegion: true,
+            affectsStruts: false,
+        });
+    }
+    handleEvent(event) {
+        const isTerminalEvent = event.event === 'audio.failed' ||
+            event.event === 'playback.completed' ||
+            event.event === 'playback.failed' ||
+            event.event === 'playback.skipped';
+        if (this.$dismissedBriefIds.has(event.briefId)) {
+            if (isTerminalEvent) {
+                this.$dismissedBriefIds.delete(event.briefId);
+                this.$removePendingBrief(event.briefId);
+            }
+            return;
+        }
+        if (event.event === 'playback.queued') {
+            this.$pendingBriefIds.add(event.briefId);
+            return;
+        }
+        if (event.event === 'playback.ready') {
+            if (this.$phase === 'holding') {
+                this.$replaceDialogue(event);
+                return;
+            }
+            this.$showDialogue(event);
+            return;
+        }
+        if (event.event === 'playback.started') {
+            this.$pendingBriefIds.delete(event.briefId);
+            return;
+        }
+        if (isTerminalEvent)
+            this.$handleTerminalEvent(event.briefId);
+    }
+    setPosition(position) {
+        this.$position = position;
+        this.$updateRootPosition();
+    }
+    setScreenMargin(screenMargin) {
+        this.$screenMargin = screenMargin;
+        this.$updateRootPosition();
+    }
+    destroy() {
+        this.$clearTimers();
+        this.$briefId = undefined;
+        this.$dismissedBriefIds.clear();
+        this.$pendingBriefIds.clear();
+        this.$disableEscapeHotKey();
+        this.$stopTransitions();
+        Main.layoutManager.untrackChrome(this.$dialogueHideButton);
+        Main.layoutManager.removeChrome(this.$root);
+        this.$root.destroy();
+    }
+    $showDialogue(event) {
+        if (this.$phase !== 'idle')
+            return;
+        this.$briefId = event.briefId;
+        const hasAvatar = this.$configureLayout(event);
+        if (!this.$layout)
+            return;
+        if (!hasAvatar) {
+            this.$showDialogueDirect(event);
+            return;
+        }
+        this.$phase = 'introducing';
+        this.$stopTransitions();
+        this.$surface.hide();
+        this.$dialoguePanel.hide();
+        const avatarTranslation = this.$getAvatarTranslation(this.$layout.avatar.initial);
+        this.$avatar.translation_x = avatarTranslation.x;
+        this.$avatar.translation_y = avatarTranslation.y;
+        this.$avatar.opacity = 0;
+        this.$avatar.scale_x = 0.65;
+        this.$avatar.scale_y = 0.65;
+        this.$avatar.show();
+        this.$root.opacity = 255;
+        this.$root.scale_x = 1;
+        this.$root.scale_y = 1;
+        this.$root.translation_y = 0;
+        this.$root.show();
+        this.$animateAvatarEntrance(event.briefId);
+    }
+    $animateAvatarEntrance(briefId) {
+        this.$avatar.ease({
+            opacity: 255,
+            scale_x: AVATAR_ENTER_OVERSHOOT_SCALE,
+            scale_y: AVATAR_ENTER_OVERSHOOT_SCALE,
+            duration: AVATAR_ENTER_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+            onStopped: () => {
+                if (briefId !== this.$briefId || this.$phase !== 'introducing')
+                    return;
+                this.$avatar.ease({
+                    scale_x: 1,
+                    scale_y: 1,
+                    duration: AVATAR_ENTER_SETTLE_DURATION_MS,
+                    mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+                    onStopped: () => this.$holdAvatarBeforeDialogue(briefId),
+                });
+            },
+        });
+    }
+    $holdAvatarBeforeDialogue(briefId) {
+        if (briefId !== this.$briefId || this.$phase !== 'introducing')
+            return;
+        this.$avatarTimeoutId = DialogueGLib.timeout_add(DialogueGLib.PRIORITY_DEFAULT, AVATAR_ENTER_HOLD_MS, () => {
+            this.$avatarTimeoutId = undefined;
+            if (briefId !== this.$briefId || this.$phase !== 'introducing')
+                return DialogueGLib.SOURCE_REMOVE;
+            if (this.$layout) {
+                const initialSurface = {
+                    x: this.$layout.avatar.initial.x,
+                    y: this.$layout.avatar.initial.y,
+                    width: this.$layout.avatar.width,
+                    height: this.$layout.avatar.height,
+                };
+                this.$expandDialogue(briefId, initialSurface);
+            }
+            return DialogueGLib.SOURCE_REMOVE;
+        });
+    }
+    $expandDialogue(briefId, initialSurface) {
+        if (!this.$layout)
+            return;
+        this.$enableEscapeHotKey();
+        this.$phase = 'expanding';
+        const initialScaleX = initialSurface.width / this.$layout.finalSurface.width;
+        const initialScaleY = initialSurface.height / this.$layout.finalSurface.height;
+        const initialTranslationX = initialSurface.x + (initialSurface.width - this.$layout.finalSurface.width) / 2;
+        const initialTranslationY = initialSurface.y + (initialSurface.height - this.$layout.finalSurface.height) / 2;
+        this.$setRect(this.$dialoguePanel, this.$layout.finalPanel);
+        this.$dialoguePanel.opacity = 0;
+        this.$dialoguePanel.translation_y = 6;
+        this.$dialoguePanel.show();
+        this.$surface.scale_x = initialScaleX;
+        this.$surface.scale_y = initialScaleY;
+        this.$surface.translation_x = initialTranslationX;
+        this.$surface.translation_y = initialTranslationY;
+        this.$surface.opacity = 255;
+        this.$surface.show();
+        this.$surface.ease({
+            scale_x: 1,
+            scale_y: 1,
+            translation_x: 0,
+            translation_y: 0,
+            duration: DIALOGUE_EXPAND_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+            onStopped: () => {
+                if (briefId !== this.$briefId || this.$phase !== 'expanding')
+                    return;
+                if (!this.$layout)
+                    return;
+                this.$emphasizeDialogue(briefId, () => {
+                    this.$phase = 'dialogue';
+                });
+            },
+        });
+        this.$avatar.ease({
+            translation_x: 0,
+            translation_y: 0,
+            duration: DIALOGUE_EXPAND_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+        });
+        this.$dialoguePanel.ease({
+            delay: 40,
+            opacity: 255,
+            translation_y: 0,
+            duration: CONTENT_FADE_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+        });
+    }
+    $emphasizeDialogue(briefId, onComplete) {
+        if (!this.$layout)
+            return;
+        const visibleRect = this.$layout.finalSurface;
+        const pivotY = (visibleRect.y + visibleRect.height / 2) / this.$layout.root.height;
+        this.$root.set_pivot_point(0.5, pivotY);
+        this.$root.ease({
+            scale_y: PANEL_EMPHASIS_SCALE_Y,
+            duration: PANEL_EMPHASIS_EXPAND_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+            onStopped: () => {
+                if (briefId !== this.$briefId || this.$phase !== 'expanding')
+                    return;
+                this.$root.ease({
+                    scale_y: 1,
+                    duration: PANEL_EMPHASIS_SETTLE_DURATION_MS,
+                    mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+                    onStopped: () => {
+                        if (briefId === this.$briefId && this.$phase === 'expanding')
+                            onComplete();
+                    },
+                });
+            },
+        });
+    }
+    $showDialogueDirect(event) {
+        this.$briefId = event.briefId;
+        this.$clearTimers();
+        this.$stopTransitions();
+        if (!this.$layout)
+            return;
+        this.$enableEscapeHotKey();
+        this.$phase = 'expanding';
+        this.$setRect(this.$surface, this.$layout.finalSurface);
+        this.$surface.scale_x = 1;
+        this.$surface.scale_y = 1;
+        this.$surface.translation_x = 0;
+        this.$surface.translation_y = 0;
+        this.$surface.opacity = 0;
+        this.$surface.show();
+        this.$setRect(this.$dialoguePanel, this.$layout.finalPanel);
+        this.$dialoguePanel.opacity = 0;
+        this.$dialoguePanel.translation_y = 5;
+        this.$dialoguePanel.show();
+        this.$placeActor(this.$avatar, this.$layout.avatar.final);
+        this.$avatar.translation_x = 0;
+        this.$avatar.translation_y = 0;
+        this.$avatar.opacity = 255;
+        this.$avatar.scale_x = 1;
+        this.$avatar.scale_y = 1;
+        this.$root.opacity = 255;
+        this.$root.scale_x = 1;
+        this.$root.scale_y = 1;
+        this.$root.translation_y = 0;
+        this.$root.show();
+        this.$surface.ease({
+            opacity: 255,
+            duration: CONTENT_FADE_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+            onStopped: () => {
+                if (event.briefId !== this.$briefId || this.$phase !== 'expanding')
+                    return;
+                if (!this.$layout)
+                    return;
+                this.$emphasizeDialogue(event.briefId, () => {
+                    this.$phase = 'dialogue';
+                });
+            },
+        });
+        this.$dialoguePanel.ease({
+            opacity: 255,
+            translation_y: 0,
+            duration: CONTENT_FADE_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+        });
+    }
+    $replaceDialogue(event) {
+        this.$briefId = event.briefId;
+        this.$clearTimers();
+        this.$stopTransitions();
+        this.$configureLayout(event);
+        if (!this.$layout)
+            return;
+        this.$enableEscapeHotKey();
+        this.$phase = 'expanding';
+        this.$showDialogueSteady();
+        this.$emphasizeDialogue(event.briefId, () => {
+            this.$phase = 'dialogue';
+        });
+    }
+    $showDialogueSteady() {
+        if (!this.$layout)
+            return;
+        this.$setRect(this.$surface, this.$layout.finalSurface);
+        this.$surface.scale_x = 1;
+        this.$surface.scale_y = 1;
+        this.$surface.translation_x = 0;
+        this.$surface.translation_y = 0;
+        this.$surface.opacity = 255;
+        this.$surface.show();
+        this.$setRect(this.$dialoguePanel, this.$layout.finalPanel);
+        this.$dialoguePanel.opacity = 255;
+        this.$dialoguePanel.translation_y = 0;
+        this.$dialoguePanel.show();
+        this.$placeActor(this.$avatar, this.$layout.avatar.final);
+        this.$avatar.translation_x = 0;
+        this.$avatar.translation_y = 0;
+        this.$avatar.opacity = 255;
+        this.$avatar.scale_x = 1;
+        this.$avatar.scale_y = 1;
+        this.$root.opacity = 255;
+        this.$root.scale_x = 1;
+        this.$root.scale_y = 1;
+        this.$root.translation_y = 0;
+        this.$root.show();
+    }
+    $handleTerminalEvent(briefId) {
+        this.$removePendingBrief(briefId);
+        if (briefId !== this.$briefId)
+            return;
+        if (this.$pendingBriefIds.size === 0) {
+            this.$hide(briefId);
+            return;
+        }
+        this.$holdDialogue(briefId);
+    }
+    $removePendingBrief(briefId) {
+        this.$pendingBriefIds.delete(briefId);
+        if (this.$phase === 'holding' && this.$pendingBriefIds.size === 0 && this.$briefId) {
+            this.$hide(this.$briefId);
+        }
+    }
+    $holdDialogue(briefId) {
+        if (briefId !== this.$briefId)
+            return;
+        this.$clearTimers();
+        this.$stopTransitions();
+        this.$showDialogueSteady();
+        this.$phase = 'holding';
+    }
+    $hide(briefId) {
+        if (briefId !== this.$briefId)
+            return;
+        this.$clearTimers();
+        this.$phase = 'exiting';
+        this.$stopTransitions();
+        this.$disableEscapeHotKey();
+        this.$dialogueHideButton.hide();
+        if (!this.$root.visible) {
+            this.$finishHide(briefId);
+            return;
+        }
+        this.$dialoguePanel.ease({
+            opacity: 0,
+            duration: 70,
+            mode: DialogueClutter.AnimationMode.EASE_IN_QUAD,
+        });
+        if (!this.$layout || !this.$avatar.visible) {
+            this.$fadeRoot(briefId);
+            return;
+        }
+        if (!this.$surface.visible) {
+            this.$fadeAvatar(briefId);
+            return;
+        }
+        const initialAvatarTranslation = this.$getAvatarTranslation(this.$layout.avatar.initial);
+        this.$surface.ease({
+            scale_x: 0.96,
+            scale_y: 0.96,
+            opacity: 0,
+            duration: EXIT_PANEL_FADE_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_IN_QUAD,
+        });
+        this.$avatar.ease({
+            translation_x: initialAvatarTranslation.x,
+            translation_y: initialAvatarTranslation.y,
+            duration: EXIT_COLLAPSE_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+            onStopped: () => this.$fadeAvatar(briefId),
+        });
+    }
+    $dismissCurrentBrief() {
+        if (!this.$briefId)
+            return;
+        this.$dismissedBriefIds.add(this.$briefId);
+        this.$hide(this.$briefId);
+    }
+    $enableEscapeHotKey() {
+        if (this.$escapeHotKeyRegistered)
+            return;
+        this.$escapeHotKeyRegistered = Main.keybindingManager.addHotKey(HIDE_HOT_KEY_NAME, 'Escape', () => this.$dismissCurrentBrief());
+    }
+    $disableEscapeHotKey() {
+        if (!this.$escapeHotKeyRegistered)
+            return;
+        Main.keybindingManager.removeHotKey(HIDE_HOT_KEY_NAME);
+        this.$escapeHotKeyRegistered = false;
+    }
+    $fadeAvatar(briefId) {
+        if (briefId !== this.$briefId || this.$phase !== 'exiting')
+            return;
+        this.$avatarTimeoutId = DialogueGLib.timeout_add(DialogueGLib.PRIORITY_DEFAULT, EXIT_AVATAR_HOLD_MS, () => {
+            this.$avatarTimeoutId = undefined;
+            if (briefId === this.$briefId && this.$phase === 'exiting')
+                this.$pulseAvatarBeforeExit(briefId);
+            return DialogueGLib.SOURCE_REMOVE;
+        });
+    }
+    $pulseAvatarBeforeExit(briefId) {
+        this.$avatar.ease({
+            scale_x: EXIT_AVATAR_OVERSHOOT_SCALE,
+            scale_y: EXIT_AVATAR_OVERSHOOT_SCALE,
+            duration: EXIT_AVATAR_PULSE_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_OUT_CUBIC,
+            onStopped: () => {
+                if (briefId !== this.$briefId || this.$phase !== 'exiting')
+                    return;
+                this.$avatar.ease({
+                    opacity: 0,
+                    scale_x: 0.65,
+                    scale_y: 0.65,
+                    duration: EXIT_AVATAR_DURATION_MS,
+                    mode: DialogueClutter.AnimationMode.EASE_IN_QUAD,
+                    onStopped: () => this.$finishHide(briefId),
+                });
+            },
+        });
+    }
+    $fadeRoot(briefId) {
+        this.$root.ease({
+            opacity: 0,
+            translation_y: -8,
+            duration: EXIT_COLLAPSE_DURATION_MS,
+            mode: DialogueClutter.AnimationMode.EASE_IN_QUAD,
+            onStopped: () => this.$finishHide(briefId),
+        });
+    }
+    $finishHide(briefId) {
+        if (briefId !== this.$briefId || this.$phase !== 'exiting')
+            return;
+        this.$root.hide();
+        this.$surface.hide();
+        this.$dialoguePanel.hide();
+        this.$root.scale_x = 1;
+        this.$root.scale_y = 1;
+        this.$briefId = undefined;
+        this.$layout = undefined;
+        this.$phase = 'idle';
+    }
+    $configureLayout(event) {
+        const accentColor = this.$resolveAccentColor(event.persona?.color);
+        const personaName = event.persona?.name ?? 'Voice Brief';
+        const metadata = [event.source?.agent, event.source?.model]
+            .filter((value) => value !== undefined)
+            .join(' · ');
+        const contextText = event.source?.session || metadata;
+        this.$surface.set_style(`border-color: ${accentColor};`);
+        this.$nameLabel.text = personaName;
+        this.$nameLabel.set_style(`color: ${accentColor};`);
+        this.$contextLabel.text = contextText;
+        if (contextText)
+            this.$contextLabel.show();
+        else
+            this.$contextLabel.hide();
+        this.$textLabel.text = event.brief.text;
+        this.$dialogueHideButton.show();
+        const hasAvatar = this.$setAvatar(event.persona?.avatar);
+        const [, measuredAvatarWidth] = this.$avatar.get_preferred_width(-1);
+        const [, measuredAvatarHeight] = this.$avatar.get_preferred_height(measuredAvatarWidth);
+        const avatarWidth = hasAvatar ? measuredAvatarWidth : 0;
+        const avatarHeight = hasAvatar ? measuredAvatarHeight : 0;
+        const monitor = Main.layoutManager.primaryMonitor;
+        const finalWidth = Math.min(FINAL_WIDTH, monitor.width - 64);
+        const avatarGap = hasAvatar ? CONTENT_GAP : 0;
+        const finalPanelWidth = finalWidth - CARD_INSET_X * 2 - avatarWidth - avatarGap;
+        this.$dialoguePanel.set_size(finalPanelWidth, -1);
+        this.$dialoguePanel.show();
+        const [, finalPanelHeight] = this.$dialoguePanel.get_preferred_height(finalPanelWidth);
+        const finalHeight = Math.max(avatarHeight + CARD_INSET_Y * 2, finalPanelHeight + CARD_INSET_Y * 2);
+        const rootHeight = finalHeight;
+        const finalY = this.$getContentY(rootHeight, finalHeight);
+        const finalAvatarX = CARD_INSET_X;
+        this.$layout = {
+            root: {
+                x: monitor.x + Math.round((monitor.width - finalWidth) / 2),
+                y: this.$getRootY(rootHeight),
+                width: finalWidth,
+                height: rootHeight,
+            },
+            finalSurface: { x: 0, y: finalY, width: finalWidth, height: finalHeight },
+            avatar: {
+                width: avatarWidth,
+                height: avatarHeight,
+                initial: {
+                    x: Math.round((finalWidth - avatarWidth) / 2),
+                    y: finalY + Math.round((finalHeight - avatarHeight) / 2),
+                },
+                final: {
+                    x: finalAvatarX,
+                    y: finalY + Math.round((finalHeight - avatarHeight) / 2),
+                },
+            },
+            finalPanel: {
+                x: finalAvatarX + avatarWidth + avatarGap,
+                y: finalY + CARD_INSET_Y,
+                width: finalPanelWidth,
+                height: finalPanelHeight,
+            },
+        };
+        this.$setRect(this.$root, this.$layout.root);
+        this.$setRect(this.$surface, this.$layout.finalSurface);
+        this.$placeActor(this.$avatar, this.$layout.avatar.final);
+        this.$dialoguePanel.hide();
+        return hasAvatar;
+    }
+    $getContentY(rootHeight, contentHeight) {
+        if (this.$position === 'bottom')
+            return rootHeight - contentHeight;
+        return 0;
+    }
+    $getRootY(rootHeight) {
+        const monitor = Main.layoutManager.primaryMonitor;
+        if (this.$position === 'bottom')
+            return monitor.y + monitor.height - this.$screenMargin - rootHeight;
+        return monitor.y + this.$screenMargin;
+    }
+    $updateRootPosition() {
+        if (!this.$layout)
+            return;
+        this.$layout.root.y = this.$getRootY(this.$layout.root.height);
+        this.$root.set_position(this.$layout.root.x, this.$layout.root.y);
+    }
+    $setAvatar(avatarPath) {
+        if (!avatarPath || !DialogueGLib.file_test(avatarPath, DialogueGLib.FileTest.IS_REGULAR)) {
+            this.$avatar.hide();
+            this.$avatar.set_style('');
+            return false;
+        }
+        const avatarUri = DialogueGio.File.new_for_path(avatarPath).get_uri();
+        this.$avatar.set_style(`${AVATAR_LAYOUT_STYLE} background-image: url("${avatarUri}"); background-size: cover;`);
+        this.$avatar.show();
+        return true;
+    }
+    $setRect(actor, rect) {
+        actor.set_position(rect.x, rect.y);
+        actor.set_size(rect.width, rect.height);
+    }
+    $placeActor(actor, point) {
+        actor.set_position(point.x, point.y);
+    }
+    $getAvatarTranslation(point) {
+        if (!this.$layout)
+            return { x: 0, y: 0 };
+        return {
+            x: point.x - this.$layout.avatar.final.x,
+            y: point.y - this.$layout.avatar.final.y,
+        };
+    }
+    $stopTransitions() {
+        this.$root.remove_all_transitions();
+        this.$surface.remove_all_transitions();
+        this.$avatar.remove_all_transitions();
+        this.$dialoguePanel.remove_all_transitions();
+    }
+    $clearTimers() {
+        if (this.$avatarTimeoutId !== undefined) {
+            DialogueGLib.Source.remove(this.$avatarTimeoutId);
+            this.$avatarTimeoutId = undefined;
+        }
+    }
+    $resolveAccentColor(color) {
+        if (color && /^#[0-9a-f]{6}$/i.test(color))
+            return color;
+        return DEFAULT_ACCENT_COLOR;
+    }
+}
+// oxlint-disable-next-line no-unused-vars -- Cinnamon exposes top-level functions through its legacy GJS module loader.
+function createDialogueOverlay(position, screenMargin) {
+    return new DialogueOverlay(position, screenMargin);
+}
+// oxlint-disable-next-line no-unused-vars -- Cinnamon exposes top-level functions through its legacy GJS module loader.
+function getDialoguePlaybackStartDelayMs() {
+    return PLAYBACK_START_DELAY_MS;
+}

package/extension/voice-brief@tinyaxis/extension.js

@@ -0,0 +1,93 @@
+"use strict";
+const { createHookServer: createExtensionHookServer, getDefaultSocketPath: getExtensionSocketPath, } = require('./lib/hook-server');
+const { parseHookEvent: parseExtensionHookEvent } = require('./lib/protocol');
+const { createDialogueOverlay: createExtensionDialogueOverlay, getDialoguePlaybackStartDelayMs: getExtensionPlaybackStartDelayMs, } = require('./dialogue-overlay');
+const ExtensionGio = imports.gi.Gio;
+const ExtensionGLib = imports.gi.GLib;
+const CinnamonSettings = imports.ui.settings;
+class VoiceBriefExtension {
+    $uuid;
+    $screenMargin = 112;
+    $screenPosition = 'top';
+    $settings;
+    $hookServer;
+    $dialogueOverlay;
+    constructor(metadata) {
+        this.$uuid = metadata.uuid;
+    }
+    enable() {
+        const settings = new CinnamonSettings.ExtensionSettings(this, this.$uuid);
+        settings.bind('screen-position', '$screenPosition', () => {
+            this.$dialogueOverlay?.setPosition(this.$screenPosition);
+        });
+        settings.bind('screen-margin', '$screenMargin', () => {
+            this.$dialogueOverlay?.setScreenMargin(this.$screenMargin);
+        });
+        const dialogueOverlay = createExtensionDialogueOverlay(this.$screenPosition, this.$screenMargin);
+        const hookServer = createExtensionHookServer(getExtensionSocketPath(), parseExtensionHookEvent, event => dialogueOverlay.handleEvent(event), error => global.logError(error, '[voice-brief] rejected hook event'));
+        try {
+            hookServer.start();
+            this.$configurePlaybackStartDelay();
+            this.$settings = settings;
+            this.$dialogueOverlay = dialogueOverlay;
+            this.$hookServer = hookServer;
+        }
+        catch (error) {
+            settings.finalize();
+            dialogueOverlay.destroy();
+            throw error;
+        }
+    }
+    $configurePlaybackStartDelay() {
+        const executable = ExtensionGLib.find_program_in_path('voice-brief');
+        if (!executable) {
+            global.log('[voice-brief] executable not found; playback start delay was not configured');
+            return;
+        }
+        const delayMs = getExtensionPlaybackStartDelayMs();
+        try {
+            const process = ExtensionGio.Subprocess.new([
+                executable,
+                'runtime',
+                'configure',
+                '--playback-start-delay-ms',
+                String(delayMs),
+            ], ExtensionGio.SubprocessFlags.STDOUT_SILENCE | ExtensionGio.SubprocessFlags.STDERR_SILENCE);
+            process.wait_check_async(null, (_source, result) => {
+                try {
+                    process.wait_check_finish(result);
+                    global.log(`[voice-brief] playback start delay configured to ${delayMs}ms`);
+                }
+                catch (error) {
+                    global.logError(error, '[voice-brief] failed to configure playback start delay');
+                }
+            });
+        }
+        catch (error) {
+            global.logError(error, '[voice-brief] failed to start playback delay configuration');
+        }
+    }
+    disable() {
+        this.$hookServer?.stop();
+        this.$settings?.finalize();
+        this.$dialogueOverlay?.destroy();
+        this.$settings = undefined;
+        this.$hookServer = undefined;
+        this.$dialogueOverlay = undefined;
+    }
+}
+let extension;
+// oxlint-disable-next-line no-unused-vars -- Cinnamon invokes this lifecycle function through its extension loader.
+function init(metadata) {
+    extension = new VoiceBriefExtension(metadata);
+}
+// oxlint-disable-next-line no-unused-vars -- Cinnamon invokes this lifecycle function through its extension loader.
+function enable() {
+    if (!extension)
+        throw new Error('Voice Brief extension was not initialized');
+    extension.enable();
+}
+// oxlint-disable-next-line no-unused-vars -- Cinnamon invokes this lifecycle function through its extension loader.
+function disable() {
+    extension?.disable();
+}

package/extension/voice-brief@tinyaxis/lib/hook-server.js

@@ -0,0 +1,137 @@
+"use strict";
+const Gio = imports.gi.Gio;
+const GLib = imports.gi.GLib;
+const MAX_MESSAGE_BYTES = 64 * 1024;
+const READ_CHUNK_BYTES = 4096;
+// oxlint-disable-next-line no-unused-vars -- Cinnamon exposes top-level functions through its legacy GJS module loader.
+function getDefaultSocketPath() {
+    return GLib.build_filenamev([GLib.get_user_runtime_dir(), 'voice-brief', 'cinnamon.sock']);
+}
+class HookServer {
+    $socketPath;
+    $parseEvent;
+    $onEvent;
+    $onError;
+    $service;
+    $cancellable;
+    $incomingId;
+    $connections = new Set();
+    constructor($socketPath, $parseEvent, $onEvent, $onError) {
+        this.$socketPath = $socketPath;
+        this.$parseEvent = $parseEvent;
+        this.$onEvent = $onEvent;
+        this.$onError = $onError;
+    }
+    start() {
+        if (this.$service)
+            throw new Error('Hook server is already running');
+        const directory = GLib.path_get_dirname(this.$socketPath);
+        if (GLib.mkdir_with_parents(directory, 0o700) !== 0) {
+            throw new Error(`Unable to create socket directory: ${directory}`);
+        }
+        if (GLib.chmod(directory, 0o700) !== 0) {
+            throw new Error(`Unable to secure socket directory: ${directory}`);
+        }
+        this.$removeSocketFile();
+        const cancellable = new Gio.Cancellable();
+        const service = new Gio.SocketService();
+        const address = new Gio.UnixSocketAddress({ path: this.$socketPath });
+        try {
+            service.add_address(address, Gio.SocketType.STREAM, Gio.SocketProtocol.DEFAULT, null);
+            const incomingId = service.connect('incoming', (_service, connection) => {
+                this.$accept(connection, cancellable);
+                return true;
+            });
+            service.start();
+            this.$cancellable = cancellable;
+            this.$service = service;
+            this.$incomingId = incomingId;
+        }
+        catch (error) {
+            service.close();
+            this.$removeSocketFile();
+            throw error;
+        }
+    }
+    stop() {
+        if (!this.$service || !this.$cancellable || this.$incomingId === undefined)
+            return;
+        this.$cancellable.cancel();
+        for (const connection of this.$connections)
+            connection.close(null);
+        this.$connections.clear();
+        this.$service.disconnect(this.$incomingId);
+        this.$service.stop();
+        this.$service.close();
+        this.$service = undefined;
+        this.$cancellable = undefined;
+        this.$incomingId = undefined;
+        this.$removeSocketFile();
+    }
+    $accept(connection, cancellable) {
+        this.$connections.add(connection);
+        this.$readChunk(connection, connection.get_input_stream(), [], cancellable);
+    }
+    $readChunk(connection, input, buffer, cancellable) {
+        input.read_bytes_async(READ_CHUNK_BYTES, GLib.PRIORITY_DEFAULT, cancellable, (_stream, result) => {
+            let bytes;
+            try {
+                bytes = input.read_bytes_finish(result).get_data() ?? new Uint8Array();
+            }
+            catch (error) {
+                if (!cancellable.is_cancelled())
+                    this.$onError(error);
+                this.$closeConnection(connection);
+                return;
+            }
+            if (bytes.length === 0) {
+                this.$onError(new Error('Hook connection closed before newline'));
+                this.$closeConnection(connection);
+                return;
+            }
+            const newlineIndex = bytes.indexOf(10);
+            const chunkLength = newlineIndex === -1 ? bytes.length : newlineIndex;
+            if (buffer.length + chunkLength > MAX_MESSAGE_BYTES) {
+                this.$onError(new Error(`Hook message exceeds ${MAX_MESSAGE_BYTES} bytes`));
+                this.$closeConnection(connection);
+                return;
+            }
+            for (let index = 0; index < chunkLength; index++)
+                buffer.push(bytes[index]);
+            if (newlineIndex === -1) {
+                this.$readChunk(connection, input, buffer, cancellable);
+                return;
+            }
+            if (buffer.at(-1) === 13)
+                buffer.pop();
+            try {
+                const text = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(buffer));
+                this.$onEvent(this.$parseEvent(text));
+            }
+            catch (error) {
+                this.$onError(error);
+            }
+            this.$closeConnection(connection);
+        });
+    }
+    $closeConnection(connection) {
+        if (!this.$connections.delete(connection))
+            return;
+        connection.close_async(GLib.PRIORITY_DEFAULT, null, (_stream, result) => {
+            try {
+                connection.close_finish(result);
+            }
+            catch (error) {
+                this.$onError(error);
+            }
+        });
+    }
+    $removeSocketFile() {
+        if (GLib.file_test(this.$socketPath, GLib.FileTest.EXISTS))
+            GLib.unlink(this.$socketPath);
+    }
+}
+// oxlint-disable-next-line no-unused-vars -- Cinnamon exposes top-level functions through its legacy GJS module loader.
+function createHookServer(socketPath, parseEvent, onEvent, onError) {
+    return new HookServer(socketPath, parseEvent, onEvent, onError);
+}

package/extension/voice-brief@tinyaxis/lib/protocol.js

@@ -0,0 +1,97 @@
+"use strict";
+const EVENT_NAMES = new Set([
+    'brief.skipped',
+    'audio.preparing',
+    'audio.ready',
+    'audio.failed',
+    'playback.queued',
+    'playback.ready',
+    'playback.started',
+    'playback.completed',
+    'playback.failed',
+    'playback.skipped',
+]);
+const BRIEF_KINDS = new Set(['final', 'progress', 'test']);
+const PRIORITIES = new Set(['normal', 'high']);
+const AUDIO_SOURCES = new Set(['cache', 'provider']);
+const SKIP_REASONS = new Set(['disabled', 'duplicate', 'empty_text', 'player_disabled', 'throttled']);
+function requireRecord(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${path} must be an object`);
+    }
+    return value;
+}
+function requireString(value, path, allowEmpty = false) {
+    if (typeof value !== 'string' || (!allowEmpty && value.length === 0)) {
+        throw new Error(`${path} must be a string`);
+    }
+    return value;
+}
+function validateOptionalString(value, path) {
+    if (value !== undefined)
+        requireString(value, path);
+}
+function validateSource(value) {
+    if (value === undefined)
+        return;
+    const source = requireRecord(value, 'source');
+    validateOptionalString(source['agent'], 'source.agent');
+    validateOptionalString(source['model'], 'source.model');
+    validateOptionalString(source['session'], 'source.session');
+}
+function validatePersona(value) {
+    if (value === undefined)
+        return;
+    const persona = requireRecord(value, 'persona');
+    requireString(persona['name'], 'persona.name');
+    validateOptionalString(persona['avatar'], 'persona.avatar');
+    validateOptionalString(persona['color'], 'persona.color');
+}
+function validateAudio(value) {
+    if (value === undefined)
+        return;
+    const audio = requireRecord(value, 'audio');
+    requireString(audio['provider'], 'audio.provider');
+    if (!AUDIO_SOURCES.has(audio['source']))
+        throw new Error('audio.source is invalid');
+    if (audio['durationMs'] !== undefined && (typeof audio['durationMs'] !== 'number' || audio['durationMs'] < 0)) {
+        throw new Error('audio.durationMs must be a non-negative number');
+    }
+}
+function validateError(value) {
+    if (value === undefined)
+        return;
+    const eventError = requireRecord(value, 'error');
+    requireString(eventError['stage'], 'error.stage');
+    requireString(eventError['message'], 'error.message');
+}
+// oxlint-disable-next-line no-unused-vars -- Cinnamon exposes top-level functions through its legacy GJS module loader.
+function parseHookEvent(text) {
+    const event = requireRecord(JSON.parse(text), 'event');
+    if (event['protocol'] !== 'voice-brief.hook-event')
+        throw new Error('unsupported hook protocol');
+    if (event['version'] !== 2)
+        throw new Error('unsupported hook protocol version');
+    requireString(event['eventId'], 'eventId');
+    requireString(event['occurredAt'], 'occurredAt');
+    requireString(event['briefId'], 'briefId');
+    if (!EVENT_NAMES.has(event['event']))
+        throw new Error('event name is invalid');
+    if (!Number.isInteger(event['sequence']) || event['sequence'] < 1) {
+        throw new Error('sequence must be a positive integer');
+    }
+    const brief = requireRecord(event['brief'], 'brief');
+    requireString(brief['text'], 'brief.text', true);
+    if (!BRIEF_KINDS.has(brief['kind']))
+        throw new Error('brief.kind is invalid');
+    if (!PRIORITIES.has(brief['priority']))
+        throw new Error('brief.priority is invalid');
+    validateSource(event['source']);
+    validatePersona(event['persona']);
+    validateAudio(event['audio']);
+    validateError(event['error']);
+    if (event['reason'] !== undefined && !SKIP_REASONS.has(event['reason'])) {
+        throw new Error('reason is invalid');
+    }
+    return event;
+}

package/extension/voice-brief@tinyaxis/metadata.json

@@ -0,0 +1,11 @@
+{
+	"uuid": "voice-brief@tinyaxis",
+	"name": "Voice Brief",
+	"description": "Display Voice Brief playback events as desktop dialogue",
+	"author": "TinyAxis",
+	"url": "https://github.com/Geequlim/voice-brief",
+	"version": 1,
+	"cinnamon-version": [
+		"6.6"
+	]
+}

package/extension/voice-brief@tinyaxis/settings-schema.json

@@ -0,0 +1,24 @@
+{
+	"display": {
+		"type": "section",
+		"description": "显示"
+	},
+	"screen-position": {
+		"type": "combobox",
+		"description": "屏幕位置",
+		"default": "top",
+		"options": {
+			"靠顶部": "top",
+			"靠底部": "bottom"
+		}
+	},
+	"screen-margin": {
+		"type": "spinbutton",
+		"description": "屏幕边距",
+		"default": 112,
+		"min": 0,
+		"max": 512,
+		"step": 8,
+		"units": "px"
+	}
+}

package/extension/voice-brief@tinyaxis/stylesheet.css

@@ -0,0 +1,74 @@
+.voice-brief-dialogue-surface {
+	border: 2px solid #eb4272;
+	border-radius: 32px;
+	background-gradient-direction: vertical;
+	background-gradient-start: rgba(29, 25, 36, 0.97);
+	background-gradient-end: rgba(16, 17, 25, 0.97);
+	box-shadow: 0 12px 32px rgba(0, 0, 0, 0.92);
+}
+
+.voice-brief-dialogue-avatar {
+	width: 96px;
+	height: 96px;
+	border: 3px solid rgba(255, 255, 255, 0.96);
+	border-radius: 999px;
+	background-color: #ffffff;
+	background-size: cover;
+	box-shadow: 0 10px 24px rgba(0, 0, 0, 0.78);
+}
+
+.voice-brief-dialogue-panel {
+	spacing: 8px;
+}
+
+.voice-brief-dialogue-header {
+	spacing: 10px;
+}
+
+.voice-brief-dialogue-context-label {
+	padding-right: 18px;
+	text-align: right;
+}
+
+.voice-brief-dialogue-name {
+	font-size: 20px;
+	font-weight: bold;
+	color: #eb4272;
+}
+
+.voice-brief-dialogue-text {
+	padding: 1px 0;
+	font-size: 20px;
+	font-weight: bold;
+	color: #ffffff;
+}
+
+.voice-brief-dialogue-runtime {
+	font-size: 12px;
+	color: rgba(255, 255, 255, 0.46);
+}
+
+.voice-brief-dialogue-hide-row {
+	padding-right: 18px;
+}
+
+.voice-brief-dialogue-hide-button {
+	padding: 1px 8px;
+	border: 0;
+	border-radius: 999px;
+	background-color: transparent;
+	box-shadow: none;
+	font-size: 11px;
+	color: rgba(255, 255, 255, 0.38);
+}
+
+.voice-brief-dialogue-hide-button:hover,
+.voice-brief-dialogue-hide-button:focus {
+	background-color: rgba(255, 255, 255, 0.08);
+	color: rgba(255, 255, 255, 0.7);
+}
+
+.voice-brief-dialogue-hide-button:active {
+	background-color: rgba(255, 255, 255, 0.12);
+	color: rgba(255, 255, 255, 0.9);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@tinyaxis/voice-brief-cinnamon",
+  "version": "0.4.0",
+  "description": "Cinnamon desktop overlay for Voice Brief hook events",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Geequlim/voice-brief.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Geequlim/voice-brief/issues"
+  },
+  "homepage": "https://github.com/Geequlim/voice-brief#readme",
+  "os": [
+    "linux"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "extension",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * @tinyaxis/voice-brief-cinnamon 的 postinstall 安装脚本。
+ *
+ * 仅复制扩展文件到当前用户的 Cinnamon 扩展目录：
+ * - 优先 $XDG_DATA_HOME，否则 ~/.local/share
+ * - 先复制到同父目录临时目录，验证通过后 rename
+ * - 替换已有安装时保留备份，失败自动恢复，成功后删除备份
+ * - 不执行 gdbus，不强制重载或启用扩展
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const UUID = 'voice-brief@tinyaxis';
+const packageRoot = path.resolve(__dirname, '..');
+const extensionSource = path.join(packageRoot, 'extension', UUID);
+
+function fail(message) {
+	console.error(`[voice-brief-cinnamon] ${message}`);
+	process.exit(1);
+}
+
+function validateExtension(directory, label) {
+	const metadataFile = path.join(directory, 'metadata.json');
+	if (!fs.existsSync(metadataFile)) fail(`${label} 缺少 metadata.json`);
+	let metadata;
+	try {
+		metadata = JSON.parse(fs.readFileSync(metadataFile, 'utf8'));
+	} catch (error) {
+		fail(`${label} 的 metadata.json 无法解析: ${error.message}`);
+	}
+	if (metadata.uuid !== UUID) fail(`${label} 的 uuid 与预期不符: ${metadata.uuid}`);
+	if (!fs.existsSync(path.join(directory, 'extension.js'))) fail(`${label} 缺少扩展入口 extension.js`);
+	return metadata;
+}
+
+function copyDirectory(source, target) {
+	fs.mkdirSync(target, { recursive: true });
+	for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+		const from = path.join(source, entry.name);
+		const to = path.join(target, entry.name);
+		if (entry.isDirectory()) copyDirectory(from, to);
+		else if (entry.isFile()) fs.copyFileSync(from, to);
+	}
+}
+
+function main() {
+	validateExtension(extensionSource, '扩展产物');
+
+	const dataHome = process.env.XDG_DATA_HOME && process.env.XDG_DATA_HOME.trim()
+		? process.env.XDG_DATA_HOME
+		: path.join(os.homedir(), '.local', 'share');
+	const extensionsRoot = path.join(dataHome, 'cinnamon', 'extensions');
+	const targetDirectory = path.join(extensionsRoot, UUID);
+	const stagingDirectory = path.join(extensionsRoot, `.voice-brief-staging-${process.pid}-${Date.now()}`);
+	const backupDirectory = path.join(extensionsRoot, `.voice-brief-backup-${UUID}`);
+
+	fs.mkdirSync(extensionsRoot, { recursive: true });
+	try {
+		copyDirectory(extensionSource, stagingDirectory);
+		validateExtension(stagingDirectory, '临时安装目录');
+
+		const hadExisting = fs.existsSync(targetDirectory);
+		if (hadExisting) fs.renameSync(targetDirectory, backupDirectory);
+		try {
+			fs.renameSync(stagingDirectory, targetDirectory);
+		} catch (error) {
+			if (hadExisting) {
+				fs.rmSync(targetDirectory, { recursive: true, force: true });
+				fs.renameSync(backupDirectory, targetDirectory);
+			}
+			throw error;
+		}
+		fs.rmSync(backupDirectory, { recursive: true, force: true });
+	} finally {
+		fs.rmSync(stagingDirectory, { recursive: true, force: true });
+	}
+
+	console.log(`[voice-brief-cinnamon] 已安装 ${UUID} 到 ${targetDirectory}`);
+	console.log('[voice-brief-cinnamon] 如需立即生效，请在 Cinnamon 中重载或启用该扩展');
+}
+
+main();