markdown/.trae/rules/project_rules.md

Markdown uTools 插件项目规则

项目概述

这是一个基于 uTools 的 Markdown 插件，用于在 uTools 中直接打开/编辑/预览本地 Markdown 文件，并提供目录树、搜索、图片粘贴保存、导出等能力。

技术栈

• 前端框架: Vue 3.5.13
• UI 组件库: Ant Design Vue 4.2.6
• 构建工具: Vite 6.0.11
• 插件平台: uTools
• 编辑器能力: CodeMirror 6
• Markdown 渲染: markdown-it 14.1.0
• 其他: jsoneditor 10.4.2、tree-kill 1.2.2、uuid 13.x

项目结构

markdown/
├── .trae/
│   └── rules/
│       └── project_rules.md          # 项目规则文件
├── public/
│   ├── plugin.json                   # uTools 插件配置
│   └── preload/
│       └── services.js               # 预加载脚本：文件系统/Git/搜索/配置等能力
├── scripts/
│   └── copy-deps.js                  # 构建后依赖拷贝脚本
├── src/
│   ├── components/                   # 业务组件（目录树/编辑器/预览/搜索/Git 等）
│   ├── composables/                  # 组合式能力（配置/文件树/搜索/主题等）
│   ├── App.vue                       # 主应用组件
│   ├── main.css                      # 全局样式
│   └── main.js                       # 应用入口
├── index.html
├── package.json
└── vite.config.js

核心能力边界

• UI（src）：只做交互、状态与渲染，不直接触达 Node API；通过 window.services 调用预加载能力。
• 预加载（public/preload/services.js）：集中提供文件系统、Git、搜索、配置读写等能力；注意所有路径都必须来源于用户选择的根目录或当前打开的文件路径。
• 构建产物（dist）：用于 uTools 插件发布；npm run build 需要同时完成构建与依赖拷贝。

功能约束（必须保持一致）

• 目录树：支持递归浏览与懒加载；刷新目录树；右键新建/删除/重命名/复制路径/打开所在位置/克隆副本。
• 编辑与预览：Markdown 编辑实时预览；支持源码模式切换；支持粘贴图片并写入与当前 md 同名的资源目录。
• 搜索：支持文件名搜索与内容搜索（支持正则）；搜索结果可定位并打开对应文件。
• Git：当根目录存在 .git 时，展示基础 Git 操作入口（状态/提交/推送/拉取）。

配置与数据落盘

• 配置文件位置：在用户选择的根目录下创建/读取 .md-helper.json。
• 配置内容：用于记录 pinnedFiles、recentFiles 等 UI 状态与使用习惯数据。
• 写入原则：只写入用户已选择的根目录及其子路径；禁止写入未知位置；所有写入失败必须返回可感知的错误信息（弹窗/提示或明确的返回值）。

开发规范

代码组织

• 业务逻辑优先收敛到 src/composables/，组件内只保留与 UI 强相关的 glue code。
• 任何跨组件共享状态，优先通过 composable 管理，避免组件之间隐式耦合。
• 尽量避免不必要的对象复制；能提前返回就不要多层嵌套；异步任务需要有并发与中断意识（例如搜索/读目录）。

命名与文件

• Vue 组件使用 PascalCase 命名（例如 FileTree.vue）。
• composable 使用 useXxx.js 命名（例如 useFileTree.js）。

样式

• 使用 CSS 变量表达主题色/背景/文字等基础 token，统一由主题能力控制。
• 组件样式优先使用 scoped，通用样式放在 src/main.css。

代码校验（必做）

• 合入前校验：必须在本地执行并通过 npm run build。
• 发布前校验：必须执行 npm run build，确认 dist 产物可用于 uTools 开发者工具加载。

构建与发布

本地开发

npm run dev

生产构建

npm run build

uTools 配置

• 插件入口与开发联调地址配置在 public/plugin.json。
• 预加载脚本入口配置在 public/preload/services.js。