@@ -260,273 +260,6 @@ pnpm objectstack --help
260260pnpm 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/
5753533 . Other packages - Can build in parallel after spec
5763544 . Examples - Build last
577355
578- ---
579-
580356## Best Practices
581357
582358### Code Organization
@@ -608,17 +384,14 @@ spec/
6083843 . Update documentation if needed
6093854 . 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
624396Apache 2.0 © ObjectStack
397+
0 commit comments