brainsmatics 1.1.64 → 1.1.65

package/.opencode/skills/react/SKILL.md

@@ -0,0 +1,49 @@
+---
+description: 专注于 React + TypeScript + Ant Design + Vite 的前端开发规范与最佳实践
+tags: [react, typescript, antd, vite, frontend]
+---
+
+# React & UI Development Skill
+
+## 角色定位
+你是一个资深的 React 架构师，精通 TypeScript 类型安全、Ant Design 组件库封装以及 Vite 构建优化。
+
+## 核心准则
+1. **函数式组件**: 始终使用函数式组件和 Hooks。
+2. **严格类型**: 所有组件 Props、State 和函数参数必须定义明确的 TypeScript 接口。禁止使用 `any`。
+3. **UI 规范**: 优先使用 Ant Design (v5+) 组件。如需自定义样式，优先考虑内联样式或 CSS Modules。
+4. **性能优化**: 合理使用 `useMemo` 和 `useCallback` 避免不必要的重绘。
+
+## 技术栈细节
+- **构建工具**: Vite (配置在 vite.config.ts)。
+- **状态管理**: 优先使用 Context API 或 Zustand (如果项目中已安装)。
+- **文档化**: 新组件应在 `src/stories` 目录下创建对应的 Storybook 文件 (`.stories.tsx`)。
+- **Ant Design**: 
+  - 使用 ConfigProvider 全局配置主题。
+  - 复杂表单使用 `Form` 组件并配合 `onFinish` 处理。
+
+## 常用模式示例
+### 组件结构
+```tsx
+import React from 'react';
+import { Button, Space } from 'antd';
+
+interface MyComponentProps {
+  title: string;
+  onAction?: () => void;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ title, onAction }) => {
+  return (
+    <Space direction="vertical">
+      <h3>{title}</h3>
+      <Button type="primary" onClick={onAction}>点击</Button>
+    </Space>
+  );
+};
+```
+
+## 调试与诊断
+- 如果遇到热更新(HMR)失效，检查文件命名是否符合规范（React 刷新通常要求导出名称与文件名关联）。
+- 检查 `tsconfig.json` 以确保路径别名（如 `@/`）配置正确。
+- 如果 Ant Design 样式未生效，检查是否在入口文件引入了样式重置或 ConfigProvider。

package/.opencode/skills/three/SKILL.md

@@ -0,0 +1,82 @@
+---
+description: 专注于在 React 架构下通过原生 Three.js 进行分布式场景管理和对象生命周期控制
+tags: [threejs, webgl, react-integration, scene-management]
+---
+
+# Three.js Distributed Architecture Skill
+
+## 角色定位
+你是一个精通 Three.js 架构的专家。你擅长在 React 环境中管理复杂的 3D 场景流，能够处理“父组件初始化场景，子组件管理物体”的分布式逻辑，并确保内存管理严格符合 WebGL 要求。
+
+## 核心准则 (分布式开发)
+1.  **单例维护**: 场景 (Scene)、渲染器 (Renderer) 和相机 (Camera) 由顶层提供（通常通过 React Context 或 Props 传递）。
+2.  **子组件职责**: 
+    - 子组件不应创建渲染器，只负责创建、添加和删除其管辖内的 `Object3D`。
+    - 在 `useEffect` 的挂载阶段将物体 `scene.add(object)`。
+    - 在卸载阶段必须执行 `scene.remove(object)` 并调用 `geometry.dispose()` 和 `material.dispose()`。
+3.  **引用一致性**: 使用 `useRef` 持有 Three.js 原生对象，确保在 React 重绘时对象不被重新创建。
+4.  **数据同步**: 监听 Props 变化，在 `useEffect` 中手动更新 Three.js 对象的属性（如 `position.set()`, `material.color.set()`）。
+
+## 推荐架构模式
+
+### 1. 顶层共享模式 (Context)
+建议使用 React Context 共享底层的 Three.js 实例，以便深层子组件访问。
+
+### 2. 子组件示例 (Logic Fragment)
+当需要编写一个负责渲染特定物体的子组件时，遵循以下结构：
+
+```typescript
+import React, { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+
+interface BoxProps {
+  scene: THREE.Scene; // 从父组件或 Context 传入
+  position: [number, number, number];
+  color: string;
+}
+
+export const BoxElement: React.FC<BoxProps> = ({ scene, position, color }) => {
+  const meshRef = useRef<THREE.Mesh>();
+
+  useEffect(() => {
+    // 初始化物体
+    const geo = new THREE.BoxGeometry(1, 1, 1);
+    const mat = new THREE.MeshStandardMaterial({ color });
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.position.set(...position);
+    
+    // 挂载到全局场景
+    scene.add(mesh);
+    meshRef.current = mesh;
+
+    // 销毁逻辑：必须彻底释放显存
+    return () => {
+      scene.remove(mesh);
+      geo.dispose();
+      mat.dispose();
+    };
+  }, [scene]); // 仅在场景对象变更时重新初始化
+
+  // 监听属性变化并同步到 Three.js 对象
+  useEffect(() => {
+    if (meshRef.current) {
+      meshRef.current.position.set(...position);
+      (meshRef.current.material as THREE.MeshStandardMaterial).color.set(color);
+    }
+  }, [position, color]);
+
+  return null; // 这是一个逻辑组件，不渲染任何 DOM
+};
+```
+## 调试与诊断
+1. **物体未显示**: 
+  - 确认子组件是否正确执行了 scene.add()。
+  - 确认 mesh.frustumCulled 是否导致物体在相机视野外被剔除。
+  - **检查父组件的渲染循环 (requestAnimationFrame) 是否正在运行。
+2. **内存持续增长**: 检查子组件卸载时是否遗漏了 geometry.dispose()。使用 renderer.info.memory 监控资源。
+3. **重复添加**: 确保 scene.add 逻辑在 useEffect 中有正确的清理机制，防止 React StrictMode 下重复挂载。
+
+## 注意事项
+1. **计算逻辑**: 复杂的几何计算应放在 useMemo 中或单独的 worker 中，避免阻塞 React 主线程。
+2. **渲染频率**: 不要将 Three.js 的每一帧状态同步回 React 的 State，这会导致严重的性能瓶颈。
+3. **坐标系一致性**: 在分布式开发中，所有子组件应约定使用统一的比例尺和坐标基准。

package/AGENTS.md

@@ -0,0 +1,219 @@
+# AGENTS.md
+
+This file defines how agentic coding assistants should operate in this repository.
+It is consumed by tools such as OpenCode, Cursor, Claude Code, etc.
+
+======================================================================
+Project Overview
+======================================================================
+
+Project name: brain-ui
+
+This is a frontend UI project built with:
+
+- React 18
+- TypeScript
+- Vite
+- Ant Design (antd)
+- Three.js
+- Storybook
+
+The project contains reusable UI components and 3D / visualization related components.
+Agents must follow the conventions and constraints defined below.
+
+======================================================================
+Package Management
+======================================================================
+
+Preferred package manager:
+- pnpm (preferred if lockfile exists)
+- npm or yarn if pnpm is unavailable
+
+Do NOT introduce new dependencies unless explicitly requested.
+
+======================================================================
+Development / Build Commands
+======================================================================
+
+Install dependencies:
+- pnpm install
+- npm install
+- yarn install
+
+Start development server:
+- pnpm dev
+- npm run dev
+
+Production build:
+- pnpm build
+- npm run build
+
+Preview production build:
+- pnpm preview
+- npm run preview
+
+======================================================================
+Storybook
+======================================================================
+
+Run Storybook locally:
+- pnpm storybook
+- npm run storybook
+
+Build Storybook:
+- pnpm build-storybook
+- npm run build-storybook
+
+Story files should be colocated with components and named:
+- *.stories.tsx
+
+======================================================================
+TypeScript Rules
+======================================================================
+
+- Always use TypeScript (.ts / .tsx)
+- Avoid `any` unless absolutely unavoidable
+- Prefer explicit types for:
+  - component props
+  - public functions
+- Use `interface` for component props and public APIs
+- Use `type` for unions, utility types, and internal helpers
+
+Example:
+
+interface ComponentProps {
+  value: number;
+  onChange?: (value: number) => void;
+}
+
+======================================================================
+React Rules
+======================================================================
+
+- Use function components only
+- Do NOT use class components
+- Follow the Rules of Hooks
+- Prefer composition over inheritance
+- Extract reusable logic into custom hooks
+- Avoid deeply nested JSX structures
+
+State management:
+- Prefer local state (useState / useReducer)
+- Avoid unnecessary global state
+- Use refs for mutable values that should not trigger re-render
+
+======================================================================
+Component Structure
+======================================================================
+
+Recommended component structure:
+
+ComponentName/
+  ├─ index.tsx
+  ├─ index.less | index.css | index.scss
+  ├─ ComponentName.stories.tsx
+  └─ types.ts (optional)
+
+Rules:
+- index.tsx exports the component
+- styles are colocated with the component
+- stories demonstrate common usage and edge cases
+
+======================================================================
+Ant Design (antd) Usage
+======================================================================
+
+- Use antd components as the primary UI building blocks
+- Avoid copying or modifying antd internal styles
+- Prefer composition instead of overriding antd components
+- Use className or style props for customization
+- Avoid deep CSS selectors targeting antd internals
+
+======================================================================
+Three.js Usage
+======================================================================
+
+- Keep Three.js logic isolated from UI logic when possible
+- Avoid heavy allocations inside render loops
+- Be mindful of GPU memory usage
+- Always clean up resources when no longer needed:
+  - geometry.dispose()
+  - material.dispose()
+  - texture.dispose()
+
+- Avoid unnecessary re-creation of:
+  - geometries
+  - materials
+  - textures
+- Prefer memoization for expensive objects
+
+======================================================================
+Performance Guidelines
+======================================================================
+
+- Avoid unnecessary re-renders
+- Use useMemo / useCallback for expensive computations
+- Do not create new objects/functions inside render unless required
+- Be careful with requestAnimationFrame loops
+- Pay attention to performance in Three.js related code
+
+======================================================================
+Error Handling
+======================================================================
+
+- Do not silently swallow errors
+- Log meaningful error messages
+- Validate external or dynamic data before usage
+- Prefer early returns over deeply nested conditionals
+
+======================================================================
+Imports & Naming
+======================================================================
+
+Imports order:
+1. React and external libraries
+2. UI components
+3. hooks / utils
+4. styles
+
+Naming conventions:
+- Components: PascalCase
+- Hooks: useSomething
+- Files: follow existing project convention
+- Variables: camelCase
+
+======================================================================
+Testing (If Present)
+======================================================================
+
+- Prefer testing public behavior over implementation details
+- Avoid excessive snapshot testing
+- Keep tests focused and readable
+
+======================================================================
+Agent Behavior Rules (IMPORTANT)
+======================================================================
+
+When modifying code, agents MUST:
+
+1. Read existing code before making changes
+2. Follow existing patterns and conventions
+3. Keep changes minimal and scoped
+4. Do NOT refactor unrelated code
+5. Do NOT introduce new dependencies unless requested
+6. Ensure TypeScript types remain correct
+7. Ensure Storybook stories still work if affected
+
+If a change is non-trivial, explain WHY the change is needed.
+
+======================================================================
+Out of Scope
+======================================================================
+
+- Backend logic
+- API implementations
+- CI/CD configuration unless explicitly requested
+
+======================================================================
+End of AGENTS.md
+======================================================================