docs: translate repository documentation to English (#72)

This commit is contained in:
vin authored and GitHub committed 2026-02-06 22:14:06 +08:00
1 parent 2ae2216f1e
commit 18389b9753
8 files changed
+456 -441

No files matched your search

+204 -192
View File
@@ -20,157 +20,169 @@ Keep this managed block so 'openspec update' can refresh the instructions.
<!-- OPENSPEC:END -->
# 用户指南
# User Guide
本文是 AI 助手在本仓库工作的用户级指南。中文为主、工具与脚本偏好统一、并纳入你补充的技术栈与开发注意事项。
This document is a user-level guide for AI assistants working in this repository. It standardizes language, tool/script preferences, and development notes for the current tech stack.
## 💬 沟通约定
## 💬 Communication Conventions
- **语言**: 对话、待办、代码相关内容(注释、UI 文案、提交信息、PR 描述等)统一使用中文。
- **结论先行**: 回答先给出核心结论/摘要,再补充细节。
- **引用**: 引用具体代码时,务必给出完整文件路径(如 `src/main.ts:42`)。
- **Language**: Use English consistently for conversation, TODOs, and code-related content (comments, UI copy, commit messages, PR descriptions, and similar artifacts).
- **Conclusion first**: Start with the core conclusion/summary, then provide details.
- **References**: When citing code, always provide full file paths (for example, `src/main.ts:42`).
## 💻 运行环境与工具
## 💻 Runtime and Tooling
- **Runtime**: Node.js (Electron 环境)
- **Node**: 建议 Node.js 20+
- **包管理器**: `npm` (本项目包含 package-lock.json,强制使用 npm)
- **构建工具**: Electron Forge + Vite
- **终端环境**: Windows (PowerShell) / 可安全使用 VSCode MCP 工具
- **Runtime**: Node.js (Electron environment)
- **Node**: Recommended Node.js 20+
- **Package manager**: `npm` (this project includes `package-lock.json`; use npm only)
- **Build tools**: Electron Forge + Vite
- **Terminal**: Windows (PowerShell) / VSCode MCP tools can be used safely
## 🧩 技术栈总览 (Tech Stack)
## 🧩 Tech Stack Overview
- **Frontend**:
- React 19, TypeScript
- Tailwind CSS v4, `clsx`, `tailwind-merge`, `tailwindcss-animate`
- Radix UI (Primitives), Lucide React (Icons), Sonner (Toast)
- Radix UI (Primitives), Lucide React (Icons), Simple Icons (`@icons-pack/react-simple-icons`)
- `class-variance-authority` (CVA), `react-i18next` + `i18next`
- TanStack Router (Routing), TanStack Query (State Management)
- Components: 模块化设计,`src/components`
- Components: Modular design under `src/components`
- **Backend (Electron Main/Server)**:
- Electron (Main/Preload/Renderer 架构)
- NestJS (用于内部代理/网关服务,由 Main Process 启动)
- Better-SQLite3 (本地数据库), Drizzle ORM (如果后续引入) / Raw SQL
- ORPC (Type-safe RPC)
- Zod (Validation)
- Electron (Main/Preload/Renderer architecture)
- NestJS (internal proxy/gateway service, started by main process)
- Better-SQLite3 (local database), Drizzle ORM / Raw SQL
- ORPC (type-safe RPC)
- gRPC (`@grpc/grpc-js`, `@grpc/proto-loader`)
- Logging: `winston` + `winston-daily-rotate-file`
- Zod (validation)
- **Testing**:
- Vitest (Unit/Integration Tests)
- Playwright (E2E Tests)
- Vitest (unit/integration), Testing Library
- Playwright (E2E)
## 📁 目录结构
## 📁 Directory Structure
```plaintext
.
├─ src/
│ ├─ components/ # React UI 组件 (ui/ 存放基础组件)
│ ├─ hooks/ # Custom React Hooks
│ ├─ ipc/ # Electron IPC 处理逻辑 (Database, Config, etc.)
│ ├─ layouts/ # 页面布局组件
│ ├─ lib/ # 通用工具库
│ ├─ routes/ # TanStack Router 路由定义
│ ├─ server/ # NestJS 后端服务逻辑 (Gateway/Proxy)
│ ├─ services/ # 业务服务层
│ ├─ styles/ # 全局样式 (Tailwind class)
│ ├─ types/ # TypeScript 类型定义
│ ├─ utils/ # 通用工具函数
│ ├─ App.tsx # React 应用入口
│ ├─ main.ts # Electron 主进程入口
│ ├─ preload.ts # Electron 预加载脚本
│ └─ renderer.ts # Electron 渲染进程入口
├─ forge.config.ts # Electron Forge 配置
│ ├─ actions/ # App actions and flow orchestration
│ ├─ assets/ # Static assets
│ ├─ components/ # React UI components (base components under ui/)
│ ├─ constants/ # Constants
│ ├─ hooks/ # Custom React hooks
│ ├─ ipc/ # Electron IPC logic (Database, Config, etc.)
│ ├─ layouts/ # Layout components
│ ├─ lib/ # Shared low-level utilities
│ ├─ localization/ # i18n translation resources
│ ├─ mocks/ # Mock data for tests and development
│ ├─ routes/ # TanStack Router route definitions
│ ├─ server/ # NestJS backend logic (Gateway/Proxy)
│ ├─ services/ # Service layer
│ ├─ styles/ # Global styles (Tailwind classes)
│ ├─ tests/ # Test code
│ ├─ types/ # TypeScript type definitions
│ ├─ utils/ # Utility functions
│ ├─ App.tsx # React app entry
│ ├─ main.ts # Electron main entry
│ ├─ preload.ts # Electron preload script
│ └─ renderer.ts # Electron renderer entry
├─ forge.config.ts # Electron Forge config
└─ package.json
```
## 🧱 组件架构(Component Architecture)
## 🧱 Component Architecture
- **模块化组件**: 每个组件使用独立目录,至少包含 `.tsx` 以及可能的样式或子组件。
- **共享能力**: 通用函数置于 `src/utils/`,底层通用封装置于 `src/lib/`。
- **服务层**: 统一在 `src/services/` 或 `src/ipc/` 中封装数据访问,前端仅依赖 IPC 或 RPC 调用。
- **Modular components**: Each component should have its own directory, with at least a `.tsx` file and optional styles/subcomponents.
- **Shared capabilities**: General helpers in `src/utils/`; low-level shared wrappers in `src/lib/`.
- **Service layer**: Centralize data access in `src/services/` or `src/ipc/`; frontend should consume IPC or RPC only.
## 📦 常用脚本 (Scripts)
## 📦 Common Scripts
所有命令使用 `npm` 执行:
Use `npm` for all commands:
- **开发 (Dev)**:
- `npm start` - 启动 Electron 开发环境 (Electron Forge)
- `npm run lint` - 运行 ESLint 检查
- `npm run format` - 运行 Prettier 格式化检查
- **Development (Dev)**:
- `npm start` - Start Electron dev environment (Electron Forge)
- `npm run lint` - Run ESLint checks
- `npm run format` - Run Prettier check
- `npm run format:write` - Auto-format with Prettier
- `npm run type-check` - Run TypeScript type check
- **构建 (Build)**:
- `npm run package` - 打包应用 (生成的只有应用包)
- `npm run make` - 构建并生成分发安装包 (Make)
- `npm run publish` - 发布应用
- **Build**:
- `npm run package` - Package app (application bundle only)
- `npm run make` - Build and generate distributable installers
- `npm run publish` - Publish app
- **测试 (Test)**:
- `npm test` - 运行 Vitest 单元测试
- `npm run test:unit` - 同上
- `npm run test:e2e` - 运行 Playwright 端到端测试
- `npm run test:all` - 运行所有测试
- **Testing**:
- `npm test` - Run Vitest tests
- `npm run test:watch` - Run Vitest in watch mode
- `npm run test:unit` - Same as above for unit-focused runs
- `npm run test:e2e` - Run Playwright E2E tests
- `npm run test:all` - Run all tests
### 运行单个测试 (Running Single Tests)
### Running a Single Test
- 单元测试: `npm run test:unit path/to/test.test.ts`
- E2E 测试: `npm run test:e2e path/to/test.spec.ts`
- 类型检查: `npm run type-check`
- Unit test: `npm run test:unit path/to/test.test.ts`
- E2E test: `npm run test:e2e path/to/test.spec.ts`
- Type check: `npm run type-check`
## 🧪 开发注意事项(Development Notes)
## 🧪 Development Notes
- **Build**: 构建阶段忽略 TS/ESLint 错误(如有特定配置或 CI 要求,请以实际为准)。
- **DevTools**: 项目集成了 `code-inspector-plugin`,开发时支持从页面元素直接跳转代码(Shift+Click)。
- **React**: React Strict Mode 关闭。
- **NestJS**: 作为 Electron 子进程运行,日志输出在主进程控制台。
- **Build**: Build stage may ignore TS/ESLint errors depending on project/CI configuration.
- **DevTools**: `code-inspector-plugin` is integrated; use `Shift + Click` on page elements to jump to source code.
- **React**: React Strict Mode is disabled.
- **NestJS**: Runs as an Electron child process; logs are visible in main-process console.
## �️ 安全与数据 (Security & Data)
## Security and Data
- **安全**: 绝不提交密钥;敏感配置使用环境变量;验证所有用户输入;敏感数据加密存储。
- **数据库**: 使用 Better-SQLite3;所有操作封装在 Services 层;必须使用 Prepared Statements;独立测试 DB 操作。
- **国际化**: 使用 `react-i18next`;Key 使用 kebab-case;翻译文件存放在 `src/localization/`。
- **Security**: Never commit secrets; use environment variables for sensitive config; validate all user input; encrypt sensitive data.
- **Database**: Use Better-SQLite3; encapsulate operations in services layer; always use prepared statements; test DB operations independently.
- **i18n**: Use `react-i18next`; keys should use kebab-case; translation files are stored in `src/localization/`.
## �📝 代码规范 (Conventions)
## 📝 Conventions
- **文件命名**:
- 组件: PascalCase (e.g., `Button.tsx`)
- 工具/配置: camelCase 或 kebab-case
- **导入路径**: 使用 `@/` 别名指向 `src/` 目录。
- **类型安全**: 严禁使用 `any`,利用 Zod 和 TypeScript 确保全链路类型安全。
- **组件设计**:
- 优先使用 Radix UI Primitives。
- 样式使用 Tailwind Utility Classes,避免 CSS Modules (除非必要)。
- **API 通信**: 前端调用后端优先使用 ORPC 客户端或 IPC,确保类型推导。
- **File naming**:
- Components: PascalCase (for example, `Button.tsx`)
- Tools/config: camelCase or kebab-case
- **Import paths**: Use `@/` alias for `src/`.
- **Type safety**: Avoid `any`; enforce end-to-end type safety with Zod + TypeScript.
- **Component design**:
- Prefer Radix UI Primitives.
- Use Tailwind utility classes; avoid CSS Modules unless necessary.
- **API communication**: Frontend should prioritize ORPC client or IPC for strong type inference.
### 命名约定 (Naming Specifics)
### Naming Specifics
- **Functions/Variables**: camelCase (e.g., `handleClick`, `isCurrent`)
- **Constants**: UPPER_SNAKE_CASE (e.g., `LOCAL_STORAGE_KEYS`)
- **Functions/Variables**: camelCase (for example, `handleClick`, `isCurrent`)
- **Constants**: UPPER_SNAKE_CASE (for example, `LOCAL_STORAGE_KEYS`)
- **Files**:
- Services: `ServiceName.service.ts`
- Types: `type-name.ts`
### 导入组织 (Import Organization)
### Import Organization
```typescript
// 1. React 和核心库
// 1. React and core libraries
import React, { useEffect } from 'react';
import { createRoot } from 'react-dom/client';
// 2. 外部依赖 (按字母顺序)
// 2. External dependencies (alphabetical order)
import { useTranslation } from 'react-i18next';
import { formatDistanceToNow } from 'date-fns';
// 3. 内部导入 (使用 @ 别名)
// 3. Internal imports (using @ alias)
import { Account } from '@/types/account';
import { Card, CardContent } from '@/components/ui/card';
```
### 组件结构 (Component Structure)
### Component Structure
```typescript
// 1. 导入
// 1. Imports
import React, { useState } from 'react';
// 2. 类型定义
// 2. Type definitions
interface ComponentProps { /* props */ }
// 3. 组件实现
// 3. Component implementation
export const Component: React.FC<ComponentProps> = ({ prop1 }) => {
// 4. Hooks
const { t } = useTranslation();
@@ -179,14 +191,14 @@ export const Component: React.FC<ComponentProps> = ({ prop1 }) => {
};
```
> 提交前请确保执行 `npm run lint` 和 `npm run format`。
> Before commit, run `npm run lint` and `npm run format`.
## 📝 终端输出与引用规范
## 📝 Terminal Output and References
- 代码块优先,避免 Markdown 表格与 mermaid(Claude 代码块渲染更稳定)。
- 表格(如需)左对齐;中文字符等宽注意显示差异。
- Prefer code blocks; avoid Markdown tables and Mermaid unless necessary.
- If tables are used, keep them left-aligned and check display consistency.
示例:
Example:
```plaintext
+------+---------+---------+
@@ -197,77 +209,77 @@ export const Component: React.FC<ComponentProps> = ({ prop1 }) => {
+------+---------+---------+
```
### 引用规范(References)
### Reference Rules
- 外部资源:使用完整可点击链接(Issue、文档、API 参考)。
- 源码位置:使用完整文件路径(可附行号)。
- External resources: use full clickable links (issues, docs, API references).
- Source code location: use full file paths (optionally with line numbers).
示例:
Example:
```plaintext
- “resolveFilePath 负责该逻辑”
- “VSCode 在撤销操作上存在既知限制”
- "resolveFilePath owns this logic"
- "VSCode has a known limitation in undo behavior"
🔗 References:
References:
- resolveFilePath: src/utils/workspace.ts:40
- VSCode undo limitation: https://github.com/microsoft/vscode/issues/77190
```
## 🏷️ Markdown 书写
## 🏷️ Markdown Writing
- 代码块语言不要留空,无法确定时使用 `plaintext`。
- 标题后保留一行空行,便于渲染与阅读。
- Always specify a language for fenced code blocks; use `plaintext` if unsure.
- Keep one blank line after headings for readability.
## 换行规范
## Line-Break Rule
return 等语句不要与其他语句在同一行,而是单独保持一行
`return` and similar statements should not share a line with other statements. Keep them on separate lines.
## 💭 注释规范
## 💭 Commenting Rules
- 必注释场景:复杂业务/算法、特殊行为、重要设计取舍、关键参考链接。
- 原则:
- 注释“为什么”(Why),非“做了什么”(What)、非变更记录(Changelog)。
- 修改代码时同步更新注释(过时注释比无注释更糟)。
- 优先使用 JSDoc,复杂函数先给高层概览,函数体内按步骤(1、2、3…)标注关键过程。
- 中英文之间适当空格,提升可读性;不要为删除的旧代码写注释。
- Required comment scenarios: complex business logic/algorithms, non-obvious behaviors, important design tradeoffs, and key reference links.
- Principles:
- Explain **why**, not **what**, and not changelog history.
- Update comments whenever related code changes.
- Prefer JSDoc; for complex functions, start with high-level overview, then annotate key steps (1, 2, 3...).
- Keep spacing between English and Chinese words if both appear for readability; do not comment deleted legacy code.
“质量自检”问题:六个月后新同事看到这条注释能得到什么有用信息?若答案是“没有”,删掉它。
Quality self-check: six months later, what useful context does a new teammate gain from this comment? If the answer is "none", remove it.
示例:
Example:
```typescript
/**
* 处理支付请求,多步骤校验
* Handle payment request with multi-step validation.
*/
function processPayment(request: PaymentRequest) {
// 1. 数据校验
// 2. 风控评估(低/中/高差异处理)
// 3. 网关调用
// 4. 用户通知
// 1. Input validation
// 2. Risk evaluation (low/medium/high paths)
// 3. Gateway call
// 4. User notification
}
export enum BudgetType {
Free = 'free',
/** ✅ 推荐使用 JSDoc,而不是行尾注释 */
/** ✅ Prefer JSDoc over end-of-line comments */
Package = 'package',
}
```
## 🛠️ 开发指南
## 🛠️ Development Guide
### 通用原则
### General Principles
- 优先稳定与可维护性,其次再谈性能优化。
- 面对不确定性:明确假设、取舍与验证方案;先沟通再实施。
- 信任既定前置条件,避免对承诺不变量的过度防御;若出现冲突,更新方案而非额外兜底。
- 老代码重构保守推进,新功能实现可采用更现代方式。
- 避免过早优化:先以简单直接的实现达成功能,确需时再优化(避免先行加缓存/抖动或拆分成过多文件)。
- 对于 if,while 等条件、循环语句必须加上花括号,不能与return、break、continue 等语句同级。
- Prioritize stability and maintainability before optimization.
- For uncertainty, state assumptions/tradeoffs/validation approach clearly, then implement.
- Trust agreed preconditions; avoid excessive defensive coding against guaranteed invariants.
- Refactor legacy code conservatively; use modern approaches for new features where appropriate.
- Avoid premature optimization: implement simple and direct first; optimize only when justified.
- Always use braces for control flow (`if`, `while`, and similar statements).
### 错误处理 (Error Handling)
### Error Handling
```typescript
// 异步操作使用 try-catch
// Use try-catch for async operations
try {
const result = await someOperation();
return result;
@@ -276,92 +288,92 @@ try {
throw new Error('Failed to complete operation');
}
// 使用正确的错误类型
// Use proper error typing
if (error instanceof Error) {
/* 处理 Error 实例 */
/* handle Error instance */
}
```
### 新功能实现
### New Feature Implementation
- 代码应清晰、可读、可复用、有效率且可测试。
- 倾向选用成熟可靠的现代 API。
- Code should be clear, readable, reusable, efficient, and testable.
- Prefer mature and reliable modern APIs.
### 重构与修 Bug
### Refactoring and Bug Fixing
- 倾向增量式改动;如需大重构,先就范围对齐再推进。
- 保持原结构与风格,避免过度抽象引入新风险。
- Prefer incremental changes; align scope first before large refactors.
- Preserve existing structure and style; avoid over-abstraction risk.
### 开发生命周期(Checklist)
### Development Lifecycle Checklist
探索/规划:
Exploration / planning:
- \[ ] 充分理解需求,分步思考与列计划(3–6 步)
- \[ ] 优先查阅文档与既有方案
- \[ ] 通过阅读实际代码验证想法
- \[ ] 形成 TODO 列表
- \[ ] Fully understand requirements; break down into 3-6 steps
- \[ ] Review documentation and existing solutions first
- \[ ] Validate ideas by reading actual code
- \[ ] Build a TODO list
实现/重构/修复:
Implementation / refactor / fix:
- [ ] 阅读相关模板与周边代码,沿用既有模式
- [ ] Fail fast:对非法输入/状态抛错,尽早暴露问题
- [ ] 在约束内尽力提升前端交互与体验
- [ ] Review related templates and surrounding code; follow existing patterns
- [ ] Fail fast on invalid inputs/states
- [ ] Improve frontend interaction and UX within constraints
验收/校验:
Acceptance / validation:
- \[ ] 通过测试或临时脚本验证实现
- \[ ] 多次增量修改后回看是否可合并为一次更连贯的修改
- \[ ] 运行质量检查
- \[ ] 更新相关文档
- \[ ] Validate implementation through tests or temporary scripts
- \[ ] After multiple incremental edits, evaluate whether changes should be consolidated
- \[ ] Run quality checks
- \[ ] Update related docs
总结/输出:
Summary / output:
- \[ ] 检查输出格式要求
- \[ ] 列出与原计划偏差与关键决策,便于人工复核
- \[ ] 提供优化建议
- \[ ] 在结尾提供完整引用链接
- \[ ] Verify output formatting requirements
- \[ ] List deviations from plan and key decisions for human review
- \[ ] Provide optimization suggestions
- \[ ] Include full references at the end
## 🔍 代码质量与 Lint
## 🔍 Code Quality and Lint
- 变量命名具描述性(如 `mutationObserver`、`button`、`element`),避免 `mo`、`btn`、`el`。
- 检查缺失的重要注释,并保持注释语言一致。
- 使用 VSCode MCP 诊断工具查看 TS/ESLint 报告并修复关键问题。
- 若新增/修改测试,需运行并修复测试后再提交。
- Use descriptive variable names (`mutationObserver`, `button`, `element`) and avoid `mo`, `btn`, `el`.
- Check for missing critical comments and keep comment language consistent.
- Use VSCode MCP diagnostics for TS/ESLint issues and fix key findings.
- If tests are added/updated, run and fix them before submission.
## ⛔ 需要显式确认的操作
## ⛔ Operations Requiring Explicit Confirmation
- 运行具有破坏性的命令
- 执行 `git commit`、`git push`
- 新建测试文件(先由维护者进行人工审核)
- Running destructive commands
- Executing `git commit` or `git push`
- Creating new test files (maintainer review required first)
## 🔧 工具偏好与命令
## 🔧 Tool Preferences and Commands
包与脚本:
Packages and scripts:
- `npm install` (或简写 `npm i`)
- `npm install` (or `npm i`)
Shell:
Shell:
- 在工作区根目录执行命令。
- 路径建议使用引号包裹。
- Run commands in repository root.
- Quote file paths when appropriate.
Web 搜索:
Web search:
- `WebSearch` 获取最新内容;不足时用 `mcp__SearXNG__search` 聚合搜索
- Use `WebSearch` for latest information; use `mcp__SearXNG__search` when needed.
文档/用法检索:
Documentation/usage lookup:
- `context7` 获取依赖的最新用法
- Use `context7` for latest dependency usage.
VSCode MCP (如可用):
VSCode MCP (if available):
- `mcp__vscode-mcp__get_references` 辅助重构范围判定
- `mcp__vscode-mcp__rename_symbol` 安全重命名
- `mcp__vscode-mcp__get_symbol_lsp_info` 获取类型/签名/定义等信息
- `mcp__vscode-mcp__get_references` for refactor impact analysis
- `mcp__vscode-mcp__rename_symbol` for safe renaming
- `mcp__vscode-mcp__get_symbol_lsp_info` for types/signatures/definitions
## 🚨 本地质量检查(可选流程)
## 🚨 Local Quality Checks (Optional Flow)
在完成一组修改后并行执行三类检查,而非直接跑全量 lint:
After a set of changes, run these three checks in parallel instead of full lint immediately:
```plaintext
Task(subagent_type: "quick-code-review", description: "Code review", prompt: "[change description]")
@@ -369,16 +381,16 @@ Task(subagent_type: "diagnostics", description: "Diagnostics", prompt: "[same as
Task(subagent_type: "run-related-tests", description: "Run tests", prompt: "[same as above]")
```
change description 示例:
`change description` example:
```plaintext
- Modified files: 相对路径列表
- Context: 需求/业务背景
- Modified files: list of relative paths
- Context: requirement/business background
```
流程:初检 → 修复关键问题 → 复检 → 迭代至关键问题清零。
Flow: initial check -> fix key issues -> re-check -> iterate until key issues are resolved.
注意:上述工具为只读分析,需自行修复;传入精确文件路径,避免用笼统目录。
Note: these tools are read-only analyzers; you still need to apply fixes manually. Pass precise file paths, not broad directories.
<skills_system priority="1">