docs: 更新项目规则文档以反映从项目管理到 Markdown 助手的变更
更新项目概述、技术栈、项目结构、核心功能、开发规范及构建说明，以准确描述当前 Markdown uTools 插件的功能边界与技术实现。
This commit is contained in:
cfq
parent
308578feca
commit
6b26049909
|
|
@ -1,104 +1,76 @@
|
|||
# 项目管理插件项目规则
|
||||
# Markdown uTools 插件项目规则
|
||||
|
||||
## 项目概述
|
||||
这是一个基于 uTools 的项目管理插件，使用 Vue 3 + Ant Design Vue 开发，提供本地项目管理和运行功能。
|
||||
这是一个基于 uTools 的 Markdown 插件，用于在 uTools 中直接打开/编辑/预览本地 Markdown 文件，并提供目录树、搜索、图片粘贴保存、导出等能力。
|
||||
|
||||
## 技术栈
|
||||
- **前端框架**: Vue 3.5.13
|
||||
- **UI 组件库**: Ant Design Vue 4.2.6
|
||||
- **构建工具**: Vite 6.0.11
|
||||
- **插件平台**: uTools
|
||||
- **Node.js集成**: 支持 Node 版本管理和项目运行
|
||||
- **图标库**: @ant-design/icons-vue 7.0.1
|
||||
- **JSON编辑器**: jsoneditor 10.4.2
|
||||
- **编辑器能力**: CodeMirror 6
|
||||
- **Markdown 渲染**: markdown-it 14.1.0
|
||||
- **进程管理**: tree-kill 1.2.2
|
||||
- **其他**: jsoneditor 10.4.2、tree-kill 1.2.2、uuid 13.x
|
||||
|
||||
## 项目结构
|
||||
```
|
||||
projectManagement/
|
||||
├── .gitignore # Git 忽略文件
|
||||
markdown/
|
||||
├── .trae/
|
||||
│ └── rules/
|
||||
│ └── project_rules.md # 项目规则文件
|
||||
├── README.md # 项目说明文档
|
||||
├── index.html # HTML 入口文件
|
||||
├── jsconfig.json # JavaScript 配置
|
||||
├── package.json # 项目依赖配置
|
||||
├── package-lock.json # 依赖锁定文件
|
||||
├── public/
|
||||
│ ├── plugin.json # uTools 插件配置
|
||||
│ ├── logo.png # 插件图标
|
||||
│ └── preload/
|
||||
│ ├── services.js # Node.js 预加载脚本
|
||||
│ └── package.json
|
||||
│ └── services.js # 预加载脚本：文件系统/Git/搜索/配置等能力
|
||||
├── scripts/
|
||||
│ └── copy-deps.js # 依赖拷贝脚本
|
||||
│ └── copy-deps.js # 构建后依赖拷贝脚本
|
||||
├── src/
|
||||
│ ├── components/ # 业务组件（目录树/编辑器/预览/搜索/Git 等）
|
||||
│ ├── composables/ # 组合式能力（配置/文件树/搜索/主题等）
|
||||
│ ├── App.vue # 主应用组件
|
||||
│ ├── ProjectManager/
|
||||
│ │ ├── index.vue # 项目管理主界面
|
||||
│ │ └── components/ # 子组件目录
|
||||
│ ├── composables/
|
||||
│ │ └── useTheme.js # 主题管理
|
||||
│ ├── main.css # 全局样式
|
||||
│ └── main.js # 应用入口
|
||||
├── tsconfig.json # TypeScript 配置
|
||||
├── vite.config.js # Vite 配置
|
||||
└── 插件安装包/
|
||||
├── 项目管理-1.0.0.upxs # 插件安装包 v1.0.0
|
||||
└── 项目管理-2.1.0.upxs # 插件安装包 v2.1.0
|
||||
├── index.html
|
||||
├── package.json
|
||||
└── vite.config.js
|
||||
```
|
||||
|
||||
## 核心功能
|
||||
## 核心能力边界
|
||||
- **UI（src）**：只做交互、状态与渲染，不直接触达 Node API；通过 `window.services` 调用预加载能力。
|
||||
- **预加载（public/preload/services.js）**：集中提供文件系统、Git、搜索、配置读写等能力；注意所有路径都必须来源于用户选择的根目录或当前打开的文件路径。
|
||||
- **构建产物（dist）**：用于 uTools 插件发布；`npm run build` 需要同时完成构建与依赖拷贝。
|
||||
|
||||
### 1. 项目管理
|
||||
- **目录管理**: 添加、编辑、删除项目目录
|
||||
- **项目列表**: 显示目录下的所有项目
|
||||
- **搜索功能**: 按项目名或目录名搜索
|
||||
- **隐藏管理**: 支持隐藏目录和项目
|
||||
## 功能约束（必须保持一致）
|
||||
- **目录树**：支持递归浏览与懒加载；刷新目录树；右键新建/删除/重命名/复制路径/打开所在位置/克隆副本。
|
||||
- **编辑与预览**：Markdown 编辑实时预览；支持源码模式切换；支持粘贴图片并写入与当前 md 同名的资源目录。
|
||||
- **搜索**：支持文件名搜索与内容搜索（支持正则）；搜索结果可定位并打开对应文件。
|
||||
- **Git**：当根目录存在 `.git` 时，展示基础 Git 操作入口（状态/提交/推送/拉取）。
|
||||
|
||||
### 2. 项目操作
|
||||
- **打开文件夹**: 在文件管理器中打开项目目录
|
||||
- **编辑器集成**: 支持 VSCode、Cursor 等编辑器
|
||||
- **自定义编辑器**: 可配置其他编辑器
|
||||
## 配置与数据落盘
|
||||
- **配置文件位置**：在用户选择的根目录下创建/读取 `.md-helper.json`。
|
||||
- **配置内容**：用于记录 pinnedFiles、recentFiles 等 UI 状态与使用习惯数据。
|
||||
- **写入原则**：只写入用户已选择的根目录及其子路径；禁止写入未知位置；所有写入失败必须返回可感知的错误信息（弹窗/提示或明确的返回值）。
|
||||
|
||||
### 3. 项目运行
|
||||
- **脚本执行**: 自动读取 package.json 中的 scripts
|
||||
- **进程管理**: 启动、停止、监控项目进程
|
||||
- **日志查看**: 实时查看项目运行日志
|
||||
## 开发规范
|
||||
### 代码组织
|
||||
- 业务逻辑优先收敛到 `src/composables/`，组件内只保留与 UI 强相关的 glue code。
|
||||
- 任何跨组件共享状态，优先通过 composable 管理，避免组件之间隐式耦合。
|
||||
- 尽量避免不必要的对象复制；能提前返回就不要多层嵌套；异步任务需要有并发与中断意识（例如搜索/读目录）。
|
||||
|
||||
### 4. Node.js 版本管理
|
||||
- **版本切换**: 支持使用 NVM 切换 Node 版本
|
||||
- **版本安装**: 在线安装新的 Node 版本
|
||||
- **版本列表**: 显示已安装和可安装的版本
|
||||
### 命名与文件
|
||||
- Vue 组件使用 PascalCase 命名（例如 `FileTree.vue`）。
|
||||
- composable 使用 `useXxx.js` 命名（例如 `useFileTree.js`）。
|
||||
|
||||
## 开发规则
|
||||
### 样式
|
||||
- 使用 CSS 变量表达主题色/背景/文字等基础 token，统一由主题能力控制。
|
||||
- 组件样式优先使用 scoped，通用样式放在 `src/main.css`。
|
||||
|
||||
### 代码规范
|
||||
- 使用 Vue 3 Composition API
|
||||
- 遵循 Ant Design Vue 组件使用规范
|
||||
- 使用 TypeScript 风格的类型注解
|
||||
- 组件和函数需要添加中文注释
|
||||
## 代码校验（必做）
|
||||
- **合入前校验**：必须在本地执行并通过 `npm run build`。
|
||||
- **发布前校验**：必须执行 `npm run build`，确认 `dist` 产物可用于 uTools 开发者工具加载。
|
||||
|
||||
### 文件命名
|
||||
- Vue 组件使用 PascalCase
|
||||
- JavaScript 文件使用 camelCase
|
||||
- 目录使用 PascalCase
|
||||
|
||||
### 样式规范
|
||||
- 使用 CSS 变量管理主题色
|
||||
- 组件样式使用 scoped CSS
|
||||
- 全局样式定义在 main.css
|
||||
|
||||
### 数据存储
|
||||
- 使用 uTools 提供的用户数据存储
|
||||
- 数据格式为 JSON
|
||||
- 存储路径: `userData/projectManager.json`
|
||||
|
||||
## 构建和部署
|
||||
|
||||
### 开发环境
|
||||
## 构建与发布
|
||||
### 本地开发
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
|
@ -108,79 +80,6 @@ npm run dev
|
|||
npm run build
|
||||
```
|
||||
|
||||
### 依赖拷贝
|
||||
```bash
|
||||
npm run copy-deps
|
||||
```
|
||||
|
||||
### uTools 插件发布
|
||||
- 构建后生成 dist 目录
|
||||
- 通过 uTools 开发者工具上传插件
|
||||
- 配置插件信息在 public/plugin.json
|
||||
|
||||
## 功能模块说明
|
||||
|
||||
### services.js (预加载脚本)
|
||||
提供 Node.js 能力，包括：
|
||||
- 文件系统操作
|
||||
- 进程管理
|
||||
- 编辑器集成
|
||||
- Node 版本管理
|
||||
- 数据持久化
|
||||
|
||||
### ProjectManager/index.vue
|
||||
主界面组件，包含：
|
||||
- 目录列表展示
|
||||
- 项目操作界面
|
||||
- 模态框管理
|
||||
- 状态管理
|
||||
|
||||
### 数据模型
|
||||
```javascript
|
||||
{
|
||||
directories: [
|
||||
{
|
||||
id: string,
|
||||
name: string,
|
||||
path: string,
|
||||
remark: string,
|
||||
hidden: boolean,
|
||||
expanded: boolean,
|
||||
projects: [
|
||||
{
|
||||
id: string,
|
||||
name: string,
|
||||
path: string,
|
||||
remark: string,
|
||||
hidden: boolean,
|
||||
runConfig: {
|
||||
command: string,
|
||||
nodeVersion: string
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
settings: {
|
||||
defaultEditor: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **跨平台兼容**: 支持 Windows、macOS、Linux
|
||||
2. **安全考虑**: 所有文件操作都在用户授权下进行
|
||||
3. **性能优化**: 大文件操作使用异步处理
|
||||
4. **错误处理**: 完善的错误捕获和用户提示
|
||||
|
||||
## 扩展建议
|
||||
|
||||
- 支持更多编辑器类型
|
||||
- 添加项目模板功能
|
||||
- 集成 Git 操作
|
||||
- 添加项目统计功能
|
||||
- 支持插件主题切换
|
||||
- 增强 Markdown 文档支持
|
||||
- 添加项目依赖分析功能
|
||||
- 支持自定义脚本模板
|
||||
### uTools 配置
|
||||
- 插件入口与开发联调地址配置在 `public/plugin.json`。
|
||||
- 预加载脚本入口配置在 `public/preload/services.js`。
|
||||
|
|
|
|||
Loading…
Reference in New Issue