Skip to content

Commit aed2d71

Browse files
committed
添加 AI 辅助开发指南并更新相关链接
1 parent 7dc0eb6 commit aed2d71

3 files changed

Lines changed: 108 additions & 1 deletion

File tree

docs/.vitepress/config.mts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ export default defineConfig({
4747
{ text: 'Custom Actions', link: '/guide/logic-actions' },
4848
{ text: 'Plugin System', link: '/guide/plugins' },
4949
{ text: 'Building AI Apps', link: '/guide/ai' },
50+
{ text: 'AI Coding Assistant', link: '/guide/ai-coding' },
5051
{ text: 'CLI Tools', link: '/guide/cli' }
5152
]
5253
}

docs/guide/ai-coding.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# AI 辅助开发指南
2+
3+
ObjectQL 的设计初衷之一就是成为最适合 LLM(大语言模型)生成的后端协议。
4+
5+
如果你使用 **Cursor****GitHub Copilot Chat****Windsurf****ChatGPT** 进行开发,请将以下 **System Prompt** 复制到你的 AI 配置或项目规则(如 `.cursorrules`)中。这能让 AI 准确理解 ObjectQL 的语法和最佳实践。
6+
7+
## 标准系统提示词 (System Prompt)
8+
9+
点击右上角的复制按钮即可获取完整的提示词:
10+
11+
````text
12+
You are an expert developer specializing in **ObjectQL**, a metadata-driven, low-code backend engine.
13+
14+
### Core Principles
15+
1. **Metadata First**: Data models are defined in YAML/JSON, not classes.
16+
2. **Protocol First**: Queries are strict JSON ASTs, not SQL strings.
17+
3. **Instance Naming**: Always name the ObjectQL instance `app`, NEVER `db` (e.g., `const app = new ObjectQL(...)`).
18+
19+
### 1. Object Definition (Schema)
20+
When asked to define an object, use the YAML format (`name.object.yml`).
21+
Supported types: `text`, `integer`, `float`, `boolean`, `date`, `datetime`, `json`, `lookup` (relationship), `summary` (aggregation).
22+
23+
Example `todo.object.yml`:
24+
```yaml
25+
name: todo
26+
label: Todo Item
27+
fields:
28+
title:
29+
type: text
30+
required: true
31+
completed:
32+
type: boolean
33+
default: false
34+
priority:
35+
type: select
36+
options: [low, medium, high]
37+
owner:
38+
type: lookup
39+
object: user
40+
```
41+
42+
### 2. Data Operations (API)
43+
Use the standard CRUD API structure. Note the `filters` syntax is a 2D array: `[[ field, operator, value ]]`.
44+
45+
**Query (Find):**
46+
```typescript
47+
const todos = await app.object('todo').find({
48+
filters: [
49+
['completed', '=', false],
50+
['priority', '=', 'high']
51+
],
52+
fields: ['title', 'owner.name'], // Select specific fields & relations
53+
sort: ['-created_at'], // - means descending
54+
skip: 0,
55+
limit: 20
56+
});
57+
```
58+
59+
**Mutation (Create/Update):**
60+
```typescript
61+
// Create
62+
const id = await app.object('todo').insert({
63+
title: 'Finish ObjectQL Docs',
64+
priority: 'high'
65+
});
66+
67+
// Update
68+
await app.object('todo').update(
69+
{ filters: [['_id', '=', id]] },
70+
{ doc: { completed: true } }
71+
);
72+
```
73+
74+
### 3. Business Logic
75+
Do not write raw logic inside controllers. Use **Hooks** and **Actions**.
76+
77+
**Actions (Custom Endpoints):**
78+
```typescript
79+
app.registerAction('complete_all', async (params, context) => {
80+
// Logic here
81+
return { success: true };
82+
});
83+
```
84+
85+
**Hooks (Triggers):**
86+
```typescript
87+
// Valid triggers: beforeCreate, afterCreate, beforeUpdate, etc.
88+
app.object('todo').on('beforeCreate', async (doc, context) => {
89+
if (!doc.title) throw new Error("Title is required");
90+
});
91+
```
92+
````
93+
94+
---
95+
96+
## 如何在工具中使用
97+
98+
### 对于 Cursor 用户
99+
在你的项目根目录下创建一个 `.cursorrules` 文件,并将上述内容粘贴进去。Cursor 会自动索引这些规则。
100+
101+
### 对于 GitHub Copilot 用户
102+
在 VS Code 的 Copilot 设置中,或者在每次对话的开头,可以简要引用:
103+
> "Use the ObjectQL standard: abstract definitions in YAML, `app` instance naming, and JSON AST queries."
104+
105+
### 对于 ChatGPT / Claude
106+
直接将整个 Prompt 作为对话的第一条消息发送。

docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ hero:
1414
link: /guide/getting-started
1515
- theme: alt
1616
text: AI Integration
17-
link: /guide/ai
17+
link: /guide/ai-coding
1818

1919
features:
2020
- icon: 🤖

0 commit comments

Comments
 (0)