贡献指南

技术栈

层	技术
桌面框架	Tauri 2
后端	Rust
前端	React 18 + TypeScript
样式	Tailwind CSS 4
数据库	SQLite（rusqlite bundled）
HTTP	axum 0.7
官网	Docusaurus 3

目录结构

├── src/                          # React 前端
│   ├── pages/                    # 页面（快传/队列/共享/打印/更新/配置）
│   ├── components/               # 组件
│   │   ├── ui/                   # 基础 UI（Card/Button/Input/Modal/Toast）
│   │   └── Layout.tsx            # 侧边导航布局
│   ├── lib/                      # 工具与 toast
│   └── index.css                 # 设计令牌（Tailwind @theme）
├── src-tauri/
│   ├── src/
│   │   ├── api/                  # 本地 HTTP API（axum）
│   │   ├── clipboard/            # 剪贴板写入、智能粘贴、逐字输入
│   │   ├── commands/             # Tauri 命令
│   │   ├── db/                   # SQLite 与迁移
│   │   ├── hotkey.rs             # 全局快捷键（低级键盘钩子）
│   │   ├── im.rs                 # IM 识别与差异化策略
│   │   ├── print/                # 打印模块
│   │   ├── send_queue.rs         # 发送队列（含持久化）
│   │   ├── share/                # 文件共享、配对、CIDA 构造
│   │   ├── transfer/             # 下载
│   │   ├── update/               # 更新检查、下载、安装
│   │   └── util.rs               # 随机数与延时
│   ├── tests/                    # 集成测试
│   └── examples/                 # 诊断工具
├── docs/api.md                   # API 文档源
├── site/                         # Docusaurus 官网
└── scripts/bump-version.ps1      # 版本递增脚本

开发环境

前置：Rust 1.85+、Node 18+、pnpm

git clone https://github.com/alaikis/seiyu-webapps.git
cd seiyu-webapps

pnpm install
pnpm tauri dev

pnpm tauri dev 会同时启动 Vite（端口 1420）与 Rust 后端，前端改动热重载，Rust 改动自动重编译。

设计令牌

前端与官网共用同一套设计语言。修改 src/index.css 中的 @theme 块：

@theme {
  --color-primary: #9fe870;
  --color-primary-hover: #8ed95c;
  --color-primary-dark: #7bc94f;
  --color-primary-soft: #e8f8db;
  --color-ink: #1a2e1a;
  --color-ink-soft: #4a5d4a;
  --color-line: #e3e9e0;
  --color-surface: #ffffff;
  --color-surface-soft: #f6faf3;
  --color-danger: #e5484d;
  --color-warn: #f5a623;

  --radius-card: 20px;
  --radius-card-lg: 24px;
  --radius-control: 12px;
}

官网侧对应 site/src/css/custom.css 中的 CSS 变量。改一处请同步另一处。

测试

# Rust 单元 + 集成测试
cargo test --manifest-path src-tauri/Cargo.toml

# 前端构建
pnpm build

测试采用 TDD：先写失败测试，看它失败，再写最小实现。

代码约定

注释、错误提示、UI 文案跟随需求语言（中文需求用中文）
不为「看起来专业」把新增业务注释写成英文
Windows API 调用集中在 clipboard/、hotkey.rs、share/、im.rs
诊断工具放 src-tauri/examples/，不影响正式构建

常用诊断工具

# 枚举当前剪贴板格式
cargo run --manifest-path src-tauri/Cargo.toml --example clipboard_formats

# 验证 Shell IDList Array（CIDA）结构
cargo run --manifest-path src-tauri/Cargo.toml --example cida_check

# 枚举微信窗口树
cargo run --manifest-path src-tauri/Cargo.toml --example wechat_windows

# 探测可用全局热键组合
cargo run --manifest-path src-tauri/Cargo.toml --example probe_hotkey

提交前检查

安全准则

绝不提交令牌。部署令牌放 .cnb-token（已被 .gitignore 忽略），流水线里只引用 ${CNB_TOKEN} 变量
剪贴板写入不得泄露密钥
更新包必须校验 SHA256，未提供校验值时拒绝静默安装

技术栈​

目录结构​

开发环境​

设计令牌​

测试​

代码约定​

常用诊断工具​

提交前检查​

安全准则​

技术栈