编辑器模块(笔记)初版

This commit is contained in:
zhongluofeng committed 2026-09-30 18:12:53 +08:00
1 parent 7e65825d3e
commit ad987111a3
66 files changed
+17470 -283

No files matched your search

+507
View File
@@ -0,0 +1,507 @@
# AI Agent 开发指南
本文档为 AI Agent 开发本项目提供详细的规范和模板,帮助快速理解项目结构、技术栈和开发流程。
## 项目概览
- **项目名称**: Thing
- **技术栈**: Tauri 2 + Vue 3 + Vite + Pinia + shadcn-vue + Rust
- **平台**: Windows
- **包管理**: Bun
## 核心架构
### 模块系统
项目采用统一的模块注册机制。每个模块通过 `src/modules/<name>/index.ts` 导出 `ModuleConfig` 配置,由 `src/modules/registry.ts` 中的 `moduleRegistry` 单例统一管理。
```
src/modules/<module-name>/
├── index.ts # 模块配置(ModuleConfig)
├── ModuleComponent.vue # 前端组件
src-tauri/src/ # Rust 后端逻辑(按功能分文件/模块目录)
```
#### 模块配置类型
```typescript
// src/types/module.ts
interface ModuleConfig {
id: string // 唯一标识
name: string // 显示名称
icon: string // 图标标识(对应 icons.ts 中的 key)
description: string // 模块描述
category: ModuleCategory // 分类:'network' | 'tool' | 'system' | 'media'
defaultEnabled?: boolean // 默认是否启用
builtin?: boolean // 是否内置模块(不可禁用)
loader?: () => Promise<{ default: Component }> // 懒加载
component?: Component // 直接组件引用(内置模块)
searchItems?: SearchIndexItem[] // 全局搜索项
process?: ModuleProcessConfig // 进程配置(需要子进程的模块)
lifecycle?: ModuleLifecycle // 生命周期钩子
order?: number // 排序权重
}
```
#### 注册新模块
1. 创建 `src/modules/<name>/index.ts`,导出 `moduleConfig`
2. 在 `src/modules/index.ts` 中添加导入
3. 在 `src/modules/icons.ts` 中添加图标映射
### IPC 通信
前端通过 Tauri API 调用 Rust 命令:
```typescript
import { invoke } from '@tauri-apps/api/core'
// 调用 Rust 命令
const result = await invoke('module_command', { param: 'value' })
```
### 状态管理
使用 Pinia 管理全局状态,每个模块可拥有独立的 store:
```typescript
// src/stores/moduleName.ts
import { defineStore } from 'pinia'
export const useModuleStore = defineStore('moduleName', {
state: () => ({
// 状态定义
}),
actions: {
// 操作方法
}
})
```
## 开发规范
### 命名规范
| 类型 | 格式 | 示例 |
|------|------|------|
| 组件 | PascalCase | `ProxyManager.vue` |
| 函数 | camelCase | `getSystemProxy()` |
| 文件 | kebab-case | `proxy-manager.ts` |
| 常量 | UPPER_CASE | `MAX_HISTORY_COUNT` |
| Rust 模块 | snake_case | `proxy.rs` |
| Tauri 命令 | snake_case | `get_system_proxy` |
### 代码风格
- **TypeScript**: 使用 ESLint,配置在 `.eslintrc.cjs`
- **Rust**: 使用 `cargo fmt` 格式化
- **提交信息**: Conventional Commits 格式
## 模块开发模板
### 前端模块模板
创建 `src/modules/<module-name>/` 目录,包含以下文件:
```typescript
// index.ts - 模块配置
import type { ModuleConfig } from '@/types/module'
export const moduleConfig: ModuleConfig = {
id: 'module-name',
name: '模块名称',
icon: 'module-name', // 需在 icons.ts 中添加映射
description: '模块描述',
category: 'tool', // 'network' | 'tool' | 'system' | 'media'
defaultEnabled: true,
loader: () => import('./ModuleComponent.vue'),
searchItems: [
{
title: '功能名称',
description: '功能描述',
keywords: ['关键词1', '关键词2']
}
],
order: 100
}
```
> 注册模块时,还需在 `src/modules/index.ts` 中添加导入,在 `src/modules/icons.ts` 中添加图标映射。
```vue
<!-- ModuleComponent.vue - 主组件 -->
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import { useModuleStore } from '@/stores/moduleName'
const store = useModuleStore()
// 组件逻辑
const data = ref(null)
const loadData = async () => {
// 调用 Rust 命令
}
onMounted(() => {
loadData()
})
onUnmounted(() => {
// 清理资源
})
</script>
<template>
<div class="module-container">
<!-- 模块内容 -->
</div>
</template>
<style scoped>
.module-container {
padding: 20px;
}
</style>
```
### Rust 命令模板
在 `src-tauri/src/` 中创建模块文件(如 `src-tauri/src/my_module.rs` 或 `src-tauri/src/my_module/` 目录),并在 `lib.rs` 中注册:
```rust
// src-tauri/src/my_module.rs
use serde::Serialize;
use tauri::State;
#[derive(Serialize)]
pub struct CommandResult<T> {
pub success: bool,
pub data: Option<T>,
pub error: Option<String>,
}
#[tauri::command]
pub async fn module_get_data() -> CommandResult<Vec<String>> {
match fetch_data() {
Ok(data) => CommandResult {
success: true,
data: Some(data),
error: None,
},
Err(e) => CommandResult {
success: false,
data: None,
error: Some(e.to_string()),
},
}
}
#[tauri::command]
pub async fn module_set_data(data: String) -> CommandResult<bool> {
match save_data(&data) {
Ok(_) => CommandResult {
success: true,
data: Some(true),
error: None,
},
Err(e) => CommandResult {
success: false,
data: None,
error: Some(e.to_string()),
},
}
}
fn fetch_data() -> Result<Vec<String>, Box<dyn std::error::Error>> {
// 实现逻辑
Ok(vec![])
}
fn save_data(data: &str) -> Result<(), Box<dyn std::error::Error>> {
// 实现逻辑
Ok(())
}
```
### 注册 Rust 命令
在 `src-tauri/src/lib.rs` 中注册命令:
```rust
// lib.rs
mod my_module;
use my_module::{module_get_data, module_set_data};
#[tauri::command]
fn greet(name: &str) -> String {
format!("Hello, {}!", name)
}
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
tauri::Builder::default()
.invoke_handler(tauri::generate_handler![
greet,
module_get_data,
module_set_data
])
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
## 常用 Tauri 插件
项目当前使用的 Tauri 插件(见 `Cargo.toml`):
| 插件 | 用途 |
|------|------|
| `tauri-plugin-autostart` | 开机自启 |
| `tauri-plugin-opener` | 打开文件/目录/URL(绕过 IPC scope 限制) |
| `tauri-plugin-dialog` | 文件/目录选择对话框 |
> 系统托盘(tray)和窗口效果(mica/acrylic)是 Tauri 2 内置能力,无需额外插件。日志系统为自建(`src-tauri/src/logger.rs`),未使用 `tauri-plugin-log`。
## 进程管理
对于需要管理外部子进程的模块(如 mihomo),使用内置的 `ProcessManager`。下载器模块使用进程内自建下载引擎(`src-tauri/src/download_engine/`),不涉及外部子进程:
### 架构
- **Rust 端** (`src-tauri/src/process_manager.rs`):`ProcessManager` 通过 `std::process::Command` 管理子进程,支持启动、停止、崩溃检测和自动重启
- **前端** (`src/stores/processStore.ts`):Pinia store,通过 `invoke` 调用 Rust 命令,通过 `listen` 接收进程状态变更事件
- **模块配置**:在模块的 `index.ts` 中通过 `ModuleProcessConfig` 声明进程信息
### 模块配置
```typescript
// src/modules/proxy/index.ts
export const moduleConfig: ModuleConfig = {
// ...
process: {
name: 'mihomo',
executable: '', // 运行时确定
args: ['-f', 'config.yaml'],
autoStart: false, // 模块启用时是否自动启动
restartOnCrash: true, // 崩溃后自动重启
maxRestarts: 3 // 最大重启次数(0 = 不限制)
}
}
```
### 前端 API
```typescript
import { useProcessStore } from '@/stores/processStore'
const processStore = useProcessStore()
// 通过模块 ID 启动进程(自动读取模块配置)
await processStore.startByModule('proxy')
// 停止进程
await processStore.stopByModule('proxy')
// 获取进程状态
const status = processStore.getProcessStatus('proxy')
// 监听状态变更(在 main.ts 中已初始化)
// processStore.initListener()
```
### Rust 命令
| 命令 | 参数 | 返回值 |
|------|------|--------|
| `process_start` | `StartProcessParams` | `ProcessInfo` |
| `process_stop` | `id: String` | `()` |
| `process_status` | `id: String` | `Option<ProcessInfo>` |
| `process_all_status` | - | `Vec<ProcessInfo>` |
| `process_stop_all` | - | `()` |
### 事件
| 事件名 | 载荷 | 触发时机 |
|--------|------|----------|
| `process-status-changed` | `ProcessInfo` | 进程状态变更(崩溃、重启、停止) |
## 数据存储
### 配置文件
使用 JSON 格式存储在应用数据目录:
```rust
// 获取应用数据目录
let app_dir = app.path().app_data_dir()?;
let config_path = app_dir.join("config.json");
```
### SQLite
对于需要查询的数据(如剪贴板历史),使用 `rusqlite` crate:
```toml
# Cargo.toml
rusqlite = { version = "0.30", features = ["bundled"] }
```
## 权限配置
在 `src-tauri/capabilities/default.json` 中配置权限(实际项目配置):
```json
{
"$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default",
"description": "Capability for the main window",
"windows": ["main"],
"permissions": [
"core:default",
"opener:default",
"opener:allow-reveal-item-in-dir",
"opener:allow-open-path",
"dialog:default",
"core:window:allow-minimize",
"core:window:allow-maximize",
"core:window:allow-close",
"core:window:allow-toggle-maximize",
"core:window:allow-hide",
"core:window:allow-show",
"core:window:allow-set-focus",
"core:window:allow-start-dragging",
"core:window:allow-set-effects",
"core:window:allow-set-background-color",
"core:window:allow-set-theme"
]
}
```
## 调试指南
### 前端调试
- 使用 Chrome DevTools:`Ctrl+Shift+I`
- 打印日志:`console.log()`
### Rust 调试
- 使用 `crate::logger::log_info / log_warn / log_error`(或 `log_line`)写入统一日志文件,日志页面可过滤级别
- 使用 `dbg!()` 宏调试变量(仅临时,提交前删除)
- 使用 Visual Studio Code 的 Rust 调试插件
### 构建问题排查
1. **Rust 编译错误**:检查 `Cargo.toml` 依赖版本
2. **前端构建错误**:检查 `package.json` 依赖和 TypeScript 类型
3. **Tauri 配置错误**:检查 `tauri.conf.json` 路径和权限配置
## 常见问题
### Windows 路径问题
使用 `std::path::Path` 处理路径,避免硬编码分隔符:
```rust
let path = Path::new("data").join("config.json");
```
### Tauri 2 权限问题
确保在 `capabilities` 中声明所需权限,否则命令调用会失败。
### WebView2 兼容性
确保用户安装了 Microsoft Edge WebView2 Runtime:
- 安装包:https://developer.microsoft.com/zh-cn/microsoft-edge/webview2/
## 开发流程
1. **创建模块目录**:`src/modules/<module-name>/`,编写组件和 `index.ts` 配置
2. **注册模块**:在 `src/modules/index.ts` 中添加导入,在 `src/modules/icons.ts` 中添加图标映射
3. **实现 Rust 命令**:在 `src-tauri/src/` 中编写后端逻辑,在 `lib.rs` 中注册命令
4. **配置权限**:更新 `capabilities/default.json`(如需要)
5. **测试**:运行 `bun run tauri dev` 测试
6. **构建**:运行 `bun run tauri build` 构建生产版本
## 模板代码生成
### 快速生成模块
使用以下命令创建新模块结构:
```bash
# 创建前端模块目录
mkdir -p src/modules/new-module
# 创建 Rust 模块文件
touch src-tauri/src/new_module.rs
```
### 模板文件
复制以下模板快速开始:
**前端组件模板**:
```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue'
const loading = ref(false)
const error = ref('')
const fetchData = async () => {
loading.value = true
try {
// 调用 Rust 命令
} catch (e) {
error.value = (e as Error).message
} finally {
loading.value = false
}
}
onMounted(() => {
fetchData()
})
</script>
<template>
<div v-if="loading" class="flex items-center justify-center py-8">
<Loader2 class="animate-spin text-muted-foreground" :size="24" />
</div>
<div v-else-if="error" class="text-destructive p-4">{{ error }}</div>
<div v-else class="content p-5">
<!-- 内容 -->
</div>
</template>
```
**Rust 命令模板**:
```rust
#[tauri::command]
pub async fn new_module_action() -> Result<serde_json::Value, String> {
// 实现逻辑
Ok(serde_json::json!({}))
}
```
## 注意事项
1. **避免阻塞主线程**:Rust 命令使用 `async` 避免阻塞
2. **资源清理**:在组件卸载时清理定时器和事件监听器
3. **错误处理**:所有操作都应有错误处理和用户提示
4. **安全考虑**:避免执行未验证的用户输入作为命令参数
5. **性能优化**:对于高频更新的数据使用 `watch` 和 `computed`
## 参考资源
- [Tauri 2 Documentation](https://v2.tauri.app/)
- [Vue 3 Documentation](https://vuejs.org/)
- [Pinia Documentation](https://pinia.vuejs.org/)
- [shadcn-vue UI Documentation](https://shadcn-vue.com/docs)
- [Rust Documentation](https://doc.rust-lang.org/)
+519
View File
@@ -0,0 +1,519 @@
# 编辑器模块规划(Editor Module Plan)
> 状态:**方案已确认,待开工**(v1 已落地;v2 定位修订与本轮 10 项决策已定稿)
> 本轮决策(2026-09-30,用户已拍板):**不引入工作区**(Q2=a)· **目录树不纳入索引**(Q3=a)· **标签页放 P4**(Q4=a)· **模块显示名 = 编辑器**(Q1=a)
> v1 现状(原「笔记模块」,已全部落地):CM6 内核 + Live Preview + 本地笔记库 + 独立窗口 + 检索/索引 + WebDAV + 导入导出 + 模板 + 双链 + 图片预览 + 全局快捷键 + 文件关联
> v2 修订方向:模块核心从「笔记」改为「**编辑器**」——一个 notepad++ 式的通用文本/代码编辑器;**笔记库与本地目录探查退化为它的两个并列导航能力**,不再是模块的中心
> 已确认决策:所见即所得 = **Live Preview**(非块编辑);WebDAV = **备份 / 同步目标**(不做远端直连读写);编码 = **可探测、可切换、原样写回**
> 定位:Thing 工具集的第 13 个模块,`id = editor`(原 `notes`),`category = 'tool'`
> 作者:砚 | 日期:2026-09-30
> 关联文档:`AI_DEV_GUIDE.md`(模块注册 / IPC / 进程管理范式)、`UI_DESIGN_SYSTEM.md`(页面框架 / 组件规范)、`TERMINAL_MODULE_PLAN.md`(独立窗口 / 跨窗口设置同步范式)
>
> 阅读顺序:**§11 开工清单(先读,它是执行入口)** → §0 结论 → §1 定位修订 → §3 功能规格 → §5 编码 → §7 缺口 → §8 路线图。
> **§9 是 v1 的压缩实施记录**,只保留「为什么这么做」的结论与踩过的坑;**§10 是已拍板的决策表**(不再是待定项)。
---
## 0. 结论先行
八个关键判断。
1. **模块改名 `notes` → `editor`,但一次到位、不留双命名。** `id` / 窗口 label / 事件名 / Rust 命令前缀 / 目录名 / 存储键全部统一。半改不改(模块叫 editor、命令还叫 `notes_*`)比不改更糟:读代码的人要同时维护两套心智。改名是机械工作(约 400 处标识符),风险集中在「漏改一处」,用脚本核对(§9.6)。
2. **「笔记」不是被删掉,而是被降级为一种能力。** 编辑器的最小模型是「路径 + 字节 + 编码」,笔记库是加在它之上的一层(库根沙箱 + front-matter + 索引 + 双链)。因此**文件是真相层,笔记库是视图层**——这条和 v1 的「文件即真相」并不冲突,只是把「库」从中心挪到了并列位置。
3. **左侧导航 = 两个并列的树 + 三块辅助能力。** 两个树:**笔记库**(沙箱、有索引、有双链)与**本地目录**(任意路径、无索引、无 front-matter 语义)。三块辅助:**文件名/内容搜索**、**最近打开(文件夹与文件分开记)**、**定位到资源管理器**。
4. **多编码是这一版的新增硬需求,且必须「可切换」。** 探测链:BOM → 严格 UTF-8 → GB18030(中文存量主力)→ 用户手动指定。写回**默认按读取时的编码**。切换编码的语义是「**换一种方式解释磁盘字节**」而不是「重新解释缓冲区文本」——因此切换动作会**从磁盘按新编码重新解码**(有未保存改动时先让用户三选一,见 §5.3)。
5. **系统集成走用户级注册表,不需要管理员权限。** 文件关联(双击打开)走 Tauri `fileAssociations`;**资源管理器右键菜单**(文件/文件夹)走 `HKCU\Software\Classes\*\shell\*` 与 `Directory\shell\*`,用**已在依赖树里的 `winreg`** 写(项目已有 `system_proxy.rs` / `glsmtc.rs` 两处先例)。**注册动作放在设置页按钮里、默认不自动写注册表**——开发模式下的 exe 路径是 `target\debug\thing.exe`,自动注册会留下指向临时产物的僵尸菜单项。
6. **默认全局快捷键 `Alt+E` 打开编辑器。** 走既有 `shortcut.rs`(原子注册 + 冲突检测),设置页可改。
7. **不引入「工作区」概念(已拍板)。** 用户要的是「右键文件夹 → 在这里打开」,用**当前目录根**这一个状态就够了(可切换 + 有历史)。引入 workspace 会连带出「多根 / 会话恢复 / 每根独立状态」三个复杂度,而收益(同时开两个目录树)在 notepad++ 式用法里很低。因此侧栏只有一个「目录」面板,根是单值。
8. **不做的事**(明确划界,避免无限扩张):不做 IDE 能力(调试器、终端内嵌、LSP 补全、Git 集成);不做块编辑器;不做远端工作区(WebDAV 只做备份/同步目标)。
---
## 1. 定位修订(v1 → v2)
| 维度 | v1(笔记模块) | v2(编辑器模块) |
|---|---|---|
| 一句话 | 一个 Markdown 笔记库,带所见即所得编辑 | 一个通用文本/代码编辑器,**顺带**能管一个笔记库 |
| 中心对象 | 笔记(库内 `.md`) | 文件(任意路径的任意文本) |
| 首要入口 | 库树 → 选一篇笔记 | 打开文件 / 最近文件 / 目录树 → 选一个文件 |
| 笔记库的角色 | 模块的**全部** | 两个导航根之一 + 一层语义(front-matter / 双链 / 索引) |
| 编码 | 「尽量别写坏」(读时记、写回原样) | **一级功能**:探测 + 状态栏显示 + 可切换 |
| 系统集成 | 无(P2 曾因依赖代价搁置) | 文件关联 + 资源管理器右键 + `Alt+E` |
| 索引 | FTS5 全文检索(笔记的核心) | 保留,但只服务笔记库;目录树只做文件名匹配 |
| markdown Live Preview | 默认视图 | **按文件类型自动选择**:`.md` 用 Live Preview,其余用纯高亮 |
> 一句话总结这次修订:**把「库」从产品中心降为两个导航能力之一,把「文件 + 编码 + 系统集成」提到中心。**
---
## 2. 需求解构
| 用户原话 | 解构为 | 落点 |
|---|---|---|
| 「核心改为 Editer,标题和其他都改」 | 模块改名 + 重定位 + 主页面/窗口标题/文案全面改口径 | §1 / §7 / §9.6 |
| 「笔记作为编辑器模块的一个核心功能」 | 笔记库降为并列能力,但保留全部既有实现 | §1 / §3.3 |
| 「左边导航栏有两个功能:笔记库 / 本地目录结构」 | 侧栏两个并列根:库根(沙箱 + 索引)与当前目录(任意) | §3.3 / §6 |
| 「导航栏需要定位打开文件位置、搜索文件名(参考 idea)」 | 「在资源管理器中显示」+ 两级过滤(文件名 LIKE / 库内 FTS) | §3.4 |
| 「核心只是普通编辑器,类似 notepad++」 | 不引入 IDE 能力;以「打开快、编码稳、快捷键全」为质量目标 | §0.8 / §3.1 |
| 「快捷键直接打开编辑器,默认 alt+e」 | 全局快捷键,默认 `Alt+E`,设置页可改 | §3.7 |
| 「文件管理器右键菜单,用 Thing Editer 打开」 | HKCU 注册 `*\shell\ThingEditor` 与 `Directory\shell\ThingEditor` | §3.6 |
| 「历史打开的文件夹/文件记录」 | 最近文件 + 最近文件夹两份列表(分组显示、可清空) | §3.5 |
| 「多编码,识别 + 支持切换编码」 | 探测链 + 状态栏编码菜单 + 重解码 + 按新编码重写 | §5 |
| 「优化结构和功能完整性」 | 补齐:编码切换、目录树、最近记录、右键菜单、大文件策略、只读打开 | §3 / §4 |
---
## 3. 功能规格
### 3.1 编辑器核心
- **打开方式**:最近文件 / 目录树 / 笔记库树 / 系统对话框 / 命令行 / 文件关联 / 资源管理器右键 / 拖入窗口。
- **视图按类型自动选**:`.md`/`.markdown`/`.mdx` 默认 Markdown(Live Preview,可在状态栏切到源码);其余按扩展名加载语言高亮(`@codemirror/lang-*` 按需 `import()`)。
- **基础编辑**:行号、折叠、括号匹配、多光标、矩形选择、搜索替换(CM6 原生 `searchKeymap`)、转到行(`Alt+G`)、撤销栈、Tab 缩进。
- **快捷键**(窗口内,CM6 `keymap` 优先于全局):`Ctrl+S` 保存、`Ctrl+Shift+S` 另存为、`Ctrl+O` 打开、`Ctrl+P` 快速打开、`Ctrl+W` 关闭当前文档、`Ctrl+Tab` 文档间切换、`Ctrl+E` 切换编码、`Ctrl+Shift+M` 切换 Live Preview/源码。
- **多文档**:同一窗口内多标签(**新增**,见 §8-P1)。`Ctrl+W` 关闭标签,关闭前若有未保存改动则二次确认。
- **大文件策略**:超过阈值(默认 5MB,可配)时关闭 Live Preview / 折叠 / 补全 / 装饰,只保留高亮 + 行号;并在状态栏给出可点击的降级说明。
- **只读打开**:检测到文件不可写时以只读模式打开(替代「打开成功但保存失败」)。
### 3.2 笔记模式(`.md` 在库内)
保持 v1 全部能力:Live Preview(标题/强调/行内代码/列表/任务/引用/代码块/分隔线/表格/图片内联)、`[[wikilink]]` 点击跳转与一键新建、front-matter 属性面板、大纲、双链面板、字数/行数统计。
### 3.3 左侧导航(两个并列根)
| 面板 | 根 | 能力 | 数据来源 |
|---|---|---|---|
| **笔记库** | 库根(可切换,默认 `{appData}/editor/library`) | 树 / 新建 / 重命名 / 删除 / 标签 / 双链 / FTS 全文检索 | SQLite 索引(`notes.db` → `editor.db`) |
| **本地目录** | 当前目录根(可切换,有历史) | 树 / 文件名过滤 / 打开文件 / 新建文件/文件夹 / 重命名 / 删除 / 在资源管理器中显示 / 复制路径 | 直接 `fs` 读目录(**不进索引**) |
两个面板都在**同一个侧栏**里用分段导航切换(v1 已有 4 段:文件/检索/大纲/双链;v2 扩为:**库 / 目录 / 检索 / 最近**,大纲与双链改为编辑区右侧的**抽屉**,因为它们跟「当前文档」绑定而不是跟「导航」绑定)。
> 为什么把大纲/双链挪到右侧抽屉:它们描述的是**当前文档**,而侧栏描述的是**去哪找文件**。混在一起会让侧栏在「导航」与「文档信息」两种语义之间摇摆(v1 已经能感到这个别扭)。
### 3.4 搜索与定位
- **文件名过滤**:侧栏顶部输入框,对当前树做不区分大小写的子串匹配,命中项的**祖先自动展开**(v1 已有)。
- **快速打开 `Ctrl+P`**:跨「库 + 最近 + 当前目录」的文件名跳转,本地模糊排序(连续匹配 > 前缀 > 词首 > 位置),零网络、零后端。
- **库内全文检索 `Ctrl+Shift+F`**:FTS5(trigram),标题权重高于正文,命中片段高亮(定界符方案,不注入 HTML)。目录树**不做**全文检索(不在索引里,也不该为此扫盘)。
- **定位打开文件位置**:`revealItemInDir`(`opener` 插件,能力已授权)。三处入口:标签右键、侧栏行右键、状态栏路径点击。
- **搜索文件名作用域切换**:输入框旁边一个「当前树 / 全库 / 当前目录」的小切换(idea 的 `Ctrl+Shift+N` 体验,但不引入独立对话框)。
### 3.5 历史记录
- **最近文件**:路径 + 显示名 + 时间 + 是否仍存在(失效项灰显、可一键清理)。
- **最近文件夹**:同理,用于「右键文件夹 → 在这里打开」与侧栏目录面板的快速切换。
- 存储:`editor/settings.json` 的 `recentFiles` / `recentFolders`(**与笔记库解耦** —— 库可以换/删,历史不该跟着丢)。各自上限 20 条,超出淘汰最旧。
- 两份列表**分开存**:文件与文件夹的用途不同,混在一起会让「最近文件夹」被文件挤掉。
### 3.6 系统集成
| 集成 | 机制 | 权限 |
|---|---|---|
| 双击 `.md`/`.markdown`/`.mdx` 打开 | `bundle.fileAssociations`(安装器写 `OpenWithProgids`) | 安装器 |
| 「用 Thing 编辑器打开」(文件) | `HKCU\Software\Classes\*\shell\ThingEditor` | 用户级,免管理员 |
| 「用 Thing 编辑器打开」(文件夹) | `HKCU\Software\Classes\Directory\shell\ThingEditor` | 同上 |
| 「用 Thing 编辑器打开」(目录背景) | `HKCU\Software\Classes\Directory\Background\shell\ThingEditor` | 同上 |
| 菜单图标 | 菜单项 `Icon` 值指向 exe(用 exe 自带图标) | — |
| 已运行时的二次启动 | `tauri-plugin-single-instance` 转交 argv 给已有实例 | 已落地 |
| 免注册表运行 | 设置页提供「注册 / 卸载右键菜单」按钮,并显示当前 exe 路径 | — |
**关键约束**:注册表条目里写的是**绝对 exe 路径**。
- 打包安装后:指向安装目录的 exe,稳定;
- `tauri dev` 下:指向 `target\debug\thing.exe`,一旦清理 target 就变成死链。
→ 因此**默认不注册**,且注册时校验 exe 存在;设置页在 dev 环境下给出明确提示。
### 3.7 全局快捷键
| 快捷键 | 动作 | 默认 |
|---|---|---|
| `Alt+E` | 打开编辑器窗口(无参数 = 上次的文档/最近文件) | **本版新增默认值** |
| `Ctrl+Shift+N` | 新建笔记(直接落库根) | 空(v1 已有实现,改为可配) |
两者都走 `shortcut.rs`,触发时只发事件、窗口由前端创建(v1 已确立的姿态)。
---
## 4. 存储、索引与目录树
```
{appData}/editor/ # 模块自身(与库解耦)
├── settings.json # 设置 + 最近文件/文件夹
├── editor.db # 笔记库索引(可重建)
└── library/ # 默认库根
├── notes/ assets/ templates/
└── .editor/ # 库内私有:同步基线 sync.json
```
- **配置文件全量走 `settings.json`**(v1 已如此),新增 `recentFiles` / `recentFolders` / `defaultEncoding` / `largeFileMb` / `contextMenuEnabled`。
- **索引服务架构不变**(单线程 worker 独占 `rusqlite` 连接 + 通道排队 + notify 监听),只改名。
- **目录树不进索引**:它是「看盘」而不是「管库」。目录树节点按需 `read_dir`(带缓存与手动刷新),深度上限与库树一致(24)。
- **配置改动只在用户显式操作下发生**:目录树上的新建/重命名/删除都是显式动作,且删除走系统回收站(复用 `quickpanel` 的回收站实现,`terminal/local_fs.rs` 已有先例)。**目录树自身不做任何隐式写入**(不生成索引、不生成元数据文件、不自动整理)。
---
## 5. 编码:探测、显示、切换
### 5.1 探测链(按优先级)
| 顺序 | 判据 | 结论 | 说明 |
|---|---|---|---|
| 1 | `EF BB BF` / `FF FE` / `FE FF` | `utf-8-bom` / `utf-16le` / `utf-16be` | BOM 是无歧义事实,直接采信 |
| 2 | `std::str::from_utf8` 通过 | `utf-8` | 结构性校验,不是统计猜测 |
| 3 | 以上失败 | `gb18030` | 中文存量主力(GBK 超集),比「猜 Big5/Shift_JIS」安全 |
| 4 | 用户手动指定 | 用户值 | 前三级都可能错,必须留人工兜底 |
**刻意不做**:字符频率统计 + 多编码自信度比较(chardet 式)。理由是它在短文本上比规则更不可靠,而本项目的主要场景(代码/配置/中文笔记)恰好都是「UTF-8 或 GB18030」二选一。真错了有第 4 级兜底,代价可控。
### 5.2 读取与状态
读文件时一次性回传:`content`(已解码 UTF-8 字符串 + 换行归一为 `\n`)、`encoding`(探测结果)、`eol`(`lf`/`crlf`)、`size`、`large`、`readonly`。
- 状态栏显示:`UTF-8` / `GB18030` / `UTF-8 BOM` + `CRLF` / `LF` + 只读标记。
- `readonly`:打开时用 `OpenOptions::new().write(true).open()` 探一次写权限(**不实际写入**),失败则置只读。这比「打开成功但保存时才报错」体验好得多。
- 编码名一律用 `terminal/encoding.rs` 的 `normalize()` 规范形态(`utf-8` / `gbk` / `gb18030` / `big5` / `shift_jis` / `euc-kr` / `latin1`),双端取值同源,避免「状态栏写 GBK、设置里叫 cp936」这种不一致。
### 5.3 切换编码(关键设计)
**核心约束:切换编码不是「重新解释缓冲区文本」,而是「换一种方式去解释磁盘字节」。**
- **切换时**:以磁盘当前字节(而非缓冲区文本)按新编码重新解码 → 替换缓冲区内容。
- 若此时有未保存改动:弹确认框给出三个选项——①**丢弃我的改动并按新编码重读**(默认,语义最清晰);②**先保存再重读**(用旧编码落盘,再按新编码读回——用户能立刻看出旧编码是否选错);③取消。
- **保存时**:按当前 `encoding` 编码写回。若目标编码无法表示缓冲区里的某些字符(例如把含 emoji 的文本存成 GBK),**保存前报错并列出无法表示的字符位置**,而不是静默替换成 `?`(静默替换 = 不可逆数据损坏)。
- **状态栏编码下拉**:`UTF-8` / `UTF-8 BOM` / `GB18030` / `GBK` / `Big5` / `Shift_JIS` / `EUC-KR` / `Latin-1` + 「重新载入为…」(不改变写回编码,仅重新解释)。
- **换行切换**:`LF` / `CRLF` 独立于编码(v1 已按读取值写回),状态栏可切换。
### 5.4 与终端模块的编码复用
`terminal/encoding.rs` 提供 `decode` / `encode` / `normalize` / `SUPPORTED` / `is_supported`(v1 已直接复用,未提取为公共模块 —— 它们是纯函数,无业务耦合;若将来第三个模块要用再提取)。
---
## 6. 界面结构
### 6.1 主模块页(设置与管理,不编辑)
Tab 收敛为 **概览 / 库 / 编辑器 / 集成**(把 v1 的「同步」并入「库」,因为同步是库的属性):
| Tab | 内容 |
|---|---|
| 概览 | 库状态横幅(路径/笔记数/索引)、最近文件与文件夹、快捷入口(打开编辑器 / 打开文件 / 打开文件夹 / 今日日记) |
| 库 | 库根切换、重建索引、导入导出、WebDAV(连接/方向/冲突/快照) |
| 编辑器 | 主题(含 JetBrains 三套)、字体字号行高连字、Live Preview 开关、默认编码、大文件阈值、自动保存、快捷键 |
| 集成 | 文件关联状态、**右键菜单注册/卸载**、exe 路径、单实例说明 |
### 6.2 编辑器窗口
```
┌─ 标题栏(自绘:文档名 + 未保存点 + 窗口按钮)────────────────────────┐
├─ 工具栏:保存 另存 打开 快速打开 | 格式化(.md 时) | 编码 换行 主题 ─┤
├────────────┬──────────────────────────────────────────┬─────────────┤
│ 侧栏 │ 标签页条:doc1 × | doc2 × | … │ 抽屉(可选) │
│ [库|目录| │ │ 大纲 / 双链 │
│ 检索|最近] │ 编辑器(CM6) │ │
│ │ │ │
│ 树 / 结果 │ │ │
├────────────┴──────────────────────────────────────────┴─────────────┤
│ 状态栏:保存态 · 字数/行数 · 行列 · 语言 · 编码 · 换行 · 路径 │
└─────────────────────────────────────────────────────────────────────┘
```
- 侧栏可整体折叠(腾出宽度给长行代码)。
- 抽屉默认关闭,`Ctrl+Shift+O` 切大纲、`Ctrl+Shift+B` 切双链。**这两个键位在实现时由 `keymap.ts` 统一声明并做冲突检测**:若与 CM6 默认键位冲突,以 CM6 默认键位优先,本功能改用 `Alt+O` / `Alt+B`(冲突检测方式沿用 v1 的 `shortcut.rs` 思路,编辑器内用 CM6 的 keymap 优先级)。
### 6.3 目录面板的命令面(P3-5 实现依据)
| 命令 | 入参 | 说明 |
|---|---|---|
| `editor_read_dir` | `path: String`(空 = 用户主目录) | 返回 `cwd` / `parent` / `entries`(名字/路径/是否目录/大小/mtime) |
| `editor_create_file` | `dir: String`, `name: String` | 重名报错(**不自动加序号**:目录树是用户的真实文件系统,静默改名会让人找不到刚建的文件) |
| `editor_create_folder` | `dir: String`, `name: String` | 同上 |
| `editor_rename_path` | `path: String`, `newName: String` | 同目录改名;目标存在则报错 |
| `editor_delete_path` | `paths: Vec<String>` | **走系统回收站**(复用 `quickpanel::commands::delete_file_impl`),返回 `(成功数, 失败明细)`;拒绝盘符根 |
| `editor_reveal_path` | `path: String` | 在资源管理器中选中(`opener` 的 `reveal_item_in_dir`) |
**安全边界**:目录树操作的是**用户真实文件系统**(不是沙箱),因此
- 不设「必须在本目录根下」的限制(那是本地文件管理器,限制根目录只会挡住用户自己);
- 但**拒绝删除盘符根**(`Path::new(p).parent().is_none()`)—— 这是唯一不可恢复的事故;
- 删除一律走回收站,不用 `remove_file`;
- 路径来自用户自己的浏览/输入,与 `terminal/local_fs.rs` 同一姿态(该模块已有 `list_dir` / `delete` 的成熟实现,**优先复用而不是重写**)。
---
## 7. 缺口清单(v1 已有 → v2 要做)
| # | 缺口 | 严重度 | 落点 |
|---|---|---|---|
| G1 | 模块仍叫 notes(id / 命令 / 事件 / 目录 / 存储键) | 高(结构性) | §9.6 |
| G2 | 没有「本地目录」导航根(只有笔记库) | 高 | §3.3 |
| G3 | 编码只能探测不能切换;无状态栏显示 | 高 | §5 |
| G4 | 没有最近文件夹记录(只有最近笔记,且存在 localStorage) | 中 | §3.5 |
| G5 | 没有资源管理器右键菜单 | 中 | §3.6 |
| G6 | 默认全局快捷键为空(`Alt+E` 未设) | 低 | §3.7 |
| G7 | 单窗口单文档(无标签页) | 中 | §3.1 |
| G8 | 大纲/双链挤在导航侧栏里,语义混杂 | 中 | §3.3 |
| G9 | 大文件降级没有「只读打开」与显式提示 | 低 | §3.1 / §5.2 |
| G10 | 主模块页 Tab 结构未随定位调整(同步应并入库) | 低 | §6.1 |
| G11 | 语言包缺 `.sh`/`.ps1`/`.toml`/`.ini`/`.scss`(legacy-modes 未接) | 低 | §8-P5.1 |
| G12 | Markdown 内嵌代码块高亮未做(`codeLanguages` 异步问题) | 低 | §8-P5.3 |
| G13 | `FileDoc` 无 `readonly` 字段(只读文件要等保存时才报错) | 中 | §5.2 / P4-1 |
---
## 8. 分期路线图
> v1 的 P0/P1/P2 已全部落地(见 §9)。以下是从 **P3 起**的新路线图。
### P3 — 编辑器化改造(结构)
1. **改名**:`notes` → `editor`(id / 窗口 label / 事件 / 命令前缀 / 目录 / 存储键 / Rust 模块名),脚本核对无残留(§9.6)。
2. **库内目录改名**:`<库根>/.notes/` → `<库根>/.editor/`(含 `sync.json`),首次打开时惰性迁移;索引可重建,丢了无损。
3. **侧栏重构**:`库 / 目录 / 检索 / 最近` 四段;大纲与双链移到编辑区右侧抽屉。
4. **本地目录树**:打开文件夹(对话框 / 右键菜单 / 最近文件夹)、树浏览、文件名过滤、打开文件、在资源管理器中显示、复制路径、手动刷新。
5. **最近记录**:最近文件 + 最近文件夹(落 `settings.json`,分组显示、可清空、失效项灰显)。
6. **主模块页 Tab 调整**:概览 / 库 / 编辑器 / 集成。
### P4 — 编码与系统集成(这一版的核心价值)
1. **编码探测链**(§5.1)+ 状态栏显示编码/换行/只读。
2. **切换编码**(§5.3):重解码对话框三选项、保存时不可表示字符报错、换行独立切换。
3. **系统集成**:`Alt+E` 默认值;HKCU 右键菜单注册/卸载(文件 + 文件夹 + 目录背景),设置页按钮 + exe 路径显示 + dev 环境提示。
4. **只读打开**与大文件降级提示。
5. **标签页**(多文档):`Ctrl+W` / `Ctrl+Tab`、每标签独立编码与视图模式、关闭确认。
### P5 — 完善(本轮不做,按体感排后续优先级)
1. 语言包补齐:`.sh` / `.ps1` / `.toml` / `.ini` / `.dockerfile` 走 `legacy-modes`;`.scss` / `.less` 引入 `@codemirror/lang-sass`。
2. 目录树上的文件操作完善:拖拽移动、在新窗口打开、批量重命名。
3. Markdown 内嵌代码块高亮(`codeLanguages`,需解决 language-data 异步 vs `markdown()` 同步)。
4. 双链图谱(数据已就绪:`editor_link_graph` 命令可用,仅缺可视化)。
5. 会话恢复:关窗后重开恢复文档与光标位置。
---
## 9. v1 实施记录(压缩归档)
> 完整细节已在 v1 文档中,此处只留**结论**与**坑**——它们对 v2 仍然成立。
> **本节的文件名一律是 v2 目标名**。v1 代码里对应的真实路径是:
> `src-tauri/src/notes/*.rs`、`src/modules/notes/**`、`src/stores/notesStore.ts`、
> `src/types/notes.ts`,命令为 `notes_*`。
### 9.1 交付总览(v1,均已落地)
| 层 | 关键文件 |
|---|---|
| Rust 文件 IO | `editor/files.rs`(编码/换行探测、授权白名单、附件落盘) |
| Rust 库 | `editor/library.rs`(`safe_join` 路径沙箱、扫描、增删改移) |
| Rust 模板 | `editor/templates.rs`(4 个内置模板 + 库内覆盖 + `{{title}}`/`{{date}}`) |
| Rust 导入导出 | `editor/import.rs`(文件/目录/zip,重名加序号、绝不覆盖)、`editor/export.rs`(整库/单目录 zip) |
| Rust 索引 | `editor/index.rs`(SQLite + FTS5 trigram:front-matter、标签、双链、检索、片段)、`editor/index_service.rs`(单线程 worker + notify) |
| Rust WebDAV | `editor/webdav/{client,sync}.rs`(PROPFIND/MKCOL/PUT/GET/DELETE/MOVE + 三方比对 + 冲突策略 + 改名识别)、`editor/backup.rs`(zip 快照 + 轮转 + 恢复) |
| Rust 参数 | `editor/args.rs`(文件关联/命令行参数解析 + 待打开文件缓存) |
| 前端内核 | `editor/core.ts`(Compartment 热重配置)、`markdownLivePreview.ts`、`languages.ts`、`themes.ts`、`keymap.ts`、`outline.ts`、`wikilink.ts`、`images.ts`、`markdownExport.ts` |
| 前端组件 | `LibrarySidebar.vue`、`SearchPanel.vue`、`QuickOpen.vue`、`MarkdownOutline.vue`、`BacklinksPanel.vue`、`WebdavPanel.vue`、`ImportExportPanel.vue`、`NewNoteDialog.vue`、`EditorHost.vue`、`EditorToolbar.vue` |
| 前端状态 | `stores/editorStore.ts`、`modules/editor/editorClient.ts`、`types/editor.ts` |
| 命令 | 40 条(`notes_*` → 将统一改名为 `editor_*`) |
### 9.2 关键决策(v2 继续沿用)
- **真相是文件,索引可丢**:删掉 `editor.db` 的唯一后果是下次搜索前做一次全量扫描。
- **索引由单线程 worker 独占**:`rusqlite::Connection` 非共享对象,而搜索命令(Tauri 线程池)、保存后的增量更新、notify 回调会并发进来;通道排队 + 专职线程换来「慢操作只排队不堵搜索」。
- **FTS5 用 trigram**:默认 `unicode61` 把连续汉字切成一个词元,「会议」搜不到「周会议纪要」。代价是查询词 <3 字符静默返回空 → 回退 `LIKE` + Rust 侧自建片段。
- **WebDAV 同步基线存两侧指纹**,不比 mtime(跨机时钟偏差会让「本地比远端新」两边都成立)。删除传播保守优先;同步有失败不推进基线。
- **冲突「两侧都留」用远端 `MOVE`** 保留历史,而不是覆盖。
- **同步/网络类命令一律 `async` + `spawn_blocking`**:`reqwest::blocking` 在 tokio 运行时线程上会 panic。
- **HTML 导出零外链、失败关闭**:样式内联;DOMPurify 不可用时返回**空串**而不是原文。
- **渲染链路按需 `import()`**:`markdownExport`(markdown-it + DOMPurify + highlight.js)约 1.1MB,静态引入会让模块 chunk 从 40kB 涨到 1.2MB。
- **库外文件的路径授权白名单**:库内走 `safe_join`(根目录沙箱),库外走「用户显式打开过的绝对路径集合」。读宽松(读时登记),写严格。
- **`from`(大纲)一律是行首偏移**:指向正文起点会让空标题没有合法取值。
- **Live Preview 是装饰不是渲染**:只对 `view.visibleRanges` 计算(性能红线);光标行「显形」为可编辑源码。
### 9.3 验证状态(v1 收尾时)
```
cargo check 0 warning
cargo build 整包通过
cargo test --lib 58 passed / 0 failed
node --test 74 passed / 0 failed / 1 skipped(Node 无 DOM 的 XSS 断言)
vue-tsc / eslint 通过
vite build NotesModule 41kB(gzip 12.5) / NotesWindow 98kB(gzip 32.6)
/ markdownExport 1.12MB(gzip 371) 按需加载
接线核对 命令 定义=导出=注册 40/40/40,无差集
事件 Rust 8 = TS 8,无差集
类型 18 个结构字段名双端一一对应
```
### 9.4 坑记录(跨版本有效)
1. **`<SelectItem>` 不能用空串 `value`**:reka-ui 把空串保留给 placeholder,会直接抛异常。用显式哨兵值(`'__all__'` / `'__current__'`)在调用点翻译。报错栈指向 `SelectItem.vue` 而不是调用方 —— 先搜 `value: ''`。
2. **`cargo add <tauri 插件>` 会连带升级整个 tauri 依赖树**(wry / tray-icon / window-vibrancy),而 dev 启动会校验 JS 包与 crate 的 minor 是否一致。**改一边必须同时看另一边**。
3. **不要把 `package.json` 交给 PowerShell 的 `Set-Content -Encoding UTF8`**(PS 5.1 写入 BOM),带 BOM 会让 Vite 读 PostCSS 配置直接失败。用 `node -e` 或 `UTF8Encoding($false)`。
4. **CRLF 下反推行首偏移一律偏 1**:必须预先算 `lineStarts` 表,不要在循环里「减回去」。
5. **front-matter 用状态机而不是布尔量**:首行 `---` 是*开头*,布尔量会在第 0 行就关掉状态,导致第 2 行的闭合 `---` 把上一行元数据提升成 Setext 标题。
6. **`let plan = plan(...)` 会遮蔽函数名**,第二个测试起报 `E0618` 且位置离成因很远。函数名避开返回值名。
7. **`enum` 不能出现在 `node --test` 直接跑的文件里**(Node 的 TS 支持是 strip-only)。用 `const X = {...} as const` + 类型别名。
8. **quick-xml 0.42 的 `QName::as_ref()` 返回 `&str`**(旧版 `&[u8]`),`BytesText` 无 `decode()`;升级时只 `cargo update -p quick-xml`,避免动到 wry 链。
9. **冷启动的文件关联事件会丢**:`setup` 里 `emit` 时 WebView 还没加载。改为存 `OnceLock<Mutex<Option<PathBuf>>>`,前端注册完监听后主动取走。
10. **FTS5 的 `snippet()` 对「走 LIKE 回退的短词」什么都不产出**;列索引用 `-1`(让 FTS 挑最佳列)。
### 9.5 与 v1 规划不一致之处(保留结论)
| 规划 | 实际 | 原因 |
|---|---|---|
| 语言支持走 `language-data` 一处入口 | 手写扩展名映射表 + 逐语言 `import()` | `matchFilename` 覆盖不到 `.vue`/`.toml`/`.ps1`;手写表行为可预期 |
| Markdown 内嵌代码块高亮 | 未做 | language-data 清单异步 vs `markdown()` 同步(见 G12) |
| `.scss` / `.less` | 未做 | `@codemirror/lang-css` 只导出 `css()` |
| 表格渲染 / 图片内联 | **已做**(图片走 data URL,非 asset 协议) | asset 协议要求把用户自选库根加进白名单,等于给 WebView 开任意读文件的口子 |
| 提取 `terminal/encoding.rs` 为公共模块 | 未提取,直接复用 | 纯函数无耦合;第三个模块要用时再提取 |
| 系统关联 | 已做文件关联;**右键菜单本轮补** | §3.6 |
| 双链图谱 / 托盘入口 / Mermaid | 未做 | §8-P5 / §0.8 |
### 9.6 改名清单(P3 的执行依据)
| 面 | v1 | v2 | 规模 |
|---|---|---|---|
| 模块 id / 目录 | `notes` / `src/modules/notes/` | `editor` / `src/modules/editor/` | 10 处 |
| 窗口 hash / label 前缀 | `#notes-window` / `notes-window-*` | `#editor-window` / `editor-window-*` | 16 处 + capability 文件名 |
| 事件名 | `notes-settings` 等 8 个 | `editor-*` | 4 处(双端一致) |
| Rust 命令前缀 | `notes_*`(40 条) | `editor_*` | 246 行 |
| Rust 模块目录 | `src-tauri/src/notes/` | `src-tauri/src/editor/` | 18 处 |
| store / client / types | `notesStore` / `notesClient` / `types/notes.ts` | `editorStore` / `editorClient` / `types/editor.ts` | 77 处 |
| localStorage 键 | `thing_notes_recent` | 改为落 `settings.json`(不再用 localStorage) | 1 处 |
| capability 文件 | `notes-window.json` | `editor-window.json` | 1 文件 |
| 默认库目录 | `{appData}/notes/library` | `{appData}/editor/library` | 需迁移逻辑(见下) |
**迁移策略**:`{appData}/notes/` 若存在且 `{appData}/editor/` 不存在 → 启动时整目录重命名并记日志;否则各自独立。库内 `.notes/`(索引 + 同步基线)同理改 `.editor/`,并在首次打开时惰性迁移(索引可重建,丢了也无损)。
---
## 10. 决策表(已拍板,开工时按此执行)
> Q1–Q4 由用户于 2026-09-30 明确拍板;Q5–Q10 由本规划给出建议并**一并视为生效**(若要改,改这一行即可,不影响其它章节)。
| # | 决策点 | 结论 | 影响面 |
|---|---|---|---|
| Q1 | 模块显示名与英文 id | **`id = editor`,显示名「编辑器」**(一词式,与「终端」「下载」一致) | 模块注册、窗口标题、搜索项、改名清单 §9.6 |
| Q2 | 是否引入「工作区」 | **不引入**。只有「笔记库根」与「当前目录根」两个单值 + 各自历史 | §3.3 侧栏只有一个目录面板;ST-4 无需 workspace 状态 |
| Q3 | 目录树是否纳入索引 | **不纳入**。目录树只做文件名过滤;全文检索仅对笔记库可用(FTS5) | §3.4 / §4;`editor_index_*` 只处理库内 `.md` |
| Q4 | 标签页放哪一期 | **P4**(与编码、系统集成同期) | §8-P4.5;`EditorHost` 需支持多 view 实例 |
| Q5 | 右键菜单注册时机 | **设置页手动按钮**,默认不写注册表 | §3.6;dev 环境 exe 路径不稳定 |
| Q6 | 目录树删除语义 | **走系统回收站**(复用 `quickpanel` 实现) | §4;与 `terminal/local_fs.rs` 同口径 |
| Q7 | 默认编码兜底 | **`GB18030`**(探测链第 3 级) | §5.1;第 4 级人工指定兜底 |
| Q8 | 「笔记库」这一叫法 | **保留**(库内文件仍是笔记,用户已理解该词) | §3.3 面板名「笔记库」 |
| Q9 | 主模块页是否给「打开文件夹」入口 | **给** | §6.1 概览页行动区 |
| Q10 | 大文件阈值 | **5MB 默认,可配**,且状态栏显式提示降级 | §3.1;`largeFileMb` 进设置 |
---
## 11. 开工清单(执行入口)
> 本节是「照做即可」的清单。**P3 与 P4 之间没有依赖倒置**:P3 是结构改造(改名 + 侧栏 + 目录树 + 最近记录),P4 是能力新增(编码 + 系统集成 + 标签页)。建议**严格 P3 → P4**:改名会碰到 P4 要改的每一个文件,同时做会让 diff 无法 review。
### 11.1 定稿参数(实现时直接用这些值,不要再另起炉灶)
| 项 | 值 |
|---|---|
| 模块 id / 显示名 / 图标 key | `editor` / `编辑器` / `editor`(`icons.ts` 映射到 `FileCode2` 或 `NotebookPen`,见下) |
| 模块排序 `order` | **45**(沿用,排在终端 40 之后) |
| 窗口 hash / label 前缀 | `#editor-window` / `editor-window-` |
| 窗口查询参数 | `?file=<绝对路径>` / `?note=<库内相对路径>` / `?folder=<绝对路径>` |
| Tauri 命令前缀 | `editor_`(40 条现有命令全部平移,P4 新增约 12 条) |
| 事件名(8 个) | `editor-settings` / `editor-library-changed` / `editor-file-changed` / `editor-sync-progress` / `editor-new-note` / `editor-open-editor` / `editor-open-file` / `editor-open-folder`(最后一个是 P4 新增) |
| Rust 模块目录 | `src-tauri/src/editor/` |
| 前端目录 | `src/modules/editor/` |
| store / client / types | `useEditorStore` / `src/modules/editor/editorClient.ts` / `src/types/editor.ts` |
| 模块自身目录 | `{appData}/editor/`(settings.json / editor.db / library/) |
| 库内私有目录 | `<库根>/.editor/`(`sync.json`) |
| keyring 键 | `editor.webdav.password` |
| 默认全局快捷键 | 打开编辑器 = **`Alt+E`**;新建笔记 = 空(可配) |
| 默认库根 | `{appData}/editor/library` |
| 默认编码 / 大文件阈值 | `UTF-8` 优先探测,兜底 `GB18030`;5MB |
| 右键菜单键名 | `HKCU\Software\Classes\{*,Directory,Directory\Background}\shell\ThingEditor`,显示名 **「用 Thing 编辑器打开」** |
| 图标 key / 组件 | key = `editor`;组件 **`FileCode2`**(已确认 `@lucide/vue` 有该图标;备选 `SquarePen` / `FileCode`)。侧栏新面板建议:目录 = `FolderTree`、最近 = `History`、抽屉 = `PanelRight` |
### 11.2 P3 执行顺序(每步都可独立验证 + 可提交)
| 步 | 内容 | 验证 |
|---|---|---|
| **P3-1** | 改名:Rust 侧(模块目录 `notes/` → `editor/`、40 条命令 `notes_*` → `editor_*`、`NoteSettings` → `EditorSettings` 等类型名、事件常量) | `cargo check` 0 warning;`cargo test --lib editor::` 58 passed |
| **P3-2** | 改名:前端侧(`src/modules/notes/` → `editor/`、`notesStore` → `editorStore`、`notesClient` → `editorClient`、`types/notes.ts` → `editor.ts`、`STORAGE_KEYS`、`main.ts` 路由、capability 文件名与 `windows` glob、模块注册与图标) | `vue-tsc` / `eslint` / `vite build` 通过;模块列表里显示「编辑器」 |
| **P3-3** | 迁移:`{appData}/notes/` → `{appData}/editor/`(启动时整目录 rename,幂等);`<库根>/.notes/` → `.editor/`(惰性,`ensure_schema` 时探测并 rename) | 手工验证:改名前留下的库仍能被打开、索引被重建 |
| **P3-4** | 侧栏重构为 `库 / 目录 / 检索 / 最近` 四段;大纲与双链移到右侧抽屉 | 四段可切换;抽屉快捷键生效 |
| **P3-5** | 本地目录树:Rust `editor_read_dir` / `editor_create_file` / `editor_create_folder` / `editor_rename_path` / `editor_delete_path`(回收站)+ 前端 `DirectoryPanel.vue` | 能浏览、新建、重命名、删除(进回收站)、在资源管理器中显示 |
| **P3-6** | 最近记录:`recentFiles` / `recentFolders` 落 `settings.json`,`RecentPanel.vue`,失效项灰显 + 清空 | 打开文件/文件夹后出现在「最近」,重启后仍在 |
| **P3-7** | 主模块页 Tab → 概览 / 库 / 编辑器 / 集成(同步并入库页) | 四页可切换,入口按钮就位 |
**P3 完成判据**:模块叫「编辑器」、侧栏有库与目录两个根、最近记录可用、`cargo test` 与 `node --test` 全绿、`vite build` 通过且模块 chunk 无异常膨胀。
### 11.3 P4 执行顺序
| 步 | 内容 | 验证 |
|---|---|---|
| **P4-1** | `FileDoc` 增 `readonly`;`files.rs` 增写权限探测(`OpenOptions::new().write(true).open()` 不写入) | 只读文件打开后状态栏显示「只读」,保存被拦并给出原因 |
| **P4-2** | 编码探测链按 §5.1 收紧(BOM → 严格 UTF-8 → GB18030);新增 `editor_redecode_file(path, encoding)` | Rust 单测覆盖 BOM/UTF-8/GBK/UTF-16 |
| **P4-3** | 状态栏编码与本行下拉 + 切换编码三选项对话框(§5.3)+ 保存时不可表示字符报错 | 手工:GBK 文件切 UTF-8 看到乱码→切回正常;含 emoji 存 GBK 被拦 |
| **P4-4** | 系统集成:`Alt+E` 默认值;右键菜单注册/卸载(`winreg`,HKCU)+ 设置页「集成」Tab | 注册后资源管理器右键出现菜单项,点击能打开文件/文件夹 |
| **P4-5** | 标签页(多文档):`Ctrl+W` / `Ctrl+Tab`、每标签独立 `encoding`/`eol`/视图模式、关闭确认 | 同时开 3 个不同编码的文件,互不串味 |
**P4 完成判据**:编码可探测可切换、右键菜单可用、`Alt+E` 生效、多标签可用;§9.3 的全部检查项重新跑一遍通过。
### 11.4 每个阶段都要跑的验证命令
```powershell
# Rust
& "C:\Users\<user>\.cargo\bin\cargo.exe" check --message-format short # 必须 0 warning
& "C:\Users\<user>\.cargo\bin\cargo.exe" test --lib editor:: # 单测(P3-1 后模块名变了)
# 前端
& "C:\Program Files\nodejs\node.exe" node_modules/vue-tsc/bin/vue-tsc.js --noEmit
& "C:\Program Files\nodejs\node.exe" node_modules/eslint/bin/eslint.js src
& "C:\Program Files\nodejs\node.exe" node_modules/vite/bin/vite.js build
& "C:\Program Files\nodejs\node.exe" --test src/modules/quickpanel/engine.test.ts src/lib/calc.test.ts src/lib/theme.test.ts src/modules/editor/editor/outline.test.ts
```
> 注意:本机沙箱禁止直接 spawn 工作区外的可执行文件,必须用**绝对路径**调用
> `cargo.exe` / `node.exe`(`node` 在 `C:\Program Files\nodejs\`)。
> 新增依赖用 `bun add`,且 `$env:TEMP` 必须指向可写目录(详见 §9.4 的坑记录)。
### 11.5 改名核对脚本(P3-1/P3-2 完成后跑)
```powershell
# 应无输出(除文档与 §9 的历史记录外)
Select-String -Path (Get-ChildItem src,src-tauri/src,src-tauri/capabilities -Recurse -Include *.ts,*.vue,*.rs,*.json |
ForEach-Object { $_.FullName }) -Pattern "notes_" | ForEach-Object { "$($_.Path):$($_.LineNumber)" }
Select-String -Path (Get-ChildItem src -Recurse -Include *.ts,*.vue |
ForEach-Object { $_.FullName }) -Pattern "notesStore|notesClient" | ForEach-Object { "$($_.Path):$($_.LineNumber)" }
# 命令三方一致性(应 定义 = 导出 = 注册)
# 见 §9.3 的接线核对做法:比对 commands.rs / mod.rs / lib.rs 两处
```
---
## 附录 A:命名规范(v2)
- 模块 id:`editor`;显示名:`编辑器`;图标 key:`editor`。
- 窗口 hash:`#editor-window`(可带 `?file=<abs path>` 或 `?note=<rel path>`);label 前缀:`editor-window`。
- 事件名(**8 个**,与 v1 一一对应,最后一个为 P4 新增):`editor-settings` / `editor-library-changed` / `editor-file-changed` / `editor-sync-progress` / `editor-new-note` / `editor-open-editor` / `editor-open-file` / `editor-open-folder`。
- 窗口 label 前缀:`editor-window-`(不是事件,列在此处避免与上表混淆)。
- 前端组件:`DirectoryPanel.vue` / `RecentPanel.vue` / `EditorTabs.vue`(P4)/ `DrawerPanel.vue`(大纲与双链的容器)为 P3/P4 新增。
- Rust 命令前缀:`editor_`;Rust 模块目录:`src-tauri/src/editor/`。
- 前端 store:`useEditorStore`;类型文件:`src/types/editor.ts`;IPC 客户端:`src/modules/editor/editorClient.ts`。
- 存储:`{appData}/editor/settings.json`;库内私有目录:`<库根>/.editor/`。
- keyring 键:`editor.webdav.password`。
## 附录 B:能力边界(明确不做)
| 不做 | 理由 |
|---|---|
| 调试器 / 内嵌终端 / LSP 补全 / Git 集成 | 那是 IDE,与「notepad++ 式编辑器」的定位冲突;本项目终端模块已覆盖终端场景 |
| 块编辑器(拖拽块、`/` 菜单) | 与「`.md` 文本是唯一真相」的模型不匹配(v1 已确认) |
| 远端直连读写(把 WebDAV 当工作区) | 离线不可用、限流敏感、冲突面大(v1 已确认) |
| 目录树全文索引 | 与「打开快」冲突(Q3) |
| 字符频率统计式编码探测 | 短文本上比规则更不可靠(§5.1) |
| 二进制文件编辑 | 编码/换行模型只对文本成立;识别为二进制时明确拒绝并提示用外部工具 |
+667
View File
@@ -0,0 +1,667 @@
# 音乐模块 · 本地音乐解密规划(Music Decrypt Plan)
> 状态:**P0 + P1a + P1c 已实施并完成真机端到端验证**(2026-09-27:网易云解密 + QQ音乐离线解密 + 文件夹批量 + musicex 在线取密钥,用真实 192kHz/24bit `.mflac` 样本跑通全链路;Rust 单测 204 项全库通过)
> 定位:音乐模块的「本地解密」子能力,不是独立模块——挂靠 `music` 模块新增「解密」页签,Rust 侧新增 `music/decrypt/` 子模块;`ncm` 与 `qmc` 均为纯 Rust 离线引擎,QQ 按「内嵌 ekey 离线 → musicex 在线取密钥」分层(Frida 降为 P2 兜底)
> 日期:2026-09-27(同日修订:QQ 分层重排、ncm 算法细节补全)
> 关联文档:`AI_DEV_GUIDE.md`(模块注册 / IPC 范式——注意 specta 绑定见 `lib.rs` 的 `export_bindings()`)、`MUSIC_REMOTE_PLAN.md`(规划文档范式)
> 参考项目与**许可分档**:
> - `taurusxin/ncmdump`(<https://github.com/taurusxin/ncmdump>,**MIT**)——§3.1 全部算法细节的对照物,**可逐行对照**。
> - `QQKWKG-TriMusicDecrypt`(QKKDecrypt,<https://github.com/Acooldog/QQKWKG-TriMusicDecrypt>,**GPLv3**)——只取平台矩阵与坑清单。
> - `ownlight6/qmc-decoder`(<https://github.com/ownlight6/qmc-decoder>,**GPLv3**)——只取 QMC/musicex/ekey 的**格式与协议知识**(<https://github.com/ownlight6/qmc-decoder/blob/main/MGG_DECRYPTION_FLOW.md>)。
> - GPLv3 两仓:**只读文档与行为,严禁抄代码**。
---
## 0. 结论先行
1. **范围收敛到两平台**(本轮显式指定):网易云 `.ncm` + QQ音乐 QMC 系列。酷狗/酷我明确出栈,不进任何分期。
2. **两条技术路线,全部纯 Rust,零新增运行时依赖**:
- ncm → **Rust 原生**(`aes 0.8` / `cbc 0.1` / `base64 0.22` 已在依赖;`ecb` crate 不在依赖树,ECB 手写 16 字节块循环,零新增 crate)。
- QQ → **Rust 原生三层路由**(详见 §3.2):① 尾部内嵌 ekey 的文件纯离线可解;② musicex 文件读本机凭据调 `GetEVkey` API;③ 前两层都不成立才用 Frida 注入兜底。
- **本节原有的「Frida 主链」判断已作废**:它把「需要客户端在跑」与「需要 Frida 注入」绑成了一件事。实际只有第③层需要注入,而前两层覆盖绝大多数真实文件。改分层后**不再需要便携 Python、不再需要 `pip install frida`、不再受杀软与 mangled 符号版本漂移影响**。
3. **UI 是音乐模块第 4 个页签「解密」**:`useModuleTabs` 加一项 + `DecryptPanel.vue` + 独立轻量 store,命令与事件挂进现有 music 命令族,完全照抄下载任务的「先回 taskId、进度走事件」范式。
4. **许可边界分三档**:`ncmdump` 是 MIT,**可逐行对照**;QKKDecrypt 与 `qmc-decoder` 是 GPLv3 + FFmpeg GPL,**只沉淀格式/协议知识与坑清单,实现逐行重写**。
5. **工作量**:P0(网易云 + 页签全链路)约 **2 个工作日**;P1a(QQ 离线 + API,纯 Rust)约 **2~3 个工作日**;P1b(Frida 兜底,按需)另计。
```mermaid
flowchart LR
subgraph FE["前端 · 解密页签"]
A["DecryptPanel.vue<br/>文件选择 / 任务列表 / 状态卡"]
S["decryptStore.ts<br/>任务状态 + 事件监听"]
end
subgraph R["Rust · music/decrypt/"]
C["commands.rs<br/>run / cancel"]
N["ncm.rs<br/>网易云离线引擎"]
Q["qq.rs<br/>QMC 三层路由(P1)"]
end
subgraph QQS["QQ 三层(P1)"]
L1["① 尾部内嵌 ekey<br/>纯离线"]
L2["② musicex → 本机凭据<br/>GetEVkey API"]
L3["③ Frida 兜底<br/>(P1b,按需)"]
end
O["savedir/decrypted/"]
A --> S --> C
C --> N --> O
C --> Q --> L1 --> O
Q --> L2 --> O
Q -.-> L3 -.-> O
Q -.->|"music-decrypt-event"| S
N -.-> S
```
---
## 1. 需求解构
| 用户原话 | 解构 | 落点 |
|---|---|---|
| 在音乐模块添加解密 Tabs | 音乐模块第 4 个页签 | §5.2 |
| 解密各平台的加密格式 | 收敛为 QQ音乐 + 网易云(本轮显式指定) | §3 |
| 最小路径实现 | 砍掉:转码、元数据回填、封面提取、拖拽、酷狗酷我、并发调优、历史持久化 | §7 P2 清单 |
| 可参考 QKKDecrypt | 对齐思路与坑,不搬 GPLv3 代码 | §3.3 |
---
## 2. 现状勘察(2026-09-27 从仓库实际读取)
### 2.1 已具备的基建(直接复用)
| 能力 | 现有实现 | 复用方式 |
|---|---|---|
| Tab 体系 | `useModuleTabs`(`MusicModule.vue:78`,alwaysVisible 模式,标题栏浮动切换器自动接管) | 加 `{ value: 'decrypt', label: '解密' }` 一项 |
| 任务 + 事件范式 | `music_download` / `music-download-event`(`commands.rs:187`、`constants.rs:107`) | 解密照抄:先回 taskId,进度推事件 |
| 便携 Python + pip 镜像 | `runtime.rs`(清华源 `PIP_INDEX_URL`,`mod.rs:77`) | QQ sidecar 的 frida 安装、Python 就绪检查 |
| 加密依赖 | `Cargo.toml` 已有 `aes = "0.8"`、`cbc = "0.1"`、`base64 = "0.22"` | ncm 的 AES-128-ECB 手写循环,零新增依赖 |
| specta 绑定 | `lib.rs export_bindings()` 两处 `collect_commands!` | 新命令两处同步登记(`lib.rs:300` 注释明确要求) |
| 文件选择对话框 | `@tauri-apps/plugin-dialog`(`MusicModule.vue:4` 已 import) | 页签内直接用,不加 Rust 命令 |
| 输出目录 | 默认 `savedir`(设置页「本地下载目录」) | 解密默认输出 `savedir/decrypted/` |
| 播放引擎 | symphonia(`Cargo.toml:115`) | 解出的 flac/mp3/ogg 可直接进曲库试听 |
### 2.2 关键缺口(需新增)
| 缺口 | 说明 |
|---|---|
| ncm 解密实现 | 纯算法,约 200 行 + 单测 |
| QQ 运行期 sidecar | Frida 注入 + `EncAndDesMediaFile` 调用序列,按参考思路重写 |
| 解密任务 store | 下载任务在 `musicStore`;解密需独立轻量 store(页签切换会卸载组件,监听器必须挂 store) |
| frida 依赖安装 | `pip install frida`(wheel 带原生扩展,走现有镜像),需一条安装命令 + 进度事件 |
---
## 3. 技术选型
### 3.1 网易云 `.ncm`:Rust 原生离线
**为什么不进 Python**:
- ncm 是纯文件级算法,不需要任何进程配合;塞进 Python 等于把 200 行算法绑上「必须先装运行时」的前置。
- 便携 Python 是按需安装(musicdl 才触发),解密不应被它卡住——Rust 路线开箱即用。
- Rust 侧可直接 `cargo test`,对照样本文件做回归。
**算法要点**(对照 MIT 协议的 `ncmdump`(`src/ncmcrypt.cpp`)逐条独立重写。下面每一条都是**会写错的地方**,不是梗概):
**① 容器结构**
```
0x00 magic 8B "CTENFDAM"(即 43 54 45 4E 46 44 41 4D)
0x08 2B 0x02 0x00 → 跳过
0x0A key_len 4B LE
0x0E key_data key_len B (XOR 0x64 → AES-128-ECB → 得 RC4 密钥盒种子)
... meta_len 4B LE
... meta_data meta_len B (XOR 0x63 → 去 22B 前缀 → base64 → AES-128-ECB → 去 6B 前缀 → JSON)
... 5B 跳过(CRC32 4B + 图片版本 1B)
... cover_len 4B LE
... img_len 4B LE
... img_data img_len B (内嵌封面:PNG 或 JPEG)
... 跳 cover_len - img_len
... audio 剩余全部 (改性 RC4)
```
**② 两个 XOR 常量不同**(原文档误合并成一个 `0x64`)
| 段 | XOR 常量 | 加密方式 | 解密后处理 |
|---|---|---|---|
| key 段 | `0x64` | AES-128-ECB | **跳过前 17 字节**(`neteasecloudmusic`),其余即 RC4 密钥盒种子 |
| meta 段 | `0x63` | AES-128-ECB(先 base64 解码) | 跳过前 6 字节(`music:`),其余为 JSON |
**③ AES-128-ECB 解密**:**key 段与 meta 段用两个不同的 16 字节密钥**——`sCoreKey` = ASCII `neteasecloudmusi`(即 17 字节前缀 `neteasecloudmusic\0` 的前 16 字节)、`sModifyKey` = ASCII `#14ljk_!\]&0U<'(`。**收尾不是"去前缀",而是 PKCS#7 风格 padding**:逐 16 字节块解密,最后一字节即 padding 长度(`> 16` 时视作 0),去掉 padding 后再手动跳前缀。
> 易错点:**「AES 密钥」与「要剥掉的前缀」是两个东西**。`neteasecloudmusic` 既是被剥的 17 字节前缀(含结尾 NUL),其前 16 字节又是 key 段的 AES 密钥;meta 段则两者都不同。混用不报错、只会全解错(实现里分别命名为 `CORE_KEY` / `CORE_AES_KEY` / `MODIFY_KEY`)。
**④ meta 段的两层前缀**:原始数据前 22 字节是字面量 `163 key(Don't modify):`,**先剥掉它**,再对余下部分 base64 解码,才喂给 AES。
**⑤ 音频段是「改性 RC4」**
- 密钥盒用参考实现的 KSA:`swap = keybox[i]`;`c = (swap + last_byte + key[key_offset]) & 0xff`,`key_offset` 触 keyLen 归零循环取 key,`keybox[i] = keybox[c]`、`keybox[c] = swap`、`last_byte = c`。**照抄即可,但注意 `last_byte` 在模 256 下是恒等变形(结果与标准 RC4 逐字节相同),它既不是"关键差异",也不能作为验证手段**——见 §6.25。
- 明文按 `0x8000` 字节一块循环,块内 `j = (i + 1) & 0xff`,`plain[i] = cipher[i] ^ keybox[(keybox[(keybox[j] + j) & 0xff] + keybox[j]) & 0xff]`。块之间不重置密钥盒、也不额外跳字节——`i` 是块内下标。
- **块边界必须由"读满一块"确定**(`read_full`),不能用 `Read::read` 的短读结果,否则相位错位、中途变噪声(§6.24)。
- **不存在"每 0x8000 字节后跳过 5 字节间隔"**(原文档此条有误)。`0x8000` 是块大小,`5` 是 §① 里跳过的 CRC32 + 图片版本。
**⑥ 输出扩展名由音频首帧魔数决定,不是 meta 的 `format` 字段**(原文档此条说反了):首个解密块以 `ID3`(`0x49 0x44 0x33`)开头 → `.mp3`,否则 → `.flac`。meta 的 `format` 只用于另一件事——**判断该不该回填标签/封面时的格式分支**。
**⑦ 顺手可得的元数据**:meta JSON 含 `musicName` / `artist`(二维数组,取每项第 0 个元素并用 `/` 连接)/ `album` / `bitrate` / `duration`,且封面字节已在上面的 `img_data` 里读出。**P0 已实现封面单独落盘**(`<歌名>.cover.png|jpg`,按魔数定扩展名);**写进音频标签**仍留 P2——那需要 `lofty` 且要按 mp3/flac/m4a 分派容器,属于「增强」而非「能播」。
**⑧ 失败处理**:魔数不符 / `key_len <= 0` / 块不足 16 字节 → 返回可读错误(`Err(String)`),**per-file 失败不 panic、不中断整批**。
### 3.2 QQ音乐:Rust 原生三层路由(**本节已重写**)
**原判断作废的理由**:原文把「需要 QQ 客户端在跑」与「需要 Frida 注入」绑成了一件事。二者其实独立——ekey(解密密钥)有三种存储形态,只有第三种才需要注入。前两层覆盖真实曲库的绝大多数文件,且都是纯 Rust。
**QMC 加密本体**(与 ncm 同构:字节流密码 + 可选密钥):
| 方案 | 密钥来源 | 适用 |
|---|---|---|
| QMC1 | 固定种子,**无需密钥** | 旧版 `.qmc0` / `.qmc3` / `.qmcflac` / `.qmcogg` |
| QMC2 | ekey(base64 + TC-TEA 加密),密钥 ≤300B 走 Map XOR,>300B 走改性 RC4 | `.mgg` / `.mflac` 全系 |
**ekey 的三种存储形态 → 三层路由**:
| 层 | 形态 | 需要客户端? | 实现方式 |
|---|---|---|---|
| **①** | **尾部内嵌 ekey**:QTag 格式(ekey + 歌曲 ID + `QTag` 魔术)或 V1 格式(文件末尾 4 字节为 key 长度,key 在其前) | ❌ 不需要 | **纯 Rust 离线**,从文件尾直接提取 |
| **②** | **musicex 尾部**(QQ 客户端 ≥ 19.57 / Win 22.x):尾部 192B 只存 song_id + media_mid + filename,**ekey 不落盘** | ✅ 需运行且已登录 | **纯 Rust**:读凭据 → 调 API 取 ekey |
| **③** | 客户端内部导出(方案原文所选) | ✅ | Python sidecar + Frida attach `QQMusicCommon.dll` |
**第②层的完整链路**(全部可在 Rust 内完成,`windows-sys` 只差一个 feature):
1. 尾部检测:读末 8 字节,为 `"musicex\0"` 即 musicex;再向前读 `footer_size + 8` 解析完整 footer(`0x00` song_id u32LE、`0x0C` media_mid UTF-16LE 60B、`0x48` filename UTF-16LE 68B、`0xC0` footer_size、`0xC8` magic)。
2. 取 `uin`:读 `%APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini` 的 `[Account] Uin`(明文 INI)。
3. 取 `authst`:**`authst` 在 Windows 上不落盘**,仅在运行中的 `QQMusic.exe` 进程内存里。用 `CreateToolhelp32Snapshot` + `Process32FirstW/NextW` 定位进程 → `OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_VM_READ)` → `VirtualQueryEx` 遍历可读区(只需 `MEM_COMMIT`,跳过 `MEM_MAPPED`)→ `ReadProcessMemory` 按 1MB 分块 → 搜 `"authst":"` 取其后 Base64URL 串。实测约 0.5 秒。
4. 调 API:`POST https://u.y.qq.com/cgi-bin/musicu.fcg`,`req_1.module = "music.vkey.GetEVkey"`、`method = "CgiGetEVkey"`;`param.filename` **必须带 `.mgg`/`.mflac` 后缀**、`param.songtype` **必须为 1**(否则返回 `104005`)、`param.platform = "27"`(Windows)。响应取 `req_1.data.midurlinfo[0].ekey`。
> 三处易错点:`MEMORY_BASIC_INFORMATION` 在 Win10 1803+ 有 2 字节 `PartitionId` 插在 `AllocationProtect` 与 `RegionSize` 之间,**漏掉会导致 `state` 读成 `protect`、所有内存区被跳过**;`filename` 不带扩展名返回空 ekey;`authst` 有效期约 22.3 小时会过期。
**前置检查与降级出口**(UI 状态卡据此渲染):QQ 未运行或未登录 → 提示"请启动并登录 QQ 音乐后重试";层①②均失败的文件才落到③;Frida 不可用时报可读错误并给排除指引,**不自动拉起 QQ 客户端**。
**③(P1b,按需)的形态**若将来要做:`qq_decrypt.py` 走 `include_str!` 内置(与 `bridge.rs:17` 的 `BRIDGE_SCRIPT` 同范式),一次进程 attach 一批文件,stdout JSON-Lines 回报进度;导出符号是 mangled name(`?Open@EncAndDesMediaFile@@…`),**按子串 `EncAndDesMediaFile` 模糊匹配,严禁硬编码地址或 RVA**。
**输出扩展名**(不能按输入扩展名机械映射):`.qmc0`→`.mp3`、`.qmc3`→`.mp3`、`.qmc2`→`.ogg`、`.qmcogg`→`.ogg`、`.qmcflac`→`.flac`、`.mgg`/`.mgg0`/`.mgg1`/`.mggl`→`.ogg`、`.mflac`/`.mflac0`/`.mflach`→`.flac`(均以首帧魔数兜底校验)。**`.mmp4` 的产物容器(m4a 还是 mp4)尚未独立证实,实施 P1 时必须用真机样本确认后再定**。
### 3.3 许可边界(必须遵守,三档口径)
- **MIT(可逐行对照)**:`taurusxin/ncmdump`(网易云 ncm 算法本体)。可直接对照 `src/ncmcrypt.cpp` 实现,仅需保留版权声明。
- **GPLv3(只读文档与行为,严禁抄代码)**:`QQKWKG-TriMusicDecrypt`(+ FFmpeg GPL)、`ownlight6/qmc-decoder`。**整段搬代码 = 给本仓库引入 GPL 传染。** 允许的是:阅读其调用序列、常量、格式与协议说明后**独立重写**——本文档 §3.1 / §3.2 沉淀的正是这类非代码知识。
- **合规口径**(UI 底部放一行):仅处理用户本人拥有合法访问权限的本地文件,不用于批量分发或规避付费授权。
---
## 4. 接口契约
### 4.1 Tauri 命令
```rust
// 任务
music_decrypt_run(task_id, files?, folder?, root?, out_dir?, in_place?) -> Result<(), String>
music_decrypt_cancel(task_id: String) -> Result<bool, String>
// 预览与状态
music_decrypt_scan(folder: String, root: Option<String>) -> Result<ScanSummary, String>
music_decrypt_qq_status() -> Result<QqOnlineStatus, String> // 只读本机,不发网络请求
```
`QqOnlineStatus` 字段:`{ running, loggedIn, uin, ready, message, steps }`。
**`authst` 不下发到前端**——它只活在后端内存里用于调接口。
- **注册是 3 处,不是 2 处**(实测仓库现状):
1. `music/mod.rs` 的 `pub use commands::{...}` re-export(约 `mod.rs:48`);
2. `lib.rs` 的 `collect_commands![]`(`export_bindings()` 内,`lib.rs:205`);
3. `lib.rs` 的 `generate_handler![]`(`run()` 内,`lib.rs:348`)。
漏第 2 处 = 运行时能调但 `bindings.ts` 缺类型;漏第 1、3 处 = 编译失败或调用失败。
- 前端沿用本模块既有范式(`musicStore.ts` 全用原生 `invoke` + 手写类型,不用 `commands`),故解密 store 同样用 `invoke`。
### 4.2 事件 `music-decrypt-event`(登记进 `constants.rs` 音乐分组)
```typescript
type MusicDecryptEvent = // 注意:只有 tag 是 kebab-case,**字段名仍是 snake_case**
| { type: 'start'; task_id: string; total: number }
| { type: 'file'; task_id: string; index: number; name: string;
status: 'ok' | 'error' | 'unsupported';
message: string | null; // 失败原因,或成功时的备注(平台 / 密钥形态 / 元数据摘要)
output: string | null; // 主产物
cover: string | null } // 单独落盘的封面(网易云带内嵌封面时才有)
| { type: 'progress'; task_id: string; done: number; total: number;
bytes_done: number; bytes_total: number; name: string }
| { type: 'finished'; task_id: string; ok: number; failed: number; cancelled: number }
```
> **字段名是 snake_case 而非 camelCase**:`DecryptEvent` 上只有 `#[serde(tag = "type", rename_all = "kebab-case")]`
> 作用在 tag 上,变体字段名原样输出。前端 `decryptStore.ts` 的 `RawEvent` 必须照此声明
> ——两边不一致时不会编译报错,只会表现为「任务建好了但进度永不动」。
> Rust 侧有 `event_json_contract` 单测把形状钉死(§6.23)。
>
> 结果态没有 `already`:P0 不做「已解密过则跳过」(同一文件重解会产出 `_1` 后缀的新文件),
> 语义比"猜哪份产物属于哪次输入"更可预测。
> 原先的 `deps-install` 事件随 `music_decrypt_install_deps` 一起取消——三层路由后不再需要 `pip install frida`。
> 注意前端 `musicStore.ts:419` 是**硬编码事件名字符串**、并未引用前端常量表,故解密 store 同样硬编码,仅 Rust 侧登记常量。
### 4.3 文件识别(用户不选平台)
按扩展名路由,魔数校验兜底:
| 扩展名 | 路线 |
|---|---|
| `.ncm` | 网易云离线引擎(按内容魔数识别,不依赖后缀) |
| `.mgg` / `.mgg0` / `.mgg1` / `.mggl` / `.mflac` / `.mflac0` / `.mflach` / `.mmp4` / `.qmc0` / `.qmc2` / `.qmc3` / `.qmcflac` / `.qmcogg` | QQ 引擎(按尾部形态决定是否联网) |
| 其他 | 散选时保留为 `unsupported`;文件夹扫描时直接跳过 |
> 后缀矩阵原文档只列了 3 个,会**静默漏掉用户曲库里的常见文件**,故过滤列表与路由表**一次写全**。
> 实际判定以**内容**为准(§4.5),后缀只用于文件对话框的过滤器。
### 4.3.1 QQ 音乐:是否需要登录?
这是使用者最常问的一点,所以结论放在前面:
| 文件来源 | 扩展名 | 需要 QQ 音乐登录? |
|---|---|---|
| QQ 客户端 **≤ 19.51** 下载 | `.qmc0` `.qmc3` `.qmcflac` `.qmcogg` | **不需要** |
| QQ 客户端较旧版本下载(QTag / V1 尾部) | `.mgg` `.mflac` | **不需要** |
| QQ 客户端 **≥ 19.57** 下载(musicex 尾部) | `.mgg` `.mflac` `.mmp4` | **需要**:客户端运行 + 已登录 |
| 网易云(任何版本) | `.ncm` | **不需要** |
**为什么新版必须登录**:从 19.57 起,QQ 音乐不再把解密密钥(ekey)写进文件,
只在文件末尾留 192 字节元数据;客户端自己也是在播放/下载时拿本机登录态
(`uin` + `authst`)向服务器实时换取密钥。第三方要解开同一个文件,只能复刻这一步。
**这里的实现方式**:只读本机凭据(INI 里的 `uin` + 运行中 `QQMusic.exe` 内存里的 `authst`),
再调官方 `music.vkey.GetEVkey` 接口取密钥——**不注入进程、不改写文件、不做任何反检测**。
**操作步骤**(与 UI 状态卡里的文案一致):
1. 在电脑上启动 QQ 音乐客户端(Windows 版)。
2. 用它登录你的账号,并**保持客户端开着**(`authst` 只存在于运行期内存)。
3. 回到「解密」页点「重新检测」,状态变为「已就绪」即可解密 musicex 文件。
4. 若提示未取到登录令牌:先在客户端里**播放任意一首歌**触发一次网络请求,再重新检测。
5. 仍失败则试过**以管理员身份运行**本应用(读其他进程内存可能需要更高权限)。
6. 登录令牌约 **22.3 小时**过期;过期后重新检测即可,无需重装。
**UI 呈现**:状态卡显示三态(未运行 / 未登录 / 已就绪)+ QQ 号 + 「重新检测」按钮;
未就绪时折叠区里就是上面这 6 条步骤。上方那句"旧版文件与 `.ncm` 本来就不需要登录"
也会一并显示,避免用户误以为自己必须登录才能用这个功能。
### 4.4 输出路径规则
- **就地模式(`in_place = true`,文件夹批量的默认)**:产物与源文件**同目录同名**,
仅按格式改扩展名(`Pop/a.mflac` → `Pop/a.flac`)。符合"就地解出来"的直觉,
也天然不会与其他目录的同名文件冲突。此时 `out_dir` 不参与写盘。
- **指定输出目录(`in_place = false`)**:默认根目录 `savedir/decrypted/`,
并**按 `root` 还原相对目录结构**(`Pop/2026/b.ncm` → `out/Pop/2026/b.flac`)。
散选文件没有相对目录,平铺到根目录。
- **同名去重**:即使还原了目录结构,同一目录内仍可能撞名(如 `.mgg` 与 `.mgg1` 同基名)。
规则:优先用原名,已存在(磁盘上或本批内已占位)则追加 `_1` / `_2`…
- **输入输出相交保护**:非就地模式下,若某输入文件已位于输出目录内则剔除,
避免"解出来再解"无限膨胀;全被剔除时报错并提示可改用「就地解密」。
- 扩展名以**音频首帧魔数**决定(ncm 见 §3.1⑥,QMC 见 §3.2 末),不信任输入扩展名;
魔数认不出时才回退到输入后缀映射。
### 4.5 文件夹批量
命令参数的关系:
| 参数 | 含义 |
|---|---|
| `folder` | **文件夹批量入口**:Rust 侧递归扫描该目录 |
| `root` | 计算相对路径的基准(决定输出目录里还原哪几层) |
| `files` | 散选文件列表(`folder` 为空时使用) |
| `in_place` | 就地解密(默认 `true`,见 §4.4) |
| `music_decrypt_scan` | 只扫描不解密,返回 `{ total, ncm, qmc }` 供 UI 预览 |
**平台判定按内容,不按后缀**(`scan::route`):
1. 读 8 字节魔数,命中 `CTENFDAM` → 网易云;
2. 否则读尾部判 QMC 形态:后缀在 QMC 家族里 → QQ音乐;
3. 后缀不认识时,只有**明确**的尾部形态(QTag / V1 / musicex)才认领——
否则任何末尾凑巧不是 `QTag` 的文件都会被判成"QMC1",噪声太大。
理由:同一曲库里 `.ncm` / `.mflac` / `.qmcflac` / `.mgg` 混放是常态,且 QQ 还有
`.mgg0` / `.mflac0` 等变体,靠后缀枚举必然漏。代价是**认不出的文件会被跳过**,
所以扫描数可能少于用户预期——因此 UI 先调 `music_decrypt_scan` 显示
"找到 N 个 · 网易云 x · QQ音乐 y",让用户在开跑前就能判断是否符合预期。
---
## 5. 架构与模块设计
### 5.1 Rust 侧 `src-tauri/src/music/decrypt/`(已实施的实际结构)
```
decrypt/
mod.rs // 任务表(Mutex<HashMap<taskId, 取消标志>>)、工作线程 + 节流事件转发、事件契约
common.rs // 两引擎公共件:DecryptError、魔数定格式、同名去重、读满一块
ncm.rs // 网易云离线引擎(AES-ECB + RC4 变体 + meta/封面)
qmc.rs // QQ:QMC1 静态密钥 / QMC2 Map / QMC2 RC4 / tc_tea / 尾部形态 + 流密码
qq_footer.rs // musicex 尾部解析(纯,可单测)
qq_credentials.rs // 凭据:INI 解析(纯)+ 进程内存取 authst(平台胶水)
qq_memscan.rs // Windows 专用:ToolHelp 枚举进程 + VirtualQueryEx/ReadProcessMemory(只读)
qq_ekey.rs // GetEVkey 请求组装与响应解析(纯,可单测)
qq_online.rs // 编排:musicex → 凭据 → 取密钥 → 解密;probe_status()
scan.rs // 文件夹递归扫描 + 内容优先的平台路由
commands.rs // run / cancel / scan / qq_status(四条命令)
```
平台判定与密钥来源的**分工**:`scan.rs` 只决定"这文件归哪个引擎";
`qmc.rs` 决定"密钥从哪来"(内嵌 / 静态);只有尾部是 musicex 时,
调度层才把 `KeyRequired` 交给 `qq_online.rs` 转在线路径——这样离线路径保持零网络依赖。
`mod.rs` 挂到 `music/mod.rs` 的子模块列表;事件常量加进 `constants.rs` 音乐分组。
### 5.2 前端
```
src/modules/music/components/DecryptPanel.vue // 页签内容
src/stores/decryptStore.ts // 任务列表 + 事件监听(照 musicUploadStore 范式)
MusicModule.vue // tabs 加一项 + <TabsContent value="decrypt">
index.ts // searchItems 加「音乐解密」(tab: 'decrypt')
```
**P0 / P1a / P1c UI 形态**(已实施):
- 顶部操作行:**选择文件夹** | 选择文件(dialog 多选,按 §4.3 全后缀过滤)| **就地解密开关** | 取消 / 清空记录
- **QQ 音乐在线解密状态卡**:状态点(三态)+ 一句话状态 + QQ 号 + **重新检测** + 折叠的**操作步骤**;
未就绪时折叠区里就是 §4.3.1 那 6 条,并附一句"旧版文件与 `.ncm` 本来就不需要登录"
- 输出目录行:就地模式下置灰并显示"与源文件同目录"
- **文件夹扫描预览条**:显示"找到 N 个 · 网易云 x · QQ音乐 y" + 开始解密按钮
- 中部任务表:任务头(文件夹路径 / 进度条 / `bytes_done/bytes_total` / 打开产物目录)|
文件行(文件名 | 平台徽标 | 状态徽章 | 打开产物目录 | 打开封面 | 备注或失败原因)
- 空态用 `StateBlock variant="empty"`;进度条结构恒定(完成后保留满格,不整块消失)
- 底部一行合规说明
### 5.3 数据流
与下载链路同构:前端 → `music_decrypt_run` → Rust 建 taskId 即回 → 后台执行 → `music-decrypt-event` → `decryptStore` 更新 → 列表刷新。页签切换组件卸载不影响任务(监听在 store)。
---
## 6. 关键实现细节与已知的坑
**ncm**(编号对应 §3.1 的条目号)
1. `aes 0.8` 只有块原语、`ecb` crate 不在依赖树:ECB 手写 16 字节块循环(`cipher::BlockDecrypt::decrypt_block`)。**不要**为此引入 `ecb` crate。
2. **两段 XOR 常量不同**(`0x64` key / `0x63` meta)。照抄成同一个常量 = 必然失败。
3. **PKCS#7 风格 padding**:AES-ECB 收尾取最后一字节为 padding 长度(`> 16` 视作 0),不是“去前缀”。
4. **改性 RC4 KSA 的 `last_byte` 累加**(照抄参考实现即可,但别误解它):
式子 `c = (swap + last_byte + key[key_offset]) & 0xff` 在模 256 下**恰好化简为标准 RC4**,
实测两者密钥盒逐字节相同(256/256)。因此它**不是**"与标准 RC4 的关键差异",
也不能靠与标准 RC4 比对来验证实现——验证只能靠固定向量(见 §6.25)。
`key_offset` 触 keyLen 归零循环取 key 这一点照抄。
5. **音频块之间不跳字节**,`0x8000` 只是块大小;`i` 是块内下标。原文档的"每 0x8000 跳过 5 字节"是错的(那 5 字节在 §① 的头部里,且已单独处理)。**但块边界必须由"读满一块"确定**,不能用 `Read::read` 的短读结果(见 §6.24)。
6. **输出扩展名看音频首帧魔数**(`ID3` → `.mp3`,否则 `.flac`),不看 meta 的 `format`。
实现比这条更宽一点:还识别 `fLaC` / `OggS` / `RIFF..WAVE` / `ftyp` / `wvpk`,
给 P1 的 QQ 产物复用(ncmdump 的兜底同为 flac)。
7. meta 段是**两层前缀**:先剥 22 字节 `163 key(Don't modify):`,再 base64,再 AES,再剥 6 字节 `music:`。
8. **流式处理**:`0x8000` 块逐块读→解→写,禁止整文件读入内存(`.mmp4` 可能很大)。大文件下需按已处理字节数推 `progress`。
9. **单测不依赖真实样本**:真实 FLAC 最小样本进不了仓库。改为对**中间产物**断言——AES-ECB 往返、KSA 密钥盒已知值、padding 剥离、魔数→扩展名判定、以及"自造一个合法 ncm 容器(用同一套算法正向构造)再解回来"的往返测试。真机样本走手动自测。
10. 魔数/解析失败走 per-file `Err`,**不 panic、不中断整批**。
**QQ(P1)**
11. 第①层(QTag / V1)**完全离线**,不要因为"QQ 文件"就先去连客户端——先用尾部分支判形态再决定要不要读凭据。
12. 第②层的 `authst` **只在 `QQMusic.exe` 运行期内存里**,不落盘;`uin` 在 `QQMusicServiceConfig.ini` 可明文读。`MEMORY_BASIC_INFORMATION` 的 2 字节 `PartitionId`(Win10 1803+)**必须包含**,否则 `state` 会读成 `protect`、所有内存区被跳过。
13. API 三处必须:`filename` 带 `.mgg`/`.mflac` 后缀、`songtype = 1`、`module = music.vkey.GetEVkey`(不是 `GetVkey`)。否则 `104005` 或 ekey 为空。
14. `authst` 约 22.3 小时过期:失败文案要给"重新登录 QQ 音乐"的出口,而不是只报网络错误。
15. 第③层(Frida):必须**先启动 QQ 音乐**再 attach,`QQMusicCommon.dll` 打开主界面即加载;导出符号是 mangled name,**按子串 `EncAndDesMediaFile` 模糊匹配,严禁硬编码地址或 RVA**;被杀软拦截只给排除指引,**不做反检测动作**;批量时客户端 UI 可能短暂卡顿,属预期。
16. `path_sensitive_mflac` 变体(同名文件不同目录内容不同)P1 不处理:报错带全路径,遇到再迭代。
17. `.mmp4` 产物容器未证实,P1 先用真机样本确认再定(见 §3.2 末)。
**工程**
18. 新命令登记 **3 处**:`music/mod.rs` re-export、`lib.rs` 的 `collect_commands![]`、`lib.rs` 的 `generate_handler![]`(见 §4.1)。
19. `music-decrypt-event` 常量进 `constants.rs` 音乐分组;前端沿用硬编码字符串(与 `musicStore.ts:419` 一致)。
20. 解密 store 必须独立于组件生命周期:Tabs 非 active 会卸载内容,事件监听挂 store 不挂组件。
21. **输出同名去重 + 输入输出相交保护**(见 §4.4)——原文档缺失,不做会静默覆盖用户文件。
22. 三层路由后**不再需要便携 Python 与 frida**,`music_decrypt_install_deps` 命令取消;QQ 未登录的错误出口走状态卡提示。
**实施中新增确认的坑(2026-09-27 实测)**
23. **事件字段名是 snake_case**(不是 camelCase)。`#[serde(tag = ..., rename_all = "kebab-case")]`
只作用于 tag,变体字段名原样输出。前后端不一致时**不报错**,只表现为进度不动。
Rust 侧 `event_json_contract` 单测钉死 JSON 形状。
24. **音频块边界必须用"读满一块"而非 `Read::read` 的返回值**。`BufReader::read` 会短读,
块边界一漂移,解密式里的「块内偏移 `i`」就与加密侧错位,表现为**文件从中间某处起全是噪声**
(实测首个坏字节落在 32418,仍在第一大块内),前半段却完全正常,极难排查。
已加 `read_full()` 专门处理。
25. **`last_byte` 累加在模 256 下是恒等变形**:`c = swap + last_byte + key` 与标准 RC4 的
`j += s[i] + key` 结果**逐字节相同**(已实测 256/256 一致)。所以:
- 不能靠"与标准 RC4 比对"来验证密钥盒实现;
- 也**不要**以为它是"改性 RC4 的关键差异"而据此改写(本计划早期的 §6.4 表述即由此误导)。
真正的验证手段是**固定向量**(`key_box_matches_reference_vectors` /
`keystream_matches_reference_vector`)。
26. **`MODIFY_KEY` 是 16 字节而非 17**(`aes::Aes128` 的密钥长度就是 16);
`CORE_KEY` 的 17 字节是**解密后要剥掉的前缀**,与 AES 密钥不是同一个东西
(AES 密钥是它的前 16 字节)。两者混用不会编译报错,只会全解错。
27. **合成容器单测的 key 段必须带 `neteasecloudmusic` 前缀**——否则解密端剥前缀后拿到错种子。
这个坑一度被"单循环 KSA"的错误实现掩盖(两边同时错、往返仍然自洽)。
**P1a(QQ 离线)实施中新增确认的坑**
28. **QMC2 Map 密码的 `scramble` 必须用 `wrapping_shl/shr`**(对移位量取模),
不能写成 `u8::rotate_left/rotate_right`——后者会在内部再取一次模,结果**不同**。
被 Apache 参考实现的原向量抓到(若不比对向量,会产出"能跑但全错"的解密)。
29. **tc_tea 不是 TEA-ECB,而是 TEA 变体 + 自定义 CBC**:块与密钥字都是**大端**、
16 轮(非 32)、单轮是 `((v<<4)+k1) ^ (sum+v) ^ ((v>>5)+k2)`,
且明文前置 `1+pad+2` 字节头、尾部 7 字节 0 自校验。照 TEA-ECB 写会解出**部分可读的乱码**
(表现极具迷惑性:能看到明文碎片)。尾部 0 校验正是"密钥对不对"的权威判据。
30. **V1 尾部判定不能只看长度**:任意加密数据末尾都可能凑出 `0<n<=0x400`,
只按长度判会把普通 QMC1 文件误判成 V1 并砍掉一大截音频(实测 32871 字节 → 4096)。
必须追加"前面那一段像不像 base64 ekey"的校验。
31. **`sniff_tail` 的 `audio_len` 必须换算成绝对长度**:它只读了尾部 probe,
`detect_tail` 给出的是**相对 probe 起点**的偏移;QMC1(无尾部)必须回落到**整个文件大小**。
另外**不要在两个地方各写一遍尾部探测**——当初 `decrypt_file` 自己复制了一遍,
修了 `sniff_tail` 却没修它,症状是"探测结果对、实际产物只有 4KB"。
32. **QMC1 的掩码分支是 `pos > 0x7FFF`(严格大于)**,不是 `>=`;写成 `>=` 会在回绕点差一字节。
**P1c(musicex 在线)实施中新增确认的点**
33. **`MEMORY_BASIC_INFORMATION` 的 `PartitionId`(Win10 1803+)**:直接沿用
`windows-sys` 的结构体即可,但**自己手写 `#[repr(C)]` 时千万别漏**——漏了会让
`RegionSize`/`State`/`Protect` 全部读错偏移,`VirtualQueryEx` 返回的 `State`
读成 `Protect`(如 `0x04` 而非 `0x1000`),于是所有内存区被跳过、永远扫不到 token。
34. **`getEVkey` 的三个"必须"**:`filename` 带扩展名、`songtype=1`、
`module=music.vkey.GetEVkey`(不是 `GetVkey`)。任一写错都只是"拿不到 ekey",
不会报错——所以请求体用纯函数组装并单测锁死(`qq_ekey::build_evkey_request`)。
35. **`authst` 会过期(约 22.3 小时)**:失败文案必须给"重新登录 / 重新检测"的出口,
否则用户会以为是网络问题。响应里的 `expiration` 已带进产物备注。
36. **单元测试不要真的发网络请求**:本机一旦登录成功,测试就会去连 QQ 服务器,
导致测试变慢变脆。改为验证"请求体能正确构造"+"`#!Qk` 头守卫"+"尾部能被解析出
`media_mid`/`filename`"三段——真实响应留给真机端到端。
37. **musicex 音频段要校验 `#!Qk` 头**:尾部像 musicex 不代表内容真是 QMC2 密文;
没有这道守卫会把任意文件"解"成垃圾却报告成功。
**真机端到端验证后修正(2026-09-27)**
38. **`#!Qk` 不是 QMC2 密文的通用魔术**(推翻第 37 条的做法):真机 musicex 样本
(Avicii - Heaven,197MB `.mflac`)的密文头是 **`51 74 03 75`**,按"必须以 `#!Qk`
开头"写的守卫会把**完全合法的文件误拒**。
正确做法是**用解密结果判定密钥是否正确**:用取到的密钥解出前 16 字节,
看是否是已知音频魔术(`fLaC` / `OggS` / `ID3` / `ftyp`…)——密钥错时它是随机噪声,
几乎不可能凑巧命中;命中即说明密钥对、文件也对。
这也是"内容优先"原则的又一次应用:**不要用猜测的密文特征做判据,要用能验证的结果。**
39. **文档给的 musicex 字段偏移在真样本上是对的**:`0x0C` media_mid(60B UTF-16LE)、
`0x48` filename(68B UTF-16LE)、`0xC0` footer_size、`0xC8` magic 全部命中,
尾部实测 192 字节、padding 区有 13 个非零字节(所以不能假设 padding 全 0)。
40. **真机样本的规模提醒**:`.mflac` 可达 197MB / 192kHz / 24bit。
`qq_online` 目前把音频段整段读入内存再解密(探针与生产路径都是),
在这个量级下可用,但如果将来遇到多 G 的文件,应改成分块解密 + 流式写盘
(`qmc` 的流密码本身已支持任意偏移)。
---
## 7. 分阶段计划
### P0 — 网易云 + 解密页签全链路(约 2 天)**✅ 已实施(2026-09-27)**
- [x] `useModuleTabs` + `TabsContent` 接「解密」页签;`index.ts` 搜索条目
- [x] `decrypt/ncm.rs`:§3.1 全部要点 + 单测(**18 项通过**)
- [x] `decrypt/mod.rs` + `commands.rs`:run / cancel + 事件发射;**三处**登记;`constants.rs` 事件常量
- [x] `decryptStore.ts` + `DecryptPanel.vue`:选文件 → 批量任务 → 进度 → 打开输出目录
- [x] 输出同名去重 + 输入输出相交保护(§4.4)
- [x] 封面单独落盘(`<歌名>.cover.png|jpg`)——标签回填仍留 P2(`lofty` 需按容器分派)
- [ ] **自测:真实 `.ncm` 样本解出**(需人工用真机样本验证;仓库内样本有版权且体积大,故算法靠 §6.9 的中间产物单测 + 合成容器往返覆盖)
- **验收**:页签选 10 个 ncm 全部解出、失败有原因、切页签不丢任务、播放器直接可播
**已交付文件**:
| 文件 | 内容 |
|---|---|
| `src-tauri/src/music/decrypt/ncm.rs` | 网易云离线引擎(容器解析 / AES-ECB / 密钥盒 / 流式解密 / 魔数定格式 / 封面 / 同名去重)+ 单测 |
| `src-tauri/src/music/decrypt/mod.rs` | 任务表、工作线程 + 节流事件转发、`DecryptEvent` 契约(含 JSON 形状单测) |
| `src-tauri/src/music/decrypt/commands.rs` | `music_decrypt_run` / `music_decrypt_cancel` + 输出目录解析与相交保护 |
| `src/stores/decryptStore.ts` | 任务状态 + 事件监听(挂 store,不随组件卸载) |
| `src/modules/music/components/DecryptPanel.vue` | 页签 UI |
| `music/mod.rs` · `lib.rs` · `constants.rs` | 子模块挂载、`MusicManager.decrypt` 字段、三处命令登记、事件常量 |
### P1a — QQ 离线解密 + 文件夹批量(**✅ 已实施,纯 Rust,无 Python/frida**)
- [x] `decrypt/qmc.rs`:QMC1 静态密钥表 / QMC2 Map 密码 / QMC2 RC4 变体 / tc_tea(TEA 变体 + 自定义 CBC)
- [x] 第①层:QTag 与 V1 尾部 ekey 提取 → **离线解密**
- [x] `decrypt/scan.rs`:递归扫描 + 内容优先的平台路由 + 保留相对目录结构
- [x] **文件夹批量**:`folder` / `root` / `in_place` 三个参数 + `music_decrypt_scan` 预览命令
- [x] `decrypt/common.rs`:两引擎统一的错误类型、魔数定格式、同名去重、读满一块
- [x] 单测 **56 项**(模块合计 174 项全库通过),含参考实现的原始测试向量
- [ ] 第②层 musicex + `GetEVkey` API(**未实施**,见 P1c)
- [ ] 真实 `.mflac/.mgg/.qmcflac` 样本自测(需人工;仓库内不放版权样本)
**已交付文件(P1a 增量)**:
| 文件 | 内容 |
|---|---|
| `src-tauri/src/music/decrypt/qmc.rs` | QMC 全套离线算法 + 尾部形态判定 |
| `src-tauri/src/music/decrypt/scan.rs` | 文件夹递归扫描与平台路由 |
| `src-tauri/src/music/decrypt/common.rs` | 两引擎公共件 |
**算法来源(全部宽松许可,均有原始向量锁行为)**:
| 部分 | 来源 | 许可 |
|---|---|---|
| QMC1 静态密钥表 + 掩码规则 | `jixunmoe/qmc-decode` | MIT |
| QMC2 密钥派生 / Map / RC4 / 尾部形态 | `bczhc/qmc-dec`(`qmc2-crypto`) | Apache-2.0 |
| tc_tea | `tc_tea` crate | MIT/Apache-2.0 |
### P1b — Frida 兜底(按需,不计入本轮)
- [ ] `qq_decrypt.py`(`include_str!`):attach → `EncAndDesMediaFile` 调用序列 → 批量 → JSON-Lines 进度
- [ ] `decrypt/qq_frida.rs`:前置检查、spawn、逐行读转发事件
- **触发条件**:仅当 §3.2 的第③层文件在真实用户场景中被确认存在且前两层无法覆盖时才做
### P1c — musicex 联网取 ekey(**✅ 已实施**)
- [x] `qq_footer.rs`:musicex 尾部解析(song_id / media_mid / filename)
- [x] `qq_credentials.rs`:读 `%APPDATA%\Tencent\QQMusic\QQMusicServiceConfig.ini` 的 `uin` + 扫进程内存取 `authst`
- [x] `qq_memscan.rs`(Windows):`CreateToolhelp32Snapshot` + `OpenProcess` + `VirtualQueryEx` + `ReadProcessMemory`(**只读**)
- [x] `qq_ekey.rs`:`GetEVkey` 请求组装与响应解析(`filename` 带扩展名 / `songtype=1` / `platform="27"`)
- [x] `qq_online.rs`:编排 + `probe_status()` 在线能力探测
- [x] `music_decrypt_qq_status` 命令 + UI 状态卡(含**逐步操作说明**)
- [x] `windows-sys` 增开 `Win32_System_Diagnostics_ToolHelp` 与 `..._Debug`
- [x] **本机实测**:`probe_status()` 返回 `running=true logged_in=true uin=1154027699 ready=true` —— 内存扫描确实取到了 `authst`
- [x] **端到端已用真机样本跑通**(2026-09-27,见下)
#### 真机端到端验证记录(首个 musicex 样本)
样本:`C:\Users\Administrator\Music\Heaven - Avicii_EM.mflac`(197,104,516 字节,
尾部 `musicex\0`,`song_id=233102682`,`media_mid=003iTvi44A6RMs`,
`filename=AIM0002ELI6a1wXJDo.mflac`)
| 环节 | 实测结果 |
|---|---|
| 尾部解析 | song_id / quality1=2 / quality2=11 / media_mid / filename 全部正确 |
| 凭据 | 返回 `running=true logged_in=true uin=1154027699 ready=true` |
| `GetEVkey` | **成功**,拿到 704 字符 ekey;`expiration=80400`(22.3 小时,与文档一致) |
| ekey → 密钥 | 解密出 **512 字节**原始密钥 → 命中 **RC4 变体**(>300 字节)分支 |
| 音频段 | 197,104,324 字节(= 文件大小 − 192 字节尾部,完全吻合) |
| 解密结果 | 首帧 `66 4c 61 43` = **`fLaC`** ✅ |
| 产物校验(`lofty`) | **277.261 秒 · 192000 Hz · 24 bit · 2 声道 · 5686 kbps** —— 192kHz/24bit Hi-Res 无损 |
**验证方式**:`examples/decrypt_musicex_probe.rs` 走真实链路(读内存凭据 → 真实
HTTP 请求 → 解密),再用 `examples/verify_audio.rs` 交给项目同款解析器确认产物合法。
两个 example 都保留,供后续 QQ 改协议时快速定位。
**这次验证推翻了一个错误假设**:样本的密文头是 `51 74 03 75`,**不是**文档里提到的
`#!Qk`。原先按"密文必须以 `#!Qk` 开头"写的守卫会把完全合法的文件误拒——已改为
**用解密结果判定**(解出的前 16 字节是否为已知音频魔术),见 §6.38。
**凭据可用性已知限制**:
| 维度 | 情况 |
|---|---|
| `uin` 来源 | INI 明文,稳定 |
| `authst` 来源 | 仅运行期内存;**QQ 音乐必须开着且已登录** |
| 有效期 | 约 22.3 小时(响应 `expiration` 字段,已带进产物备注) |
| 权限 | 读他人进程内存可能需管理员;失败文案已提示 |
| 是否注入 | **否**,纯只读——这是它与 Frida 兜底的本质区别 |
### P2 — 按需增强(不进本轮)
- **ID3 / FLAC / MP4 标签回填**(用 `lofty`,按容器分派;meta JSON 已在解密时解析出来)
- 解密完成 →「加入本地曲库」/ 上传飞牛(复用 `musicUploadStore`)
- 拖拽文件进页签、解密历史持久化
- 酷狗 / 酷我(除非再次明确要求)
- QQ 变体适配(path_sensitive_mflac)
> **变更**:原计划把「封面提取 / ID3 标签回填」一起从 P2 提前到 P0。**实际只提前了封面提取**——
> 封面字节在解析容器时顺手就读出来了,落盘是十几行,且不做就"能播但难用"。
> 标签回填仍留 P2:它需要 `lofty` 且要按 mp3/flac/m4a 分派容器,属于增强而非可用性门槛。
---
## 8. 风险与开放问题
| 风险 | 影响 | 对策 |
|---|---|---|
| QQ 改 musicex 尾部/API 协议 | 第②层失效 | 协议字段集中在 `qq_footer` / `qq_ekey` 两处;错误文案带原始响应码;关注 qmc-decoder issue |
| `authst` 提取被安全软件拦截 | 第②层失效 | **只读**内存、不注入;失败给"以管理员身份运行"出口 |
| **musicex 端到端** | ~~真实响应字段可能与文档不符~~ **已验证通过**(真机 197MB 样本,产物为合法 192kHz/24bit FLAC) | 保留 `examples/decrypt_musicex_probe.rs` + `verify_audio.rs`,QQ 改协议时可快速定位 |
| `authst` 过期(22.3h) | 第②层短期失效 | 错误文案给"重新登录/重新检测"出口;有效期带进产物备注 |
| QQ 版本升级改 mangled 导出符号 | 仅第③层(Frida)失效 | 子串模糊匹配;第③层不在实施范围,影响面已缩小 |
| 真实样本不足导致算法细节偏差 | 解出错文件 | **已用参考实现的原始测试向量交叉验证**(QMC1 掩码 / Map / RC4 / tc_tea / ekey 端到端) |
| GPLv3 边界被无意破坏 | 许可风险 | 三档口径见 §3.3;QMC 只取 MIT / Apache-2.0 两份来源的**代码与数据** |
| 网易云改 ncm 格式 | 个别文件失败 | per-file error 不中断整批 |
| 同名文件落盘互相覆盖 | **用户文件丢失** | §4.4 同名去重 + 相交保护 |
| 文件夹扫描漏文件(内容认不出) | 用户以为解完了 | UI 先出 `music_decrypt_scan` 预览数量 |
**开放问题**:
1. 解密输出默认就地(文件夹批量)或 `savedir/decrypted/`(散选);独立设置项留 P2。
2. QQ 未运行时是否自动拉起?**离线层与 `.ncm` 完全不需要客户端**;只有 musicex 需要,
当前选择"只提示、不自动拉"(客户端要登录,自动拉起也解决不了登录态)。
3. `.mmp4` 的产物容器(m4a / mp4)待真机样本确认——当前靠首帧 `ftyp` 魔数判定,认不出时按后缀落 `m4a`。
(`.mflac` 已实测确认:产物为 192kHz/24bit 的 `.flac`。)
4. ~~musicex 端到端未验证~~ **已解决**(2026-09-27,真机样本跑通,见 P1c 的验证记录)。
5. `.mflac0` / `.mgg1` 等变体按 QMC2 处理,但**未用真实样本验证**过其尾部形态与 `.mflac` / `.mgg` 一致。
6. 微信登录的 QQ 音乐 (`tmeLoginType=3`):实现上 `authst` 与 QQ 登录通用,
但 `login_type` 目前固定发 `1`(QQ 登录实测可用)——若真机发现微信登录取不到 ekey,需按凭据来源推断。
7. **大文件内存占用**:`qq_online` 目前整段读入内存解密;197MB 实测可用,
但 `.mflac` 可以更大。若遇到多 G 文件,应改流式(`qmc` 的流密码已支持任意偏移)。
---
## 附录 A:参考项目对照(只取思路)
### A.1 QKKDecrypt 实测结论(2026-09-27 深读 `main@938b22d`,来自其源码而非猜测)
**最重要的一条**:该项目 QQ 路径**完全不解析 QMC 加密格式**——它把原始加密文件整包交给 QQ 自己的 DLL 解密,因此不受 static/map cipher 变体影响。**代价是强依赖四项**:QQ 客户端运行 + `QQMusicCommon.dll` 已加载 + **管理员权限**(`cli.py::_require_admin()`,非管理员直接 `return 2` 并打印"已禁止继续使用")+ mangled 名/编译器版本不变。**这四项与它的"回退"一起,正是我们改走 §3.2 分层路由的原因。**
| QKKDecrypt 文件 | 可借鉴 | 不可借鉴 |
|---|---|---|
| `platforms/qq/adapter.py` | `SUPPORTED_SUFFIXES` 仅 `.mflac/.mgg/.mmp4`;前置检查项;ASCII 暂存 |
| `qq/runtime/qqmusic_decrypt.py` | `EncAndDesMediaFile` 的 3 组候选 mangled 名、NativeFunction 全 `thiscall` 签名、调用序(`Memory.alloc(0x28)` → ctor → `allocUtf16String` → `Open(..,1,0)` → `GetSize` → `Read` → dtor) | **硬编码**;整文件读入内存;未校验 `Open`/`Read` 返回值 |
| `qq/runtime/frida_decrypt_gateway.py` | 进程查找用**子串匹配** `"qqmusic"`;**每批次只 attach 一次**并缓存 session | 无 session 重连(QQ 中途重启即失效) |
| `qq/variant_adapter.py` | "路径敏感型 mflac"→**解密前先复制到纯 ASCII 路径**(`pick_safe_tmp_dir`:盘根 `_qqmusic_tmp` → 项目根 → `tempfile.gettempdir()`) | 只实装了这一个变体 |
| `qq/internal_direct.py` / `qq/export_fallback.py` | — | **存在但未接入主流程 = 死代码**,不可当作可用的回退能力承诺 |
| `platforms/netease/adapter.py` | 输出扩展白名单法 | **它没有自研 ncm 算法**——直接 `from ncmdump import NeteaseCloudMusicFile` 委托 PyPI 的 `ncmdump-py`;且 `predicted_extension()` 会**多解密一遍**(性能坑) |
| `Application/decrypt_service.py` | 事件粒度 = **逐文件 `index`/`total`**;`file_finished.result ∈ success/failed/already_decrypted` | 事件种类过多(20+) |
| `cover_art_service.py` | "本地同名图 → 缓存 → 联网"的 local-first 顺序 | **给网易云产物做封面兜底时查的是 QQ 音乐 API** |
| `THIRD_PARTY_LICENSES.md` | 合规口径与风险表述 | 内置 FFmpeg 为 `--enable-gpl --enable-version3` 构建 → 传染面比"仓库 GPLv3"更大 |
**对本文档的两处直接修正**:
1. **"输出扩展名看音频首帧魔数"得到双重印证**——QKKDecrypt 的最终扩展名同样**不取映射表**,而是 `detect_audio_container()` 从实际字节判定(`fLaC`/`OggS`/`RIFF..WAVE`/`ID3`/`0xFF 0xFB|0xF3|0xF2`/偏移 4 处 `ftyp`)。故 §3.2 的输出扩展名表仅作**声明/预期**用,实际以魔数为准。
2. **`.mgg` 解出后它强制归一为 `.m4a`**(`normalize_target_format` 把 `ogg→m4a`)。本项目**不跟**这个行为——`Cargo.toml:112` 已确认 symphonia 默认特性含 `ogg/vorbis`,直接落 `.ogg` 即可播,保持"所见即所得"(§3.1 原口径)。
3. QKKDecrypt 不支持 `.mflac0/.mgg1/.mflac1/.qmc*`——**我们的扩展面比它宽**(§4.3),但格式知识来源是 qmc-decoder 的**文档**(GPLv3,不抄代码)。
### A.2 借鉴到 P0 的一条设计(**最终未采用,附理由**)
QKKDecrypt 的 `file_finished.result` 含 `already_decrypted` 与 `stopped_by_user` 两个态。
**`stopped_by_user` 已采纳**(取消后 `finished.cancelled > 0`,任务落为"已取消")。
**`already_decrypted` 决定不做**:它要判断"某份已存在的产物是否就是本次输入的产物",
在扁平输出目录里只能靠文件名猜,猜错就静默跳过用户的文件——代价大于收益。
P0 改为**永不跳过**:目标名被占用就写 `<名>_1.<ext>`,宁可多一份产物也不丢工作。
(`ncm::unique_output` 同时处理"磁盘上已存在"与"本批次内已占用"两种情况。)
+303
View File
@@ -0,0 +1,303 @@
# 音乐模块 · 手机端连接与控制规划(Music Remote Plan)
> 状态:**规划中**(未开始实施)
> 定位:音乐模块的"手机互联"子能力,不是独立模块——挂靠 `music` 模块,Rust 侧新增 `music/remote/` 子系统
> 日期:2026-09-25
> 关联文档:`AI_DEV_GUIDE.md`(模块注册 / IPC 范式——注意其未涵盖 specta,绑定范例见 `lib.rs` 的 `export_bindings()`)、`TERMINAL_MODULE_PLAN.md`(规划文档范式)
> 对端文档:`F:\AtieProject\LFMusic\PLAN.md`(手机端 LFMusic 的功能与实现规划,协议以本文 §4(协议)/ §5(实现)为准)
---
## 0. 结论先行
四个关键判断,先摆在这里,后文展开论证:
1. **"获取电脑端正在播放的内容(不管是不是 Thing 播的)"必须走 GSMTC**(`GlobalSystemMediaTransportControlsSessionManager`),而不是扩展现有的 `smtc.rs`。`smtc.rs` 以"Thing → 系统"的元数据/进度上报为主(`ISystemMediaTransportControlsInterop::GetForWindow`),并经 `TypedEventHandler` 接收系统按钮回传(双向)——但它只管自己这条会话;要读到**系统里所有应用的媒体会话**(网易云、QQ 音乐、浏览器、Thing 自己……),唯一官方通道是 GSMTC 的全局会话管理器。两者方向相反、互不冲突,`smtc.rs` 原样保留。
2. **控制链路统一走 GSMTC 的 `Try*Async`,Thing 自己不特殊处理**。手机发的播放/暂停/切歌 → Thing 的 GSMTC 调用 → 系统把按钮事件派发给目标会话。Thing 自己因为已在 `smtc.rs` 注册了 SMTC 会话并有按钮事件回传链路(`music-smtc-button` → 前端执行),这条环路是现成的,**对 Thing 自身会话近乎零新增执行代码**(需补的是 cmd-ack 语义与派发时序定义,见 §4.2 / §5.2)。不要为 Thing 自建"直通 AudioEngine"的旁路——多一条路径就多一类不一致(P1 若延迟体感明显再优化)。
3. **局域网服务用 axum(已有依赖)新增 HTTP + WebSocket 双通道,发现用"电脑广播 beacon + 手动扫码"双保险**。axum 已在 `download_engine/server.rs` 和 `feiniu/proxy.rs` 两处落地,范式现成。发现协议不选 mDNS 做 P0 主路径:Android/iOS 的 mDNS 栈碎片化、路由器 AP 隔离下失效、iOS 后台受限;而电脑端周期性 UDP 广播 + 手机被动监听实现最简、权限最友好,配合二维码手动配对兜底已覆盖 99% 场景。mDNS 降级为 P1 增强。
4. **安全按"配对制"设计,不做裸奔**。首次连接用一次性配对码(Thing 弹窗展示,手机扫码/手输),换取长期设备 token;token 两侧持久化(Thing 侧入 keyring,手机侧入系统安全存储),后续连接 WS 握手鉴权,设置页可随时撤销设备。局域网明文 HTTP 在 P0 可接受(风险面:同网段已配对 token 泄露才会被利用),TLS 自签放 P2。
**工作量估算**:P0(系统会话捕获 + LAN 服务 + 发现配对 + 基础遥控)约 6~9 个工作日;P1(mDNS、多会话切换、系统音量、投播)约 5~8 个工作日;P2(TLS、队列投播完善)按需。
---
## 1. 需求解构
用户需求拆成可执行的规格:
| 用户原话 | 解构为 | 落点 |
|---|---|---|
| 「手机端 app 打开后自动连接局域网电脑上的 Thing」 | 电脑端局域网服务(HTTP+WS)+ 自动发现(UDP beacon)+ 配对与鉴权 | §3.2 / §3.3 / §3.4 |
| 「可以获取到电脑端正在播放的内容(不管是 Thing 自己播放的,或是其他应用播放的)」 | GSMTC 全局会话监视:当前活跃会话的元数据、进度、播放状态、封面 | §3.1 / §5.2 |
| 「显示例如歌曲名,歌手,专辑,封面,进度」 | `NowPlaying` 状态模型 + WS 增量推送 + 封面 HTTP 端点 | §4 / §5.2 |
| 「控制等等」 | 播放/暂停/上一首/下一首/seek/停止,走 GSMTC `Try*Async`;音量 P1 | §3.1 / §5.3 |
| (自然延伸,非本次明说) | 投播:手机选歌 → 电脑播放(Thing 曲库播放队列控制) | §7 P2 |
| 「打开后自动连接」的边界 | 首次需用户在电脑设置页点「连接手机」弹出配对码/二维码,5 分钟内完成一次配对;此后已配对设备才自动重连 | §3.4 / 对端文档 §5.1 |
---
## 2. 现状勘察(2026-09-25 从仓库实际读取)
### 2.1 已具备的基建(直接复用)
| 能力 | 现有实现 | 本功能可复用的部分 |
|---|---|---|
| 播放引擎 | `music/audio/engine.rs`:`AudioEngine`(symphonia + cpal/WASAPI 独立线程),`AudioState` 快照 + `music-audio-ended` / `music-audio-error` 事件 | Thing 自身播放状态的事实来源;封面/元数据兜底可直读播放队列 |
| SMTC 上报 | `music/smtc.rs`:`SmtcController`(GetForWindow 全字段上报 + 系统按钮事件 `music-smtc-button` 回传前端) | **零改动保留**;它让 Thing 拥有一条标准 SMTC 会话,GSMTC 控制才能作用到 Thing 自己 |
| HTTP 服务范式 | `download_engine/server.rs`、`feiniu/proxy.rs` 均为 axum + `tokio::net` | 新 LAN 服务照抄此范式(`axum::serve` + tokio) |
| WebSocket | `tokio-tungstenite 0.24` 已在依赖树 | 备选;WS 通道直接用 axum 的 `ws` feature 更统一 |
| 凭据存储 | `secrets.rs`(keyring + Windows 凭据管理器)、`music/secrets.rs` | 设备 token / 配对密钥持久化 |
| 类型绑定 | tauri-specta 自动生成 `src/lib/bindings.ts` | remote 命令与消息类型走 specta,前端零手写类型 |
| 设置持久化 | `MusicManager::load_settings / save_settings`(settings.json + 500ms 缓存) | remote 开关/端口等设置项追加到 `MusicSettings` |
| 日志 | `logger.rs` 统一日志 | remote 全链路日志 |
### 2.2 关键缺口(需新增)
| 缺口 | 现状 | 方案 |
|---|---|---|
| 系统媒体会话读取 | 无。`windows` crate 未开 `Media_Control` feature | 开启 feature,新增 `music/remote/glsmtc.rs`(见 §3.1) |
| 局域网服务 | axum 仅用于本机/代理场景,无对外 LAN 端点 | 新增 `music/remote/server.rs`,监听 `0.0.0.0` |
| 设备发现 | 无 | 新增 `music/remote/discovery.rs`(UDP beacon) |
| 配对与设备管理 | 无 | 新增 `music/remote/pairing.rs` |
| 二维码渲染 | 无 | 前端引入 `qrcode`/`qr-code-styling`(纯前端生成即可) |
---
## 3. 技术选型
### 3.1 系统媒体捕获:GSMTC
Windows 10 1809+ 的 `Windows.Media.Control` 命名空间是**唯一**能枚举/监视/控制系统全部 SMTC 会话的公开 API。凡是有标准系统集成(SMTC)的播放器——网易云、QQ 音乐、foobar2000、浏览器、以及 Thing 自己——都会出现在会话列表里。
Rust 侧路径:`windows` crate(当前 0.52)增加 `"Media_Control"` feature,类型位于 `windows::Media::Control`:
```rust
use windows::Media::Control::{
GlobalSystemMediaTransportControlsSessionManager,
GlobalSystemMediaTransportControlsSession,
};
```
核心 API 清单:
| API | 用途 |
|---|---|
| `SessionManager::RequestAsync()` | 取全局管理器单例(惰性初始化,失败则整个能力降级关闭) |
| `manager.GetSessions()` | 枚举所有会话——**同步**返回 `IVectorView`(0.52 投影无 Async 版本,计划原文 `GetSessionsAsync` 有误,以实测为准) |
| `manager.GetCurrentSession()` | 当前"活跃"会话(系统自动判定:最近操作的会话);**同步**,无会话时 ABI 返回 null → windows-rs 投影为 `Err(E_POINTER)`,按"无会话"分支处理。**实测修正:WinRT 没有 `SetCurrentSessionAsync`**——P1 多会话切换采用 Thing 侧"选中覆盖"(§7),不修改系统判定 |
| `session.SourceAppUserModelId` | 来源应用标识(用于显示"正在播放的应用",也作为会话 key) |
| `session.TryGetMediaPropertiesAsync()` | 元数据:Title / Artist / AlbumTitle / AlbumArtist / **Thumbnail** |
| `session.GetTimelineProperties()` | Position / EndTime / **LastUpdatedTime**(进度推算基准,见 §6.4) |
| `session.GetPlaybackInfo()` | PlaybackStatus / Controls(`IsPlayEnabled` 等能力位)/ PlaybackRate |
| `TryPlayAsync` / `TryPauseAsync` / `TryStopAsync` / `TrySkipNextAsync` / `TrySkipPreviousAsync` | 控制(即手机端全部按钮的实现) |
| `TryChangePlaybackPositionAsync(ticks)` | seek(仅当会话 `IsSeekEnabled`) |
| 事件:`CurrentSessionChanged` / `MediaPropertiesChanged` / `TimelinePropertiesChanged` / `PlaybackInfoChanged` / `SessionsChanged` | 状态变更推送源 |
**线程与套间**(沿用 `smtc.rs` 已验证的范式,但有一处关键差异):
- 初始化(`RequestAsync`)与事件订阅在**主线程**执行(`run_on_main_thread` 抛过去),与 `smtc.rs` 一致。
- **`Try*Async` 的 `.get()` 阻塞等待必须放专用工作线程**,不能在主线程 `.get()`——STA 上阻塞等待 WinRT async 有死锁风险,而 `smtc.rs` 那种"fire-and-forget 更新属性"不涉及等待所以没踩到。设计上:主线程只做"发起",等待统一丢给 `tokio::task::spawn_blocking` 或专用线程。
- 所有 GSMTC 对象是 agile 的,跨线程传引用安全(与 smtc.rs 注释同源结论)。
**失败策略**:与 `smtc.rs` 同哲学——GSMTC 任何一步失败只记日志,不影响播放;GSMTC 初始化失败时整个"远程查看/控制其他应用"能力降级为"仅 Thing 自身"(可从 `AudioEngine.state()` 兜底聚合,见 §5.2)。
### 3.2 局域网服务:axum HTTP + WebSocket
单端口(默认候选 **26124**,被占则 +1 重试至 26139,实际端口写进 beacon 与二维码):
| 端点 | 方法 | 用途 |
|---|---|---|
| `/ws` | GET(Upgrade) | 主通道:鉴权、状态推送(server→client)、控制指令(client→server) |
| `/api/state` | GET | REST 兜底快照(WS 不可用/调试用),Bearer token 鉴权 |
| `/cover/:hash` | GET | 封面字节流(内存缓存,`hash` 由状态推送携带,`?v=` 控制刷新),Bearer token(query 参数 `t=`,`<img>` 标签无法带 header);**访问日志不打印 query**,token 不落日志 |
| `/pair` | POST | 配对:`{ pairingCode, deviceName }` → `{ token, deviceId }` |
WS 承载双向消息(协议见 §4.2);HTTP 承载资源(封面)与低频操作。全部监听 `0.0.0.0`。
**防火墙注意**:首次监听 LAN 端口 Windows 会弹防火墙授权(专用网络勾选即可)。在设置页 remote 开关旁给出说明文案;不做 `netsh` 自动加规则(改系统防火墙属于越权行为,且需要管理员)。
### 3.3 设备发现:UDP beacon(P0 主)+ 扫码兜底(P0)+ mDNS(P1)
| 方案 | 机制 | 判断 |
|---|---|---|
| **UDP beacon(推荐 P0)** | 电脑每 3s 向 `255.255.255.255:26123` 与各网卡定向广播地址发 JSON 包:`{ "service": "thing-music", "deviceId", "name", "port", "protoVer" }`;手机监听 26123 被动收集 | 实现最简(一个 tokio interval + UdpSocket);手机端只需 bind 收包,**Android 免多播权限问题,iOS 不触发 multicast entitlement**(仍会触发本地网络权限弹窗,属正常) |
| 扫码/手输(P0 兜底) | Thing 设置页展示二维码:`thingmusic://connect?ip=…&port=…&code=…`;手机扫码或手输 IP+配对码 | AP 隔离下 beacon 不可达时的最后手段;同时它就是配对入口(见 §3.4) |
| mDNS(P1 增强) | `mdns-sd` crate 注册 `_thingmusic._tcp.local.`,手机 browse | 生态标准、后台发现友好;但依赖各端 mDNS 栈质量,放 P1 不阻塞 |
beacon 里**不含**任何敏感信息(无 token、无配对码),只描述"这里有一个 Thing 音乐服务"。手机端根据 deviceId 去重。
### 3.4 安全与配对
流程(对齐业界遥控 App 的标准做法):
1. 手机端发起配对:beacon 得到 ip:port 后 POST `/pair`,携带 6 位一次性配对码 + 设备名。
2. 配对码由 Thing 侧生成:用户在设置页点击「连接手机」→ 弹窗展示 6 位码 + 二维码(码内含 ip/port/code,扫码即完成 1、2 两步),有效期 5 分钟,一次性。
3. 校验通过 → 生成 32 字节随机 hex 设备 token,返回手机;Thing 侧持久化 `{deviceId, deviceName, token}` 到 keyring(复用 `secrets.rs` 范式),列表落 settings。
4. 后续连接:WS 握手首条消息 `hello { token }`(或 HTTP `Authorization: Bearer`),校验失败 3 次即拉黑该 IP 60s;`/pair` 的配对码校验执行同一限速(防 6 位码爆破,配对响应也只在成功时下发 token)。
5. 设置页设备列表:展示在线/离线、最后连接时间,可撤销(吊销 token)。
P2 增强:自签 TLS(`rcgen` 生成 + `rustls`,二维码里带证书指纹)。P0 明文 HTTP 的风险面评估:同局域网内明文嗅探只能看到 token 之后的媒体元数据;token 本身仅在配对响应中明文传输一次,可接受。
---
## 4. 状态模型与协议设计
### 4.1 `NowPlaying`(核心状态, specta 类型双端共享)
```typescript
interface NowPlaying {
sessionId: string // 会话 key(SourceAppUserModelId;Thing 自身 = "thing.self")
sourceApp: string // 来源应用显示名(AUMID 末段或注册表友好名)
isThing: boolean // 是否 Thing 自身播放(决定封面/元数据兜底来源)
title: string
artist: string
album: string
coverHash: string | null // 封面缓存键;封面从 /cover/:hash 拉
status: 'playing' | 'paused' | 'stopped'
durationSec: number
positionSec: number // 推送时刻的位置
positionUpdatedAtMs: number // 电脑时钟毫秒(源自 TimelineProperties.LastUpdatedTime,见 §6.4);仅供校准,手机端 elapsed 一律以本地收包时刻起算(见 §6.10)
playbackRate: number
canControl: { play: boolean; pause: boolean; next: boolean; prev: boolean; seek: boolean }
deviceId: string // 电脑标识(多电脑预留)
}
```
### 4.2 WS 消息(JSON,`type` 字段区分)
| 方向 | type | 载荷 | 时机 |
|---|---|---|---|
| c→s | `hello` | `{ token, deviceName, protoVer }` | 连接后首条;失败即断开 |
| s→c | `welcome` | `{ deviceId, deviceName, protoVer }` | 鉴权通过 |
| s→c | `state` | `NowPlaying`(全量) | 连接后、以及任何变更(见 §6.3 节流;**由 `cmd` 触发的变更立即推一帧,绕过节流**) |
| c→s | `cmd` | `{ id, action, args? }`,action ∈ `play / pause / toggle / next / prev / stop / seek(posSec)` | 用户操作 |
| s→c | `cmd-ack` | `{ id, ok, error? }` | 回执语义 = **"指令已被接受/派发"**(GSMTC 路径 = Try*Async 完成;前端兜底路径 = 事件已投递),不代表播放状态已切换;UI 轻提示,真实状态以随后的 `state` 为准 |
| c→s | `ping` / s→c `pong` | `{ ts }` | 30s 心跳,双向判活 |
版本策略:`protoVer` 从 1 起,不匹配时 `welcome` 带最新版本号,手机端提示升级。
---
## 5. 架构与模块设计
### 5.1 Rust 侧:`src-tauri/src/music/remote/`
```
src-tauri/src/music/remote/
├── mod.rs # RemoteManager:manage() 进 State;启动/停止服务与 beacon;开关状态
├── server.rs # axum app:路由 /ws /api/state /cover /pair;WS 会话表(fanout 广播)
├── glsmtc.rs # GsmtcMonitor:GSMTC 初始化、事件订阅 → 聚合 NowPlaying → 广播
├── discovery.rs # UdpBeacon:3s 周期广播(255.255.255.255 + 各网卡定向广播)
├── pairing.rs # 配对码生成/校验、设备 token 签发、设备表(keyring + settings)
└── proto.rs # NowPlaying / WS 消息类型(serde + specta,前端 bindings 自动生成)
```
数据流:
```
GSMTC 事件(主线程订阅)──→ GsmtcMonitor 聚合/节流 ──→ Server 广播到全部 WS 客户端
AudioEngine.state()(兜底聚合,isThing 时封面/元数据来源之一)┘
手机 cmd ──→ server.rs ──→ glsmtc.rs(spawn_blocking 调 Try*Async)──→ 系统派发给目标会话
└─ Thing 自身会话:SMTC 按钮 → smtc.rs 既有链路 → 前端 feiniuStore 执行(既有链路,约束见 §5.2)
```
`MusicManager` 增加 `remote: RemoteManager` 字段(或平级 manage,倾向后者,避免 MusicManager 继续膨胀);`lib.rs` 注册 `remote_*` 系列命令:
| 命令 | 用途 |
|---|---|
| `remote_get_config` / `remote_set_enabled` | 开关(MusicSettings 追加 `remote_enabled`、`remote_port`) |
| `remote_status` | 服务状态、端口、在线设备 |
| `remote_start_pairing` | 生成配对码 + 二维码 payload(前端渲染二维码) |
| `remote_cancel_pairing` | 取消 |
| `remote_list_devices` / `remote_revoke_device` | 设备管理 |
### 5.2 双来源聚合规则(GSMTC 为主,AudioEngine 兜底)
- GSMTC 可用:一切以 GSMTC 当前会话为准。Thing 自身播放时它就是一条普通会话(`SourceAppUserModelId` 识别后标 `isThing: true`)。
- GSMTC 无会话但 `AudioEngine` 在播放(GSMTC 初始化失败或会话丢失的兜底):从 `AudioEngine.state()` + 播放队列聚合出 `NowPlaying`(`isThing: true`);控制指令由 server 复用 `music-smtc-button` 事件(同名、同 payload)emit 给前端执行。**既有架构约束**:队列控制逻辑(toggle/next/prev/播放模式)在前端 `feiniuStore`,AudioEngine 本身只有 play/set_playing/seek/stop——兜底路径依赖 WebView 存活,WebView 未就绪时直接回 `cmd-ack { ok: false, error: "frontend-unavailable" }`。
- 两者都无:`status: 'stopped'`,手机端显示"电脑未在播放"。
### 5.3 前端侧
- `src/modules/music/components/settings/RemoteSettings.vue`:总开关、端口、设备列表(在线状态/撤销)、「连接手机」按钮 → 配对码 + 二维码(`qrcode` 库,5s 轮询 status 刷新倒计时/在线态)。
- 状态存放:P0 用 RemoteSettings **组件本地状态**(5s 轮询 `remote_status`),不扩 musicStore——当前无其他消费方;遥控 UI 出现共享需求时再入 store。
- `constants.rs`:`REMOTE_WS_*` 等消息类型常量(如需要);本功能的"事件"主要是 WS 而非 Tauri event,前端基本只走 invoke + bindings。
### 5.4 生命周期
- 随应用启动初始化(不随模块启用——music 默认启用且常驻),`remote_enabled = false` 时仅不启服务/beacon,GSMTC 监视可保持惰性。
- 应用退出:axum graceful shutdown、beacon 停发(`cleanup_on_exit` 挂钩,参照 `MusicManager::cleanup_on_exit` 范式)。
- 系统休眠/网络切换:WS 断开由心跳判活;beacon 无状态持续广播即可,无需额外处理。
---
## 6. 关键实现细节与已知的坑
1. **GSMTC 在非打包桌面应用可用**(unpackaged desktop app 明确支持,1809+)。不要被"WinRT 需要 package identity"的泛泛说法劝退——GSMTC 不在受限之列,开源社区大量此类工具可佐证。**2026-09-25 已实证**:`examples/gsmtc_probe.rs`(unpackaged 控制台进程)跑通,读到当前会话元数据/状态/时间轴,核心假设成立。
2. **封面(Thumbnail)是 `RandomAccessStreamReference`**:`OpenReadAsync()` → 按 `ContentType`(image/png|jpeg)读全量字节 → 以 `hash(sourceApp + title + album + 尺寸)` 为键存内存 LRU(上限 ~20 张)。推送里只带 `coverHash`,封面走 HTTP 拉取,避免 WS 帧被几百 KB 图片打爆。
3. **事件风暴节流**:`TimelinePropertiesChanged` 在部分播放器上高频触发(每次内部时钟更新都发)。聚合层统一节流:任何状态变更合并后**最快 1Hz** 推送 `state`;进度靠手机端 `positionSec + elapsed` 本地推算(`status=playing` 时每秒 +1,收到新 `state` 校准),不依赖高频推送。**例外**:由 `cmd` 触发的状态变更立即推一帧(绕过 1Hz 节流),避免按钮"没反应"的体感——节流仅约束进度等自然高频变更。
4. **进度推算基准用 `TimelineProperties.LastUpdatedTime`**,不要用"收到事件的本地时刻"——事件分发有延迟,`LastUpdatedTime` 是播放器侧的权威时间戳。(本条约束 **Thing 侧**把 GSMTC 事件组装成 `positionSec/positionUpdatedAtMs` 的动作;**手机侧** elapsed 的起算基准见 §6.10,两层不要混用。)
5. **会话 key 的稳定性**:GSMTC 无显式 sessionId,用 `SourceAppUserModelId` 作 key;同一应用双会话(极少见)时后者覆盖前者,P1 的多会话切换再处理。
6. **`Try*Async` 的返回值不可全信**:部分播放器对不可用操作静默成功,回执只做 UI 轻提示,真实状态以下一帧 `state` 为准(`canControl` 能力位已尽力过滤)。
7. **AUMID → 友好名**:`SourceAppUserModelId` 是 `PackageFamilyName!App` 或注册表 AUMID,显示名需查 `Get-StartApps` 等价逻辑(注册表 `HKCU\Software\Classes\AppUserModelId`);先显示末段兜底,友好名缓存 LRU。
8. **防火墙弹窗只出现一次**(每个 exe 路径 × 网络类型),开发期 `tauri dev` 与正式版 exe 路径不同会各弹一次,属预期。
9. **Windows 通知区域"媒体"浮层与 GSMTC 互不干扰**:`smtc.rs` 的上报会话照常工作;手机控制 Thing 自身时,系统面板同步可见,是 feature 不是 bug。
10. **进度推算的时钟基准分两层,不要混用**:Thing 侧组装 `positionSec/positionUpdatedAtMs` 用 `TimelineProperties.LastUpdatedTime`(§6.4);手机侧 `elapsed` **一律以本地收到该条 `state` 的时刻起算**,禁止拿 `positionUpdatedAtMs` 与手机本机时间直接做差——电脑时钟偏差(手动对时/休眠漂移可差数秒以上)会整体拖偏进度条。手机端检测到两端时钟偏差 >5s 时冻结推算、只显示基准值,等待下一条 `state` 校准。两端时钟正常时(NTP 同步)此方案残差 ≤ 推送延迟(LAN 上 <1s,且播放中 ~1Hz 校准)。
---
## 7. 分阶段计划
### P0:可用版本(目标:手机能看到并控制电脑当前播放)
- [x] `windows` crate 开 `Media_Control` feature;10 行探测 demo 验证 GSMTC 在本机可用 —— **2026-09-25 实测通过**(`examples/gsmtc_probe.rs`,unpackaged 控制台进程:读到 1 会话 + 元数据/状态/时间轴全通;注意 `GetSessions`/`GetCurrentSession` 是同步 API,见 §3.1)
- [x] `remote/proto.rs`:类型定义(serde,未进 specta——WS 对端是手机,Thing 前端不消费)+ 单测(序列化往返/时间换算/会话 key)——**2026-09-26 完成,8 单测全绿**
- [x] `remote/glsmtc.rs`:初始化、事件订阅、`NowPlaying` 聚合、封面 LRU、节流(1Hz + cmd Force 例外)——**完成**;订阅 P0 只挂 Manager 级两事件 + 500ms 节拍轮询(会话级事件需随会话订阅/退订,列入 P1)
- [x] `remote/server.rs`:axum 路由 + WS 会话表 + 广播 + 心跳判活 + Bearer/hello 鉴权(+ /pair 限速、封面 token 走 query)——**完成**
- [x] `remote/discovery.rs`:UDP beacon(GetAdaptersAddresses 各网卡定向广播)——**完成**
- [x] `remote/pairing.rs`:配对码 + token 签发 + 设备表(keyring `music-remote-token-*`)——**完成**(单测含限速)
- [x] 控制指令:play/pause/toggle/next/prev/stop/seek → `Try*Async`(spawn_blocking);**Thing 自身 seek 直通 AudioEngine**(SMTC 回环无 seek 通道)——**完成**
- [x] 命令注册(collect_commands + generate_handler 双处)+ `RemoteSettings.vue`(开关/配对二维码/设备列表;qrcode 库前端生成)——**完成**;改为组件本地状态,不扩 musicStore(当前无其他消费方,需要时再入 store)
- [x] `AudioEngine` 兜底聚合(+ `SmtcMetaCache` 回填标题/歌手/专辑)——**完成**
- [x] 运行时冒烟(2026-09-26):自启绑定 `0.0.0.0:26124` ✓、beacon 实收(`addrs=["192.168.110.40"]`、deviceId 落盘)✓、`/api/state` 401 ✓、`/pair` 错码 403 ✓、日志「GSMTC 已初始化(专用线程 MTA)」✓、运行时 bindings 导出含 remote 命令 ✓
- [x] 联调:**真机 E2E 完成(2026-09-26)**——LFMusic 真机客户端全流程实测:配对码 142919 → `/pair` 成功(192.168.110.27)→ WS hello 鉴权 → state 推送(封面/元数据/thing.self/能力位)→ 播放暂停上下首控制生效 → App 重启后自动重连。过程修复:手机端 deviceId 语义(存电脑 id 而非 Thing 分配的行 id)与对端显示名两处关联 bug
- [ ] P0 验收口径(联调时执行):遥控界面显示 GSMTC `GetCurrentSession` 判定的活跃会话("最近操作"语义,多会话切换只留 UI 入口);进度推算按 §6.10 时钟基准联调;`cmd` 后 1s 内看到状态变化
### P1:体验完善 —— **2026-09-26 除两项暂缓外全部完成**
- [ ] mDNS 发现(mdns-sd 注册 `_thingmusic._tcp`)——**暂缓**:beacon 在目标网络 100% 可用且扫码兜底已覆盖;双端 mDNS(含 Android MulticastLock/Kotlin 桥)成本高、当前无失效场景驱动,等 beacon 实际失效案例再做
- [x] 多会话列表与手动切换——**完成**:`sessions` WS 消息(watch 变化推送 + 连接首帧)+ `select` 动作(**WinRT 无 SetCurrentSession,实测修正**:Thing 侧选中覆盖,空 id = 跟随系统 current;选中会话消失自动回落);手机端 chips UI(高亮 `isCurrent`)+「跟随系统」
- [x] **会话级事件精细化订阅**——**完成**:`SessionSubs` 随目标会话换绑 `MediaPropertiesChanged`/`TimelinePropertiesChanged`/`PlaybackInfoChanged`(切换时先退订后订阅,线程退出统一清理);Manager 级两事件 + 500ms 节拍轮询保留为保底
- [x] 系统音量控制 + 手机端音量条——**完成**:`volume.rs`(MMDevice → `IAudioEndpointVolume`,每次现取 COM 对象避免 Send/Sync 争议);监视线程 500ms 轮询进 `NowPlaying.volume/muted`(指纹纳入、变化即推);`volume` 动作 0~1、**>0 自动解除静音**;手机端 🔊 音量条(松手发送)
- [x] Thing 直通控制路径评估——**评估结论:落地直通**:`isThing` 按钮类指令直接 emit `music-smtc-button`(跳过 GSMTC→系统→SMTC 回环,少一跳系统派发延迟);seek 本就直通 AudioEngine;非 Thing 会话仍走 GSMTC `Try*Async`。系统面板同步不受影响(面板状态由前端持续上报 smtc.rs)。**真机复测**:非 Thing 路径(QQMusic 播放恢复)通过;isThing 直通与 P0 事件链同码,待 Thing 下次自身播放时自然覆盖
- [x] AUMID 友好名缓存、封面本地持久化缓存——**完成**:`friendly_name`(`HKCU\Software\Classes\AppUserModelId\<aumid>\DisplayName` 查询 + 128 条缓存,查不到退回 AUMID 简化段;路径形 AUMID 跳过注册表);`CoverStore` 写透 `{app_data}/remote_covers`(内存+磁盘双层 LRU 各 20 张,冷启动可回源)。**真机复测**:友好名生效(QQMusic / Microsoft.ZuneMusic);持久化目录已创建,落盘写入待下次取到封面时自然验证(当前可见会话均无缩略图)
- [ ] 手机端通知栏/锁屏媒体控件联动(LFMusic 侧 native-audio / MediaSession,见对端文档)——**暂缓**:被 LFMusic M1(集成 `tauri-plugin-native-audio`)阻塞,M1 完成后按对端文档回填
### P2:增强(按需)
- [ ] 自签 TLS(rcgen + rustls,二维码带证书指纹)
- [ ] 投播:手机浏览 Thing 曲库 → 远程下发放进 Thing 播放队列(`/queue` 端点 + AudioEngine 队列 API 暴露)
- [ ] 歌词推送(Thing 已有 lyric 能力,同步到手机端滚动显示)
- [ ] 多电脑:beacon 天然支持,配对表按 deviceId 区分,UI 侧完善
---
## 8. 风险与开放问题
| 风险/问题 | 影响 | 对策 |
|---|---|---|
| GSMTC 某播放器不上报专辑/封面(上报方行为,非 bug) | 手机端显示缺字段 | UI 兜底占位;Thing 自身播放时从曲库元数据补全(lofty 已有) |
| 路由器 AP 隔离导致广播不可达 | 手机发现不了电脑 | 扫码/手输 IP 兜底(P0 已含);mDNS 同样受影响,不是银弹 |
| 防火墙/杀软拦截 LAN 监听 | 手机连不上 | 设置页说明 + 连接失败诊断提示(检测本机端口监听、提示放行) |
| 手机休眠断 WS | 状态不实时 | 心跳 + 重连退避(手机端职责,见对端文档);恢复前台即拉 `/api/state` 快照 |
| `TryChangePlaybackPositionAsync` 部分应用不支持 | seek 无效 | `canControl.seek` 能力位隐藏进度条拖动 |
| 多网段/VPN 虚拟网卡产生杂音 beacon | 发现列表脏数据 | beacon 携带本机各网卡地址,手机端按连通性优选;显示名可区分 |
**开放问题**(实施前确认):
1. 是否需要"电脑端显示已连接手机"的托盘/OSD 提示?(倾向 P1,托盘菜单加一行在线设备数即可)
2. 投播的队列控制 API 形态(P2 前与 LFMusic 端一起定)。
3. 遥控界面是否需要歌词显示?用户需求"显示音乐信息"是否含歌词——Thing 已有 lyric 能力,但"歌词推送"列在 P2,需两端确认是否提前。
4. 音量控制是否提前到 P0?用户"控制电脑端"可能隐含音量——当前计划在 P1(`IAudioEndpointVolume`)。
File diff suppressed because it is too large. Load diff
+797
View File
@@ -0,0 +1,797 @@
# Thing UI 设计系统与开发约束
> **适用范围**:`src/` 下全部前端代码(12 个模块、220+ 组件)
> **约束力**:第 7 章为硬性约束,Code Review 据此判定;第 3–5 章为实现规范
> **配套**:`UI Design System` 画布(色彩 / 排版 / 组件 / 骨架四屏可视化规范)
> **唯一事实来源**:token 值以 `src/style.css` 为准,本文档与之同步
---
## 1. 设计原则
以下 8 条为不可协商项,贯穿全部模块。
**P1 · 单一强调色**
全应用只有 `--primary` 一种交互色,用于按钮、链接、选中态、焦点环。不存在"第二个主题色"。状态色(success/warning/danger)仅表达**状态**,不得用于可点击元素。
**P2 · 颜色只能来自 token**
禁止在组件内写 hex、rgb、oklch,禁止引用 Tailwind 原生色阶(`bg-blue-500`、`text-emerald-700`)。组件里出现的每个颜色都必须能追溯到 `style.css` 的一个语义变量。
**P3 · 状态必须四态齐全**
任何数据驱动的界面必须实现 **加载 / 空 / 错误 / 成功** 四态。禁止空白,禁止静默失败。这是最容易漏、也最影响质感的一条。
**P4 · 一个主区域,一个主操作**
每屏有且仅有一个视觉重心、一个主按钮。破坏性操作(停止内核、删除记录)必须视觉降级或二次确认,且不得与主操作同权重。
**P5 · 骨架统一,内容区自治**
所有模块共享同一套外壳(侧边栏 / 标题栏 / Tab 行)。**模块之间允许不同的只有内容区布局**——这是"统一"与"灵活"的分界线。
**P6 · 密度一致**
全应用统一使用**紧凑偏中**密度:13px 正文、34px 控件、16px 卡片内边距。禁止在同一屏内混用疏密两种节奏。
**P7 · 卡片统一描边 + 轻阴影,浮层用重阴影**
层级靠**表面色差 + 1px 描边 + 轻阴影(`shadow-sm` / `--shadow-card`)**表达。浮层(下拉、气泡、对话框)使用更重的 `--shadow-popover` / `--shadow-dialog`。
**P8 · 中文界面不做负字距**
字体模板中的负字距(`-0.28px` 等)是为拉丁字母设计的,会让中文发挤。**拉丁文与数字可保留微调,中文一律 `letter-spacing: 0`。**
---
## 2. Design Token
### 2.1 命名与结构
Token 分四组,**在现有 shadcn 变量之上扩展,不另起一套**:
```
shadcn 既有(值调整) → --background / --foreground / --primary / --card / --border / ...
本项目扩展 → --canvas / --fg-* / --success / --warning / --data-* / --shadow-*
```
**关键调整**:把 shadcn 的 `--primary` 从当前近黑色(`oklch(0.21 0.006 285.885)`)改为强调蓝 `#0066CC`。这样全部 shadcn 组件(Button / Switch / Checkbox / focus ring)自动获得统一的交互色,无需逐组件改样式。
### 2.2 色彩
#### 浅色模式(`:root`)
```css
:root {
/* ── 表面 ───────────────────────────── */
--canvas: #F5F5F7; /* 应用底 / 模块内容区背景 */
--background: #FFFFFF; /* shadcn 基准面 */
--card: #FFFFFF; /* 卡片 / 面板 */
--popover: #FFFFFF; /* 浮层 */
--subtle: #F0F0F2; /* 次级填充:搜索框底、分段控件槽、代码块 */
--hover: #EBEBED; /* 通用中性 hover:按钮、菜单项、数据表、导航 */
--active: #E4E4E7; /* 幽灵控件 active */
--row-hover: #EBF3FB; /* 内容行 hover(= primary 8% 混入 card,随主题色变) */
--row-selected: #D9E8F7; /* 内容行选中(= primary 15% 混入 card) */
--row-hover-veil: color-mix(in srgb, var(--primary) 16%, transparent); /* mica 弹窗行 hover */
--row-selected-veil: color-mix(in srgb, var(--primary) 30%, transparent); /* mica 弹窗行选中 */
/* ── 描边 ───────────────────────────── */
--border: #E4E4E7; /* 卡片外框、输入框 */
--border-strong: #D1D1D6; /* 需要更强分隔时 */
--divider: #F0F0F2; /* 卡片内部分隔线(1px) */
--input: #E4E4E7;
/* ── 文字 ───────────────────────────── */
--foreground: #1D1D1F; /* 主文字:标题、正文、数值 */
--fg-secondary: #55555C; /* 次文字:键名、标签说明、幽灵控件文字 */
--muted-foreground: #8A8A90; /* 辅助:占位符、规格说明、次级 meta */
--fg-disabled: #B4B4BA; /* 禁用 */
/* ── 强调 ───────────────────────────── */
--primary: #0066CC;
--primary-hover: #0055B3;
--primary-active: #004A9E;
--primary-foreground: #FFFFFF;
--primary-soft: #E8F1FC; /* 选中 Tab 底、选中行底 */
--primary-soft-text: #004F9E; /* 上述底上的文字 */
--ring: #0071E3;
/* ── 语义状态 ───────────────────────── */
--success: #0F7B4F; --success-soft: #E7F5EE; --success-text: #0B5C3B;
--warning: #A96B00; --warning-soft: #FDF4E4; --warning-text: #7D4F00;
--danger: #C7362F; --danger-soft: #FDECEA; --danger-text: #9A2620;
--info: #0066CC; --info-soft: #E8F1FC; --info-text: #004F9E;
--neutral: #8A8A90; --neutral-soft: #F0F0F2; --neutral-text: #55555C;
--destructive: #C7362F; /* shadcn 兼容别名,指向 danger */
--destructive-foreground: #FFFFFF;
/* ── 数据方向(与状态语义解耦)───────── */
--data-down: #0F7B4F; /* 下载 / 入站 */
--data-up: #C7362F; /* 上传 / 出站 */
/* ── 尺寸 ───────────────────────────── */
--radius: 12px;
--radius-xs: 4px; --radius-sm: 6px; --radius-md: 8px;
--radius-lg: 12px; --radius-xl: 16px;
/* ── 阴影 ───────────────────────────── */
--shadow-card: 0 1px 2px rgba(0,0,0,0.06);
--shadow-popover: 0 1px 3px rgba(0,0,0,0.06), 0 4px 16px rgba(0,0,0,0.10);
--shadow-dialog: 0 4px 12px rgba(0,0,0,0.08), 0 20px 48px rgba(0,0,0,0.16);
}
```
#### 深色模式(`.dark`)
深色下**必须成对重定义**,且强调色改为亮蓝(`#0066CC` 在深底上对比度不足):
```css
.dark {
--canvas: #16161A;
--background: #16161A;
--card: #1E1E22;
--popover: #1E1E22;
--subtle: #26262B;
--hover: #2C2C32;
--active: #33333A;
--row-hover: #1F2B3A; /* = primary 11% 混入 card(深色下用更高强度) */
--row-selected: #213E5C; /* = primary 26% 混入 card */
/* --row-*-veil 刻意不在此重写:半透明叠在壁纸上,深浅由 --primary 自动决定 */
--border: #2E2E34;
--border-strong: #3A3A42;
--divider: #26262B;
--input: #2E2E34;
--foreground: #F5F5F7;
--fg-secondary: #A8A8B0;
--muted-foreground: #7A7A82;
--fg-disabled: #55555C;
--primary: #2997FF;
--primary-hover: #4AA8FF;
--primary-active: #1A85E8;
--primary-foreground: #FFFFFF;
--primary-soft: #14304D;
--primary-soft-text: #7FC0FF;
--ring: #2997FF;
--success: #3DC77F; --success-soft: #12301F; --success-text: #7FE0AB;
--warning: #E0A83C; --warning-soft: #33260E; --warning-text: #F0C976;
--danger: #FF6B60; --danger-soft: #3A1A18; --danger-text: #FF9E96;
--info: #2997FF; --info-soft: #14304D; --info-text: #7FC0FF;
--neutral: #7A7A82; --neutral-soft: #26262B; --neutral-text: #A8A8B0;
--destructive: #FF6B60; --destructive-foreground: #FFFFFF;
--data-down: #3DC77F;
--data-up: #FF6B60;
}
```
#### 状态色三件套的用法
每个语义状态有 **3 个** token,用途严格区分:
| Token | 用途 | 示例 |
|---|---|---|
| `--success` | 实心:状态点、图标、粗体数值 | ● 运行中 的圆点 |
| `--success-soft` | 浅底:徽章背景、行高亮 | `<span class="bg-success-soft">` |
| `--success-text` | 浅底上的文字 | 徽章内的"已安装" |
**禁止**把 `--success` 用作文字色 + `--success-soft` 以外的底色组合,也**禁止**用状态色做可点击元素的颜色(见 P1)。
#### 强调色的使用边界
`--primary` 只表达两件事:**这里可以点**、**这里是当前项**。
| 用 | 不用 |
|---|---|
| 主按钮底色、开关开启态、焦点环 | 卡片标题前的**装饰性图标** |
| 当前 Tab / 选中列表行 / 选中项 | 全部 Tab 的图标 |
| 可点击的文字链接 | 状态徽章(那是状态语义色的职责) |
| 输入框聚焦态 | 大面积背景、分隔线、装饰元素 |
**反例(已修正)**:proxy 概览页的 6 个卡片标题图标全部用了 `text-primary`,加上主按钮、开关、选中态,整屏发蓝 —— 结果"蓝色"不再意味着"可点击",层次感也丢了。已统一改为 `--fg-secondary`。
#### 数据方向色(`--data-*`)
下载/上传速率沿用现有视觉(绿/红),但独立成 token,**与 `success/danger` 解耦**。
> **待决策**:当前 `data-up` 与 `danger` 同色,会让人把"上传速率"误读为"异常"。若希望彻底解耦,建议改为
> `--data-down: #0066CC`(蓝)/ `--data-up: #A96B00`(琥珀)。这是**唯一改动成本为零**的时机——只需改两个 token。
### 2.3 排版
字体族保持不变(现有 `--font-sans` 已正确针对中文优化):
```css
--font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI',
'Microsoft YaHei', 'PingFang SC', 'Noto Sans SC', sans-serif;
--font-mono: 'JetBrains Mono', 'Cascadia Code', Consolas, monospace;
```
生产代码不引用外部字体 CDN(设计稿 / 原型页可保留 Inter);数值对齐通过全局 `font-feature-settings: 'tnum','lnum'` 实现,不依赖具体字体。
字号标尺(9 级,全部为 `px`):
| Token | 字号 / 字重 | 行高 | 用途 |
|---|---|---|---|
| `display` | 28 / 700 | 36 | 页面级大标题(设置页、关于页),**全应用不超过 1 处/屏** |
| `metric` | 22 / 600 | 28 | 关键数值(速率、容量)· **必须 `font-variant-numeric: tabular-nums`** |
| `h1` | 16 / 600 | 24 | 模块标题、卡片标题 |
| `h2` | 14 / 600 | 20 | 区块标题、卡片标题(小卡) |
| `h3` | 13 / 600 | 20 | 小节标题、列表分组标题 |
| `body` | 13 / 400 | 20 | **界面默认正文** |
| `body-strong` | 13 / 600 | 20 | 行内强调、键值行的键 |
| `caption` | 12 / 400 | 18 | 辅助说明、参数解释 |
| `label` | 11 / 500 | 16 | 徽章、标签、表头、单位 |
**规则**:
1. 字号只从以上 9 级中取,**禁止 `text-[13.5px]` 这类任意值**。
2. 数值(速率、版本号、计数)统一用 `tabular-nums`,避免刷新时数字跳动。
3. 中文 `letter-spacing: 0`;拉丁小标题可 `-0.1px`,正文一律 `0`。
4. 行高按表中固定值写,不用 Tailwind 默认相对行高。
### 2.4 间距
4px 基数,**8 个值,用尽即止**:
| Token | 值 | 典型用途 |
|---|---|---|
| `space-1` | 4 | 图标与文字间隙、徽章内边距(纵向) |
| `space-2` | 8 | 控件内元素间隙、徽章内边距(横向) |
| `space-3` | 12 | 列表行内间隙、卡片标题与内容间距 |
| `space-4` | 16 | **卡片内边距、卡片间距** |
| `space-5` | 20 | **模块内容区默认内边距** |
| `space-6` | 24 | 区块之间、对话框内边距 |
| `space-8` | 32 | 大区块分隔 |
| `space-12` | 48 | 页面级分段 |
**禁止** `p-[18px]`、`gap-[14px]`、`mt-[6px]`。需要更细的调整时,说明是布局问题而非间距问题。
### 2.5 圆角
| Token | 值 | 适用 |
|---|---|---|
| `radius-xs` | 4 | 内联小元素:标签内块、进度条端点 |
| `radius-sm` | 6 | 徽章、小按钮、下拉项 |
| `radius-md` | 8 | **按钮、输入框、下拉框、分段控件、Tab 项** |
| `radius-lg` | 12 | **卡片、面板、样张容器** |
| `radius-xl` | 16 | 对话框、大浮层 |
| `radius-full` | 9999 | 状态点、开关、头像、搜索框(胶囊) |
**规则**:同层级控件必须同圆角。按钮 8px 就全应用 8px,不允许某模块用 6px。
### 2.6 阴影与层级
**层级主要靠表面色差 + 描边 + 轻阴影**(P7):
| 层级 | 表现 | 用途 |
|---|---|---|
| L0 应用底 | `--canvas`,无描边无阴影 | 窗口、模块内容区 |
| L1 卡片 | `--card` + 1px `--border` + 轻阴影 `shadow-sm` | 所有卡片、面板 |
| L1.5 次级容器 | `--subtle`,无描边 | 搜索框底、分段控件槽、代码块 |
| L2 浮层 | `--card` + `--shadow-popover` | 下拉菜单、气泡、tooltip、右键菜单 |
| L3 模态 | `--card` + `--shadow-dialog` + 遮罩 | 对话框、AlertDialog |
卡片默认使用轻阴影 `--shadow-card`(`shadow-sm`);`--shadow-popover` / `--shadow-dialog` 仅用于浮层与模态。
### 2.7 动效
```css
--ease-standard: cubic-bezier(0.22, 0.61, 0.36, 1); /* 沿用现有 tab-animate 曲线 */
--duration-fast: 120ms; /* hover、颜色变化 */
--duration-base: 200ms; /* 展开、浮层出现 */
--duration-slow: 320ms; /* 页面/Tab 切换 */
```
**规则**:
1. 只对 `opacity` 和 `transform` 做动画(性能)。
2. 按钮按下统一 `transform: scale(0.97)`,不用颜色变化模拟按压。
3. 所有动画必须包在 `@media (prefers-reduced-motion: reduce)` 里降级为 `none`(现有 `.music-eq` 已正确实现,作为模板)。
4. Tab 切换复用现有全局 `.tab-animate` 类,**不要各模块自建过渡**。
### 2.8 图标
- 库:`@lucide/vue`,**禁止混用其他图标库或内联 Unicode 符号**(`↓` `✓` `●` 等)。
- 尺寸只有 3 档:`14`(行内 / 徽章内)、`16`(按钮、Tab、默认)、`20`(侧边栏、卡片标题)。
- `stroke-width` 统一 `1.75`(lucide 默认 2,偏粗,与 13px 正文不协调)—— 在 `style.css` 里对 `.lucide` 全局设置,不要逐个组件写。
- 图标**不单独承载语义**:状态点旁必须有文字,工具栏图标必须有 tooltip 或文字标签(P4 可理解性)。
### 2.9 主题色自定义(已落地)
**需求**:设置页提供主题色选择,统一改变全应用的强调色。
**可行性**:可行且成本低 —— 因为全应用的"可交互色"已经收敛到单一来源 `--primary`。落地后组件层改动为 0。
**实现**:`src/lib/theme.ts`(派生 + 应用)+ `appStore.setAccent()` + 设置页「主题色」卡片。
用户**只选一个基色**,深浅两套由代码派生 —— 不需要为浅色/深色各选一次(同色相两个亮度是既有做法:
浅 `#0066cc` / 深 `#2997ff`),也不会出现"浅色选青、深色选紫"的语义割裂。
#### 需要派生的变量
只改基色是不够的,必须同时派生 7 个变量,否则 hover / 选中态仍是旧色:
| 变量 | 派生规则(OKLCH,色相 H 原样保留) | 用途 |
|---|---|---|
| `--primary` | 基色,L 归一到 `0.42–0.58`(浅)/ `0.68–0.80`(深),C 限制在 `0.06–0.20` | 主按钮、开关、焦点环 |
| `--primary-hover` | 浅:L − 0.08;深:L + 0.06 | 主按钮 hover |
| `--primary-active` | 浅:L − 0.16;深:L − 0.10 | 主按钮按下 |
| `--primary-soft` | 浅:`oklch(0.95, C×0.30, H)`;深:`oklch(0.30, C×0.45, H)` | 选中底、幽灵按钮 hover |
| `--primary-soft-text` | 基色加深/提亮起步,再按对比度推进到 ≥4.5:1 | 上述底上的文字 |
| `--ring` | 同 `--primary` | 焦点环 |
| `--primary-foreground` | 白字低于 2.5:1 时才换 `#1D1D1F` | 填充上的文字 |
深色模式**单独派生一套**(深底上要提亮),不能复用浅色值。
行高亮这一族(`--row-hover` / `--row-selected` / `--row-hover-veil` / `--row-selected-veil`)
**不在这 7 个之内**:它们在 `style.css` 里写成 `color-mix(..., var(--primary) ...)`,
而 `--primary` 的行内覆盖是惰性求值的,所以换主题色时自动跟着变,
不需要进 `theme.ts` 的派生组,也不需要新增断言。
#### 关键技术点
1. **用 OKLCH 做派生,不要用 HSL。**
只换色相 H、锁定 L 与 C,才能保证换任意色相后对比度一致。HSL 的"明度"感知不均匀,换色相会时亮时暗。
2. **对比度靠"推进亮度"而不是固定阈值判定。**
同一 OKLCH L 下不同色相的 WCAG 亮度差很多(L=0.58 的青柠对白底只有 ~2.8:1,蓝色却有 ~5:1),
所以归一到区间后还要继续推进 L 直到达标:
- 浅色:`--primary` 对 `#FFFFFF` ≥ 4.5:1(它会被当文字用在白卡上)→ 选亮色自动压暗
- 深色:`--primary` 对 `#1E1E22` ≥ 4.5:1 → 自动提亮
- `--primary-soft-text` 对 `--primary-soft` ≥ 4.5:1
以上断言在 `src/lib/theme.test.ts` 里对 10 个预设 × 2 模式全量校验。
3. **`--primary-foreground` 的取舍是有意的。**
深色模式下强调色必须够亮才能在深底上当文字用(≥4.5:1),同一颜色做填充时白字只能到 2.7–3:1 ——
现有主题就是这个取舍(`#2997ff` + 白字 ≈ 2.98:1)。因此门槛按 UI 组件的 2.5:1 兜底,
只在自定义极亮色时才改深墨。
4. **只开放"强调色",不开放状态色。**
`success` / `warning` / `danger` 是语义色,改了会破坏"绿色=成功"的心智模型。`--data-*` 同理。
`--info` 一族当前取值与强调色相同(蓝),但**不跟随**主题色 —— 它表达"信息"而非"可交互",
换紫/绿主色后少数徽标(代理"国外"、HTTP 1xx/3xx、快速面板分类)仍是蓝色,属有意的语义区分。
5. **预设 + 自定义。**
10 个预设(默认蓝 / 靛蓝 / 紫罗兰 / 玫红 / 橙 / 琥珀 / 青柠 / 翠绿 / 青绿 / 石墨)+ 原生取色器。
纯自由取色很容易选出对比度不达标的颜色,所以色板优先。
色板显示色用**派生后的浅色模式主色**(所见即所得,如青柠显示为压暗后的绿)。
6. **实时预览 + 可回滚。**
点击色块 / 拖动取色器立即生效(写 7 个变量,无防抖);「恢复默认」清除行内变量回到内置蓝。
7. **持久化**:随其它设置写入 `thing_app_settings`(`accentId` + `accentHex`)。
属**纯增量字段**,`SETTINGS_VERSION` 不递增 —— 递增会命中"版本不匹配清空"分支,
把用户的模块排序/启停/开机自启一并抹掉,为零收益付真实数据损失。
8. **行内变量的优先级陷阱。**
变量写在 `documentElement` 的行内样式上,优先级高于 `:root` 与 `.dark` 两条规则,因此:
切模式必须**整组 7 个重写**(否则浅色的行内值会残留到深色模式);
恢复默认必须 `removeProperty`(写空串仍算"已设置")。
#### 落地范围
- `src/lib/theme.ts` —— 派生计算 + 应用/清除(新增,含单测)
- `src/stores/appStore.ts` —— `accentId`/`accentHex` + `setAccent()`,在 `applyTheme()` 与
`handleSystemThemeChange()` 里按当前模式应用
- `src/modules/settings/GeneralSettings.vue` —— 「主题色」卡片
- 9 个独立窗口(快速面板 / 托盘菜单 / 下载窗 / 剪贴板弹窗与预览 / 翻译弹窗 / 截图覆盖层·编辑器·贴图)
各加一行 `applyStoredAccent()`;托盘菜单额外补 `storage` 监听
- `src/style.css` —— **无需改动**(7 个变量已是 CSS 变量)
- **首屏闪烁(FOUC)不需要额外处理**:主窗口 `visible: false`,`appStore.init()` 在 `show()` 前完成应用;
文档原建议的 Rust `initialization_script` 方案与本仓库 localStorage 方案冲突,不实施
**影响面:0 处组件改动。** 这正是把交互色收敛到 `--primary` 单点带来的收益 —— 现在不做,将来也不用挨个改组件。
---
## 3. 页面框架
框架只定义三件事:**谁多高、谁滚动、padding 加在哪**。这三件事定死之前,任何模块级的美化都会被布局 bug 吃掉。
### 3.1 分区与高度约束链
```
AppShell h-screen flex-col
├ TitleBar h-14 shrink-0 固定 · 侧栏图标 + 模块 Tab + 搜索
└ 主体 flex-1 min-h-0 flex-row
├ Sidebar w-15 shrink-0 60px 固定
└ 内容滚动区 flex-1 min-h-0 overflow-y-auto ← 全应用唯一滚动容器
└ 内容 wrapper p-5(占满内容宽,无 max-width)
```
Tab 已并入标题栏(见 3.5),内容区不含独立 Tab 行,纵向空间最大化。
**三个必须遵守的点**(都是实际踩过的坑,不是理论):
1. **`min-h-0` 不能漏。**
flex 子项默认 `min-height: auto` —— 内容变高时它**不收缩**,直接把父容器顶破,底部 padding 被推出视口。这就是"卡片贴着应用底部"的根因。
2. **padding 加在滚动容器**内部**的 wrapper 上。**
加在滚动容器自身,底部 padding 会被内容高度覆盖,滚动到底依然贴边。
3. **断点按内容宽度选,不按视口宽度。**
侧边栏固定占 60px —— 视口 1000px 时内容只剩 940px。两列网格必须用 `md`(768) 而不是 `lg`(1024),否则窗口一窄就退化成单列全宽、卡片大片留白。
### 3.2 滚动归属
**全应用只有一处滚动容器。**
- 模块内容区随外层滚动,**不是**每个模块各建一个滚动容器
- 模块根 / 页面级容器**禁止** `overflow-y-auto` —— 那会绕过外层 `ScrollArea`,出现原生宽滚动条(快速面板踩过);根容器一律 `min-h-full`
- 局部列表(剪贴板历史、音乐队列等)**可以用 `ScrollArea` 组件**做独立滚动 —— 这是「局部区域」而非「页面级」
- 需要固定表头的长表格:用 `position: sticky` 固定表头,而不是给表格单独开滚动容器
- 例外:terminal / translate 的工作台面板内部滚动(workbench 模式特征)
- 代价:切换 Tab 时共享同一个滚动位置(可以接受,反而更符合"翻页"直觉)
**统一组件使用规则**(违规即 UI 不一致,等同违反第 5 章 D 系):
| 需求 | 用 | 禁止 |
|---|---|---|
| 页面滚动 | 外层 `ScrollArea`(自动,模块无需处理) | 模块根 `overflow-y-auto` |
| 局部列表滚动 | `ScrollArea` 组件 | 原生 `overflow` |
| 键值行 / 状态点 / 徽章 / 大数值 | `@/components/common` 对应组件 | 手写 flex 结构 |
| 卡片 | `Card` / `InfoGroup(card)` / `StatCard`(统一 `shadow-sm`) | 手写描边块 |
| 多分组设置表单 | `SettingGroup` + `SettingRow` | 手写行 |
### 3.3 内容区宽度
内容区**不限宽,占满窗口宽度**(已移除 `max-w-6xl` 限制)。窗口拉宽时卡片随内容区延展,不再居中约束。
### 3.4 内容区布局模式
内容区**只能**从以下五种里选,不得自创:
| 模式 | 适用 | 规格 |
|---|---|---|
| `grid` | 概览 / 状态总览 | `grid-cols-1 md:grid-cols-2`·gap 16·`items-start` 让卡片各自高度 |
| `split` | 列表类(clipboard / music / terminal) | 左栏 280–320px·右栏 fill·中间 1px `--border`·无 padding |
| `workbench` | 输入-输出类(devtools / translate) | 纵向堆叠·gap 12 |
| `settings` | 设置页 | 纵向堆叠·gap 24·复用 `SettingGroup` |
| `plain` | 其他 | 纵向堆叠·gap 12 |
**`grid` 的用法边界**:只适合「各块内容量接近」的概览页。若各块信息量差异大,两列会让矮的那列留空。
**概览页标准结构 · 「状态横幅 + 卡片网格」**(适用于 proxy / 下载 / 硬件监控,四处横幅已统一,见下方「落地状态」):
```
第一行:状态横幅(全宽,独立于网格,高约 76px)
├ 容器 `Card`(`!py-0 !gap-0`)+ `CardContent`(`flex flex-wrap items-center gap-x-6 gap-y-3 px-4 py-4`)
│ 圆角/描边/阴影一律由 Card 提供(`rounded-xl + border + shadow-sm`),禁止手写 `rounded-lg border bg-card`
├ 左组成组(状态 → 核心属性 → 实时指标,依次靠左,不把指标悬在中间)
│ 状态区 状态点 8px + 状态文字 13px/500 + 进程名 13px 次要色(状态点/文字用语义色;运行态加 status-dot-pulse)
│ 指标区 label 11px 灰 + 数值 18px/600 tabular-nums;核心属性(如内核版本、PID)也占一个指标位
└ 操作区 运行中 = 重启(outline)+停止(destructive);停止 = 启动(primary);sm = 32px;`ml-auto` 推到行尾
下方:**两列瀑布流** `columns-1 md:columns-2`(卡片 `break-inside-avoid`,列间距/卡间距 16px),`InfoGroup variant="card"`
├ 卡内键值**一律单列**(`InfoGroup columns=1`,一行一条)—— 双列键值会挤压值区,路径类长值被截断
├ 瀑布流各卡自然高度、列内堆叠,**没有「同行等高」的配对压力** —— 双列网格的配对调整是反复返工的根源,已废弃
├ 表单类内容(下拉/输入)用「label 在上 + 控件全宽」纵排,不塞进键值行的值区
└ 阅读顺序为纵向(先左列后右列),分组按重要性排序;列底部不齐是模型特征,不是缺陷
```
**适用判断**:模块概览有「一个核心状态 + 2-4 个实时指标 + 一个主操作」就用横幅;三者不齐的模块直接用卡片网格,不要硬凑横幅。
**落地状态**(2026-09-21 统一):proxy 概览 / proxy 连接 / 下载任务 / 硬件监控概览四处横幅均按本节实现 ——
- 硬件监控:`PID / 传感器 / 重启 / 事件` 从 `text-xs` 内联「标签: 值」提升为指标位,进程名用 `ThingHK`,操作区 `xs` → `sm`,停止按钮改 `destructive`
- 下载:`下载中 / 等待 / 已暂停 / 已完成 / 已取消` 从 `Badge` 改为指标位,且恒显(0 比隐藏更真实,也避免位置漂移)
- 状态文字一律「状态 + 进程名」顺序(`运行中 mihomo` / `已连接 ThingHK` / `运行中 下载引擎`)
**已否决的两个方案**(避免回头再试):
- **平铺分组**(InfoGroup 无容器版):无容器所以视觉"散";键值两端对齐导致一行一条时"空"。
- **等宽两列卡片**:内容量不齐导致列内留白。D2 之所以成立,是横幅吸收了最"高"的内容(状态+指标),剩下的卡片内容量天然接近。
**设置行**结构(`SettingGroup` + `SettingRow`):
```
分组标题(h2 14/600)+ 可选说明
└ 设置行:左 label · 右控件,行高 44,行间 1px --divider
```
### 3.5 导航与 Tab
**Tab 只有一处:标题栏。** 模块内容区不再渲染 Tab 行。
| 层级 | 位置 | 内容 |
|---|---|---|
| 一级导航 | 侧边栏 60px | 模块图标(代理 / 音乐 / 剪贴板…) |
| 二级导航 | **标题栏内** | 当前模块的 Tab(概览 / 连接 / 节点 / 订阅 / 设置) |
**为什么**:Tab 行独占 48px 纵向空间,却只承载一个切换器。并入标题栏后,内容区最大化。
**实现**:
```ts
useModuleTabs('proxy', activeTab, tabs, { alwaysVisible: true })
```
- 模块**不渲染** `TabsList`,标题栏切换器常驻
- 传 `alwaysVisible` 后不再注册 `IntersectionObserver`
- 未传该选项的模块保持原行为(Tab 行滚出视口时才在标题栏补一个)—— 属过渡状态,应逐步迁移
**选中态**:`--primary` 实心胶囊 + 白字。标题栏空间小、Tab 数量少,实心比下划线更易扫读。
> 过渡期存在两套 Tab 外观:模块内的 `TabsList`(下划线)与标题栏切换器(实心胶囊)。**全部模块迁移完成后,只保留标题栏这一套**,那时 `TabsTrigger` 的下划线样式可以简化掉。
### 3.6 状态覆盖(P3 落地)
每种模式都必须实现四态,**抽成通用组件,不在模块内手写**:
| 状态 | 组件 | 表现 |
|---|---|---|
| 加载 | `<StateBlock variant="loading">` | Spinner 16px + "加载中…",高度撑满容器最小 120px |
| 空 | `<StateBlock variant="empty">` | 图标 32px(`--muted-foreground`) + 说明 caption + 可选主按钮 |
| 错误 | `<StateBlock variant="error">` | 图标 32px(`--danger`) + 错误信息 + "重试"次按钮 |
| 无权限 | `<StateBlock variant="denied">` | 图标 + 说明 + 引导操作 |
**验收**:随机打开任一模块的任一 Tab,断网/清空数据/制造错误,都必须看到对应的块,而不是空白。
### 3.7 页面构造示例 · proxy(样板,含其余四页规划)
概览页已定稿(横幅 + 瀑布流)。其余四页用**同一套模式**组装,空态一律按 M8(结构恒定 + `—` 占位):
**统一原则(四页共用)**
1. 每页从 3.4 的模式里选一种承载,不自创
2. 统计类信息统一用「指标行」形态(与横幅指标区同构:label 11 + 数值 18/600),容器口径同横幅 —— 用 `Card` 承载,不做裸指标行(M8)
3. 表格/列表统一用卡片承载,长表头 `sticky`
4. 行内操作集中在行尾,用 `icon-sm`(28px),禁微缩按钮
**连接** —— 指标行 + 表格卡(workbench 变体)
```
指标行:活跃连接 + 规则命中 chips(与概览横幅同容器 Card + `px-4 py-4`;chips 紧挨活跃连接,随命中项变化向右延伸)
下载/上传速率已删(与概览横幅重复);命中规则计数已删(恒等于活跃连接数)
表格卡(全宽):进程/域名 + 国内国外徽章 + 规则 + 上下行流量 + 断开
表头 sticky · 行 hover(bg-hover) · 空态「暂无活跃连接」
```
**节点** —— 组导航 + 节点网格
```
顶部:代理组切换(SegmentedNav,组多时降级为 Select)+ 测速按钮(行右)
节点网格:节点小卡(名称 + 延迟徽章 + 选中态 primary-soft),grid-cols-2 lg:grid-cols-3
未运行时网格空态「暂无节点」,结构不变
```
**订阅** —— 列表卡 + 导入区(plain 模式)
```
列表卡:行式(名称 / 更新时间 / 节点数 + 更新、删除),行高 52,行间 1px divider
导入区:URL 输入 + 导入按钮,置于列表卡上方
空态「暂无订阅」+ 主按钮引导导入
```
**设置** —— 单卡 + 卡内标题(峰定稿偏好:设置页标题留在卡片内)
```
单张设置卡承载全部设置项,卡片占满内容宽(放大居中与概览/连接一致)
输入类双列(md:grid-cols-2)、开关行「左说明右开关」、提示条 primary-soft 底;保存按钮在标题栏
(SettingGroup / SettingRow 保留,用于全局设置页等多分组场景)
```
---
## 4. 组件规范
### 4.1 业务组件清单(统一从 `@/components/common` 导入)
以下 14 个组件已建立完成。**模块内不得再手写同类结构**——这是"UI 不统一"反复复发的根本原因:只要没有现成的替代品,开发者就只能手写。
| # | 组件 | 解决的问题 | 关键 props |
|---|---|---|---|
| 1 | `ModuleShell` | **页面框架落地件**:高度约束链 + 滚动归属 + 内容区 padding/限宽 | `layout`, `padded`, `maxWidth`, `tabs` |
| 2 | `ModuleToolbar` | 模块内容区顶部操作条 | `slot: left/right` |
| 3 | `SectionHeader` | 区块标题 + 说明 + 右侧操作 | `title`, `description`, `slot: action` |
| 4 | `StatCard` | 键值卡片(需要视觉分组的独立块) | `title`, `description`, `slot: action` |
| 4a | `InfoGroup` | **平铺分组**(概览页键值快照,密度优先) | `title`, `columns`, `slot: action` / `slot: footer` |
| 5 | `MetricValue` | 大数值 + 标签 + 单位 + 方向色 | `value`, `unit`, `label`, `trend` |
| 6 | `KeyValueRow` | 键值行(状态/版本/路径) | `label`, `value`, `slot: value` |
| 7 | `StatusDot` | 状态点 + 文字 | `state: success/warning/danger/neutral`, `label` |
| 8 | `StatusBadge` | 徽章 | `variant`, `size: sm/md` |
| 9 | `SettingRow` | 设置行 | `label`, `description`, `slot: control` |
| 10 | `SettingGroup` | 设置分组 | `title`, `description` |
| 11 | `DataListRow` | 列表行(主从分栏左栏) | `title`, `subtitle`, `active`, `slot: trailing` |
| 12 | `StateBlock` | 加载/空/错误/无权限 | `variant`, `title`, `description`, `slot: action` |
| 13 | `CopyField` | 可复制文本(路径、版本号) | `value`, `mono` |
| 14 | `ConfirmDialog` | 破坏性操作确认 | `title`, `description`, `variant: danger` |
### 4.2 关键组件规格
**按钮**(基于 shadcn `Button`,只调 token 与尺寸)
| 变体 | 底色 | 文字 | 描边 | 用途 |
|---|---|---|---|---|
| `default`(主) | `--primary` | `--primary-foreground` | 无 | 每屏仅 1 个 |
| `outline`(次) | `--card` | `--foreground` | `--border-strong` | 常规操作 |
| `ghost`(幽灵) | 无底 / hover `--primary-soft` | `--fg-secondary` / hover `--primary-soft-text` | 无 | 工具栏、行内 |
| `destructive`(危险) | `--danger` | 白 | 无 | 停止/删除,需确认 |
尺寸:`sm` 高 28 / `default` 高 34 / `lg` 高 40。内边距 `px-3.5`(default),圆角 `radius-md`。按下统一 `scale(0.97)`。
**禁止** `h-4 px-1.5 text-[10px]` 这类微缩按钮(`ProxyModule.vue:1768` 有此写法)——需要更小的按钮时用 `StatusBadge`。
**交互反馈(hover / active / focus)**
| 场景 | hover | active |
|---|---|---|
| 主按钮 | `--primary-hover`(变深) | `--primary-active` |
| 次按钮 / 卡片 | `--hover`(中性加深) | `--active` |
| 幽灵按钮 / 图标按钮 | `--primary-soft` + `--primary-soft-text` | `--primary-soft` |
| 内容列表行 / 选项卡片 | `--row-hover`(主题色弱底) | — |
| mica / acrylic 弹窗内的行(快速面板、托盘菜单) | `--row-hover-veil`(半透明蒙层) | `--row-selected-veil`(按下/光标) |
| 菜单项 / 数据表行 / 导航 / 分段 / 折叠头 | `--hover` | — |
| 选中行 | — | `--row-selected` |
| 选中 Tab | — | `--primary-soft` |
**焦点环**全应用统一:`ring-2 ring-ring/40`。hover ≠ selected:hover 表达"可以点",selected 表达"已经选中",后者才用强调色。
**内容行 vs 通用中性(2026-09 修订)**
`--hover` 与行高亮的分工,不是"哪个好看",而是语义:
| | 用 `--hover`(中性) | 用行高亮(主题色) |
|---|---|---|
| 判断依据 | 控件本身可点,不承载数据对象 | 一行/一卡承载一个**对象**(歌曲、任务、主机、密钥、设备、剪贴项) |
| 典型 | 按钮、菜单项、代理连接表、侧栏、Tab、设置行 | 音乐列表/队列/歌单/搜索结果、任务列表、主机/密钥/shell 卡片、监控设备项、历史命令、剪贴板条目、快速面板与托盘菜单条目 |
**四种值的选择(2×2)**
先问两件事:**是不是"一行一个对象"** → 否则用 `--hover`;**这一行坐在什么底上** → 决定用哪一对:
| 行所在的面 | hover | 选中 |
|---|---|---|
| 不透明(卡片、面板、弹窗自带底色) | `--row-hover` 8% / 11% | `--row-selected` 15% / 26% |
| mica / acrylic 糊化层(行直接画在壁纸上,窗口无自身底色) | `--row-hover-veil` 16% | `--row-selected-veil` 30% |
五条硬约束:
1. **不能全局把 `--hover` 改成主题色**。次按钮 hover 会与幽灵按钮(`--primary-soft`)撞色,菜单项与数据表整片变蓝,按钮层级和"hover 中性"的既有观感一起塌。必须是新增 token 分开用。
2. **行选中不能用 `--primary-soft`**。`--primary-soft` ≈ primary 10% 混白,和 8% 的 `--row-hover` 只差 2 个色阶,悬停已选中项时看不出区别 —— 这就是 `--row-selected`(15%)存在的原因。`--primary-soft` 留给"选中 Tab / 幽灵按钮 hover"。
3. **透明面上的行必须用 veil 而不是不透明色**。不透明浅底在糊化层上会变成一块"贴上去的白块",并盖掉 mica 质感;半透明会与壁纸自然叠合(浅壁纸偏浅、深壁纸偏深),因此 veil 只在 `:root` 定义一次,不在 `.dark` 重写。veil 也明显更重(16% vs 8%)—— 不透明的 8% 放到壁纸上基本看不见;但也不能一路加重,20% 起就偏"罩住"了,16% / 30% 是实测的手感点。
4. **禁止在内容行上继续用 `--accent/40 ~ /60`**。半透明中性灰在白卡上只有 3% 明度差,等于 hover 无效——这是本次修订要清掉的存量问题。
5. **选中态必须显式盖过 hover**。二者的 CSS 特异性经常是平的或反过来:纯 CSS 里 `:hover`((0,2,0))高于单类((0,1,0)),要写 `.sel:hover` 同规则;Vue 里静态的 `hover:bg-row-hover` 不能和条件类的 `bg-row-selected` 并存,必须写成三元互斥(见 `SftpPanel.vue` 文件表格与 `TrackItem.vue`)。
**状态点**
```
8px 圆 · border-radius: full · 底色 = 对应 --<state>
与文字间距 6px · 文字用 body 或 label
```
可选呼吸动效(运行中):`opacity` 1↔0.55,1.8s 循环,`prefers-reduced-motion` 下禁用。
**徽章**
```
高 20 · 内边距 3px 8px · 圆角 radius-sm
底 --<state>-soft · 文字 --<state>-text · 字号 label(11/500)
```
**卡片**
```
底 --card · 1px --border · 圆角 radius-lg(12) · 内边距 space-4(16)
标题 h2(14/600) · 标题与内容间距 space-3(12)
统一轻阴影 shadow-sm(--shadow-card)—— shadcn Card / InfoGroup card / StatCard 一致
```
**输入 / 下拉 / 分段控件**
```
高度 34 · 圆角 radius-md(8) · 1px --border
输入与下拉态:底 --card
分段控件:外槽底 --subtle,内边距 3,选中项底 --card + 文字 --foreground,未选中项文字 --fg-secondary
聚焦:border 不变,box-shadow: 0 0 0 2px --ring(40% alpha)
```
### 4.3 组件用法要点
- 业务组件统一从 `@/components/common` 导入(见 4.1 清单),模块内禁止手写同类结构。
- 页面用 `ModuleShell` 包裹,通过 `layout`(grid / split / workbench / settings / plain)选内容区模式。
- 内容区先按四态组织:先 `loading`,再 `empty`/`error`,最后才是数据内容(见 3.6 / M8)。
- 颜色只用 token 类名(`bg-card border border-border`),禁止 hex 与原生色阶(见第 5 章 D1–D2)。
- 数值统一 `tabular-nums`;状态点 / 徽章用 `StatusDot` / `StatusBadge`,键值用 `KeyValueRow` / `InfoGroup`。
---
## 5. 开发约束(硬性)
### 5.1 禁止清单
| # | 禁止 | 替代方案 |
|---|---|---|
| D1 | 组件内出现 hex / rgb / oklch 字面量 | 用语义 token 类名 |
| D2 | Tailwind 原生色阶 `bg-blue-500` `text-emerald-700` `border-slate-200` | 用 `bg-primary` `text-success-text` `border-border` |
| D3 | 间距/圆角/尺寸的任意值 `p-[18px]` `rounded-[10px]` | 归位 4px 栅格:`p-4` `rounded-md`(非 4 倍数就近归档)。**字号例外**:正文标准档 `text-[11px]`~`text-[14px]` 是项目字号体系(Tailwind 无 13px 预设),允许保留;非标准档(15/13.5/16px 等)归位最近标准档 |
| D4 | 用状态色表达可点击性(绿色按钮 = 主操作) | 主操作一律 `--primary` |
| D5 | 卡片使用重阴影(shadow-popover / shadow-dialog 或 hover 抬起阴影) | 卡片统一轻阴影 `shadow-sm` |
| D6 | 模块内手写状态点 / 徽章 / 卡片标题 / 键值行 | 用第 4.1 节组件 |
| D7 | 混用图标库,或用 Unicode 符号(`↓ ✓ ● ▸`)当图标 | lucide,尺寸 14/16/20 |
| D8 | 中文加负字距 | `letter-spacing: 0` |
| D9 | 生产代码 `@import` 外部字体 CDN | 系统字体栈 |
| D10 | 数据驱动界面缺四态之一 | `StateBlock` |
| D11 | 一屏多个主按钮 / 破坏性操作与主操作同权重 | 视觉降级 + `ConfirmDialog` |
| D12 | 在 `.dark` 下靠改组件类名做适配 | 只改 token,组件代码不感知主题 |
### 5.2 必须清单
- **M1** 新增模块必须使用 `ModuleShell`,内容区三选一(第 3.2 节)
- **M2** 所有颜色/间距/圆角/字号可追溯到 `style.css` 的 token
- **M3** 深色模式与浅色模式同时验证,不得只测一套
- **M4** 数值使用 `tabular-nums`
- **M5** 动效尊重 `prefers-reduced-motion`
- **M6** 控件最小点击区 28×28(桌面标准,非触摸的 44)
- **M7** 文字与背景对比度 ≥ 4.5:1;`--muted-foreground` 不得用于正文,只用于 ≥12px 的辅助信息
- **M8** 数据驱动的界面**结构恒定**:无数据时保持完整结构、值用 `—` 占位(横幅、键值行、表格单元同规则);**不得**用「xx 未运行」之类文案整块替换结构。运行状态由横幅状态区或状态点表达,不在卡片内复述。控件在不可用时禁用,而不是隐藏整块。
`—` 与 `0` 的区分:`—` = 数据缺失/不适用(如未运行时的 PID);`0` = 语义上就是零(如未运行时的连接数、速率)—— 可计数指标显示 0 比 `—` 更真实。指标行/横幅必须有容器(卡片),裸指标行浮在画布上与页面不协调。
- **M9** 动态数值的指标位**按数据类型固定最小宽度**:速率/流量/计数高频刷新,宽度变化会左右推移兄弟元素。做法同 OSD(`tabular-nums` + `min-width`)。**宽度按内容定,不要一刀切**——速率 `min-w-24`(容纳 `999 KB/s`)、版本/累计 `min-w-20`、纯计数 `min-w-12`;统一给大值会留白并把同卡操作按钮挤换行
- **M8** 键盘可聚焦元素必须有可见焦点环(`ring-2 ring-ring/40`)
### 5.3 Code Review 检查点
提交前自查(建议做成 MR 模板 checklist):
1. `grep -rE "(#[0-9a-fA-F]{3,8}|(bg|text|border)-(slate|gray|zinc|blue|emerald|amber|red|rose|orange|sky|purple|violet)-[0-9]{2,3})" src/` **无新增命中**
2. `grep -rE "\w-\[[^\]]+\]" src/` 新增行数可控且能说明理由
3. 深浅两套主题截图留存
4. 加载/空/错误三态至少手动触发过一次
5. 破坏性操作有确认
**建议自动化**:加入 ESLint 规则,直接拦截 D1–D3。
```js
// eslint 思路示例:禁止特定 class 模式
{
files: ['**/*.vue'],
rules: {
'no-restricted-syntax': [
'error',
{
selector: 'Literal[value=/(bg|text|border)-(slate|gray|zinc|blue|emerald|amber|red|rose|orange|sky|purple|violet)-\\d{3}/]',
message: '禁止使用 Tailwind 原生色阶,请使用语义 token(见 UI_DESIGN_SYSTEM.md 第 5.1 节 D2)'
}
]
}
}
```
---
## 6. 工具与状态
### 6.1 组件预览页(改 token 后的回归工具)
路径:`preview/` —— **不在生产构建入口内**,只在 `bun dev` 时可访问。
```bash
bun dev
# 浏览器打开 http://localhost:14210/preview/index.html
```
用途:改完 `src/style.css` 的 token 后,把全部基础组件与业务组件过一遍,确认浅色 / 深色两套都正确 —— 替代"改完 token 靠记忆推断影响面"。本页不依赖任何 Tauri API,纯浏览器即可运行。
查询参数:
| 参数 | 作用 | 示例 |
|---|---|---|
| `theme=dark` | 以深色模式启动 | `?theme=dark` |
| `only=<id>` | 只渲染指定分区,便于放大核对 | `?only=data` |
已内置 `id` 的分区:`forms`、`data`、`shell`。需要放大看其他分区时,按同样方式给 `<section>` 加 `id` 即可。
> **实现注意**:`only` 的隔离 CSS 只能用**显式标记**(`[data-block]` / `[data-page-header]`),**不能用 `section` / `header` 这类标签选择器**——`StatCard` 内部也用 `<section>` 和 `<header>`,会被一起隐藏,产生"组件没渲染"的假象。
### 6.2 当前状态
- 业务组件层(第 4.1 节 14 个组件)与 Token 层已落地,`preview/` 预览页已完成浅色/深色视觉回归。
- 色阶治理:Tailwind 原生色阶从约 155 处降至 3 处(proxy / terminal / monitor / translate / music 的色阶与 Tabs 已完成)。
- proxy 概览页定稿为「状态横幅 + 两列瀑布流」,InfoGroup 新增 `variant="card"`。
- 状态横幅统一(2026-09-21):proxy 概览 / proxy 连接 / 下载任务 / 硬件监控概览四处横幅统一为 §3.4 的三段式(状态区 → 指标区 → 操作区)+ `Card` 容器;监控与下载的旧样式(`text-xs` 内联键值、Badge 计数、`xs` 按钮)已废弃。
- 主题色自定义落地(2026-09-21,见 §2.9):`src/lib/theme.ts` + `appStore.setAccent()` + 设置页「主题色」卡片(10 预设 + 自定义),深浅两套自动派生、对比度自动兜底;组件层 0 改动。
- 终端模块非终端页对齐(2026-09-21,见 TERMINAL_MODULE_PLAN.md §5):根 padding 归类、列表 Card 化、表单走 `@/components/ui` 原语、四态/徽章走 `@/components/common`、设置页用 `SettingGroup`/`SettingRow`(此后二者与 `StateBlock`/`StatusBadge` 有真实消费者);终端画布、状态栏、`h-11` 契约、xterm 链保持不动。
- 剩余项:
- `OsdWindow` 免改(功能性配置,非 UI token 问题)
- `DownloadWindow` / `ClipboardPopup` 仍有少量 hex,待统一
- ESLint 约束规则(第 5.3 节)尚未搭建
### 6.3 待决策
| # | 问题 | 状态 | 结论 / 影响 |
|---|---|---|---|
| 1 | 数据方向色是否与状态色解耦 | 已定(暂保留现有取值) | 保留"下载=绿、上传=红",已独立成 `--data-*` token,要换色只改这 2 个值 |
| 2 | 强调色用 `#0066CC` | ✅ 已采用 | 落地;同时解决 shadcn primary 近黑导致按钮发灰 |
| 3 | 浮窗(OSD/截图/下载)是否纳入统一体系 | 部分已定 | `OsdWindow` 免改(功能性配置);`DownloadWindow`/`ClipboardPopup` 少量 hex 待统一;不强行并入主界面 token |
| 4 | `--font-mono` 是否用网络字体 | ✅ 已定 | 系统 `Cascadia Code` / `Consolas`,不引外部字体 |
| 5 | 侧边栏宽度 60px | ✅ 已定 | 沿用现有实现 |
| 6 | 内容区限宽 | ✅ 已定 | 改为**不限宽占满**窗口宽度(原 `max-w-6xl` 限制已移除) |
| 7 | 卡片阴影 | ✅ 已定 | 卡片统一轻阴影 `shadow-sm`(shadcn Card / InfoGroup card / StatCard 一致),浮层仍用 `shadow-popover`/`shadow-dialog` |
---
**维护约定**:Token 值以 `src/style.css` 为唯一事实来源,本文档与之同步;两者冲突时以本文档为准并修正代码。新增 token 或组件须同步更新第 2、4 章。