feat: 添加硬件指纹功能并优化依赖管理

- 更新依赖管理文档，明确使用 Bun Catalog 统一管理版本并规范安装方式，新增已知问题与解决方案、依赖选择经验及 Git 工作流要求，强化团队协作与技术决策可追溯性。
- 添加硬件指纹页面，展示机器码、指纹质量等级及详细信息，并支持一键复制和缓存提示。
- 添加指纹路由配置并更新路由树类型定义以包含新路由路径和相关类型。
- 添加硬件指纹获取接口的契约定义，包含指纹字符串、质量等级、强标识符数量和时间戳的验证规则。
- 添加指纹合约到API合约导出中
- 添加硬件指纹获取接口，支持10分钟缓存并包含主硬盘序列号以提升指纹稳定性。
- 添加指纹路由到API路由器中
- 重构硬件指纹生成逻辑，引入缓存机制、质量等级评估和容错处理，提升稳定性与可维护性。

apps/server/AGENTS.md

@@ -16,6 +16,41 @@
 - **代码质量**: Biome (格式化 + Lint)
 - **桌面壳** (可选): Tauri v2 (详见 `src-tauri/AGENTS.md`)
 
+## 依赖管理
+
+### Bun Catalog 系统
+
+项目使用 **Bun Catalog** 统一管理依赖版本（定义在根目录 `package.json` 的 `catalog` 字段）。
+
+**安装依赖的正确方式**：
+```bash
+# ✅ 正确：使用 catalog: 前缀
+bun add <package-name>@catalog:
+
+# ❌ 错误：直接安装会绕过版本统一管理
+bun add <package-name>@latest
+```
+
+**示例**：
+```bash
+# 添加 systeminformation 依赖到 packages/utils
+cd packages/utils
+bun add systeminformation@catalog:
+
+# 添加 react 依赖到 apps/server
+cd apps/server
+bun add react@catalog:
+```
+
+**为什么使用 Catalog**：
+- 确保 monorepo 中所有包使用相同版本
+- 集中管理依赖版本，避免版本冲突
+- 简化依赖升级（只需修改根 package.json）
+
+**添加新依赖的步骤**：
+1. 在根目录 `package.json` 的 `catalog` 字段添加依赖及版本
+2. 在目标包中使用 `bun add <package>@catalog:` 安装
+
 ## 构建、Lint 和测试命令
 
 ### 开发
@@ -273,5 +308,63 @@ const mutation = useMutation(orpc.myFeature.create.mutationOptions())
 
 ---
 
-**最后更新**: 2026-01-18
+## 已知问题与解决方案
+
+### 构建问题
+
+**问题**: Vite 8.0.0-beta.9 与 Nitro 插件存在兼容性问题
+- **错误**: `TypeError: Cannot redefine property: viteMetadata`
+- **影响**: `bun run build` 构建失败
+- **解决方案**: 等待 Vite 8.0 正式版发布修复，开发环境（`bun dev`）不受影响
+- **临时方案**: 如需生产构建，可降级到 Vite 5.x 稳定版
+
+### 依赖选择经验
+
+**ohash vs crypto.createHash**
+
+在实现硬件指纹功能时，曾误判 `ohash` 不适合用于硬件指纹识别。经深入研究发现：
+
+**事实**：
+- `ohash` 内部使用**完整的 SHA-256** 算法（256 位）
+- 输出 43 字符 Base64URL 编码（等价于 64 字符 Hex）
+- 碰撞概率与 `crypto.createHash('sha256')` **完全相同**（2^128）
+- 自动处理对象序列化，代码更简洁
+
+**对比**：
+```typescript
+// ohash - 推荐用于对象哈希
+import { hash } from 'ohash'
+const fingerprint = hash(systemInfo) // 一行搞定
+
+// crypto - 需要手动序列化
+import { createHash } from 'node:crypto'
+const fingerprint = createHash('sha256')
+  .update(JSON.stringify(systemInfo))
+  .digest('base64url')
+```
+
+**结论**：
+- ✅ `ohash` 完全适合硬件指纹场景（数据来自系统 API，非用户输入）
+- ✅ 两者安全性等价，选择取决于代码风格偏好
+- ⚠️ ohash 文档警告的"序列化安全性"仅针对**用户输入**场景
+
+**经验教训**：
+- 不要仅凭名称（"短哈希"）判断库的实现
+- 深入研究文档和源码再做技术决策
+- 区分"用户输入场景"和"系统数据场景"的安全要求
+
+### Git 工作流要求
+
+**重要原则**：保持代码仓库与文档同步
+
+当遇到技术问题、做出架构决策、或发现重要经验时：
+1. **立即更新 AGENTS.md**：记录问题、原因、解决方案
+2. **持续同步**：每次重大变更后更新文档
+3. **版本关联**：在文档中标注相关的库版本、commit hash
+
+这确保未来的开发者（包括 AI 助手）能快速理解项目历史和技术选择。
+
+---
+
+**最后更新**: 2026-01-24
 **项目版本**: 基于 package.json 依赖版本