Skip to content

AGENTS.md

Latest commit

 

History

History
118 lines (87 loc) · 6.46 KB

AGENTS.md

File metadata and controls

118 lines (87 loc) · 6.46 KB
Raw

Project Background

Github Repository: graphif/project-graph

Project Graph 是一款桌面级节点图绘制工具，用于头脑风暴、知识图谱、项目规划等场景的可视化思考。

Tech-stack

  • React (TypeScript) + Tauri (Rust)
  • Vite + pnpm (monorepo) + Nx
  • Canvas 2D
  • shadcn/ui + Tailwind CSS + 自研子窗口系统
  • Jotai

Rust 主要负责本地文件等系统能力；绝大部分业务逻辑在前端。

Structure

Application

  • Frontend Vite project: /app
  • Rust / Tauri: /app/src-tauri
  • UI components: /app/src/components
  • i18n locales: /app/src/locales
  • React state (Jotai 等): /app/src/state.tsx 及附近

app/src/core（核心业务）

路径 职责
Project.tsx 单个工程/项目实例的入口与生命周期
Tab*.ts(x) / TabWorkspace.tsx 标签页与工作区
loadAllServices.tsx 注册/加载全部服务
algorithm/ 通用算法与几何工具
stage/ 舞台：Camera、Canvas、舞台对象（stageObject）、舞台管理（stageManager）
render/ 渲染：canvas2d、svg、3d、domElement
service/ 业务服务（见下）
extension/ 扩展系统运行时与 API
fileSystemProvider/ 文件系统抽象（草稿/本地文件等）
interfaces/ 核心接口（如 Service）
subWindowOpen*.ts 子窗口打开方式

service/ 主要子目录：

  • controlService/ — 输入控制、快捷键、框选、自动布局等
  • dataFileService/ — 工程文件读写
  • dataGenerateService/ — 数据生成
  • dataManageService/ — 内容搜索、复制、AI、节点工具等
  • feedbackService/ — 特效、音效、舞台样式、颜色
  • Settings.tsx 等 — 设置、主题、菜单、教程等全局服务

Packages（/packages）

前端复用的开源/内部库，例如：

  • @graphif/serializer — 实例序列化
  • @graphif/shapes — 可序列化图形
  • @graphif/data-structures — 可序列化数据结构
  • extprg / extprg-types / create-extprg — 扩展工具链与类型

Agent skills

具体工作流见 .agents/skills/：

  • type-check — TypeScript 类型检查（改代码后用这个，不要 build）
  • create-keybind — 新增/修改快捷键
  • create-setting-item — 新增/修改设置项
  • shadcn / ui — UI 组件
  • suggest-lucide-icons — 图标建议

Locales (app/src/locales)

文件 说明
en.yml 英文（手写维护）
zh_CN.yml 简体中文（手写维护）
zh_TW.yml 普通繁体中文 — 由 zh_CN.yml 自动生成（OpenCC），不要手改
zh_TWC.yml 接地气繁体中文 — 手写维护，不是自动生成
id.yml 印尼语（手写维护）

新增文案时：改 en.yml / zh_CN.yml（及需要时的 zh_TWC.yml、id.yml），不要编辑 zh_TW.yml。

Coding guidelines

  • 正确性与清晰度优先；性能除非明确要求，否则次之。
  • 不要写组织性/总结性注释；仅在「为什么这样写」不直观时解释 why。
  • 优先在已有文件中实现功能；仅在新的逻辑组件时新建文件，避免拆成大量小文件。
  • 目录内使用 something.tsx，不要用单独的 index.tsx。
  • 错误处理（前端）：
    • 不要静默吞掉错误：禁止 catch {} 或仅 console.error 后忽略
    • 能不 catch 就不 catch，让调用方处理
    • 需要忽略时用对话框提示用户（用户看不到控制台）
    • 错误应向上传到 DOM（如 window），由 ErrorHandler 展示友好对话框
    • 反例：try { something() } catch (e) { console.error(e) } → 直接 something()
  • 错误处理（Rust / Tauri 命令）：命令在运行中不能让进程因未捕获错误闪退，须在函数内妥善处理错误并返回给前端。
  • UI：优先复用 shadcn 与 .agents/skills/ui 中的约定（Dialog、toast 等）。
  • 快捷键 / 设置：分别遵循 create-keybind、create-setting-item skill。

Commands

包管理：pnpm。常用：

  • 开发：pnpm dev
  • Lint：pnpm lint / pnpm lint:fix
  • 测试：pnpm test（vitest）
  • 类型检查：使用 type-check skill（pnpm --filter @graphif/project-graph type-check）

禁止 Agent 运行 build / build:ci / build:no-tauri / tauri build 等构建命令。验证改动用 type-check（及必要的 lint/test），不要 build。

Agent constraints

  • 依赖 API / 用法：禁止用 shell 在 node_modules 里搜索、翻源码或类型定义。需要了解第三方库时，读取该项目的官方文档（优先 llms.txt，例如 https://<pkg-docs>/llms.txt），或使用已有 skill；不要 grep / find / cat node_modules/**。
  • 实现方式：禁止用 python、python3、node -e、node --eval、内联 shell 脚本等做文本处理或批量改文件。应直接用读/写/编辑文件的工具（Read / Write / Edit 等）完成；需要多文件改动时逐个编辑，不要写临时脚本。
  • 构建：禁止 build（见上）；验证用 type-check skill。

Commit Message

使用 Conventional Commits，例如：feat: ...、fix: ...、refactor: ...。