kintone-customize-manager/AGENTS.md

AGENTS.md

Kintone Customize Manager - Electron + React 应用，用于管理 Kintone 自定义资源。

1. 构建命令

# 开发（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 格式化

2. 项目架构

src/
├── main/           # Electron 主进程
│   ├── index.ts          # 入口，创建窗口
│   ├── ipc-handlers.ts   # IPC 处理器（所有通信入口）
│   ├── storage.ts        # 文件存储 + 密码加密
│   └── kintone-api.ts    # Kintone REST API 封装
├── preload/        # Preload 脚本
│   ├── index.ts          # 暴露 API 到渲染进程
│   └── index.d.ts        # 类型声明
├── shared/         # 跨进程共享代码
│   └── types/            # 共享类型定义
└── renderer/       # React 渲染进程
    └── src/
        ├── main.tsx      # React 入口
        ├── App.tsx       # 根组件
        ├── components/   # React 组件
        ├── stores/       # Zustand Stores
        └── locales/      # i18n 翻译文件

数据流

Renderer (React) → Preload API → IPC → Main Process → Storage/Kintone API
                                  ↓
                            Result<T> 返回

3. 路径别名

别名	路径
@renderer/*	src/renderer/src/*
@main/*	src/main/*
@preload/*	src/preload/*
@shared/*	src/shared/*

4. 代码风格

导入顺序

// 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 通信规范

type Result<T> = { success: true; data: T } | { success: false; error: string };

• IPC 调用使用 invoke 返回 Result<T>
• Preload 通过 contextBridge.exposeInMainWorld 暴露 API
• 所有 IPC handlers 集中在 src/main/ipc-handlers.ts

6. UI 组件规范

UI Kit 优先使用 LobeHub UI (@lobehub/ui)，其次使用 Ant Design 6 + antd-style：

import { Button } from "@lobehub/ui";
import { createStyles } from "antd-style";

// antd-style 仅用于自定义样式
export const useStyles = createStyles(({ token, css }) => ({
  container: css`
    padding: ${token.paddingLG}px;
  `,
}));

• 禁止使用 Tailwind
• ESM Only: LobeHub UI 仅支持 ESM

7. 国际化 (i18n)

• 支持语言: en-US, ja-JP, zh-CN
• 翻译文件位置: src/renderer/src/locales/{locale}/{namespace}.json
• 使用 react-i18next 进行翻译
• Ant Design 默认使用日文: import jaJP from 'antd/locale/ja_JP'

8. 安全规范

• 密码使用 electron 的 safeStorage 加密存储
• WebPreferences 必须：contextIsolation: true, nodeIntegration: false, sandbox: false

9. 错误处理

• 所有 IPC 返回 Result<T> 格式
• 渲染进程检查 result.success 处理错误

10. fnm 环境配置

所有 npm/npx 命令需加载 fnm 环境：

# 使用 fnm wrapper（推荐）
~/.config/opencode/node-fnm-wrapper.sh npm run dev

# 或手动加载 fnm
eval "$(fnm env --use-on-cd)" && npm run dev

11. 技术栈约束

1. React 19: 使用 @types/react@^19.0.0
2. CSS 方案: 使用 antd-style，禁止 Tailwind
3. 禁止 as any: 使用类型守卫或 unknown
4. 函数组件优先: 禁止 class 组件

12. 沟通规范

1. 人设: 在回答的末尾加上「🦐」，用于确认上下文是否被正确保留
2. 语言: 使用中文进行回答

13. 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