Skip to content

Commit f4ea3d4

Browse files
Copilotxuyushun441-sys
Copilot
and
xuyushun441-sys
committed
Add protocol index and Chinese summary documentation
Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
1 parent 25c5f7f commit f4ea3d4

File tree

4 files changed

+387
-2
lines changed

4 files changed

+387
-2
lines changed

‎PROTOCOL_INDEX.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# ObjectStack Protocol Quick Index
2+
3+
> **Fast navigation to all 70 protocol specifications**
4+
5+
Last Updated: 2026-01-27
6+
7+
## Quick Links
8+
9+
| Category | Count | Documentation | Source Code |
10+
| :--- | :---: | :--- | :--- |
11+
| **Data** | 8 | [docs/references/data/](./content/docs/references/data/) | [src/data/](./packages/spec/src/data/) |
12+
| **UI** | 10 | [docs/references/ui/](./content/docs/references/ui/) | [src/ui/](./packages/spec/src/ui/) |
13+
| **System** | 14 | [docs/references/system/](./content/docs/references/system/) | [src/system/](./packages/spec/src/system/) |
14+
| **AI** | 8 | [docs/references/ai/](./content/docs/references/ai/) | [src/ai/](./packages/spec/src/ai/) |
15+
| **API** | 6 | [docs/references/api/](./content/docs/references/api/) | [src/api/](./packages/spec/src/api/) |
16+
| **Automation** | 7 | [docs/references/automation/](./content/docs/references/automation/) | [src/automation/](./packages/spec/src/automation/) |
17+
| **Auth** | 6 | [docs/references/auth/](./content/docs/references/auth/) | [src/auth/](./packages/spec/src/auth/) |
18+
| **Permission** | 4 | [docs/references/permission/](./content/docs/references/permission/) | [src/permission/](./packages/spec/src/permission/) |
19+
| **Hub** | 5 | [docs/references/hub/](./content/docs/references/hub/) | [src/hub/](./packages/spec/src/hub/) |
20+
| **Shared** | 1 | [docs/references/shared/](./content/docs/references/shared/) | [src/shared/](./packages/spec/src/shared/) |
21+
| **Stack** | 1 | — | [src/stack.zod.ts](./packages/spec/src/stack.zod.ts) |
22+
23+
## Data Protocol (8 protocols)
24+
25+
| Protocol | File | Description |
26+
| :--- | :--- | :--- |
27+
| **Field** | [field.zod.ts](./packages/spec/src/data/field.zod.ts) | 44 field types for data modeling |
28+
| **Object** | [object.zod.ts](./packages/spec/src/data/object.zod.ts) | Object/table definitions |
29+
| **Query** | [query.zod.ts](./packages/spec/src/data/query.zod.ts) | Query AST with advanced features |
30+
| **Validation** | [validation.zod.ts](./packages/spec/src/data/validation.zod.ts) | Validation rules |
31+
| **Filter** | [filter.zod.ts](./packages/spec/src/data/filter.zod.ts) | Query filtering |
32+
| **Dataset** | [dataset.zod.ts](./packages/spec/src/data/dataset.zod.ts) | Dataset definitions |
33+
| **Mapping** | [mapping.zod.ts](./packages/spec/src/data/mapping.zod.ts) | Field mappings |
34+
| **Hook** | [hook.zod.ts](./packages/spec/src/data/hook.zod.ts) | Lifecycle hooks |
35+
36+
## UI Protocol (10 protocols)
37+
38+
| Protocol | File | Description |
39+
| :--- | :--- | :--- |
40+
| **View** | [view.zod.ts](./packages/spec/src/ui/view.zod.ts) | List/form views |
41+
| **Page** | [page.zod.ts](./packages/spec/src/ui/page.zod.ts) | FlexiPage layouts |
42+
| **App** | [app.zod.ts](./packages/spec/src/ui/app.zod.ts) | App navigation |
43+
| **Dashboard** | [dashboard.zod.ts](./packages/spec/src/ui/dashboard.zod.ts) | Dashboard layouts |
44+
| **Report** | [report.zod.ts](./packages/spec/src/ui/report.zod.ts) | Report definitions |
45+
| **Action** | [action.zod.ts](./packages/spec/src/ui/action.zod.ts) | UI actions |
46+
| **Component** | [component.zod.ts](./packages/spec/src/ui/component.zod.ts) | Reusable components |
47+
| **Block** | [block.zod.ts](./packages/spec/src/ui/block.zod.ts) | UI blocks |
48+
| **Theme** | [theme.zod.ts](./packages/spec/src/ui/theme.zod.ts) | Theming system |
49+
| **Widget** | [widget.zod.ts](./packages/spec/src/ui/widget.zod.ts) | Custom widgets |
50+
51+
## System Protocol (14 protocols)
52+
53+
| Protocol | File | Description |
54+
| :--- | :--- | :--- |
55+
| **Manifest** | [manifest.zod.ts](./packages/spec/src/system/manifest.zod.ts) | Package manifest |
56+
| **Datasource** | [datasource.zod.ts](./packages/spec/src/system/datasource.zod.ts) | Data source config |
57+
| **Driver** | [driver.zod.ts](./packages/spec/src/system/driver.zod.ts) | Database drivers |
58+
| **PostgreSQL** | [driver/postgres.zod.ts](./packages/spec/src/system/driver/postgres.zod.ts) | PostgreSQL driver |
59+
| **MongoDB** | [driver/mongo.zod.ts](./packages/spec/src/system/driver/mongo.zod.ts) | MongoDB driver |
60+
| **Plugin** | [plugin.zod.ts](./packages/spec/src/system/plugin.zod.ts) | Plugin interface |
61+
| **Context** | [context.zod.ts](./packages/spec/src/system/context.zod.ts) | Kernel context |
62+
| **Events** | [events.zod.ts](./packages/spec/src/system/events.zod.ts) | Event bus |
63+
| **Job** | [job.zod.ts](./packages/spec/src/system/job.zod.ts) | Background jobs |
64+
| **Audit** | [audit.zod.ts](./packages/spec/src/system/audit.zod.ts) | Audit logging |
65+
| **Logger** | [logger.zod.ts](./packages/spec/src/system/logger.zod.ts) | Logging config |
66+
| **Translation** | [translation.zod.ts](./packages/spec/src/system/translation.zod.ts) | i18n support |
67+
| **Feature** | [feature.zod.ts](./packages/spec/src/system/feature.zod.ts) | Feature flags |
68+
| **Storage** | [scoped-storage.zod.ts](./packages/spec/src/system/scoped-storage.zod.ts) | Key-value storage |
69+
70+
## AI Protocol (8 protocols)
71+
72+
| Protocol | File | Description |
73+
| :--- | :--- | :--- |
74+
| **Agent** | [agent.zod.ts](./packages/spec/src/ai/agent.zod.ts) | AI agent definitions |
75+
| **Model Registry** | [model-registry.zod.ts](./packages/spec/src/ai/model-registry.zod.ts) | LLM model registry |
76+
| **RAG Pipeline** | [rag-pipeline.zod.ts](./packages/spec/src/ai/rag-pipeline.zod.ts) | RAG workflows |
77+
| **NLQ** | [nlq.zod.ts](./packages/spec/src/ai/nlq.zod.ts) | Natural language query |
78+
| **Conversation** | [conversation.zod.ts](./packages/spec/src/ai/conversation.zod.ts) | Conversation mgmt |
79+
| **Cost** | [cost.zod.ts](./packages/spec/src/ai/cost.zod.ts) | Cost tracking |
80+
| **Predictive** | [predictive.zod.ts](./packages/spec/src/ai/predictive.zod.ts) | Predictive models |
81+
| **Orchestration** | [orchestration.zod.ts](./packages/spec/src/ai/orchestration.zod.ts) | AI orchestration |
82+
83+
## API Protocol (6 protocols)
84+
85+
| Protocol | File | Description |
86+
| :--- | :--- | :--- |
87+
| **Contract** | [contract.zod.ts](./packages/spec/src/api/contract.zod.ts) | API contracts |
88+
| **Endpoint** | [endpoint.zod.ts](./packages/spec/src/api/endpoint.zod.ts) | REST endpoints |
89+
| **Router** | [router.zod.ts](./packages/spec/src/api/router.zod.ts) | API routing |
90+
| **OData** | [odata.zod.ts](./packages/spec/src/api/odata.zod.ts) | OData support |
91+
| **Realtime** | [realtime.zod.ts](./packages/spec/src/api/realtime.zod.ts) | Real-time subscriptions |
92+
| **Discovery** | [discovery.zod.ts](./packages/spec/src/api/discovery.zod.ts) | API discovery |
93+
94+
## Automation Protocol (7 protocols)
95+
96+
| Protocol | File | Description |
97+
| :--- | :--- | :--- |
98+
| **Flow** | [flow.zod.ts](./packages/spec/src/automation/flow.zod.ts) | Visual workflows |
99+
| **Workflow** | [workflow.zod.ts](./packages/spec/src/automation/workflow.zod.ts) | Workflow rules |
100+
| **Approval** | [approval.zod.ts](./packages/spec/src/automation/approval.zod.ts) | Approval processes |
101+
| **Webhook** | [webhook.zod.ts](./packages/spec/src/automation/webhook.zod.ts) | Webhooks |
102+
| **ETL** | [etl.zod.ts](./packages/spec/src/automation/etl.zod.ts) | ETL pipelines |
103+
| **Sync** | [sync.zod.ts](./packages/spec/src/automation/sync.zod.ts) | Data sync |
104+
| **Connector** | [connector.zod.ts](./packages/spec/src/automation/connector.zod.ts) | External connectors |
105+
106+
## Auth Protocol (6 protocols)
107+
108+
| Protocol | File | Description |
109+
| :--- | :--- | :--- |
110+
| **Identity** | [identity.zod.ts](./packages/spec/src/auth/identity.zod.ts) | User identity |
111+
| **Role** | [role.zod.ts](./packages/spec/src/auth/role.zod.ts) | Role definitions |
112+
| **Organization** | [organization.zod.ts](./packages/spec/src/auth/organization.zod.ts) | Multi-org |
113+
| **Policy** | [policy.zod.ts](./packages/spec/src/auth/policy.zod.ts) | Security policies |
114+
| **Config** | [config.zod.ts](./packages/spec/src/auth/config.zod.ts) | OAuth/SAML/SSO |
115+
| **SCIM** | [scim.zod.ts](./packages/spec/src/auth/scim.zod.ts) | SCIM provisioning |
116+
117+
## Permission Protocol (4 protocols)
118+
119+
| Protocol | File | Description |
120+
| :--- | :--- | :--- |
121+
| **Permission** | [permission.zod.ts](./packages/spec/src/permission/permission.zod.ts) | Object permissions |
122+
| **Sharing** | [sharing.zod.ts](./packages/spec/src/permission/sharing.zod.ts) | Sharing rules |
123+
| **RLS** | [rls.zod.ts](./packages/spec/src/permission/rls.zod.ts) | Row-level security |
124+
| **Territory** | [territory.zod.ts](./packages/spec/src/permission/territory.zod.ts) | Territories |
125+
126+
## Hub Protocol (5 protocols)
127+
128+
| Protocol | File | Description |
129+
| :--- | :--- | :--- |
130+
| **Marketplace** | [marketplace.zod.ts](./packages/spec/src/hub/marketplace.zod.ts) | Plugin marketplace |
131+
| **Composer** | [composer.zod.ts](./packages/spec/src/hub/composer.zod.ts) | Dependency mgmt |
132+
| **License** | [license.zod.ts](./packages/spec/src/hub/license.zod.ts) | Feature licensing |
133+
| **Tenant** | [tenant.zod.ts](./packages/spec/src/hub/tenant.zod.ts) | Multi-tenancy |
134+
| **Space** | [space.zod.ts](./packages/spec/src/hub/space.zod.ts) | Workspace mgmt |
135+
136+
## Shared Protocol (1 protocol)
137+
138+
| Protocol | File | Description |
139+
| :--- | :--- | :--- |
140+
| **Identifiers** | [identifiers.zod.ts](./packages/spec/src/shared/identifiers.zod.ts) | Common identifiers |
141+
142+
## Stack Protocol (1 protocol)
143+
144+
| Protocol | File | Description |
145+
| :--- | :--- | :--- |
146+
| **Stack** | [stack.zod.ts](./packages/spec/src/stack.zod.ts) | Root stack definition |
147+
148+
## Documentation Resources
149+
150+
- **[PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md)** - Detailed reference with examples
151+
- **[PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md)** - Visual diagrams and relationships
152+
- **[README.md](./README.md)** - Project overview
153+
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System architecture
154+
- **[content/docs/references/](./content/docs/references/)** - Generated API documentation (473 files)
155+
156+
## How to Use
157+
158+
### View Source Code
159+
```bash
160+
# View a protocol definition
161+
cat packages/spec/src/data/field.zod.ts
162+
163+
# Search for specific schema
164+
grep -r "FieldSchema" packages/spec/src/
165+
```
166+
167+
### Import in Code
168+
```typescript
169+
import { FieldSchema, ObjectSchema } from '@objectstack/spec/data';
170+
import { ViewSchema, AppSchema } from '@objectstack/spec/ui';
171+
import { ManifestSchema } from '@objectstack/spec/system';
172+
```
173+
174+
### Generate JSON Schema
175+
```bash
176+
# Build generates JSON schemas
177+
pnpm --filter @objectstack/spec build
178+
179+
# Output location
180+
ls packages/spec/json-schema/
181+
```
182+
183+
### Generate Documentation
184+
```bash
185+
# Generate reference docs
186+
pnpm --filter @objectstack/spec gen:docs
187+
188+
# Output location
189+
ls content/docs/references/
190+
```
191+
192+
## Version Information
193+
194+
- **Protocol Version:** 0.3.3
195+
- **Total Protocols:** 70
196+
- **Generated Documentation Files:** 473
197+
- **Last Updated:** 2026-01-27
198+
199+
---
200+
201+
**See Also:**
202+
- [Contributing Guide](./CONTRIBUTING.md)
203+
- [Development Roadmap](./internal/planning/DEVELOPMENT_ROADMAP.md)
204+
- [Protocol Extensions](./PROTOCOL_EXTENSIONS_COMPLETED.md)

‎PROTOCOL_REFERENCE.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44
55
Last Updated: 2026-01-27
66

7-
**📖 See also:** [PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md) for visual diagrams and protocol relationships.
7+
**📖 See also:**
8+
- [PROTOCOL_INDEX.md](./PROTOCOL_INDEX.md) for quick navigation links to all protocols
9+
- [PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md) for visual diagrams and protocol relationships
810

911
## Overview
1012

‎PROTOCOL_UPDATE_SUMMARY_ZH.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# ObjectStack 协议文档更新总结
2+
3+
**更新日期:** 2026-01-27
4+
5+
## 任务完成情况
6+
7+
本次任务已完成对 ObjectStack 规范库中所有协议的全面扫描和文档更新。
8+
9+
### 已完成工作
10+
11+
✅ **扫描了所有 70 个协议文件**
12+
- 覆盖 11 个核心模块
13+
- 每个协议都有完整的 Zod 模式定义
14+
- 生成了 473 个 API 参考文档
15+
16+
✅ **创建了完整的协议文档体系**
17+
1. **PROTOCOL_INDEX.md** - 快速导航索引，包含所有协议的直接链接
18+
2. **PROTOCOL_REFERENCE.md** - 完整的协议清单，包含详细描述和使用示例
19+
3. **PROTOCOL_ORGANIZATION.md** - 可视化图表展示协议结构和依赖关系
20+
21+
✅ **更新了主要文档**
22+
- README.md：添加了协议统计和快速导航链接
23+
- 所有文档之间建立了交叉引用
24+
25+
## 协议统计
26+
27+
| 模块 | 协议数量 | 说明 |
28+
| :--- | :---: | :--- |
29+
| **Data Protocol** | 8 | 核心业务逻辑和数据建模 |
30+
| **UI Protocol** | 10 | 用户界面定义和交互 |
31+
| **System Protocol** | 14 | 运行时环境和平台能力 |
32+
| **AI Protocol** | 8 | AI/ML 集成和智能体编排 |
33+
| **API Protocol** | 6 | 标准化 API 契约和通信 |
34+
| **Automation Protocol** | 7 | 工作流自动化和集成 |
35+
| **Auth Protocol** | 6 | 身份认证和授权 |
36+
| **Permission Protocol** | 4 | 访问控制和安全策略 |
37+
| **Hub Protocol** | 5 | 市场和多租户 |
38+
| **Shared Protocol** | 1 | 通用工具和标识符 |
39+
| **Stack Protocol** | 1 | 根栈定义 |
40+
| **总计** | **70** | **完整协议套件** |
41+
42+
## 核心协议模块
43+
44+
### 1. 数据协议 (ObjectQL) - 8 个协议
45+
定义数据的"形状"和业务逻辑：
46+
- 44 种字段类型（包括 AI/ML 向量和 GPS 位置）
47+
- 高级查询功能（窗口函数、HAVING、DISTINCT、子查询）
48+
- 验证规则和公式
49+
- 生命周期钩子
50+
51+
### 2. UI 协议 (ObjectUI) - 10 个协议
52+
定义交互的"形状"以渲染界面：
53+
- 多种视图类型（网格、看板、日历、甘特图）
54+
- 灵活的页面布局
55+
- 丰富的仪表板和报表功能
56+
- 完整的主题系统
57+
58+
### 3. 系统协议 (ObjectOS) - 14 个协议
59+
定义"运行时环境"和平台能力：
60+
- 可插拔架构
61+
- 多驱动支持（PostgreSQL、MongoDB 等）
62+
- 事件驱动架构
63+
- 全面的审计和日志功能
64+
65+
### 4. AI 协议 - 8 个协议
66+
定义 AI 智能体集成能力：
67+
- 多提供商 LLM 支持
68+
- RAG 语义搜索管道
69+
- 自然语言到 ObjectQL 翻译
70+
- 成本跟踪和预算控制
71+
72+
### 5. API 协议 - 6 个协议
73+
定义标准化 API 契约：
74+
- RESTful API 契约
75+
- OData 查询支持
76+
- 实时订阅（WebSocket/SSE）
77+
- API 速率限制和节流
78+
79+
## 文档导航
80+
81+
### 快速开始
82+
- **[PROTOCOL_INDEX.md](./PROTOCOL_INDEX.md)** - 快速导航到所有 70 个协议
83+
- **[README.md](./README.md)** - 项目概述和入门指南
84+
85+
### 详细参考
86+
- **[PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md)** - 完整的协议清单，包含详细描述
87+
- **[PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md)** - 协议组织的可视化图表
88+
89+
### 架构文档
90+
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - 系统架构概述
91+
- **[content/docs/references/](./content/docs/references/)** - 自动生成的 API 文档（473 个文件）
92+
93+
## 协议文件位置
94+
95+
所有协议定义位于：
96+
```
97+
packages/spec/src/
98+
├── ai/ (8 个协议)
99+
├── api/ (6 个协议)
100+
├── auth/ (6 个协议)
101+
├── automation/ (7 个协议)
102+
├── data/ (8 个协议)
103+
├── hub/ (5 个协议)
104+
├── permission/ (4 个协议)
105+
├── shared/ (1 个协议)
106+
├── system/ (14 个协议)
107+
├── ui/ (10 个协议)
108+
└── stack.zod.ts (1 个协议)
109+
```
110+
111+
## 使用方法
112+
113+
### 查看源代码
114+
```bash
115+
# 查看协议定义
116+
cat packages/spec/src/data/field.zod.ts
117+
118+
# 搜索特定的模式
119+
grep -r "FieldSchema" packages/spec/src/
120+
```
121+
122+
### 在代码中导入
123+
```typescript
124+
import { FieldSchema, ObjectSchema } from '@objectstack/spec/data';
125+
import { ViewSchema, AppSchema } from '@objectstack/spec/ui';
126+
import { ManifestSchema } from '@objectstack/spec/system';
127+
```
128+
129+
### 生成 JSON Schema
130+
```bash
131+
# 构建会生成 JSON schemas
132+
pnpm --filter @objectstack/spec build
133+
134+
# 输出位置
135+
ls packages/spec/json-schema/
136+
```
137+
138+
### 生成文档
139+
```bash
140+
# 生成参考文档
141+
pnpm --filter @objectstack/spec gen:docs
142+
143+
# 输出位置
144+
ls content/docs/references/
145+
```
146+
147+
## 命名约定
148+
149+
所有协议遵循严格的命名约定：
150+
151+
| 上下文 | 约定 | 示例 |
152+
| :--- | :--- | :--- |
153+
| **配置键** | `camelCase` | `maxLength`, `referenceFilters` |
154+
| **机器名称** | `snake_case` | `name: 'project_task'`, `object: 'account'` |
155+
| **Schema 名称** | `PascalCase` + `Schema` | `FieldSchema`, `ObjectSchema` |
156+
| **类型名称** | 从 Zod 推断的 `PascalCase` | `type Field = z.infer<typeof FieldSchema>` |
157+
158+
## 版本信息
159+
160+
- **协议版本:** 0.3.3
161+
- **协议总数:** 70
162+
- **生成的文档文件:** 473
163+
- **最后更新:** 2026-01-27
164+
165+
## 下一步
166+
167+
开发人员可以：
168+
1. 浏览 [PROTOCOL_INDEX.md](./PROTOCOL_INDEX.md) 快速查找特定协议
169+
2. 参考 [PROTOCOL_REFERENCE.md](./PROTOCOL_REFERENCE.md) 了解详细说明
170+
3. 查看 [PROTOCOL_ORGANIZATION.md](./PROTOCOL_ORGANIZATION.md) 理解协议架构
171+
4. 阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解如何贡献
172+
173+
---
174+
175+
**相关链接:**
176+
- [开发路线图](./internal/planning/DEVELOPMENT_ROADMAP.md)
177+
- [优先级矩阵](./internal/planning/PRIORITIES.md)
178+
- [协议扩展](./PROTOCOL_EXTENSIONS_COMPLETED.md)

0 commit comments

Comments
 (0)