Imported from ChenXin-2009/OPIC (AGENTS.md). Install upstream with npx skills add ChenXin-2009/OPIC. Copyright stays with the author.

OPIC — AI Agent 开发指南

项目概述

OPIC (Open Integrated Cosmos) 是一个基于 Web 的多尺度宇宙可视化系统，支持从地球到星系的沉浸式探索。

• 技术栈: Next.js 16 + React 19 + TypeScript 5 + Three.js 0.170 + Cesium 1.139 + Zustand 5
• 测试: Jest 30 + ts-jest, jsdom 环境
• 路径别名: @/ → src/

目录结构速查

src/
├── app/                    # Next.js 页面和 API 路由
│   ├── page.tsx            # 主页面
│   └── api/                # 后端 API (卫星、发射、灾害、交通等)
├── components/             # React 组件
│   ├── canvas/3d/          # Three.js 3D 渲染组件
│   ├── ui/                 # 基础 UI 组件库
│   ├── window-manager/     # 浮动窗口系统
│   ├── dock/               # macOS 风格 Dock
│   ├── search/             # 天体搜索
│   ├── satellite/          # 卫星追踪 UI
│   ├── loading/            # 加载动画
│   ├── cesium/             # Cesium 地球组件
│   ├── exoplanets/         # 系外行星组件
│   ├── mod-manager/        # MOD 管理器 UI
│   ├── moon/               # 月球组件
│   ├── space-flight/       # 航天飞行 UI
│   ├── space-launches/     # 发射数据组件
│   ├── weather-disaster/   # 天气/灾害组件
│   ├── global-traffic/     # 全球交通组件
│   ├── gravity-grid/       # 重力网格组件
│   ├── debug/              # 调试工具
│   ├── error-boundaries/   # 错误边界
│   └── windows/            # 窗口组件
├── lib/                    # 核心业务逻辑 (无 React 依赖)
│   ├── 3d/                 # Three.js 渲染 (camera/, player/, utils/, orbit-curve/)
│   ├── astronomy/          # 天文计算 (轨道、时间、星表、历表)
│   ├── cesium/             # Cesium 地球集成
│   ├── config/             # 配置管理器
│   ├── coordinates/        # 统一坐标系变换 (ICRF 锚定的 Frame Graph)
│   ├── data/               # 宇宙数据加载器
│   ├── errors/             # 基础错误类型
│   ├── flight-dynamics/    # 飞行动力学 (RK4积分器/大气/推力/火箭方程)
│   ├── exoplanets/         # 系外行星坐标计算
│   ├── i18n/               # 国际化
│   ├── mod-manager/        # MOD 插件系统 (核心子系统，14 个模块)
│   ├── mods/               # 内置 MOD 实现
│   ├── search/             # 搜索引擎
│   ├── state/              # Zustand 状态管理 (5 个 store)
│   ├── store/              # Zustand store hooks
│   ├── utils/              # 数学/通用工具函数
│   ├── types/              # 共享类型定义
│   ├── satellite/          # 卫星数据处理
│   ├── accessibility/      # 无障碍支持
│   ├── constants/          # 全局常量
│   ├── design-system/      # 设计系统
│   ├── documentation/      # 文档工具
│   ├── loading/            # 加载逻辑
│   ├── parsers/            # 数据解析器
│   ├── performance/        # 性能监控
│   ├── pwa/                # PWA 支持
│   └── server/             # 服务端工具
├── core/                   # 核心模块
├── hooks/                  # React hooks
├── models/                 # 数据模型
├── reporters/              # 报告生成器
├── validators/             # 数据验证器
├── types/                  # 类型定义
├── utils/                  # 通用工具函数
├── styles/                 # 全局样式
└── test/                   # 集成和手动测试

核心约定

文件命名

导出模式

所有 lib/ 子模块使用 index.ts barrel 文件，采用命名导出风格：

// 正确 — 命名导出
export { CameraController } from './CameraController';
export { Planet } from './Planet';

// 避免 — 通配符重导出
export * from './CameraController';

导入别名

// 推荐 — 使用 @/ 别名
import { CameraController } from '@/lib/3d/camera/CameraController';

// 避免 — 相对路径深层嵌套
import { CameraController } from '../../../lib/3d/camera/CameraController';

模块职责

MOD 插件系统

src/lib/mod-manager/ 是核心子系统，包含 14 个模块：

mod-manager/
├── api/              # MOD API 层 (Camera, Celestial, Render, Satellite, Time)
├── config/           # 配置解析器
├── core/             # 核心 (EventBus, Lifecycle, Registry, DependencyResolver)
├── error/            # 错误类型层次 (ModError, PermissionError, SandboxError, ...)
├── permission/       # 权限系统
├── sandbox/          # 沙箱执行环境
├── service/          # 服务注册表
├── store/            # MOD 状态 store
├── utils/            # SemVer 解析、Manifest 验证
├── contribution/     # 贡献点系统 (Dock/Window/Command 注册)
├── discovery/        # MOD 自动发现
├── performance/      # 性能监控
├── persistence/      # 配置持久化
└── proxy/            # API 代理层

测试规范

测试位置

测试文件放在源码同级 __tests__/ 目录中：

src/lib/utils/
├── math.ts
├── validation.ts
└── __tests__/
    ├── math.test.ts
    └── validation.test.ts

测试风格

import { degreesToRadians } from '../math';

describe('math', () => {
  it('should convert degrees to radians', () => {
    expect(degreesToRadians(180)).toBeCloseTo(Math.PI);
  });
});

覆盖率

当前 Jest 配置的覆盖率阈值为 7%（全局），实际覆盖率：

• Lines: 41.76%, Statements: 41.22%, Branches: 29.66%, Functions: 46.41%
• 195 suites (3 skipped), 3301 tests (35 skipped), 0 failures
• TypeScript 编译：无错误

已实现 100% 行覆盖率的模块

• lib/astronomy/time.ts — 儒略日/日期转换
• lib/coordinates/frames/teme.ts — TEME 坐标变换
• lib/data/universe-data-parsers.ts — 宇宙二进制数据解析
• lib/search/SearchEngine.ts — 搜索引擎
• lib/mod-manager/proxy/APIProxyFactory.ts (99.43%)
• lib/astronomy/orbit/ephemeris-integration.ts (98.71%)
• lib/store/useSatelliteStore.ts (97.36%)

待覆盖的高难度模块（含 Three.js/异步/复杂 mock）

• lib/3d/ 下绝大多数 Three.js 渲染器（0%）
• lib/mod-manager/core/ModLifecycle.ts（0%）— 复杂链式调用
• lib/mod-manager/discovery/ModDiscovery.ts（0%）— 文件系统
• lib/mods/space-flight/useFlightSimulation.ts（0%）— React hook
• lib/astronomy/ephemeris/manager.ts（43.5%）— 异步加载 + window 事件
• lib/mod-manager/init.ts（63.5%）— 模块级导入图复杂
• lib/accessibility/keyboard-nav.ts（59.9%）— DOM 重
• lib/server/celestrakClient.ts（67%）— fetch + 重试逻辑
• lib/i18n/locale-manager.ts（75.9%）— 国际化

常见陷阱

1. @/ 路径别名 — 在 jest.config.js 和 tsconfig.json 中都配置了，测试中可直接使用
2. fs 模块 — Jest 的 jsdom 环境不支持 fs，涉及文件读写的代码（如遗留审计系统）在测试中会失败
3. Three.js 导入 — import * as THREE from 'three' 已在依赖中，测试环境可直接使用
4. Cesium 导入 — import('cesium') 仅为动态导入，测试时需 mock
5. Store 命名 — 状态文件使用 PascalCase（如 DockStore.ts），导出的 hook 使用 use 前缀（如 useDockStore）