| 1 | # Agent.md |
| 2 | |
| 3 | > 不要跑 `npm run lint`。 |
| 4 | > 不要跑 `npm run build`。 |
| 5 | |
| 6 | ## Project |
| 7 | |
| 8 | Electron 桌面应用，主进程 (`src/main/`) + 渲染进程 (`src/renderer/`) + 共享类型 (`src/shared/`)。 |
| 9 | |
| 10 | ## Code Style |
| 11 | |
| 12 | - `singleQuote`, `no semi`, `printWidth: 100`, `trailingComma: none` |
| 13 | - 路径别名: `@shared/*`, `@renderer/*` |
| 14 | |
| 15 | ## Execution Rules |
| 16 | |
| 17 | - 先定位变更属于生成、编辑、导入、导出还是运行时；不要只修单一路径 |
| 18 | - 公共规则改动要同时确认生成与编辑链路是否覆盖，尤其是整页编辑、deck 编辑、selector 编辑 |
| 19 | - 改运行时资源时，同步确认 session asset 兼容/刷新机制 |
| 20 | - 修 bug 时优先补定向回归测试，覆盖当前问题和相邻入口 |
| 21 | - 验证优先跑最小相关测试；不要跑 `npm run lint` 或 `npm run build` |
| 22 | |
| 23 | ## Testing |
| 24 | |
| 25 | - 框架：Vitest + happy-dom，测试文件放 `tests/unit/` 下，按功能域分子目录，文件名 `*.test.ts` |
| 26 | - 跑测试：`pnpm test`，跑单个文件：`pnpm test -- tests/unit/xxx/foo.test.ts` |
| 27 | - 修 bug 或加功能时，必须补对应测试到 `tests/unit/`；测试不通过就继续修代码直到通过 |
| 28 | - 注意：样式ui改动不需要写测试 |
| 29 | |
| 30 | |
| 31 | ## React 组件编写规范 |
| 32 | |
| 33 | ### 核心原则 |
| 34 | |
| 35 | #### 1. 逻辑内聚，少传 props |
| 36 | - **能写在组件内的逻辑就写在组件内**，不要通过 props 从父组件传进来 |
| 37 | - 事件处理、数据获取、状态管理，都优先写在组件自己里面 |
| 38 | |
| 39 | ```jsx |
| 40 | // ✅ 好 |
| 41 | function ProductCard({ id }) { |
| 42 | const [count, setCount] = useState(0) |
| 43 | const handleBuy = () => { /* 逻辑写这里 */ } |
| 44 | return <button onClick={handleBuy}>购买</button> |
| 45 | } |
| 46 | |
| 47 | // ❌ 坏 |
| 48 | function ProductCard({ count, onBuy }) { /* 逻辑都从外面传 */ } |
| 49 | ``` |
| 50 | |
| 51 | #### 2. 跨组件状态用 Zustand |
| 52 | - 多个组件需要共享的数据 → 放 zustand store |
| 53 | - 不要通过 props 一层层传 |
| 54 | |
| 55 | ```jsx |
| 56 | const useStore = create((set) => ({ |
| 57 | user: null, |
| 58 | setUser: (user) => set({ user }) |
| 59 | })) |
| 60 | |
| 61 | // 任何组件直接拿来用，不用传 props |
| 62 | const user = useStore(state => state.user) |
| 63 | ``` |
| 64 | |
| 65 | #### 3. 复用逻辑抽成自定义 Hook |
| 66 | - 多个组件都需要**相同的有状态逻辑**时，抽成自定义 Hook |
| 67 | - Hook 放在 `hooks/` 目录下，以 `use` 开头 |
| 68 | |
| 69 | ```jsx |
| 70 | // hooks/useProductData.js |
| 71 | function useProductData(productId) { |
| 72 | const [product, setProduct] = useState(null) |
| 73 | const [loading, setLoading] = useState(false) |
| 74 | |
| 75 | useEffect(() => { |
| 76 | fetchProduct(productId).then(setProduct) |
| 77 | }, [productId]) |
| 78 | |
| 79 | return { product, loading } |
| 80 | } |
| 81 | |
| 82 | // 组件中使用 |
| 83 | function ProductCard({ id }) { |
| 84 | const { product, loading } = useProductData(id) |
| 85 | // 不用从 props 传 product 和 loading |
| 86 | } |
| 87 | ``` |
| 88 | |
| 89 | #### 4. 什么情况才用 props？ |
| 90 | 只传这两类东西： |
| 91 | - **配置项**：`size`, `disabled`, `variant` |
| 92 | - **纯展示数据**：`title`, `description` |
| 93 | |
| 94 | ## 简单检查 |
| 95 | 写代码前问一句：*"这个逻辑/状态能不能直接写在当前组件里？"* |
| 96 | - 能 → 就写里面 |
| 97 | - 不能，但多个组件都需要 → 放 zustand 或抽成自定义 Hook |
| 98 | - 实在不行 → 才传 props |
| 99 | |
| 100 | ## 记住 |
| 101 | **组件要自己管自己，别当父组件的提线木偶。** |
| 102 | |
| 103 |