schema-dsl 1.2.4 → 2.0.0

package/docs/i18n.md

@@ -1,7 +1,7 @@
 # 多语言配置指南
 
-**版本**: v1.0.9  
-**最后更新**: 2026-01-04
+**版本**: v2.0.0-beta.1  
+**最后更新**: 2026-04-30
 
 ---
 
@@ -21,10 +21,22 @@
 
 schema-dsl 支持完整的多语言功能，允许你自定义字段标签和错误消息的翻译。
 
-**v1.0.9 新增**：
+> **Node.js 要求**：`>=18.0.0`
+
+**目录加载（Node >=18）默认支持的语言文件格式**：
+- `.js`（CommonJS 语言包）
+- `.cjs`
+- `.json`
+- `.jsonc`
+- `.json5`
+
+> **推荐**：如果你的应用是 `type: module` / ESM 项目，优先使用 `.cjs`、`.json`、`.jsonc`、`.json5`；`.js` 更适合 CommonJS 语言包文件。
+
+**v2 当前能力**：
 - ✅ 支持参数化语言切换（无需修改全局状态）
 - ✅ 支持自定义错误消息（三种格式）
 - ✅ TypeScript 类型定义完整
+- ✅ 目录递归加载 `.js/.cjs/.json/.jsonc/.json5`
 
 ---
 
@@ -84,7 +96,7 @@ const path = require('path');
 
 // ✅ 方式 1: 从目录加载（推荐）
 dsl.config({
-  i18n: path.join(__dirname, 'i18n/dsl')  // 直接传字符串路径
+  i18n: path.join(__dirname, 'i18n/dsl')  // Node >=18：支持 .js/.cjs/.json/.jsonc/.json5
 });
 
 // ✅ 方式 2: 直接传入对象
@@ -98,20 +110,20 @@ dsl.config({
 
 ### 目录结构
 
-```
+```text
 project/
 ├── i18n/
 │   └── dsl/              # schema-dsl 语言包目录
-│       ├── zh-CN.js      # 中文语言包
-│       ├── en-US.js      # 英文语言包
-│       └── ja-JP.js      # 日语语言包（可选）
+│       ├── zh-CN.cjs     # CommonJS / ESM 项目都稳定
+│       ├── en-US.jsonc   # 带注释/末尾逗号
+│       └── ja-JP.json5   # JSON5 风格（可选）
 ```
 
 ---
 
 ## 📝 语言包格式
 
-### 完整示例 (`i18n/dsl/zh-CN.js`)
+### 完整示例 (`i18n/dsl/zh-CN.cjs`)
 
 ```javascript
 module.exports = {
@@ -190,7 +202,7 @@ dsl.config({
   }
 });
 
-// 默认语言（zh-CN）
+// 默认语言（en-US）
 validate(schema, data);
 
 // 切换到英文
@@ -203,8 +215,8 @@ validate(schema, data, { locale: 'en-US' });
 
 ### 通用错误
 
-| 错误键 | 说明 | 默认消息（zh-CN） |
-|--------|------|-------------------|
+| 错误键 | 说明 | 中文消息示例 |
+|--------|------|--------------|
 | `required` | 必填字段缺失 | {{#label}}是必填项 |
 | `enum` | 枚举值不在范围 | {{#label}}必须是以下值之一: {{#allowed}} |
 | `pattern` | 格式不正确 | {{#label}}格式不正确 |
@@ -260,7 +272,7 @@ validate(schema, data, { locale: 'en-US' });
 | `pattern.idCard` | 身份证格式错误 |
 | `pattern.objectId` | ObjectId格式错误 |
 
-完整列表请参考: `lib/locales/zh-CN.js`
+完整列表请参考: `src/locales/zh-CN.ts`
 
 ---
 
@@ -312,25 +324,25 @@ const schema = dsl({
 
 #### 1. 目录结构
 
-```
+```text
 project/
 ├── i18n/
 │   └── dsl/
-│       ├── zh-CN.js      # 中文
-│       ├── en-US.js      # 英文
-│       ├── ja-JP.js      # 日语
-│       └── index.js      # 导出工具
+│       ├── zh-CN.cjs     # 中文
+│       ├── en-US.jsonc   # 英文
+│       ├── ja-JP.json5   # 日语
+│       └── index.cjs     # 导出工具
 ```
 
-#### 2. 导出工具 (`i18n/dsl/index.js`)
+#### 2. 导出工具 (`i18n/dsl/index.cjs`)
 
 ```javascript
 const path = require('path');
 
 module.exports = {
-  'zh-CN': require('./zh-CN'),
-  'en-US': require('./en-US'),
-  'ja-JP': require('./ja-JP')
+  'zh-CN': require('./zh-CN.cjs'),
+  'en-US': require('./en-US.jsonc'),
+  'ja-JP': require('./ja-JP.json5')
 };
 
 // 使用
@@ -342,14 +354,14 @@ dsl.config({
 #### 3. 消息复用
 
 ```javascript
-// i18n/dsl/common.js
+// i18n/dsl/common.cjs
 module.exports = {
   required: '{{#label}}是必填项',
   minLength: '{{#label}}长度不能少于{{#limit}}个字符'
 };
 
-// i18n/dsl/zh-CN.js
-const common = require('./common');
+// i18n/dsl/zh-CN.cjs
+const common = require('./common.cjs');
 
 module.exports = {
   ...common,
@@ -414,16 +426,16 @@ console.log(result.errors[0].message);
 **检查清单**:
 - ✅ 配置键是否正确（`i18n` 而非 `locales`）
 - ✅ 目录路径是否正确
-- ✅ 文件名是否为语言代码（如 `zh-CN.js`）
-- ✅ 是否使用了 `module.exports`
+- ✅ 文件名是否为语言代码（如 `zh-CN.cjs` / `zh-CN.jsonc`）
+- ✅ `.js` 文件是否为 CommonJS（`module.exports`），若是 ESM 项目优先使用 `.cjs` / `.json*`
 
 ### 2. 错误消息仍然是英文？
 
-**原因**: 默认语言是英文，需要设置语言
+**原因**: 当前请求没有显式传入 `locale`，或全局默认语言尚未切到你期望的语言
 
 ```javascript
 // 方法 1: 全局设置
-const Locale = require('schema-dsl/lib/core/Locale');
+const { Locale } = require('schema-dsl');
 Locale.setLocale('zh-CN');
 
 // 方法 2: 验证时指定
@@ -446,12 +458,19 @@ dsl('string!')
 
 ## 📚 相关文档
 
-- [快速开始](../README.md)
+- [快速开始](https://github.com/vextjs/schema-dsl/blob/main/README.md)
 - [API 参考](./api.md)
-- [完整示例](../examples/i18n-full-demo.js)
+- [完整示例](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/i18n.ts)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [i18n.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/i18n.ts)  
+**说明**: 覆盖内置 locale 切换、字段级消息优先级，以及自定义 locale 的最小工作路径。
 
 ---
 
-**文档生成时间**: 2025-12-31  
+**文档生成时间**: 2026-05-08  
 **版本**: v1.0.1
 

package/docs/index.md

@@ -0,0 +1,48 @@
+---
+pageType: home
+
+hero:
+  name: schema-dsl
+  text: 简洁强大的 JSON Schema 验证库
+  tagline: DSL 语法 · 链式 API · 多格式导出 · 完整 TypeScript 支持
+  actions:
+    - theme: brand
+      text: 快速上手
+      link: /quick-start
+    - theme: alt
+      text: 文档索引
+      link: /doc-index
+    - theme: alt
+      text: GitHub
+      link: https://github.com/vextjs/schema-dsl
+
+features:
+  - title: DSL 语法
+    details: 用紧凑 DSL 字符串或对象定义验证规则，覆盖常见字段、约束与组合场景。
+  - title: 高性能验证
+    details: 基于 AJV 8 封装，支持同步、异步和批量验证，并提供缓存管理能力。
+  - title: 多格式导出
+    details: 同一份 schema 可导出到 MongoDB、MySQL、PostgreSQL 和 Markdown 文档。
+  - title: 国际化
+    details: 内置多语言错误消息与动态 locale 切换，适合服务端和前端共享校验规则。
+  - title: 插件系统
+    details: 支持扩展关键字、格式和类型注册，兼容 v1 常见插件用法。
+  - title: TypeScript 友好
+    details: 提供完整类型声明，便于在现代 Node.js 与 TypeScript 项目中直接集成。
+---
+
+## 入口导航
+
+- 在线文档: https://schema-dsl.github.io
+- 本地文档索引: [doc-index.md](./doc-index.md)
+- 快速开始: [quick-start.md](./quick-start.md)
+- 功能索引: [FEATURE-INDEX.md](./FEATURE-INDEX.md)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [home.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/home.ts)  
+**说明**: 覆盖首页展示的 DSL 定义、便捷验证与编译复用路径，可作为 Batch 1 的总入口样板。
+
+

package/docs/json-schema-basics.md

@@ -0,0 +1,40 @@
+# JSON Schema 基础
+
+schema-dsl 生成的是 JSON Schema Draft 7 风格的对象，并额外保留少量内部字段供验证器使用。
+
+常见字段：
+
+- `type`
+- `properties`
+- `required`
+- `minLength` / `maxLength`
+- `minimum` / `maximum`
+- `format`
+- `enum`
+- `items`
+
+对外输出纯净 JSON Schema 时，请使用 `toJsonSchema()`。
+
+```javascript
+const emailField = dsl('email!').label('邮箱');
+
+emailField.toSchema();
+// 含 _label / _customMessages 等内部字段
+
+emailField.toJsonSchema();
+// 纯净 JSON Schema，适合导出到外部系统
+
+const objectSchema = dsl({
+	email: emailField,
+	age: dsl('number:18-100')
+});
+// dsl({ ... }) 入口直接返回 Draft 7 风格对象
+```
+
+---
+
+## 对应示例文件
+
+**示例入口**: [json-schema-basics.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/json-schema-basics.ts)  
+**说明**: 直接对比 `toSchema()` 与 `toJsonSchema()` 的输出差异，并展示对象入口返回的 JSON Schema 结构。
+

package/docs/label-vs-description.md

@@ -79,19 +79,21 @@ email: 'email!'
 </div>
 ```
 
-**在API文档中**:
+**在导出 / 文档工具中**:
 
 ```json
 {
   "email": {
     "type": "string",
     "format": "email",
-    "title": "邮箱地址",           // 来自 label
+    "_label": "邮箱地址",          // label 在 schema-dsl 内部以 _label 保存
     "description": "用于登录和接收系统通知"  // 来自 description
   }
 }
 ```
 
+`SchemaUtils.toMarkdown()`、导出器或你自己的表单渲染层，通常会再把 `_label` 映射成展示标题。
+
 ---
 
 ## 💡 最佳实践
@@ -257,6 +259,13 @@ apiKey: 'string:32!'
 
 ---
 
-**记住**: label用于错误消息，description用于帮助说明！
+**记住**: label用于错误消息和展示标题来源，description用于帮助说明！
+
+---
+
+## 对应示例文件
+
+**示例入口**: [label-vs-description.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/label-vs-description.ts)  
+**说明**: 直接展示 `_label` / `description` 在 schema 中的实际落点，以及验证错误如何消费 `label`。
 
 

package/docs/markdown-exporter.md

@@ -86,7 +86,7 @@ console.log(markdown);
 - `schema` (Object) - JSON Schema 对象
 - `options` (Object) - 导出选项
   - `title` (String) - 文档标题，默认: `'Schema 文档'`
-  - `locale` (String) - 语言代码，默认: `'zh-CN'`
+  - `locale` (String) - 语言代码，默认: `'en-US'`
     - 支持: `'zh-CN'` (中文), `'en-US'` (英文), `'ja-JP'` (日文)
   - `includeExample` (Boolean) - 是否包含示例数据，默认: `true`
   - `includeDescription` (Boolean) - 是否包含描述，默认: `true`
@@ -306,13 +306,15 @@ const mongoSchema = exporters.MongoDBExporter.export(schema, {
 });
 
 // 导出为 MySQL DDL
-const mysqlDDL = exporters.MySQLExporter.export(schema, {
-  tableName: 'users'
-});
+const mysqlDDL = exporters.MySQLExporter.export('users', schema);
+
+// 导出为 PostgreSQL DDL
+const pgDDL = exporters.PostgreSQLExporter.export('users', schema);
 
 console.log('Markdown 文档:\n', markdown);
 console.log('\nMongoDB Schema:\n', mongoSchema);
 console.log('\nMySQL DDL:\n', mysqlDDL);
+console.log('\nPostgreSQL DDL:\n', pgDDL);
 ```
 
 ---
@@ -392,6 +394,13 @@ console.log('✅ 文档已生成');
 
 ---
 
-**文档更新日期**: 2025-12-29  
-**版本**: v2.2.0
+## 对应示例文件
+
+**示例入口**: [markdown-exporter.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/markdown-exporter.ts)  
+**说明**: 覆盖 `MarkdownExporter.export()` 的中英文文档生成和标题/字段落点检查，适合作为文档导出最小样板。
+
+---
+
+**文档更新日期**: 2026-04-30  
+**版本**: v2.0.0-beta.1
 

package/docs/mongodb-exporter.md

@@ -1,6 +1,6 @@
 # MongoDB 导出器文档
 
-> **模块**: `lib/exporters/MongoDBExporter.js`  
+> **模块**: `src/exporters/MongoDBExporter.ts`  
 
 > **用途**: 将 JSON Schema 转换为 MongoDB 验证 Schema
 
@@ -19,7 +19,7 @@
 
 ## 概述
 
-`MongoDBExporter` 将 SchemaI-DSL 生成的 JSON Schema 转换为 MongoDB 的 `$jsonSchema` 验证格式，可直接用于创建集合时的文档验证。
+`MongoDBExporter` 将 schema-dsl 生成的 JSON Schema 转换为 MongoDB 的 `$jsonSchema` 验证格式，可直接用于创建集合时的文档验证。
 
 ### 核心功能
 
@@ -104,7 +104,7 @@ const mongoSchema = exporter.export(jsonSchema);
 ```
 
 **参数**：
-- `jsonSchema` (Object): SchemaI-DSL 生成的 JSON Schema 对象
+- `jsonSchema` (Object): schema-dsl 生成的 JSON Schema 对象
 
 **返回值**：
 - `Object`: 包含 `$jsonSchema` 的 MongoDB 验证对象
@@ -272,7 +272,7 @@ async function createValidatedCollection() {
 
 ## 导出限制
 
-⚠️ **重要提示**: 并非所有 SchemaI-DSL 特性都能导出到数据库 Schema。
+⚠️ **重要提示**: 并非所有 schema-dsl 特性都能导出到数据库 Schema。
 
 **不支持导出的特性**:
 - ❌ 条件验证逻辑（`dsl.match()`, `dsl.if()`）
@@ -292,4 +292,11 @@ async function createValidatedCollection() {
 - [TypeConverter](type-converter.md)
 - [**导出限制说明**](export-limitations.md) ⚠️
 
+---
+
+## 对应示例文件
+
+**示例入口**: [mongodb-exporter.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/mongodb-exporter.ts)  
+**说明**: 覆盖 `$jsonSchema` 导出、`generateCreateCommand()` 和 `generateCommand()`，对应文档中的验证集合创建场景。
+
 

package/docs/multi-language.md

@@ -0,0 +1,26 @@
+# 多语言支持
+
+多语言能力由 `Locale`、`dsl.config({ i18n })` 和验证选项 `locale` 提供。
+
+常见入口：
+
+- 运行时切换默认语言：`Locale.setLocale('en-US')`
+- 运行时补充语言包：`Locale.addLocale('en-US', messages)`
+- 从目录扫描语言包：`dsl.config({ i18n: '/path/to/locales' })`
+- 单次验证覆盖语言：`validator.validate(schema, data, { locale: 'en-US' })`
+
+当前 i18n 目录扫描支持这些语言包文件：`.js`、`.cjs`、`.json`、`.jsonc`、`.json5`。
+
+更多内容请见：
+
+- [i18n.md](./i18n.md)
+- [i18n-user-guide.md](./i18n-user-guide.md)
+- [dynamic-locale.md](./dynamic-locale.md)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [multi-language.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/multi-language.ts)  
+**说明**: 展示默认语言、按次覆盖 `locale` 以及可用语言列表的最小运行时示例。
+

package/docs/multi-type-support.md

@@ -5,7 +5,7 @@
 ## 📖 快速导航
 
 - **单一类型验证**（本文档）
-- **[联合类型验证](./union-type-guide.md)** - 一个字段支持多种类型（使用 `.pattern()` 正则匹配）
+- **[联合类型验证](./union-types.md)** - 使用 `types:` 语法做真正的跨类型联合验证
 
 ---
 
@@ -216,46 +216,32 @@ const schema = dsl({
 
 ## 🚀 扩展新类型
 
-如果需要添加新类型支持：
+当前版本优先通过公开运行时 API 扩展类型，而不是要求业务方修改内部 `DslAdapter` / `ErrorCodes` 源码。
 
-### 1. 在DslAdapter中添加解析规则
+### 推荐入口
 
 ```javascript
-// lib/adapters/DslAdapter.js
-
-_parseType(dslString) {
-  // 添加新类型
-  if (dslString === 'phone') {
-    return {
-      type: 'string',
-      pattern: '^1[3-9]\\d{9}$',
-      minLength: 11,
-      maxLength: 11
-    };
-  }
-  
-  // 现有类型...
-}
-```
+const { DslBuilder, TypeRegistry } = require('schema-dsl');
 
-### 2. 在ErrorCodes中添加错误消息
-
-```javascript
-// lib/core/ErrorCodes.js
+TypeRegistry.register('evenNumber', {
+  baseSchema: { type: 'number', multipleOf: 2 }
+});
 
-ERROR_CODES.phone = {
-  code: 'INVALID_PHONE',
-  message: '{{#label}} must be a valid phone number',
-  zhCN: '{{#label}}必须是有效的手机号'
-};
+DslBuilder.registerType('phone-cn-lite', {
+  type: 'string',
+  pattern: '^1[3-9]\\d{9}$',
+  minLength: 11,
+  maxLength: 11
+});
 ```
 
-### 3. 在文档中说明
+### 使用方式
 
 ```javascript
-// 使用新类型
-phone: 'phone!'           // 中国手机号
-phone: 'phone!'.label('手机号')
+const schema = dsl({
+  phone: 'phone-cn-lite!',
+  luckyNumber: 'evenNumber'
+});
 ```
 
 ---
@@ -317,7 +303,7 @@ amount: 'number:0-10000'
 
 ## 💡 总结
 
-SchemaI-DSL的多类型支持采用**类型无关Builder + 方法智能适配**设计：
+schema-dsl 的多类型支持采用**类型无关 Builder + 方法智能适配**设计：
 
 1. **统一入口**: 所有类型都通过DslBuilder
 2. **类型感知**: 方法内部检查类型兼容性
@@ -326,4 +312,11 @@ SchemaI-DSL的多类型支持采用**类型无关Builder + 方法智能适配**
 
 **设计哲学**: 让最常见的场景（字符串验证）最简洁，其他类型保持DSL的简洁性。
 
+---
+
+## 对应示例文件
+
+**示例入口**: [multi-type-support.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/multi-type-support.ts)  
+**说明**: 用一个对象同时覆盖字符串、数字、布尔、日期、数组和枚举字段的推荐写法，以及对应的成功 / 失败验证路径。
+
 

package/docs/mysql-exporter.md

@@ -1,6 +1,6 @@
 # MySQL 导出器文档
 
-> **模块**: `lib/exporters/MySQLExporter.js`  
+> **模块**: `src/exporters/MySQLExporter.ts`  
 
 > **用途**: 将 JSON Schema 转换为 MySQL CREATE TABLE 语句
 
@@ -19,7 +19,7 @@
 
 ## 概述
 
-`MySQLExporter` 将 SchemaI-DSL 生成的 JSON Schema 转换为 MySQL 的 DDL 语句，包括 `CREATE TABLE` 和索引创建语句。
+`MySQLExporter` 将 schema-dsl 生成的 JSON Schema 转换为 MySQL 的 DDL 语句，包括 `CREATE TABLE` 和索引创建语句。
 
 ### 核心功能
 
@@ -271,3 +271,10 @@ CREATE INDEX `idx_users_status` ON `users` (`status`);
 - [TypeConverter](type-converter.md)
 - [**导出限制说明**](export-limitations.md) ⚠️
 
+---
+
+## 对应示例文件
+
+**示例入口**: [mysql-exporter.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/mysql-exporter.ts)  
+**说明**: 覆盖 `export()` 生成 DDL、主键检测，以及 `generateIndex()` 生成普通/唯一索引。
+

package/docs/number-operators.md

@@ -430,13 +430,20 @@ dsl({ level: 'number:=5' })    // 等于
 
 ## 📚 相关文档
 
-- [DSL 语法速查](../README.md#-dsl-语法速查)
-- [完整示例](../examples/number-operators.examples.js)
-- [测试用例](../test/unit/number-operators.test.js)
-- [CHANGELOG](../CHANGELOG.md)
+- [DSL 语法速查](./dsl-syntax.md)
+- [完整示例](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/number-operators.ts)
+- [测试用例](../test/unit/number-operators.test.ts)
+- [CHANGELOG](https://github.com/vextjs/schema-dsl/blob/main/CHANGELOG.md)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [number-operators.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/number-operators.ts)  
+**说明**: 覆盖 `>=`、`<`、`<=`、`=` 和整数比较运算符的成功/失败路径，便于直接观察边界行为。
 
 ---
 
 **版本**: v1.1.2+  
-**更新时间**: 2026-01-06
+**更新时间**: 2026-05-08
 

package/docs/optional-marker-guide.md

@@ -13,9 +13,9 @@ schema-dsl 现在支持使用 `?` 显式标记可选字段，提供更清晰的
 
 | 标记 | 含义 | 示例 | 说明 |
 |------|------|------|------|
-| `!` | 必填 | `string!` | 字段不能为空 |
-| `?` | 可选 | `string?` | 字段可以为空（显式表达） |
-| 无标记 | 可选（默认） | `string` | 字段可以为空（默认行为） |
+| `!` | 必填 | `string!` | 字段必须存在 |
+| `?` | 可选 | `string?` | 字段可省略（显式表达） |
+| 无标记 | 可选（默认） | `string` | 字段可省略（默认行为） |
 
 ---
 
@@ -207,7 +207,7 @@ const schema3 = dsl({
 - ✅ **email?** - 支持
 - ✅ **number:18-?** - 支持
 - ✅ **array<string>?** - 支持
-- ✅ **所有单元测试通过** - 949/949
+- ✅ **相关单元测试已覆盖**
 
 ### 测试代码
 
@@ -236,28 +236,26 @@ console.log(validate(schema3, { username: 'test' }).valid); // true
 
 ## 🔧 实现细节
 
-### DslBuilder 构造函数
+### DslParser / DslBuilder 标记处理
 
 ```javascript
-constructor(dslString) {
-  // ...
-  
-  // 🔴 处理必填标记 ! 和可选标记 ?
-  // 优先级：! > ?（如果同时存在，! 优先）
-  this._required = processedDsl.endsWith('!');
-  this._optional = processedDsl.endsWith('?') && !this._required;
-  
-  let dslWithoutMarker = processedDsl;
-  if (this._required) {
-    dslWithoutMarker = processedDsl.slice(0, -1);
-  } else if (this._optional) {
-    dslWithoutMarker = processedDsl.slice(0, -1);
-  }
-  
-  // ...
+// DslParser.parseString()
+if (s.endsWith('!')) {
+  required = true;
+  s = s.slice(0, -1);
+} else if (s.endsWith('?')) {
+  s = s.slice(0, -1);
+}
+
+// DslBuilder constructor（兼容链式入口）
+this._required = s.endsWith('!');
+this._optional = s.endsWith('?') && !this._required;
+if (this._required || this._optional) s = s.slice(0, -1);
 }
 ```
 
+当前版本会在 `DslParser.parseString()` 中统一剥离末尾 `!` / `?`，同时 `DslBuilder` 构造函数保留相同的兼容处理，因此字符串 DSL 和链式 Builder 两条入口都能识别可选标记。
+
 ---
 
 ## 📝 最佳实践
@@ -311,11 +309,18 @@ const schema = dsl({
 ## 📚 相关文档
 
 - [DSL 语法完整指南](./dsl-syntax.md)
-- [TypeScript 类型定义](../index.d.ts)
-- [单元测试](../test/unit/dsl-adapter.test.js)
+- [类型参考](./type-reference.md)
+- [跨类型联合验证](./union-types.md)
 
 ---
 
 **最后更新**: 2026-01-13  
 **作者**: schema-dsl Team
 
+---
+
+## 对应示例文件
+
+**示例入口**: [optional-marker-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/optional-marker-guide.ts)  
+**说明**: 覆盖 `!` / `?` 的基础字段、对象字段和默认可选枚举场景，直接展示成功 / 失败路径。
+