Skip to content

Commit 1f54990

Browse files
hotlonghotlong
committed
feat: 添加ObjectQL和ObjectOS实现文档，提供开发者指导和实施规则
1 parent d3b0ab4 commit 1f54990

File tree

4 files changed

+212
-0
lines changed

4 files changed

+212
-0
lines changed

‎packages/spec/llms.txt‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,3 +86,82 @@ const query = {
8686
- `PluginSchema`: Module lifecycle.
8787
- `EventSchema`: Pub/Sub definitions.
8888
- `PolicySchema`: Security rules.
89+
90+
---
91+
92+
## 4. Implementing the Protocol (Engine Devs)
93+
94+
If you are building an ObjectQL engine or Driver in another repository:
95+
96+
### ObjectQL Implementation (Data Layer)
97+
*Reference: `node_modules/@objectstack/spec/prompts/implement-objectql.md`*
98+
99+
Use `z.infer` to derive types directly from the protocol. Do not manually re-declare interfaces.
100+
101+
```typescript
102+
import { DriverInterfaceSchema, type DriverInterface } from '@objectstack/spec/data';
103+
// ...
104+
```
105+
106+
### ObjectOS Implementation (System Layer)
107+
*Reference: `node_modules/@objectstack/spec/prompts/implement-objectos.md`*
108+
109+
The Runtime Kernel must be bootstrapped from the Manifest.
110+
111+
```typescript
112+
import { ManifestSchema, IdentitySchema } from '@objectstack/spec/system';
113+
import { type RequestEnvelope } from '@objectstack/spec/api';
114+
115+
// 1. Boot: Validate Config
116+
const config = ManifestSchema.parse(rawConfig);
117+
118+
// 2. Runtime: Validate Identity
119+
function handleRequest(user: z.infer<typeof IdentitySchema>) { ... }
120+
```
121+
122+
### ObjectUI Implementation (View Layer)
123+
*Reference: `node_modules/@objectstack/spec/prompts/implement-objectui.md`*
124+
125+
The UI must be Server-Driven (SDUI), rendering structures defined by the protocol.
126+
127+
```typescript
128+
import { ViewSchema, ActionSchema } from '@objectstack/spec/ui';
129+
130+
// ✅ Valid: Components accept Schema Props
131+
function GridView({ config }: { config: z.infer<typeof ViewSchema> }) {
132+
// Render based on config.columns, config.filters...
133+
}
134+
```
135+
136+
### 1. Strict Type Compliance
137+
Use `z.infer` to derive types directly from the protocol. Do not manually re-declare interfaces.
138+
139+
```typescript
140+
import { DriverInterfaceSchema, type DriverInterface } from '@objectstack/spec/data';
141+
import { z } from 'zod';
142+
143+
// ✅ CORRECT: Implementing the interface strictly
144+
export class PostgresDriver implements DriverInterface {
145+
name = 'postgres';
146+
version = '1.0.0';
147+
supports = { transactions: true, ... };
148+
149+
// Implementation matches the Zod schema exactly
150+
async find(object: string, query: z.infer<typeof QuerySchema>) {
151+
// ...
152+
}
153+
}
154+
```
155+
156+
### 2. Runtime Validation
157+
The engine **MUST** validate inputs against the Zod schemas before processing.
158+
159+
```typescript
160+
import { ObjectSchema } from '@objectstack/spec/data';
161+
162+
function registerObject(rawConfig: unknown) {
163+
// CRITICAL: Parse strictly throws if protocol is violated
164+
const config = ObjectSchema.parse(rawConfig);
165+
// ... proceed
166+
}
167+
```

‎packages/spec/prompts/implement-objectos.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# ObjectOS Implementation Agent
2+
3+
**Role:** You are the System Architect building the `objectos` runtime kernel.
4+
**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
5+
6+
## 1. Setup
7+
8+
You are working in a repository that depends on `@objectstack/spec`.
9+
Your source of truth is `node_modules/@objectstack/spec`.
10+
11+
## 2. Implementation Rules
12+
13+
### Rule #1: Manifest Driven Boot
14+
The system MUST boot by loading and validating the `objectstack.config.ts`.
15+
```typescript
16+
import { ManifestSchema } from '@objectstack/spec/system';
17+
// The kernel starts here
18+
const config = ManifestSchema.parse(loadedConfig);
19+
```
20+
21+
### Rule #2: Security First (Identity & Policy)
22+
All request handlers must validate against `IdentitySchema`.
23+
No operation proceeds without checking `PolicySchema`.
24+
```typescript
25+
import { IdentitySchema, PolicySchema } from '@objectstack/spec/system';
26+
```
27+
28+
### Rule #3: API Gateway Contract
29+
The HTTP/Gateway layer must perform strict request/response validation using `api/contract.zod.ts` and `api/endpoint.zod.ts`.
30+
- Incoming requests -> Validate `RequestEnvelope`
31+
- Outgoing responses -> Wrap in `ResponseEnvelope`
32+
33+
### Rule #4: Event Driven Architecture
34+
System state changes (User created, Schema changed) MUST emit events defined in `EventSchema`.
35+
Do not invent event formats. Use the standard CloudEvents-compatible structure.
36+
37+
## 3. Workflow
38+
39+
1. **Define Configuration**: Start by mapping `ManifestSchema` to your runtime config.
40+
2. **Initialize Identity**: Implement the Auth Provider using `IdentitySchema`.
41+
3. **Setup Gateway**: Configure routes based on `ApiRoutesSchema` (from `api/discovery.zod.ts`).
42+
43+
## 4. Key Files to Watch
44+
45+
- `system/manifest.zod.ts`: The "Kernel Configuration".
46+
- `system/identity.zod.ts`: The "Security Context".
47+
- `system/events.zod.ts`: The "System Bus".
48+
- `api/contract.zod.ts`: The "Wire Protocol".

‎packages/spec/prompts/implement-objectql.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# ObjectQL Implementation Agent
2+
3+
**Role:** You are the Lead Engineer building the `objectql` engine.
4+
**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
5+
6+
## 1. Setup
7+
8+
You are working in a repository that depends on `@objectstack/spec`.
9+
Your source of truth is `node_modules/@objectstack/spec`.
10+
11+
## 2. Implementation Rules
12+
13+
### Rule #1: Never Redefine Types
14+
Do not create your own interfaces for `Object`, `Field`, or `Query`.
15+
ALWAYS import them:
16+
```typescript
17+
import { type Object, ObjectSchema } from '@objectstack/spec/data';
18+
```
19+
20+
### Rule #2: Schema-First Validation
21+
Every public method in the Engine must invoke the corresponding Zod parser.
22+
If the Input does not match `QuerySchema`, the engine must throw a ZodError.
23+
24+
### Rule #3: Driver Compliance
25+
Drivers must implement `DriverInterface` exactly.
26+
- Do not add public methods to drivers that are not in the spec.
27+
- If a feature (like `vectorSearch`) is defined in `DriverCapabilities`, you must check that flag before executing logic.
28+
29+
## 3. Workflow
30+
31+
1. **Read the Spec**: Before writing logic, read the relevant `.zod.ts` file in `@objectstack/spec`.
32+
2. **Scaffold Types**: Create classes that `implements` the imported types.
33+
3. **Implement Logic**: Write the code to satisfy the interface.
34+
35+
## 4. Key Files to Watch
36+
37+
- `data/query.zod.ts`: The AST you need to parse.
38+
- `data/driver.zod.ts`: The interface you need to call.
39+
- `data/object.zod.ts`: The metadata structure you need to store.

‎packages/spec/prompts/implement-objectui.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# ObjectUI Implementation Agent
2+
3+
**Role:** You are the Lead Frontend Engineer building the `objectui` presentation layer.
4+
**Constraint:** Your implementation must strictly adhere to the `@objectstack/spec` protocol.
5+
6+
## 1. Setup
7+
8+
You are working in a repository that depends on `@objectstack/spec`.
9+
Your source of truth is `node_modules/@objectstack/spec`.
10+
11+
## 2. Implementation Rules
12+
13+
### Rule #1: Server-Driven UI (SDUI)
14+
Do not hardcode page layouts. The UI must render dynamically based on `PageSchema` and `ViewSchema` fetched from the metadata API.
15+
```typescript
16+
import { PageSchema, ViewSchema } from '@objectstack/spec/ui';
17+
// Fetch JSON -> Validate -> Render
18+
const pageLayout = PageSchema.parse(apiResponse);
19+
```
20+
21+
### Rule #2: Metadata-Aware Components
22+
Components (Grid, Form, Kanban) must accept `ViewSchema` as props.
23+
- A `Grid` component takes a `ListView` definition (columns, sort, filter) and renders it.
24+
- A `Form` component takes an `ObjectSchema` and `FormView` definition to render fields.
25+
26+
### Rule #3: Action Abstraction
27+
Buttons do not run arbitrary code. They execute `ActionSchema` definitions.
28+
- `type: 'api'`: Call an endpoint.
29+
- `type: 'flow'`: Trigger a server-side flow.
30+
- `type: 'navigate'`: Change the URL.
31+
32+
### Rule #4: Global Theming
33+
Styles must be derived from `ThemeSchema` (tokens), not hardcoded CSS values.
34+
35+
## 3. Workflow
36+
37+
1. **App Shell**: Implement the navigation frame using `AppSchema` (menus, branding).
38+
2. **Page Router**: specific routes `/app/:object/:view` should load the corresponding `ViewSchema`.
39+
3. **View Renderer**: Create a factory that maps `view.type` ('grid', 'kanban') to React/Vue components.
40+
41+
## 4. Key Files to Watch
42+
43+
- `ui/app.zod.ts`: The Navigation structure.
44+
- `ui/view.zod.ts`: The data visualization config.
45+
- `ui/action.zod.ts`: The interaction logic.
46+
- `ui/page.zod.ts`: The layout container.

0 commit comments

Comments
 (0)