262 lines
7.1 KiB
Markdown
262 lines
7.1 KiB
Markdown
# AGENTS.md
|
||
|
||
Kintone Customize Manager - Electron + React 应用，用于管理 Kintone 自定义资源。
|
||
|
||
## 1. 构建命令
|
||
|
||
```bash
|
||
# 开发（HMR + 热重载）
|
||
npm run dev
|
||
|
||
# 类型检查
|
||
npx tsc --noEmit
|
||
|
||
# 构建
|
||
npm run build
|
||
|
||
# 打包
|
||
npm run package:win # Windows
|
||
npm run package:mac # macOS
|
||
npm run package:linux # Linux
|
||
|
||
# 代码质量
|
||
npm run lint # ESLint 检查
|
||
npm run format # Prettier 格式化
|
||
|
||
# 测试
|
||
npm test # 运行测试
|
||
npm run test:watch # 监听模式
|
||
npm run test:coverage # 测试覆盖率
|
||
```
|
||
|
||
**重要**: 修改 `src/main/` 目录下的文件后，必须运行 `npm test` 确保测试通过。
|
||
|
||
## 2. 项目架构
|
||
|
||
```
|
||
src/
|
||
├── main/ # Electron 主进程
|
||
│ ├── index.ts # 入口，创建窗口
|
||
│ ├── ipc-handlers.ts # IPC 处理器（所有通信入口）
|
||
│ ├── storage.ts # 文件存储 + 密码加密
|
||
│ ├── kintone-api.ts # Kintone REST API 封装
|
||
│ └── __tests__/ # 主进程测试
|
||
├── preload/ # Preload 脚本
|
||
│ ├── index.ts # 暴露 API 到渲染进程
|
||
│ └── index.d.ts # 类型声明
|
||
├── shared/ # 跨进程共享代码
|
||
│ └── types/ # 共享类型定义
|
||
├── renderer/ # React 渲染进程
|
||
│ └── src/
|
||
│ ├── main.tsx # React 入口
|
||
│ ├── App.tsx # 根组件
|
||
│ ├── components/ # React 组件
|
||
│ └── stores/ # Zustand Stores
|
||
└── tests/ # 测试配置
|
||
├── setup.ts # 测试环境设置
|
||
└── mocks/ # Mock 文件
|
||
```
|
||
|
||
## 3. 路径别名
|
||
|
||
| 别名 | 路径 |
|
||
| ------------- | -------------------- |
|
||
| `@renderer/*` | `src/renderer/src/*` |
|
||
| `@main/*` | `src/main/*` |
|
||
| `@preload/*` | `src/preload/*` |
|
||
| `@shared/*` | `src/shared/*` |
|
||
|
||
## 4. 代码风格
|
||
|
||
### 导入顺序
|
||
|
||
```typescript
|
||
// 1. Node.js 内置模块
|
||
import { join } from "path";
|
||
import { app, BrowserWindow } from "electron";
|
||
|
||
// 2. 第三方库
|
||
import React, { useState, useEffect } from "react";
|
||
import { Button, Layout } from "antd";
|
||
|
||
// 3. 项目内部模块（别名）
|
||
import { useDomainStore } from "@renderer/stores";
|
||
|
||
// 4. 相对导入
|
||
import "./styles.css";
|
||
```
|
||
|
||
### 命名规范
|
||
|
||
- 组件文件/名: `PascalCase` (e.g., `DomainManager.tsx`)
|
||
- 工具函数文件: `camelCase` (e.g., `formatDate.ts`)
|
||
- Store 文件: `camelCase + Store` (e.g., `domainStore.ts`)
|
||
- 函数/变量: `camelCase` (e.g., `handleSubmit`)
|
||
- 常量: `UPPER_SNAKE_CASE` (e.g., `MAX_FILE_SIZE`)
|
||
- 类型/接口: `PascalCase` (e.g., `DomainConfig`)
|
||
|
||
### TypeScript 规范
|
||
|
||
- 显式类型定义，避免 `any`
|
||
- 使用字面量联合类型（如 `authType: "password" | "api_token"`）
|
||
- 异步函数返回 `Promise<T>`
|
||
- 使用类型守卫处理 `unknown`
|
||
|
||
### React 组件规范
|
||
|
||
- Hooks 放在组件顶部
|
||
- 事件处理函数使用 `useCallback`
|
||
- 使用 TypeScript 显式定义 props 类型
|
||
|
||
### Zustand Store 规范
|
||
|
||
- 使用 `persist` 中间件持久化状态
|
||
- 定义接口明确 state 和 actions 类型
|
||
|
||
## 5. IPC 通信规范
|
||
|
||
```typescript
|
||
type Result<T> = { success: true; data: T } | { success: false; error: string };
|
||
```
|
||
|
||
- IPC 调用使用 `invoke` 返回 `Result<T>`
|
||
- Preload 通过 `contextBridge.exposeInMainWorld` 暴露 API
|
||
|
||
## 6. UI 组件规范
|
||
|
||
**UI Kit 优先使用 LobeHub UI** (`@lobehub/ui`)，其次使用 Ant Design 6 + antd-style：
|
||
|
||
```typescript
|
||
import { Button } from '@lobehub/ui';
|
||
import { createStyles } from 'antd-style';
|
||
|
||
// antd-style 仅用于自定义样式
|
||
export const useStyles = createStyles(({ token, css }) => ({
|
||
container: css`padding: ${token.paddingLG}px;`
|
||
}));
|
||
```
|
||
|
||
- 国际化：使用中文默认 `import zhCN from 'antd/locale/zh_CN'`
|
||
- 禁止使用 Tailwind
|
||
|
||
## 7. 安全规范
|
||
|
||
- 密码使用 `electron` 的 `safeStorage` 加密存储
|
||
- WebPreferences 必须：`contextIsolation: true`, `nodeIntegration: false`, `sandbox: false`
|
||
|
||
## 8. 错误处理
|
||
|
||
- 所有 IPC 返回 `Result<T>` 格式
|
||
- 渲染进程检查 `result.success` 处理错误
|
||
|
||
## 9. fnm 环境配置
|
||
|
||
所有 npm/npx 命令需加载 fnm 环境：
|
||
|
||
```bash
|
||
# 使用 fnm wrapper（推荐）
|
||
~/.config/opencode/node-fnm-wrapper.sh npm run dev
|
||
|
||
# 或手动加载 fnm
|
||
eval "$(fnm env --use-on-cd)" && npm run dev
|
||
```
|
||
|
||
## 10. 工具使用规范
|
||
|
||
### 使用 `edit_file` 进行代码编辑
|
||
|
||
推荐使用 `edit_file` 工具进行代码修改，它支持部分代码片段编辑，无需提供完整文件内容：
|
||
|
||
```typescript
|
||
// 示例：替换单行代码
|
||
edit_file({
|
||
filePath: "src/main/index.ts",
|
||
edits: [{
|
||
pos: "42#XZ", // LINE#ID 格式
|
||
op: "replace",
|
||
lines: "new line content"
|
||
}]
|
||
})
|
||
|
||
// 示例：删除代码块
|
||
edit_file({
|
||
filePath: "src/main/index.ts",
|
||
edits: [{
|
||
pos: "40#AB",
|
||
end: "45#CD",
|
||
op: "replace",
|
||
lines: null // null 表示删除
|
||
}]
|
||
})
|
||
```
|
||
|
||
### LINE#ID 格式说明
|
||
|
||
- 格式：`{line_number}#{hash_id}`
|
||
- hash_id 是每行唯一的两位标识符
|
||
- 从 read 工具输出中获取正确的 LINE#ID
|
||
|
||
## 11. 注意事项
|
||
|
||
1. **ESM Only**: LobeHub UI 仅支持 ESM
|
||
2. **React 19**: 使用 `@types/react@^19.0.0`
|
||
3. **CSS 方案**: 使用 `antd-style`，禁止 Tailwind
|
||
4. **禁止 `as any`**: 使用类型守卫或 `unknown`
|
||
5. **函数组件优先**: 禁止 class 组件
|
||
|
||
## 12. MVP Phase - Breaking Changes
|
||
|
||
**This is MVP phase - breaking changes are acceptable for better design.** However, you MUST:
|
||
|
||
- **Explain what will break and why**: Document which components/APIs/workflows will be affected
|
||
- **Compare old vs new approach**: Show the differences and improvements
|
||
- **Document the tradeoffs**: What are the pros and cons of this change
|
||
- **Ask for confirmation**: If the change is significant (affects multiple modules or core architecture)
|
||
|
||
**Examples of acceptable breaking changes during MVP**:
|
||
|
||
- Refactoring data structures for better type safety
|
||
- Changing IPC communication patterns
|
||
- Restructuring component hierarchy
|
||
- Modifying store architecture
|
||
- Updating API interfaces
|
||
|
||
**Process for breaking changes**:
|
||
|
||
1. Identify the change and its impact scope
|
||
2. Document the breaking change in code comments
|
||
3. Explain the reasoning and benefits
|
||
4. If significant, ask user for confirmation before implementing
|
||
5. Update related documentation after implementation
|
||
|
||
## 13. 测试规范
|
||
|
||
### 测试框架
|
||
|
||
使用 **Vitest** 作为测试框架，与 Vite 原生集成。
|
||
|
||
### 测试文件结构
|
||
|
||
```
|
||
src/main/__tests__/ # 主进程测试
|
||
tests/
|
||
├── setup.ts # 全局测试设置
|
||
└── mocks/
|
||
└── electron.ts # Electron API Mocks
|
||
```
|
||
|
||
### 测试要求
|
||
|
||
1. **修改 `src/main/` 目录下的文件后，必须运行 `npm test` 确保测试通过**
|
||
2. 新增 API 功能时，应在 `src/main/__tests__/` 中添加对应测试
|
||
3. 测试文件命名：`*.test.ts`
|
||
|
||
### Mock Electron API
|
||
|
||
测试中需要 Mock Electron 的 API（如 `safeStorage`、`app` 等），已在 `tests/mocks/electron.ts` 中提供。
|
||
|
||
```typescript
|
||
// tests/setup.ts 中自动 Mock
|
||
vi.mock("electron", () => import("./mocks/electron"));
|
||
```
|