From 7ba7fd0ae94be227d49cb9b0c277344d56d2c201 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 17 Jan 2026 01:11:19 +0000
Subject: [PATCH 1/3] Initial plan


From ce8123b4feea371f6d4b6ec0c871172667d6c90e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 17 Jan 2026 01:17:51 +0000
Subject: [PATCH 2/3] Update ObjectStack Manifesto with 4 core principles

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 content/docs/00-framework/manifesto.mdx    | 290 +++++++++++++++++---
 content/docs/cn/00-framework/manifesto.mdx | 292 ++++++++++++++++++---
 2 files changed, 497 insertions(+), 85 deletions(-)

diff --git a/content/docs/00-framework/manifesto.mdx b/content/docs/00-framework/manifesto.mdx
index 7ebe54d..b08f498 100644
--- a/content/docs/00-framework/manifesto.mdx
+++ b/content/docs/00-framework/manifesto.mdx
@@ -1,23 +1,25 @@
 ---
-title: The Manifesto
-description: ObjectStack's core design principles
+title: The ObjectStack Manifesto
+description: The unshakable core principles that govern ObjectStack's existence and evolution
 ---
 
-# The Manifesto
+# The ObjectStack Manifesto
 
-ObjectStack's design follows three core principles that form the foundation of the entire architecture.
+ObjectStack exists to return data application development to its essence. To maintain a healthy and open ecosystem, we pledge to uphold the following unshakable core principles:
 
 ## Principle I: Protocol Neutrality
 
-### Definition
+### The Principle
 
-The protocol layer must remain technology-neutral, not dependent on any specific implementation technology.
+**ObjectQL is neutral**: It must not contain any logic specific to a particular language (e.g., Node.js), database (e.g., MySQL), or runtime (e.g., Electron).
 
-### Core Philosophy
+### Standards First
+
+**Spec before Engine**: Any feature must first be defined in the Specification layer before being implemented in the Engine layer. We reject the "implement first, standardize later" black-box approach.
 
-**"Protocol is the standard, implementation is replaceable"**
+### What This Means
 
-ObjectStack's protocol layer (ObjectQL, ObjectUI) is purely specification definition, containing no concrete implementation. This means:
+ObjectStack's protocol layer (ObjectQL, ObjectUI) consists purely of specification definitions, with no concrete implementation. This ensures:
 
 - ObjectQL protocol can have multiple implementations (JavaScript, Python, Java, etc.)
 - ObjectUI protocol can have multiple renderers (React, Vue, Angular, etc.)
@@ -29,11 +31,13 @@ ObjectStack's protocol layer (ObjectQL, ObjectUI) is purely specification defini
 - Use standard JSON Schema format
 - Avoid introducing language or framework-specific concepts
 - Keep protocols simple and extensible
+- Define in Spec layer first, implement in Engine layer second
 
 **When developing implementations**:
 - Strictly follow protocol specifications
 - Validate protocol compatibility through test suites
 - Implementations should be interchangeable without affecting applications
+- No implementation-specific logic should leak into the protocol layer
 
 ### Example
 
@@ -54,15 +58,19 @@ This ObjectQL query protocol can be:
 - Transpiled to PostgreSQL queries by Python implementation
 - Transpiled to Oracle queries by Java implementation
 
-## Principle II: Mechanism-Implementation Separation
+**The protocol remains neutral; the implementation is replaceable.**
 
-### Definition
+## Principle II: Mechanism over Policy
 
-Completely separate "what to do" (mechanism) from "how to do it" (implementation).
+### The Principle
 
-### Core Philosophy
+**ObjectQL provides mechanisms only**: It defines the `allowRead` interface, but never mandates where user data must exist.
+
+**ObjectOS provides implementations**: User systems, file storage, and multi-tenancy logic belong to the OS layer. Polluting the Protocol layer with these is strictly forbidden.
 
-**"Define behavior, not implementation"**
+### Separation of Concerns
+
+We completely separate "what to do" (mechanism) from "how to do it" (policy/implementation).
 
 Developers only need to:
 - Define data models (Schema)
@@ -73,10 +81,11 @@ Without worrying about:
 - How data is stored
 - How interfaces are rendered
 - How queries are optimized
+- How permissions are enforced
 
 ### Practice Guidelines
 
-**Schema Definition**:
+**Schema Definition** (Mechanism):
 
 ```json
 {
@@ -86,17 +95,23 @@ Without worrying about:
     "customer": { "type": "reference", "ref": "customers" },
     "total": { "type": "number" },
     "status": { "type": "select", "options": ["pending", "completed"] }
+  },
+  "permissions": {
+    "allowRead": "{{ formula }}"
   }
 }
 ```
 
-Developers only define the data model, and the system automatically:
+The protocol defines the **mechanism** (`allowRead` interface), while ObjectOS provides the **implementation** (user authentication, data filtering).
+
+Developers only define the data model and permissions interface, and the system automatically:
 - Creates database table structure
 - Generates CRUD APIs
 - Provides data validation
 - Establishes relationship mappings
+- Enforces permission rules
 
-**UI Definition**:
+**UI Definition** (Mechanism):
 
 ```json
 {
@@ -119,18 +134,50 @@ Developers only define the interface structure, and the system automatically:
 - Executes form validation
 - Manages state updates
 
-### Benefits
+### Why This Matters
+
+1. **Protocol layer stays pure**: ObjectQL defines mechanisms like `allowRead`, not policies like "must use JWT authentication"
+2. **Implementation flexibility**: ObjectOS can implement user systems using JWT, OAuth, or custom solutions
+3. **No vendor lock-in**: User system logic belongs to OS layer, not hardcoded in protocol
+4. **Clear boundaries**: Mechanism (ObjectQL) vs. Implementation (ObjectOS) separation is strictly enforced
+
+### ❌ What We Reject
+
+**Bad Example**: Adding user authentication logic directly to ObjectQL protocol
+```json
+// ❌ FORBIDDEN: This pollutes the protocol layer
+{
+  "object": "users",
+  "authentication": {
+    "provider": "jwt",
+    "secret": "hardcoded-secret"
+  }
+}
+```
+
+**Good Example**: ObjectQL defines mechanism, ObjectOS provides implementation
+```json
+// ✅ CORRECT: Protocol defines the mechanism
+{
+  "object": "users",
+  "permissions": {
+    "allowRead": "{{ currentUser.id === record.id }}"
+  }
+}
+
+// ObjectOS implementation (separate layer) handles:
+// - What is "currentUser"?
+// - How is authentication performed?
+// - Where is user data stored?
+```
 
-1. **Lower learning curve**: Developers don't need to learn implementation details
-2. **Higher development efficiency**: Focus on business logic rather than technical implementation
-3. **Enhanced maintainability**: Business logic is independent of technology stack
-4. **Easier technology upgrades**: Changing underlying implementation doesn't affect business code
+## Principle III: Data Sovereignty
 
-## Principle III: Data Sovereignty Declaration
+### The Principle
 
-### Definition
+**Local-First**: All architectural designs must prioritize "offline availability". Any core functionality that depends on cloud connectivity to operate is **forbidden**.
 
-Users have complete control and ownership of their data.
+**Portability**: User data (Schema + Data) must be exportable in standard file formats (.oos / .json), never locked into any specific vendor's cloud platform.
 
 ### Core Philosophy
 
@@ -141,6 +188,7 @@ ObjectStack adheres to the Local-First philosophy:
 - Users can choose their own database
 - No mandatory cloud service binding
 - Supports fully offline data operation
+- Complete data portability guaranteed
 
 ### Practice Guidelines
 
@@ -150,30 +198,57 @@ ObjectStack adheres to the Local-First philosophy:
    - Use .oos files to store data (based on SQLite)
    - Data completely local, no network required
    - Suitable for personal application scenarios
+   - Works offline by design
 
 2. **Self-Hosted Mode**:
    - Deploy to enterprise's own servers
    - Use enterprise's existing databases (MySQL, Oracle, etc.)
    - Enterprise has complete data control
+   - No dependency on external services
 
 3. **Hybrid Mode**:
    - Local-first with optional cloud sync
    - Supports end-to-end encryption
    - Users can export data anytime
+   - Cloud is enhancement, not requirement
 
 ### Data Migration Freedom
 
 **Zero-Friction Migration**:
 
 ```bash
+# Export data in standard format
+objectstack export --format json --output my-data.json
+
 # Migrate from SQLite to MySQL
 objectstack migrate --from sqlite://app.oos --to mysql://localhost/mydb
 
 # Migrate from MySQL to PostgreSQL
 objectstack migrate --from mysql://... --to postgresql://...
+
+# Export as portable .oos file
+objectstack export --format oos --output my-app.oos
+```
+
+Due to protocol layer abstraction, data can freely migrate between different databases without vendor lock-in. User data (Schema + Data) can always be exported in standard formats.
+
+### What Is Forbidden
+
+❌ **Prohibited**: Core features that require cloud connectivity
+```
+// ❌ FORBIDDEN
+"This feature requires internet connection to function"
+"Data must be stored on our cloud servers"
+"Offline mode is not supported"
 ```
 
-Due to protocol layer abstraction, data can freely migrate between different databases without vendor lock-in.
+✅ **Required**: Core features must work offline
+```
+// ✅ CORRECT
+"Works offline by default, cloud sync is optional"
+"Data stored locally, you own and control it"
+"Export your data anytime in .oos or .json format"
+```
 
 ### Privacy Protection
 
@@ -181,6 +256,7 @@ Due to protocol layer abstraction, data can freely migrate between different dat
 - **Field-level permissions**: Fine-grained data access control
 - **Audit logs**: Complete data access records
 - **Data erasure**: Support for complete user data deletion
+- **No telemetry lock-in**: Users control what data is shared
 
 ### Open Source Commitment
 
@@ -188,16 +264,104 @@ Due to protocol layer abstraction, data can freely migrate between different dat
 - Ensures protocol specifications are permanently open
 - Community can freely implement compatible engines
 - Avoids single vendor control
+- Data formats are publicly documented and open
+
+## Principle IV: Stability Pledge
+
+### The Principle
+
+**As foundational infrastructure, we pledge the stability of ObjectQL's core syntax.** For breaking changes, we will provide at least 2 major version migration windows.
+
+### Version Compatibility Commitment
+
+ObjectStack is not a typical application—it's infrastructure. Applications built on ObjectStack must have confidence that their foundation is stable.
+
+**Our Promise**:
+1. **Core syntax stability**: ObjectQL query syntax, schema definitions, and protocol formats are stable
+2. **Migration window**: Breaking changes require at least 2 major versions notice
+3. **Deprecation path**: Features marked deprecated will be supported for at least 2 major versions
+4. **Backward compatibility**: New features are additive, not destructive
+
+### What This Means in Practice
+
+**Version Policy**:
+- **Patch versions** (1.0.x): Bug fixes only, zero breaking changes
+- **Minor versions** (1.x.0): New features, backward compatible
+- **Major versions** (x.0.0): May include breaking changes, but with migration path
+
+**Breaking Change Process**:
+1. **Version N**: Feature marked as deprecated, warning added
+2. **Version N+1**: Deprecation warning continues, migration guide provided
+3. **Version N+2**: Feature can be removed, but migration tool provided
+
+**Example Timeline**:
+```
+v1.0.0: Feature X works normally
+v2.0.0: Feature X deprecated, warning added
+       "⚠️ Feature X is deprecated, use Feature Y instead"
+       Both X and Y work
+v3.0.0: Feature X still works with warning
+       Migration guide and automated migration tool provided
+v4.0.0: Feature X can be removed
+       Migration tool continues to work
+```
+
+### What We Guarantee
+
+✅ **Stable Core**:
+- ObjectQL query syntax
+- Schema definition format
+- Protocol message structure
+- Data type system
+- Permission model interface
+
+✅ **Migration Support**:
+- Automated migration tools
+- Comprehensive migration guides
+- Version compatibility testing
+- Community support during migrations
 
-## Significance of the Manifesto
+### What Can Change
 
-These three principles are not technical details, but ObjectStack's **core values**:
+The following can evolve without the 2-version window:
+- **Implementation details**: How engines execute queries internally
+- **Performance optimizations**: Query optimization strategies
+- **New features**: Additive features that don't break existing code
+- **Bug fixes**: Corrections to unintended behavior
+- **Documentation**: Clarifications and improvements
+
+### Why This Matters
+
+As infrastructure, ObjectStack powers applications that may live for years or decades. Breaking compatibility casually would:
+- ❌ Destroy trust in the platform
+- ❌ Force costly rewrites on users
+- ❌ Create fragmentation in the ecosystem
+- ❌ Violate the data sovereignty principle
+
+Our stability pledge ensures:
+- ✅ Long-term confidence in ObjectStack
+- ✅ Predictable upgrade paths
+- ✅ Lower total cost of ownership
+- ✅ Ecosystem coherence
+
+### Compatibility Testing
+
+Every ObjectStack release includes:
+- Backward compatibility test suite
+- Migration path validation
+- Version compatibility matrix
+- Breaking change documentation
+
+## The Unshakable Foundation
+
+These four principles are not technical details—they are **ObjectStack's core values**:
 
 1. **Protocol Neutrality**: Ensures freedom of technology choice
-2. **Mechanism-Implementation Separation**: Ensures development efficiency and maintainability
-3. **Data Sovereignty**: Ensures user rights
+2. **Mechanism over Policy**: Ensures clean architecture and flexibility
+3. **Data Sovereignty**: Ensures user rights and data freedom
+4. **Stability Pledge**: Ensures long-term reliability and trust
 
-Features that violate these principles, even if they have short-term benefits, should not be added to ObjectStack.
+Features that violate these principles, even if they have short-term benefits, **must not** be added to ObjectStack.
 
 ## Design Decision Examples
 
@@ -206,9 +370,16 @@ Features that violate these principles, even if they have short-term benefits, s
 **Scenario**: Adding full-text search functionality
 
 **Decision**:
-- Define unified full-text search syntax in protocol layer
+- Define unified full-text search syntax in protocol layer (Principle I: Protocol Neutrality)
 - Allow different implementations to use different search engines (Elasticsearch, Meilisearch, etc.)
-- Users can choose the search solution that suits them
+- Users can choose the search solution that suits them (Principle III: Data Sovereignty)
+- Keep search syntax backward compatible (Principle IV: Stability Pledge)
+
+**Why it complies**:
+- Protocol layer defines mechanism, not implementation
+- No vendor lock-in
+- Works offline with local search index
+- Stable, documented syntax
 
 ### ❌ Non-Compliant Design
 
@@ -218,27 +389,62 @@ Features that violate these principles, even if they have short-term benefits, s
 - Mandatory use of a specific cloud service provider
 - Data must be uploaded to platform servers
 - No local storage option provided
+- Core features require internet connection
 
 **Why it violates**:
-- Violates Protocol Neutrality principle (binding to specific provider)
-- Violates Data Sovereignty principle (mandatory cloud storage)
+- ❌ Violates Protocol Neutrality (Principle I): Binding to specific provider
+- ❌ Violates Data Sovereignty (Principle III): Mandatory cloud storage, requires internet
+- ❌ Violates Local-First mandate: Core feature depends on cloud connectivity
+
+**Compliant Alternative**:
+- Define storage abstraction protocol
+- Support local storage (SQLite, file system) as default
+- Cloud storage as optional plugin
+- All features work offline first
 
 ## Practice Checklist
 
 When designing new features, ask yourself:
 
-- [ ] Is this feature defined in the protocol layer or implementation layer?
-- [ ] Does it depend on specific technology or services?
-- [ ] Do users maintain complete control over data?
-- [ ] Can it have multiple implementation approaches?
-- [ ] Does it increase vendor lock-in risk?
+**Protocol Neutrality**:
+- [ ] Is this feature defined in the Spec layer first?
+- [ ] Does it avoid language/database/runtime-specific logic?
+- [ ] Can it have multiple implementations?
+
+**Mechanism over Policy**:
+- [ ] Does it define mechanism (interface) rather than policy (implementation)?
+- [ ] Is implementation logic properly separated into ObjectOS layer?
+- [ ] Does it avoid polluting the Protocol layer?
+
+**Data Sovereignty**:
+- [ ] Does it work offline (Local-First)?
+- [ ] Can users export their data in standard formats?
+- [ ] Does it avoid vendor lock-in?
+- [ ] Do users maintain complete control over their data?
+
+**Stability Pledge**:
+- [ ] Is it backward compatible?
+- [ ] If breaking, is there a 2-version migration path?
+- [ ] Is the change documented with migration guide?
+
+## Enforcement
+
+This manifesto is enforced through:
+
+1. **Code Review**: All contributions must comply with these principles
+2. **Architecture Review**: Major features reviewed against manifesto
+3. **Community Governance**: Manifesto violations can be raised by anyone
+4. **Documentation**: All new features documented with manifesto compliance rationale
 
 ## Summary
 
-ObjectStack's architectural manifesto is not just a technical guide, but a declaration of values. It ensures:
+The ObjectStack Manifesto is not just a technical guide—it's a **declaration of values**. It ensures:
 
 - **Technical Freedom**: Developers can choose the most suitable technology stack
+- **Architectural Purity**: Clean separation between mechanism and implementation
 - **Data Freedom**: Users fully own and control their data
 - **Evolution Freedom**: System can continuously evolve without breaking compatibility
 
-These principles are what fundamentally distinguish ObjectStack from other platforms.
+These principles are what fundamentally distinguish ObjectStack from other platforms. They are **unshakable** and **non-negotiable**.
+
+When in doubt, return to these four principles. They are the foundation upon which ObjectStack is built, and the promise we make to everyone who builds on ObjectStack.
diff --git a/content/docs/cn/00-framework/manifesto.mdx b/content/docs/cn/00-framework/manifesto.mdx
index 9c07063..542c153 100644
--- a/content/docs/cn/00-framework/manifesto.mdx
+++ b/content/docs/cn/00-framework/manifesto.mdx
@@ -1,23 +1,25 @@
 ---
-title: 架构宪法
-description: ObjectStack 的核心设计原则
+title: ObjectStack 宣言
+description: 定义 ObjectStack 存在与演进的不可动摇的核心原则
 ---
 
-# 架构宪法（The Manifesto）
+# ObjectStack 宣言（The ObjectStack Manifesto）
 
-ObjectStack 的设计遵循三大核心原则，这些原则构成了整个架构的基础。
+ObjectStack 的存在是为了让数据应用开发回归本质。为了保持生态的健康与开放，我们承诺遵循以下不可动摇的核心原则：
 
-## 原则一：协议中立（Protocol Neutrality）
+## 第一条：协议中立原则（Protocol Neutrality）
 
-### 定义
+### 原则
 
-协议层必须保持技术中立，不依赖于任何特定的实现技术。
+**ObjectQL 是中立的**：它不应该包含任何特定于语言（如 Node.js）、特定于数据库（如 MySQL）或特定于运行时（如 Electron）的逻辑。
 
-### 核心理念
+### 标准优先
+
+**Spec 先于 Engine**：任何功能必须先在 Spec（规范）层定义，然后才在 Engine（引擎）层实现。我们拒绝"先实现后标准化"的黑盒操作。
 
-**"协议即标准，实现可替换"**
+### 这意味着什么
 
-ObjectStack 的协议层（ObjectQL、ObjectUI）是纯粹的规范定义，不包含任何具体实现。这意味着：
+ObjectStack 的协议层（ObjectQL、ObjectUI）是纯粹的规范定义，不包含任何具体实现。这确保了：
 
 - ObjectQL 协议可以有多种实现（JavaScript、Python、Java 等）
 - ObjectUI 协议可以有多种渲染器（React、Vue、Angular 等）
@@ -29,11 +31,13 @@ ObjectStack 的协议层（ObjectQL、ObjectUI）是纯粹的规范定义，不
 - 使用标准的 JSON Schema 格式
 - 避免引入特定语言或框架的概念
 - 保持协议的简洁性和可扩展性
+- 先在 Spec 层定义，再在 Engine 层实现
 
 **实现开发时**：
 - 严格遵循协议规范
 - 通过测试套件验证协议兼容性
 - 实现之间可以相互替换而不影响应用
+- 不得将特定实现的逻辑泄漏到协议层
 
 ### 示例
 
@@ -54,15 +58,19 @@ ObjectStack 的协议层（ObjectQL、ObjectUI）是纯粹的规范定义，不
 - Python 实现转译成 PostgreSQL 查询
 - Java 实现转译成 Oracle 查询
 
-## 原则二：机制与实现分离（Mechanism-Implementation Separation）
+**协议保持中立；实现可以替换。**
 
-### 定义
+## 第二条：机制与实现分离（Mechanism over Policy）
 
-将"做什么"（机制）与"怎么做"（实现）彻底分离。
+### 原则
 
-### 核心理念
+**ObjectQL 只提供机制**：它定义 `allowRead` 接口，但绝不强制规定用户数据必须存在哪里。
+
+**ObjectOS 提供实现**：用户系统、文件存储、多租户逻辑属于 OS 层，严禁下沉污染 Protocol 层。
 
-**"定义行为，不定义实现"**
+### 关注点分离
+
+我们将"做什么"（机制）与"怎么做"（策略/实现）彻底分离。
 
 开发者只需要：
 - 定义数据模型（Schema）
@@ -73,10 +81,11 @@ ObjectStack 的协议层（ObjectQL、ObjectUI）是纯粹的规范定义，不
 - 数据如何存储
 - 界面如何渲染
 - 查询如何优化
+- 权限如何执行
 
 ### 实践指南
 
-**Schema 定义**：
+**Schema 定义**（机制）：
 
 ```json
 {
@@ -86,17 +95,23 @@ ObjectStack 的协议层（ObjectQL、ObjectUI）是纯粹的规范定义，不
     "customer": { "type": "reference", "ref": "customers" },
     "total": { "type": "number" },
     "status": { "type": "select", "options": ["pending", "completed"] }
+  },
+  "permissions": {
+    "allowRead": "{{ formula }}"
   }
 }
 ```
 
-开发者只需要定义数据模型，系统自动：
+协议定义**机制**（`allowRead` 接口），而 ObjectOS 提供**实现**（用户认证、数据过滤）。
+
+开发者只需要定义数据模型和权限接口，系统自动：
 - 创建数据库表结构
 - 生成 CRUD API
 - 提供数据验证
 - 建立关系映射
+- 执行权限规则
 
-**UI 定义**：
+**UI 定义**（机制）：
 
 ```json
 {
@@ -119,18 +134,50 @@ ObjectStack 的协议层（ObjectQL、ObjectUI）是纯粹的规范定义，不
 - 执行表单验证
 - 管理状态更新
 
-### 好处
+### 为什么这很重要
+
+1. **协议层保持纯粹**：ObjectQL 定义像 `allowRead` 这样的机制，而不是像"必须使用 JWT 认证"这样的策略
+2. **实现灵活性**：ObjectOS 可以使用 JWT、OAuth 或自定义方案来实现用户系统
+3. **无厂商锁定**：用户系统逻辑属于 OS 层，不硬编码在协议中
+4. **清晰的边界**：机制（ObjectQL）与实现（ObjectOS）的分离被严格执行
+
+### ❌ 我们拒绝的做法
+
+**错误示例**：直接在 ObjectQL 协议中添加用户认证逻辑
+```json
+// ❌ 禁止：这污染了协议层
+{
+  "object": "users",
+  "authentication": {
+    "provider": "jwt",
+    "secret": "hardcoded-secret"
+  }
+}
+```
+
+**正确示例**：ObjectQL 定义机制，ObjectOS 提供实现
+```json
+// ✅ 正确：协议定义机制
+{
+  "object": "users",
+  "permissions": {
+    "allowRead": "{{ currentUser.id === record.id }}"
+  }
+}
+
+// ObjectOS 实现（独立层）处理：
+// - "currentUser" 是什么？
+// - 如何执行认证？
+// - 用户数据存储在哪里？
+```
 
-1. **降低学习曲线**：开发者不需要学习底层实现细节
-2. **提高开发效率**：专注于业务逻辑而非技术实现
-3. **增强可维护性**：业务逻辑独立于技术栈
-4. **便于技术升级**：更换底层实现不影响业务代码
+## 第三条：数据主权原则（Data Sovereignty）
 
-## 原则三：数据主权宣言（Data Sovereignty Declaration）
+### 原则
 
-### 定义
+**Local-First**：所有架构设计必须优先考虑"离线可用性"。任何依赖云端连接才能运行的核心功能，都是**被禁止的**。
 
-用户拥有对其数据的完全控制权和所有权。
+**可移植性**：用户的数据（Schema + Data）必须能以标准文件格式（.oos / .json）导出，不锁定在任何特定厂商的云平台上。
 
 ### 核心理念
 
@@ -141,6 +188,7 @@ ObjectStack 坚持本地优先（Local-First）理念：
 - 用户可以选择自己的数据库
 - 没有强制性的云服务绑定
 - 支持数据完全离线工作
+- 保证完全的数据可移植性
 
 ### 实践指南
 
@@ -150,30 +198,57 @@ ObjectStack 坚持本地优先（Local-First）理念：
    - 使用 .oos 文件存储数据（基于 SQLite）
    - 数据完全在本地，无需网络
    - 适合个人应用场景
+   - 设计上离线工作
 
 2. **自托管模式**：
    - 部署到企业自己的服务器
    - 使用企业现有数据库（MySQL、Oracle 等）
    - 企业完全掌控数据
+   - 不依赖外部服务
 
 3. **混合模式**：
    - 本地优先，可选云同步
    - 支持端到端加密
    - 用户随时可以导出数据
+   - 云是增强，而非必需
 
 ### 数据迁移自由
 
 **零摩擦迁移**：
 
 ```bash
+# 以标准格式导出数据
+objectstack export --format json --output my-data.json
+
 # 从 SQLite 迁移到 MySQL
 objectstack migrate --from sqlite://app.oos --to mysql://localhost/mydb
 
 # 从 MySQL 迁移到 PostgreSQL
 objectstack migrate --from mysql://... --to postgresql://...
+
+# 导出为可移植的 .oos 文件
+objectstack export --format oos --output my-app.oos
+```
+
+由于协议层的抽象，数据可以在不同数据库之间自由迁移，没有厂商锁定。用户数据（Schema + Data）总是可以以标准格式导出。
+
+### 什么是被禁止的
+
+❌ **禁止**：需要云连接才能运行的核心功能
+```
+// ❌ 禁止
+"此功能需要互联网连接才能使用"
+"数据必须存储在我们的云服务器上"
+"不支持离线模式"
 ```
 
-由于协议层的抽象，数据可以在不同数据库之间自由迁移，没有厂商锁定。
+✅ **必需**：核心功能必须离线工作
+```
+// ✅ 正确
+"默认离线工作，云同步是可选的"
+"数据存储在本地，您拥有并控制它"
+"随时以 .oos 或 .json 格式导出您的数据"
+```
 
 ### 隐私保护
 
@@ -181,6 +256,7 @@ objectstack migrate --from mysql://... --to postgresql://...
 - **字段级权限**：细粒度的数据访问控制
 - **审计日志**：完整的数据访问记录
 - **数据擦除**：支持完全删除用户数据
+- **无遥测锁定**：用户控制共享哪些数据
 
 ### 开源承诺
 
@@ -188,16 +264,104 @@ objectstack migrate --from mysql://... --to postgresql://...
 - 确保协议规范永久开放
 - 社区可以自由实现兼容的引擎
 - 避免单一厂商控制
+- 数据格式公开记录且开放
+
+## 第四条：向下兼容承诺（Stability Pledge）
+
+### 原则
+
+**作为底层基础设施，我们承诺 ObjectQL 核心语法的稳定性。**对于破坏性变更（Breaking Changes），我们将提供至少 2 个大版本的迁移窗口。
+
+### 版本兼容性承诺
+
+ObjectStack 不是一个普通的应用程序——它是基础设施。构建在 ObjectStack 之上的应用程序必须对其基础的稳定性充满信心。
+
+**我们的承诺**：
+1. **核心语法稳定**：ObjectQL 查询语法、Schema 定义和协议格式是稳定的
+2. **迁移窗口**：破坏性变更需要至少 2 个主要版本的通知
+3. **弃用路径**：标记为弃用的功能将至少支持 2 个主要版本
+4. **向后兼容**：新功能是增量的，不是破坏性的
+
+### 这在实践中意味着什么
+
+**版本策略**：
+- **补丁版本**（1.0.x）：仅修复错误，零破坏性变更
+- **次要版本**（1.x.0）：新功能，向后兼容
+- **主要版本**（x.0.0）：可能包含破坏性变更，但有迁移路径
+
+**破坏性变更流程**：
+1. **版本 N**：功能标记为弃用，添加警告
+2. **版本 N+1**：弃用警告继续，提供迁移指南
+3. **版本 N+2**：可以删除功能，但提供迁移工具
+
+**示例时间线**：
+```
+v1.0.0: 功能 X 正常工作
+v2.0.0: 功能 X 被弃用，添加警告
+       "⚠️ 功能 X 已弃用，请改用功能 Y"
+       X 和 Y 都可以工作
+v3.0.0: 功能 X 仍然可以工作，但有警告
+       提供迁移指南和自动化迁移工具
+v4.0.0: 可以删除功能 X
+       迁移工具继续可用
+```
+
+### 我们保证的内容
+
+✅ **稳定核心**：
+- ObjectQL 查询语法
+- Schema 定义格式
+- 协议消息结构
+- 数据类型系统
+- 权限模型接口
+
+✅ **迁移支持**：
+- 自动化迁移工具
+- 全面的迁移指南
+- 版本兼容性测试
+- 迁移期间的社区支持
 
-## 宪法的意义
+### 什么可以变更
 
-这三大原则不是技术细节，而是 ObjectStack 的**核心价值观**：
+以下内容可以在没有 2 版本窗口的情况下演进：
+- **实现细节**：引擎内部如何执行查询
+- **性能优化**：查询优化策略
+- **新功能**：不破坏现有代码的增量功能
+- **错误修复**：纠正非预期行为
+- **文档**：澄清和改进
 
-1. **协议中立**：保证技术选型自由
-2. **机制实现分离**：保证开发效率和可维护性
-3. **数据主权**：保证用户权益
+### 为什么这很重要
 
-违背这些原则的功能，即使有短期利益，也不应该加入到 ObjectStack 中。
+作为基础设施，ObjectStack 支撑着可能运行数年甚至数十年的应用程序。随意破坏兼容性会：
+- ❌ 破坏对平台的信任
+- ❌ 强迫用户进行昂贵的重写
+- ❌ 在生态系统中造成碎片化
+- ❌ 违反数据主权原则
+
+我们的稳定性承诺确保：
+- ✅ 对 ObjectStack 的长期信心
+- ✅ 可预测的升级路径
+- ✅ 更低的总拥有成本
+- ✅ 生态系统的一致性
+
+### 兼容性测试
+
+每个 ObjectStack 版本都包括：
+- 向后兼容性测试套件
+- 迁移路径验证
+- 版本兼容性矩阵
+- 破坏性变更文档
+
+## 不可动摇的基础
+
+这四大原则不是技术细节——它们是 **ObjectStack 的核心价值观**：
+
+1. **协议中立原则**：确保技术选型自由
+2. **机制与实现分离**：确保架构清晰与灵活性
+3. **数据主权原则**：确保用户权益和数据自由
+4. **向下兼容承诺**：确保长期可靠性和信任
+
+违背这些原则的功能，即使有短期利益，也**绝不**应该加入到 ObjectStack 中。
 
 ## 设计决策示例
 
@@ -206,9 +370,16 @@ objectstack migrate --from mysql://... --to postgresql://...
 **场景**：添加全文搜索功能
 
 **决策**：
-- 在协议层定义统一的全文搜索语法
+- 在协议层定义统一的全文搜索语法（第一条：协议中立原则）
 - 允许不同实现使用不同的搜索引擎（Elasticsearch、Meilisearch 等）
-- 用户可以选择适合自己的搜索方案
+- 用户可以选择适合自己的搜索方案（第三条：数据主权原则）
+- 保持搜索语法向后兼容（第四条：向下兼容承诺）
+
+**为什么符合**：
+- 协议层定义机制，而非实现
+- 无厂商锁定
+- 使用本地搜索索引离线工作
+- 稳定、有文档的语法
 
 ### ❌ 违反宪法的设计
 
@@ -218,27 +389,62 @@ objectstack migrate --from mysql://... --to postgresql://...
 - 强制使用某个特定的云服务商
 - 数据必须上传到平台的服务器
 - 不提供本地存储选项
+- 核心功能需要互联网连接
 
 **为什么违反**：
-- 违反了协议中立原则（绑定特定服务商）
-- 违反了数据主权原则（强制云存储）
+- ❌ 违反协议中立原则（第一条）：绑定特定服务商
+- ❌ 违反数据主权原则（第三条）：强制云存储，需要互联网
+- ❌ 违反本地优先要求：核心功能依赖云连接
+
+**符合的替代方案**：
+- 定义存储抽象协议
+- 支持本地存储（SQLite、文件系统）作为默认
+- 云存储作为可选插件
+- 所有功能优先离线工作
 
 ## 实践检查清单
 
 在设计新功能时，问自己：
 
-- [ ] 这个功能是定义在协议层还是实现层？
-- [ ] 是否依赖于特定的技术或服务？
+**协议中立原则**：
+- [ ] 这个功能是否先在 Spec 层定义？
+- [ ] 是否避免了语言/数据库/运行时特定的逻辑？
+- [ ] 是否可以有多种实现？
+
+**机制与实现分离**：
+- [ ] 是否定义了机制（接口）而非策略（实现）？
+- [ ] 实现逻辑是否正确地分离到 ObjectOS 层？
+- [ ] 是否避免了污染 Protocol 层？
+
+**数据主权原则**：
+- [ ] 是否离线工作（本地优先）？
+- [ ] 用户是否可以以标准格式导出数据？
+- [ ] 是否避免了厂商锁定？
 - [ ] 用户是否保持对数据的完全控制？
-- [ ] 是否可以有多种实现方式？
-- [ ] 是否增加了厂商锁定风险？
+
+**向下兼容承诺**：
+- [ ] 是否向后兼容？
+- [ ] 如果有破坏性变更，是否有 2 版本迁移路径？
+- [ ] 变更是否有文档记录和迁移指南？
+
+## 执行
+
+本宪法通过以下方式执行：
+
+1. **代码审查**：所有贡献必须符合这些原则
+2. **架构审查**：主要功能根据宣言进行审查
+3. **社区治理**：任何人都可以提出违反宣言的问题
+4. **文档记录**：所有新功能都要记录符合宣言的理由
 
 ## 总结
 
-ObjectStack 的架构宪法不仅是技术指南，更是价值观宣言。它确保：
+ObjectStack 宣言不仅是技术指南——它是**价值观宣言**。它确保：
 
 - **技术自由**：开发者可以选择最适合的技术栈
+- **架构纯粹性**：机制与实现之间的清晰分离
 - **数据自由**：用户完全拥有和控制自己的数据
 - **进化自由**：系统可以持续演进而不破坏兼容性
 
-这些原则是 ObjectStack 区别于其他平台的根本所在。
+这些原则是 ObjectStack 区别于其他平台的根本所在。它们是**不可动摇的**和**不可协商的**。
+
+当有疑问时，回到这四大原则。它们是 ObjectStack 构建的基础，也是我们对所有在 ObjectStack 上构建的人的承诺。

From 6dfe291100f8c4afa12eab58fcb5c5db9bdc3a77 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 17 Jan 2026 01:23:22 +0000
Subject: [PATCH 3/3] Complete ObjectStack Manifesto update with 4 core
 principles

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
---
 pnpm-workspace.yaml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 18ec407..ba1b8d4 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,2 +1,6 @@
 packages:
-  - 'packages/*'
+  - packages/*
+
+onlyBuiltDependencies:
+  - esbuild
+  - sharp