docs: translate repository documentation to English (#72)
This commit is contained in:
8 files changed
+456
-441
No files matched your search
@@ -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">
|
||||
|
||||
|
||||
Reference in new issue
Block a user