Menu
技术决策记录技能，记录和管理项目中的技术选型与架构决策。 触发场景： - 用户需要进行技术选型评估 - 用户需要记录架构决策及其原因 - 用户需要回顾历史技术决策 触发词：技术选型、架构决策、ADR、方案对比、技术评估
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | tech-decision |
| description | 技术决策记录技能，记录和管理项目中的技术选型与架构决策。 触发场景： - 用户需要进行技术选型评估 - 用户需要记录架构决策及其原因 - 用户需要回顾历史技术决策 触发词：技术选型、架构决策、ADR、方案对比、技术评估 |
Tauri Desktop App 的技术决策记录技能，使用 ADR（Architecture Decision Record）模式管理技术选型和架构决策。
# ADR-{编号}: {决策标题}
## 状态
[提议中 / 已采纳 / 已废弃 / 已取代]
## 背景
[描述决策的背景和约束条件]
## 技术约束
- 后端: Rust + Tauri 2.x
- 前端: React 19 + TypeScript 5.8
- 平台: Windows / macOS / Linux
## 方案对比
| 方案 | 优点 | 缺点 | Rust 生态兼容 | 跨平台 |
|------|------|------|-------------|--------|
| A | | | | |
| B | | | | |
## 决策
[选择方案 X，理由...]
## 影响
- Rust 侧: ...
- React 侧: ...
- Capabilities: ...
| 决策领域 | 选择 | 理由 |
|---|---|---|
| 后端架构 | 三层架构（models → database → services → commands） | 清晰的职责分离，便于测试和维护 |
| 数据库方案 | rusqlite (直接使用，不用 tauri-plugin-sql) | 更灵活的 SQL 控制，无需通过插件桥接 |
| 错误处理 | thiserror 定义 AppError enum | 类型安全的错误处理，避免 panic |
| 状态管理（前端） | Zustand | 轻量、API 简洁、TypeScript 友好 |
| 路由 | React Router v7 | 成熟稳定，文档完善 |
| 决策领域 | 选择 | 理由 |
|---|---|---|
| UI 组件库 | Ant Design 5 | 企业级组件库，功能完善，开箱即用 |
| 样式方案 | TailwindCSS 4 | 原子化 CSS，开发效率高 |
| 路径别名 | @/ 指向 src/ | 简化导入路径 |
| 决策领域 | 选择 | 理由 |
|---|---|---|
| 键值存储 | tauri-plugin-store | 前端直接使用，适合应用配置 |
| 结构化数据 | rusqlite | 后端使用，适合业务数据 |
| 决策领域 | 选择 | 理由 |
|---|---|---|
| 日志系统 | tauri-plugin-log | 官方插件，支持日志文件 |
| 打开 URL | tauri-plugin-opener | 安全地打开外部链接 |
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| Ant Design | 企业级、功能完善、中文文档 | 体积较大、样式定制复杂 | ✅ 已采纳 |
| shadcn/ui | 轻量、可定制、现代设计 | 需要手动配置、组件较少 | ⭕ 未采纳 |
| MUI | 成熟、Material Design | 体积大、学习曲线陡 | ⭕ 未采纳 |
| Headless UI | 无样式、完全可定制 | 需要自己写样式 | ⭕ 未采纳 |
决策: 选择 Ant Design，因为需要快速搭建功能完善的企业级应用。
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| Zustand | 轻量、API 简洁、无 boilerplate | 功能相对简单 | ✅ 已采纳 |
| Redux Toolkit | 功能强大、生态丰富 | 代码量大、学习成本高 | ⭕ 未采纳 |
| Jotai | 原子化状态、灵活 | 适合复杂场景，本项目不需要 | ⭕ 未采纳 |
| React Context | 内置、无需依赖 | 性能问题、不适合全局状态 | ⭕ 未采纳 |
决策: 选择 Zustand，因为项目状态管理需求简单，Zustand 足够轻量且易用。
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| React Router v7 | 成熟稳定、文档完善、社区大 | 相对传统 | ✅ 已采纳 |
| TanStack Router | 类型安全、现代化 | 较新、生态较小 | ⭕ 未采纳 |
决策: 选择 React Router v7，因为成熟稳定，文档完善。
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| rusqlite | 灵活、直接控制 SQL、无需插件 | 需要手动管理连接 | ✅ 已采纳 |
| tauri-plugin-sql | 官方插件、自动管理连接池 | 功能受限、需要通过 IPC 调用 | ⭕ 未采纳 |
| IndexedDB (前端) | 浏览器原生、无需后端 | 不适合桌面应用、API 复杂 | ⭕ 未采纳 |
决策: 选择 rusqlite，因为需要在 Rust 后端直接操作数据库，灵活性更高。
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| thiserror | 定义清晰的错误类型、派生宏 | 需要手动定义每个错误 | ✅ 已采纳 |
| anyhow | 灵活、快速开发 | 类型擦除、不适合库代码 | ⭕ 未采纳 |
| Result<T, String> | 简单直接 | 缺乏类型安全 | ⭕ 未采纳 |
决策: 选择 thiserror，因为需要类型安全的错误处理，方便调试和维护。
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| TailwindCSS 4 | 原子化、快速开发、配置简单 | 类名冗长 | ✅ 已采纳 |
| CSS Modules | 作用域隔离、传统 CSS | 需要管理多个 CSS 文件 | ⭕ 未采纳 |
| styled-components | CSS-in-JS、动态样式 | 运行时开销 | ⭕ 未采纳 |
决策: 选择 TailwindCSS 4，因为开发效率高，与 Ant Design 搭配使用效果好。
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| tauri-plugin-log | 官方插件、支持日志文件 | 功能相对简单 | ✅ 已采纳 |
| tracing | 功能强大、异步支持 | 配置复杂、体积大 | ⭕ 未采纳 |
| env_logger | 轻量、简单 | 功能有限 | ⭕ 未采纳 |
决策: 选择 tauri-plugin-log，因为满足基本需求且集成简单。
| 方案 | 优点 | 缺点 | 本项目选择 |
|---|---|---|---|
| cargo test (Rust) | 内置、无需配置 | 功能相对简单 | ✅ 已采纳 |
| Vitest (前端) | 快速、Vite 原生支持 | 需要配置 | ✅ 已采纳 |
| Jest | 成熟、生态丰富 | 配置复杂、速度慢 | ⭕ 未采纳 |
决策: 选择 cargo test + Vitest，因为分别是 Rust 和 Vite 的最佳选择。
| 错误做法 | 正确做法 |
|---|---|
| 技术选型不记录原因 | 使用 ADR 记录决策背景和理由 |
| 选择不支持跨平台的方案 | 评估 Windows/macOS/Linux 兼容性 |
| 选 Rust crate 不考虑编译时间 | 权衡功能 vs 编译时间 |
| 决策后不追踪效果 | 定期回顾决策结果并更新状态 |
| 混用多种状态管理方案 | 统一使用一种（本项目用 Zustand） |
| 混用多种样式方案 | 统一使用一种（本项目用 TailwindCSS） |
| 混用多种数据库方案 | 统一使用一种（本项目用 rusqlite + tauri-plugin-store） |
Git 工作流与版本管理技能，规范分支策略、提交信息和发布流程。 触发场景： - 用户需要创建分支或合并代码 - 用户需要规范提交信息格式 - 用户需要管理版本发布流程 触发词：Git、分支、提交、合并、版本发布
发布 Tauri 桌面应用新版本，处理版本号同步、Git tag、GitHub Actions 构建、Release 仓库产物同步、Cloudflare R2 上传、update.json 生成、自动更新发布和文档站重建。 触发场景： - 需要发布新版本或 release - 需要打 tag、推送发布分支或触发 CI 构建 - 需要生成或更新 update.json - 需要处理 Tauri updater 签名产物 - 需要同步 R2 CDN、GitHub/Gitee release 仓库或发布安装包 触发词：发布、release、版本发布、推送、打Tag、update.json、签名构建、安装包、自动更新、R2、CDN
Git 工作流与版本管理技能，规范分支策略、提交信息和发布流程。 触发场景： - 用户需要创建分支或合并代码 - 用户需要规范提交信息格式 - 用户需要管理版本发布流程 触发词：Git、分支、提交、合并、版本发布
自主连续开发方法论（Codex 版）。把一个项目按「每轮一个最小可提交单元」的方式推进到完成： 每轮读真相源 → 选下一个未做项 → 做一个最小单元 → 过验证门 → 记录勾选 → 最小提交 → 报进度。 适用于"按需求/台账建功能、还原原型、修一批 bug、补测试、重构、迁移、清理"等需要反复同构推进的任务。 与 Claude Code 的关系：Claude Code 有内置 `/loop` 自动续期（`/loop /dev-loop`），Codex 没有—— 所以 Codex 端由你（或脚本 / cron）反复触发"继续下一轮"，方法论本身一致。 触发场景： - 想让 Codex 把某个项目/某个意图"一轮轮推进到完成" - 还原原型图、修一批 warning、补单测、重构模块等同构重复任务 - 需要"每步可编译、可回退、可恢复"的稳健推进方式 触发词：自主开发、连续开发、循环开发、一轮一提交、还原原型、批量修复、autonomous dev、continuous dev
Tauri 打包与分发技能,指导桌面端（Windows/macOS/Linux）与移动端（Android/iOS）的构建、签名和分发。 触发场景: - 需要构建生产安装包（exe/dmg/deb/apk/aab/ipa） - 需要配置各平台打包参数 - 需要代码签名（Windows 证书 / Android keystore / iOS 描述文件） - 需要减小安装包体积 - 需要设置应用图标和元数据 - 需要打包 Android / iOS App 触发词: 打包、构建、build、发布、安装包、exe、dmg、deb、apk、aab、ipa、签名、分发、release、android build、ios build、移动端打包
排查已发生的问题、定位 Bug 原因。 触发场景： - 代码运行报错，需要定位原因 - 功能不正常，需要排查 - Tauri Command 返回错误，需要分析 - 日志分析、调试代码 触发词：Bug、报错、不工作、调试、排查、为什么、出问题、失败、不生效、无效、找不到原因、定位问题