# Maltese马尔济斯桌面宠物 **Repository Path**: Mint-Space/maltese ## Basic Information - **Project Name**: Maltese马尔济斯桌面宠物 - **Description**: Maltese · 会摇尾巴的桌面宠物聊天伙伴 Windows 桌面宠物:桌面上趴一只马尔济斯(挂件态),点它打开聊天窗口(窗口态)。 离线、只存本地,模型编在 exe 里,不联网。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-21 - **Last Updated**: 2026-09-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Maltese · 会摇尾巴的桌面宠物聊天伙伴 Windows 桌面宠物:桌面上趴一只马尔济斯(挂件态),点它打开聊天窗口(窗口态)。 离线、只存本地,模型编在 exe 里,不联网。 ## 文档地图 | 文档 | 讲什么 | 什么时候看 | |---|---|---| | 本文件 | 是什么、怎么构建 / 跑 / 验 | 第一次拿到这个仓库 | | [`ONBOARDING.md`](ONBOARDING.md) | **新人上手 / 开发手册**:这台机器的坑、改一处东西的完整流程、排查手册、常见误解 | **第一天就该读** | | [`ARCHITECTURE.md`](ARCHITECTURE.md) | **架构**:两形态一个窗口、线程与事件协议、启动→每帧→退出、状态归属、失败降级路径 | 想知道"整体怎么转起来" | | [`MODULES.md`](MODULES.md) | **模块与接口参考**:逐模块职责 / 对外入口 / 依赖方向 / 测试分布,含"死 pub"与全局状态清单 | 要改某一块、或想知道"这东西归谁管" | | [`TECH_DESIGN.md`](TECH_DESIGN.md) | **工程实现**:架构总览(§0)、关键设计与实测数据、测试策略、开发开关、**偏差表 §11c / 未做项 §11d** | 要改代码 | | [`CHANGELOG.md`](CHANGELOG.md) | **按时间顺序的实现日志**(§11b-1 … §11b-67):每一轮踩过的坑、当时为什么这么定、后来被什么推翻 | 想知道"某个决定是怎么来的"。**源码注释里的 `§11b-NN` 指的就是这份** | | [`REBUILD.md`](REBUILD.md) | **从零复刻指南**:约束怎么推出设计、哪些决定可迁移、各自的代价 | 想做一个同类的东西 | | [`DESIGN.md`](DESIGN.md) | **界面规格**:长什么样、为什么这样 | 要改界面 | | [`ui/maltese-ui-prototype.html`](ui/maltese-ui-prototype.html) | 界面规格的**唯一来源**(可交互原型);`DESIGN.md` 是它的文字版 | 对某个控件拿不准时 | **要改代码,先读 `TECH_DESIGN.md` §0(架构总览)**——那一节有一张架构图、模块地图, 以及"一次对话里发生了什么";它的展开版就是 `ARCHITECTURE.md`。 ## 构建 **先放模型**:`models/` 整个被 git 忽略,**clone 之后不放进模型是构建不过的** (`src/lib.rs` 用 `include_bytes!` 把它编进 exe)。需要的是 `models/maltese.json.gz`——见 `TECH_DESIGN.md` §5.7(模型从哪来)与 §7.6(为什么不进仓库)。 ```powershell cargo build --release # 产物 target\release\maltese.exe ``` **两条坑,先看**: 1. **不要跑 `cargo fmt`**。`src/rt/` 是从 Polarbear 逐字搬来的(`tests/vendor_integrity.rs` 用 FNV 指纹守着),而 `rustfmt.toml` 的 `ignore` 是 nightly 限定项、stable 上静默失效 —— 格式化会把 `rt/` 重排、指纹当场变红(§11a-2、§2b)。 2. 这台机器如果被 Smart App Control 拦(`WinError 4551`),用 `cargo build --release --features console-subsystem` 出逃生版(§11b-29); 代价是双击会闪一下黑框。 ## 运行 ```powershell .\target\release\maltese.exe # GUI:挂件态起步,点小狗开窗口 .\target\release\maltese.exe -cli # 终端对话(模型验收口) .\target\release\maltese.exe --no-model # 不加载模型,回复走内置台词表 .\target\release\maltese.exe --help # 其余开关(-model= / --dump-pose-sheet 等) ``` 存档与日志放在**数据目录**里(`src/paths.rs` 一处决定):**便携版 = exe 同级**(与从前完全一致), **从商店装的版本 = `%LOCALAPPDATA%\Maltese\`**——`WindowsApps` 是只读的,写在那儿会静默失败。 文件名是 `maltese_state.json` / `maltese.log`(写满一份会自动滚成 `maltese.log.1`,只留最近两份)。 开发用的开关(截图、灌数据、逐帧打印、托盘应急)列在 `TECH_DESIGN.md` §7.5。 ## 签名 ```powershell # 造证书(跑一次)→ 构建 + 签名 + 验证 powershell -ExecutionPolicy Bypass -File signing\make-cert.ps1 powershell -ExecutionPolicy Bypass -File sign.ps1 ``` 身份写在证书里:**`CN=北极熊, O=Mint 薄荷, C=CN`**(与 taco 的 `signing/make-cert.ps1` 同一套做法);版本信息(发布者 / 公司 / 版本)在 `build.rs` 里按 Mint 那套字段嵌进 exe, 版本号只从 `Cargo.toml` 取一处。 ⚠️ **自签名挡不住 Smart App Control / SmartScreen**(它们要云信誉或 CA 签发的证书)—— 签名后属性页仍会显示「未知发布者」,本机"GUI 版被拦"那件事也**不会**因此好转(§11b-29)。 它的用处是:属性页能看到发布者、内部署流程就位、以后换真证书时不用改流程。 > `.ps1` 里带中文的话**必须存成 UTF-8 with BOM**:PowerShell 5.1 没 BOM 就按 ANSI 读, > 字符串里的中文会直接把脚本解析断(`signing/make-cert.ps1` 末尾记着这条)。 ## 测试与验证 ```powershell cargo test --release # lib 221 条 + 集成 5 条 cargo check --release --all-targets # 本机可用的静态检查 ``` **别用 `cargo test --lib`**:`tests/vendor_integrity.rs`(`src/rt/` 的逐字指纹)挂在**另一个 target** 上,而"日常只跑 `--lib`"正是那条守卫**红了一年没人知道**的原因(CHANGELOG §11b-45)。 跑全部 target 才会带上它。 **`cargo clippy` 在本机是"时好时坏"**:它要**执行** `build-script-build.exe`,而 Smart App Control 会拦这类未签名二进制(`WinError 4551`)——**同一份源码,有时一次就过、有时换源码/换 `CARGO_TARGET_DIR` 都过不去**。(写这份文档时实测是**能跑**的:26 条 warning,`--all-targets` exit 0; 更早的会话里它一次都没跑起来。所以别把它当"必过的门"。) 静态检查以 `cargo check --release --offline --all-targets` 为准——对这个仓库基本等价。 ### 界面类改动怎么验(不能只靠"看截图") | 手段 | 怎么用 | 什么时候用 | |---|---|---| | **进程内界面测试** | `src/ui/ui_tests.rs`:无窗口造一个 `Context`、喂 `egui::Event`、断言 `MalteseApp` 的字段**和这一帧下发的 `ViewportCommand`** | **默认手段**。焦点、命中区、`generating` 卡死、音效接线这类"截图看不出来"的事,只能这么测 | | **截图** | `cargo build --release --features screenshot`,再设 `EFRAME_SCREENSHOT_TO=` + `MALTESE_INSTANT_ANIM=1`(+ `MALTESE_START_WINDOW=1` 直接开窗口态、`MALTESE_DEV_UI=tag,menu,drop-model,…` 把只有交互才出现的部件定住) | 看观感 | | **从屏幕上抓窗口** | `python tools/_grab_window.py [margin]` | ⚠️ 挂牌/引导牌撑高窗口时,`EFRAME_SCREENSHOT_TO` 那张图**会骗你**(内容整体下移 `top_extra()`)——要看真实所见就用这个。它自己也要**先声明 DPI 感知**,否则 `GetWindowRect` 给逻辑点、BitBlt 给物理像素,1.5× 缩放下整个抓偏 | | **冒烟** | `python tools/_gui_smoke.py `:启动 → 托盘 → 模型就绪 → 发 `WM_CLOSE` → 验优雅退出(读 `maltese.log`:便携版在 exe 同级、商店版在 `%LOCALAPPDATA%\Maltese\`,脚本两处都找) | 每次出包 | 开发开关(截图硬化、灌假消息、逐帧心跳、托盘应急)的完整清单在 `TECH_DESIGN.md` §7.5。 > ⚠️ **上面那些 `tools/_*.py` 不在仓库里**:`.gitignore` 把 `_*.py`(任何层级)都忽略了—— > 它们是开发机上的排障工具,**全新 clone 之后没有**。仓库里真正带的只有 > `tools/chat_probe.py` 与 `tools/hit_probe.py` 两个探针(`git ls-files tools` 可核)。 > 需要时照 §7.5 的说明重写一个,几十行的事。 ### CI `.github/workflows/ci.yml` 有个前提:**仓库里没有模型**(见上面「构建」),所以它在模型 缺席时只打印一条说明就退出。想让它真跑,得先把 `models/maltese.json.gz` 作为 Release 资产或 LFS 对象放进去。 ## 现状(出包时更新) - **测试**:lib **226** + 集成 **5**(其中 3 条是 `--ignored` 的模型实验台)。 - **产物**:单文件 exe,约 **35.4 MiB(37,147,608 B)**——体积几乎全是被 gzip 的内嵌检查点 (另有约 12 KB 是编进去的 MIT 许可原文,见下面「许可」)。 - **内嵌检查点**:**v2**(`d_model 512` / **词表 2158** / `slots 8` / `pool 1` / **`max_seq 32`** / 参数 6,414,446 / `val_loss 2.6130`),gz **29.4 MiB**。`src/engine.rs` 里有**硬断言**钉着它, 换模型必须同步(§5.7、CHANGELOG §11b-68)。 ⚠️ **这一版比上一版弱**:词表从 17829 缩到 2158、上下文从 128 缩到 **32**(比提示词本身还短), 换来的是 exe 小了 17 MiB。旧的两份归档在 `models/maltese-v1.json.gz`、`….zhwiki-backup`。 - **版本归档**:作者按 `versions/vN/maltese.exe` 留每一版的签名产物,根目录那份是当前在用的。 - **应用商店 / 安装包**:MSIX(`dist/maltese.msix`,33,963,612 B,自签名)给商店与侧载; MSI(`dist/maltese.msi`,34,172,928 B,自签名、**每机器安装**)给离线 / 企业 / 想要"能装能卸"的人。 前者的清单与图标资产在 `packaging/`,后者的 WiX 源也在那儿(`packaging/maltese.wxs`); 流水线是 `tools/pack_msix.py` 与 `tools/pack_msi.py`(MSI 那步要 WiX,从哪来见 [`../packaging/README.md`](../packaging/README.md) §10)。上架要走的手续、文案草稿与合规点 在 [`STORE.md`](STORE.md)。 ## 许可 **[MIT](../LICENSE)**,版权行是 `Copyright (c) 2026 北极熊 / Mint 薄荷`——与 exe 版本资源里 那句(`build.rs:32`)、商店列表的版权格(`STORE.md` §3.8)**同一行字**。 `Cargo.toml` 里也有一份 `license = "MIT"`(给 `cargo` / crates.io / 依赖扫描工具看), **两处要一直对得上**。`LICENSE` 保持纯英文原文、不加中文对照,这样 GitHub 之类才能把它认成 MIT。 **这份原文在四个地方出现,必须是同一份正文**(改一处就要四处一起改): | 在哪 | 谁生成 | 用户怎么看到 | |---|---|---| | 仓库根 `LICENSE` | 手写(**源头**) | 翻仓库 | | exe 里(`src/license.rs` 的 `include_str!("../LICENSE")`) | 编译期读上一条 | 设置 →「关于」→ 那行「许可」+「**MIT 许可**」按钮打开网页版 | | MSI 的安装首屏 | `tools/pack_msi.py` 把上一条**转成 RTF**(`WixUILicenseRtf`) | 双击 MSI 装的时候 | | 官网 `/license` | 人工同步(另一个仓库 `maltese-site`,见 `STORE.md` §5.3 的同款约定) | 页脚「条款」那一列 | **为什么 exe 里也要有一份**:MIT 的条件句要求"版权声明与这段许可声明随**副本**一并给出", 而便携版**只发一个 exe**——用户手里没有那份 `LICENSE`。所以原文得编进二进制、 并且随时打得开(打开的那一页是自包含 HTML,不联网)。这不是装饰,是把许可条件兑成了可执行的东西。 **三件必须一并说清的事**,不然这份 MIT 会被读成"什么都能覆盖": 1. **`src/rt/` 是从 Polarbear 逐字搬来的**(`tensor` / `genome` / `runtime` / `data`; `tests/vendor_integrity.rs` 用 FNV 指纹守着逐字一致性,见 [`REBUILD.md`](REBUILD.md) §1)。 那个项目**也属于本仓库作者**,所以 2026-09-20 那天两边同时加上了同一份 MIT (`E:\mimo\Polarbear\LICENSE` + 它 `Cargo.toml` 里的 `license = "MIT"`)—— **两边必须是同一个许可**,否则这边这份覆盖不到搬过来的代码。 ⚠️ 反过来说:以后若要跟别处的 Polarbear 分支对上,先确认那一支的许可再搬。 2. **编进 exe 的第三方 crate**(`Cargo.toml` / `Cargo.lock` 是权威清单:serde / rand / rayon / chrono / flate2 / image / eframe / windows-sys …)各自有各自的许可,多数是 MIT 或 MIT OR Apache-2.0。⚠️ **本机没有逐个核过,也没有附带第三方声明**——离线环境下 `cargo metadata` 解析不全(缺 Linux 平台的包缓存,`accesskit_atspi_common` 就下不来)。 要公开分发(商店或官网下载)的话值得补一份 `THIRD_PARTY.md`,`cargo-about` / `cargo-license` 能生成,但**都得联网**。 3. **内嵌的检查点**(`models/maltese.json.gz`)是作者自训的 v2,训练数据取自公开语料—— 数据集的许可**不在 MIT 的射程内**,这一条**没核过**,不能默认它没问题。