Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (71 loc) · 5.14 KB

AGENTS.md

File metadata and controls

83 lines (71 loc) · 5.14 KB

AGENTS.md

项目定位

  • 本项目是 Tauri 2 + Vue 3 + TypeScript 桌面应用模板，前端负责 UI 与交互，Rust 负责系统能力与命令实现。
  • 后续功能（包括“桌面窗口置顶管理工具”）必须在现有模板架构内扩展，不得绕开分层。

技术栈与关键依赖

  • 前端：Vue 3、Vue Router 4、Pinia、PrimeVue、UnoCSS、TypeScript。
  • 桌面端：Tauri 2、Rust、@tauri-apps/api。
  • 状态持久化：pinia-plugin-persistedstate。

目录职责

  • src/main.ts：前端启动入口，挂载 router/pinia/PrimeVue 主题。
  • src/App.vue：应用壳，仅承载顶层 RouterView。
  • src/router/：路由定义与页面组织（当前采用 layout + children 路由）。
  • src/layouts/：页面骨架布局（如顶部栏、内容容器）。
  • src/pages/：页面级组件，一个文件对应一个路由页面。
  • src/common/components/：可复用业务/界面组件。
  • src/common/composables/：组合式逻辑（useXxx），封装可复用交互与状态衍生。
  • src/common/assets/：静态资源。
  • src/pinia/stores/：Pinia store 模块。
  • src/pinia/index.ts：Pinia 实例与插件注册、store 对外导出入口。
  • src-tauri/src/main.rs：Rust 可执行入口，仅调用 run()。
  • src-tauri/src/lib.rs：Tauri Builder、plugin 注册、invoke_handler 注册入口。
  • src-tauri/capabilities/：Tauri 能力权限声明。

前端 / Rust 分层边界

  • Vue 层只负责：页面展示、交互编排、状态管理。
  • Rust 层只负责：系统 API 调用、平台能力封装、命令实现。
  • 前端调用系统能力必须经由 Tauri command（invoke）或官方 API 封装，不允许把系统调用逻辑散落在页面组件中。
  • 所有跨层交互都要有清晰的数据结构（建议显式 TypeScript 类型 + Rust serde 序列化结构）。

命名规范

  • 通用规则：使用英文命名，避免拼音/中文缩写；名称表达业务语义。
  • Vue SFC 文件：
    • 页面文件放 src/pages/，可使用简洁页面名；新增页面建议采用语义化 PascalCase（如 WindowListPage.vue）。
    • 通用组件采用 PascalCase（如 TopNav.vue）。
  • composables：统一 useXxx.ts。
  • Pinia store：src/pinia/stores/<domain>.ts，导出 useXxxStore。
  • Rust command 函数：使用 snake_case；对外命令名与前端调用名保持一致。

页面、组件、store、composables 放置规则

  • 页面级逻辑优先放在 src/pages/*，不要把整页业务写进 layouts。
  • 布局只处理“结构壳子”，不承载具体页面业务。
  • 可复用 UI/业务片段抽到 src/common/components/。
  • 复用交互逻辑（滚动、主题切换等）抽到 src/common/composables/，页面中只做组装。
  • 跨页面共享状态进入 Pinia；仅页面私有的瞬时状态保留在组件内。
  • store 不直接依赖具体页面组件，保持可复用与可测试。

状态管理约定

  • 统一使用 Pinia 管理全局/跨页面状态。
  • 需要持久化的状态通过 pinia-plugin-persistedstate 在 store 内声明。
  • localStorage key 应稳定、可读、与 store 域一致（如当前 theme）。
  • 避免重复状态：同一事实来源只在一个 store 中维护。

Tauri command 组织规则

  • 当前项目以 src-tauri/src/lib.rs 作为 command 注册中心（invoke_handler）。
  • command 数量较少时可直接定义在 lib.rs；数量增长后按领域拆分为 src-tauri/src/commands/*.rs，并在 lib.rs 统一注册。
  • 每个 command 只做一件事：输入校验 + 调用底层能力 + 返回结构化结果。
  • command 返回值应稳定（成功/失败语义清晰），错误信息避免直接暴露底层实现细节。
  • 新增系统能力时，必须同步检查/更新 src-tauri/capabilities/*.json 权限。

路径与导入约定

  • 优先使用已配置别名：@、@pages、@layouts、@components、@composables、@assets、@pinia 等。
  • 保持导入路径风格一致，不在同一模块混用大量相对路径与别名路径。

禁止事项

  • 禁止在 Vue 页面/组件中直接实现系统级能力（窗口枚举、置顶控制、进程访问等）。
  • 禁止绕过 store 直接在多个页面重复维护同一份全局状态。
  • 禁止将一次性需求或临时调试代码固化到长期模块（提交前清理临时代码）。
  • 禁止进行与当前任务无关的大规模重构或目录迁移。

修改代码的最小改动原则

  • 只改与需求直接相关的文件，优先复用现有模块与模式。
  • 先遵循现有结构，再考虑抽象；避免“为未来”过度设计。
  • 新增文件时保持与现有目录职责一致，避免跨层放置。
  • 不在一次改动中同时引入架构调整、样式重写、业务重写等多类变化。
  • 修改 Tauri command 时，前后端调用链（类型、命名、权限）必须一次性对齐。

提交前自检

  • 前端构建与类型检查可通过：pnpm build。
  • Rust/Tauri 构建可通过：pnpm desktop:build（或开发态 pnpm desktop:dev）。
  • 新增路由、store、command 均有对应入口注册（router / pinia 导出 / invoke_handler）。