Cobalt Guider Client

一个现代化的 PHD2 导星客户端，使用 Next.js 16、React 19 和 Tauri 2.9 构建。通过 WebSocket JSON-RPC 协议提供美观、响应式的界面来控制 PHD2 自动导星软件。

English Documentation

功能特性

核心导星功能

🔭 实时导星监控 - 实时导星误差图表、散点图和修正脉冲可视化
⭐ 星点选择 - 自动选星或手动选择，带视觉反馈
📊 统计仪表板 - RMS 误差、峰峰值、SNR、HFD 跟踪
🎯 校准工具 - 启动、清除、翻转校准，带状态显示
🌍 极轴校准 - 漂移法、静态极轴校准、极轴漂移校准工具
🌑 暗场库 - 构建、加载和管理暗场帧库
🔧 坏点图 - 创建和管理坏点像素图

高级功能

⚙️ 算法参数 - 微调 RA/Dec 导星算法
🔄 锁定偏移 - 配置锁定位置偏移用于彗星追踪
📝 导星日志 - 查看和导出详细导星日志
🎛️ 导星设置 - Dec 导星模式、可变延迟、搜索区域配置
💾 帧设置 - 限制帧 ROI、子帧设置
📊 直方图面板 - 实时图像直方图分析
🎯 覆盖层系统 - 可自定义十字丝、分划板、网格和注释
⌨️ 键盘快捷键 - 全键盘控制所有操作
📊 性能监控 - 实时性能指标

界面体验

🖥️ 桌面和移动端 - 响应式设计，PHD2 风格桌面布局
🌓 深色/浅色主题 - 系统感知主题切换
📱 触控友好 - 移动端导航支持滑动手势
🎨 现代 UI - 使用 shadcn/ui 和 Radix 原语构建
🖥️ 原生桌面 - 通过 Tauri 实现跨平台桌面应用
🛠️ 工作流面板 - 一键引导工作流
🔔 通知中心 - 集中式通知管理
📏 可调整面板 - 可自定义面板布局

技术栈

前端: Next.js 16, React 19, TypeScript
UI: Tailwind CSS v4, shadcn/ui, Radix UI, Lucide Icons
状态管理: Zustand
桌面: Tauri 2.9 (Rust)
测试: Jest, Playwright
协议: WebSocket JSON-RPC 2.0 (PHD2 Event Server)

前置要求

Web 开发所需

Node.js 20.x 或更高版本（下载）
pnpm 8.x 或更高版本（推荐）
```
npm install -g pnpm
```

桌面开发所需（额外要求）

Rust 1.70 或更高版本（安装）
系统依赖：
- Windows：Microsoft Visual Studio C++ 生成工具
- macOS：Xcode 命令行工具
- Linux：参见 Tauri 前置要求

安装

# 克隆仓库
git clone https://github.com/ElementAstro/cobalt-guider-client.git
cd cobalt-guider-client

# 安装依赖
pnpm install

# 验证安装
pnpm dev

快速开始

连接到 PHD2

启动 PHD2 并启用 Event Server（默认端口 4400）
运行 pnpm dev 并打开 http://localhost:3000
点击 "连接" → 输入 PHD2 主机/端口 → "连接"
通过 "连接设备" 连接设备

基本导星流程

循环曝光 - 点击 "循环曝光" 开始相机预览
选择星点 - 点击 "自动选星" 或在预览中点击选择
校准 - 如需要，运行校准（校准标签页）
导星 - 点击 "开始导星" 开始自动导星
监控 - 观察实时图表和统计数据

使用模拟服务器开发

无需 PHD2 进行开发：

# 终端 1：启动模拟 PHD2 服务器
pnpm mock-server

# 终端 2：启动开发服务器
pnpm dev

模拟服务器模拟：

PHD2 WebSocket JSON-RPC 2.0 协议
设备连接（相机、赤道仪）
循环曝光和星点选择
带真实漂移和视宁度模拟的导星
带 RA/Dec 误差和修正的导星步进事件

可用脚本

命令	描述
`pnpm dev`	启动开发服务器（端口 3000）
`pnpm build`	构建生产版本
`pnpm start`	启动生产服务器
`pnpm lint`	运行 ESLint
`pnpm test`	运行单元测试（Jest）
`pnpm test:e2e`	运行 E2E 测试（Playwright）
`pnpm test:e2e:ui`	带 UI 运行 E2E 测试
`pnpm mock-server`	启动模拟 PHD2 服务器
`pnpm tauri dev`	启动 Tauri 桌面开发模式
`pnpm tauri build`	构建桌面应用

项目结构

cobalt-guider-client/
├── app/                              # Next.js App Router
│   ├── page.tsx                      # 主导星界面
│   ├── layout.tsx                    # 根布局
│   └── globals.css                   # 全局样式 (Tailwind v4)
├── components/
│   ├── guider/                       # 导星专用组件（模块化）
│   │   ├── advanced/                 # 高级设置
│   │   │   ├── algo-params.tsx       # 算法参数
│   │   │   ├── frame-settings.tsx    # 帧/ROI 设置
│   │   │   ├── guide-pulse.tsx       # 手动导星脉冲
│   │   │   ├── guide-settings.tsx    # Dec 模式、可变延迟
│   │   │   ├── guiding-log.tsx       # 导星日志查看器
│   │   │   └── lock-shift.tsx        # 锁定位置偏移（彗星追踪）
│   │   ├── calibration/              # 校准工具
│   │   │   ├── calibration-panel.tsx # 校准控制
│   │   │   └── polar-alignment.tsx   # 极轴校准工具
│   │   ├── connection/               # 连接管理
│   │   │   ├── connection-panel.tsx  # PHD2 连接
│   │   │   └── equipment-status.tsx  # 设备状态显示
│   │   ├── controls/                 # 导星控制
│   │   │   ├── guide-controls.tsx    # 主控制按钮
│   │   │   ├── quick-controls.tsx    # 快捷操作按钮
│   │   │   └── workflow-panel.tsx    # 一键工作流
│   │   ├── image/                    # 图像处理
│   │   │   ├── dark-library.tsx      # 暗场库
│   │   │   ├── defect-map.tsx        # 坏点图
│   │   │   └── overlay-settings.tsx  # 导星图像覆盖层自定义
│   │   ├── layout/                   # 布局组件
│   │   │   ├── header.tsx            # 应用头部
│   │   │   ├── mobile-nav.tsx        # 移动端导航
│   │   │   ├── floating-actions.tsx  # 浮动操作按钮
│   │   │   ├── resizable-panel.tsx   # 可调整大小面板系统
│   │   │   └── status-bar.tsx        # 状态栏
│   │   ├── log/                      # 日志和通知
│   │   │   ├── event-log.tsx         # 事件日志查看器
│   │   │   └── notification-center.tsx # 通知系统
│   │   ├── preview/                  # 预览和图表
│   │   │   ├── guide-preview.tsx     # 导星相机预览
│   │   │   ├── guide-chart.tsx       # 导星误差图表
│   │   │   ├── scatter-plot.tsx      # RA/Dec 散点图
│   │   │   ├── correction-chart.tsx  # 修正脉冲图表
│   │   │   └── histogram-panel.tsx   # 图像直方图
│   │   ├── settings/                 # 设置
│   │   │   ├── settings-dialog.tsx   # 设置对话框
│   │   │   └── collapsible-panel.tsx # 可折叠面板包装器
│   │   ├── stats/                    # 统计
│   │   │   ├── guide-stats.tsx       # 导星统计
│   │   │   └── stats-panel.tsx       # 统计面板
│   │   └── index.ts                  # 组件导出
│   └── ui/                           # shadcn/ui 组件 (30+)
├── lib/
│   ├── guider/
│   │   └── overlay-renderer.ts       # Canvas 覆盖层渲染
│   ├── hooks/
│   │   ├── use-guide-data.ts         # 导星数据聚合
│   │   ├── use-keyboard-shortcuts.ts # 键盘快捷键
│   │   ├── use-performance-monitor.ts # 性能监控
│   │   └── use-phd2.ts               # PHD2 连接 hook
│   ├── phd2/
│   │   ├── client.ts                 # PHD2 WebSocket 客户端
│   │   └── events.ts                 # 事件类型守卫和处理器
│   ├── stores/
│   │   ├── guider-store.ts           # 主应用状态
│   │   └── overlay-store.ts          # 覆盖层配置状态
│   ├── types/
│   │   ├── phd2.ts                   # PHD2 API 类型
│   │   └── overlay.ts                # 覆盖层配置类型
│   ├── utils/
│   │   ├── export-utils.ts           # 数据导出工具
│   │   ├── toast-utils.ts            # Toast 通知助手
│   │   └── validation-utils.ts       # 输入验证
│   └── utils.ts                      # 通用工具
├── mock-server/
│   └── index.ts                      # 模拟 PHD2 服务器
├── tests/
│   └── e2e/
│       └── guider.spec.ts            # E2E 测试 (Playwright)
├── docs/                             # 文档
│   ├── index.md                      # 文档首页
│   ├── architecture.md               # 架构概述
│   ├── overlay-system.md             # 覆盖层系统指南
│   ├── state-management.md           # 状态管理指南
│   ├── events.md                     # PHD2 事件参考
│   ├── event-server.md               # 事件服务器协议
│   ├── methods/                      # PHD2 API 方法
│   ├── components/                   # 组件文档
│   └── user-guide/                   # 用户指南
├── src-tauri/                        # Tauri 桌面应用 (Rust)
│   ├── src/                          # Rust 源码
│   └── tauri.conf.json               # Tauri 配置
└── package.json

配置

环境变量

创建 .env.local 文件配置环境变量：

# PHD2 连接默认值（可选）
NEXT_PUBLIC_PHD2_HOST=localhost
NEXT_PUBLIC_PHD2_PORT=4400

注意：只有以 NEXT_PUBLIC_ 为前缀的变量会暴露给浏览器。

Tauri 配置

编辑 src-tauri/tauri.conf.json 自定义桌面应用：

{
  "productName": "Cobalt Guider",
  "version": "0.1.0",
  "identifier": "com.elementastro.cobalt-guider",
  "app": {
    "windows": [
      {
        "title": "Cobalt Guider",
        "width": 1280,
        "height": 800,
        "resizable": true
      }
    ]
  }
}

路径别名

import { Button } from "@/components/ui/button";
import { usePHD2 } from "@/lib/hooks/use-phd2";
import { useGuiderStore } from "@/lib/stores/guider-store";

可用别名：

@/components → components/
@/lib → lib/
@/ui → components/ui/

PHD2 API 参考

本客户端实现了 PHD2 Event Server JSON-RPC 2.0 协议。

支持的方法

分类	方法
核心	`get_app_state`, `get_connected`, `set_connected`, `get_profiles`, `set_profile`, `shutdown`
设备	`get_exposure`, `set_exposure`, `get_current_equipment`, `get_cooler_status`, `set_cooler_state`
导星	`loop`, `stop_capture`, `find_star`, `guide`, `dither`, `set_paused`, `guide_pulse`
校准	`get_calibrated`, `clear_calibration`, `flip_calibration`, `get_calibration_data`
暗场/坏点	`start_dark_library_build`, `load_dark_library`, `start_defect_map_build`, `load_defect_map`
极轴校准	`start_drift_alignment`, `start_static_polar_alignment`, `start_polar_drift_alignment`
高级	`get_algo_param`, `set_algo_param`, `get_lock_shift_params`, `set_lock_shift_params`

事件类型

事件	描述
`Version`	连接时的服务器版本信息
`AppState`	应用状态变化
`GuideStep`	导星帧数据，包含误差/修正
`StarSelected`	星点选择确认
`StarLost`	导星星点丢失
`Calibrating`	校准进度
`SettleDone`	稳定操作完成

完整 API 文档请参见 docs/。

生产构建

Web 应用

pnpm build
# 输出：out/ 目录 - 部署到任何静态托管服务

桌面应用

pnpm tauri build

# 输出位置：
# Windows: src-tauri/target/release/bundle/msi/
# macOS: src-tauri/target/release/bundle/dmg/
# Linux: src-tauri/target/release/bundle/appimage/

测试

单元测试

pnpm test              # 运行一次
pnpm test:watch        # 监视模式
pnpm test:coverage     # 带覆盖率

E2E 测试

# 需要模拟服务器运行
pnpm test:e2e          # 运行所有 E2E 测试
pnpm test:e2e:ui       # 带 Playwright UI

E2E 测试覆盖：

连接流程
循环曝光和星点选择
导星启动/停止/暂停
图表数据显示
移动端导航

故障排除

连接问题

无法连接到 PHD2

确保 PHD2 正在运行且已启用 Event Server
检查端口 4400 的防火墙设置
验证连接对话框中的主机/端口

WebSocket 错误

PHD2 Event Server 使用 ws:// 而非 wss://
检查是否有其他客户端已连接

构建问题

端口 3000 被占用

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:3000 | xargs kill -9

Tauri 构建失败

pnpm tauri info    # 检查环境
rustup update      # 更新 Rust
cd src-tauri && cargo clean  # 清理缓存

资源

PHD2

开发

贡献

Fork 仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m 'feat: add amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开 Pull Request

许可证

MIT 许可证 - 详见 LICENSE。

支持

查看故障排除
查阅 PHD2 文档
在 GitHub 上提出 issue

FilesExpand file tree

README_zh.md

Latest commit

History