Skip to content

Commit f81b4b1

Browse files
zty012zty012
committed
docs: rewrite AGENTS.md for agents and drop README_FOR_AI
Expand project structure, locales, commands, and agent constraints; remove outdated RFC/turborepo notes and the redundant AI readme.
1 parent bce0bdb commit f81b4b1

2 files changed

Lines changed: 92 additions & 47 deletions

File tree

‎AGENTS.md‎

Lines changed: 92 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -2,55 +2,117 @@
22

33
Github Repository: `graphif/project-graph`
44

5-
Project Graph is a desktop application designed to visualize and manage complex project structures. It allows users to create, edit, and visualize project graphs, making it easier to understand relationships and dependencies within projects.
6-
7-
## Coding guidelines
8-
9-
- Prioritize code correctness and clarity. Speed and efficiency are secondary priorities unless otherwise specified.
10-
- Do not write organizational or comments that summarize the code. Comments should only be written in order to explain "why" the code is written in some way in the case there is a reason that is tricky / non-obvious.
11-
- Prefer implementing functionality in existing files unless it is a new logical component. Avoid creating many small files.
12-
- Never silently discard errors with `catch {}` or `catch (e) { console.error(e) }` on fallible operations. Always handle errors appropriately:
13-
- Don't catch errors, let the calling function to handle them
14-
- If the error should be ignored, show a dialog instead of logging to console. User cannot see logs in the console.
15-
- Ensure errors propagate to the top of DOM (eg. `window`), so `ErrorHandler` component can catch it and show an user-friendly dialog
16-
- Example: avoid `try { something() } catch (e) { console.error(e) }` - use `something()` instead
17-
- Always use `something.tsx` instead of a single `index.tsx` in a directory.
5+
Project Graph 是一款桌面级节点图绘制工具，用于头脑风暴、知识图谱、项目规划等场景的可视化思考。
186

197
## Tech-stack
208

219
- React (TypeScript) + Tauri (Rust)
22-
- Vite + pnpm (monorepo) + turborepo
10+
- Vite + pnpm (monorepo) + Nx
2311
- Canvas 2D
24-
- shadcn/ui + Tailwind CSS + self-developed sub-window system
12+
- shadcn/ui + Tailwind CSS + 自研子窗口系统
2513
- Jotai
2614

15+
Rust 主要负责本地文件等系统能力；绝大部分业务逻辑在前端。
16+
2717
## Structure
2818

29-
### Tauri Application, and Frontend
19+
### Application
3020

3121
- Frontend Vite project: `/app`
32-
- Rust Project: `/app/src-tauri`
33-
34-
### Open-source Libraries
22+
- Rust / Tauri: `/app/src-tauri`
23+
- UI components: `/app/src/components`
24+
- i18n locales: `/app/src/locales`
25+
- React state (Jotai 等): `/app/src/state.tsx` 及附近
26+
27+
### `app/src/core`（核心业务）
28+
29+
| 路径 | 职责 |
30+
| --------------------------------- | ------------------------------------------------------------------------------- |
31+
| `Project.tsx` | 单个工程/项目实例的入口与生命周期 |
32+
| `Tab*.ts(x)` / `TabWorkspace.tsx` | 标签页与工作区 |
33+
| `loadAllServices.tsx` | 注册/加载全部服务 |
34+
| `algorithm/` | 通用算法与几何工具 |
35+
| `stage/` | 舞台：`Camera`、`Canvas`、舞台对象（`stageObject`）、舞台管理（`stageManager`） |
36+
| `render/` | 渲染：`canvas2d`、`svg`、`3d`、`domElement` |
37+
| `service/` | 业务服务（见下） |
38+
| `extension/` | 扩展系统运行时与 API |
39+
| `fileSystemProvider/` | 文件系统抽象（草稿/本地文件等） |
40+
| `interfaces/` | 核心接口（如 `Service`） |
41+
| `subWindowOpen*.ts` | 子窗口打开方式 |
42+
43+
`service/` 主要子目录：
44+
45+
- `controlService/` — 输入控制、快捷键、框选、自动布局等
46+
- `dataFileService/` — 工程文件读写
47+
- `dataGenerateService/` — 数据生成
48+
- `dataManageService/` — 内容搜索、复制、AI、节点工具等
49+
- `feedbackService/` — 特效、音效、舞台样式、颜色
50+
- `Settings.tsx` 等 — 设置、主题、菜单、教程等全局服务
51+
52+
### Packages（`/packages`）
53+
54+
前端复用的开源/内部库，例如：
55+
56+
- `@graphif/serializer` — 实例序列化
57+
- `@graphif/shapes` — 可序列化图形
58+
- `@graphif/data-structures` — 可序列化数据结构
59+
- `extprg` / `extprg-types` / `create-extprg` — 扩展工具链与类型
60+
61+
### Agent skills
62+
63+
具体工作流见 `.agents/skills/`：
64+
65+
- `type-check` — TypeScript 类型检查（**改代码后用这个，不要 build**）
66+
- `create-keybind` — 新增/修改快捷键
67+
- `create-setting-item` — 新增/修改设置项
68+
- `shadcn` / `ui` — UI 组件
69+
- `suggest-lucide-icons` — 图标建议
70+
71+
## Locales (`app/src/locales`)
72+
73+
| 文件 | 说明 |
74+
| ------------ | ------------------------------------------------------------------ |
75+
| `en.yml` | 英文（手写维护） |
76+
| `zh_CN.yml` | 简体中文（手写维护） |
77+
| `zh_TW.yml` | 普通繁体中文 — **由 `zh_CN.yml` 自动生成（OpenCC）**，**不要手改** |
78+
| `zh_TWC.yml` | 接地气繁体中文 — **手写维护，不是自动生成** |
79+
| `id.yml` | 印尼语（手写维护） |
80+
81+
新增文案时：改 `en.yml` / `zh_CN.yml`（及需要时的 `zh_TWC.yml`、`id.yml`），**不要编辑 `zh_TW.yml`**。
3582

36-
They are all in `/packages` directory, and are used in the frontend.
83+
## Coding guidelines
3784

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

40-
Trade time for space, meaning that you should use more **storage** (not memory!) to reduce computation time
99+
## Commands
41100

42-
## RFCs
101+
包管理：`pnpm`。常用：
43102

44-
The `tasks` the user refers to are **RFCs**. These RFCs are usually tracked in the repository’s Issues and their titles begin with `RFC:`.
103+
- 开发：`pnpm dev`
104+
- Lint：`pnpm lint` / `pnpm lint:fix`
105+
- 测试：`pnpm test`（vitest）
106+
- 类型检查：**使用 `type-check` skill**（`pnpm --filter @graphif/project-graph type-check`）
45107

46-
A user **cannot** take on tasks that are irrelevant to their own system. For example, a Linux user **cannot** complete a task that exists only on macOS.
108+
**禁止** Agent 运行 `build` / `build:ci` / `build:no-tauri` / `tauri build` 等构建命令。验证改动用 type-check（及必要的 lint/test），不要 build。
47109

48-
When the user asks which tasks remain unfinished, you must
110+
## Agent constraints
49111

50-
- assign **a unique number** to every task
51-
- sort the list by a combined score of **importance × implementation difficulty**,
52-
so the user can easily tell you to tick the finished items in the corresponding RFCs.
112+
- **依赖 API / 用法**：禁止用 shell 在 `node_modules` 里搜索、翻源码或类型定义。需要了解第三方库时，读取该项目的官方文档（优先 `llms.txt`，例如 `https://<pkg-docs>/llms.txt`），或使用已有 skill；不要 `grep` / `find` / `cat` `node_modules/**`。
113+
- **实现方式**：禁止用 `python`、`python3`、`node -e`、`node --eval`、内联 shell 脚本等做文本处理或批量改文件。应直接用读/写/编辑文件的工具（Read / Write / Edit 等）完成；需要多文件改动时逐个编辑，不要写临时脚本。
114+
- **构建**：禁止 build（见上）；验证用 type-check skill。
53115

54116
## Commit Message
55117

56-
Use conventional commits
118+
使用 [Conventional Commits](https://www.conventionalcommits.org/)，例如：`feat: ...`、`fix: ...`、`refactor: ...`。

‎docs-pg/README_FOR_AI.md‎

Lines changed: 0 additions & 17 deletions
This file was deleted.

0 commit comments

Comments
 (0)