Skip to content

Commit 58b6dba

Browse files
Copilothotlong
andcommitted
feat: add serve command and English-only docs
- Add `objectstack serve` command to start server with plugin configuration - Support loading plugins from objectstack.config.ts - Allow custom port via --port flag - Support headless mode with --no-server flag - Remove Chinese documentation, keep English only - Update DEVELOPMENT.md with serve command documentation - Update TOOLCHAIN_DEMO.md to English only Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 9b5fbe0 commit 58b6dba

File tree

6 files changed

+226
-331
lines changed

6 files changed

+226
-331
lines changed

DEVELOPMENT.md

Lines changed: 47 additions & 274 deletions
Original file line numberDiff line numberDiff line change
@@ -260,273 +260,6 @@ pnpm objectstack --help
260260
pnpm objectstack <command> --help
261261
```
262262

263-
---
264-
265-
## 中文版
266-
267-
## 快速开始
268-
269-
### 环境设置
270-
271-
```bash
272-
# 克隆仓库
273-
git clone https://github.com/objectstack-ai/spec.git
274-
cd spec
275-
276-
# 安装依赖
277-
pnpm install
278-
279-
# 构建核心包
280-
pnpm build
281-
282-
# 运行健康检查
283-
pnpm doctor
284-
```
285-
286-
### 开发工作流
287-
288-
#### 使用 ObjectStack CLI
289-
290-
```bash
291-
# 首先构建CLI(如未构建)
292-
pnpm --filter @objectstack/cli build
293-
294-
# 编译配置为JSON
295-
pnpm objectstack compile objectstack.config.ts dist/objectstack.json
296-
297-
# 启动开发模式(包的监听模式)
298-
pnpm objectstack dev [package-name]
299-
300-
# 检查环境健康
301-
pnpm objectstack doctor
302-
303-
# 创建新项目
304-
pnpm objectstack create plugin my-plugin
305-
pnpm objectstack create example my-app
306-
```
307-
308-
#### 常用 npm 快捷命令
309-
310-
```bash
311-
# 一次性设置
312-
pnpm setup # 安装依赖并构建核心包
313-
314-
# 开发
315-
pnpm dev # 启动开发模式(默认:msw-react-crud示例)
316-
pnpm build # 构建所有包
317-
pnpm test # 运行测试
318-
319-
# 诊断
320-
pnpm doctor # 检查环境健康
321-
322-
# 清理
323-
pnpm clean # 清理构建产物
324-
```
325-
326-
### 包开发
327-
328-
#### 开发 @objectstack/spec
329-
330-
```bash
331-
# 监听模式(更改时自动重建)
332-
cd packages/spec
333-
pnpm dev
334-
335-
# 测试监听模式
336-
pnpm test:watch
337-
338-
# 生成schemas和文档
339-
pnpm gen:schema
340-
pnpm gen:docs
341-
```
342-
343-
#### 创建新插件
344-
345-
```bash
346-
# 使用CLI
347-
pnpm objectstack create plugin my-feature
348-
349-
# 然后开发
350-
cd packages/plugins/plugin-my-feature
351-
pnpm install
352-
pnpm dev
353-
```
354-
355-
#### 创建新示例
356-
357-
```bash
358-
# 使用CLI
359-
pnpm objectstack create example my-app
360-
361-
# 然后开发
362-
cd examples/my-app
363-
pnpm install
364-
pnpm build
365-
```
366-
367-
### 测试
368-
369-
#### 单元测试
370-
371-
```bash
372-
# 运行所有测试
373-
pnpm test
374-
375-
# 运行特定包的测试
376-
pnpm --filter @objectstack/spec test
377-
378-
# 监听模式
379-
pnpm --filter @objectstack/spec test:watch
380-
381-
# 覆盖率报告
382-
pnpm --filter @objectstack/spec test:coverage
383-
```
384-
385-
#### 集成测试
386-
387-
```bash
388-
# 测试CRM示例
389-
cd examples/crm
390-
pnpm build
391-
pnpm test
392-
```
393-
394-
### 调试
395-
396-
#### VSCode 调试
397-
398-
`.vscode/launch.json` 中预配置了启动配置:
399-
400-
1. **Debug Current TypeScript File** - 调试任何 .ts 文件
401-
2. **Debug @objectstack/spec Tests** - 调试 spec 测试
402-
3. **Debug CLI (compile)** - 调试 compile 命令
403-
4. **Debug CLI (doctor)** - 调试 doctor 命令
404-
5. **Debug Example (CRM)** - 调试 CRM 示例
405-
406-
**使用方法:**
407-
1. 打开要调试的文件
408-
2.`F5` 或转到运行与调试面板
409-
3. 选择适当的配置
410-
4. 设置断点并调试
411-
412-
#### 命令行调试
413-
414-
```bash
415-
# 使用 tsx 调试
416-
tsx --inspect packages/cli/src/bin.ts doctor
417-
418-
# 使用 node 调试
419-
node --inspect $(which tsx) packages/cli/src/bin.ts compile
420-
```
421-
422-
#### 日志记录
423-
424-
```bash
425-
# 启用详细日志
426-
DEBUG=* pnpm build
427-
428-
# 特定包的日志
429-
DEBUG=objectstack:* pnpm build
430-
```
431-
432-
### 常见任务
433-
434-
#### 添加新的协议Schema
435-
436-
```typescript
437-
// 1. 创建schema文件: packages/spec/src/data/my-schema.zod.ts
438-
import { z } from 'zod';
439-
440-
/**
441-
* 我的新schema
442-
* @description schema的详细描述
443-
*/
444-
export const MySchema = z.object({
445-
/** 字段描述 */
446-
name: z.string().describe('机器名称 (snake_case)'),
447-
448-
/** 另一个字段 */
449-
value: z.number().optional().describe('可选值'),
450-
});
451-
452-
export type MyType = z.infer<typeof MySchema>;
453-
454-
// 2. 从index导出
455-
// packages/spec/src/data/index.ts
456-
export * from './my-schema.zod.js';
457-
458-
// 3. 构建生成JSON schema
459-
pnpm --filter @objectstack/spec build
460-
```
461-
462-
#### 运行特定包命令
463-
464-
```bash
465-
# 按包名过滤
466-
pnpm --filter @objectstack/spec <command>
467-
pnpm --filter @objectstack/cli <command>
468-
469-
# 过滤模式(所有插件)
470-
pnpm --filter "@objectstack/plugin-*" build
471-
472-
# 在所有包中运行
473-
pnpm -r <command>
474-
475-
# 并行运行
476-
pnpm -r --parallel <command>
477-
```
478-
479-
### 性能技巧
480-
481-
1. **增量构建**: 开发期间使用监听模式 (`pnpm dev`)
482-
2. **选择性测试**: 只测试变更的包
483-
3. **并行执行**: 对独立任务使用 `--parallel`
484-
4. **过滤包**: 使用 `--filter` 针对特定包
485-
486-
### 问题排查
487-
488-
#### 常见问题
489-
490-
**依赖未安装:**
491-
```bash
492-
pnpm doctor
493-
pnpm install
494-
```
495-
496-
**构建错误:**
497-
```bash
498-
# 清理并重建
499-
pnpm clean
500-
pnpm build
501-
```
502-
503-
**类型错误:**
504-
```bash
505-
# 确保先构建spec
506-
pnpm --filter @objectstack/spec build
507-
```
508-
509-
**监听模式不工作:**
510-
```bash
511-
# 终止现有进程
512-
pkill -f "tsc --watch"
513-
# 重启
514-
pnpm dev
515-
```
516-
517-
#### 获取帮助
518-
519-
```bash
520-
# 检查环境
521-
pnpm doctor
522-
523-
# CLI帮助
524-
pnpm objectstack --help
525-
pnpm objectstack <command> --help
526-
```
527-
528-
---
529-
530263
## Architecture Overview
531264

532265
### Monorepo Structure
@@ -550,10 +283,55 @@ spec/
550283
├── apps/ # Applications
551284
│ └── docs/ # Documentation site
552285
└── packages/cli/ # Command-line tools
553-
├── src/commands/ # CLI commands (dev, doctor, create, compile)
286+
├── src/commands/ # CLI commands (dev, doctor, create, compile, serve)
554287
└── bin/ # Executable entry points
555288
```
556289

290+
### Starting a Server
291+
292+
The `serve` command starts an ObjectStack server with plugins loaded from your configuration:
293+
294+
```bash
295+
# Start server with default config
296+
pnpm objectstack serve
297+
298+
# Start with custom config and port
299+
pnpm objectstack serve objectstack.config.ts --port 8080
300+
301+
# Start without HTTP server plugin (headless mode)
302+
pnpm objectstack serve --no-server
303+
```
304+
305+
**Configuration Example:**
306+
307+
```typescript
308+
// objectstack.config.ts
309+
import { defineStack } from '@objectstack/spec';
310+
import { HonoServerPlugin } from '@objectstack/plugin-hono-server';
311+
312+
export default defineStack({
313+
metadata: {
314+
name: 'my-app',
315+
version: '1.0.0',
316+
},
317+
318+
objects: {
319+
// Your data objects
320+
},
321+
322+
plugins: [
323+
// Add plugins to load
324+
new HonoServerPlugin({ port: 3000 }),
325+
],
326+
});
327+
```
328+
329+
The server will:
330+
1. Load your configuration file
331+
2. Register all plugins specified in `config.plugins`
332+
3. Start the HTTP server (unless `--no-server` is specified)
333+
4. Listen on the specified port (default: 3000)
334+
557335
### Package Dependencies
558336

559337
```
@@ -575,8 +353,6 @@ spec/
575353
3. Other packages - Can build in parallel after spec
576354
4. Examples - Build last
577355

578-
---
579-
580356
## Best Practices
581357

582358
### Code Organization
@@ -608,17 +384,14 @@ spec/
608384
3. Update documentation if needed
609385
4. Follow the PR template
610386

611-
---
612-
613387
## Resources
614388

615389
- [CONTRIBUTING.md](./CONTRIBUTING.md) - Detailed contribution guide
616390
- [ARCHITECTURE.md](./ARCHITECTURE.md) - Architecture documentation
617391
- [Package Dependencies](./PACKAGE-DEPENDENCIES.md) - Dependency graph
618392
- [Quick Reference](./QUICK-REFERENCE.md) - API quick reference
619393

620-
---
621-
622394
## License
623395

624396
Apache 2.0 © ObjectStack
397+

0 commit comments

Comments
 (0)