Contributing

贡献指南

感谢你对 Zephyr 的关注！本项目主要用于个人使用，但欢迎提交 Bug 报告和安全问题。

开发环境搭建

详见 BuildGuide。

代码规范

Rust

# 格式化
cargo fmt

# 检查格式
cargo fmt --check

# Clippy 检查（含 12 条额外规则）
cargo clippy

额外 Clippy 规则：

• indexing_slicing — 数组索引越界风险
• cast_possible_truncation — 数值截断
• cast_possible_wrap — 数值溢出
• cast_sign_loss — 有符号转无符号
• implicit_clone — 隐式克隆
• unused_async — 未使用的 async
• todo — TODO 标记

JavaScript

# ESLint 检查
npm run lint

# 单元测试
npm test

安全扫描

项目配置了 10 个独立的自动化安全扫描 Job：

#	工具	检查内容
1	cargo audit	Rust 依赖已知 CVE 漏洞
2	cargo-deny	许可证合规 + 重复 crate + 来源验证
3	cargo clippy	代码质量 + 安全 lint
4	cargo fmt	代码格式化
5	npm audit	前端依赖漏洞（moderate 级别即失败）
6	dependency-review-action	PR 依赖变更审查（拒绝 GPL/AGPL）
7	semgrep	SAST 静态代码分析
8	trufflehog + grep	密钥泄露检测
9	Tauri Security Audit	框架安全配置审计
10	cargo build/test + npm test	构建验证

Semgrep 自定义规则

项目包含 8 条自定义 Semgrep 规则（.semgrep.yml）：

Rust（5 条）：

• rust-osascript-privilege-escalation — 检测提权命令注入
• rust-osascript-command-pattern — 验证 osascript 参数转义
• rust-command-format-arg — 防止 .arg(format!(...)) 命令注入
• rust-unsafe-block — 审查 unsafe {} 块
• rust-hardcoded-crypto-constant — 检测硬编码加密常量

JavaScript（3 条）：

• js-innerhtml-assignment — 防止 XSS
• js-insertadjacenthtml — 提示验证输入
• js-document-write — 防止 XSS

依赖审计策略

许可证白名单（deny.toml）： MIT、Apache-2.0、BSD-2/3-Clause、ISC、OpenSSL、Zlib、MPL-2.0、LGPL-3.0、0BSD

禁止项：

• 通配符版本号
• 未知 registry 来源
• 未知 git 来源

提交 Issue

Bug 报告

请包含以下信息：

1. 操作系统和版本
2. Zephyr 版本
3. 复现步骤
4. 预期行为 vs 实际行为
5. 相关日志（如有）

安全报告

如果发现安全漏洞，请直接提交 Issue 并标注为安全问题。我们会在确认后尽快修复。

CI/CD

发布流程

推送 v* 格式的 tag 触发自动发布：

tag: v1.0.0
  ↓
4 个平台并行构建 (macOS arm64/x64, Linux, Windows)
  ↓
获取最新 mihomo 版本 + SHA256 校验下载
  ↓
构建 Full 版本（含内核 + Geo 数据）
  ↓
构建 Lite 版本（不含内核）
  ↓
上传到 GitHub Release（Draft 模式）

代码安全扫描触发条件

• 推送到 main / dev 分支
• 针对 main 的 Pull Request
• 每日定时扫描（UTC 3:00）
• CodeQL 每周一扫描（UTC 2:00）
• 手动触发（workflow_dispatch）

许可证

本项目基于 MIT License 开源。

Copyright (c) 2026 Juwan Hwang (黄治文)