69 lines
5.2 KiB
Markdown
69 lines
5.2 KiB
Markdown
|
# Repository Guidelines
|
|||
|
|
|
|||
|
|
## Agent 工作方式
|
|||
|
|
进入本仓库后，先阅读本文件，再开始分析、修改或输出结论。不要跳过现有文档直接下判断，至少先结合根目录现有说明、`doc/`、`package.json`、目标模块代码和相关配置确认上下文；如果存在 `README.md`，也应一并阅读。
|
|||
|
|
|
|||
|
|
日常交互遵循以下习惯：
|
|||
|
|
|
|||
|
|
- 先整理执行方案，说明目标、涉及模块、预计修改点和验证方式，待用户评审确认后再执行。
|
|||
|
|
- 不要想当然；如果需求存在歧义、前提不清或有多种实现路径，先说清假设与取舍，再继续。
|
|||
|
|
- 默认先确认任务是否位于 `frontend/src/`，再按 `views/`、`components/`、`api/`、`stores/`、`routers/`、`hooks/` 的调用关系向下分析；只有涉及桌面壳层或启动问题时，再继续查看 `electron/`、`scripts/`、`build/`、`public/`。
|
|||
|
|
- 涉及 preload 桥接、主进程配置、自动更新、窗口生命周期、端口检测或打包启动链路时，先核对已有实现和 `doc/` 中的说明，避免只看局部代码就下结论。
|
|||
|
|
- 回复风格保持简洁、直接，优先给出可执行结果；如果存在限制、风险或未验证部分，需要明确说明。
|
|||
|
|
|
|||
|
|
## 执行与修改原则
|
|||
|
|
- 简单优先：只做当前需求所需的最小改动，不额外引入新功能、抽象层、配置项或“顺手优化”。
|
|||
|
|
- 外科手术式修改：只改与任务直接相关的文件和代码行，不重构无关模块，不调整无关格式或注释。
|
|||
|
|
- 保持现有风格：遵循仓库已有包结构、分层方式、命名和写法，不按个人偏好重写。
|
|||
|
|
- 只清理自己造成的问题：可以删除因本次修改而产生的未使用 `import`、变量或方法；不要删除仓库中原本就存在的死代码，除非用户明确要求。
|
|||
|
|
- 先定义验证方式：执行方案里要写清楚“改哪里、怎么判断改对了”；默认通过代码路径、配置一致性、界面影响范围和启动链路检查进行验证。
|
|||
|
|
- 除非用户明确要求，否则不执行 `npm run build`、`npm run build-w`、`electron-builder`、加密打包或其他重型构建命令；通常只做静态检查、必要的代码阅读和轻量验证。
|
|||
|
|
|
|||
|
|
## 项目结构与模块组织
|
|||
|
|
本仓库以前端界面开发为主，使用 Vue 3 构建页面，并通过 Electron 提供桌面壳层与本地运行能力。
|
|||
|
|
|
|||
|
|
- `electron/`：主进程入口、preload 桥接层、运行时配置。
|
|||
|
|
- `frontend/src/`：前端源码，按 `api/`、`components/`、`hooks/`、`layouts/`、`routers/`、`stores/`、`styles/`、`utils/`、`views/` 分层组织。
|
|||
|
|
- `scripts/`：桌面启动、端口检测、日志窗口和运行时辅助脚本。
|
|||
|
|
- `public/`：静态 HTML 与应用图片资源。
|
|||
|
|
- `build/`、`cmd/`、`data/`：打包资源、构建配置、运行时附带数据。
|
|||
|
|
- `doc/`：维护说明与打包文档。
|
|||
|
|
|
|||
|
|
不要直接修改生成内容，如 `frontend/dist/`、`out/`、`logs/`、`public/electron/`。
|
|||
|
|
|
|||
|
|
## 构建、测试与开发命令
|
|||
|
|
- `npm run dev`：启动 Electron 与前端联调环境。
|
|||
|
|
- `npm run dev-frontend`：仅启动前端开发流程。
|
|||
|
|
- `npm run dev-electron`：仅启动 Electron 侧开发流程。
|
|||
|
|
- `npm run build`：构建前端与 Electron，并执行 `ee-bin encrypt`。
|
|||
|
|
- `npm run build-w`：生成 Windows 包，并将 `out/win-unpacked` 重命名为 `out/CN_Tool`。
|
|||
|
|
- `cd frontend; npm run lint`：运行 ESLint 并自动修复 `.vue`、TypeScript 等文件。
|
|||
|
|
- `cd frontend; npm run type-check`：运行 `vue-tsc` 进行类型检查。
|
|||
|
|
|
|||
|
|
## 代码风格与命名规范
|
|||
|
|
前端格式化规则定义在 `frontend/.prettierrc`：4 空格缩进、单引号、不写分号、单行 120 字符、LF 换行。Lint 规则基于 Vue 3 与 TypeScript。
|
|||
|
|
|
|||
|
|
请遵循现有命名方式：
|
|||
|
|
- 页面或路由目录通常使用 `index.vue`，例如 `views/home/`
|
|||
|
|
- 通用组件使用 PascalCase，例如 `HomeToolCard.vue`
|
|||
|
|
- 组合式函数使用 `useX.ts`，例如 `useTheme.ts`
|
|||
|
|
- 状态模块放在 `frontend/src/stores/modules/`
|
|||
|
|
|
|||
|
|
## 执行原则
|
|||
|
|
涉及页面主流程、状态切换、接口适配、preload 通信、启动链路等关键业务节点时，必须补充简洁、准确的中文注释，并统一使用 UTF-8 编码。注释应说明业务目的、关键条件或异常处理原因，避免空泛描述。
|
|||
|
|
|
|||
|
|
## 测试指南
|
|||
|
|
仓库根目录当前未配置自动化测试，也不存在 `*.spec.*` 或 `*.test.*` 文件。提交 PR 前至少执行 `cd frontend; npm run lint`、`cd frontend; npm run type-check`，并手动验证启动、登录和受影响页面。
|
|||
|
|
|
|||
|
|
## 提交与 Pull Request 规范
|
|||
|
|
当前 `main` 分支还没有可用提交历史，建议使用清晰的祈使句提交信息，优先采用 Conventional Commits，例如 `feat: 增加启动端口重试`、`fix: 处理 mysql 路径缺失`。
|
|||
|
|
|
|||
|
|
PR 应包含：
|
|||
|
|
- 问题与方案的简要说明
|
|||
|
|
- 对应的任务单或 issue 链接（如有）
|
|||
|
|
- UI 变更截图
|
|||
|
|
- 打包、启动或 preload 变更的人工验证步骤
|
|||
|
|
|
|||
|
|
## 安全与配置提示
|
|||
|
|
`public/ssl/`、`build/extraResources/` 与 `electron/config/` 包含敏感运行资源。不要硬编码新的密钥或口令；凡是影响打包或启动的本地 `.env`、端口或运行配置调整，都应同步记录到 `doc/`。
|