You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2025/12/15 15:45:26 UTC
(fory-site) branch main updated: Release 0.14.0 (#369)
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new bfd1497c1 Release 0.14.0 (#369)
bfd1497c1 is described below
commit bfd1497c11760df42222b710137f03eed616fc7b
Author: Shawn Yang <sh...@gmail.com>
AuthorDate: Mon Dec 15 23:45:21 2025 +0800
Release 0.14.0 (#369)
---
blog/2025-12-15-fory_0_14_0_release.md | 193 +++
docs/docs/guide/java/compression.md | 2 +-
docs/docs/guide/kotlin/index.md | 4 +-
docs/docs/guide/scala/index.md | 2 +-
docs/docs/guide/xlang/getting-started.md | 4 +-
docs/docs/introduction/benchmark.md | 6 +
docs/docs/start/install.md | 16 +-
.../current/docs/start/install.md | 16 +-
.../version-0.14/community/community.md | 85 +
.../community/how_to_join_community.md | 108 ++
.../version-0.14/community/how_to_release.md | 422 +++++
.../version-0.14/community/how_to_verify.md | 119 ++
.../version-0.14/docs/guide/DEVELOPMENT.md | 146 ++
.../version-0.14/docs/guide/_category_.json | 4 +
.../version-0.14/docs/guide/cpp/_category_.json | 6 +
.../docs/guide/cpp/basic-serialization.md | 238 +++
.../version-0.14/docs/guide/cpp/configuration.md | 189 +++
.../version-0.14/docs/guide/cpp/cross-language.md | 271 ++++
.../version-0.14/docs/guide/cpp/index.md | 245 +++
.../version-0.14/docs/guide/cpp/row-format.md | 516 ++++++
.../docs/guide/cpp/schema-evolution.md | 404 +++++
.../version-0.14/docs/guide/cpp/supported-types.md | 277 ++++
.../docs/guide/cpp/type-registration.md | 225 +++
.../version-0.14/docs/guide/graalvm_guide.md | 318 ++++
.../version-0.14/docs/guide/java/_category_.json | 6 +
.../docs/guide/java/advanced-features.md | 208 +++
.../docs/guide/java/basic-serialization.md | 137 ++
.../version-0.14/docs/guide/java/compression.md | 136 ++
.../version-0.14/docs/guide/java/configuration.md | 77 +
.../version-0.14/docs/guide/java/cross-language.md | 231 +++
.../docs/guide/java/custom-serializers.md | 659 ++++++++
.../version-0.14/docs/guide/java/index.md | 193 +++
.../version-0.14/docs/guide/java/migration.md | 120 ++
.../version-0.14/docs/guide/java/row-format.md | 183 +++
.../docs/guide/java/schema-evolution.md | 215 +++
.../docs/guide/java/troubleshooting.md | 213 +++
.../docs/guide/java/type-registration.md | 112 ++
.../version-0.14/docs/guide/kotlin/_category_.json | 6 +
.../docs/guide/kotlin/default-values.md | 137 ++
.../docs/guide/kotlin/fory-creation.md | 116 ++
.../version-0.14/docs/guide/kotlin/index.md | 108 ++
.../docs/guide/kotlin/type-serialization.md | 184 +++
.../version-0.14/docs/guide/python/_category_.json | 6 +
.../docs/guide/python/basic-serialization.md | 145 ++
.../docs/guide/python/configuration.md | 181 +++
.../docs/guide/python/cross-language.md | 140 ++
.../docs/guide/python/custom-serializers.md | 146 ++
.../version-0.14/docs/guide/python/index.md | 160 ++
.../version-0.14/docs/guide/python/migration.md | 85 +
.../docs/guide/python/numpy-integration.md | 103 ++
.../version-0.14/docs/guide/python/out-of-band.md | 179 +++
.../docs/guide/python/python-native.md | 205 +++
.../version-0.14/docs/guide/python/row-format.md | 169 ++
.../docs/guide/python/schema-evolution.md | 77 +
.../version-0.14/docs/guide/python/security.md | 150 ++
.../docs/guide/python/troubleshooting.md | 186 +++
.../docs/guide/python/type-registration.md | 146 ++
.../version-0.14/docs/guide/rust/_category_.json | 6 +
.../docs/guide/rust/basic-serialization.md | 166 ++
.../version-0.14/docs/guide/rust/configuration.md | 125 ++
.../version-0.14/docs/guide/rust/cross-language.md | 165 ++
.../docs/guide/rust/custom-serializers.md | 147 ++
.../version-0.14/docs/guide/rust/index.md | 184 +++
.../version-0.14/docs/guide/rust/polymorphism.md | 232 +++
.../version-0.14/docs/guide/rust/references.md | 213 +++
.../version-0.14/docs/guide/rust/row-format.md | 126 ++
.../docs/guide/rust/schema-evolution.md | 204 +++
.../docs/guide/rust/troubleshooting.md | 164 ++
.../docs/guide/rust/type-registration.md | 126 ++
.../version-0.14/docs/guide/scala/_category_.json | 6 +
.../docs/guide/scala/default-values.md | 186 +++
.../version-0.14/docs/guide/scala/fory-creation.md | 139 ++
.../version-0.14/docs/guide/scala/index.md | 100 ++
.../docs/guide/scala/type-serialization.md | 171 ++
.../version-0.14/docs/guide/xlang/_category_.json | 6 +
.../docs/guide/xlang/getting-started.md | 96 +-
.../version-0.14/docs/guide/xlang/index.md | 125 ++
.../version-0.14/docs/guide/xlang/row_format.md | 190 +++
.../version-0.14/docs/guide/xlang/serialization.md | 542 +++++++
.../docs/guide/xlang/troubleshooting.md | 321 ++++
.../version-0.14/docs/guide/xlang/zero-copy.md | 207 +++
.../version-0.14/docs/introduction/_category_.json | 4 +
.../version-0.14/docs/introduction/benchmark.md | 48 +
.../version-0.14/docs/introduction/features.md | 21 +
.../version-0.14/docs/introduction/introduction.md | 56 +
.../version-0.14/docs/start/_category_.json | 4 +
.../docs/start/install.md | 16 +-
.../version-0.14/docs/start/usage.md | 236 +++
public/benchmarks/cpp/throughput_comparison.png | Bin 0 -> 52517 bytes
src/pages/download/index.md | 10 +-
versioned_docs/version-0.14/community/community.md | 90 ++
.../community/how_to_join_community.md | 105 ++
.../version-0.14/community/how_to_release.md | 635 ++++++++
.../version-0.14/community/how_to_verify.md | 125 ++
.../version-0.14/docs/guide/DEVELOPMENT.md | 146 ++
.../version-0.14/docs/guide/_category_.json | 4 +
.../version-0.14/docs/guide/cpp/_category_.json | 6 +
.../docs/guide/cpp/basic-serialization.md | 238 +++
.../version-0.14/docs/guide/cpp/configuration.md | 189 +++
.../version-0.14/docs/guide/cpp/cross-language.md | 271 ++++
.../version-0.14/docs/guide/cpp/index.md | 245 +++
.../version-0.14/docs/guide/cpp/row-format.md | 516 ++++++
.../docs/guide/cpp/schema-evolution.md | 404 +++++
.../version-0.14/docs/guide/cpp/supported-types.md | 277 ++++
.../docs/guide/cpp/type-registration.md | 225 +++
.../version-0.14/docs/guide/graalvm_guide.md | 318 ++++
.../version-0.14/docs/guide/java/_category_.json | 6 +
.../docs/guide/java/advanced-features.md | 209 +++
.../docs/guide/java/basic-serialization.md | 137 ++
.../version-0.14}/docs/guide/java/compression.md | 2 +-
.../version-0.14/docs/guide/java/configuration.md | 77 +
.../version-0.14/docs/guide/java/cross-language.md | 231 +++
.../docs/guide/java/custom-serializers.md | 659 ++++++++
.../version-0.14/docs/guide/java/index.md | 195 +++
.../version-0.14/docs/guide/java/migration.md | 120 ++
.../version-0.14/docs/guide/java/row-format.md | 183 +++
.../docs/guide/java/schema-evolution.md | 215 +++
.../docs/guide/java/troubleshooting.md | 213 +++
.../docs/guide/java/type-registration.md | 112 ++
.../version-0.14/docs/guide/kotlin/_category_.json | 6 +
.../docs/guide/kotlin/default-values.md | 137 ++
.../docs/guide/kotlin/fory-creation.md | 116 ++
.../version-0.14}/docs/guide/kotlin/index.md | 4 +-
.../docs/guide/kotlin/type-serialization.md | 184 +++
.../version-0.14/docs/guide/python/_category_.json | 6 +
.../docs/guide/python/basic-serialization.md | 145 ++
.../docs/guide/python/configuration.md | 181 +++
.../docs/guide/python/cross-language.md | 140 ++
.../docs/guide/python/custom-serializers.md | 146 ++
.../version-0.14/docs/guide/python/index.md | 160 ++
.../version-0.14/docs/guide/python/migration.md | 85 +
.../docs/guide/python/numpy-integration.md | 103 ++
.../version-0.14/docs/guide/python/out-of-band.md | 179 +++
.../docs/guide/python/python-native.md | 205 +++
.../version-0.14/docs/guide/python/row-format.md | 169 ++
.../docs/guide/python/schema-evolution.md | 77 +
.../version-0.14/docs/guide/python/security.md | 150 ++
.../docs/guide/python/troubleshooting.md | 186 +++
.../docs/guide/python/type-registration.md | 146 ++
.../version-0.14/docs/guide/rust/_category_.json | 6 +
.../docs/guide/rust/basic-serialization.md | 166 ++
.../version-0.14/docs/guide/rust/configuration.md | 125 ++
.../version-0.14/docs/guide/rust/cross-language.md | 165 ++
.../docs/guide/rust/custom-serializers.md | 147 ++
.../version-0.14/docs/guide/rust/index.md | 184 +++
.../version-0.14/docs/guide/rust/polymorphism.md | 232 +++
.../version-0.14/docs/guide/rust/references.md | 213 +++
.../version-0.14/docs/guide/rust/row-format.md | 126 ++
.../docs/guide/rust/schema-evolution.md | 204 +++
.../docs/guide/rust/troubleshooting.md | 164 ++
.../docs/guide/rust/type-registration.md | 126 ++
.../version-0.14/docs/guide/scala/_category_.json | 6 +
.../docs/guide/scala/default-values.md | 186 +++
.../version-0.14/docs/guide/scala/fory-creation.md | 139 ++
.../version-0.14}/docs/guide/scala/index.md | 2 +-
.../docs/guide/scala/type-serialization.md | 171 ++
.../version-0.14/docs/guide/xlang/_category_.json | 6 +
.../docs/guide/xlang/getting-started.md | 4 +-
.../version-0.14/docs/guide/xlang/index.md | 125 ++
.../version-0.14/docs/guide/xlang/row_format.md | 190 +++
.../version-0.14/docs/guide/xlang/serialization.md | 542 +++++++
.../docs/guide/xlang/troubleshooting.md | 321 ++++
.../version-0.14/docs/guide/xlang/zero-copy.md | 207 +++
.../version-0.14/docs/introduction/_category_.json | 4 +
.../version-0.14}/docs/introduction/benchmark.md | 6 +
.../version-0.14/docs/introduction/features.md | 230 +++
.../version-0.14/docs/introduction/introduction.md | 150 ++
.../version-0.14/docs/start/_category_.json | 4 +
.../version-0.14}/docs/start/install.md | 16 +-
versioned_docs/version-0.14/docs/start/usage.md | 343 ++++
.../specification/java_serialization_spec.md | 560 +++++++
.../version-0.14/specification/row_format_spec.md | 540 +++++++
.../specification/xlang_serialization_spec.md | 1650 ++++++++++++++++++++
.../specification/xlang_type_mapping.md | 116 ++
versioned_sidebars/version-0.14-sidebars.json | 20 +
versions.json | 1 +
176 files changed, 29255 insertions(+), 97 deletions(-)
diff --git a/blog/2025-12-15-fory_0_14_0_release.md b/blog/2025-12-15-fory_0_14_0_release.md
new file mode 100644
index 000000000..9cf87887d
--- /dev/null
+++ b/blog/2025-12-15-fory_0_14_0_release.md
@@ -0,0 +1,193 @@
+---
+slug: fory_0_14_0_release
+title: Fory v0.14.0 Released
+authors: [chaokunyang]
+tags: [fory, c++, rust, java, python]
+---
+
+The Apache Fory team is pleased to announce the 0.14.0 release. This is a major release that includes [85 PR](https://github.com/apache/fory/compare/v0.13.2...v0.14.0) from 11 distinct contributors. See the [Install](https://fory.apache.org/docs/start/install) Page to learn how to get the libraries for your platform.
+
+## Highlights
+
+- **Official C++ Support**: First release of Apache Fory C++ with high-performance object graph serialization, cross-language interoperability, and schema evolution
+- **Row Format & Type System**: New row-oriented format type system across Java, Python, and C++, enabling row-columnar conversions and removing Arrow dependencies
+- **Performance Enhancements**: Significant optimizations across all languages, including thread-local context in Rust and fast flat-int maps for C++ type dispatch
+- **Ecosystem Updates**: Added support for JDK 25 (Java), Go 1.23, and Bazel 8. Python officially marked as stable with improved build parallelism
+- **Advanced Java Features**: GraalVM Native Image support via `ForyFeature` and optimized serializers for blocking queues and final fields
+- **ObjectStreamSerializer Refactoring**: Refactored `ObjectStreamSerializer` with meta-shared compatible mode for reduced space cost and improved performance on JDK customized serialization APIs
+
+## C++: First Release Highlights
+
+This is the first Apache Fory C++ release, delivering a complete, high-performance serialization framework for modern C++17. If you build C++ applications requiring fast serialization, cross-language communication, or schema evolution, Fory C++ provides type-safe, compile-time serialization with minimal overhead.
+
+**Key capabilities:**
+
+- Macro-based struct registration via `FORY_STRUCT` for compile-time type safety
+- Cross-language serialization with Java, Python, Go, Rust, and JavaScript
+- Forward/backward compatible schema evolution (Compatible mode)
+- Reference tracking for shared objects and circular references
+- Thread-safe and single-threaded (fastest) variants
+- Comprehensive type support: primitives, `std::string`, `std::vector`, `std::map`, `std::set`, `std::optional`, `std::shared_ptr`, `std::unique_ptr`, `std::variant`, and temporal types
+- Zero-copy Row format for analytics workloads with random field access
+- CMake (FetchContent) and Bazel build system support
+
+### Quick Start
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+struct Person {
+ std::string name;
+ int32_t age;
+ std::vector<std::string> hobbies;
+ FORY_STRUCT(Person, name, age, hobbies);
+};
+
+int main() {
+ auto fory = Fory::builder()
+ .xlang(true) // Enable cross-language mode
+ .track_ref(false) // Disable ref tracking for simple types
+ .build();
+ fory.register_struct<Person>(1);
+
+ Person person{"Alice", 30, {"reading", "coding"}};
+ auto bytes = fory.serialize(person).value();
+ Person decoded = fory.deserialize<Person>(bytes).value();
+ // person == decoded
+ return 0;
+}
+```
+
+- Guide: C++ Serialization – https://fory.apache.org/docs/docs/guide/cpp/
+- Examples: [hello_world](https://github.com/apache/fory/tree/main/examples/cpp/hello_world), [hello_row](https://github.com/apache/fory/tree/main/examples/cpp/hello_row)
+
+### C++ Benchmarks
+
+<img src="/img/benchmarks/cpp/throughput_comparison.png" width="90%"/>
+
+Below are timing results (nanoseconds; lower is better) comparing Fory with Protobuf across different data structures.
+
+| Datatype | Operation | Fory (ns) | Protobuf (ns) | Faster |
+| ------------ | ----------- | --------- | ------------- | ----------- |
+| MediaContent | Serialize | 414 | 2,046 | Fory (4.9x) |
+| MediaContent | Deserialize | 1,361 | 2,890 | Fory (2.1x) |
+| Sample | Serialize | 210 | 307 | Fory (1.5x) |
+| Sample | Deserialize | 1,061 | 1,500 | Fory (1.4x) |
+| Struct | Serialize | 51 | 181 | Fory (3.5x) |
+| Struct | Deserialize | 136 | 170 | Fory (1.3x) |
+
+Note: Results depend on hardware and implementation versions. See the C++ benchmark guide for how to run benchmarks yourself: https://github.com/apache/fory/tree/main/benchmarks/cpp_benchmark
+
+## Features
+
+- feat(python): add raw method to buffer object by @chaokunyang in https://github.com/apache/fory/pull/2875
+- feat(rust): add duration serializer support by @chaokunyang in https://github.com/apache/fory/pull/2878
+- feat(rust): add typename to unregistered error message by @chaokunyang in https://github.com/apache/fory/pull/2881
+- perf(rust): support criterion profiler to generate flamegraph by @chaokunyang in https://github.com/apache/fory/pull/2882
+- refactor(rust): merge fory_debug into fory macro attr by @chaokunyang in https://github.com/apache/fory/pull/2883
+- feat(rust): direct derive primitve write/read by @chaokunyang in https://github.com/apache/fory/pull/2890
+- perf(rust): optimize buffer write read perf by @chaokunyang in https://github.com/apache/fory/pull/2892
+- feat(Rust): Support u128 & u128_array by @urlyy in https://github.com/apache/fory/pull/2899
+- feat(c++): implement fory cpp object graph serialization framework by @chaokunyang in https://github.com/apache/fory/pull/2908
+- feat(python): pure python row-columar convert by @chaokunyang in https://github.com/apache/fory/pull/2919
+- feat(c++): implement xlang serialization for c++ by @chaokunyang in https://github.com/apache/fory/pull/2925
+- feat(c++/python): add row format schema and remove arrow dependency by @chaokunyang in https://github.com/apache/fory/pull/2928
+- feat(java): implement fory row format type system by @chaokunyang in https://github.com/apache/fory/pull/2931
+- feat(python): implement cython bazel build directly without 3rd deps by @chaokunyang in https://github.com/apache/fory/pull/2936
+- feat(c+/python): upgrade bazel to bazel8 by @chaokunyang in https://github.com/apache/fory/pull/2937
+- feat(java/python/c++): add schema encoder and remove arrow serializers by @chaokunyang in https://github.com/apache/fory/pull/2938
+- feat(c++): check max dyn depth when deserializing polymorphic types by @chaokunyang in https://github.com/apache/fory/pull/2939
+- feat(c++): add cmake build support and add cpp examples by @chaokunyang in https://github.com/apache/fory/pull/2942
+- feat(c++ ): add cpp benchmark by @chaokunyang in https://github.com/apache/fory/pull/2943
+- perf(rust): use segmented pool to reduce contention of fory pool by @chaokunyang in https://github.com/apache/fory/pull/2945
+- perf(rust): use thread local to manage fory rust WriteContext/ReadContext by @chaokunyang in https://github.com/apache/fory/pull/2946
+- feat(rust): add fory config for rust by @chaokunyang in https://github.com/apache/fory/pull/2947
+- perf(c++): optimize cpp serialization performance by @chaokunyang in https://github.com/apache/fory/pull/2944
+- perf(c++): remove shared_ptr from type info to reduce atomic counter cost by @chaokunyang in https://github.com/apache/fory/pull/2951
+- feat: refine python module check by @chaokunyang in https://github.com/apache/fory/pull/2952
+- feat(java): support jdk 25 by @chaokunyang in https://github.com/apache/fory/pull/2954
+- feat(java): add optimized serializers for blocking queues by @zhan7236 in https://github.com/apache/fory/pull/2955
+- perf(c++): directly error set instead of result to reduce cost on hotpath by @chaokunyang in https://github.com/apache/fory/pull/2959
+- perf(c++): optimize primitive struct fields read performance by @chaokunyang in https://github.com/apache/fory/pull/2960
+- feat(java): implement FinalFieldReplaceResolveSerializer for final fields with writeReplace/readResolve methods by @mchernyakov in https://github.com/apache/fory/pull/2917
+- perf(c++): add mac profile script for c++ by @chaokunyang in https://github.com/apache/fory/pull/2962
+- perf(c++): fair benchmark for cpp by @chaokunyang in https://github.com/apache/fory/pull/2963
+- perf(c++): optimize type dispatch performance by a fast flat-int map by @chaokunyang in https://github.com/apache/fory/pull/2966
+- perf(c++): add media content benchmark by @chaokunyang in https://github.com/apache/fory/pull/2968
+- feat(c++): support polymorphic collection elements serialization by @chaokunyang in https://github.com/apache/fory/pull/2974
+- feat(c++): add cpp tuple serializer by @chaokunyang in https://github.com/apache/fory/pull/2975
+- refactor(xlang): use 0 for unknow type id by @chaokunyang in https://github.com/apache/fory/pull/2985
+- feat(java): Add ForyFeature for GraalVM Native Image by @mengnankkkk in https://github.com/apache/fory/pull/2701
+- feat(c++): support container xlang serialization with polymorphic elements by @chaokunyang in https://github.com/apache/fory/pull/2980
+- feat(python): parallel python wheel build by @chaokunyang in https://github.com/apache/fory/pull/2989
+- perf(c++): improve the serialization performance of array/collection by @LiangliangSui in https://github.com/apache/fory/pull/2986
+- feat(go): upgrade go to to 1.23 by @chaokunyang in https://github.com/apache/fory/pull/2995
+- perf(c++): centralize error state in context for faster serialization by @chaokunyang in https://github.com/apache/fory/pull/3009
+- refactor(go): redesign serialization implementation with performance and usability improvements by @chaokunyang in https://github.com/apache/fory/pull/2998
+- refactor(rust): merge rust type layer into TypeMeta by @chaokunyang in https://github.com/apache/fory/pull/3019
+- ci: remove macos x86 CI for Python by @chaokunyang in https://github.com/apache/fory/pull/3023
+- feat(c++): support unsigned type for cpp by @chaokunyang in https://github.com/apache/fory/pull/3022
+- feat(c++): support variant-based union type serialization for c++ by @chaokunyang in https://github.com/apache/fory/pull/3032
+- feat(java): refactor ObjectStreamSerializer to use meta shared compatible serializer by @chaokunyang in https://github.com/apache/fory/pull/3034
+- feat(java): separate user register type id with fory registered type id by @chaokunyang in https://github.com/apache/fory/pull/3035
+- feat(): add c++ user guide doc by @chaokunyang in https://github.com/apache/fory/pull/3037
+- refactor(c++/rust): refine c++ serialize_to API by @chaokunyang in https://github.com/apache/fory/pull/3045
+
+## Bug Fix
+
+- fix(Rust): fix Binary implementation by @urlyy in https://github.com/apache/fory/pull/2902
+- fix(rust): fix array field support by @chaokunyang in https://github.com/apache/fory/pull/2933
+- fix(rust): raise error for nested polymorphics for collection by @chaokunyang in https://github.com/apache/fory/pull/2934
+- fix(kotlin): support Kotlin field with Java reserved world by @chaokunyang in https://github.com/apache/fory/pull/2948
+- fix(java): handle TypeVariable in row format type inference by @chaokunyang in https://github.com/apache/fory/pull/2949
+- fix(java): use single quotes in Python command for Windows compatibility by @zhan7236 in https://github.com/apache/fory/pull/2953
+- fix(java): fix race condition in blocking queue serializers by @zhan7236 in https://github.com/apache/fory/pull/2956
+- fix(cpp): fix the type error by @LiangliangSui in https://github.com/apache/fory/pull/2961
+- fix(go): fix struct value reference tracking bug by @chaokunyang in https://github.com/apache/fory/pull/2991
+- fix(java): support serialization of CopyOnWriteArraySet by @LiangliangSui in https://github.com/apache/fory/pull/2999
+
+## Other Improvements
+
+- docs: fix broken table in in java_serialization_guide.md by @mosinnik in https://github.com/apache/fory/pull/2876
+- chore(rust): fix tuple test comment by @chaokunyang in https://github.com/apache/fory/pull/2877
+- docs(rust): remove redundant doc for shared reference by @chaokunyang in https://github.com/apache/fory/pull/2879
+- chore(Java): Update java quickstart doc, for note register order-sensitive by @moooonk in https://github.com/apache/fory/pull/2837
+- chore(CI): Add caching for bazel in github workflows by @prakash-218 in https://github.com/apache/fory/pull/2888
+- chore(CI): Fix cache with symlinks by @prakash-218 in https://github.com/apache/fory/pull/2893
+- chore: move benchmarks to separate dir to speed up ci build by @chaokunyang in https://github.com/apache/fory/pull/2894
+- docs: fix rust benchmark links by @chaokunyang in https://github.com/apache/fory/pull/2896
+- docs: fix cargo benchmark comand in doc by @chaokunyang in https://github.com/apache/fory/pull/2897
+- chore: bump release version to 0.13.1 by @chaokunyang in https://github.com/apache/fory/pull/2901
+- docs(java): add logging section by @mosinnik in https://github.com/apache/fory/pull/2905
+- chore(c++): remove cpp benchmarks by @chaokunyang in https://github.com/apache/fory/pull/2926
+- chore(c++): move meta string to meta dir by @chaokunyang in https://github.com/apache/fory/pull/2940
+- docs: remove unused type mappings for arrow types by @chaokunyang in https://github.com/apache/fory/pull/2964
+- chore: Remove the content related to arrow. by @LiangliangSui in https://github.com/apache/fory/pull/2965
+- chore(c++): move common macro into macros.h by @chaokunyang in https://github.com/apache/fory/pull/2970
+- docs: Update Bazel version in README.md by @chaokunyang in https://github.com/apache/fory/pull/2971
+- docs: refine xlang spec documentation by @chaokunyang in https://github.com/apache/fory/pull/2979
+- docs: Refine metadata packing and automatic type mapping by @chaokunyang in https://github.com/apache/fory/pull/2984
+- ci: add workflow to remove HTML comments from PR body by @chaokunyang in https://github.com/apache/fory/pull/2983
+- docs: Update xlang_serialization_spec.md by @chaokunyang in https://github.com/apache/fory/pull/2987
+- docs: update the C++ benchmark case by @LiangliangSui in https://github.com/apache/fory/pull/2988
+- chore(deps): bump gopkg.in/yaml.v3 from 3.0.0-20200313102051-9f266ea9e77c to 3.0.1 in /go/fory by @dependabot[bot] in https://github.com/apache/fory/pull/2996
+- chore: bump release version to 0.13.2 by @chaokunyang in https://github.com/apache/fory/pull/2997
+- chore(python): mark pyfory as stable by @chaokunyang in https://github.com/apache/fory/pull/3001
+- docs(c++): add cpp bazel example and add ci by @chaokunyang in https://github.com/apache/fory/pull/3033
+- docs: refactor user guide docs by @chaokunyang in https://github.com/apache/fory/pull/3036
+- docs: add scala and kotlin docs by @chaokunyang in https://github.com/apache/fory/pull/3040
+- docs: refactor xlang docs by @chaokunyang in https://github.com/apache/fory/pull/3041
+- docs: add row format spec by @chaokunyang in https://github.com/apache/fory/pull/3042
+- docs: fix sidebar position by @chaokunyang in https://github.com/apache/fory/pull/3043
+- docs: remove copy rust/python docs by @chaokunyang in https://github.com/apache/fory/pull/3044
+
+## New Contributors
+
+- @mosinnik made their first contribution in https://github.com/apache/fory/pull/2876
+- @prakash-218 made their first contribution in https://github.com/apache/fory/pull/2888
+- @zhan7236 made their first contribution in https://github.com/apache/fory/pull/2953
+- @mchernyakov made their first contribution in https://github.com/apache/fory/pull/2917
+
+**Full Changelog**: https://github.com/apache/fory/compare/v0.13.2...v0.14.0
diff --git a/docs/docs/guide/java/compression.md b/docs/docs/guide/java/compression.md
index c08a9cad8..852c69d0c 100644
--- a/docs/docs/guide/java/compression.md
+++ b/docs/docs/guide/java/compression.md
@@ -84,7 +84,7 @@ CompressedArraySerializers.registerSerializers(fory);
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-simd</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
diff --git a/docs/docs/guide/kotlin/index.md b/docs/docs/guide/kotlin/index.md
index 6975c8958..5d0b26d4e 100644
--- a/docs/docs/guide/kotlin/index.md
+++ b/docs/docs/guide/kotlin/index.md
@@ -50,14 +50,14 @@ See [Java Features](../java/index.md#features) for complete feature list.
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
### Gradle
```kotlin
-implementation("org.apache.fory:fory-kotlin:0.13.2")
+implementation("org.apache.fory:fory-kotlin:0.14.0")
```
## Quick Start
diff --git a/docs/docs/guide/scala/index.md b/docs/docs/guide/scala/index.md
index 7d158bcf1..b81a9a4a4 100644
--- a/docs/docs/guide/scala/index.md
+++ b/docs/docs/guide/scala/index.md
@@ -48,7 +48,7 @@ See [Java Features](../java/index.md#features) for complete feature list.
Add the dependency with sbt:
```sbt
-libraryDependencies += "org.apache.fory" %% "fory-scala" % "0.13.2"
+libraryDependencies += "org.apache.fory" %% "fory-scala" % "0.14.0"
```
## Quick Start
diff --git a/docs/docs/guide/xlang/getting-started.md b/docs/docs/guide/xlang/getting-started.md
index 45e7263ee..3645d77d3 100644
--- a/docs/docs/guide/xlang/getting-started.md
+++ b/docs/docs/guide/xlang/getting-started.md
@@ -31,14 +31,14 @@ This guide covers installation and basic setup for cross-language serialization
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
**Gradle:**
```gradle
-implementation 'org.apache.fory:fory-core:0.13.2'
+implementation 'org.apache.fory:fory-core:0.14.0'
```
### Python
diff --git a/docs/docs/introduction/benchmark.md b/docs/docs/introduction/benchmark.md
index 540e8e0b0..a9913d83b 100644
--- a/docs/docs/introduction/benchmark.md
+++ b/docs/docs/introduction/benchmark.md
@@ -47,6 +47,12 @@ Fory Rust demonstrates competitive performance compared to other Rust serializat
Note: Results depend on hardware, dataset, and implementation versions. See the Rust guide for how to run benchmarks yourself: https://github.com/apache/fory/blob/main/benchmarks/rust_benchmark/README.md
+## C++ Benchmark
+
+Fory C++ demonstrates competitive performance compared to Protobuf C++ serialization framework.
+
+<img src="public/benchmarks/cpp/throughput_comparison.png" width="90%"/>
+
## JavaScript Benchmark
<img width="33%" alt="" src="/img/benchmarks/javascript/complex_object.jpg" />
diff --git a/docs/docs/start/install.md b/docs/docs/start/install.md
index b7ce73340..232513340 100644
--- a/docs/docs/start/install.md
+++ b/docs/docs/start/install.md
@@ -16,7 +16,7 @@ To add a dependency on Apache Fory™ using Maven, use the following:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
<!-- Optional row format support -->
<!--
@@ -44,7 +44,7 @@ To add a dependency on Apache Fory™ scala for scala 2.13 with maven, use the f
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_2.13</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
@@ -54,20 +54,20 @@ To add a dependency on Apache Fory™ scala for scala 3 with maven, use the foll
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_3</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
To add a dependency on Apache Fory™ scala for scala 2.13 with sbt, use the following:
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.13.2"
+libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.14.0"
```
To add a dependency on Apache Fory™ scala for scala 3 with sbt, use the following:
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.13.2"
+libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.14.0"
```
## Kotlin
@@ -78,7 +78,7 @@ To add a dependency on Apache Fory™ kotlin with maven, use the following:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
@@ -86,7 +86,7 @@ To add a dependency on Apache Fory™ kotlin with maven, use the following:
```bash
python -m pip install --upgrade pip
-pip install pyfory==0.13.2
+pip install pyfory==0.14.0
```
## Rust
@@ -99,7 +99,7 @@ fory = "0.13"
or just execute command:
```bash
-cargo add fory@0.13.2
+cargo add fory@0.14.0
```
## JavaScript
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/start/install.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/start/install.md
index 29f376490..efe9cac98 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/start/install.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/docs/start/install.md
@@ -14,7 +14,7 @@ Apache Fory™ 源码下载请参见 Apache Fory™ [download](https://github.co
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-core</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
<!-- Optional row format support -->
<!--
@@ -42,7 +42,7 @@ Apache Fory™ 源码下载请参见 Apache Fory™ [download](https://github.co
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_2.13</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
@@ -52,20 +52,20 @@ Apache Fory™ 源码下载请参见 Apache Fory™ [download](https://github.co
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-scala_3</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
要使用 sbt 添加 scala 2.13 的 Fory scala 依赖，请使用以下配置：
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.13.2"
+libraryDependencies += "org.apache.fory" % "fory-scala_2.13" % "0.14.0"
```
要使用 sbt 添加 scala 3 的 Fory scala 依赖，请使用以下配置：
```sbt
-libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.13.2"
+libraryDependencies += "org.apache.fory" % "fory-scala_3" % "0.14.0"
```
## 安装 Apache Fory™ Kotlin
@@ -76,7 +76,7 @@ To add a dependency on Apache Fory™kotlin with maven, use the following:
<dependency>
<groupId>org.apache.fory</groupId>
<artifactId>fory-kotlin</artifactId>
- <version>0.13.2</version>
+ <version>0.14.0</version>
</dependency>
```
@@ -84,7 +84,7 @@ To add a dependency on Apache Fory™kotlin with maven, use the following:
```bash
python -m pip install --upgrade pip
-pip install pyfory==0.13.2
+pip install pyfory==0.14.0
```
## 安装 Apache Fory™ Rust
@@ -97,5 +97,5 @@ fory = "0.13"
或者直接执行以下命令：
```bash
-cargo add fory@0.13.2
+cargo add fory@0.14.0
```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/community.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/community.md
new file mode 100644
index 000000000..25b8db402
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/community.md
@@ -0,0 +1,85 @@
+---
+title: 社区
+sidebar_position: 0
+id: community
+---
+
+Apache Fory™ 是一个由社区驱动的开源项目，项目的蓬勃发展得益于社区贡献。
+我们邀请您根据自己的意愿尽可能地参与项目。以下是几种贡献方式：
+
+- 使用 Apache Fory™ 并分享使用体验和反馈问题；
+- 为项目提供最佳实践示例；
+- 报告错误并修复；
+- 贡献代码和参与文档建设。
+
+## 邮件列表
+
+| 邮件列表 | 描述 | 订阅 | 取消订阅 | 发送邮件 | 活动 |
+| ----------------------- | ------------------ | ------------------------------------------------ | ------------------------------------------------------ | -------------------------------------- | -------------------------------------------------------------------------- |
+| dev@fory.apache.org | 开发相关讨论 | [订阅](mailto:dev-subscribe@fory.apache.org) | [取消订阅](mailto:dev-unsubscribe@fory.apache.org) | [发送邮件](mailto:dev@fory.apache.org) | [邮件列表活动](https://lists.apache.org/list.html?dev@fory.apache.org) |
+| commits@fory.apache.org | 仓库的所有 commits | [订阅](mailto:commits-subscribe@fory.apache.org) | [取消订阅](mailto:commits-unsubscribe@fory.apache.org) | 只读的邮件列表 | [邮件列表活动](https://lists.apache.org/list.html?commits@fory.apache.org) |
+
+在尝试发送邮件之前，请确保订阅上述的邮件列表。
+
+**如果您没有订阅邮件列表，您的邮件将被拒绝或不会收到回复。**
+
+### 如何订阅邮件列表
+
+要发送邮件至邮件列表，请先通过以下方式订阅：
+
+1. 发送电子邮件至 listname-subscribe@fory.apache.org，并相应替换 `listname`；
+2. 回复您将收到的确认电子邮件，保持邮件主题行完整；
+3. 然后您将收到一封欢迎的电子邮件，订阅成功。
+
+在讨论电子邮件中的代码片段时，请确保：
+
+- 您不要链接到外部服务中的文件，因为此类文件可能会更改、被删除或链接可能会中断，从而使存档的电子邮件线程变得无用；
+- 您粘贴文本而不是文本屏幕截图；
+- 粘贴代码时保持格式，以保持代码可读；
+- 有足够的导入语句以避免产生代码歧义。
+
+## Slack
+
+您可以加入[Slack 上的 Apache Fory™ 社区](https://join.slack.com/t/fory-project/shared_invite/zt-1u8soj4qc-ieYEu7ciHOqA2mo47llS8A)。
+
+这里有一些社区规则：
+
+- 保持尊重和友善；
+- 所有重要的决定和结论都必须反映到邮件列表中。 “如果这没有在邮件列表中有相关的讨论记录，则代表它不生效” ；
+- [The Apache Way](https://theapacheway.com/on-list/)；
+- 使用 Slack 线程来防止并行对话淹没当前的对话频道；
+- 请不要直接向邮件列表发送 Bug fix、Issue 分配和 Code Review 消息。这些内容应该被社区贡献者自愿处理并分配。
+
+## Issue 跟踪
+
+我们使用 GitHub Issues 来跟踪所有 Issues：
+
+- 代码相关问题：https://github.com/apache/fory/issues
+- 网站相关问题：https://github.com/apache/fory-site/issues
+
+您需要有一个 [GitHub 帐号](https://github.com/signup) 才能创建问题。
+如果您没有 [GitHub 帐号](https://github.com/signup)，您可以发送电子邮件至 dev@fory.apache.org。
+
+### 报告 Bug
+
+您在报告 Bug 之前，应该：
+
+- 验证该 Bug 确实存在；
+- 搜索 [Issue List](https://github.com/apache/fory/issues) 以确保不存在相关 Bug。
+- 在 Issue List 中创建 [bug 报告](https://github.com/apache/fory/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml)。
+- 如果可能的话，深入研究 Apache Fory™ 的源代码，并针对您报告的 Bug 提交补丁，这有助于快速修复 Bug。
+
+### 报告安全漏洞
+
+Apache Fory™ 是 [Apache 软件基金会](https://apache.org/) 的一个项目，遵循 [ASF 漏洞处理流程](https://apache.org/security/#vulnerability-handling)。
+
+要报告您发现的新的安全漏洞，请遵循 [ASF 漏洞报告流程](https://apache.org/security/#reporting-a-vulnerability)，该流程解释了如何私下向社区维护者发送详细的漏洞信息。
+
+### New Feature
+
+欢迎您增强功能或新功能建议。提案越具体、越合理，您在 Apache Fory™ 社区的影响力就越大。它有可能在之后版本发布。
+
+### 项目源代码
+
+- Apache Fory™ Core 存储库：https://github.com/apache/fory
+- Apache Fory™ 网站存储库：https://github.com/apache/fory-site
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_join_community.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_join_community.md
new file mode 100644
index 000000000..e24a36673
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_join_community.md
@@ -0,0 +1,108 @@
+---
+title: 如何加入 Apache Fory™ 社区
+sidebar_position: 0
+id: how_to_join_community
+---
+
+首先为你选择加入开源贡献行列的行为点赞 👍🏻。再者，十分感谢你选择参与到 Apache Fory™ 社区，为这个开源项目做出贡献。
+
+## Apache Fory™ 贡献指南
+
+Apache Fory™ 团队通常在 github 上进行开发和 issue 维护，请打开 [Github 网站](https://github.com/)，点击右上角 `Sign up` 按钮，注册一个自己的账号，开启你开源之旅的第一步。
+
+在 [Apache Fory™ 仓库](https://github.com/apache/fory)中，我们有一份面向所有开源贡献者的[指南](https://fory.apache.org/zh-CN/docs/community/)，介绍了有关版本管理、分支管理等内容，**请花几分钟时间阅读了解一下**。
+
+## 你的第一个 Pull Request
+
+### Step0：安装 Git
+
+Git 是一种版本控制系统，用于跟踪和管理软件开发项目中的代码变更。它帮助开发者记录和管理代码的历史记录，方便团队协作、代码版本控制、合并代码等操作。通过 Git，您可以追踪每个文件的每个版本，并轻松地在不同版本之间进行切换和比较。Git 还提供了分支管理功能，使得可以同时进行多个并行开发任务。
+
+- 访问 Git 官方网站：[https://git-scm.com](https://git-scm.com)
+- 下载最新版本的 Git 安装程序。
+- 运行下载的安装程序，按照安装向导的提示进行安装。
+- 安装完成后，你可以通过命令行使用 `git version` 命令确认安装成功。
+
+### Step1：Fork 项目
+
+- 首先需要 fork 这个项目，进入[Apache Fory™ 项目页面](https://github.com/apache/fory)，点击右上角的 Fork 按钮
+- 你的 github 帐号中会出现 xxxx(你的 github 用户名)/fory 这个项目
+- 在本地电脑上使用以下命令: 得到一个 fory 文件夹
+
+```
+// ssh
+git clone git@github.com:xxxx(你的github用户名)/fory.git
+// https
+git clone https://github.com/xxxx(你的github用户名)/fory.git
+```
+
+### Step2：获取项目代码
+
+- 进入 fory 文件夹，添加 fory 的远程地址
+
+```
+git remote add upstream https://github.com/apache/fory.git
+```
+
+### Step3：创建分支
+
+- 好了，现在可以开始贡献我们的代码了。fory 默认分支为 main 分支。无论是功能开发、bug 修复、文档编写，都请新建立一个分支，再合并到 main 分支上。使用以下代码创建分支：
+
+```shell
+// 创建功能开发分支
+git checkout -b feat/xxxx
+
+// 创建问题修复开发分支
+git checkout -b fix/xxxx
+
+// 创建文档、demo分支
+git checkout -b docs/add-java-demo
+```
+
+假设我们创建了文档修改分支 `docs/add-java-demo`
+
+- 假设我们已经添加了一些代码，提交到代码库
+
+- git add .
+
+- git commit -a -m "docs: add java demo and related docs" 。
+
+### Step4：合并修改
+
+- 切换回自己的开发分支:
+
+```
+git checkout docs/add-java-demo
+```
+
+- 把更新代码提交到自己的分支中:
+
+```
+git push origin docs/add-java-demo
+```
+
+### Step5：提交 Pull Request
+
+你可以在你的 github 代码仓库页面点击 `Compare & pull request` 按钮。或通过 `contribute` 按钮创建。
+
+- 填写这是什么类型的修改
+- 填写关联的 issue
+- 若有复杂变更，请说明背景和解决方案
+
+相关信息填写完成后，点击 Create pull request 提交。
+
+## **轻松步入 Apache Fory™ 开源贡献之旅**
+
+"**good first issue**" 是一个在开源社区常见的标签，这个标签的目的是帮助新贡献者找到适合入门的问题。
+
+Apache Fory™ 的入门问题，你可以通过 [issue 列表](https://github.com/apache/fory/issues)查看。
+
+如果你当前**有时间和意愿**参与到社区贡献，可以在 issue 里看一看 **good first issue**，选择一个感兴趣、适合自己的认领。
+
+## 拥抱 Apache Fory™ 社区
+
+在你为 Apache Fory™ 贡献代码之余，我们鼓励你参与其他让社区更加繁荣的事情，比如：
+
+- 为项目的发展、功能规划 等提建议。
+- 创作文章、视频，开办讲座来宣传 Apache Fory™
+- 撰写推广计划，同团队一同执行。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_release.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_release.md
new file mode 100644
index 000000000..acd0f0b1c
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_release.md
@@ -0,0 +1,422 @@
+---
+title: 如何发布
+sidebar_position: 0
+id: how_to_release
+---
+
+本文主要介绍如何发布新版本的 Apache Fory™。
+
+## 介绍
+
+源代码发布是 Apache 最重视以及最重要的部分。
+
+请注意许可证和发布的软件签名问题。发布软件是一件严肃的事情，并会产生相应的法律后果。
+
+## release manager 第一次发布
+
+### 环境要求
+
+此发布过程在 Ubuntu 系统中运行，需要以下几个环境依赖：
+
+- JDK 1.8+
+- Apache Maven 3.x+
+- Python 3.8
+- GnuPG 2.x
+- Git
+- SVN（Apache 基金会使用 svn 来托管项目发布）
+- **设置环境变量**：如果您在不同的目录下配置了 gpg 密钥，请执行 `export GNUPGHOME=$(xxx)` 导出环境变量。
+
+### 准备 GPG 密钥
+
+如果您是第一次作为软件发布者，您需要准备一个 GPG 密钥。
+
+您可以参考这里的[快速开始](https://infra.apache.org/openpgp.html)获取一个 GPG 密钥或者获取更多相关信息。
+
+#### 安装 GPG
+
+```bash
+sudo apt install gnupg2
+```
+
+#### 生成 GPG 密钥
+
+请使用您的 Apache 名字和电子邮件地址生成 GPG 密钥：
+
+```bash
+$ gpg --full-gen-key
+gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Please select what kind of key you want:
+ (1) RSA and RSA (default)
+ (2) DSA and Elgamal
+ (3) DSA (sign only)
+ (4) RSA (sign only)
+ (14) Existing key from card
+Your selection? 1 # input 1
+RSA keys may be between 1024 and 4096 bits long.
+What keysize do you want? (2048) 4096 # input 4096
+Requested keysize is 4096 bits
+Please specify how long the key should be valid.
+ 0 = key does not expire
+ <n> = key expires in n days
+ <n>w = key expires in n weeks
+ <n>m = key expires in n months
+ <n>y = key expires in n years
+Key is valid for? (0) 0 # input 0
+Key does not expire at all
+Is this correct? (y/N) y # input y
+
+GnuPG needs to construct a user ID to identify your key.
+
+Real name: Chaokun Yang # input your name
+Email address: chaokunyang@apache.org # input your email
+Comment: CODE SIGNING KEY # input some annotations, optional
+You selected this USER-ID:
+ "Chaokun <ch...@apache.org>"
+
+Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+
+# Input the security key
+┌──────────────────────────────────────────────────────┐
+│ Please enter this passphrase │
+│ │
+│ Passphrase: _______________________________ │
+│ │
+│ <OK> <Cancel> │
+└──────────────────────────────────────────────────────┘
+# key generation will be done after your inputting the key with the following output
+gpg: key E49B00F626B marked as ultimately trusted
+gpg: revocation certificate stored as '/Users/chaokunyang/.gnupg/openpgp-revocs.d/1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4.rev'
+public and secret key created and signed.
+
+pub rsa4096 2022-07-12 [SC]
+ 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4
+uid [ultimate] Chaokun <ch...@apache.org>
+sub rsa4096 2022-07-12 [E]
+```
+
+#### 上传公钥至 GPG 密钥服务器
+
+首先，列出您所创建的 GPG 密钥：
+
+```bash
+gpg --list-keys
+```
+
+执行相关命令之后，您将看到如下输出：
+
+```bash
+--------------------------------------------------
+pub rsa4096 2024-03-27 [SC]
+ 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4
+uid [ultimate] chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+sub rsa4096 2024-03-27 [E]
+```
+
+然后，将您的密钥 ID 发送到密钥服务器：
+
+```bash
+gpg --keyserver keys.openpgp.org --send-key <key-id> # e.g., 1E2CDAE4C08AD7D694D1CB139D7BE8E45E580BA4
+```
+
+其中，`keys.openpgp.org` 是一个随机选择的密钥服务器，可以使用 keyserver.ubuntu.com 或任何其他功能完备的密钥服务器。
+
+#### 检查密钥是否创建成功
+
+上传大约需要一分钟；之后，您可以通过电子邮件在相应的密钥服务器上检查。
+
+将密钥上传到密钥服务器的主要目的是为了加入一个可信的[信任网络](https://infra.apache.org/release-signing.html#web-of-trust)。
+
+#### 将 GPG 公钥添加到项目 KEYS 文件中
+
+发布分支的 svn 仓库是：https://dist.apache.org/repos/dist/release/fory
+
+请在发布分支的 KEYS 中添加公钥：
+
+```bash
+svn co https://dist.apache.org/repos/dist/release/fory fory-dist
+# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it.
+cd fory-dist
+(gpg --list-sigs YOUR_NAME@apache.org && gpg --export --armor YOUR_NAME@apache.org) >> KEYS # Append your key to the KEYS file
+svn add . # It is not needed if the KEYS document exists before.
+svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password.
+```
+
+#### 将 GPG 公钥上传到您的 GitHub 帐户
+
+- 输入 `https://github.com/settings/keys` 以添加您的 GPG 密钥。
+- 如果添加后发现“未验证”字样，请将 GPG 密钥中使用的电子邮件地址绑定到您的 GitHub 帐户（https://github.com/settings/emails）。
+
+### 延伸阅读
+
+建议您在发布之前阅读以下文档，了解有关 Apache 基金会发布软件的更多详细信息，但这不是必须的：
+
+- 发布政策：https://www.apache.org/legal/release-policy.html
+- TLP 版本：https://infra.apache.org/release-distribution
+- 发布标志：https://infra.apache.org/release-signing.html
+- 发布发布：https://infra.apache.org/release-publishing.html
+- 发布下载页面：https://infra.apache.org/release-download-pages.html
+- 发布 maven artifacts：https://infra.apache.org/publishing-maven-artifacts.html
+
+## 开始有关发布的讨论
+
+通过发送电子邮件至以下地址发起有关下一个版本的讨论：dev@fory.apache.org：
+
+标题：
+
+```
+[DISCUSS] Release Apache Fory ${release_version}
+```
+
+内容：
+
+```
+Hello, Apache Fory Community,
+
+This is a call for a discussion to release Apache Fory version ${release_version}.
+
+The change lists about this release:
+
+https://github.com/apache/fory/compare/v0.11.2...v0.12.0
+
+Please leave your comments here about this release plan. We will bump the version in repo and start the release process after the discussion.
+
+Thanks,
+
+${name}
+```
+
+## 准备发布
+
+如果讨论结果中没有出现反对声音，您需要做一些发布版本的准备工作。
+
+### Github 分支和标签
+
+- 创建一个名为 `releases-0.12.0`
+- 通过执行命令将版本 `$version` 升级到 `python ci/release.py bump_version -l all -version $version`
+- 执行 git commit 并将分支推送到 `git@github.com:apache/fory.git`
+- 通过 `git tag v0.12.0-rc1` 创建一个新标签，然后将其推送到 `git@github.com:apache/fory.git`
+
+### 构建 artifacts 并上传到 SVN dist/dev 仓库
+
+首先，您需要通过 `python ci/release.py build -v $version` 构建预发布 artifacts。
+
+然后您需要把它上传到 svn dist repo。dev 分支的 dist 仓库地址是：https://dist.apache.org/repos/dist/dev/fory
+
+```bash
+# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it.
+svn co https://dist.apache.org/repos/dist/dev/fory fory-dist-dev
+```
+
+然后，上传项目：
+
+```bash
+cd fory-dist-dev
+# create a directory named by version
+mkdir ${release_version}-${rc_version}
+# copy source code and signature package to the versioned directory
+cp ${repo_dir}/dist/* ${release_version}-${rc_version}
+# check svn status
+svn status
+# add to svn
+svn add ${release_version}-${rc_version}
+# check svn status
+svn status
+# commit to SVN remote server
+svn commit -m "Prepare for fory ${release_version}-${rc_version}"
+```
+
+访问 https://dist.apache.org/repos/dist/dev/fory/ 以检查 artifacts 是否正确上传。
+
+### 如果出现问题该怎么办
+
+如果某些文件是意外出现或者发生某些错误，则需要删除相关内容并执行 `svn delete`，然后重复上述上传过程。
+
+## 投票
+
+新版本发布需要 Apache Fory 社区的投票。
+
+- release_version：Fory 的版本，如 0.12.0。
+- release_candidate_version：投票的版本，如 0.12.0-rc1。
+- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001. 具体来说，可以通过搜索 “fory” 来找到 maven_artifact_number https://repository.apache.org/#stagingRepositories.
+
+### Fory 社区投票
+
+发送电子邮件至 Fory Community：dev@fory.apache.org：
+
+标题：
+
+```
+[VOTE] Release Apache Fory v${release_version}-${rc_version}
+```
+
+内容：
+
+```
+Hello, Apache Fory Community:
+
+This is a call for vote to release Apache Fory
+version release-0.12.0-rc1.
+
+Apache Fory - A blazingly fast multi-language serialization
+framework powered by JIT and zero-copy.
+
+The change lists about this release:
+
+https://github.com/apache/fory/compare/v0.12.0...v0.12.0-rc1
+
+The release candidates:
+https://dist.apache.org/repos/dist/dev/fory/0.12.0-rc1/
+
+The maven staging for this release:
+https://repository.apache.org/content/repositories/orgapachefory-1003
+
+Git tag for the release:
+https://github.com/apache/fory/releases/tag/v0.12.0-rc1
+
+Git commit for the release:
+https://github.com/apache/fory/commit/fae06330edd049bb960536e978a45b97bca66faf
+
+The artifacts signed with PGP key [5E580BA4], corresponding to
+[chaokunyang@apache.org], that can be found in keys file:
+https://downloads.apache.org/fory/KEYS
+
+The vote will be open for at least 72 hours until the necessary number of votes are reached.
+
+Please vote accordingly:
+
+[ ] +1 approve
+[ ] +0 no opinion
+[ ] -1 disapprove with the reason
+
+To learn more about Fory, please see https://fory.apache.org/
+
+*Valid check is a requirement for a vote. *Checklist for reference:
+
+[ ] Download Fory is valid.
+[ ] Checksums and PGP signatures are valid.
+[ ] Source code distributions have correct names matching the current release.
+[ ] LICENSE and NOTICE files are correct.
+[ ] All files have license headers if necessary.
+[ ] No compiled archives bundled in source archive.
+[ ] Can compile from source.
+
+How to Build and Test, please refer to: https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md
+
+Thanks,
+Chaokun Yang
+```
+
+在至少获得 3 + 1 且具有约束力的投票（来自 Fory Podling PMC 成员和提交者）并没有收到否决票之后，发布投票结果：
+
+标题：
+
+```
+[RESULT][VOTE] Release Apache Fory v${release_version}-${rc_version}
+```
+
+内容：
+
+```
+Hello, Apache Fory Community,
+
+The vote to release Apache Fory v${release_version}-${rc_version} has passed.
+
+The vote PASSED with 3 binding +1 and 0 -1 vote:
+
+Binding votes:
+
+- xxx
+- yyy
+- zzz
+
+Vote thread: ${vote_thread_url}
+
+Thanks,
+
+${name}
+```
+
+### 如果投票失败怎么办
+
+如果投票失败，请单击“删除”以删除暂存的 Maven artifacts。
+
+解决提出的问题，然后再次提出 `rc_version` 的新投票。
+
+## 官方发布
+
+### 将 artifacts 发布到 SVN 发布目录
+
+- release_version：Fory 的发布版本，如 0.12.0
+- release_candidate_version：投票版本，如 0.12.0-rc1
+
+```bash
+svn mv https://dist.apache.org/repos/dist/dev/fory/${release_version}-${rc_version} https://dist.apache.org/repos/dist/release/fory/${release_version} -m "Release fory ${release_version}"
+```
+
+### 更改 Fory 网站下载链接
+
+提交 PR 到 https://github.com/apache/fory-site 仓库更新 Fory 版本，[下载页面](https://fory.apache.org/download)
+
+### 发布 Maven artifacts
+
+- maven_artifact_number：Maven 暂存 artifacts 的数量。如 1001。
+- 打开https://repository.apache.org/#stagingRepositories.
+- 找到 artifacts `orgapachefory-${maven_artifact_number}`，点击“发布”。
+
+### 发送公告
+
+将发布公告发送给 dev@fory.apache.org 并且抄送给 announce@apache.org。
+
+标题：
+
+```
+[ANNOUNCE] Apache Fory ${release_version} released
+```
+
+内容：
+
+```
+Hi all,
+
+The Apache Fory community is pleased to announce
+that Apache Fory {release_version} has been released!
+
+Apache Fory - A blazingly fast multi-language serialization
+framework powered by JIT and zero-copy.
+
+The release notes are available here:
+https://github.com/apache/fory/releases/tag/v${release_version}
+
+For the complete list of changes:
+https://github.com/apache/fory/compare/v0.12.0...v${release_version}
+
+Apache Fory website: https://fory.apache.org/
+
+Download Links: https://fory.apache.org/download
+
+Fory Resources:
+- Fory github repo: https://github.com/apache/fory
+- Issue: https://github.com/apache/fory/issues
+- Mailing list: dev@fory.apache.org
+
+We are looking to grow our community and welcome new contributors. If
+you are interested in contributing to Fory, please contact us on the
+mailing list or on GitHub. We will be happy to help you get started.
+
+------------------
+Best Regards,
+${your_name}
+```
+
+至此，整个发布流程结束。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_verify.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_verify.md
new file mode 100644
index 000000000..150fb90cf
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/community/how_to_verify.md
@@ -0,0 +1,119 @@
+---
+title: 如何验证 Apache Fory™
+sidebar_position: 0
+id: how_to_verify
+---
+
+## 下载 Apache Fory™
+
+```bash
+# If there is svn locally, you can clone to the local
+svn co https://dist.apache.org/repos/dist/dev/incubator/fory/${release_version}-${rc_version}/
+# You can download the material file directly
+wget https://dist.apache.org/repos/dist/dev/incubator/fory/${release_version}-${rc_version}/xxx.xxx
+```
+
+## 验证 checksums 和 signatures
+
+首先，您需要安装 gpg：
+
+```bash
+apt-get install gnupg
+# or
+yum install gnupg
+# or
+brew install gnupg
+```
+
+之后，导入 Apache Fory release manager 的公钥：
+
+```bash
+curl https://downloads.apache.org/incubator/fory/KEYS > KEYS # Download KEYS
+gpg --import KEYS # Import KEYS to local
+# Then, trust the public key:
+gpg --edit-key <KEY-used-in-this-version> # Edit the key(mentioned in vote email)
+# It will enter the interactive mode, use the following command to trust the key:
+gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+
+pub 4096R/5E580BA4 created: 2024-03-27 expires: never usage: SC
+ trust: unknown validity: unknown
+sub 4096R/A31EF728 created: 2024-03-27 expires: never usage: E
+[ unknown] (1). chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+
+gpg> trust
+pub 4096R/5E580BA4 created: 2024-03-27 expires: never usage: SC
+ trust: unknown validity: unknown
+sub 4096R/A31EF728 created: 2024-03-27 expires: never usage: E
+[ unknown] (1). chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+
+Please decide how far you trust this user to correctly verify other users' keys
+(by looking at passports, checking fingerprints from different sources, etc.)
+
+ 1 = I don't know or won't say
+ 2 = I do NOT trust
+ 3 = I trust marginally
+ 4 = I trust fully
+ 5 = I trust ultimately
+ m = back to the main menu
+
+Your decision? 5
+Do you really want to set this key to ultimate trust? (y/N) y
+
+pub 4096R/5E580BA4 created: 2024-03-27 expires: never usage: SC
+ trust: ultimate validity: unknown
+sub 4096R/A31EF728 created: 2024-03-27 expires: never usage: E
+[ unknown] (1). chaokunyang (CODE SIGNING KEY) <ch...@apache.org>
+Please note that the shown key validity is not necessarily correct
+unless you restart the program.
+```
+
+接下来验证签名：
+
+```bash
+for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i; done
+```
+
+如果出现如下内容，则表示签名正确：
+
+```bash
+apache-fory-0.5.0-src.tar.gz
+gpg: Signature made Wed 17 Apr 2024 11:49:45 PM CST using RSA key ID 5E580BA4
+gpg: checking the trustdb
+gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
+gpg: Good signature from "chaokunyang (CODE SIGNING KEY) <ch...@apache.org>"
+```
+
+然后验证 checksum：
+
+```bash
+for i in *.tar.gz; do echo $i; sha512sum --check $i.sha512; done
+```
+
+它应该输出如下内容：
+
+```bash
+apache-fory-0.12.0-src.tar.gz
+apache-fory-0.12.0-src.tar.gz: OK
+```
+
+## 检查源码包中的文件
+
+解压缩 `apache-fory-${release_version}-${rc_version}-src.tar.gz` 并检查以下内容：
+
+- 此存储库 LICENSE 和 NOTICE 文件是正确的；
+- 如有必要，所有文件都有 ASF 许可证标头；
+- 项目构建通过。
+
+## 检查 fory-java 的 Maven artifacts
+
+下载 Apache Fory™：https://repository.apache.org/content/repositories/orgapachefory-${maven_artifact_number}/.
+
+您可以检查以下内容：
+
+- JAR 的 Checksum 与项目绑定的 checksum 文件一致。
+- JAR 的 signature 与项目绑定的 signature 文件一致。
+- JAR 在本地是可重复的。这意味着您可以在计算机上构建 JAR，并验证 checksum 和与项目绑定的相同。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/DEVELOPMENT.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/DEVELOPMENT.md
new file mode 100644
index 000000000..004da7bd9
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/DEVELOPMENT.md
@@ -0,0 +1,146 @@
+---
+title: 开发指南
+sidebar_position: 20
+id: development
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+## 如何构建 Apache Fory™
+
+请从 https://github.com/apache/fory 检出源代码树。
+
+### 构建 Apache Fory™ Java
+
+```bash
+cd java
+mvn clean compile -DskipTests
+```
+
+#### 环境要求
+
+- java 1.8+
+- maven 3.6.3+
+
+### 构建 Apache Fory™ Python
+
+```bash
+cd python
+# 首先卸载 numpy，以便在安装 pyarrow 时自动安装正确的 numpy 版本。
+# 对于 Python 版本低于 3.13，目前不支持 numpy 2。
+pip uninstall -y numpy
+# 为 Python < 3.13 安装必要的环境。
+pip install pyarrow Cython wheel pytest
+# pip install pyarrow Cython wheel pytest
+pip install -v -e .
+```
+
+#### 环境要求
+
+- python 3.6+
+
+### 构建 Apache Fory™ C++
+
+构建 fory 行格式：
+
+```bash
+bazel build //cpp/fory/row:fory_row_format
+```
+
+构建 fory 行格式编码器：
+
+```bash
+bazel build //cpp/fory/encoder:fory_encoder
+```
+
+#### 环境要求
+
+- 支持 C++17 的编译器
+- bazel 6.3.2
+
+### 构建 Apache Fory™ GoLang
+
+```bash
+cd go/fory
+# 运行测试
+go test -v ./...
+# 运行跨语言测试
+go test -v fory_xlang_test.go
+```
+
+#### 环境要求
+
+- go 1.13+
+
+### 构建 Apache Fory™ Rust
+
+```bash
+cd rust
+# 构建
+cargo build
+# 运行测试
+cargo test
+# 运行特定测试
+cargo test -p tests --test $test_file $test_method
+# 运行子目录下的特定测试
+cargo test --test mod $dir$::$test_file::$test_method
+# 调试子目录下的特定测试并获取回溯信息
+RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 cargo test --test mod $dir$::$test_file::$test_method
+# 检查 fory derive 宏生成的代码
+cargo expand --test mod $mod$::$file$ > expanded.rs
+```
+
+#### 环境要求
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+### 构建 Apache Fory™ JavaScript
+
+```bash
+cd javascript
+npm install
+
+# 运行构建
+npm run build
+# 运行测试
+npm run test
+```
+
+#### 环境要求
+
+- node 14+
+- npm 8+
+
+### Lint Markdown 文档
+
+```bash
+# 全局安装 prettier
+npm install -g prettier
+
+# 格式化 markdown 文件
+prettier --write "**/*.md"
+```
+
+#### 环境要求
+
+- node 14+
+- npm 8+
+
+## 贡献
+
+更多信息，请参考[如何贡献到 Apache Fory™](https://github.com/apache/fory/blob/main/CONTRIBUTING.md)。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/_category_.json
new file mode 100644
index 000000000..a4d4668e3
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/_category_.json
@@ -0,0 +1,4 @@
+{
+ "position": 3,
+ "label": "Guide"
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/_category_.json
new file mode 100644
index 000000000..c543ab138
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "C++",
+ "position": 3,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/basic-serialization.md
new file mode 100644
index 000000000..828ed4a6b
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/basic-serialization.md
@@ -0,0 +1,238 @@
+---
+title: 基础序列化
+sidebar_position: 2
+id: cpp_basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍基础对象图序列化和核心序列化 API。
+
+## 对象图序列化
+
+Apache Fory™ 提供复杂对象图的自动序列化，保留对象之间的结构和关系。`FORY_STRUCT` 宏在编译时生成高效的序列化代码，消除运行时开销。
+
+**核心功能：**
+
+- 支持任意深度的嵌套结构体序列化
+- 集合类型（vector、set、map）
+- 使用 `std::optional<T>` 的可选字段
+- 智能指针（`std::shared_ptr`、`std::unique_ptr`）
+- 自动处理基本类型和字符串
+- 使用变长整数的高效二进制编码
+
+```cpp
+#include "fory/serialization/fory.h"
+#include <vector>
+#include <map>
+
+using namespace fory::serialization;
+
+// 定义结构体
+struct Address {
+ std::string street;
+ std::string city;
+ std::string country;
+
+ bool operator==(const Address &other) const {
+ return street == other.street && city == other.city &&
+ country == other.country;
+ }
+};
+FORY_STRUCT(Address, street, city, country);
+
+struct Person {
+ std::string name;
+ int32_t age;
+ Address address;
+ std::vector<std::string> hobbies;
+ std::map<std::string, std::string> metadata;
+
+ bool operator==(const Person &other) const {
+ return name == other.name && age == other.age &&
+ address == other.address && hobbies == other.hobbies &&
+ metadata == other.metadata;
+ }
+};
+FORY_STRUCT(Person, name, age, address, hobbies, metadata);
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+ fory.register_struct<Address>(100);
+ fory.register_struct<Person>(200);
+
+ Person person{
+ "John Doe",
+ 30,
+ {"123 Main St", "New York", "USA"},
+ {"reading", "coding"},
+ {{"role", "developer"}}
+ };
+
+ auto result = fory.serialize(person);
+ auto decoded = fory.deserialize<Person>(result.value());
+ assert(person == decoded.value());
+}
+```
+
+## 序列化 API
+
+### 序列化到新 Vector
+
+```cpp
+auto fory = Fory::builder().xlang(true).build();
+fory.register_struct<MyStruct>(1);
+
+MyStruct obj{/* ... */};
+
+// 序列化 - 返回 Result<std::vector<uint8_t>, Error>
+auto result = fory.serialize(obj);
+if (result.ok()) {
+ std::vector<uint8_t> bytes = std::move(result).value();
+ // 使用 bytes...
+} else {
+ // 处理错误
+ std::cerr << result.error().to_string() << std::endl;
+}
+```
+
+### 序列化到现有缓冲区
+
+```cpp
+// 序列化到现有 Buffer（最快路径）
+Buffer buffer;
+auto result = fory.serialize_to(buffer, obj);
+if (result.ok()) {
+ size_t bytes_written = result.value();
+ // buffer 现在包含序列化数据
+}
+
+// 序列化到现有 vector（零拷贝）
+std::vector<uint8_t> output;
+auto result = fory.serialize_to(output, obj);
+if (result.ok()) {
+ size_t bytes_written = result.value();
+ // output 现在包含序列化数据
+}
+```
+
+### 从字节数组反序列化
+
+```cpp
+// 从原始指针反序列化
+auto result = fory.deserialize<MyStruct>(data_ptr, data_size);
+if (result.ok()) {
+ MyStruct obj = std::move(result).value();
+}
+
+// 从 vector 反序列化
+std::vector<uint8_t> data = /* ... */;
+auto result = fory.deserialize<MyStruct>(data);
+
+// 从 Buffer 反序列化（更新 reader_index）
+Buffer buffer(data);
+auto result = fory.deserialize<MyStruct>(buffer);
+```
+
+## 错误处理
+
+Fory 使用 `Result<T, Error>` 类型进行错误处理：
+
+```cpp
+auto result = fory.serialize(obj);
+
+// 检查操作是否成功
+if (result.ok()) {
+ auto value = std::move(result).value();
+ // 使用 value...
+} else {
+ Error error = result.error();
+ std::cerr << "Error: " << error.to_string() << std::endl;
+}
+
+// 或使用 FORY_TRY 宏进行提前返回
+FORY_TRY(bytes, fory.serialize(obj));
+// 直接使用 bytes...
+```
+
+常见错误类型：
+
+- `Error::type_mismatch` - 反序列化时类型 ID 不匹配
+- `Error::invalid_data` - 无效或损坏的数据
+- `Error::buffer_out_of_bound` - 缓冲区溢出/下溢
+- `Error::type_error` - 类型注册错误
+
+## FORY_STRUCT 宏
+
+`FORY_STRUCT` 宏用于注册结构体以进行序列化：
+
+```cpp
+struct MyStruct {
+ int32_t x;
+ std::string y;
+ std::vector<int32_t> z;
+};
+
+// 必须与结构体在同一命名空间中
+FORY_STRUCT(MyStruct, x, y, z);
+```
+
+该宏：
+
+1. 生成编译时字段元数据
+2. 启用 ADL（参数依赖查找）进行序列化
+3. 通过模板特化创建高效的序列化代码
+
+**要求：**
+
+- 必须放在与结构体相同的命名空间中（用于 ADL）
+- 所有列出的字段必须是可序列化类型
+- 宏中的字段顺序决定序列化顺序
+
+## 嵌套结构体
+
+完全支持嵌套结构体：
+
+```cpp
+struct Inner {
+ int32_t value;
+};
+FORY_STRUCT(Inner, value);
+
+struct Outer {
+ Inner inner;
+ std::string label;
+};
+FORY_STRUCT(Outer, inner, label);
+
+// 两者都必须注册
+fory.register_struct<Inner>(1);
+fory.register_struct<Outer>(2);
+```
+
+## 性能提示
+
+- **缓冲区复用**：使用 `serialize_to(buffer, obj)` 配合预分配的缓冲区
+- **预注册**：在序列化开始前注册所有类型
+- **单线程**：尽可能使用 `build()` 而不是 `build_thread_safe()`
+- **禁用跟踪**：当不需要引用跟踪时使用 `track_ref(false)`
+- **紧凑编码**：使用变长编码提高空间效率
+
+## 相关主题
+
+- [配置](configuration.md) - 构建器选项
+- [类型注册](type-registration.md) - 注册类型
+- [支持的类型](supported-types.md) - 所有支持的类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/configuration.md
new file mode 100644
index 000000000..58cb417c2
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/configuration.md
@@ -0,0 +1,189 @@
+---
+title: 配置
+sidebar_position: 1
+id: cpp_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Fory 配置选项和序列化模式。
+
+## 序列化模式
+
+Apache Fory™ 支持两种序列化模式：
+
+### SchemaConsistent 模式（默认）
+
+类型声明必须在通信双方完全匹配：
+
+```cpp
+auto fory = Fory::builder().build(); // 默认为 SchemaConsistent
+```
+
+### Compatible 模式
+
+允许独立的 schema 演化：
+
+```cpp
+auto fory = Fory::builder().compatible(true).build();
+```
+
+## 构建器模式
+
+使用 `ForyBuilder` 构造具有自定义配置的 Fory 实例：
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// 默认配置
+auto fory = Fory::builder().build();
+
+// 用于 schema 演化的兼容模式
+auto fory = Fory::builder()
+ .compatible(true)
+ .build();
+
+// 跨语言模式
+auto fory = Fory::builder()
+ .xlang(true)
+ .build();
+
+// 完整配置
+auto fory = Fory::builder()
+ .compatible(true)
+ .xlang(true)
+ .track_ref(true)
+ .max_dyn_depth(10)
+ .check_struct_version(true)
+ .build();
+```
+
+## 配置选项
+
+### xlang(bool)
+
+启用/禁用跨语言（xlang）序列化模式。
+
+```cpp
+auto fory = Fory::builder()
+ .xlang(true) // 启用跨语言兼容性
+ .build();
+```
+
+启用后，包含用于与 Java、Python、Go、Rust 和 JavaScript 跨语言兼容的元数据。
+
+**默认值：** `true`
+
+### compatible(bool)
+
+启用/禁用用于 schema 演化的兼容模式。
+
+```cpp
+auto fory = Fory::builder()
+ .compatible(true) // 启用 schema 演化
+ .build();
+```
+
+启用后，支持读取使用不同 schema 版本序列化的数据。
+
+**默认值：** `false`
+
+### track_ref(bool)
+
+启用/禁用共享引用和循环引用的引用跟踪。
+
+```cpp
+auto fory = Fory::builder()
+ .track_ref(true) // 启用引用跟踪
+ .build();
+```
+
+启用后，避免重复序列化共享对象并处理循环引用。
+
+**默认值：** `true`
+
+### max_dyn_depth(uint32_t)
+
+设置动态类型对象的最大允许嵌套深度。
+
+```cpp
+auto fory = Fory::builder()
+ .max_dyn_depth(10) // 允许最多 10 层
+ .build();
+```
+
+这限制了嵌套多态对象序列化的最大深度（例如 `shared_ptr<Base>`、`unique_ptr<Base>`）。防止深度嵌套结构在动态序列化场景中导致栈溢出。
+
+**默认值：** `5`
+
+**何时调整：**
+
+- **增加**：对于合法的深度嵌套数据结构
+- **减少**：对于更严格的安全要求或浅层数据结构
+
+### check_struct_version(bool)
+
+启用/禁用结构体版本检查。
+
+```cpp
+auto fory = Fory::builder()
+ .check_struct_version(true) // 启用版本检查
+ .build();
+```
+
+启用后，验证类型哈希以检测 schema 不匹配。
+
+**默认值：** `false`
+
+## 线程安全 vs 单线程
+
+### 单线程（最快）
+
+```cpp
+auto fory = Fory::builder()
+ .xlang(true)
+ .build(); // 返回 Fory
+```
+
+单线程 `Fory` 是最快的选项，但非线程安全。每个线程使用一个实例。
+
+### 线程安全
+
+```cpp
+auto fory = Fory::builder()
+ .xlang(true)
+ .build_thread_safe(); // 返回 ThreadSafeFory
+```
+
+`ThreadSafeFory` 使用 Fory 实例池提供线程安全的序列化。由于池开销略慢，但可以从多个线程并发安全使用。
+
+## 配置摘要
+
+| 选项 | 说明 | 默认值 |
+| ---------------------------- | ---------------------- | ------- |
+| `xlang(bool)` | 启用跨语言模式 | `true` |
+| `compatible(bool)` | 启用 schema 演化 | `false` |
+| `track_ref(bool)` | 启用引用跟踪 | `true` |
+| `max_dyn_depth(uint32_t)` | 动态类型的最大嵌套深度 | `5` |
+| `check_struct_version(bool)` | 启用结构体版本检查 | `false` |
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 使用配置的 Fory
+- [跨语言](cross-language.md) - XLANG 模式详情
+- [类型注册](type-registration.md) - 注册类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/cross-language.md
new file mode 100644
index 000000000..1e22860cb
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/cross-language.md
@@ -0,0 +1,271 @@
+---
+title: 跨语言序列化
+sidebar_position: 6
+id: cpp_cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何使用 Fory 在 C++ 和其他语言之间进行跨语言序列化。
+
+## 概述
+
+Apache Fory™ 支持在 C++、Java、Python、Go、Rust 和 JavaScript 之间无缝交换数据。xlang（跨语言）模式确保所有支持语言之间的二进制兼容性。
+
+## 启用跨语言模式
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+auto fory = Fory::builder()
+ .xlang(true) // 启用跨语言模式
+ .build();
+```
+
+## 跨语言示例
+
+### C++ 生产者
+
+```cpp
+#include "fory/serialization/fory.h"
+#include <fstream>
+
+using namespace fory::serialization;
+
+struct Message {
+ std::string topic;
+ int64_t timestamp;
+ std::map<std::string, std::string> headers;
+ std::vector<uint8_t> payload;
+
+ bool operator==(const Message &other) const {
+ return topic == other.topic && timestamp == other.timestamp &&
+ headers == other.headers && payload == other.payload;
+ }
+};
+FORY_STRUCT(Message, topic, timestamp, headers, payload);
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+ fory.register_struct<Message>(100);
+
+ Message msg{
+ "events.user",
+ 1699999999000,
+ {{"content-type", "application/json"}},
+ {'h', 'e', 'l', 'l', 'o'}
+ };
+
+ auto result = fory.serialize(msg);
+ if (result.ok()) {
+ auto bytes = std::move(result).value();
+ // 写入文件、通过网络发送等
+ std::ofstream file("message.bin", std::ios::binary);
+ file.write(reinterpret_cast<const char*>(bytes.data()), bytes.size());
+ }
+ return 0;
+}
+```
+
+### Java 消费者
+
+```java
+import org.apache.fory.Fory;
+import org.apache.fory.config.Language;
+
+public class Message {
+ public String topic;
+ public long timestamp;
+ public Map<String, String> headers;
+ public byte[] payload;
+}
+
+public class Consumer {
+ public static void main(String[] args) throws Exception {
+ Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .build();
+ fory.register(Message.class, 100); // 与 C++ 相同的 ID
+
+ byte[] bytes = Files.readAllBytes(Path.of("message.bin"));
+ Message msg = (Message) fory.deserialize(bytes);
+
+ System.out.println("Topic: " + msg.topic);
+ System.out.println("Timestamp: " + msg.timestamp);
+ }
+}
+```
+
+### Python 消费者
+
+```python
+import pyfory
+
+class Message:
+ topic: str
+ timestamp: int
+ headers: dict[str, str]
+ payload: bytes
+
+fory = pyfory.Fory()
+fory.register(Message, type_id=100) # 与 C++ 相同的 ID
+
+with open("message.bin", "rb") as f:
+ data = f.read()
+
+msg = fory.deserialize(data)
+print(f"Topic: {msg.topic}")
+print(f"Timestamp: {msg.timestamp}")
+```
+
+## 类型映射
+
+### 基本类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 | Rust 类型 |
+| --------- | --------- | ----------- | --------- | --------- |
+| `bool` | `boolean` | `bool` | `bool` | `bool` |
+| `int8_t` | `byte` | `int` | `int8` | `i8` |
+| `int16_t` | `short` | `int` | `int16` | `i16` |
+| `int32_t` | `int` | `int` | `int32` | `i32` |
+| `int64_t` | `long` | `int` | `int64` | `i64` |
+| `float` | `float` | `float` | `float32` | `f32` |
+| `double` | `double` | `float` | `float64` | `f64` |
+
+### 字符串类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 | Rust 类型 |
+| ------------- | --------- | ----------- | -------- | --------- |
+| `std::string` | `String` | `str` | `string` | `String` |
+
+### 集合类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 |
+| ---------------- | ---------- | ----------- | ---------------- |
+| `std::vector<T>` | `List<T>` | `list` | `[]T` |
+| `std::set<T>` | `Set<T>` | `set` | `map[T]struct{}` |
+| `std::map<K,V>` | `Map<K,V>` | `dict` | `map[K]V` |
+
+### 时间类型
+
+| C++ 类型 | Java 类型 | Python 类型 | Go 类型 |
+| ----------- | ----------- | --------------- | --------------- |
+| `Timestamp` | `Instant` | `datetime` | `time.Time` |
+| `Duration` | `Duration` | `timedelta` | `time.Duration` |
+| `LocalDate` | `LocalDate` | `datetime.date` | `time.Time` |
+
+## 字段顺序要求
+
+**关键：** 字段将按照其 snake_cased 字段名排序，转换后的名称必须在各语言之间保持一致
+
+### C++
+
+```cpp
+struct Person {
+ std::string name; // 字段 0
+ int32_t age; // 字段 1
+ std::string email; // 字段 2
+};
+FORY_STRUCT(Person, name, age, email); // 顺序很重要！
+```
+
+### Java
+
+```java
+public class Person {
+ public String name; // 字段 0
+ public int age; // 字段 1
+ public String email; // 字段 2
+}
+```
+
+### Python
+
+```python
+class Person:
+ name: str # 字段 0
+ age: int # 字段 1
+ email: str # 字段 2
+```
+
+## 类型 ID 一致性
+
+所有语言必须使用相同的类型 ID：
+
+```cpp
+// C++
+fory.register_struct<Person>(100);
+fory.register_struct<Address>(101);
+fory.register_struct<Order>(102);
+```
+
+```java
+// Java
+fory.register(Person.class, 100);
+fory.register(Address.class, 101);
+fory.register(Order.class, 102);
+```
+
+```python
+# Python
+fory.register(Person, type_id=100)
+fory.register(Address, type_id=101)
+fory.register(Order, type_id=102)
+```
+
+## Compatible 模式
+
+用于跨语言边界的 schema 演化：
+
+```cpp
+// 使用 compatible 模式的 C++
+auto fory = Fory::builder()
+ .xlang(true)
+ .compatible(true) // 启用 schema 演化
+ .build();
+```
+
+Compatible 模式允许：
+
+- 添加新字段（带默认值）
+- 删除未使用的字段
+- 重排字段顺序
+
+## 故障排查
+
+### 类型不匹配错误
+
+```
+Error: Type mismatch: expected 100, got 101
+```
+
+**解决方案：** 确保类型 ID 在所有语言中匹配。
+
+### 编码错误
+
+```
+Error: Invalid UTF-8 sequence
+```
+
+**解决方案：** 确保所有语言中的字符串都是有效的 UTF-8。
+
+## 相关主题
+
+- [配置](configuration.md) - 构建器选项
+- [类型注册](type-registration.md) - 注册类型
+- [支持的类型](supported-types.md) - 类型兼容性
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/index.md
new file mode 100644
index 000000000..61db78056
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/index.md
@@ -0,0 +1,245 @@
+---
+title: C++ 序列化指南
+sidebar_position: 0
+id: cpp_serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+**Apache Fory™** 是一个极速的多语言序列化框架，基于 **JIT 编译**和**零拷贝**技术，在保持易用性和安全性的同时提供**超高性能**。
+
+C++ 实现利用现代 C++17 特性和模板元编程，提供具有编译时类型安全的高性能序列化。
+
+## 为什么选择 Apache Fory™ C++？
+
+- **🔥 极速性能**：快速序列化和优化的二进制协议
+- **🌍 跨语言**：在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化/反序列化数据
+- **🎯 类型安全**：基于宏的结构体注册实现编译时类型检查
+- **🔄 引用跟踪**：自动跟踪共享引用和循环引用
+- **📦 Schema 演化**：兼容模式支持独立的 schema 变更
+- **⚡ 双格式支持**：对象图序列化和零拷贝行格式
+- **🧵 线程安全**：同时提供单线程（最快）和线程安全两种变体
+
+## 安装
+
+C++ 实现同时支持 CMake 和 Bazel 构建系统。
+
+### 前置条件
+
+- CMake 3.16+（用于 CMake 构建）或 Bazel 8+（用于 Bazel 构建）
+- C++17 兼容的编译器（GCC 7+、Clang 5+、MSVC 2017+）
+
+### 使用 CMake（推荐）
+
+使用 CMake 的 `FetchContent` 模块是最简单的方式：
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(my_project LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+include(FetchContent)
+FetchContent_Declare(
+ fory
+ GIT_REPOSITORY https://github.com/apache/fory.git
+ GIT_TAG v0.14.0
+ SOURCE_SUBDIR cpp
+)
+FetchContent_MakeAvailable(fory)
+
+add_executable(my_app main.cc)
+target_link_libraries(my_app PRIVATE fory::serialization)
+```
+
+然后构建并运行：
+
+```bash
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+cmake --build . --parallel
+./my_app
+```
+
+### 使用 Bazel
+
+在项目根目录创建 `MODULE.bazel` 文件：
+
+```bazel
+module(
+ name = "my_project",
+ version = "1.0.0",
+)
+
+bazel_dep(name = "rules_cc", version = "0.1.1")
+
+bazel_dep(name = "fory", version = "0.14.0")
+git_override(
+ module_name = "fory",
+ remote = "https://github.com/apache/fory.git",
+ commit = "v0.14.0", # 或使用特定的 commit hash 以确保可重现性
+)
+```
+
+为应用程序创建 `BUILD` 文件：
+
+```bazel
+cc_binary(
+ name = "my_app",
+ srcs = ["main.cc"],
+ deps = ["@fory//cpp/fory/serialization:fory_serialization"],
+)
+```
+
+然后构建并运行：
+
+```bash
+bazel build //:my_app
+bazel run //:my_app
+```
+
+对于本地开发，可以使用 `local_path_override`：
+
+```bazel
+bazel_dep(name = "fory", version = "0.14.0")
+local_path_override(
+ module_name = "fory",
+ path = "/path/to/fory",
+)
+```
+
+### 示例
+
+请参阅 [examples/cpp](https://github.com/apache/fory/tree/main/examples/cpp) 目录获取完整的工作示例：
+
+- [hello_world](https://github.com/apache/fory/tree/main/examples/cpp/hello_world) - 对象图序列化
+- [hello_row](https://github.com/apache/fory/tree/main/examples/cpp/hello_row) - 行格式编码
+
+## 快速开始
+
+### 基础示例
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// 定义结构体
+struct Person {
+ std::string name;
+ int32_t age;
+ std::vector<std::string> hobbies;
+
+ bool operator==(const Person &other) const {
+ return name == other.name && age == other.age && hobbies == other.hobbies;
+ }
+};
+
+// 使用 Fory 注册结构体（必须在同一命名空间中）
+FORY_STRUCT(Person, name, age, hobbies);
+
+int main() {
+ // 创建 Fory 实例
+ auto fory = Fory::builder()
+ .xlang(true) // 启用跨语言模式
+ .track_ref(false) // 对简单类型禁用引用跟踪
+ .build();
+
+ // 使用唯一 ID 注册类型
+ fory.register_struct<Person>(1);
+
+ // 创建对象
+ Person person{"Alice", 30, {"reading", "coding"}};
+
+ // 序列化
+ auto result = fory.serialize(person);
+ if (!result.ok()) {
+ // 处理错误
+ return 1;
+ }
+ std::vector<uint8_t> bytes = std::move(result).value();
+
+ // 反序列化
+ auto deser_result = fory.deserialize<Person>(bytes);
+ if (!deser_result.ok()) {
+ // 处理错误
+ return 1;
+ }
+ Person decoded = std::move(deser_result).value();
+
+ assert(person == decoded);
+ return 0;
+}
+```
+
+## 线程安全
+
+Apache Fory™ C++ 为不同的线程需求提供两种变体：
+
+### 单线程（最快）
+
+```cpp
+// 单线程 Fory - 最快，但非线程安全
+auto fory = Fory::builder()
+ .xlang(true)
+ .build();
+```
+
+### 线程安全
+
+```cpp
+// 线程安全 Fory - 使用上下文池
+auto fory = Fory::builder()
+ .xlang(true)
+ .build_thread_safe();
+
+// 可以从多个线程安全使用
+std::thread t1([&]() {
+ auto result = fory.serialize(obj1);
+});
+std::thread t2([&]() {
+ auto result = fory.serialize(obj2);
+});
+```
+
+**提示：** 在生成线程之前完成类型注册，以确保每个工作线程看到相同的元数据。
+
+## 使用场景
+
+### 对象序列化
+
+- 包含嵌套对象和引用的复杂数据结构
+- 微服务中的跨语言通信
+- 具有完整类型安全的通用序列化
+- 使用兼容模式的 schema 演化
+
+### 行格式序列化
+
+- 高吞吐量数据处理
+- 需要快速字段访问的分析工作负载
+- 内存受限环境
+- 零拷贝场景
+
+## 后续步骤
+
+- [配置](configuration.md) - 构建器选项和模式
+- [基础序列化](basic-serialization.md) - 对象图序列化
+- [Schema 演化](schema-evolution.md) - 兼容模式和 schema 变更
+- [类型注册](type-registration.md) - 注册类型
+- [支持的类型](supported-types.md) - 所有支持的类型
+- [跨语言](cross-language.md) - XLANG 模式
+- [行格式](row-format.md) - 零拷贝行格式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/row-format.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/row-format.md
new file mode 100644
index 000000000..6c01f20b9
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/row-format.md
@@ -0,0 +1,516 @@
+---
+title: 行格式
+sidebar_position: 7
+id: cpp_row_format
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍用于高性能、缓存友好的数据访问的行格式序列化。
+
+## 概述
+
+Apache Fory™ 行格式是一种针对以下场景优化的二进制格式：
+
+- **随机访问**：无需反序列化整个对象即可读取任意字段
+- **零拷贝**：无数据复制的直接内存访问
+- **缓存友好**：连续内存布局提高 CPU 缓存效率
+- **列式转换**：易于转换为 Apache Arrow 格式
+- **部分序列化**：只序列化需要的字段
+
+## 何时使用行格式
+
+| 使用场景 | 行格式 | 对象图 |
+| ------------------ | ------ | ------ |
+| 分析/OLAP | ✅ | ❌ |
+| 随机字段访问 | ✅ | ❌ |
+| 完整对象序列化 | ❌ | ✅ |
+| 复杂对象图 | ❌ | ✅ |
+| 引用跟踪 | ❌ | ✅ |
+| 跨语言（简单类型） | ✅ | ✅ |
+
+## 快速开始
+
+```cpp
+#include "fory/encoder/row_encoder.h"
+#include "fory/row/writer.h"
+
+using namespace fory::row;
+using namespace fory::row::encoder;
+
+// 定义结构体
+struct Person {
+ int32_t id;
+ std::string name;
+ float score;
+};
+
+// 注册字段元数据（行编码必需）
+FORY_FIELD_INFO(Person, id, name, score);
+
+int main() {
+ // 创建编码器
+ RowEncoder<Person> encoder;
+
+ // 编码一个 person
+ Person person{1, "Alice", 95.5f};
+ encoder.Encode(person);
+
+ // 获取编码后的行
+ auto row = encoder.GetWriter().ToRow();
+
+ // 随机访问字段
+ int32_t id = row->GetInt32(0);
+ std::string name = row->GetString(1);
+ float score = row->GetFloat(2);
+
+ assert(id == 1);
+ assert(name == "Alice");
+ assert(score == 95.5f);
+
+ return 0;
+}
+```
+
+## 行编码器
+
+### 基本用法
+
+`RowEncoder<T>` 模板类提供类型安全的编码：
+
+```cpp
+#include "fory/encoder/row_encoder.h"
+
+// 使用 FORY_FIELD_INFO 定义结构体
+struct Point {
+ double x;
+ double y;
+};
+FORY_FIELD_INFO(Point, x, y);
+
+// 创建编码器
+RowEncoder<Point> encoder;
+
+// 访问 schema（用于检查）
+const Schema& schema = encoder.GetSchema();
+std::cout << "Fields: " << schema.field_names().size() << std::endl;
+
+// 编码值
+Point p{1.0, 2.0};
+encoder.Encode(p);
+
+// 获取结果作为 Row
+auto row = encoder.GetWriter().ToRow();
+```
+
+### 嵌套结构体
+
+```cpp
+struct Address {
+ std::string city;
+ std::string country;
+};
+FORY_FIELD_INFO(Address, city, country);
+
+struct Person {
+ std::string name;
+ Address address;
+};
+FORY_FIELD_INFO(Person, name, address);
+
+// 编码嵌套结构体
+RowEncoder<Person> encoder;
+Person person{"Alice", {"New York", "USA"}};
+encoder.Encode(person);
+
+auto row = encoder.GetWriter().ToRow();
+std::string name = row->GetString(0);
+
+// 访问嵌套结构体
+auto address_row = row->GetStruct(1);
+std::string city = address_row->GetString(0);
+std::string country = address_row->GetString(1);
+```
+
+### 数组 / 列表
+
+```cpp
+struct Record {
+ std::vector<int32_t> values;
+ std::string label;
+};
+FORY_FIELD_INFO(Record, values, label);
+
+RowEncoder<Record> encoder;
+Record record{{1, 2, 3, 4, 5}, "test"};
+encoder.Encode(record);
+
+auto row = encoder.GetWriter().ToRow();
+auto array = row->GetArray(0);
+
+int count = array->num_elements();
+for (int i = 0; i < count; i++) {
+ int32_t value = array->GetInt32(i);
+}
+```
+
+### 直接编码数组
+
+```cpp
+// 直接编码 vector（不在结构体内）
+std::vector<Person> people{
+ {"Alice", {"NYC", "USA"}},
+ {"Bob", {"London", "UK"}}
+};
+
+RowEncoder<decltype(people)> encoder;
+encoder.Encode(people);
+
+// 获取数组数据
+auto array = encoder.GetWriter().CopyToArrayData();
+auto first_person = array->GetStruct(0);
+std::string first_name = first_person->GetString(0);
+```
+
+## 行数据访问
+
+### Row 类
+
+`Row` 类提供对结构体字段的随机访问：
+
+```cpp
+class Row {
+public:
+ // 空值检查
+ bool IsNullAt(int i) const;
+
+ // 基本类型 getter
+ bool GetBoolean(int i) const;
+ int8_t GetInt8(int i) const;
+ int16_t GetInt16(int i) const;
+ int32_t GetInt32(int i) const;
+ int64_t GetInt64(int i) const;
+ float GetFloat(int i) const;
+ double GetDouble(int i) const;
+
+ // 字符串/二进制 getter
+ std::string GetString(int i) const;
+ std::vector<uint8_t> GetBinary(int i) const;
+
+ // 嵌套类型
+ std::shared_ptr<Row> GetStruct(int i) const;
+ std::shared_ptr<ArrayData> GetArray(int i) const;
+ std::shared_ptr<MapData> GetMap(int i) const;
+
+ // 元数据
+ int num_fields() const;
+ SchemaPtr schema() const;
+
+ // 调试
+ std::string ToString() const;
+};
+```
+
+### ArrayData 类
+
+`ArrayData` 类提供对列表/数组元素的访问：
+
+```cpp
+class ArrayData {
+public:
+ // 空值检查
+ bool IsNullAt(int i) const;
+
+ // 元素数量
+ int num_elements() const;
+
+ // 基本类型 getter（与 Row 相同）
+ int32_t GetInt32(int i) const;
+ // ... 其他基本类型
+
+ // 字符串 getter
+ std::string GetString(int i) const;
+
+ // 嵌套类型
+ std::shared_ptr<Row> GetStruct(int i) const;
+ std::shared_ptr<ArrayData> GetArray(int i) const;
+ std::shared_ptr<MapData> GetMap(int i) const;
+
+ // 类型信息
+ ListTypePtr type() const;
+};
+```
+
+### MapData 类
+
+`MapData` 类提供对 map 键值对的访问：
+
+```cpp
+class MapData {
+public:
+ // 元素数量
+ int num_elements();
+
+ // 以数组形式访问键和值
+ std::shared_ptr<ArrayData> keys_array();
+ std::shared_ptr<ArrayData> values_array();
+
+ // 类型信息
+ MapTypePtr type();
+};
+```
+
+## Schema 和类型
+
+### Schema 定义
+
+Schema 定义行数据的结构：
+
+```cpp
+#include "fory/row/schema.h"
+
+using namespace fory::row;
+
+// 以编程方式创建 schema
+auto person_schema = schema({
+ field("id", int32()),
+ field("name", utf8()),
+ field("score", float32()),
+ field("active", boolean())
+});
+
+// 访问 schema 信息
+for (const auto& f : person_schema->fields()) {
+ std::cout << f->name() << ": " << f->type()->name() << std::endl;
+}
+```
+
+### 类型系统
+
+行格式可用的类型：
+
+```cpp
+// 基本类型
+DataTypePtr boolean(); // bool
+DataTypePtr int8(); // int8_t
+DataTypePtr int16(); // int16_t
+DataTypePtr int32(); // int32_t
+DataTypePtr int64(); // int64_t
+DataTypePtr float32(); // float
+DataTypePtr float64(); // double
+
+// 字符串和二进制
+DataTypePtr utf8(); // std::string
+DataTypePtr binary(); // std::vector<uint8_t>
+
+// 复杂类型
+DataTypePtr list(DataTypePtr element_type);
+DataTypePtr map(DataTypePtr key_type, DataTypePtr value_type);
+DataTypePtr struct_(std::vector<FieldPtr> fields);
+```
+
+### 类型推断
+
+`RowEncodeTrait` 模板自动推断类型：
+
+```cpp
+// 基本类型的类型推断
+RowEncodeTrait<int32_t>::Type(); // 返回 int32()
+RowEncodeTrait<float>::Type(); // 返回 float32()
+RowEncodeTrait<std::string>::Type(); // 返回 utf8()
+
+// 集合的类型推断
+RowEncodeTrait<std::vector<int32_t>>::Type(); // 返回 list(int32())
+
+// map 的类型推断
+RowEncodeTrait<std::map<std::string, int32_t>>::Type();
+// 返回 map(utf8(), int32())
+
+// 结构体的类型推断（需要 FORY_FIELD_INFO）
+RowEncodeTrait<Person>::Type(); // 返回 struct_({...})
+RowEncodeTrait<Person>::Schema(); // 返回 schema({...})
+```
+
+## 行写入器
+
+### RowWriter
+
+用于手动构造行：
+
+```cpp
+#include "fory/row/writer.h"
+
+// 创建 schema
+auto my_schema = schema({
+ field("x", int32()),
+ field("y", float64()),
+ field("name", utf8())
+});
+
+// 创建写入器
+RowWriter writer(my_schema);
+writer.Reset();
+
+// 写入字段
+writer.Write(0, 42); // x = 42
+writer.Write(1, 3.14); // y = 3.14
+writer.WriteString(2, "test"); // name = "test"
+
+// 获取结果
+auto row = writer.ToRow();
+```
+
+### ArrayWriter
+
+用于手动构造数组：
+
+```cpp
+// 创建数组类型
+auto array_type = list(int32());
+
+// 创建写入器
+ArrayWriter writer(array_type);
+writer.Reset(5); // 5 个元素
+
+// 写入元素
+for (int i = 0; i < 5; i++) {
+ writer.Write(i, i * 10);
+}
+
+// 获取结果
+auto array = writer.CopyToArrayData();
+```
+
+### 空值
+
+```cpp
+// 在特定索引处设置空值
+writer.SetNullAt(2); // 字段 2 为空
+
+// 读取时检查空值
+if (!row->IsNullAt(2)) {
+ std::string value = row->GetString(2);
+}
+```
+
+## 内存布局
+
+### 行布局
+
+```
++------------------+--------------------+--------------------+
+| 空值位图 | 固定大小数据 | 变长数据 |
++------------------+--------------------+--------------------+
+| ceil(n/8) B | 8 * n 字节 | 可变 |
++------------------+--------------------+--------------------+
+```
+
+- **空值位图**：每字段一位，指示空值
+- **固定大小数据**：每字段 8 字节（基本类型直接存储，变长类型存储偏移量+大小）
+- **变长数据**：字符串、数组、嵌套结构体
+
+### 数组布局
+
+```
++------------+------------------+--------------------+--------------------+
+| 元素数量 | 空值位图 | 固定大小数据 | 变长数据 |
++------------+------------------+--------------------+--------------------+
+| 8 字节 | ceil(n/8) 字节 | elem_size * n | 可变 |
++------------+------------------+--------------------+--------------------+
+```
+
+### Map 布局
+
+```
++------------------+------------------+
+| 键数组 | 值数组 |
++------------------+------------------+
+```
+
+## 性能提示
+
+### 1. 复用编码器
+
+```cpp
+RowEncoder<Person> encoder;
+
+// 编码多条记录
+for (const auto& person : people) {
+ encoder.Encode(person);
+ auto row = encoder.GetWriter().ToRow();
+ // 处理 row...
+}
+```
+
+### 2. 预分配缓冲区
+
+```cpp
+// 获取缓冲区引用进行预分配
+auto& buffer = encoder.GetWriter().buffer();
+buffer->Reserve(expected_size);
+```
+
+### 3. 批量处理
+
+```cpp
+// 批量处理以提高缓存利用率
+std::vector<Person> batch;
+batch.reserve(BATCH_SIZE);
+
+while (hasMore()) {
+ batch.clear();
+ fillBatch(batch);
+
+ for (const auto& person : batch) {
+ encoder.Encode(person);
+ process(encoder.GetWriter().ToRow());
+ }
+}
+```
+
+### 4. 零拷贝读取
+
+```cpp
+// 指向现有缓冲区（零拷贝）
+Row row(schema);
+row.PointTo(buffer, offset, size);
+
+// 直接从缓冲区访问字段
+int32_t id = row.GetInt32(0);
+```
+
+## 支持类型汇总
+
+| C++ 类型 | 行类型 | 固定大小 |
+| ------------------------ | ---------------- | -------- |
+| `bool` | `boolean()` | 1 字节 |
+| `int8_t` | `int8()` | 1 字节 |
+| `int16_t` | `int16()` | 2 字节 |
+| `int32_t` | `int32()` | 4 字节 |
+| `int64_t` | `int64()` | 8 字节 |
+| `float` | `float32()` | 4 字节 |
+| `double` | `float64()` | 8 字节 |
+| `std::string` | `utf8()` | 可变 |
+| `std::vector<T>` | `list(T)` | 可变 |
+| `std::map<K,V>` | `map(K,V)` | 可变 |
+| `std::optional<T>` | 内部类型 | 可空 |
+| 结构体 (FORY_FIELD_INFO) | `struct_({...})` | 可变 |
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 对象图序列化
+- [配置](configuration.md) - 构建器选项
+- [支持的类型](supported-types.md) - 所有支持的类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/schema-evolution.md
new file mode 100644
index 000000000..ac80a3a85
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/schema-evolution.md
@@ -0,0 +1,404 @@
+---
+title: Schema 演化
+sidebar_position: 3
+id: cpp_schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 在 **Compatible 模式**下支持 schema 演化，允许序列化和反序列化双方拥有不同的类型定义。
+
+## Compatible 模式
+
+使用 `compatible(true)` 启用 schema 演化：
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+// 版本 1：原始 schema
+struct PersonV1 {
+ std::string name;
+ int32_t age;
+};
+FORY_STRUCT(PersonV1, name, age);
+
+// 版本 2：添加 email 字段
+struct PersonV2 {
+ std::string name;
+ int32_t age;
+ std::string email; // 新字段
+};
+FORY_STRUCT(PersonV2, name, age, email);
+
+int main() {
+ // 为每个 schema 版本创建单独的 Fory 实例
+ auto fory_v1 = Fory::builder()
+ .compatible(true) // 启用 schema 演化
+ .xlang(true)
+ .build();
+
+ auto fory_v2 = Fory::builder()
+ .compatible(true)
+ .xlang(true)
+ .build();
+
+ // 使用相同的类型 ID 进行 schema 演化
+ constexpr uint32_t PERSON_TYPE_ID = 100;
+ fory_v1.register_struct<PersonV1>(PERSON_TYPE_ID);
+ fory_v2.register_struct<PersonV2>(PERSON_TYPE_ID);
+
+ // 使用 V1 序列化
+ PersonV1 v1{"Alice", 30};
+ auto bytes = fory_v1.serialize(v1).value();
+
+ // 反序列化为 V2 - email 获得默认值（空字符串）
+ auto v2 = fory_v2.deserialize<PersonV2>(bytes).value();
+ assert(v2.name == "Alice");
+ assert(v2.age == 30);
+ assert(v2.email == ""); // 缺失字段的默认值
+
+ return 0;
+}
+```
+
+## Schema 演化特性
+
+Compatible 模式支持以下 schema 变更：
+
+| 变更类型 | 支持 | 行为 |
+| ------------ | ---- | ---------------------------- |
+| 添加新字段 | ✅ | 缺失字段使用默认值 |
+| 删除字段 | ✅ | 额外字段被跳过 |
+| 重排字段顺序 | ✅ | 按名称匹配字段，而非位置 |
+| 更改可空性 | ✅ | `T` ↔ `std::optional<T>` |
+| 更改字段类型 | ❌ | 类型必须兼容 |
+| 重命名字段 | ❌ | 字段名必须匹配（区分大小写） |
+
+## 添加字段（向后兼容）
+
+当使用具有额外字段的新 schema 反序列化旧数据时：
+
+```cpp
+// 旧 schema (V1)
+struct ProductV1 {
+ std::string name;
+ double price;
+};
+FORY_STRUCT(ProductV1, name, price);
+
+// 新 schema (V2) 带有额外字段
+struct ProductV2 {
+ std::string name;
+ double price;
+ std::vector<std::string> tags; // 新字段
+ std::map<std::string, std::string> attributes; // 新字段
+};
+FORY_STRUCT(ProductV2, name, price, tags, attributes);
+
+// 序列化 V1
+ProductV1 v1{"Laptop", 999.99};
+auto bytes = fory_v1.serialize(v1).value();
+
+// 反序列化为 V2
+auto v2 = fory_v2.deserialize<ProductV2>(bytes).value();
+assert(v2.name == "Laptop");
+assert(v2.price == 999.99);
+assert(v2.tags.empty()); // 默认：空 vector
+assert(v2.attributes.empty()); // 默认：空 map
+```
+
+## 删除字段（向前兼容）
+
+当使用具有较少字段的旧 schema 反序列化新数据时：
+
+```cpp
+// 完整 schema
+struct UserFull {
+ int64_t id;
+ std::string username;
+ std::string email;
+ std::string password_hash;
+ int32_t login_count;
+};
+FORY_STRUCT(UserFull, id, username, email, password_hash, login_count);
+
+// 精简 schema（删除了 3 个字段）
+struct UserMinimal {
+ int64_t id;
+ std::string username;
+};
+FORY_STRUCT(UserMinimal, id, username);
+
+// 序列化完整版本
+UserFull full{12345, "johndoe", "john@example.com", "hash123", 42};
+auto bytes = fory_full.serialize(full).value();
+
+// 反序列化为精简版本 - 额外字段被跳过
+auto minimal = fory_minimal.deserialize<UserMinimal>(bytes).value();
+assert(minimal.id == 12345);
+assert(minimal.username == "johndoe");
+// email、password_hash、login_count 被跳过
+```
+
+## 字段重排
+
+在 compatible 模式下，字段按名称匹配，而非位置：
+
+```cpp
+// 原始字段顺序
+struct ConfigOriginal {
+ std::string host;
+ int32_t port;
+ bool enable_ssl;
+ std::string protocol;
+};
+FORY_STRUCT(ConfigOriginal, host, port, enable_ssl, protocol);
+
+// 重排后的字段
+struct ConfigReordered {
+ bool enable_ssl; // 移到第一位
+ std::string protocol; // 移到第二位
+ std::string host; // 移到第三位
+ int32_t port; // 移到最后
+};
+FORY_STRUCT(ConfigReordered, enable_ssl, protocol, host, port);
+
+// 使用原始顺序序列化
+ConfigOriginal orig{"localhost", 8080, true, "https"};
+auto bytes = fory_orig.serialize(orig).value();
+
+// 使用不同字段顺序反序列化 - 正常工作
+auto reordered = fory_reord.deserialize<ConfigReordered>(bytes).value();
+assert(reordered.host == "localhost");
+assert(reordered.port == 8080);
+assert(reordered.enable_ssl == true);
+assert(reordered.protocol == "https");
+```
+
+## 嵌套结构体演化
+
+Schema 演化递归支持嵌套结构体：
+
+```cpp
+// V1 Address
+struct AddressV1 {
+ std::string street;
+ std::string city;
+};
+FORY_STRUCT(AddressV1, street, city);
+
+// V2 Address 带有新字段
+struct AddressV2 {
+ std::string street;
+ std::string city;
+ std::string country; // 新字段
+ std::string zipcode; // 新字段
+};
+FORY_STRUCT(AddressV2, street, city, country, zipcode);
+
+// V1 Employee 使用 V1 Address
+struct EmployeeV1 {
+ std::string name;
+ AddressV1 home_address;
+};
+FORY_STRUCT(EmployeeV1, name, home_address);
+
+// V2 Employee 使用 V2 Address 和新字段
+struct EmployeeV2 {
+ std::string name;
+ AddressV2 home_address; // 嵌套结构体已演化
+ std::string employee_id; // 新字段
+};
+FORY_STRUCT(EmployeeV2, name, home_address, employee_id);
+
+// 使用相同 ID 注册类型
+constexpr uint32_t ADDRESS_TYPE_ID = 100;
+constexpr uint32_t EMPLOYEE_TYPE_ID = 101;
+
+fory_v1.register_struct<AddressV1>(ADDRESS_TYPE_ID);
+fory_v1.register_struct<EmployeeV1>(EMPLOYEE_TYPE_ID);
+fory_v2.register_struct<AddressV2>(ADDRESS_TYPE_ID);
+fory_v2.register_struct<EmployeeV2>(EMPLOYEE_TYPE_ID);
+
+// 序列化 V1
+EmployeeV1 emp_v1{"Jane Doe", {"123 Main St", "NYC"}};
+auto bytes = fory_v1.serialize(emp_v1).value();
+
+// 反序列化为 V2
+auto emp_v2 = fory_v2.deserialize<EmployeeV2>(bytes).value();
+assert(emp_v2.name == "Jane Doe");
+assert(emp_v2.home_address.street == "123 Main St");
+assert(emp_v2.home_address.city == "NYC");
+assert(emp_v2.home_address.country == ""); // 默认值
+assert(emp_v2.home_address.zipcode == ""); // 默认值
+assert(emp_v2.employee_id == ""); // 默认值
+```
+
+## 双向演化
+
+Schema 演化双向工作：
+
+```cpp
+// V2 -> V1（降级）
+PersonV2 v2{"Charlie", 35, "charlie@example.com"};
+auto bytes = fory_v2.serialize(v2).value();
+
+auto v1 = fory_v1.deserialize<PersonV1>(bytes).value();
+assert(v1.name == "Charlie");
+assert(v1.age == 35);
+// email 字段在反序列化时被丢弃
+```
+
+## 默认值
+
+当字段缺失时，使用 C++ 默认初始化：
+
+| 类型 | 默认值 |
+| ---------------------- | -------------- |
+| `int8_t`、`int16_t`... | `0` |
+| `float`、`double` | `0.0` |
+| `bool` | `false` |
+| `std::string` | `""` |
+| `std::vector<T>` | 空 vector |
+| `std::map<K,V>` | 空 map |
+| `std::set<T>` | 空 set |
+| `std::optional<T>` | `std::nullopt` |
+| 结构体类型 | 默认构造 |
+
+## SchemaConsistent 模式（默认）
+
+不使用 compatible 模式时，schema 必须完全匹配：
+
+```cpp
+// 严格模式（默认）
+auto fory = Fory::builder()
+ .compatible(false) // 默认：schema 必须匹配
+ .xlang(true)
+ .build();
+
+// 序列化/反序列化要求相同的 schema
+// Schema 不匹配可能导致错误或未定义行为
+```
+
+**何时使用 SchemaConsistent 模式：**
+
+- Schema 保证匹配（相同的二进制版本）
+- 需要最高性能（更少的元数据开销）
+- 您同时控制序列化和反序列化
+
+**何时使用 Compatible 模式：**
+
+- Schema 可能独立演化
+- 需要跨版本兼容性
+- 不同服务可能有不同的 schema 版本
+
+## 类型 ID 要求
+
+要使 schema 演化正常工作：
+
+1. **相同类型 ID**：同一结构体的不同版本必须使用相同的类型 ID
+2. **一致的 ID**：类型 ID 必须在所有 Fory 实例中保持一致
+3. **注册所有版本**：每个 Fory 实例注册自己的结构体版本
+
+```cpp
+constexpr uint32_t PERSON_TYPE_ID = 100;
+
+// 实例 1 使用 PersonV1
+fory_v1.register_struct<PersonV1>(PERSON_TYPE_ID);
+
+// 实例 2 使用 PersonV2
+fory_v2.register_struct<PersonV2>(PERSON_TYPE_ID);
+
+// 相同的类型 ID 启用 schema 演化
+```
+
+## 最佳实践
+
+### 1. 为演化做规划
+
+设计 schema 时考虑未来的变更：
+
+```cpp
+// 好的做法：对可能删除的字段使用 optional
+struct Config {
+ std::string host;
+ int32_t port;
+ std::optional<std::string> deprecated_field; // 以后可以删除
+};
+```
+
+### 2. 使用有意义的默认值
+
+考虑新字段使用什么默认值才有意义：
+
+```cpp
+struct Settings {
+ int32_t timeout_ms; // 默认：0（可能需要一个合理的默认值）
+ bool enabled; // 默认：false
+ std::string mode; // 默认：""（可能需要 "default"）
+};
+```
+
+### 3. 记录 Schema 版本
+
+跟踪 schema 变更以便调试：
+
+```cpp
+// V1：初始 schema（2024-01-01）
+// V2：添加 email 字段（2024-02-01）
+// V3：添加 phone、address 字段（2024-03-01）
+```
+
+### 4. 测试演化路径
+
+测试升级和降级场景：
+
+```cpp
+// 测试 V1 -> V2
+// 测试 V2 -> V1
+// 测试 V1 -> V3
+// 测试 V3 -> V1
+```
+
+## 跨语言 Schema 演化
+
+使用 xlang 模式时，schema 演化跨语言工作：
+
+```cpp
+// 使用 compatible 模式的 C++
+auto fory = Fory::builder()
+ .compatible(true)
+ .xlang(true)
+ .build();
+```
+
+```java
+// 使用 compatible 模式的 Java
+Fory fory = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ .withLanguage(Language.XLANG)
+ .build();
+```
+
+即使 schema 版本不同，两个实例也可以交换数据。
+
+## 相关主题
+
+- [配置](configuration.md) - 启用 compatible 模式
+- [类型注册](type-registration.md) - 类型 ID 管理
+- [跨语言](cross-language.md) - 跨语言注意事项
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/supported-types.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/supported-types.md
new file mode 100644
index 000000000..e89b3bfa6
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/supported-types.md
@@ -0,0 +1,277 @@
+---
+title: 支持的类型
+sidebar_position: 5
+id: cpp_supported_types
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页记录 Fory C++ 序列化支持的所有类型。
+
+## 基本类型
+
+所有 C++ 基本类型都支持高效的二进制编码：
+
+| 类型 | 大小 | Fory TypeId | 说明 |
+| ---------- | ------ | ----------- | ------------------ |
+| `bool` | 1 字节 | BOOL | True/false |
+| `int8_t` | 1 字节 | INT8 | 有符号字节 |
+| `uint8_t` | 1 字节 | INT8 | 无符号字节 |
+| `int16_t` | 2 字节 | INT16 | 有符号短整型 |
+| `uint16_t` | 2 字节 | INT16 | 无符号短整型 |
+| `int32_t` | 4 字节 | INT32 | 有符号整型 |
+| `uint32_t` | 4 字节 | INT32 | 无符号整型 |
+| `int64_t` | 8 字节 | INT64 | 有符号长整型 |
+| `uint64_t` | 8 字节 | INT64 | 无符号长整型 |
+| `float` | 4 字节 | FLOAT32 | IEEE 754 单精度 |
+| `double` | 8 字节 | FLOAT64 | IEEE 754 双精度 |
+| `char` | 1 字节 | INT8 | 字符（作为有符号） |
+| `char16_t` | 2 字节 | INT16 | 16 位字符 |
+| `char32_t` | 4 字节 | INT32 | 32 位字符 |
+
+```cpp
+int32_t value = 42;
+auto bytes = fory.serialize(value).value();
+auto decoded = fory.deserialize<int32_t>(bytes).value();
+assert(value == decoded);
+```
+
+## 字符串类型
+
+| 类型 | Fory TypeId | 说明 |
+| ------------------ | ----------- | ------------------ |
+| `std::string` | STRING | UTF-8 编码 |
+| `std::string_view` | STRING | 零拷贝视图（读取） |
+| `std::u16string` | STRING | UTF-16（转换） |
+| `binary` | BINARY | 无长度的原始字节 |
+
+```cpp
+std::string text = "Hello, World!";
+auto bytes = fory.serialize(text).value();
+auto decoded = fory.deserialize<std::string>(bytes).value();
+assert(text == decoded);
+```
+
+## 集合类型
+
+### Vector / List
+
+`std::vector<T>` 支持任何可序列化的元素类型：
+
+```cpp
+std::vector<int32_t> numbers{1, 2, 3, 4, 5};
+auto bytes = fory.serialize(numbers).value();
+auto decoded = fory.deserialize<std::vector<int32_t>>(bytes).value();
+
+// 嵌套 vector
+std::vector<std::vector<std::string>> nested{
+ {"a", "b"},
+ {"c", "d", "e"}
+};
+```
+
+### Set
+
+`std::set<T>` 和 `std::unordered_set<T>`：
+
+```cpp
+std::set<std::string> tags{"cpp", "serialization", "fory"};
+auto bytes = fory.serialize(tags).value();
+auto decoded = fory.deserialize<std::set<std::string>>(bytes).value();
+
+std::unordered_set<int32_t> ids{1, 2, 3};
+```
+
+### Map
+
+`std::map<K, V>` 和 `std::unordered_map<K, V>`：
+
+```cpp
+std::map<std::string, int32_t> scores{
+ {"Alice", 100},
+ {"Bob", 95}
+};
+auto bytes = fory.serialize(scores).value();
+auto decoded = fory.deserialize<std::map<std::string, int32_t>>(bytes).value();
+
+// 无序 map
+std::unordered_map<int32_t, std::string> lookup{
+ {1, "one"},
+ {2, "two"}
+};
+```
+
+## 智能指针
+
+### std::optional
+
+任何类型的可空包装：
+
+```cpp
+std::optional<int32_t> maybe_value = 42;
+std::optional<int32_t> empty_value = std::nullopt;
+
+auto bytes = fory.serialize(maybe_value).value();
+auto decoded = fory.deserialize<std::optional<int32_t>>(bytes).value();
+assert(decoded.has_value() && *decoded == 42);
+```
+
+### std::shared_ptr
+
+带引用跟踪的共享所有权：
+
+```cpp
+auto shared = std::make_shared<Person>("Alice", 30);
+
+auto bytes = fory.serialize(shared).value();
+auto decoded = fory.deserialize<std::shared_ptr<Person>>(bytes).value();
+```
+
+**启用引用跟踪（`track_ref(true)`）时：**
+
+- 共享对象只序列化一次
+- 对同一对象的引用被保留
+- 循环引用自动处理
+
+### std::unique_ptr
+
+独占所有权：
+
+```cpp
+auto unique = std::make_unique<Person>("Bob", 25);
+
+auto bytes = fory.serialize(unique).value();
+auto decoded = fory.deserialize<std::unique_ptr<Person>>(bytes).value();
+```
+
+## Variant 类型
+
+`std::variant<Ts...>` 用于类型安全的联合：
+
+```cpp
+using MyVariant = std::variant<int32_t, std::string, double>;
+
+MyVariant v1 = 42;
+MyVariant v2 = std::string("hello");
+MyVariant v3 = 3.14;
+
+auto bytes = fory.serialize(v1).value();
+auto decoded = fory.deserialize<MyVariant>(bytes).value();
+assert(std::get<int32_t>(decoded) == 42);
+```
+
+### std::monostate
+
+空 variant 替代：
+
+```cpp
+using OptionalInt = std::variant<std::monostate, int32_t>;
+
+OptionalInt empty = std::monostate{};
+OptionalInt value = 42;
+```
+
+## 时间类型
+
+### Duration
+
+`std::chrono::nanoseconds`：
+
+```cpp
+using Duration = std::chrono::nanoseconds;
+
+Duration d = std::chrono::seconds(30);
+auto bytes = fory.serialize(d).value();
+auto decoded = fory.deserialize<Duration>(bytes).value();
+```
+
+### Timestamp
+
+自 Unix 纪元以来的时间点：
+
+```cpp
+using Timestamp = std::chrono::time_point<std::chrono::system_clock,
+ std::chrono::nanoseconds>;
+
+Timestamp now = std::chrono::system_clock::now();
+auto bytes = fory.serialize(now).value();
+auto decoded = fory.deserialize<Timestamp>(bytes).value();
+```
+
+### LocalDate
+
+自 Unix 纪元以来的天数：
+
+```cpp
+LocalDate date{18628}; // 自 1970-01-01 以来的天数
+
+auto bytes = fory.serialize(date).value();
+auto decoded = fory.deserialize<LocalDate>(bytes).value();
+```
+
+## 用户定义结构体
+
+任何结构体都可以使用 `FORY_STRUCT` 进行序列化：
+
+```cpp
+struct Point {
+ double x;
+ double y;
+ double z;
+};
+FORY_STRUCT(Point, x, y, z);
+
+struct Line {
+ Point start;
+ Point end;
+ std::string label;
+};
+FORY_STRUCT(Line, start, end, label);
+```
+
+## 枚举类型
+
+使用 `FORY_ENUM` 支持作用域和非作用域枚举：
+
+```cpp
+// 作用域枚举（C++11 enum class）
+enum class Color { RED = 0, GREEN = 1, BLUE = 2 };
+
+// 非连续值的非作用域枚举
+enum Priority : int32_t { LOW = -10, NORMAL = 0, HIGH = 10 };
+FORY_ENUM(Priority, LOW, NORMAL, HIGH);
+
+// 使用
+Color c = Color::GREEN;
+auto bytes = fory.serialize(c).value();
+auto decoded = fory.deserialize<Color>(bytes).value();
+```
+
+## 不支持的类型
+
+当前不支持：
+
+- 原始指针（`T*`）- 使用智能指针代替
+- `std::tuple<Ts...>` - 使用结构体代替
+- `std::array<T, N>` - 使用 `std::vector<T>` 代替
+- 函数指针
+- 引用（`T&`、`const T&`）- 仅支持按值传递
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 使用这些类型
+- [类型注册](type-registration.md) - 注册类型
+- [跨语言](cross-language.md) - 跨语言兼容性
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/type-registration.md
new file mode 100644
index 000000000..badc70fef
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/cpp/type-registration.md
@@ -0,0 +1,225 @@
+---
+title: 类型注册
+sidebar_position: 4
+id: cpp_type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何注册类型以进行序列化。
+
+## 概述
+
+Apache Fory™ 要求显式注册结构体类型。这种设计使得：
+
+- **跨语言兼容性**：注册的类型 ID 跨语言边界使用
+- **类型安全**：在反序列化时检测类型不匹配
+- **多态序列化**：通过智能指针启用多态对象的序列化
+
+## 注册结构体
+
+使用 `register_struct<T>(type_id)` 注册结构体类型：
+
+```cpp
+#include "fory/serialization/fory.h"
+
+using namespace fory::serialization;
+
+struct Person {
+ std::string name;
+ int32_t age;
+};
+FORY_STRUCT(Person, name, age);
+
+int main() {
+ auto fory = Fory::builder().xlang(true).build();
+
+ // 使用唯一的类型 ID 注册
+ fory.register_struct<Person>(100);
+
+ Person person{"Alice", 30};
+ auto bytes = fory.serialize(person).value();
+ auto decoded = fory.deserialize<Person>(bytes).value();
+}
+```
+
+## 类型 ID 指南
+
+类型 ID 必须：
+
+1. **唯一**：每个类型在 Fory 实例中必须有唯一的 ID
+2. **一致**：必须在所有语言和版本中使用相同的 ID
+
+用户注册的类型 ID 与内置类型 ID 在不同的命名空间中，因此可以从 0 开始：
+
+```cpp
+// 用户类型 ID 可以从 0 开始
+fory.register_struct<Address>(0);
+fory.register_struct<Person>(1);
+fory.register_struct<Order>(2);
+```
+
+## 注册枚举
+
+使用 `register_enum<T>(type_id)` 注册枚举类型。对于从 0 开始连续值的简单枚举，不需要宏：
+
+```cpp
+// 简单连续枚举 - 不需要 FORY_ENUM
+enum class Color { RED, GREEN, BLUE }; // 值：0、1、2
+
+// 使用 register_enum 注册
+fory.register_enum<Color>(0);
+```
+
+对于具有非连续值的枚举，使用 `FORY_ENUM` 宏将值映射到序号：
+
+```cpp
+// 非连续枚举值 - 需要 FORY_ENUM
+enum class Priority { LOW = 10, MEDIUM = 50, HIGH = 100 };
+FORY_ENUM(Priority, LOW, MEDIUM, HIGH);
+
+// 全局命名空间枚举（前缀 ::）
+enum LegacyStatus { UNKNOWN = -1, OK = 0, ERROR = 1 };
+FORY_ENUM(::LegacyStatus, UNKNOWN, OK, ERROR);
+
+// FORY_ENUM 后注册
+fory.register_enum<Priority>(1);
+fory.register_enum<LegacyStatus>(2);
+```
+
+**何时使用 `FORY_ENUM`：**
+
+- 枚举值不从 0 开始
+- 枚举值不连续（例如 10、50、100）
+- 需要在编译时进行名称到值的映射
+
+## 线程安全注册
+
+对于 `ThreadSafeFory`，在生成线程之前注册类型：
+
+```cpp
+auto fory = Fory::builder().xlang(true).build_thread_safe();
+
+// 首先注册所有类型
+fory.register_struct<TypeA>(100);
+fory.register_struct<TypeB>(101);
+
+// 现在可以从多个线程安全使用
+std::thread t1([&]() {
+ auto result = fory.serialize(obj_a);
+});
+std::thread t2([&]() {
+ auto result = fory.serialize(obj_b);
+});
+```
+
+## 跨语言注册
+
+为了跨语言兼容性，确保：
+
+1. **相同类型 ID**：在所有语言中使用相同的 ID
+2. **兼容类型**：跨语言使用等效类型
+
+### Java
+
+```java
+Fory fory = Fory.builder().build();
+fory.register(Person.class, 100);
+fory.register(Address.class, 101);
+```
+
+### Python
+
+```python
+import pyfory
+
+fory = pyfory.Fory()
+fory.register(Person, 100)
+fory.register(Address, 101)
+```
+
+### C++
+
+```cpp
+auto fory = Fory::builder().xlang(true).build();
+fory.register_struct<Person>(100);
+fory.register_struct<Address>(101);
+```
+
+## 内置类型 ID
+
+内置类型有预分配的类型 ID，不需要注册：
+
+| 类型 ID | 类型 |
+| ------- | -------------------- |
+| 0 | NONE |
+| 1 | BOOL |
+| 2 | INT8 |
+| 3 | INT16 |
+| 4 | INT32 |
+| 5 | VAR_INT32 |
+| 6 | INT64 |
+| 7 | VAR_INT64 |
+| 8 | SLI_INT64 |
+| 9 | FLOAT16 |
+| 10 | FLOAT32 |
+| 11 | FLOAT64 |
+| 12 | STRING |
+| 13 | LIST |
+| 14 | MAP |
+| 15 | SET |
+| 16 | TIMESTAMP |
+| 17 | DURATION |
+| 18 | LOCAL_DATE |
+| 19 | DECIMAL |
+| 20 | BINARY |
+| 21 | ARRAY |
+| 22 | BOOL_ARRAY |
+| 23-28 | INT_ARRAY 变体 |
+| 29-31 | FLOAT_ARRAY 变体 |
+| 32 | STRUCT |
+| 33 | COMPATIBLE_STRUCT |
+| 34 | NAMED_STRUCT |
+| 35 | NAMED*COMPATIBLE*... |
+| 36 | EXT |
+| 37 | NAMED_EXT |
+| 63 | UNKNOWN |
+
+## 错误处理
+
+注册错误在序列化/反序列化时检查：
+
+```cpp
+// 尝试序列化未注册的类型
+auto result = fory.serialize(unregistered_obj);
+if (!result.ok()) {
+ // 错误："Type not registered: ..."
+ std::cerr << result.error().to_string() << std::endl;
+}
+
+// 反序列化时类型 ID 不匹配
+auto result = fory.deserialize<WrongType>(bytes);
+if (!result.ok()) {
+ // 错误："Type mismatch: expected X, got Y"
+ std::cerr << result.error().to_string() << std::endl;
+}
+```
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 使用已注册的类型
+- [跨语言](cross-language.md) - 跨语言注意事项
+- [支持的类型](supported-types.md) - 所有支持的类型
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/graalvm_guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/graalvm_guide.md
new file mode 100644
index 000000000..56a1dc7b1
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/graalvm_guide.md
@@ -0,0 +1,318 @@
+---
+title: GraalVM 指南
+sidebar_position: 19
+id: graalvm_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+## GraalVM Native Image
+
+GraalVM `native image` 提前将 Java 代码编译为本地可执行文件，从而实现更快的启动速度和更低的内存使用。但是，本地镜像不支持运行时 JIT 编译或反射，除非进行显式配置。
+
+Apache Fory™ 通过**使用代码生成而非反射**，可以完美地与 GraalVM native image 配合使用。所有序列化器代码都在构建时生成，在大多数情况下无需反射配置文件。
+
+## 工作原理
+
+当您执行以下操作时，Fory 会在 GraalVM 构建时生成序列化代码：
+
+1. 将 Fory 创建为**静态**字段
+2. 在静态初始化器中**注册**所有类
+3. 调用 `fory.ensureSerializersCompiled()` 来编译序列化器
+4. 通过 `native-image.properties` 配置该类在构建时初始化
+
+**主要优势**：对于大多数可序列化的类，您无需配置[反射 json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json) 或[序列化 json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#serialization)。
+
+注意：Fory 的 `asyncCompilationEnabled` 选项在 GraalVM native image 中会自动禁用，因为不支持运行时 JIT。
+
+## 基础用法
+
+### 步骤 1：创建 Fory 并注册类
+
+```java
+import org.apache.fory.Fory;
+
+public class Example {
+ // 必须是静态字段
+ static Fory fory;
+
+ static {
+ fory = Fory.builder().build();
+ fory.register(MyClass.class);
+ fory.register(AnotherClass.class);
+ // 在构建时编译所有序列化器
+ fory.ensureSerializersCompiled();
+ }
+
+ public static void main(String[] args) {
+ byte[] bytes = fory.serialize(new MyClass());
+ MyClass obj = (MyClass) fory.deserialize(bytes);
+ }
+}
+```
+
+### 步骤 2：配置构建时初始化
+
+创建 `resources/META-INF/native-image/your-group/your-artifact/native-image.properties`：
+
+```properties
+Args = --initialize-at-build-time=com.example.Example
+```
+
+## ForyGraalVMFeature（可选）
+
+对于大多数具有公共构造函数的类型，上述基本设置就足够了。但是，一些高级情况需要反射注册：
+
+- **私有构造函数**（没有可访问的无参构造函数的类）
+- **私有内部类/记录**
+- **动态代理序列化**
+
+`fory-graalvm-feature` 模块会自动处理这些情况，无需手动配置 `reflect-config.json`。
+
+### 添加依赖
+
+```xml
+<dependency>
+ <groupId>org.apache.fory</groupId>
+ <artifactId>fory-graalvm-feature</artifactId>
+ <version>${fory.version}</version>
+</dependency>
+```
+
+### 启用功能
+
+将以下内容添加到您的 `native-image.properties`：
+
+```properties
+Args = --initialize-at-build-time=com.example.Example \
+ --features=org.apache.fory.graalvm.feature.ForyGraalVMFeature
+```
+
+### ForyGraalVMFeature 处理的内容
+
+| 场景 | 不使用 Feature | 使用 Feature |
+| ------------------------ | --------------------------- | ------------ |
+| 具有无参构造函数的公共类 | ✅ 可工作 | ✅ 可工作 |
+| 私有构造函数 | ❌ 需要 reflect-config.json | ✅ 自动注册 |
+| 私有内部记录 | ❌ 需要 reflect-config.json | ✅ 自动注册 |
+| 动态代理 | ❌ 需要手动配置 | ✅ 自动注册 |
+
+### 私有记录示例
+
+```java
+public class Example {
+ // 私有内部记录 - 需要 ForyGraalVMFeature
+ private record PrivateRecord(int id, String name) {}
+
+ static Fory fory;
+
+ static {
+ fory = Fory.builder().build();
+ fory.register(PrivateRecord.class);
+ fory.ensureSerializersCompiled();
+ }
+}
+```
+
+### 动态代理示例
+
+```java
+import org.apache.fory.util.GraalvmSupport;
+
+public class ProxyExample {
+ public interface MyService {
+ String execute();
+ }
+
+ static Fory fory;
+
+ static {
+ fory = Fory.builder().build();
+ // 为序列化注册代理接口
+ GraalvmSupport.registerProxySupport(MyService.class);
+ fory.ensureSerializersCompiled();
+ }
+}
+```
+
+## 线程安全的 Fory
+
+对于多线程应用程序，使用 `ThreadLocalFory`：
+
+```java
+import org.apache.fory.Fory;
+import org.apache.fory.ThreadLocalFory;
+import org.apache.fory.ThreadSafeFory;
+
+public class ThreadSafeExample {
+ public record Foo(int f1, String f2, List<String> f3) {}
+
+ static ThreadSafeFory fory;
+
+ static {
+ fory = new ThreadLocalFory(classLoader -> {
+ Fory f = Fory.builder().build();
+ f.register(Foo.class);
+ f.ensureSerializersCompiled();
+ return f;
+ });
+ }
+
+ public static void main(String[] args) {
+ Foo foo = new Foo(10, "abc", List.of("str1", "str2"));
+ byte[] bytes = fory.serialize(foo);
+ Foo result = (Foo) fory.deserialize(bytes);
+ }
+}
+```
+
+## 故障排除
+
+### "Type is instantiated reflectively but was never registered"
+
+如果您看到此错误：
+
+```
+Type com.example.MyClass is instantiated reflectively but was never registered
+```
+
+**解决方案**：使用 Fory 注册该类（不要添加到 reflect-config.json）：
+
+```java
+fory.register(MyClass.class);
+fory.ensureSerializersCompiled();
+```
+
+如果该类具有私有构造函数，可以：
+
+1. 添加 `fory-graalvm-feature` 依赖，或
+2. 为该特定类创建 `reflect-config.json`
+
+## 框架集成
+
+对于集成 Fory 的框架开发者：
+
+1. 为用户提供配置文件以列出可序列化的类
+2. 加载这些类并为每个类调用 `fory.register(Class<?>)`
+3. 完成所有注册后调用 `fory.ensureSerializersCompiled()`
+4. 配置您的集成类以在构建时初始化
+
+## 基准测试
+
+Fory 与 GraalVM JDK 序列化的性能比较：
+
+| 类型 | 压缩 | 速度 | 大小 |
+| ------ | ---- | --------- | ---- |
+| Struct | 关闭 | 46 倍更快 | 43% |
+| Struct | 开启 | 24 倍更快 | 31% |
+| Pojo | 关闭 | 12 倍更快 | 56% |
+| Pojo | 开启 | 12 倍更快 | 48% |
+
+查看 [Benchmark.java](https://github.com/apache/fory/blob/main/integration_tests/graalvm_tests/src/main/java/org/apache/fory/graalvm/Benchmark.java) 获取基准测试代码。
+
+### Struct 基准测试
+
+#### 类字段
+
+```java
+public class Struct implements Serializable {
+ public int f1;
+ public long f2;
+ public float f3;
+ public double f4;
+ public int f5;
+ public long f6;
+ public float f7;
+ public double f8;
+ public int f9;
+ public long f10;
+ public float f11;
+ public double f12;
+}
+```
+
+#### 基准测试结果
+
+无压缩：
+
+```
+Benchmark repeat number: 400000
+Object type: class org.apache.fory.graalvm.Struct
+Compress number: false
+Fory size: 76.0
+JDK size: 178.0
+Fory serialization took mills: 49
+JDK serialization took mills: 2254
+Compare speed: Fory is 45.70x speed of JDK
+Compare size: Fory is 0.43x size of JDK
+```
+
+数字压缩：
+
+```
+Benchmark repeat number: 400000
+Object type: class org.apache.fory.graalvm.Struct
+Compress number: true
+Fory size: 55.0
+JDK size: 178.0
+Fory serialization took mills: 130
+JDK serialization took mills: 3161
+Compare speed: Fory is 24.16x speed of JDK
+Compare size: Fory is 0.31x size of JDK
+```
+
+### Pojo 基准测试
+
+#### 类字段
+
+```java
+public class Foo implements Serializable {
+ int f1;
+ String f2;
+ List<String> f3;
+ Map<String, Long> f4;
+}
+```
+
+#### 基准测试结果
+
+无压缩：
+
+```
+Benchmark repeat number: 400000
+Object type: class org.apache.fory.graalvm.Foo
+Compress number: false
+Fory size: 541.0
+JDK size: 964.0
+Fory serialization took mills: 1663
+JDK serialization took mills: 16266
+Compare speed: Fory is 12.19x speed of JDK
+Compare size: Fory is 0.56x size of JDK
+```
+
+数字压缩：
+
+```
+Benchmark repeat number: 400000
+Object type: class org.apache.fory.graalvm.Foo
+Compress number: true
+Fory size: 459.0
+JDK size: 964.0
+Fory serialization took mills: 1289
+JDK serialization took mills: 15069
+Compare speed: Fory is 12.11x speed of JDK
+Compare size: Fory is 0.48x size of JDK
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/_category_.json
new file mode 100644
index 000000000..3cb119d37
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "Java",
+ "position": 0,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/advanced-features.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/advanced-features.md
new file mode 100644
index 000000000..c73ec5470
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/advanced-features.md
@@ -0,0 +1,208 @@
+---
+title: 高级特性
+sidebar_position: 7
+id: java_advanced_features
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍高级特性，包括零拷贝序列化、深拷贝、内存管理和日志记录。
+
+## 零拷贝序列化
+
+Fory 支持零拷贝序列化，以高效处理大型二进制数据：
+
+```java
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+import org.apache.fory.serializer.BufferObject;
+import org.apache.fory.memory.MemoryBuffer;
+
+import java.util.*;
+import java.util.stream.Collectors;
+
+public class ZeroCopyExample {
+ // 注意 fory 实例应该复用，而不是每次都创建。
+ static Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .build();
+
+ public static void main(String[] args) {
+ List<Object> list = Arrays.asList("str", new byte[1000], new int[100], new double[100]);
+ Collection<BufferObject> bufferObjects = new ArrayList<>();
+ byte[] bytes = fory.serialize(list, e -> !bufferObjects.add(e));
+ List<MemoryBuffer> buffers = bufferObjects.stream()
+ .map(BufferObject::toBuffer).collect(Collectors.toList());
+ System.out.println(fory.deserialize(bytes, buffers));
+ }
+}
+```
+
+## 对象深拷贝
+
+Fory 提供高效的深拷贝功能：
+
+### 启用引用跟踪
+
+```java
+Fory fory = Fory.builder().withRefCopy(true).build();
+SomeClass a = xxx;
+SomeClass copied = fory.copy(a);
+```
+
+### 禁用引用跟踪（更好的性能）
+
+禁用时，深拷贝将忽略循环引用和共享引用。对象图的相同引用将在一次 `Fory#copy` 中被复制为不同的对象：
+
+```java
+Fory fory = Fory.builder().withRefCopy(false).build();
+SomeClass a = xxx;
+SomeClass copied = fory.copy(a);
+```
+
+## 内存分配自定义
+
+Fory 提供了 `MemoryAllocator` 接口，允许你自定义在序列化操作期间如何分配和增长内存缓冲区。这对于性能优化、内存池化或调试内存使用很有用。
+
+### MemoryAllocator 接口
+
+`MemoryAllocator` 接口定义了两个关键方法：
+
+```java
+public interface MemoryAllocator {
+ /**
+ * 分配具有指定初始容量的新 MemoryBuffer。
+ */
+ MemoryBuffer allocate(int initialCapacity);
+
+ /**
+ * 增长现有缓冲区以容纳新容量。
+ * 实现必须通过修改现有缓冲区实例来原地增长缓冲区。
+ */
+ MemoryBuffer grow(MemoryBuffer buffer, int newCapacity);
+}
+```
+
+### 使用自定义内存分配器
+
+你可以设置一个全局内存分配器，所有 `MemoryBuffer` 实例都将使用它：
+
+```java
+// 创建自定义分配器
+MemoryAllocator customAllocator = new MemoryAllocator() {
+ @Override
+ public MemoryBuffer allocate(int initialCapacity) {
+ // 为调试或池化添加额外容量
+ return MemoryBuffer.fromByteArray(new byte[initialCapacity + 100]);
+ }
+
+ @Override
+ public MemoryBuffer grow(MemoryBuffer buffer, int newCapacity) {
+ if (newCapacity <= buffer.size()) {
+ return buffer;
+ }
+
+ // 自定义增长策略 - 添加 100% 额外容量
+ int newSize = (int) (newCapacity * 2);
+ byte[] data = new byte[newSize];
+ buffer.copyToUnsafe(0, data, Platform.BYTE_ARRAY_OFFSET, buffer.size());
+ buffer.initHeapBuffer(data, 0, data.length);
+ return buffer;
+ }
+};
+
+// 全局设置自定义分配器
+MemoryBuffer.setGlobalAllocator(customAllocator);
+
+// 所有后续的 MemoryBuffer 分配都将使用你的自定义分配器
+Fory fory = Fory.builder().withLanguage(Language.JAVA).build();
+byte[] bytes = fory.serialize(someObject); // 使用自定义分配器
+```
+
+### 默认内存分配器行为
+
+默认分配器使用以下增长策略：
+
+- 对于小于 `BUFFER_GROW_STEP_THRESHOLD` (100MB) 的缓冲区：将容量乘以 2
+- 对于较大的缓冲区：将容量乘以 1.5（上限为 `Integer.MAX_VALUE - 8`）
+
+这在避免频繁重新分配和防止过度内存使用之间提供了平衡。
+
+### 使用场景
+
+自定义内存分配器适用于：
+
+- **内存池化**：重用分配的缓冲区以减少 GC 压力
+- **性能调优**：根据你的工作负载使用不同的增长策略
+- **调试**：添加日志记录或跟踪以监控内存使用
+- **堆外内存**：与堆外内存管理系统集成
+
+## 日志记录
+
+### ForyLogger
+
+默认情况下，Fory 使用自定义日志记录器 `ForyLogger` 来满足内部需求。它将生成的日志数据构建为单个字符串，并直接发送到 `System.out`。结果行布局类似于（Log4j 表示法）：
+
+```
+%d{yyyy-MM-dd hh:mm:ss} %p %C:%L [%t] - %m%n
+```
+
+布局无法更改。
+
+示例输出：
+
+```
+2025-11-07 08:49:59 INFO CompileUnit:55 [main] - Generate code for org.apache.fory.builder.SerializedLambdaForyCodec_0 took 35 ms.
+2025-11-07 08:50:00 INFO JaninoUtils:121 [main] - Compile [SerializedLambdaForyCodec_0] take 144 ms
+```
+
+### Slf4jLogger
+
+如果需要更复杂的日志记录器，可以通过 `LoggerFactory.useSlf4jLogging()` 配置 Fory 使用 Slf4j。例如，在创建 Fory 之前启用 Slf4j：
+
+```java
+public static final ThreadSafeFory FORY;
+
+static {
+ LoggerFactory.useSlf4jLogging(true);
+ FORY = Fory.builder()
+ .buildThreadSafeFory();
+}
+```
+
+**注意**：当应用程序在 GraalVM native image 中运行时，通过 `useSlf4jLogging` 启用 Slf4j 将被忽略。
+
+### 抑制 Fory 日志
+
+`ForyLogger` 和 `Slf4jLogger` 都允许控制日志输出级别或完全抑制日志。通过 `LoggerFactory.setLogLevel()` 配置日志级别：
+
+```java
+static {
+ // 只记录 WARN 及更高级别
+ LoggerFactory.setLogLevel(LogLevel.WARN_LEVEL);
+
+ // 完全禁用日志记录
+ LoggerFactory.disableLogging();
+}
+```
+
+**注意**：所选的日志级别在 Slf4j 实现的日志级别之前应用。因此，如果你设置 `WARN_LEVEL`（如上例），即使在 Logback 中启用了 INFO，你也不会看到来自 Fory 的 INFO 消息。
+
+## 相关主题
+
+- [压缩](compression.md) - 数据压缩选项
+- [配置选项](configuration.md) - 所有 ForyBuilder 选项
+- [跨语言序列化](cross-language.md) - XLANG 模式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/basic-serialization.md
new file mode 100644
index 000000000..7756bbd2a
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/basic-serialization.md
@@ -0,0 +1,137 @@
+---
+title: 基础序列化
+sidebar_position: 2
+id: java_basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍基本的序列化模式和 Fory 实例创建。
+
+## 创建 Fory 实例
+
+### 单线程 Fory
+
+对于单线程应用程序：
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ // 启用引用跟踪以支持共享/循环引用。
+ // 如果没有重复引用，禁用它会有更好的性能。
+ .withRefTracking(false)
+ .withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
+ // 启用类型前向/后向兼容性
+ // 禁用它以获得更小的大小和更好的性能。
+ // .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ // 启用异步多线程编译。
+ .withAsyncCompilation(true)
+ .build();
+byte[] bytes = fory.serialize(object);
+System.out.println(fory.deserialize(bytes));
+```
+
+### 线程安全 Fory
+
+对于多线程应用程序：
+
+```java
+ThreadSafeFory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ // 启用引用跟踪以支持共享/循环引用。
+ // 如果没有重复引用，禁用它会有更好的性能。
+ .withRefTracking(false)
+ // 压缩 int 以获得更小的大小
+ // .withIntCompressed(true)
+ // 压缩 long 以获得更小的大小
+ // .withLongCompressed(true)
+ .withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
+ // 启用类型前向/后向兼容性
+ // 禁用它以获得更小的大小和更好的性能。
+ // .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ // 启用异步多线程编译。
+ .withAsyncCompilation(true)
+ .buildThreadSafeFory();
+byte[] bytes = fory.serialize(object);
+System.out.println(fory.deserialize(bytes));
+```
+
+## 对象深拷贝
+
+Fory 提供高效的深拷贝功能：
+
+### 启用引用跟踪
+
+```java
+Fory fory = Fory.builder().withRefCopy(true).build();
+SomeClass a = xxx;
+SomeClass copied = fory.copy(a);
+```
+
+### 禁用引用跟踪（更好的性能）
+
+禁用时，深拷贝将忽略循环引用和共享引用。对象图的相同引用将在一次 `Fory#copy` 中被复制为不同的对象：
+
+```java
+Fory fory = Fory.builder().withRefCopy(false).build();
+SomeClass a = xxx;
+SomeClass copied = fory.copy(a);
+```
+
+## 序列化 API
+
+### 基本序列化/反序列化
+
+```java
+// 将对象序列化为字节数组
+byte[] bytes = fory.serialize(object);
+
+// 将字节数组反序列化为对象
+Object obj = fory.deserialize(bytes);
+```
+
+### 带类型的序列化/反序列化
+
+```java
+// 使用显式类型序列化
+byte[] bytes = fory.serializeJavaObject(object);
+
+// 使用预期类型反序列化
+MyClass obj = fory.deserializeJavaObject(bytes, MyClass.class);
+```
+
+### 带类型信息的序列化/反序列化
+
+```java
+// 带类型信息序列化
+byte[] bytes = fory.serializeJavaObjectAndClass(object);
+
+// 使用嵌入的类型信息反序列化
+Object obj = fory.deserializeJavaObjectAndClass(bytes);
+```
+
+## 最佳实践
+
+1. **复用 Fory 实例**：创建 Fory 成本很高，始终复用实例
+2. **使用适当的线程安全性**：根据需要在单线程和线程安全之间选择
+3. **注册类**：注册常用类以获得更好的性能
+4. **配置引用跟踪**：如果没有循环/共享引用，请禁用它
+
+## 相关主题
+
+- [配置选项](configuration.md) - 所有 ForyBuilder 选项
+- [类型注册](type-registration.md) - 类注册
+- [故障排除](troubleshooting.md) - 常见 API 使用问题
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/compression.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/compression.md
new file mode 100644
index 000000000..6cd40685b
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/compression.md
@@ -0,0 +1,136 @@
+---
+title: 压缩
+sidebar_position: 6
+id: java_compression
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍用于减少序列化数据大小的压缩选项。
+
+## 整数压缩
+
+`ForyBuilder#withIntCompressed`/`ForyBuilder#withLongCompressed` 可用于压缩 int/long 以获得更小的大小。通常压缩 int 就足够了。
+
+这两个压缩选项默认都是启用的。如果序列化大小不重要（例如，你之前使用 FlatBuffers 进行序列化，它不压缩任何东西），那么你应该禁用压缩。如果你的数据全是数字，压缩可能会带来 80% 的性能回退。
+
+### Int 压缩
+
+对于 int 压缩，Fory 使用 1~5 个字节进行编码。每个字节中的第一位表示是否有下一个字节。如果设置了第一位，则将读取下一个字节，直到下一个字节的第一位未设置。
+
+### Long 压缩
+
+对于 long 压缩，Fory 支持两种编码：
+
+#### SLI（Small Long as Int）编码（默认）
+
+- 如果 long 在 `[-1073741824, 1073741823]` 范围内，编码为 4 字节 int：`| little-endian: ((int) value) << 1 |`
+- 否则写为 9 字节：`| 0b1 | little-endian 8bytes long |`
+
+#### PVL（Progressive Variable-length Long）编码
+
+- 每个字节中的第一位表示是否有下一个字节。如果设置了第一位，则将读取下一个字节，直到下一个字节的第一位未设置。
+- 负数将通过 `(v << 1) ^ (v >> 63)` 转换为正数，以减少小负数的成本。
+
+如果数字是 `long` 类型，但大多数情况下不能用较小的字节表示，压缩不会得到足够好的结果——与性能成本相比不值得。如果你发现它没有带来太多空间节省，也许你应该尝试禁用 long 压缩。
+
+## 数组压缩
+
+当数组值可以适配较小的数据类型时，Fory 支持原始数组（`int[]` 和 `long[]`）的 SIMD 加速压缩。此功能在 Java 16+ 上可用，并使用 Vector API 以获得最佳性能。
+
+### 数组压缩工作原理
+
+数组压缩分析数组以确定值是否可以使用更少的字节存储：
+
+- **`int[]` → `byte[]`**：当所有值都在范围 [-128, 127] 内时（减少 75% 大小）
+- **`int[]` → `short[]`**：当所有值都在范围 [-32768, 32767] 内时（减少 50% 大小）
+- **`long[]` → `int[]`**：当所有值都适合整数范围时（减少 50% 大小）
+
+### 配置和注册
+
+要启用数组压缩，你必须显式注册序列化器：
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ // 启用 int 数组压缩
+ .withIntArrayCompressed(true)
+ // 启用 long 数组压缩
+ .withLongArrayCompressed(true)
+ .build();
+
+// 你必须显式注册压缩数组序列化器
+CompressedArraySerializers.registerSerializers(fory);
+```
+
+**注意**：必须在依赖项中包含 `fory-simd` 模块，压缩数组序列化器才可用。
+
+### Maven 依赖
+
+```xml
+<dependency>
+ <groupId>org.apache.fory</groupId>
+ <artifactId>fory-simd</artifactId>
+ <version>0.14.0</version>
+</dependency>
+```
+
+## 字符串压缩
+
+字符串压缩可以通过 `ForyBuilder#withStringCompressed(true)` 启用。这默认是禁用的。
+
+## 配置摘要
+
+| 选项 | 描述 | 默认值 |
+| ------------------- | ----------------------------------- | ------- |
+| `compressInt` | 启用 int 压缩 | `true` |
+| `compressLong` | 启用 long 压缩 | `true` |
+| `compressIntArray` | 启用 SIMD int 数组压缩（Java 16+） | `true` |
+| `compressLongArray` | 启用 SIMD long 数组压缩（Java 16+） | `true` |
+| `compressString` | 启用字符串压缩 | `false` |
+
+## 性能考虑
+
+1. **对数字密集型数据禁用压缩**：如果你的数据主要是数字，压缩开销可能不值得
+2. **数组压缩需要 Java 16+**：使用 Vector API 进行 SIMD 加速
+3. **Long 压缩可能对大值无用**：如果大多数 long 不能适配较小的表示，请禁用它
+4. **字符串压缩有开销**：仅在字符串高度可压缩时启用
+
+## 示例配置
+
+```java
+// 对于主要是数字的数据 - 禁用压缩
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withIntCompressed(false)
+ .withLongCompressed(false)
+ .build();
+
+// 对于包含数组的混合数据 - 启用数组压缩
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withIntCompressed(true)
+ .withLongCompressed(true)
+ .withIntArrayCompressed(true)
+ .withLongArrayCompressed(true)
+ .build();
+CompressedArraySerializers.registerSerializers(fory);
+```
+
+## 相关主题
+
+- [配置选项](configuration.md) - 所有 ForyBuilder 选项
+- [高级特性](advanced-features.md) - 内存管理
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/configuration.md
new file mode 100644
index 000000000..6d47bb547
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/configuration.md
@@ -0,0 +1,77 @@
+---
+title: 配置选项
+sidebar_position: 1
+id: java_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页记录通过 `ForyBuilder` 提供的所有配置选项。
+
+## ForyBuilder 选项
+
+| 选项名称 | 描述 | 默认值 |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `timeRefIgnored` | 当启用引用跟踪时，是否忽略在 `TimeSerializers` 中注册的所有时间类型及其子类的引用跟踪。如果忽略，可以通过调用 `Fory#registerSerializer(Class, Serializer)` 为每个时间类型启用引用跟踪。例如，`fory.registerSerializer(Date.class, new DateSerializer(fory, true))`。注意，启用引用跟踪应该在包含时间字段的任何类型的序列化器代码生成之前进行。否则，这些字段仍将跳过引用跟踪。 | `true` |
+| `compressInt` | 启用或禁用 int 压缩以获得更小的大小。 | `true` |
+| `compressLong` | 启用或禁用 long 压缩以获得更小的大小。 | `true` |
+| `compressIntArray` | 当值可以适配较小数据类型时，启用或禁用 int 数组的 SIMD 加速压缩。需要 Java 16+。 | `true` |
+| `compressLongArray` | 当值可以适配较小数据类型时，启用或禁用 long 数组的 SIMD 加速压缩。需要 Java 16+。 | `true` |
+| `compressString` | 启用或禁用字符串压缩以获得更小的大小。 | `false` |
+| `classLoader` | 不应更新类加载器；Fory 缓存类元数据。对于类加载器更新，请使用 `LoaderBinding` 或 `ThreadSafeFory`。 | `Thread.currentThread().getContextClassLoader()` |
+| `compatibleMode` | 类型前向/后向兼容性配置。也与 `checkClassVersion` 配置相关。`SCHEMA_CONSISTENT`：序列化端和反序列化端之间的类 schema 必须一致。`COMPATIBLE`：序列化端和反序列化端之间的类 schema 可以不同。它们可以独立添加/删除字段。[查看更多](schema-evolution.md)。 | `CompatibleMode.SCHEMA_CONSISTENT` |
+| `checkClassVersion` | 确定是否检查类 schema 的一致性。如果启用，Fory 会使用 `classVersionHash` 检查、写入和检查一致性。当启用 `CompatibleMode#COMPATIBLE` 时，它将自动禁用。除非你能确保类不会演化，否则不建议禁用。 | `false` |
+| `checkJdkClassSerializable` | 启用或禁用对 `java.*` 下的类的 `Serializable` 接口检查。如果 `java.*` 下的类不是 `Serializable`，Fory 将抛出 `UnsupportedOperationException`。 | `true` |
+| `registerGuavaTypes` | 是否预注册 Guava 类型，如 `RegularImmutableMap`/`RegularImmutableList`。这些类型不是公共 API，但似乎相当稳定。 | `true` |
+| `requireClassRegistration` | 禁用可能允许未知类被反序列化，可能导致安全风险。 | `true` |
+| `maxDepth` | 设置反序列化的最大深度，当深度超过时，将抛出异常。这可用于拒绝反序列化 DDOS 攻击。 | `50` |
+| `suppressClassRegistrationWarnings` | 是否抑制类注册警告。这些警告可用于安全审计，但可能很烦人，默认情况下将启用此抑制。 | `true` |
+| `metaShareEnabled` | 启用或禁用元数据共享模式。 | 如果设置了 `CompatibleMode.Compatible` 则为 `true`，否则为 false。 |
+| `scopedMetaShareEnabled` | 作用域元数据共享专注于单个序列化过程。在此过程中创建或识别的元数据是它专有的，不会与其他序列化共享。 | 如果设置了 `CompatibleMode.Compatible` 则为 `true`，否则为 false。 |
+| `metaCompressor` | 为元数据压缩设置压缩器。注意传递的 MetaCompressor 应该是线程安全的。默认情况下，将使用基于 `Deflater` 的压缩器 `DeflaterMetaCompressor`。用户可以传递其他压缩器，如 `zstd` 以获得更好的压缩率。 | `DeflaterMetaCompressor` |
+| `deserializeNonexistentClass` | 启用或禁用对不存在类的数据的反序列化/跳过。 | 如果设置了 `CompatibleMode.Compatible` 则为 `true`，否则为 false。 |
+| `codeGenEnabled` | 禁用可能导致更快的初始序列化，但后续序列化会更慢。 | `true` |
+| `asyncCompilationEnabled` | 如果启用，序列化首先使用解释器模式，在类的异步序列化器 JIT 完成后切换到 JIT 序列化。 | `false` |
+| `scalaOptimizationEnabled` | 启用或禁用 Scala 特定的序列化优化。 | `false` |
+| `copyRef` | 禁用时，拷贝性能会更好。但 Fory 深拷贝将忽略循环引用和共享引用。对象图的相同引用将在一次 `Fory#copy` 中被复制为不同的对象。 | `true` |
+| `serializeEnumByName` | 启用时，Fory 按名称而不是序数序列化枚举。 | `false` |
+
+## 示例配置
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ // 启用引用跟踪以支持共享/循环引用。
+ // 如果没有重复引用，禁用它会有更好的性能。
+ .withRefTracking(false)
+ // 压缩 int 以获得更小的大小
+ .withIntCompressed(true)
+ // 压缩 long 以获得更小的大小
+ .withLongCompressed(true)
+ .withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
+ // 启用类型前向/后向兼容性
+ // 禁用它以获得更小的大小和更好的性能。
+ // .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ // 启用异步多线程编译。
+ .withAsyncCompilation(true)
+ .build();
+```
+
+## 相关主题
+
+- [Schema 演化](schema-evolution.md) - 兼容模式和元数据共享
+- [压缩](compression.md) - Int、long 和数组压缩详情
+- [类型注册](type-registration.md) - 类注册选项
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/cross-language.md
new file mode 100644
index 000000000..92c1c7b8d
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/cross-language.md
@@ -0,0 +1,231 @@
+---
+title: 跨语言序列化
+sidebar_position: 8
+id: java_cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 通过 xlang 序列化格式支持 Java 和其他语言（Python、Rust、Go、JavaScript 等）之间的无缝数据交换。这使得多语言微服务、多语言数据管道和跨平台数据共享成为可能。
+
+## 启用跨语言模式
+
+要序列化供其他语言使用的数据，使用 `Language.XLANG` 模式：
+
+```java
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+
+// 使用 XLANG 模式创建 Fory 实例
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true) // 为复杂图启用引用跟踪
+ .build();
+```
+
+## 为跨语言兼容性注册类型
+
+类型必须使用**一致的 ID 或名称**在所有语言中注册。Fory 支持两种注册方法：
+
+### 按 ID 注册（推荐用于性能）
+
+```java
+public record Person(String name, int age) {}
+
+// 使用数字 ID 注册 - 更快更紧凑
+fory.register(Person.class, 1);
+
+Person person = new Person("Alice", 30);
+byte[] bytes = fory.serialize(person);
+// bytes 可以被 Python、Rust、Go 等反序列化。
+```
+
+**优点**：更快的序列化，更小的二进制大小
+**权衡**：需要协调以避免跨团队/服务的 ID 冲突
+
+### 按名称注册（推荐用于灵活性）
+
+```java
+public record Person(String name, int age) {}
+
+// 使用字符串名称注册 - 更灵活
+fory.register(Person.class, "example.Person");
+
+Person person = new Person("Alice", 30);
+byte[] bytes = fory.serialize(person);
+// bytes 可以被 Python、Rust、Go 等反序列化。
+```
+
+**优点**：不容易冲突，跨团队管理更容易，无需协调
+**权衡**：由于字符串编码，二进制大小稍大
+
+## 跨语言示例：Java ↔ Python
+
+### Java（序列化器）
+
+```java
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+
+public record Person(String name, int age) {}
+
+public class Example {
+ public static void main(String[] args) {
+ Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true)
+ .build();
+
+ // 使用一致的名称注册
+ fory.register(Person.class, "example.Person");
+
+ Person person = new Person("Bob", 25);
+ byte[] bytes = fory.serialize(person);
+
+ // 通过网络/文件/队列将 bytes 发送到 Python 服务
+ }
+}
+```
+
+### Python（反序列化器）
+
+```python
+import pyfory
+from dataclasses import dataclass
+
+@dataclass
+class Person:
+ name: str
+ age: pyfory.int32
+
+# 在 xlang 模式下创建 Fory
+fory = pyfory.Fory(ref_tracking=True)
+
+# 使用与 Java 相同的名称注册
+fory.register_type(Person, typename="example.Person")
+
+# 从 Java 反序列化 bytes
+person = fory.deserialize(bytes_from_java)
+print(f"{person.name}, {person.age}") # 输出：Bob, 25
+```
+
+## 处理循环引用和共享引用
+
+启用引用跟踪时，跨语言模式支持循环引用和共享引用：
+
+```java
+public class Node {
+ public String value;
+ public Node next;
+ public Node parent;
+}
+
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true) // 循环引用需要
+ .build();
+
+fory.register(Node.class, "example.Node");
+
+// 创建循环引用
+Node node1 = new Node();
+node1.value = "A";
+Node node2 = new Node();
+node2.value = "B";
+node1.next = node2;
+node2.parent = node1; // 循环引用
+
+byte[] bytes = fory.serialize(node1);
+// Python/Rust/Go 可以正确反序列化这个，并保留循环引用
+```
+
+## 类型映射考虑
+
+并非所有 Java 类型在其他语言中都有等价物。使用 xlang 模式时：
+
+- 使用**原始类型**（`int`、`long`、`double`、`String`）以获得最大兼容性
+- 使用**标准集合**（`List`、`Map`、`Set`）而不是特定于语言的集合
+- 避免 **Java 特定类型**，如 `Optional`、`BigDecimal`（除非目标语言支持它们）
+- 查看[类型映射指南](https://fory.apache.org/docs/specification/xlang_type_mapping)获取完整的兼容性矩阵
+
+### 兼容类型
+
+```java
+public record UserData(
+ String name, // ✅ 兼容
+ int age, // ✅ 兼容
+ List<String> tags, // ✅ 兼容
+ Map<String, Integer> scores // ✅ 兼容
+) {}
+```
+
+### 有问题的类型
+
+```java
+public record UserData(
+ Optional<String> name, // ❌ 不跨语言兼容
+ BigDecimal balance, // ❌ 支持有限
+ EnumSet<Status> statuses // ❌ Java 特定集合
+) {}
+```
+
+## 性能考虑
+
+跨语言模式相比仅 Java 模式有额外的开销：
+
+- **类型元数据编码**：每个类型添加额外字节
+- **类型解析**：在反序列化期间需要名称/ID 查找
+
+**为了最佳性能**：
+
+- 尽可能使用**基于 ID 的注册**（更小的编码）
+- 如果不需要循环引用，**禁用引用跟踪**（`withRefTracking(false)`）
+- 当只需要 Java 序列化时**使用 Java 模式**（`Language.JAVA`）
+
+## 跨语言最佳实践
+
+1. **一致的注册**：确保所有服务使用相同的 ID/名称注册类型
+2. **版本兼容性**：使用兼容模式跨服务进行 schema 演化
+
+## 跨语言序列化故障排除
+
+### "Type not registered" 错误
+
+- 验证类型在两端都使用相同的 ID/名称注册
+- 检查类型名称是否有拼写错误或大小写差异
+
+### "Type mismatch" 错误
+
+- 确保字段类型在语言之间兼容
+- 查看[类型映射指南](https://fory.apache.org/docs/next/specification/xlang_type_mapping)
+
+### 数据损坏或意外值
+
+- 验证两端都使用 `Language.XLANG` 模式
+- 确保两端具有兼容的 Fory 版本
+
+## 另请参阅
+
+- [跨语言序列化规范](https://fory.apache.org/docs/next/specification/fory_xlang_serialization_spec)
+- [类型映射参考](https://fory.apache.org/docs/next/specification/xlang_type_mapping)
+- [Python 跨语言指南](../python/cross-language.md)
+- [Rust 跨语言指南](../rust/cross-language.md)
+
+## 相关主题
+
+- [Schema 演化](schema-evolution.md) - 兼容模式
+- [类型注册](type-registration.md) - 注册方法
+- [行格式](row-format.md) - 跨语言行格式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/custom-serializers.md
new file mode 100644
index 000000000..f2b109682
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/custom-serializers.md
@@ -0,0 +1,659 @@
+---
+title: 自定义序列化器
+sidebar_position: 4
+id: java_custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何为你的类型实现自定义序列化器。
+
+## 基本自定义序列化器
+
+在某些情况下，你可能想为你的类型实现序列化器，特别是对于使用 JDK `writeObject/writeReplace/readObject/readResolve` 自定义序列化的类，这非常低效。
+
+例如，如果你不想调用以下 `Foo#writeObject`，你可以实现自定义序列化器：
+
+```java
+class Foo {
+ public long f1;
+
+ private void writeObject(ObjectOutputStream s) throws IOException {
+ System.out.println(f1);
+ s.defaultWriteObject();
+ }
+}
+
+class FooSerializer extends Serializer<Foo> {
+ public FooSerializer(Fory fory) {
+ super(fory, Foo.class);
+ }
+
+ @Override
+ public void write(MemoryBuffer buffer, Foo value) {
+ buffer.writeInt64(value.f1);
+ }
+
+ @Override
+ public Foo read(MemoryBuffer buffer) {
+ Foo foo = new Foo();
+ foo.f1 = buffer.readInt64();
+ return foo;
+ }
+}
+```
+
+### 注册序列化器
+
+```java
+Fory fory = getFory();
+fory.registerSerializer(Foo.class, new FooSerializer(fory));
+```
+
+除了注册序列化器，你还可以为类实现 `java.io.Externalizable` 来自定义序列化逻辑。这种类型将由 Fory 的 `ExternalizableSerializer` 序列化。
+
+## 集合序列化器
+
+在为自定义集合类型实现序列化器时，你必须扩展 `CollectionSerializer` 或 `CollectionLikeSerializer`。主要区别是 `CollectionLikeSerializer` 可以序列化具有类似集合结构但不是 Java Collection 子类型的类。
+
+### supportCodegenHook 参数
+
+这个特殊参数控制序列化行为：
+
+**当为 `true` 时：**
+
+- 启用对集合元素的优化访问和 JIT 编译以获得更好的性能
+- 直接序列化调用和内联集合项，无需动态序列化器分派成本
+- 对标准集合类型有更好的性能
+- 对大多数集合推荐
+
+**当为 `false` 时：**
+
+- 使用基于接口的元素访问和元素的动态序列化器分派（成本更高）
+- 对自定义集合类型更灵活
+- 当集合有特殊序列化需求时需要
+- 处理复杂的集合实现
+
+### 带 JIT 支持的集合序列化器
+
+在实现带 JIT 支持的集合序列化器时，利用 Fory 现有的二进制格式和集合序列化基础设施：
+
+```java
+public class CustomCollectionSerializer<T extends Collection> extends CollectionSerializer<T> {
+ public CustomCollectionSerializer(Fory fory, Class<T> cls) {
+ // supportCodegenHook 控制是否使用 JIT 编译
+ super(fory, cls, true);
+ }
+
+ @Override
+ public Collection onCollectionWrite(MemoryBuffer buffer, T value) {
+ // 写入集合大小
+ buffer.writeVarUint32Small7(value.size());
+ // 写入任何额外的集合元数据
+ return value;
+ }
+
+ @Override
+ public Collection newCollection(MemoryBuffer buffer) {
+ // 创建新的集合实例
+ Collection collection = super.newCollection(buffer);
+ // 读取并设置集合大小
+ int numElements = getAndClearNumElements();
+ setNumElements(numElements);
+ return collection;
+ }
+}
+```
+
+注意：在实现 `newCollection` 时调用 `setNumElements`，让 Fory 知道要反序列化多少元素。
+
+### 不带 JIT 的自定义集合序列化器
+
+对于使用原始数组或有特殊要求的集合，实现禁用 JIT 的序列化器：
+
+```java
+class IntList extends AbstractCollection<Integer> {
+ private final int[] elements;
+ private final int size;
+
+ public IntList(int size) {
+ this.elements = new int[size];
+ this.size = size;
+ }
+
+ public IntList(int[] elements, int size) {
+ this.elements = elements;
+ this.size = size;
+ }
+
+ @Override
+ public Iterator<Integer> iterator() {
+ return new Iterator<Integer>() {
+ private int index = 0;
+
+ @Override
+ public boolean hasNext() {
+ return index < size;
+ }
+
+ @Override
+ public Integer next() {
+ if (!hasNext()) {
+ throw new NoSuchElementException();
+ }
+ return elements[index++];
+ }
+ };
+ }
+
+ @Override
+ public int size() {
+ return size;
+ }
+
+ public int get(int index) {
+ if (index >= size) {
+ throw new IndexOutOfBoundsException();
+ }
+ return elements[index];
+ }
+
+ public void set(int index, int value) {
+ if (index >= size) {
+ throw new IndexOutOfBoundsException();
+ }
+ elements[index] = value;
+ }
+
+ public int[] getElements() {
+ return elements;
+ }
+}
+
+class IntListSerializer extends CollectionLikeSerializer<IntList> {
+ public IntListSerializer(Fory fory) {
+ // 禁用 JIT，因为我们直接处理序列化
+ super(fory, IntList.class, false);
+ }
+
+ @Override
+ public void write(MemoryBuffer buffer, IntList value) {
+ // 写入大小
+ buffer.writeVarUint32Small7(value.size());
+
+ // 直接将元素写为原始 int
+ int[] elements = value.getElements();
+ for (int i = 0; i < value.size(); i++) {
+ buffer.writeVarInt32(elements[i]);
+ }
+ }
+
+ @Override
+ public IntList read(MemoryBuffer buffer) {
+ // 读取大小
+ int size = buffer.readVarUint32Small7();
+
+ // 创建数组并读取元素
+ int[] elements = new int[size];
+ for (int i = 0; i < size; i++) {
+ elements[i] = buffer.readVarInt32();
+ }
+
+ return new IntList(elements, size);
+ }
+
+ // 当禁用 JIT 时不使用这些方法
+ @Override
+ public Collection onCollectionWrite(MemoryBuffer buffer, IntList value) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public Collection newCollection(MemoryBuffer buffer) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public IntList onCollectionRead(Collection collection) {
+ throw new UnsupportedOperationException();
+ }
+}
+```
+
+**何时使用此方法：**
+
+- 处理原始类型
+- 需要最大性能
+- 想要最小化内存开销
+- 有特殊的序列化需求
+
+### 类集合类型序列化器
+
+对于行为类似集合但不是标准 Java 集合的类型：
+
+```java
+class CustomCollectionLike {
+ private final Object[] elements;
+ private final int size;
+
+ public CustomCollectionLike(int size) {
+ this.elements = new Object[size];
+ this.size = 0;
+ }
+
+ public CustomCollectionLike(Object[] elements, int size) {
+ this.elements = elements;
+ this.size = size;
+ }
+
+ public Object get(int index) {
+ if (index >= size) {
+ throw new IndexOutOfBoundsException();
+ }
+ return elements[index];
+ }
+
+ public int size() {
+ return size;
+ }
+
+ public Object[] getElements() {
+ return elements;
+ }
+}
+
+class CollectionView extends AbstractCollection<Object> {
+ private final Object[] elements;
+ private final int size;
+ private int writeIndex;
+
+ public CollectionView(CustomCollectionLike collection) {
+ this.elements = collection.getElements();
+ this.size = collection.size();
+ }
+
+ public CollectionView(int size) {
+ this.size = size;
+ this.elements = new Object[size];
+ }
+
+ @Override
+ public Iterator<Object> iterator() {
+ return new Iterator<Object>() {
+ private int index = 0;
+
+ @Override
+ public boolean hasNext() {
+ return index < size;
+ }
+
+ @Override
+ public Object next() {
+ if (!hasNext()) {
+ throw new NoSuchElementException();
+ }
+ return elements[index++];
+ }
+ };
+ }
+
+ @Override
+ public boolean add(Object element) {
+ if (writeIndex >= size) {
+ throw new IllegalStateException("Collection is full");
+ }
+ elements[writeIndex++] = element;
+ return true;
+ }
+
+ @Override
+ public int size() {
+ return size;
+ }
+
+ public Object[] getElements() {
+ return elements;
+ }
+}
+
+class CustomCollectionSerializer extends CollectionLikeSerializer<CustomCollectionLike> {
+ public CustomCollectionSerializer(Fory fory) {
+ super(fory, CustomCollectionLike.class, true);
+ }
+
+ @Override
+ public Collection onCollectionWrite(MemoryBuffer buffer, CustomCollectionLike value) {
+ buffer.writeVarUint32Small7(value.size());
+ return new CollectionView(value);
+ }
+
+ @Override
+ public Collection newCollection(MemoryBuffer buffer) {
+ int numElements = buffer.readVarUint32Small7();
+ setNumElements(numElements);
+ return new CollectionView(numElements);
+ }
+
+ @Override
+ public CustomCollectionLike onCollectionRead(Collection collection) {
+ CollectionView view = (CollectionView) collection;
+ return new CustomCollectionLike(view.getElements(), view.size());
+ }
+}
+```
+
+## Map 序列化器
+
+在为自定义 Map 类型实现序列化器时，扩展 `MapSerializer` 或 `MapLikeSerializer`。主要区别是 `MapLikeSerializer` 可以序列化具有类似 map 结构但不是 Java Map 子类型的类。
+
+### 带 JIT 支持的 Map 序列化器
+
+```java
+public class CustomMapSerializer<T extends Map> extends MapSerializer<T> {
+ public CustomMapSerializer(Fory fory, Class<T> cls) {
+ // supportCodegenHook 是决定序列化行为的关键参数
+ super(fory, cls, true);
+ }
+
+ @Override
+ public Map onMapWrite(MemoryBuffer buffer, T value) {
+ // 写入 map 大小
+ buffer.writeVarUint32Small7(value.size());
+ // 在这里写入任何额外的 map 元数据
+ return value;
+ }
+
+ @Override
+ public Map newMap(MemoryBuffer buffer) {
+ // 读取 map 大小
+ int numElements = buffer.readVarUint32Small7();
+ setNumElements(numElements);
+ // 创建并返回新的 map 实例
+ T map = (T) new HashMap(numElements);
+ fory.getRefResolver().reference(map);
+ return map;
+ }
+}
+```
+
+注意：在实现 `newMap` 时调用 `setNumElements`，让 Fory 知道要反序列化多少元素。
+
+### 不带 JIT 的自定义 Map 序列化器
+
+对于完全控制序列化过程：
+
+```java
+class FixedValueMap extends AbstractMap<String, Integer> {
+ private final Set<String> keys;
+ private final int fixedValue;
+
+ public FixedValueMap(Set<String> keys, int fixedValue) {
+ this.keys = keys;
+ this.fixedValue = fixedValue;
+ }
+
+ @Override
+ public Set<Entry<String, Integer>> entrySet() {
+ Set<Entry<String, Integer>> entries = new HashSet<>();
+ for (String key : keys) {
+ entries.add(new SimpleEntry<>(key, fixedValue));
+ }
+ return entries;
+ }
+
+ @Override
+ public Integer get(Object key) {
+ return keys.contains(key) ? fixedValue : null;
+ }
+
+ public Set<String> getKeys() {
+ return keys;
+ }
+
+ public int getFixedValue() {
+ return fixedValue;
+ }
+}
+
+class FixedValueMapSerializer extends MapLikeSerializer<FixedValueMap> {
+ public FixedValueMapSerializer(Fory fory) {
+ // 禁用 codegen，因为我们直接处理序列化
+ super(fory, FixedValueMap.class, false);
+ }
+
+ @Override
+ public void write(MemoryBuffer buffer, FixedValueMap value) {
+ // 写入固定值
+ buffer.writeInt32(value.getFixedValue());
+ // 写入键的数量
+ buffer.writeVarUint32Small7(value.getKeys().size());
+ // 写入每个键
+ for (String key : value.getKeys()) {
+ buffer.writeString(key);
+ }
+ }
+
+ @Override
+ public FixedValueMap read(MemoryBuffer buffer) {
+ // 读取固定值
+ int fixedValue = buffer.readInt32();
+ // 读取键的数量
+ int size = buffer.readVarUint32Small7();
+ Set<String> keys = new HashSet<>(size);
+ for (int i = 0; i < size; i++) {
+ keys.add(buffer.readString());
+ }
+ return new FixedValueMap(keys, fixedValue);
+ }
+
+ // 当 supportCodegenHook 为 false 时不使用这些方法
+ @Override
+ public Map onMapWrite(MemoryBuffer buffer, FixedValueMap value) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public FixedValueMap onMapRead(Map map) {
+ throw new UnsupportedOperationException();
+ }
+
+ @Override
+ public FixedValueMap onMapCopy(Map map) {
+ throw new UnsupportedOperationException();
+ }
+}
+```
+
+### 类 Map 类型序列化器
+
+对于行为类似 map 但不是标准 Java Map 的类型：
+
+```java
+class CustomMapLike {
+ private final Object[] keyArray;
+ private final Object[] valueArray;
+ private final int size;
+
+ public CustomMapLike(int initialCapacity) {
+ this.keyArray = new Object[initialCapacity];
+ this.valueArray = new Object[initialCapacity];
+ this.size = 0;
+ }
+
+ public CustomMapLike(Object[] keyArray, Object[] valueArray, int size) {
+ this.keyArray = keyArray;
+ this.valueArray = valueArray;
+ this.size = size;
+ }
+
+ public Integer get(String key) {
+ for (int i = 0; i < size; i++) {
+ if (key.equals(keyArray[i])) {
+ return (Integer) valueArray[i];
+ }
+ }
+ return null;
+ }
+
+ public int size() {
+ return size;
+ }
+
+ public Object[] getKeyArray() {
+ return keyArray;
+ }
+
+ public Object[] getValueArray() {
+ return valueArray;
+ }
+}
+
+class MapView extends AbstractMap<Object, Object> {
+ private final Object[] keyArray;
+ private final Object[] valueArray;
+ private final int size;
+ private int writeIndex;
+
+ public MapView(CustomMapLike mapLike) {
+ this.size = mapLike.size();
+ this.keyArray = mapLike.getKeyArray();
+ this.valueArray = mapLike.getValueArray();
+ }
+
+ public MapView(int size) {
+ this.size = size;
+ this.keyArray = new Object[size];
+ this.valueArray = new Object[size];
+ }
+
+ @Override
+ public Set<Entry<Object, Object>> entrySet() {
+ return new AbstractSet<Entry<Object, Object>>() {
+ @Override
+ public Iterator<Entry<Object, Object>> iterator() {
+ return new Iterator<Entry<Object, Object>>() {
+ private int index = 0;
+
+ @Override
+ public boolean hasNext() {
+ return index < size;
+ }
+
+ @Override
+ public Entry<Object, Object> next() {
+ if (!hasNext()) {
+ throw new NoSuchElementException();
+ }
+ final int currentIndex = index++;
+ return new SimpleEntry<>(
+ keyArray[currentIndex],
+ valueArray[currentIndex]
+ );
+ }
+ };
+ }
+
+ @Override
+ public int size() {
+ return size;
+ }
+ };
+ }
+
+ @Override
+ public Object put(Object key, Object value) {
+ if (writeIndex >= size) {
+ throw new IllegalStateException("Map is full");
+ }
+ keyArray[writeIndex] = key;
+ valueArray[writeIndex] = value;
+ writeIndex++;
+ return null;
+ }
+
+ public Object[] getKeyArray() {
+ return keyArray;
+ }
+
+ public Object[] getValueArray() {
+ return valueArray;
+ }
+
+ public int size() {
+ return size;
+ }
+}
+
+class CustomMapLikeSerializer extends MapLikeSerializer<CustomMapLike> {
+ public CustomMapLikeSerializer(Fory fory) {
+ super(fory, CustomMapLike.class, true);
+ }
+
+ @Override
+ public Map onMapWrite(MemoryBuffer buffer, CustomMapLike value) {
+ buffer.writeVarUint32Small7(value.size());
+ return new MapView(value);
+ }
+
+ @Override
+ public Map newMap(MemoryBuffer buffer) {
+ int numElements = buffer.readVarUint32Small7();
+ setNumElements(numElements);
+ return new MapView(numElements);
+ }
+
+ @Override
+ public CustomMapLike onMapRead(Map map) {
+ MapView view = (MapView) map;
+ return new CustomMapLike(view.getKeyArray(), view.getValueArray(), view.size());
+ }
+
+ @Override
+ public CustomMapLike onMapCopy(Map map) {
+ MapView view = (MapView) map;
+ return new CustomMapLike(view.getKeyArray(), view.getValueArray(), view.size());
+ }
+}
+```
+
+## 注册自定义序列化器
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .build();
+
+// 注册 map 序列化器
+fory.registerSerializer(CustomMap.class, new CustomMapSerializer<>(fory, CustomMap.class));
+
+// 注册集合序列化器
+fory.registerSerializer(CustomCollection.class, new CustomCollectionSerializer<>(fory, CustomCollection.class));
+```
+
+## 关键点
+
+实现自定义 map 或集合序列化器时：
+
+1. 始终扩展适当的基类（map 使用 `MapSerializer`/`MapLikeSerializer`，集合使用 `CollectionSerializer`/`CollectionLikeSerializer`）
+2. 考虑 `supportCodegenHook` 对性能和功能的影响
+3. 如果需要，适当处理引用跟踪
+4. 当 `supportCodegenHook` 为 `true` 时，使用 `setNumElements` 和 `getAndClearNumElements` 实现适当的大小管理
+
+## 相关主题
+
+- [类型注册](type-registration.md) - 注册序列化器
+- [Schema 演化](schema-evolution.md) - 兼容模式考虑
+- [配置选项](configuration.md) - 序列化选项
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/index.md
new file mode 100644
index 000000000..08c893e88
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/index.md
@@ -0,0 +1,193 @@
+---
+title: Java 序列化指南
+sidebar_position: 0
+id: java_serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 提供极速的 Java 对象序列化，基于 JIT 编译和零拷贝技术。当只需要 Java 对象序列化时，这种模式相比跨语言对象图序列化提供更好的性能。
+
+## 特性
+
+### 高性能
+
+- **JIT 代码生成**：高度可扩展的 JIT 框架在运行时使用异步多线程编译生成序列化器代码，通过以下方式提供 20-170 倍的加速：
+ - 内联变量以减少内存访问
+ - 内联方法调用以消除虚拟分派开销
+ - 最小化条件分支
+ - 消除哈希查找
+- **零拷贝**：直接内存访问，无中间缓冲区拷贝；行格式支持随机访问和部分序列化
+- **变长编码**：对整数和长整型进行优化压缩
+- **元数据共享**：缓存的类元数据减少冗余类型信息
+- **SIMD 加速**：支持 Java Vector API 用于数组操作（Java 16+）
+
+### 即插即用替代
+
+- **100% JDK 序列化兼容**：支持 `writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable`
+- **Java 8-24 支持**：适用于所有现代 Java 版本，包括 Java 17+ 的 record
+- **GraalVM Native Image**：支持 AOT 编译，无需反射配置
+
+### 高级特性
+
+- **引用跟踪**：自动处理共享引用和循环引用
+- **Schema 演化**：类 schema 变更的前向/后向兼容性
+- **多态性**：完全支持继承层次结构和接口
+- **深拷贝**：高效深度克隆复杂对象图并保留引用
+- **安全性**：类注册和可配置的反序列化策略
+
+## 快速开始
+
+注意，Fory 的创建成本不低，**应该在多次序列化之间复用 Fory 实例**，而不是每次都创建。你应该将 Fory 作为静态全局变量，或者某个单例对象或有限对象的实例变量。
+
+### 单线程使用
+
+```java
+import java.util.List;
+import java.util.Arrays;
+
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+
+public class Example {
+ public static void main(String[] args) {
+ SomeClass object = new SomeClass();
+ // 注意 Fory 实例应该在多次不同对象的序列化之间复用。
+ Fory fory = Fory.builder().withLanguage(Language.JAVA)
+ .requireClassRegistration(true)
+ .build();
+ // 注册类型可以减少类名序列化开销，但不是必须的。
+ // 如果启用了类注册，所有自定义类型都必须注册。
+ // 如果未指定 id，注册顺序必须一致
+ fory.register(SomeClass.class);
+ byte[] bytes = fory.serialize(object);
+ System.out.println(fory.deserialize(bytes));
+ }
+}
+```
+
+### 多线程使用
+
+```java
+import java.util.List;
+import java.util.Arrays;
+
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+
+public class Example {
+ public static void main(String[] args) {
+ SomeClass object = new SomeClass();
+ // 注意 Fory 实例应该在多次不同对象的序列化之间复用。
+ ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
+ Fory f = Fory.builder().withLanguage(Language.JAVA)
+ .withClassLoader(classLoader).build();
+ f.register(SomeClass.class, 1);
+ return f;
+ });
+ byte[] bytes = fory.serialize(object);
+ System.out.println(fory.deserialize(bytes));
+ }
+}
+```
+
+### Fory 实例复用模式
+
+```java
+import java.util.List;
+import java.util.Arrays;
+
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+
+public class Example {
+ // 复用 fory。
+ private static final ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
+ Fory f = Fory.builder().withLanguage(Language.JAVA)
+ .withClassLoader(classLoader).build();
+ f.register(SomeClass.class, 1);
+ return f;
+ });
+
+ public static void main(String[] args) {
+ SomeClass object = new SomeClass();
+ byte[] bytes = fory.serialize(object);
+ System.out.println(fory.deserialize(bytes));
+ }
+}
+```
+
+## 线程安全
+
+Fory 提供多种线程安全序列化选项：
+
+### ThreadLocalFory
+
+使用线程本地存储为每个线程维护独立的 Fory 实例：
+
+```java
+ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
+ Fory f = Fory.builder().withLanguage(Language.JAVA)
+ .withClassLoader(classLoader).build();
+ f.register(SomeClass.class, 1);
+ return f;
+});
+byte[] bytes = fory.serialize(object);
+System.out.println(fory.deserialize(bytes));
+```
+
+### ThreadSafeForyPool
+
+对于虚拟线程或不适合使用线程本地存储的环境，使用 `buildThreadSafeForyPool`：
+
+```java
+ThreadSafeFory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withRefTracking(false)
+ .withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
+ .withAsyncCompilation(true)
+ .buildThreadSafeForyPool(minPoolSize, maxPoolSize);
+```
+
+注意，在 `ForyBuilder` 上调用 `buildThreadSafeFory()` 将创建 `ThreadLocalFory` 实例。这在使用虚拟线程的环境中可能不合适，因为每个线程都会创建自己的 Fory 实例，这是一个相对昂贵的操作。对于虚拟线程，另一种选择是使用 `buildThreadSafeForyPool`。
+
+### Builder 方法
+
+```java
+// 单线程 Fory
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withRefTracking(false)
+ .withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
+ .withAsyncCompilation(true)
+ .build();
+
+// 线程安全 Fory (ThreadLocalFory)
+ThreadSafeFory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withRefTracking(false)
+ .withCompatibleMode(CompatibleMode.SCHEMA_CONSISTENT)
+ .withAsyncCompilation(true)
+ .buildThreadSafeFory();
+```
+
+## 后续步骤
+
+- [配置选项](configuration.md) - 了解 ForyBuilder 选项
+- [基础序列化](basic-serialization.md) - 详细的序列化模式
+- [类型注册](type-registration.md) - 类注册和安全性
+- [自定义序列化器](custom-serializers.md) - 实现自定义序列化器
+- [跨语言序列化](cross-language.md) - 为其他语言序列化数据
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/migration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/migration.md
new file mode 100644
index 000000000..a69d2e3f0
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/migration.md
@@ -0,0 +1,120 @@
+---
+title: 迁移指南
+sidebar_position: 10
+id: java_migration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍从 JDK 序列化迁移以及在 Fory 版本之间升级的策略。
+
+## JDK 序列化迁移
+
+如果你之前使用 JDK 序列化，并且无法同时升级客户端和服务器（这对于在线应用程序很常见），Fory 提供了一个实用方法 `org.apache.fory.serializer.JavaSerializer.serializedByJDK` 来检查二进制是否由 JDK 序列化生成。
+
+你可以使用以下模式使现有序列化协议感知，然后以异步滚动方式升级序列化到 Fory：
+
+```java
+if (JavaSerializer.serializedByJDK(bytes)) {
+ ObjectInputStream objectInputStream = xxx;
+ return objectInputStream.readObject();
+} else {
+ return fory.deserialize(bytes);
+}
+```
+
+这允许你：
+
+1. 部署可以同时读取 JDK 和 Fory 序列化数据的新代码
+2. 逐步将序列化迁移到 Fory
+3. 最终移除 JDK 序列化支持
+
+## 升级 Fory
+
+### 小版本升级
+
+目前，仅为小版本提供二进制兼容性。例如，如果你使用 Fory `v0.2.0`，如果升级到 Fory `v0.2.1`，将提供二进制兼容性。
+
+如果你按小版本升级，或者你不会有旧版 Fory 序列化的数据，你可以直接升级 Fory，无需任何特殊处理。
+
+### 大版本升级
+
+如果你从 `v0.2.x` 升级到 Fory `v0.4.1`，则不保证二进制兼容性。
+
+大多数时候不需要升级 Fory 到更新的大版本——当前版本已经足够快速和紧凑，我们为最近的旧版本提供一些小修复。
+
+### 为序列化数据添加版本
+
+如果你确实想升级 Fory 以获得更好的性能和更小的大小，你需要将 Fory 版本作为头部写入序列化数据，使用如下代码来保持二进制兼容性：
+
+#### 带版本头的序列化
+
+```java
+MemoryBuffer buffer = xxx;
+buffer.writeVarInt32(2); // 写入 Fory 版本
+fory.serialize(buffer, obj);
+```
+
+#### 带版本头的反序列化
+
+```java
+MemoryBuffer buffer = xxx;
+int foryVersion = buffer.readVarInt32();
+Fory fory = getFory(foryVersion);
+fory.deserialize(buffer);
+```
+
+`getFory` 是一个加载相应 Fory 版本的方法。你可以将不同版本的 Fory shade 和 relocate 到不同的包，并按版本加载 Fory。
+
+### Shading 示例
+
+```xml
+<!-- Maven Shade Plugin 配置用于多个 Fory 版本 -->
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>shade-fory-v1</id>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ <configuration>
+ <relocations>
+ <relocation>
+ <pattern>org.apache.fory</pattern>
+ <shadedPattern>com.myapp.fory.v1</shadedPattern>
+ </relocation>
+ </relocations>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
+```
+
+## 最佳实践
+
+1. **升级前彻底测试**：确保与现有序列化数据的兼容性
+2. **对长期存储使用版本头**：如果数据在 Fory 版本之间持久化
+3. **保持向后兼容性**：保留旧版本 Fory 以读取遗留数据
+4. **升级后监控**：在生产环境中注意反序列化错误
+
+## 相关主题
+
+- [配置选项](configuration.md) - ForyBuilder 选项
+- [Schema 演化](schema-evolution.md) - 处理类变更
+- [故障排除](troubleshooting.md) - 常见迁移问题
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/row-format.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/row-format.md
new file mode 100644
index 000000000..45dc3adcf
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/row-format.md
@@ -0,0 +1,183 @@
+---
+title: 行格式
+sidebar_position: 9
+id: java_row_format
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 提供了一种随机访问行格式，能够在不完全反序列化的情况下从二进制数据中读取嵌套字段。当处理大对象且只需要部分数据访问时，这大大减少了开销。
+
+## 概述
+
+行格式是一种缓存友好的二进制随机访问格式，支持：
+
+- **零拷贝访问**：直接从二进制读取字段，无需分配对象
+- **部分反序列化**：只访问你需要的字段
+- **跳过序列化**：跳过不需要的字段的序列化
+- **跨语言兼容性**：在 Python、Java、C++ 和其他语言之间工作
+- **列格式转换**：可以自动转换为 Apache Arrow 列格式
+
+## 基本使用
+
+```java
+public class Bar {
+ String f1;
+ List<Long> f2;
+}
+
+public class Foo {
+ int f1;
+ List<Integer> f2;
+ Map<String, Integer> f3;
+ List<Bar> f4;
+}
+
+RowEncoder<Foo> encoder = Encoders.bean(Foo.class);
+
+// 创建大型数据集
+Foo foo = new Foo();
+foo.f1 = 10;
+foo.f2 = IntStream.range(0, 1_000_000).boxed().collect(Collectors.toList());
+foo.f3 = IntStream.range(0, 1_000_000).boxed().collect(Collectors.toMap(i -> "k" + i, i -> i));
+List<Bar> bars = new ArrayList<>(1_000_000);
+for (int i = 0; i < 1_000_000; i++) {
+ Bar bar = new Bar();
+ bar.f1 = "s" + i;
+ bar.f2 = LongStream.range(0, 10).boxed().collect(Collectors.toList());
+ bars.add(bar);
+}
+foo.f4 = bars;
+
+// 编码为行格式（跨语言兼容 Python/C++）
+BinaryRow binaryRow = encoder.toRow(foo);
+
+// 零拷贝随机访问，无需完全反序列化
+BinaryArray f2Array = binaryRow.getArray(1); // 访问 f2 列表
+BinaryArray f4Array = binaryRow.getArray(3); // 访问 f4 列表
+BinaryRow bar10 = f4Array.getStruct(10); // 访问第 11 个 Bar
+long value = bar10.getArray(1).getInt64(5); // 访问 bar.f2 的第 6 个元素
+
+// 部分反序列化 - 只反序列化你需要的
+RowEncoder<Bar> barEncoder = Encoders.bean(Bar.class);
+Bar bar1 = barEncoder.fromRow(f4Array.getStruct(10)); // 只反序列化第 11 个 Bar
+Bar bar2 = barEncoder.fromRow(f4Array.getStruct(20)); // 只反序列化第 21 个 Bar
+
+// 需要时完全反序列化
+Foo newFoo = encoder.fromRow(binaryRow);
+```
+
+## 主要优势
+
+| 特性 | 描述 |
+| ------------ | -------------------------------------- |
+| 零拷贝访问 | 读取嵌套字段而无需反序列化整个对象 |
+| 内存效率 | 直接从磁盘内存映射大数据集 |
+| 跨语言 | Java、Python、C++ 之间的二进制格式兼容 |
+| 部分反序列化 | 只反序列化你需要的特定元素 |
+| 高性能 | 跳过不必要的数据解析用于分析工作负载 |
+
+## 何时使用行格式
+
+行格式适用于：
+
+- **分析工作负载**：当你只需要访问特定字段时
+- **大数据集**：当完全反序列化成本太高时
+- **内存映射文件**：处理大于 RAM 的数据
+- **数据管道**：无需完整对象重建即可处理数据
+- **跨语言数据共享**：当数据需要从多种语言访问时
+
+## 跨语言兼容性
+
+行格式在语言之间无缝工作。相同的二进制数据可以从以下语言访问：
+
+### Python
+
+```python
+import pyfory
+import pyarrow as pa
+from dataclasses import dataclass
+from typing import List, Dict
+
+@dataclass
+class Bar:
+ f1: str
+ f2: List[pa.int64]
+
+@dataclass
+class Foo:
+ f1: pa.int32
+ f2: List[pa.int32]
+ f3: Dict[str, pa.int32]
+ f4: List[Bar]
+
+encoder = pyfory.encoder(Foo)
+binary: bytes = encoder.to_row(foo).to_bytes()
+
+# 零拷贝访问
+foo_row = pyfory.RowData(encoder.schema, binary)
+print(foo_row.f2[100000])
+print(foo_row.f4[100000].f1)
+```
+
+### C++
+
+```cpp
+#include "fory/encoder/row_encoder.h"
+#include "fory/row/writer.h"
+
+struct Bar {
+ std::string f1;
+ std::vector<int64_t> f2;
+};
+
+FORY_FIELD_INFO(Bar, f1, f2);
+
+struct Foo {
+ int32_t f1;
+ std::vector<int32_t> f2;
+ std::map<std::string, int32_t> f3;
+ std::vector<Bar> f4;
+};
+
+FORY_FIELD_INFO(Foo, f1, f2, f3, f4);
+
+fory::encoder::RowEncoder<Foo> encoder;
+encoder.Encode(foo);
+auto row = encoder.GetWriter().ToRow();
+
+// 零拷贝随机访问
+auto f2_array = row->GetArray(1);
+auto f4_array = row->GetArray(3);
+auto bar10 = f4_array->GetStruct(10);
+int64_t value = bar10->GetArray(1)->GetInt64(5);
+std::string str = bar10->GetString(0);
+```
+
+## 性能比较
+
+| 操作 | 对象格式 | 行格式 |
+| ------------ | ------------------ | ------------------ |
+| 完全反序列化 | 分配所有对象 | 零分配 |
+| 单字段访问 | 需要完全反序列化 | 直接偏移读取 |
+| 内存使用 | 完整对象图在内存中 | 仅访问的字段 |
+| 适用于 | 小对象，完全访问 | 大对象，选择性访问 |
+
+## 相关主题
+
+- [跨语言序列化](cross-language.md) - XLANG 模式
+- [高级特性](advanced-features.md) - 零拷贝序列化
+- [行格式规范](https://fory.apache.org/docs/specification/row_format_spec) - 协议详情
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/schema-evolution.md
new file mode 100644
index 000000000..1a431df79
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/schema-evolution.md
@@ -0,0 +1,215 @@
+---
+title: Schema 演化
+sidebar_position: 5
+id: java_schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 schema 演化、元数据共享以及处理不存在的类。
+
+## 处理类 Schema 演化
+
+在许多系统中，用于序列化的类的 schema 可能会随时间而改变。例如，类中的字段可能会被添加或删除。当序列化和反序列化过程使用不同版本的 jar 时，被反序列化的类的 schema 可能与序列化期间使用的不同。
+
+### 默认模式：SCHEMA_CONSISTENT
+
+默认情况下，Fory 使用 `CompatibleMode.SCHEMA_CONSISTENT` 模式序列化对象。此模式假设反序列化过程使用与序列化过程相同的类 schema，从而最小化有效负载开销。但是，如果存在 schema 不一致，反序列化将失败。
+
+### 兼容模式
+
+如果预期 schema 会发生变化，为了使反序列化成功（即 schema 前向/后向兼容性），用户必须配置 Fory 使用 `CompatibleMode.COMPATIBLE`。这可以使用 `ForyBuilder#withCompatibleMode(CompatibleMode.COMPATIBLE)` 方法完成。
+
+在此兼容模式下，反序列化可以处理 schema 变更，如缺失或额外的字段，允许在序列化和反序列化过程具有不同类 schema 时也能成功。
+
+```java
+Fory fory = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ .build();
+
+byte[] bytes = fory.serialize(object);
+System.out.println(fory.deserialize(bytes));
+```
+
+此兼容模式涉及将类元数据序列化到序列化输出中。尽管 Fory 使用复杂的压缩技术来最小化开销，但与类元数据相关联的仍有一些额外的空间成本。
+
+## 元数据共享
+
+为了进一步降低元数据成本，Fory 引入了类元数据共享机制，允许元数据只发送到反序列化过程一次。
+
+Fory 支持在上下文（例如 TCP 连接）中的多次序列化之间共享类型元数据（类名、字段名、最终字段类型信息等）。此信息将在上下文中的第一次序列化期间发送到对等端。基于此元数据，对等端可以重建相同的反序列化器，这避免了为后续序列化传输元数据，并降低网络流量压力，同时自动支持类型前向/后向兼容性。
+
+### 使用元数据共享
+
+```java
+// Fory.builder()
+// .withLanguage(Language.JAVA)
+// .withRefTracking(false)
+// // 在多次序列化之间共享元数据。
+// .withMetaContextShare(true)
+
+// 非线程安全 fory。
+MetaContext context = xxx;
+fory.getSerializationContext().setMetaContext(context);
+byte[] bytes = fory.serialize(o);
+
+// 非线程安全 fory。
+MetaContext context = xxx;
+fory.getSerializationContext().setMetaContext(context);
+fory.deserialize(bytes);
+```
+
+### 线程安全元数据共享
+
+```java
+// 线程安全 fory
+fory.setClassLoader(beanA.getClass().getClassLoader());
+byte[] serialized = fory.execute(
+ f -> {
+ f.getSerializationContext().setMetaContext(context);
+ return f.serialize(beanA);
+ }
+);
+
+// 线程安全 fory
+fory.setClassLoader(beanA.getClass().getClassLoader());
+Object newObj = fory.execute(
+ f -> {
+ f.getSerializationContext().setMetaContext(context);
+ return f.deserialize(serialized);
+ }
+);
+```
+
+**注意**：`MetaContext` 不是线程安全的，不能在 Fory 实例或多个线程之间重用。在多线程情况下，必须为每个 Fory 实例创建单独的 `MetaContext`。
+
+有关更多详细信息，请参阅 [元数据共享规范](https://fory.apache.org/docs/specification/fory_java_serialization_spec#meta-share)。
+
+## 反序列化不存在的类
+
+Fory 支持反序列化不存在的类。此功能可以通过 `ForyBuilder#deserializeNonexistentClass(true)` 启用。
+
+启用时，如果启用了元数据共享，Fory 将把此类型的反序列化数据存储在 Map 的延迟子类中。通过使用 Fory 实现的延迟映射，可以避免反序列化期间填充映射的重新平衡成本，从而进一步提高性能。
+
+如果此数据被发送到另一个进程，并且该类在此过程中存在，则数据将被反序列化为此类型的对象，而不会丢失任何信息。
+
+如果未启用元数据共享，新类数据将被跳过，并返回 `NonexistentSkipClass` 存根对象。
+
+## 将对象从一种类型复制/映射到另一种类型
+
+Fory 支持将对象从一种类型映射到另一种类型。
+
+**注意：**
+
+1. 此映射将执行深拷贝。所有映射的字段都被序列化为二进制，并从该二进制反序列化以映射到另一种类型。
+2. 所有结构体类型必须使用相同的 ID 注册，否则 Fory 无法映射到正确的结构体类型。使用 `Fory#register(Class)` 时要小心，因为 Fory 会分配一个自动增长的 ID，如果你在 Fory 实例之间以不同的顺序注册类，这可能会不一致。
+
+```java
+public class StructMappingExample {
+ static class Struct1 {
+ int f1;
+ String f2;
+
+ public Struct1(int f1, String f2) {
+ this.f1 = f1;
+ this.f2 = f2;
+ }
+ }
+
+ static class Struct2 {
+ int f1;
+ String f2;
+ double f3;
+ }
+
+ static ThreadSafeFory fory1 = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE).buildThreadSafeFory();
+ static ThreadSafeFory fory2 = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE).buildThreadSafeFory();
+
+ static {
+ fory1.register(Struct1.class);
+ fory2.register(Struct2.class);
+ }
+
+ public static void main(String[] args) {
+ Struct1 struct1 = new Struct1(10, "abc");
+ Struct2 struct2 = (Struct2) fory2.deserialize(fory1.serialize(struct1));
+ Assert.assertEquals(struct2.f1, struct1.f1);
+ Assert.assertEquals(struct2.f2, struct1.f2);
+ struct1 = (Struct1) fory1.deserialize(fory2.serialize(struct2));
+ Assert.assertEquals(struct1.f1, struct2.f1);
+ Assert.assertEquals(struct1.f2, struct2.f2);
+ }
+}
+```
+
+## 将 POJO 反序列化为另一种类型
+
+Fory 允许你序列化一个 POJO 并将其反序列化为另一个 POJO。不同的 POJO 意味着 schema 不一致。用户必须将 Fory 配置为 `CompatibleMode` 设置为 `org.apache.fory.config.CompatibleMode.COMPATIBLE`。
+
+```java
+public class DeserializeIntoType {
+ static class Struct1 {
+ int f1;
+ String f2;
+
+ public Struct1(int f1, String f2) {
+ this.f1 = f1;
+ this.f2 = f2;
+ }
+ }
+
+ static class Struct2 {
+ int f1;
+ String f2;
+ double f3;
+ }
+
+ static ThreadSafeFory fory = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE).buildThreadSafeFory();
+
+ public static void main(String[] args) {
+ Struct1 struct1 = new Struct1(10, "abc");
+ byte[] data = fory.serializeJavaObject(struct1);
+ Struct2 struct2 = (Struct2) fory.deserializeJavaObject(bytes, Struct2.class);
+ }
+}
+```
+
+## 配置选项
+
+| 选项 | 描述 | 默认值 |
+| ----------------------------- | ----------------------------------- | ------------------------- |
+| `compatibleMode` | `SCHEMA_CONSISTENT` 或 `COMPATIBLE` | `SCHEMA_CONSISTENT` |
+| `checkClassVersion` | 检查类 schema 一致性 | `false` |
+| `metaShareEnabled` | 启用元数据共享 | 如果是兼容模式则为 `true` |
+| `scopedMetaShareEnabled` | 每次序列化的作用域元数据共享 | 如果是兼容模式则为 `true` |
+| `deserializeNonexistentClass` | 处理不存在的类 | 如果是兼容模式则为 `true` |
+| `metaCompressor` | 元数据压缩的压缩器 | `DeflaterMetaCompressor` |
+
+## 最佳实践
+
+1. **对演化的 schema 使用 COMPATIBLE 模式**：当类可能在版本之间更改时
+2. **为网络通信启用元数据共享**：减少重复序列化的带宽
+3. **对结构体映射使用一致的类型 ID**：确保相同的注册顺序或显式 ID
+4. **考虑空间开销**：兼容模式会添加元数据，根据需求平衡
+
+## 相关主题
+
+- [配置选项](configuration.md) - 所有 ForyBuilder 选项
+- [跨语言序列化](cross-language.md) - XLANG 模式
+- [故障排除](troubleshooting.md) - 常见 schema 问题
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/troubleshooting.md
new file mode 100644
index 000000000..00fa9ee7e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/troubleshooting.md
@@ -0,0 +1,213 @@
+---
+title: 故障排除
+sidebar_position: 11
+id: java_troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍常见问题及其解决方案。
+
+## 类不一致和类版本检查
+
+如果你创建 Fory 时没有将 `CompatibleMode` 设置为 `org.apache.fory.config.CompatibleMode.COMPATIBLE`，并且遇到奇怪的序列化错误，这可能是由于序列化端和反序列化端之间的类不一致造成的。
+
+在这种情况下，你可以调用 `ForyBuilder#withClassVersionCheck` 来创建 Fory 以验证它。如果反序列化抛出 `org.apache.fory.exception.ClassNotCompatibleException`，则表示类不一致，你应该使用 `ForyBuilder#withCompatibleMode(CompatibleMode.COMPATIBLE)` 创建 Fory。
+
+```java
+// 启用类版本检查以诊断问题
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withClassVersionCheck(true)
+ .build();
+
+// 如果抛出 ClassNotCompatibleException，使用兼容模式
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ .build();
+```
+
+**注意**：`CompatibleMode.COMPATIBLE` 有更多的性能和空间成本。如果你的类在序列化和反序列化之间始终一致，请不要默认设置它。
+
+## 使用错误的反序列化 API
+
+确保使用匹配的 API 对：
+
+| 序列化 API | 反序列化 API |
+| ---------------------------------- | ------------------------------------ |
+| `Fory#serialize` | `Fory#deserialize` |
+| `Fory#serializeJavaObject` | `Fory#deserializeJavaObject` |
+| `Fory#serializeJavaObjectAndClass` | `Fory#deserializeJavaObjectAndClass` |
+
+**错误使用示例：**
+
+```java
+// ❌ 错误：使用 serialize 序列化，使用 deserializeJavaObject 反序列化
+byte[] bytes = fory.serialize(object);
+Object result = fory.deserializeJavaObject(bytes, MyClass.class); // 错误！
+
+// ❌ 错误：使用 serializeJavaObject 序列化，使用 deserialize 反序列化
+byte[] bytes = fory.serializeJavaObject(object);
+Object result = fory.deserialize(bytes); // 错误！
+```
+
+**正确使用：**
+
+```java
+// ✅ 正确：匹配的 API 对
+byte[] bytes = fory.serialize(object);
+Object result = fory.deserialize(bytes);
+
+byte[] bytes = fory.serializeJavaObject(object);
+MyClass result = fory.deserializeJavaObject(bytes, MyClass.class);
+
+byte[] bytes = fory.serializeJavaObjectAndClass(object);
+Object result = fory.deserializeJavaObjectAndClass(bytes);
+```
+
+## 将 POJO 反序列化为另一种类型
+
+如果你想序列化一个 POJO 并将其反序列化为另一个 POJO 类型，你必须使用 `CompatibleMode.COMPATIBLE`：
+
+```java
+public class DeserializeIntoType {
+ static class Struct1 {
+ int f1;
+ String f2;
+
+ public Struct1(int f1, String f2) {
+ this.f1 = f1;
+ this.f2 = f2;
+ }
+ }
+
+ static class Struct2 {
+ int f1;
+ String f2;
+ double f3;
+ }
+
+ static ThreadSafeFory fory = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE).buildThreadSafeFory();
+
+ public static void main(String[] args) {
+ Struct1 struct1 = new Struct1(10, "abc");
+ byte[] data = fory.serializeJavaObject(struct1);
+ Struct2 struct2 = (Struct2) fory.deserializeJavaObject(data, Struct2.class);
+ }
+}
+```
+
+## 常见错误消息
+
+### "Class not registered"
+
+**原因**：需要类注册，但类未注册。
+
+**解决方案**：在序列化之前注册类：
+
+```java
+fory.register(MyClass.class);
+// 或使用显式 ID
+fory.register(MyClass.class, 100);
+```
+
+### "ClassNotCompatibleException"
+
+**原因**：序列化和反序列化之间的类 schema 不同。
+
+**解决方案**：使用兼容模式：
+
+```java
+Fory fory = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ .build();
+```
+
+### "Max depth exceeded"
+
+**原因**：对象图太深，可能表示循环引用攻击。
+
+**解决方案**：如果是合法的，增加最大深度，或检查恶意数据：
+
+```java
+Fory fory = Fory.builder()
+ .withMaxDepth(100) // 从默认的 50 增加
+ .build();
+```
+
+### "Serializer not found"
+
+**原因**：未为该类型注册序列化器。
+
+**解决方案**：注册自定义序列化器：
+
+```java
+fory.registerSerializer(MyClass.class, new MyClassSerializer(fory));
+```
+
+## 性能问题
+
+### 初始序列化慢
+
+**原因**：JIT 编译在第一次序列化时发生。
+
+**解决方案**：启用异步编译：
+
+```java
+Fory fory = Fory.builder()
+ .withAsyncCompilation(true)
+ .build();
+```
+
+### 内存使用高
+
+**原因**：大对象图或引用跟踪开销。
+
+**解决方案**：
+
+- 如果不需要，禁用引用跟踪：`.withRefTracking(false)`
+- 使用自定义内存分配器进行池化
+- 考虑对大数据集使用行格式
+
+### 序列化大小大
+
+**原因**：元数据开销或未压缩的数据。
+
+**解决方案**：
+
+- 启用压缩：`.withIntCompressed(true)`、`.withLongCompressed(true)`
+- 仅在需要时使用兼容模式
+- 注册类以避免类名序列化
+
+## 调试技巧
+
+1. **启用类版本检查**以诊断 schema 问题
+2. **检查 API 配对** - 确保序列化/反序列化 API 匹配
+3. **验证注册顺序** - 必须在各端之间保持一致
+4. **启用日志记录**以查看内部操作：
+
+```java
+LoggerFactory.setLogLevel(LogLevel.DEBUG_LEVEL);
+```
+
+## 相关主题
+
+- [配置选项](configuration.md) - 所有 ForyBuilder 选项
+- [Schema 演化](schema-evolution.md) - 兼容模式详情
+- [类型注册](type-registration.md) - 注册最佳实践
+- [迁移指南](migration.md) - 升级 Fory 版本
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/type-registration.md
new file mode 100644
index 000000000..eddc51c30
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/java/type-registration.md
@@ -0,0 +1,112 @@
+---
+title: 类型注册与安全
+sidebar_position: 3
+id: java_type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍类注册机制和安全配置。
+
+## 类注册
+
+`ForyBuilder#requireClassRegistration` 可用于禁用类注册。这将允许反序列化未知类型的对象，这更灵活但**如果类包含恶意代码可能不安全**。
+
+**除非你能确保环境是安全的，否则不要禁用类注册**。当禁用此选项时，反序列化未知/不受信任的类型时，`init/equals/hashCode` 中的恶意代码可能会被执行。
+
+类注册不仅可以降低安全风险，还可以避免类名序列化成本。
+
+### 按 ID 注册
+
+你可以使用 API `Fory#register` 注册类：
+
+```java
+Fory fory = xxx;
+fory.register(SomeClass.class);
+fory.register(SomeClass1.class, 1);
+```
+
+注意，类注册顺序很重要。序列化和反序列化端应该具有相同的注册顺序。
+
+### 按名称注册
+
+按 ID 注册类会有更好的性能和更小的空间开销。但在某些情况下，管理一堆类型 ID 很复杂。在这种情况下，建议使用 API `register(Class<?> cls, String namespace, String typeName)` 按名称注册类：
+
+```java
+fory.register(Foo.class, "demo", "Foo");
+```
+
+如果类型没有重复的名称，`namespace` 可以留空以减少序列化大小。
+
+**不要使用此 API 注册类，因为与按 ID 注册类相比，它会大大增加序列化大小。**
+
+## 安全配置
+
+### 类检查器
+
+如果你调用 `ForyBuilder#requireClassRegistration(false)` 来禁用类注册检查，你可以通过 `ClassResolver#setClassChecker` 设置 `org.apache.fory.resolver.ClassChecker` 来控制哪些类允许序列化。
+
+例如，你可以允许以 `org.example.*` 开头的类：
+
+```java
+Fory fory = xxx;
+fory.getClassResolver().setClassChecker(
+ (classResolver, className) -> className.startsWith("org.example."));
+```
+
+### AllowListChecker
+
+Fory 提供了 `org.apache.fory.resolver.AllowListChecker`，这是一个基于允许/禁止列表的检查器，用于简化类检查机制的自定义：
+
+```java
+AllowListChecker checker = new AllowListChecker(AllowListChecker.CheckLevel.STRICT);
+ThreadSafeFory fory = new ThreadLocalFory(classLoader -> {
+ Fory f = Fory.builder().requireClassRegistration(true).withClassLoader(classLoader).build();
+ f.getClassResolver().setClassChecker(checker);
+ checker.addListener(f.getClassResolver());
+ return f;
+});
+checker.allowClass("org.example.*");
+```
+
+你可以使用此检查器或自己实现更复杂的检查器。
+
+## 限制最大反序列化深度
+
+Fory 提供 `ForyBuilder#withMaxDepth` 来限制最大反序列化深度。默认最大深度为 50。
+
+如果达到最大深度，Fory 将抛出 `ForyException`。这可用于防止恶意数据导致堆栈溢出或其他问题。
+
+```java
+Fory fory = Fory.builder()
+ .withLanguage(Language.JAVA)
+ .withMaxDepth(100) // 设置自定义最大深度
+ .build();
+```
+
+## 最佳实践
+
+1. **在生产环境中始终启用类注册**：使用 `requireClassRegistration(true)`
+2. **使用基于 ID 的注册以获得性能**：数字 ID 比字符串名称更快
+3. **保持一致的注册顺序**：序列化和反序列化端的顺序相同
+4. **设置适当的最大深度**：防止堆栈溢出攻击
+5. **使用 AllowListChecker 进行细粒度控制**：当你需要灵活的类过滤时
+
+## 相关主题
+
+- [配置选项](configuration.md) - ForyBuilder 安全选项
+- [自定义序列化器](custom-serializers.md) - 注册自定义序列化器
+- [故障排除](troubleshooting.md) - 常见注册问题
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/_category_.json
new file mode 100644
index 000000000..bd051cc65
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "Kotlin",
+ "position": 8,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/default-values.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/default-values.md
new file mode 100644
index 000000000..283ef4ccf
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/default-values.md
@@ -0,0 +1,137 @@
+---
+title: 默认值
+sidebar_position: 3
+id: kotlin_default_values
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+在使用兼容模式时，Fory 支持在反序列化期间处理 Kotlin 数据类的默认值。此特性使得数据类 schema 演化时能够保持前向/后向兼容性。
+
+## 概述
+
+当 Kotlin 数据类具有带默认值的参数时，Fory 可以：
+
+1. **检测默认值**：使用 Kotlin 反射
+2. **应用默认值**：当序列化数据中缺少字段时，在反序列化期间应用默认值
+3. **支持 schema 演化**：允许添加带默认值的新字段，而不会破坏现有的序列化数据
+
+## 用法
+
+在以下情况下，此特性会自动启用：
+
+- 启用了兼容模式（`withCompatibleMode(CompatibleMode.COMPATIBLE)`）
+- 已注册 Kotlin 序列化器（`KotlinSerializers.registerSerializers(fory)`）
+- 序列化数据中缺少某个字段，但目标类中该字段存在并具有默认值
+
+## 示例
+
+```kotlin
+import org.apache.fory.Fory
+import org.apache.fory.config.CompatibleMode
+import org.apache.fory.serializer.kotlin.KotlinSerializers
+
+// 原始数据类
+data class User(val name: String, val age: Int)
+
+// 演化后的数据类，带有新字段和默认值
+data class UserV2(val name: String, val age: Int, val email: String = "default@example.com")
+
+fun main() {
+ val fory = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ .build()
+ KotlinSerializers.registerSerializers(fory)
+ fory.register(User::class.java)
+ fory.register(UserV2::class.java)
+
+ // 使用旧 schema 序列化
+ val oldUser = User("John", 30)
+ val serialized = fory.serialize(oldUser)
+
+ // 使用新 schema 反序列化 - 缺失的字段获得默认值
+ val newUser = fory.deserialize(serialized) as UserV2
+ println(newUser) // UserV2(name=John, age=30, email=default@example.com)
+}
+```
+
+## 支持的默认值类型
+
+以下类型支持默认值：
+
+- **原始类型**：`Int`、`Long`、`Double`、`Float`、`Boolean`、`Byte`、`Short`、`Char`
+- **无符号类型**：`UInt`、`ULong`、`UByte`、`UShort`
+- **字符串**：`String`
+- **集合**：`List`、`Set`、`Map`（带默认实例）
+- **自定义对象**：任何可以通过反射实例化的对象
+
+## 复杂的默认值
+
+默认值可以是复杂的表达式：
+
+```kotlin
+data class ConfigV1(val name: String)
+
+data class ConfigV2(
+ val name: String,
+ val settings: Map<String, String> = mapOf("default" to "value"),
+ val tags: List<String> = listOf("default"),
+ val enabled: Boolean = true,
+ val retryCount: Int = 3
+)
+
+val fory = Fory.builder()
+ .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ .build()
+KotlinSerializers.registerSerializers(fory)
+
+val original = ConfigV1("myConfig")
+val serialized = fory.serialize(original)
+
+val deserialized = fory.deserialize(serialized) as ConfigV2
+// deserialized.name == "myConfig"
+// deserialized.settings == mapOf("default" to "value")
+// deserialized.tags == listOf("default")
+// deserialized.enabled == true
+// deserialized.retryCount == 3
+```
+
+## 可空字段与默认值
+
+也支持带默认值的可空字段：
+
+```kotlin
+data class PersonV1(val name: String)
+
+data class PersonV2(
+ val name: String,
+ val nickname: String? = null,
+ val age: Int? = null
+)
+
+val original = PersonV1("John")
+val serialized = fory.serialize(original)
+
+val deserialized = fory.deserialize(serialized) as PersonV2
+// deserialized.name == "John"
+// deserialized.nickname == null (默认值)
+// deserialized.age == null (默认值)
+```
+
+## 相关主题
+
+- [Schema 演化](../java/schema-evolution.md) - Java 中的前向/后向兼容性
+- [Fory 创建](fory-creation.md) - 使用兼容模式设置 Fory
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/fory-creation.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/fory-creation.md
new file mode 100644
index 000000000..958cb3ea7
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/fory-creation.md
@@ -0,0 +1,116 @@
+---
+title: Fory 创建
+sidebar_position: 1
+id: kotlin_fory_creation
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍创建 Fory 实例的 Kotlin 特定要求。
+
+## 基本设置
+
+在使用 Fory 进行 Kotlin 序列化时，通过 `KotlinSerializers.registerSerializers(fory)` 注册 Kotlin 序列化器：
+
+```kotlin
+import org.apache.fory.Fory
+import org.apache.fory.serializer.kotlin.KotlinSerializers
+
+val fory = Fory.builder()
+ .requireClassRegistration(true)
+ .build()
+
+// 注册 Kotlin 序列化器
+KotlinSerializers.registerSerializers(fory)
+```
+
+## 线程安全
+
+Fory 实例的创建成本不低。实例应该在多次序列化之间共享。
+
+### 单线程使用
+
+```kotlin
+import org.apache.fory.Fory
+import org.apache.fory.serializer.kotlin.KotlinSerializers
+
+object ForyHolder {
+ val fory: Fory = Fory.builder()
+ .requireClassRegistration(true)
+ .build().also {
+ KotlinSerializers.registerSerializers(it)
+ }
+}
+```
+
+### 多线程使用
+
+对于多线程应用程序，使用 `ThreadSafeFory`：
+
+```kotlin
+import org.apache.fory.Fory
+import org.apache.fory.ThreadSafeFory
+import org.apache.fory.ThreadLocalFory
+import org.apache.fory.serializer.kotlin.KotlinSerializers
+
+object ForyHolder {
+ val fory: ThreadSafeFory = ThreadLocalFory { classLoader ->
+ Fory.builder()
+ .withClassLoader(classLoader)
+ .requireClassRegistration(true)
+ .build().also {
+ KotlinSerializers.registerSerializers(it)
+ }
+ }
+}
+```
+
+### 使用构建器方法
+
+```kotlin
+// 线程安全的 Fory
+val fory: ThreadSafeFory = Fory.builder()
+ .requireClassRegistration(true)
+ .buildThreadSafeFory()
+
+KotlinSerializers.registerSerializers(fory)
+```
+
+## 配置选项
+
+Fory Java 的所有配置选项都可用。完整列表请参阅 [Java 配置选项](../java/configuration.md)。
+
+Kotlin 的常用选项：
+
+```kotlin
+import org.apache.fory.Fory
+import org.apache.fory.config.CompatibleMode
+import org.apache.fory.serializer.kotlin.KotlinSerializers
+
+val fory = Fory.builder()
+ // 启用循环引用的引用跟踪
+ .withRefTracking(true)
+ // 启用 schema 演化支持
+ .withCompatibleMode(CompatibleMode.COMPATIBLE)
+ // 启用异步编译以获得更好的启动性能
+ .withAsyncCompilation(true)
+ // 压缩选项
+ .withIntCompressed(true)
+ .withLongCompressed(true)
+ .build()
+
+KotlinSerializers.registerSerializers(fory)
+```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/index.md
new file mode 100644
index 000000000..a926c1e6e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/index.md
@@ -0,0 +1,108 @@
+---
+title: Kotlin 序列化指南
+sidebar_position: 0
+id: kotlin_serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ Kotlin 基于 Fory Java 构建，为 Kotlin 类型提供了优化的序列化器。大多数标准 Kotlin 类型可以直接使用默认的 Fory Java 实现，而 Fory Kotlin 则为 Kotlin 特有的类型提供了额外的支持。
+
+支持的类型包括：
+
+- `data class` 序列化
+- 无符号原始类型：`UByte`、`UShort`、`UInt`、`ULong`
+- 无符号数组：`UByteArray`、`UShortArray`、`UIntArray`、`ULongArray`
+- 标准库类型：`Pair`、`Triple`、`Result`
+- 范围：`IntRange`、`LongRange`、`CharRange` 以及等差数列
+- 集合：`ArrayDeque`、空集合（`emptyList`、`emptyMap`、`emptySet`）
+- `kotlin.time.Duration`、`kotlin.text.Regex`、`kotlin.uuid.Uuid`
+
+## 特性
+
+Fory Kotlin 继承了 Fory Java 的所有特性，并增加了 Kotlin 特定的优化：
+
+- **高性能**：JIT 代码生成、零拷贝，比传统序列化快 20-170 倍
+- **Kotlin 类型支持**：为数据类、无符号类型、范围和标准库类型提供优化的序列化器
+- **默认值支持**：在 schema 演化期间自动处理 Kotlin 数据类的默认参数
+- **Schema 演化**：支持类 schema 变更的前向/后向兼容性
+
+完整特性列表请参阅 [Java 特性](../java/index.md#features)。
+
+## 安装
+
+### Maven
+
+```xml
+<dependency>
+ <groupId>org.apache.fory</groupId>
+ <artifactId>fory-kotlin</artifactId>
+ <version>0.14.0</version>
+</dependency>
+```
+
+### Gradle
+
+```kotlin
+implementation("org.apache.fory:fory-kotlin:0.14.0")
+```
+
+## 快速开始
+
+```kotlin
+import org.apache.fory.Fory
+import org.apache.fory.ThreadSafeFory
+import org.apache.fory.serializer.kotlin.KotlinSerializers
+
+data class Person(val name: String, val id: Long, val github: String)
+data class Point(val x: Int, val y: Int, val z: Int)
+
+fun main() {
+ // 创建 Fory 实例（应该重用）
+ val fory: ThreadSafeFory = Fory.builder()
+ .requireClassRegistration(true)
+ .buildThreadSafeFory()
+
+ // 注册 Kotlin 序列化器
+ KotlinSerializers.registerSerializers(fory)
+
+ // 注册你的类
+ fory.register(Person::class.java)
+ fory.register(Point::class.java)
+
+ val p = Person("Shawn Yang", 1, "https://github.com/chaokunyang")
+ println(fory.deserialize(fory.serialize(p)))
+ println(fory.deserialize(fory.serialize(Point(1, 2, 3))))
+}
+```
+
+## 基于 Fory Java 构建
+
+Fory Kotlin 基于 Fory Java 构建。Fory Java 的大多数配置选项、特性和概念直接适用于 Kotlin。请参阅 Java 文档了解：
+
+- [配置选项](../java/configuration.md) - 所有 ForyBuilder 选项
+- [基础序列化](../java/basic-serialization.md) - 序列化模式和 API
+- [类型注册](../java/type-registration.md) - 类注册和安全性
+- [Schema 演化](../java/schema-evolution.md) - 前向/后向兼容性
+- [自定义序列化器](../java/custom-serializers.md) - 实现自定义序列化器
+- [压缩](../java/compression.md) - Int、long 和字符串压缩
+- [故障排除](../java/troubleshooting.md) - 常见问题和解决方案
+
+## Kotlin 特定文档
+
+- [Fory 创建](fory-creation.md) - Kotlin 特定的 Fory 设置要求
+- [类型序列化](type-serialization.md) - 序列化 Kotlin 类型
+- [默认值](default-values.md) - Kotlin 数据类默认值支持
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/type-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/type-serialization.md
new file mode 100644
index 000000000..4d519d7ef
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/kotlin/type-serialization.md
@@ -0,0 +1,184 @@
+---
+title: 类型序列化
+sidebar_position: 2
+id: kotlin_type_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Kotlin 特定类型的序列化。
+
+## 设置
+
+所有示例都假定以下设置：
+
+```kotlin
+import org.apache.fory.Fory
+import org.apache.fory.serializer.kotlin.KotlinSerializers
+
+val fory = Fory.builder()
+ .requireClassRegistration(false)
+ .build()
+
+KotlinSerializers.registerSerializers(fory)
+```
+
+## 数据类
+
+```kotlin
+data class Person(val name: String, val age: Int, val id: Long)
+
+fory.register(Person::class.java)
+
+val p = Person("John", 30, 1L)
+println(fory.deserialize(fory.serialize(p)))
+```
+
+## 无符号原始类型
+
+完全支持 Kotlin 无符号类型：
+
+```kotlin
+val uByte: UByte = 255u
+val uShort: UShort = 65535u
+val uInt: UInt = 4294967295u
+val uLong: ULong = 18446744073709551615u
+
+println(fory.deserialize(fory.serialize(uByte)))
+println(fory.deserialize(fory.serialize(uShort)))
+println(fory.deserialize(fory.serialize(uInt)))
+println(fory.deserialize(fory.serialize(uLong)))
+```
+
+## 无符号数组
+
+```kotlin
+val uByteArray = ubyteArrayOf(1u, 2u, 255u)
+val uShortArray = ushortArrayOf(1u, 2u, 65535u)
+val uIntArray = uintArrayOf(1u, 2u, 4294967295u)
+val uLongArray = ulongArrayOf(1u, 2u, 18446744073709551615u)
+
+println(fory.deserialize(fory.serialize(uByteArray)).contentToString())
+println(fory.deserialize(fory.serialize(uShortArray)).contentToString())
+println(fory.deserialize(fory.serialize(uIntArray)).contentToString())
+println(fory.deserialize(fory.serialize(uLongArray)).contentToString())
+```
+
+## 标准库类型
+
+### Pair 和 Triple
+
+```kotlin
+val pair = Pair("key", 42)
+val triple = Triple("a", "b", "c")
+
+println(fory.deserialize(fory.serialize(pair)))
+println(fory.deserialize(fory.serialize(triple)))
+```
+
+### Result
+
+```kotlin
+val success: Result<Int> = Result.success(42)
+val failure: Result<Int> = Result.failure(Exception("error"))
+
+println(fory.deserialize(fory.serialize(success)))
+println(fory.deserialize(fory.serialize(failure)))
+```
+
+## 范围和等差数列
+
+```kotlin
+val intRange = 1..10
+val longRange = 1L..100L
+val charRange = 'a'..'z'
+
+println(fory.deserialize(fory.serialize(intRange)))
+println(fory.deserialize(fory.serialize(longRange)))
+println(fory.deserialize(fory.serialize(charRange)))
+
+// 等差数列
+val intProgression = 1..10 step 2
+val longProgression = 1L..100L step 10
+
+println(fory.deserialize(fory.serialize(intProgression)))
+println(fory.deserialize(fory.serialize(longProgression)))
+```
+
+## 集合
+
+### ArrayDeque
+
+```kotlin
+val deque = ArrayDeque<String>()
+deque.addFirst("first")
+deque.addLast("last")
+
+println(fory.deserialize(fory.serialize(deque)))
+```
+
+### 空集合
+
+```kotlin
+val emptyList = emptyList<String>()
+val emptySet = emptySet<Int>()
+val emptyMap = emptyMap<String, Int>()
+
+println(fory.deserialize(fory.serialize(emptyList)))
+println(fory.deserialize(fory.serialize(emptySet)))
+println(fory.deserialize(fory.serialize(emptyMap)))
+```
+
+## Duration
+
+```kotlin
+import kotlin.time.Duration
+import kotlin.time.Duration.Companion.hours
+import kotlin.time.Duration.Companion.minutes
+
+val duration: Duration = 2.hours + 30.minutes
+
+println(fory.deserialize(fory.serialize(duration)))
+```
+
+## Regex
+
+```kotlin
+val regex = Regex("[a-zA-Z]+")
+
+println(fory.deserialize(fory.serialize(regex)))
+```
+
+## UUID（Kotlin 2.0+）
+
+```kotlin
+import kotlin.uuid.Uuid
+
+val uuid = Uuid.random()
+
+println(fory.deserialize(fory.serialize(uuid)))
+```
+
+## 开箱即用的类型
+
+以下类型可以使用默认的 Fory Java 实现，无需使用 `KotlinSerializers`：
+
+- **原始类型**：`Byte`、`Boolean`、`Int`、`Short`、`Long`、`Char`、`Float`、`Double`
+- **字符串**：`String`
+- **集合**：`ArrayList`、`HashMap`、`HashSet`、`LinkedHashSet`、`LinkedHashMap`
+- **数组**：`Array`、`BooleanArray`、`ByteArray`、`CharArray`、`DoubleArray`、`FloatArray`、`IntArray`、`LongArray`、`ShortArray`
+
+但是，建议始终调用 `KotlinSerializers.registerSerializers(fory)` 以确保正确支持所有 Kotlin 类型。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/_category_.json
new file mode 100644
index 000000000..a964bce6e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "Python",
+ "position": 1,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/basic-serialization.md
new file mode 100644
index 000000000..8a6df140e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/basic-serialization.md
@@ -0,0 +1,145 @@
+---
+title: 基础序列化
+sidebar_position: 2
+id: python_basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 pyfory 中的基础序列化模式。
+
+## 基础对象序列化
+
+使用简单的 API 序列化和反序列化 Python 对象：
+
+```python
+import pyfory
+
+# 创建 Fory 实例
+fory = pyfory.Fory(xlang=True)
+
+# 序列化任何 Python 对象
+data = fory.dumps({"name": "Alice", "age": 30, "scores": [95, 87, 92]})
+
+# 反序列化回 Python 对象
+obj = fory.loads(data)
+print(obj) # {'name': 'Alice', 'age': 30, 'scores': [95, 87, 92]}
+```
+
+**注意**：`dumps()`/`loads()` 是 `serialize()`/`deserialize()` 的别名。两个 API 完全相同，使用任何一个都可以。
+
+## 自定义类序列化
+
+Fory 自动处理 dataclass 和自定义类型：
+
+```python
+import pyfory
+from dataclasses import dataclass
+from typing import List, Dict
+
+@dataclass
+class Person:
+ name: str
+ age: int
+ scores: List[int]
+ metadata: Dict[str, str]
+
+# Python 模式 - 支持所有 Python 类型，包括 dataclass
+fory = pyfory.Fory(xlang=False, ref=True)
+fory.register(Person)
+person = Person("Bob", 25, [88, 92, 85], {"team": "engineering"})
+data = fory.serialize(person)
+result = fory.deserialize(data)
+print(result) # Person(name='Bob', age=25, ...)
+```
+
+## 引用跟踪和循环引用
+
+安全处理共享引用和循环依赖：
+
+```python
+import pyfory
+
+f = pyfory.Fory(ref=True) # 启用引用跟踪
+
+# 安全处理循环引用
+class Node:
+ def __init__(self, value):
+ self.value = value
+ self.children = []
+ self.parent = None
+
+root = Node("root")
+child = Node("child")
+child.parent = root # 循环引用
+root.children.append(child)
+
+# 序列化不会导致无限递归
+data = f.serialize(root)
+result = f.deserialize(data)
+assert result.children[0].parent is result # 引用被保留
+```
+
+## API 参考
+
+### 序列化方法
+
+```python
+# 序列化为字节
+data: bytes = fory.serialize(obj)
+data: bytes = fory.dumps(obj) # 别名
+
+# 从字节反序列化
+obj = fory.deserialize(data)
+obj = fory.loads(data) # 别名
+```
+
+### 使用带外缓冲区
+
+```python
+# 使用缓冲区回调序列化
+buffer_objects = []
+data = fory.serialize(obj, buffer_callback=buffer_objects.append)
+
+# 使用缓冲区反序列化
+buffers = [obj.getbuffer() for obj in buffer_objects]
+obj = fory.deserialize(data, buffers=buffers)
+```
+
+## 性能提示
+
+1. **如果不需要则禁用 `ref=True`**：引用跟踪有开销
+2. **使用 type_id 而不是 typename**：整数 ID 比字符串名称更快
+3. **重用 Fory 实例**：创建一次，多次使用
+4. **启用 Cython**：确保 `ENABLE_FORY_CYTHON_SERIALIZATION=1`
+
+```python
+# 好：重用实例
+fory = pyfory.Fory()
+for obj in objects:
+ data = fory.dumps(obj)
+
+# 坏：每次创建新实例
+for obj in objects:
+ fory = pyfory.Fory() # 浪费！
+ data = fory.dumps(obj)
+```
+
+## 相关主题
+
+- [配置](configuration.md) - Fory 参数
+- [类型注册](type-registration.md) - 注册模式
+- [Python 原生模式](python-native.md) - 函数和 lambda
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/configuration.md
new file mode 100644
index 000000000..dbd09a4ad
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/configuration.md
@@ -0,0 +1,181 @@
+---
+title: 配置
+sidebar_position: 1
+id: python_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍 Fory 配置参数和语言模式。
+
+## Fory 类
+
+主要序列化接口：
+
+```python
+class Fory:
+ def __init__(
+ self,
+ xlang: bool = False,
+ ref: bool = False,
+ strict: bool = True,
+ compatible: bool = False,
+ max_depth: int = 50
+ )
+```
+
+## ThreadSafeFory 类
+
+使用线程本地存储的线程安全序列化接口：
+
+```python
+class ThreadSafeFory:
+ def __init__(
+ self,
+ xlang: bool = False,
+ ref: bool = False,
+ strict: bool = True,
+ compatible: bool = False,
+ max_depth: int = 50
+ )
+```
+
+## 参数
+
+| 参数 | 类型 | 默认值 | 描述 |
+| ------------ | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `xlang` | `bool` | `False` | 启用跨语言序列化。当为 `False` 时，启用 Python 原生模式，支持所有 Python 对象。当为 `True` 时，启用跨语言模式，兼容 Java、Go、Rust 等。 |
+| `ref` | `bool` | `False` | 启用引用跟踪以支持共享/循环引用。如果数据没有共享引用，禁用此选项可获得更好性能。 |
+| `strict` | `bool` | `True` | 出于安全考虑需要类型注册。**生产环境强烈推荐**。仅在受信任的环境中禁用。 |
+| `compatible` | `bool` | `False` | 在跨语言模式中启用 schema 演化，允许在保持兼容性的同时添加/删除字段。 |
+| `max_depth` | `int` | `50` | 反序列化的最大深度，用于安全防护，防止栈溢出攻击。 |
+
+## 核心方法
+
+```python
+# 序列化（serialize/deserialize 与 dumps/loads 完全相同）
+data: bytes = fory.serialize(obj)
+obj = fory.deserialize(data)
+
+# 替代 API（别名）
+data: bytes = fory.dumps(obj)
+obj = fory.loads(data)
+
+# 按 ID 注册类型（用于 Python 模式）
+fory.register(MyClass, type_id=123)
+fory.register(MyClass, type_id=123, serializer=custom_serializer)
+
+# 按名称注册类型（用于跨语言模式）
+fory.register(MyClass, typename="my.package.MyClass")
+fory.register(MyClass, typename="my.package.MyClass", serializer=custom_serializer)
+```
+
+## 语言模式比较
+
+| 特性 | Python 模式 (`xlang=False`) | 跨语言模式 (`xlang=True`) |
+| --------------- | -------------------------------- | ---------------------------------- |
+| **使用场景** | 纯 Python 应用 | 多语言系统 |
+| **兼容性** | 仅限 Python | Java、Go、Rust、C++、JavaScript 等 |
+| **支持的类型** | 所有 Python 类型 | 仅限跨语言兼容类型 |
+| **函数/Lambda** | ✓ 支持 | ✗ 不允许 |
+| **本地类** | ✓ 支持 | ✗ 不允许 |
+| **动态类** | ✓ 支持 | ✗ 不允许 |
+| **Schema 演化** | ✓ 支持（需要 `compatible=True`） | ✓ 支持（需要 `compatible=True`） |
+| **性能** | 极快 | 非常快 |
+| **数据大小** | 紧凑 | 紧凑（带类型元数据） |
+
+## Python 模式 (`xlang=False`)
+
+Python 模式支持所有 Python 类型，包括函数、类和闭包：
+
+```python
+import pyfory
+
+# 完全 Python 兼容模式
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+# 支持所有 Python 对象：
+data = fory.dumps({
+ 'function': lambda x: x * 2, # 函数和 lambda
+ 'class': type('Dynamic', (), {}), # 动态类
+ 'method': str.upper, # 方法
+ 'nested': {'circular_ref': None} # 循环引用（当 ref=True 时）
+})
+
+# 可直接替代 pickle/cloudpickle
+import pickle
+obj = [1, 2, {"nested": [3, 4]}]
+assert fory.loads(fory.dumps(obj)) == pickle.loads(pickle.dumps(obj))
+```
+
+## 跨语言模式 (`xlang=True`)
+
+跨语言模式将类型限制为所有 Fory 实现间兼容的类型：
+
+```python
+import pyfory
+
+# 跨语言兼容模式
+f = pyfory.Fory(xlang=True, ref=True)
+
+# 仅支持跨语言兼容类型
+f.register(MyDataClass, typename="com.example.MyDataClass")
+
+# 数据可以被 Java、Go、Rust 等读取
+data = f.serialize(MyDataClass(field1="value", field2=42))
+```
+
+## 示例配置
+
+### 生产环境配置
+
+```python
+import pyfory
+
+# 生产环境推荐设置
+fory = pyfory.Fory(
+ xlang=False, # 如果需要跨语言支持则使用 True
+ ref=False, # 如果有共享/循环引用则启用
+ strict=True, # 关键：生产环境始终为 True
+ compatible=False, # 仅在需要 schema 演化时启用
+ max_depth=20 # 根据数据结构深度调整
+)
+
+# 预先注册所有类型
+fory.register(UserModel, type_id=100)
+fory.register(OrderModel, type_id=101)
+fory.register(ProductModel, type_id=102)
+```
+
+### 开发环境配置
+
+```python
+import pyfory
+
+# 开发设置（更宽松）
+fory = pyfory.Fory(
+ xlang=False,
+ ref=True,
+ strict=False, # 开发时允许任何类型
+ max_depth=1000 # 开发时更高的限制
+)
+```
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 使用已配置的 Fory
+- [类型注册](type-registration.md) - 注册模式
+- [安全性](security.md) - 安全最佳实践
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/cross-language.md
new file mode 100644
index 000000000..755d5a39b
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/cross-language.md
@@ -0,0 +1,140 @@
+---
+title: 跨语言序列化
+sidebar_position: 10
+id: python_cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+`pyfory` 支持跨语言对象图序列化，允许您在 Python 中序列化数据，并在 Java、Go、Rust 或其他支持的语言中反序列化。
+
+## 启用跨语言模式
+
+要使用 xlang 模式，创建 `Fory` 时设置 `xlang=True`：
+
+```python
+import pyfory
+fory = pyfory.Fory(xlang=True, ref=False, strict=True)
+```
+
+## 跨语言示例
+
+### Python（序列化器）
+
+```python
+import pyfory
+from dataclasses import dataclass
+
+# 跨语言模式实现互操作性
+f = pyfory.Fory(xlang=True, ref=True)
+
+# 注册类型以实现跨语言兼容性
+@dataclass
+class Person:
+ name: str
+ age: pyfory.int32
+
+f.register(Person, typename="example.Person")
+
+person = Person("Charlie", 35)
+binary_data = f.serialize(person)
+# binary_data 现在可以发送到 Java、Go 等
+```
+
+### Java（反序列化器）
+
+```java
+import org.apache.fory.*;
+
+public class Person {
+ public String name;
+ public int age;
+}
+
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true)
+ .build();
+
+fory.register(Person.class, "example.Person");
+Person person = (Person) fory.deserialize(binaryData);
+```
+
+### Rust（反序列化器）
+
+```rust
+use fory::Fory;
+use fory::ForyObject;
+
+#[derive(ForyObject)]
+struct Person {
+ name: String,
+ age: i32,
+}
+
+let mut fory = Fory::default()
+ .compatible(true)
+ .xlang(true);
+
+fory.register_by_namespace::<Person>("example", "Person");
+let person: Person = fory.deserialize(&binary_data)?;
+```
+
+## 跨语言的类型注解
+
+使用 pyfory 类型注解进行显式跨语言类型映射：
+
+```python
+from dataclasses import dataclass
+import pyfory
+
+@dataclass
+class TypedData:
+ int_value: pyfory.int32 # 32 位整数
+ long_value: pyfory.int64 # 64 位整数
+ float_value: pyfory.float32 # 32 位浮点数
+ double_value: pyfory.float64 # 64 位浮点数
+```
+
+## 类型映射
+
+| Python | Java | Rust | Go |
+| ---------------- | -------- | --------- | --------- |
+| `str` | `String` | `String` | `string` |
+| `int` | `long` | `i64` | `int64` |
+| `pyfory.int32` | `int` | `i32` | `int32` |
+| `pyfory.int64` | `long` | `i64` | `int64` |
+| `float` | `double` | `f64` | `float64` |
+| `pyfory.float32` | `float` | `f32` | `float32` |
+| `list` | `List` | `Vec` | `[]T` |
+| `dict` | `Map` | `HashMap` | `map[K]V` |
+
+## 与 Python 原生模式的区别
+
+二进制协议和 API 与 `pyfory` 的 Python 原生模式类似，但 Python 原生模式可以序列化任何 Python 对象——包括全局函数、局部函数、lambda、局部类以及使用 `__getstate__/__reduce__/__reduce_ex__` 自定义序列化的类型，这些在 xlang 模式中**不允许**。
+
+## 另请参阅
+
+- [跨语言序列化规范](https://fory.apache.org/docs/next/specification/fory_xlang_serialization_spec)
+- [类型映射参考](https://fory.apache.org/docs/next/specification/xlang_type_mapping)
+- [Java 跨语言指南](../java/cross-language.md)
+- [Rust 跨语言指南](../rust/cross-language.md)
+
+## 相关主题
+
+- [配置](configuration.md) - XLANG 模式设置
+- [Schema 演化](schema-evolution.md) - 兼容模式
+- [类型注册](type-registration.md) - 注册模式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/custom-serializers.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/custom-serializers.md
new file mode 100644
index 000000000..979ee24e9
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/custom-serializers.md
@@ -0,0 +1,146 @@
+---
+title: 自定义序列化器
+sidebar_position: 4
+id: python_custom_serializers
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+为特殊类型实现自定义序列化逻辑。
+
+## 实现自定义序列化器
+
+为 Python 模式覆盖 `write/read`，为跨语言模式覆盖 `xwrite/xread`：
+
+```python
+import pyfory
+from pyfory.serializer import Serializer
+from dataclasses import dataclass
+
+@dataclass
+class Foo:
+ f1: int
+ f2: str
+
+class FooSerializer(Serializer):
+ def __init__(self, fory, cls):
+ super().__init__(fory, cls)
+
+ def write(self, buffer, obj: Foo):
+ # 自定义序列化逻辑
+ buffer.write_varint32(obj.f1)
+ buffer.write_string(obj.f2)
+
+ def read(self, buffer):
+ # 自定义反序列化逻辑
+ f1 = buffer.read_varint32()
+ f2 = buffer.read_string()
+ return Foo(f1, f2)
+
+ # 用于跨语言模式
+ def xwrite(self, buffer, obj: Foo):
+ buffer.write_int32(obj.f1)
+ buffer.write_string(obj.f2)
+
+ def xread(self, buffer):
+ return Foo(buffer.read_int32(), buffer.read_string())
+
+f = pyfory.Fory()
+f.register(Foo, type_id=100, serializer=FooSerializer(f, Foo))
+
+# 现在 Foo 使用自定义序列化器
+data = f.dumps(Foo(42, "hello"))
+result = f.loads(data)
+print(result) # Foo(f1=42, f2='hello')
+```
+
+## Buffer API
+
+### 写入方法
+
+```python
+# 整数
+buffer.write_int8(value)
+buffer.write_int16(value)
+buffer.write_int32(value)
+buffer.write_int64(value)
+
+# 变长整数
+buffer.write_varint32(value)
+buffer.write_varint64(value)
+
+# 浮点数
+buffer.write_float32(value)
+buffer.write_float64(value)
+
+# 字符串和字节
+buffer.write_string(value)
+buffer.write_bytes(value)
+
+# 布尔值
+buffer.write_bool(value)
+```
+
+### 读取方法
+
+```python
+# 整数
+value = buffer.read_int8()
+value = buffer.read_int16()
+value = buffer.read_int32()
+value = buffer.read_int64()
+
+# 变长整数
+value = buffer.read_varint32()
+value = buffer.read_varint64()
+
+# 浮点数
+value = buffer.read_float32()
+value = buffer.read_float64()
+
+# 字符串和字节
+value = buffer.read_string()
+value = buffer.read_bytes(length)
+
+# 布尔值
+value = buffer.read_bool()
+```
+
+## 何时使用自定义序列化器
+
+- 来自其他包的外部类型
+- 具有特殊序列化需求的类型
+- 旧数据格式兼容性
+- 性能关键的自定义编码
+- 自动序列化效果不好的类型
+
+## 注册自定义序列化器
+
+```python
+fory = pyfory.Fory()
+
+# 使用 type_id 注册
+fory.register(MyClass, type_id=100, serializer=MySerializer(fory, MyClass))
+
+# 使用 typename 注册（用于 xlang）
+fory.register(MyClass, typename="com.example.MyClass", serializer=MySerializer(fory, MyClass))
+```
+
+## 相关主题
+
+- [类型注册](type-registration.md) - 注册模式
+- [配置](configuration.md) - Fory 参数
+- [跨语言](cross-language.md) - xlang 的 xwrite/xread
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/index.md
new file mode 100644
index 000000000..cf10eb994
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/index.md
@@ -0,0 +1,160 @@
+---
+title: Python 序列化指南
+sidebar_position: 0
+id: python_serialization_index
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+**Apache Fory™** 是一个极速的多语言序列化框架，基于 **JIT 编译**和**零拷贝**技术，在保持易用性和安全性的同时提供**超高性能**。
+
+`pyfory` 提供 Apache Fory™ 的 Python 实现，为数据处理任务提供高性能对象序列化和先进的行格式能力。
+
+## 核心特性
+
+### 灵活的序列化模式
+
+- **Python 原生模式**：完全 Python 兼容，可替代 pickle/cloudpickle
+- **跨语言模式**：针对多语言数据交换优化
+- **行格式**：用于分析工作负载的零拷贝行格式
+
+### 多功能序列化特性
+
+- **共享/循环引用支持**：在 Python 原生和跨语言模式中支持复杂对象图
+- **多态支持**：自定义类型的自动类型分发
+- **Schema 演化支持**：在跨语言模式下使用 dataclass 时的向后/向前兼容性
+- **带外缓冲区支持**：零拷贝序列化大型数据结构（如 NumPy 数组和 Pandas DataFrame），兼容 pickle 协议 5
+
+### 极速性能
+
+- **超快性能**：相比其他序列化框架
+- **运行时代码生成**和 **Cython 加速**的核心实现，实现最优性能
+
+### 紧凑数据大小
+
+- **紧凑的对象图协议**：最小空间开销——相比 pickle/cloudpickle 减少高达 3 倍大小
+- **元数据打包与共享**：最小化类型向前/向后兼容性的空间开销
+
+### 安全性与安全
+
+- **严格模式**：通过类型注册和检查防止反序列化不受信任的类型
+- **引用跟踪**：安全处理循环引用
+
+## 安装
+
+### 基础安装
+
+```bash
+pip install pyfory
+```
+
+### 可选依赖
+
+```bash
+# 安装行格式支持（需要 Apache Arrow）
+pip install pyfory[format]
+
+# 从源码安装用于开发
+git clone https://github.com/apache/fory.git
+cd fory/python
+pip install -e ".[dev,format]"
+```
+
+### 系统要求
+
+- **Python**：3.8 或更高版本
+- **操作系统**：Linux、macOS、Windows
+
+## 线程安全
+
+`pyfory` 提供 `ThreadSafeFory` 用于线程安全序列化，使用线程本地存储：
+
+```python
+import pyfory
+import threading
+from dataclasses import dataclass
+
+@dataclass
+class Person:
+ name: str
+ age: int
+
+# 创建线程安全的 Fory 实例
+fory = pyfory.ThreadSafeFory(xlang=False, ref=True)
+fory.register(Person)
+
+# 在多线程中安全使用
+def serialize_in_thread(thread_id):
+ person = Person(name=f"User{thread_id}", age=25 + thread_id)
+ data = fory.serialize(person)
+ result = fory.deserialize(data)
+ print(f"Thread {thread_id}: {result}")
+
+threads = [threading.Thread(target=serialize_in_thread, args=(i,)) for i in range(10)]
+for t in threads: t.start()
+for t in threads: t.join()
+```
+
+**核心特性：**
+
+- **实例池**：维护一个受锁保护的 `Fory` 实例池，确保线程安全
+- **共享配置**：所有注册必须预先完成，并应用于所有实例
+- **相同 API**：与 `Fory` 类相同的方法，可直接替换
+- **注册安全**：防止首次使用后注册，确保一致性
+
+**适用场景：**
+
+- **多线程应用程序**：Web 服务器、并发工作线程、并行处理
+- **共享 Fory 实例**：当多个线程需要序列化/反序列化数据时
+- **线程池**：使用线程池或 concurrent.futures 的应用程序
+
+## 快速开始
+
+```python
+import pyfory
+from dataclasses import dataclass
+
+@dataclass
+class Person:
+ name: str
+ age: int
+
+# 创建 Fory 实例
+fory = pyfory.Fory(xlang=False, ref=True)
+fory.register(Person)
+
+person = Person("Alice", 30)
+data = fory.serialize(person)
+result = fory.deserialize(data)
+print(result) # Person(name='Alice', age=30)
+```
+
+## 后续步骤
+
+- [配置](configuration.md) - Fory 参数和模式
+- [基础序列化](basic-serialization.md) - 基础使用模式
+- [Python 原生模式](python-native.md) - 函数、lambda、类
+- [跨语言](cross-language.md) - XLANG 模式
+- [行格式](row-format.md) - 零拷贝行格式
+- [安全性](security.md) - 安全最佳实践
+
+## 链接
+
+- **文档**：https://fory.apache.org/docs/latest/python_guide/
+- **GitHub**：https://github.com/apache/fory
+- **PyPI**：https://pypi.org/project/pyfory/
+- **问题反馈**：https://github.com/apache/fory/issues
+- **Slack**：https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/migration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/migration.md
new file mode 100644
index 000000000..7ceb761f6
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/migration.md
@@ -0,0 +1,85 @@
+---
+title: 迁移指南
+sidebar_position: 12
+id: python_migration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍如何从 pickle 和 JSON 迁移到 pyfory。
+
+## 从 Pickle 迁移
+
+用 Fory 替换 pickle，在保持相同 API 的同时获得更好的性能：
+
+```python
+# 之前（pickle）
+import pickle
+data = pickle.dumps(obj)
+result = pickle.loads(data)
+
+# 之后（Fory - 直接替换，性能更好）
+import pyfory
+f = pyfory.Fory(xlang=False, ref=True, strict=False)
+data = f.dumps(obj) # 更快且更紧凑
+result = f.loads(data) # 更快的反序列化
+
+# 优势：
+# - 序列化快 2-10 倍
+# - 反序列化快 2-5 倍
+# - 数据大小减少高达 3 倍
+# - 相同的 API，更好的性能
+```
+
+## 从 JSON 迁移
+
+与 JSON 不同，Fory 支持包括函数在内的任意 Python 类型：
+
+```python
+# 之前（JSON - 类型受限）
+import json
+data = json.dumps({"name": "Alice", "age": 30})
+result = json.loads(data)
+
+# 之后（Fory - 所有 Python 类型）
+import pyfory
+f = pyfory.Fory()
+data = f.dumps({"name": "Alice", "age": 30, "func": lambda x: x})
+result = f.loads(data)
+```
+
+## 主要区别
+
+| 特性 | pickle | JSON | pyfory |
+| -------- | ----------- | ---- | ---------------- |
+| 性能 | 中等 | 慢 | 快 |
+| 数据大小 | 大 | 大 | 紧凑 |
+| 类型支持 | 所有 Python | 受限 | 所有 Python |
+| 跨语言 | 否 | 是 | 是（xlang 模式） |
+| 安全性 | 低 | 高 | 可配置 |
+
+## 迁移提示
+
+1. **从 strict=False 开始** 以确保兼容性
+2. **添加类型注册** 以提高性能和安全性
+3. **在部署前彻底测试**
+4. **监控性能** 改进
+
+## 相关主题
+
+- [配置](configuration.md) - Fory 参数
+- [Python 原生模式](python-native.md) - Pickle 替换功能
+- [安全性](security.md) - 安全最佳实践
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/numpy-integration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/numpy-integration.md
new file mode 100644
index 000000000..c36691f9e
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/numpy-integration.md
@@ -0,0 +1,103 @@
+---
+title: NumPy 与科学计算
+sidebar_position: 8
+id: python_numpy_integration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory 原生支持 numpy 数组，提供优化的序列化。
+
+## NumPy 数组序列化
+
+大型数组在可能的情况下使用零拷贝：
+
+```python
+import pyfory
+import numpy as np
+
+f = pyfory.Fory()
+
+# 原生支持 Numpy 数组
+arrays = {
+ 'matrix': np.random.rand(1000, 1000),
+ 'vector': np.arange(10000),
+ 'bool_mask': np.random.choice([True, False], size=5000)
+}
+
+data = f.serialize(arrays)
+result = f.deserialize(data)
+
+# 对于兼容的数组类型使用零拷贝
+assert np.array_equal(arrays['matrix'], result['matrix'])
+```
+
+## Pandas DataFrame
+
+Fory 可以高效序列化 Pandas DataFrame：
+
+```python
+import pyfory
+import pandas as pd
+import numpy as np
+
+f = pyfory.Fory(xlang=False, ref=False, strict=False)
+
+df = pd.DataFrame({
+ 'a': np.arange(1000, dtype=np.float64),
+ 'b': np.arange(1000, dtype=np.int64),
+ 'c': ['text'] * 1000
+})
+
+data = f.serialize(df)
+result = f.deserialize(data)
+
+assert df.equals(result)
+```
+
+## 使用带外缓冲区的零拷贝
+
+对于大型数组的最大性能，使用带外序列化：
+
+```python
+import pyfory
+import numpy as np
+
+f = pyfory.Fory(xlang=False, ref=False, strict=False)
+
+# 大型数组
+array = np.random.rand(10000, 1000)
+
+# 带外零拷贝
+buffer_objects = []
+data = f.serialize(array, buffer_callback=buffer_objects.append)
+buffers = [obj.getbuffer() for obj in buffer_objects]
+
+result = f.deserialize(data, buffers=buffers)
+assert np.array_equal(array, result)
+```
+
+## 支持的数组类型
+
+- `np.ndarray`（所有 dtype）
+- `np.matrix`
+- 结构化数组
+- 记录数组
+
+## 相关主题
+
+- [带外序列化](out-of-band.md) - 零拷贝缓冲区
+- [基础序列化](basic-serialization.md) - 标准用法
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/out-of-band.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/out-of-band.md
new file mode 100644
index 000000000..fd74aee35
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/out-of-band.md
@@ -0,0 +1,179 @@
+---
+title: 带外序列化
+sidebar_position: 7
+id: python_out_of_band
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Fory 支持 pickle5 兼容的带外缓冲区序列化，用于高效零拷贝处理大型数据结构。
+
+## 概述
+
+带外序列化将元数据与实际数据缓冲区分离，允许：
+
+- **零拷贝传输**：使用 `memoryview` 通过网络或 IPC 发送数据时
+- **提高性能**：用于大型数据集
+- **Pickle5 兼容性**：使用 `pickle.PickleBuffer`
+- **灵活的流支持**：写入任何可写对象（文件、BytesIO、套接字等）
+
+## 基础带外序列化
+
+```python
+import pyfory
+import numpy as np
+
+fory = pyfory.Fory(xlang=False, ref=False, strict=False)
+
+# 大型 numpy 数组
+array = np.arange(10000, dtype=np.float64)
+
+# 使用带外缓冲区序列化
+buffer_objects = []
+serialized_data = fory.serialize(array, buffer_callback=buffer_objects.append)
+
+# 将缓冲区对象转换为 memoryview 以进行零拷贝传输
+# 对于连续缓冲区（bytes、numpy 数组），这是零拷贝
+# 对于非连续数据，可能会创建副本以确保连续性
+buffers = [obj.getbuffer() for obj in buffer_objects]
+
+# 使用带外缓冲区反序列化（接受 memoryview、bytes 或 Buffer）
+deserialized_array = fory.deserialize(serialized_data, buffers=buffers)
+
+assert np.array_equal(array, deserialized_array)
+```
+
+## 使用 Pandas DataFrame 的带外序列化
+
+```python
+import pyfory
+import pandas as pd
+import numpy as np
+
+fory = pyfory.Fory(xlang=False, ref=False, strict=False)
+
+# 创建带数值列的 DataFrame
+df = pd.DataFrame({
+ 'a': np.arange(1000, dtype=np.float64),
+ 'b': np.arange(1000, dtype=np.int64),
+ 'c': ['text'] * 1000
+})
+
+# 使用带外缓冲区序列化
+buffer_objects = []
+serialized_data = fory.serialize(df, buffer_callback=buffer_objects.append)
+buffers = [obj.getbuffer() for obj in buffer_objects]
+
+# 反序列化
+deserialized_df = fory.deserialize(serialized_data, buffers=buffers)
+
+assert df.equals(deserialized_df)
+```
+
+## 选择性带外序列化
+
+通过提供回调来控制哪些缓冲区带外传输，该回调返回 `True` 保持数据内联或返回 `False` 带外发送：
+
+```python
+import pyfory
+import numpy as np
+
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+arr1 = np.arange(1000, dtype=np.float64)
+arr2 = np.arange(2000, dtype=np.float64)
+data = [arr1, arr2]
+
+buffer_objects = []
+counter = 0
+
+def selective_callback(buffer_object):
+ global counter
+ counter += 1
+ # 只有偶数编号的缓冲区带外发送
+ if counter % 2 == 0:
+ buffer_objects.append(buffer_object)
+ return False # 带外
+ return True # 内联
+
+serialized = fory.serialize(data, buffer_callback=selective_callback)
+buffers = [obj.getbuffer() for obj in buffer_objects]
+deserialized = fory.deserialize(serialized, buffers=buffers)
+```
+
+## Pickle5 兼容性
+
+Fory 的带外序列化完全兼容 pickle 协议 5：
+
+```python
+import pyfory
+import pickle
+
+fory = pyfory.Fory(xlang=False, ref=False, strict=False)
+
+# 自动支持 PickleBuffer 对象
+data = b"Large binary data"
+pickle_buffer = pickle.PickleBuffer(data)
+
+# 使用缓冲区回调序列化以进行带外处理
+buffer_objects = []
+serialized = fory.serialize(pickle_buffer, buffer_callback=buffer_objects.append)
+buffers = [obj.getbuffer() for obj in buffer_objects]
+
+# 使用缓冲区反序列化
+deserialized = fory.deserialize(serialized, buffers=buffers)
+assert bytes(deserialized.raw()) == data
+```
+
+## 将缓冲区写入不同的流
+
+`BufferObject.write_to()` 方法接受任何可写流对象：
+
+```python
+import pyfory
+import numpy as np
+import io
+
+fory = pyfory.Fory(xlang=False, ref=False, strict=False)
+
+array = np.arange(1000, dtype=np.float64)
+
+# 收集带外缓冲区
+buffer_objects = []
+serialized = fory.serialize(array, buffer_callback=buffer_objects.append)
+
+# 写入不同的流类型
+for buffer_obj in buffer_objects:
+ # 写入 BytesIO（内存流）
+ bytes_stream = io.BytesIO()
+ buffer_obj.write_to(bytes_stream)
+
+ # 写入文件
+ with open('/tmp/buffer_data.bin', 'wb') as f:
+ buffer_obj.write_to(f)
+
+ # 获取零拷贝 memoryview（用于连续缓冲区）
+ mv = buffer_obj.getbuffer()
+ assert isinstance(mv, memoryview)
+```
+
+**注意**：对于连续内存缓冲区（如 bytes、numpy 数组），`getbuffer()` 返回零拷贝 `memoryview`。对于非连续数据，可能会创建副本以确保连续性。
+
+## 相关主题
+
+- [NumPy 集成](numpy-integration.md) - NumPy 数组序列化
+- [基础序列化](basic-serialization.md) - 标准序列化
+- [配置](configuration.md) - Fory 参数
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/python-native.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/python-native.md
new file mode 100644
index 000000000..3ac78693f
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/python-native.md
@@ -0,0 +1,205 @@
+---
+title: Python 原生模式
+sidebar_position: 5
+id: python_native_mode
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+`pyfory` 提供了 Python 原生序列化模式，提供与 pickle/cloudpickle 相同的功能，但具有**显著更好的性能、更小的数据大小和增强的安全特性**。
+
+## 概述
+
+二进制协议和 API 与 Fory 的 xlang 模式类似，但 Python 原生模式可以序列化任何 Python 对象——包括全局函数、局部函数、lambda、局部类以及使用 `__getstate__/__reduce__/__reduce_ex__` 自定义序列化的类型，这些在 xlang 模式中是不允许的。
+
+要使用 Python 原生模式，创建 `Fory` 时设置 `xlang=False`：
+
+```python
+import pyfory
+fory = pyfory.Fory(xlang=False, ref=False, strict=True)
+```
+
+## 可直接替代 Pickle/Cloudpickle
+
+`pyfory` 可以使用以下配置序列化任何 Python 对象：
+
+- **对于循环引用**：设置 `ref=True` 启用引用跟踪
+- **对于函数/类**：设置 `strict=False` 允许反序列化动态类型
+
+**⚠️ 安全警告**：当 `strict=False` 时，Fory 将反序列化任意类型，如果数据来自不受信任的源，这可能带来安全风险。仅在完全信任数据源的受控环境中使用 `strict=False`。
+
+### 常见用法
+
+```python
+import pyfory
+
+# 创建 Fory 实例
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+# 序列化常见 Python 对象
+data = fory.dumps({"name": "Alice", "age": 30, "scores": [95, 87, 92]})
+print(fory.loads(data))
+
+# 序列化自定义对象
+from dataclasses import dataclass
+
+@dataclass
+class Person:
+ name: str
+ age: int
+
+person = Person("Bob", 25)
+data = fory.dumps(person)
+print(fory.loads(data)) # Person(name='Bob', age=25)
+```
+
+## 序列化全局函数
+
+捕获并序列化在模块级别定义的函数。Fory 反序列化并返回相同的函数对象：
+
+```python
+import pyfory
+
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+def my_global_function(x):
+ return 10 * x
+
+data = fory.dumps(my_global_function)
+print(fory.loads(data)(10)) # 100
+```
+
+## 序列化局部函数/Lambda
+
+序列化带闭包的函数和 lambda 表达式。Fory 自动捕获闭包变量：
+
+```python
+import pyfory
+
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+# 带闭包的局部函数
+def my_function():
+ local_var = 10
+ def local_func(x):
+ return x * local_var
+ return local_func
+
+data = fory.dumps(my_function())
+print(fory.loads(data)(10)) # 100
+
+# Lambda
+data = fory.dumps(lambda x: 10 * x)
+print(fory.loads(data)(10)) # 100
+```
+
+## 序列化全局类/方法
+
+序列化类对象、实例方法、类方法和静态方法：
+
+```python
+from dataclasses import dataclass
+import pyfory
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+@dataclass
+class Person:
+ name: str
+ age: int
+
+ def f(self, x):
+ return self.age * x
+
+ @classmethod
+ def g(cls, x):
+ return 10 * x
+
+ @staticmethod
+ def h(x):
+ return 10 * x
+
+# 序列化全局类
+print(fory.loads(fory.dumps(Person))("Bob", 25)) # Person(name='Bob', age=25)
+
+# 序列化实例方法
+print(fory.loads(fory.dumps(Person("Bob", 20).f))(10)) # 200
+
+# 序列化类方法
+print(fory.loads(fory.dumps(Person.g))(10)) # 100
+
+# 序列化静态方法
+print(fory.loads(fory.dumps(Person.h))(10)) # 100
+```
+
+## 序列化局部类/方法
+
+序列化在函数内定义的类及其方法：
+
+```python
+from dataclasses import dataclass
+import pyfory
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+def create_local_class():
+ class LocalClass:
+ def f(self, x):
+ return 10 * x
+
+ @classmethod
+ def g(cls, x):
+ return 10 * x
+
+ @staticmethod
+ def h(x):
+ return 10 * x
+ return LocalClass
+
+# 序列化局部类
+data = fory.dumps(create_local_class())
+print(fory.loads(data)().f(10)) # 100
+
+# 序列化局部类实例方法
+data = fory.dumps(create_local_class()().f)
+print(fory.loads(data)(10)) # 100
+
+# 序列化局部类方法
+data = fory.dumps(create_local_class().g)
+print(fory.loads(data)(10)) # 100
+
+# 序列化局部类静态方法
+data = fory.dumps(create_local_class().h)
+print(fory.loads(data)(10)) # 100
+```
+
+## 性能比较
+
+```python
+import pyfory
+import pickle
+import timeit
+
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+
+obj = {f"key{i}": f"value{i}" for i in range(10000)}
+print(f"Fory: {timeit.timeit(lambda: fory.dumps(obj), number=1000):.3f}s")
+print(f"Pickle: {timeit.timeit(lambda: pickle.dumps(obj), number=1000):.3f}s")
+```
+
+## 相关主题
+
+- [配置](configuration.md) - Python 模式配置
+- [带外序列化](out-of-band.md) - 零拷贝缓冲区
+- [安全性](security.md) - DeserializationPolicy
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/row-format.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/row-format.md
new file mode 100644
index 000000000..d6e415734
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/row-format.md
@@ -0,0 +1,169 @@
+---
+title: 行格式
+sidebar_position: 11
+id: python_row_format
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 提供随机访问行格式，可以在不完全反序列化的情况下从二进制数据中读取嵌套字段。
+
+## 概述
+
+当只需要部分数据访问时，行格式可以大幅减少处理大型对象的开销。它还支持内存映射文件，实现超低内存占用。
+
+**核心优势：**
+
+| 特性 | 描述 |
+| ------------ | ---------------------------------------- |
+| 零拷贝访问 | 无需反序列化整个对象即可读取嵌套字段 |
+| 内存效率 | 直接从磁盘内存映射大型数据集 |
+| 跨语言 | Python、Java、C++ 之间的二进制格式兼容 |
+| 部分反序列化 | 仅反序列化所需的特定元素 |
+| 高性能 | 跳过不必要的数据解析，适用于分析工作负载 |
+
+## 基础用法
+
+```python
+import pyfory
+import pyarrow as pa
+from dataclasses import dataclass
+from typing import List, Dict
+
+@dataclass
+class Bar:
+ f1: str
+ f2: List[pa.int64]
+
+@dataclass
+class Foo:
+ f1: pa.int32
+ f2: List[pa.int32]
+ f3: Dict[str, pa.int32]
+ f4: List[Bar]
+
+# 为行格式创建编码器
+encoder = pyfory.encoder(Foo)
+
+# 创建大型数据集
+foo = Foo(
+ f1=10,
+ f2=list(range(1_000_000)),
+ f3={f"k{i}": i for i in range(1_000_000)},
+ f4=[Bar(f1=f"s{i}", f2=list(range(10))) for i in range(1_000_000)]
+)
+
+# 编码为行格式
+binary: bytes = encoder.to_row(foo).to_bytes()
+
+# 零拷贝访问 - 无需完全反序列化！
+foo_row = pyfory.RowData(encoder.schema, binary)
+print(foo_row.f2[100000]) # 直接访问第 100,000 个元素
+print(foo_row.f4[100000].f1) # 直接访问嵌套字段
+print(foo_row.f4[200000].f2[5]) # 直接访问深层嵌套字段
+```
+
+## 跨语言兼容性
+
+行格式可以跨语言无缝工作。相同的二进制数据可以从 Java 和 C++ 访问。
+
+### Java
+
+```java
+public class Bar {
+ String f1;
+ List<Long> f2;
+}
+
+public class Foo {
+ int f1;
+ List<Integer> f2;
+ Map<String, Integer> f3;
+ List<Bar> f4;
+}
+
+RowEncoder<Foo> encoder = Encoders.bean(Foo.class);
+
+// 编码为行格式（与 Python 跨语言兼容）
+BinaryRow binaryRow = encoder.toRow(foo);
+
+// 零拷贝随机访问，无需完全反序列化
+BinaryArray f2Array = binaryRow.getArray(1); // 访问 f2 列表
+BinaryArray f4Array = binaryRow.getArray(3); // 访问 f4 列表
+BinaryRow bar10 = f4Array.getStruct(10); // 访问第 11 个 Bar
+long value = bar10.getArray(1).getInt64(5); // 访问 bar.f2 的第 6 个元素
+
+// 部分反序列化 - 仅反序列化所需内容
+RowEncoder<Bar> barEncoder = Encoders.bean(Bar.class);
+Bar bar1 = barEncoder.fromRow(f4Array.getStruct(10)); // 仅反序列化第 11 个 Bar
+Bar bar2 = barEncoder.fromRow(f4Array.getStruct(20)); // 仅反序列化第 21 个 Bar
+```
+
+### C++
+
+```cpp
+#include "fory/encoder/row_encoder.h"
+#include "fory/row/writer.h"
+
+struct Bar {
+ std::string f1;
+ std::vector<int64_t> f2;
+};
+
+FORY_FIELD_INFO(Bar, f1, f2);
+
+struct Foo {
+ int32_t f1;
+ std::vector<int32_t> f2;
+ std::map<std::string, int32_t> f3;
+ std::vector<Bar> f4;
+};
+
+FORY_FIELD_INFO(Foo, f1, f2, f3, f4);
+
+fory::encoder::RowEncoder<Foo> encoder;
+encoder.Encode(foo);
+auto row = encoder.GetWriter().ToRow();
+
+// 零拷贝随机访问，无需完全反序列化
+auto f2_array = row->GetArray(1); // 访问 f2 列表
+auto f4_array = row->GetArray(3); // 访问 f4 列表
+auto bar10 = f4_array->GetStruct(10); // 访问第 11 个 Bar
+int64_t value = bar10->GetArray(1)->GetInt64(5); // 访问 bar.f2 的第 6 个元素
+std::string str = bar10->GetString(0); // 访问 bar.f1
+```
+
+## 安装
+
+行格式需要 Apache Arrow：
+
+```bash
+pip install pyfory[format]
+```
+
+## 何时使用行格式
+
+- **分析工作负载**：当您只需要访问特定字段时
+- **大型数据集**：当完全反序列化成本太高时
+- **内存映射文件**：处理大于 RAM 的数据
+- **数据管道**：在不完全对象重建的情况下处理数据
+- **跨语言数据共享**：当数据需要从多种语言访问时
+
+## 相关主题
+
+- [跨语言序列化](cross-language.md) - XLANG 模式
+- [基础序列化](basic-serialization.md) - 对象序列化
+- [行格式规范](https://fory.apache.org/docs/specification/row_format_spec) - 协议详情
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/schema-evolution.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/schema-evolution.md
new file mode 100644
index 000000000..bd0c1d8c6
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/schema-evolution.md
@@ -0,0 +1,77 @@
+---
+title: Schema 演化
+sidebar_position: 6
+id: python_schema_evolution
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 在兼容模式下支持 schema 演化，允许在保持兼容性的同时添加/删除字段。
+
+## 启用兼容模式
+
+```python
+import pyfory
+
+f = pyfory.Fory(xlang=True, compatible=True)
+```
+
+## Schema 演化示例
+
+```python
+import pyfory
+from dataclasses import dataclass
+
+# 版本 1：原始类
+@dataclass
+class User:
+ name: str
+ age: int
+
+f = pyfory.Fory(xlang=True, compatible=True)
+f.register(User, typename="User")
+data = f.dumps(User("Alice", 30))
+
+# 版本 2：添加新字段（向后兼容）
+@dataclass
+class User:
+ name: str
+ age: int
+ email: str = "unknown@example.com" # 带默认值的新字段
+
+# 仍然可以反序列化旧数据
+user = f.loads(data)
+print(user.email) # "unknown@example.com"
+```
+
+## 支持的变更
+
+- **添加新字段**：带默认值
+- **删除字段**：具有额外字段的旧数据将被跳过
+- **重新排序字段**：字段按名称匹配，而不是位置
+
+## 最佳实践
+
+1. **始终为新字段提供默认值**
+2. **使用 typename 实现跨语言兼容性**
+3. **在部署前测试 schema 变更**
+4. **为团队记录 schema 版本**
+
+## 相关主题
+
+- [配置](configuration.md) - 兼容模式设置
+- [跨语言](cross-language.md) - 跨语言的 schema 演化
+- [类型注册](type-registration.md) - 注册模式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/security.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/security.md
new file mode 100644
index 000000000..faef4668b
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/security.md
@@ -0,0 +1,150 @@
+---
+title: 安全最佳实践
+sidebar_position: 9
+id: python_security
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍安全最佳实践和 DeserializationPolicy。
+
+## 生产环境配置
+
+除非环境完全可信，否则不要在生产环境中禁用 `strict=True`：
+
+```python
+import pyfory
+
+# 生产环境推荐设置
+f = pyfory.Fory(
+ xlang=False, # 如果需要跨语言支持则为 True
+ ref=True, # 处理循环引用
+ strict=True, # 重要：防止恶意数据
+ max_depth=100 # 防止深度递归攻击
+)
+
+# 显式注册允许的类型
+f.register(UserModel, type_id=100)
+f.register(OrderModel, type_id=101)
+# 永远不要在生产环境中对不受信任的数据设置 strict=False！
+```
+
+## 开发环境 vs 生产环境
+
+使用环境变量在配置之间切换：
+
+```python
+import pyfory
+import os
+
+# 开发环境配置
+if os.getenv('ENV') == 'development':
+ fory = pyfory.Fory(
+ xlang=False,
+ ref=True,
+ strict=False, # 开发时允许任何类型
+ max_depth=1000 # 开发时更高的限制
+ )
+else:
+ # 生产环境配置（安全加固）
+ fory = pyfory.Fory(
+ xlang=False,
+ ref=True,
+ strict=True, # 关键：需要注册
+ max_depth=100 # 合理的限制
+ )
+ # 只注册已知的安全类型
+ for idx, model_class in enumerate([UserModel, ProductModel, OrderModel]):
+ fory.register(model_class, type_id=100 + idx)
+```
+
+## DeserializationPolicy
+
+当需要 `strict=False` 时（例如，反序列化函数/lambda），使用 `DeserializationPolicy` 在反序列化期间实现细粒度的安全控制。
+
+**为什么使用 DeserializationPolicy？**
+
+- 阻止危险的类/模块（例如，`subprocess.Popen`）
+- 在调用前拦截和验证 `__reduce__` 可调用对象
+- 在 `__setstate__` 期间清理敏感数据
+- 根据自定义规则替换或拒绝反序列化的对象
+
+### 阻止危险类
+
+```python
+import pyfory
+from pyfory import DeserializationPolicy
+
+dangerous_modules = {'subprocess', 'os', '__builtin__'}
+
+class SafeDeserializationPolicy(DeserializationPolicy):
+ """在反序列化期间阻止潜在危险的类。"""
+
+ def validate_class(self, cls, is_local, **kwargs):
+ # 阻止危险模块
+ if cls.__module__ in dangerous_modules:
+ raise ValueError(f"已阻止危险类：{cls.__module__}.{cls.__name__}")
+ return None
+
+ def intercept_reduce_call(self, callable_obj, args, **kwargs):
+ # 在 __reduce__ 期间阻止特定的可调用对象调用
+ if getattr(callable_obj, '__name__', "") == 'Popen':
+ raise ValueError("已阻止尝试调用 subprocess.Popen")
+ return None
+
+ def intercept_setstate(self, obj, state, **kwargs):
+ # 清理敏感数据
+ if isinstance(state, dict) and 'password' in state:
+ state['password'] = '***REDACTED***'
+ return None
+
+# 使用自定义安全策略创建 Fory
+policy = SafeDeserializationPolicy()
+fory = pyfory.Fory(xlang=False, ref=True, strict=False, policy=policy)
+
+# 现在反序列化受到自定义策略的保护
+data = fory.serialize(my_object)
+result = fory.deserialize(data) # 将调用策略钩子
+```
+
+## 可用的策略钩子
+
+| 钩子 | 描述 |
+| -------------------------------------------- | ------------------------------------- |
+| `validate_class(cls, is_local)` | 在反序列化期间验证/阻止类类型 |
+| `validate_module(module, is_local)` | 验证/阻止模块导入 |
+| `validate_function(func, is_local)` | 验证/阻止函数引用 |
+| `intercept_reduce_call(callable_obj, args)` | 拦截 `__reduce__` 调用 |
+| `inspect_reduced_object(obj)` | 检查/替换通过 `__reduce__` 创建的对象 |
+| `intercept_setstate(obj, state)` | 在 `__setstate__` 之前清理状态 |
+| `authorize_instantiation(cls, args, kwargs)` | 控制类实例化 |
+
+**另请参阅：** `pyfory/policy.py` 包含每个钩子的详细文档和示例。
+
+## 最佳实践
+
+1. **生产环境始终使用 `strict=True`**
+2. **必要时使用 `DeserializationPolicy`** 当需要 `strict=False` 时
+3. **阻止危险模块**（subprocess、os 等）
+4. **设置适当的 `max_depth`** 以防止栈溢出
+5. **在反序列化前验证数据源**
+6. **记录安全事件** 用于审计
+
+## 相关主题
+
+- [类型注册](type-registration.md) - 注册和严格模式
+- [配置](configuration.md) - Fory 参数
+- [Python 原生模式](python-native.md) - 函数和 lambda
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/troubleshooting.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/troubleshooting.md
new file mode 100644
index 000000000..b3728c49f
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/troubleshooting.md
@@ -0,0 +1,186 @@
+---
+title: 故障排除
+sidebar_position: 13
+id: python_troubleshooting
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍常见问题及其解决方案。
+
+## 常见问题
+
+### 格式功能的 ImportError
+
+```python
+# 解决方案：安装行格式支持
+pip install pyfory[format]
+
+# 或从源码安装格式支持
+pip install -e ".[format]"
+```
+
+### 序列化性能慢
+
+```python
+# 检查是否启用了 Cython 加速
+import pyfory
+print(pyfory.ENABLE_FORY_CYTHON_SERIALIZATION) # 应该为 True
+
+# 如果为 False，Cython 扩展可能未正确编译
+# 重新安装：pip install --force-reinstall --no-cache-dir pyfory
+```
+
+### 跨语言兼容性问题
+
+```python
+# 使用一致的命名进行显式类型注册
+f = pyfory.Fory(xlang=True)
+f.register(MyClass, typename="com.package.MyClass") # 在所有语言中使用相同的名称
+```
+
+### 循环引用错误或重复数据
+
+```python
+# 启用引用跟踪
+f = pyfory.Fory(ref=True) # 循环引用所需
+
+# 循环引用示例
+class Node:
+ def __init__(self, value):
+ self.value = value
+ self.next = None
+
+node1 = Node(1)
+node2 = Node(2)
+node1.next = node2
+node2.next = node1 # 循环引用
+
+data = f.dumps(node1)
+result = f.loads(data)
+assert result.next.next is result # 循环引用被保留
+```
+
+### Schema 演化不工作
+
+```python
+# 启用兼容模式用于 schema 演化
+f = pyfory.Fory(xlang=True, compatible=True)
+
+# 版本 1：原始类
+@dataclass
+class User:
+ name: str
+ age: int
+
+f.register(User, typename="User")
+data = f.dumps(User("Alice", 30))
+
+# 版本 2：添加新字段（向后兼容）
+@dataclass
+class User:
+ name: str
+ age: int
+ email: str = "unknown@example.com" # 带默认值的新字段
+
+# 仍然可以反序列化旧数据
+user = f.loads(data)
+print(user.email) # "unknown@example.com"
+```
+
+### 严格模式下的类型注册错误
+
+```python
+# 在序列化之前注册所有自定义类型
+f = pyfory.Fory(strict=True)
+
+# 使用前必须注册
+f.register(MyClass, type_id=100)
+f.register(AnotherClass, type_id=101)
+
+# 或禁用严格模式（生产环境不推荐）
+f = pyfory.Fory(strict=False) # 仅在受信任的环境中使用
+```
+
+## 调试模式
+
+在导入 pyfory 之前设置环境变量以禁用 Cython 进行调试：
+
+```python
+import os
+os.environ['ENABLE_FORY_CYTHON_SERIALIZATION'] = '0'
+import pyfory # 现在使用纯 Python 实现
+
+# 这对以下情况很有用：
+# 1. 调试协议问题
+# 2. 理解序列化行为
+# 3. 无需重新编译 Cython 的开发
+```
+
+## 错误处理
+
+优雅地处理常见的序列化错误：
+
+```python
+import pyfory
+from pyfory.error import TypeUnregisteredError, TypeNotCompatibleError
+
+fory = pyfory.Fory(strict=True)
+
+try:
+ data = fory.dumps(my_object)
+except TypeUnregisteredError as e:
+ print(f"类型未注册：{e}")
+ # 注册类型并重试
+ fory.register(type(my_object), type_id=100)
+ data = fory.dumps(my_object)
+except Exception as e:
+ print(f"序列化失败：{e}")
+
+try:
+ obj = fory.loads(data)
+except TypeNotCompatibleError as e:
+ print(f"Schema 不匹配：{e}")
+ # 处理版本不匹配
+except Exception as e:
+ print(f"反序列化失败：{e}")
+```
+
+## 开发环境设置
+
+```bash
+git clone https://github.com/apache/fory.git
+cd fory/python
+
+# 安装依赖
+pip install -e ".[dev,format]"
+
+# 运行测试
+pytest -v -s .
+
+# 运行特定测试
+pytest -v -s pyfory/tests/test_serializer.py
+
+# 格式化代码
+ruff format .
+ruff check --fix .
+```
+
+## 相关主题
+
+- [配置](configuration.md) - Fory 参数
+- [类型注册](type-registration.md) - 注册最佳实践
+- [安全性](security.md) - 安全配置
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/type-registration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/type-registration.md
new file mode 100644
index 000000000..38704ffe5
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/python/type-registration.md
@@ -0,0 +1,146 @@
+---
+title: 类型注册与安全性
+sidebar_position: 3
+id: python_type_registration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页介绍类型注册机制和安全配置。
+
+## 类型注册
+
+在严格模式下，只有已注册的类型才能被反序列化。这可以防止任意代码执行：
+
+```python
+import pyfory
+
+# 严格模式（生产环境推荐）
+f = pyfory.Fory(strict=True)
+
+class SafeClass:
+ def __init__(self, data):
+ self.data = data
+
+# 在严格模式下必须注册类型
+f.register(SafeClass, typename="com.example.SafeClass")
+
+# 现在序列化可以正常工作
+obj = SafeClass("safe data")
+data = f.serialize(obj)
+result = f.deserialize(data)
+
+# 未注册的类型将引发异常
+class UnsafeClass:
+ pass
+
+# 在严格模式下这将失败
+try:
+ f.serialize(UnsafeClass())
+except Exception as e:
+ print("安全保护已激活！")
+```
+
+## 注册模式
+
+### 模式 1：简单注册
+
+```python
+fory.register(MyClass, type_id=100)
+```
+
+### 模式 2：使用类型名称的跨语言注册
+
+```python
+fory.register(MyClass, typename="com.example.MyClass")
+```
+
+### 模式 3：使用自定义序列化器
+
+```python
+fory.register(MyClass, type_id=100, serializer=MySerializer(fory, MyClass))
+```
+
+### 模式 4：批量注册
+
+```python
+type_id = 100
+for model_class in [User, Order, Product, Invoice]:
+ fory.register(model_class, type_id=type_id)
+ type_id += 1
+```
+
+## 安全模式
+
+### 严格模式（推荐）
+
+```python
+# 生产环境始终使用 strict=True
+fory = pyfory.Fory(strict=True)
+
+# 显式注册允许的类型
+fory.register(UserModel, type_id=100)
+fory.register(OrderModel, type_id=101)
+```
+
+### 非严格模式
+
+**⚠️ 安全警告**：当 `strict=False` 时，Fory 将反序列化任意类型，如果数据来自不受信任的源，这可能带来安全风险。仅在完全信任数据源的受控环境中使用 `strict=False`。
+
+```python
+# 仅在受信任的环境中
+fory = pyfory.Fory(xlang=False, ref=True, strict=False)
+```
+
+如果确实需要使用 `strict=False`，请配置 `DeserializationPolicy`：
+
+```python
+from pyfory import DeserializationPolicy
+
+class SafePolicy(DeserializationPolicy):
+ def validate_class(self, cls, is_local, **kwargs):
+ # 阻止危险模块
+ if cls.__module__ in {'subprocess', 'os', '__builtin__'}:
+ raise ValueError(f"已阻止：{cls}")
+ return None
+
+fory = pyfory.Fory(xlang=False, strict=False, policy=SafePolicy())
+```
+
+## 最大深度保护
+
+限制反序列化深度以防止栈溢出攻击：
+
+```python
+fory = pyfory.Fory(
+ strict=True,
+ max_depth=100 # 根据数据结构深度调整
+)
+```
+
+## 最佳实践
+
+1. **生产环境始终使用 `strict=True`**
+2. **使用 `type_id` 提高性能**，使用 `typename` 提高灵活性
+3. **在任何序列化之前预先注册所有类型**
+4. **根据数据结构设置适当的 `max_depth`**
+5. **必要时使用 `DeserializationPolicy`** 当需要 `strict=False` 时
+
+## 相关主题
+
+- [配置](configuration.md) - Fory 参数
+- [安全性](security.md) - DeserializationPolicy 详情
+- [自定义序列化器](custom-serializers.md) - 自定义序列化
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/_category_.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/_category_.json
new file mode 100644
index 000000000..845d58f46
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/_category_.json
@@ -0,0 +1,6 @@
+{
+ "label": "Rust",
+ "position": 2,
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/basic-serialization.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/basic-serialization.md
new file mode 100644
index 000000000..f35f7e0f0
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/basic-serialization.md
@@ -0,0 +1,166 @@
+---
+title: 基础序列化
+sidebar_position: 2
+id: rust_basic_serialization
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页涵盖基础对象图序列化和支持的类型。
+
+## 对象图序列化
+
+Apache Fory™ 提供复杂对象图的自动序列化，保留对象之间的结构和关系。`#[derive(ForyObject)]` 宏在编译时生成高效的序列化代码，消除运行时开销。
+
+**核心功能：**
+
+- 任意深度的嵌套结构体序列化
+- 集合类型（Vec、HashMap、HashSet、BTreeMap）
+- 使用 `Option<T>` 的可选字段
+- 原始类型和字符串的自动处理
+- 使用变长整数的高效二进制编码
+
+```rust
+use fory::{Fory, Error};
+use fory::ForyObject;
+use std::collections::HashMap;
+
+#[derive(ForyObject, Debug, PartialEq)]
+struct Person {
+ name: String,
+ age: i32,
+ address: Address,
+ hobbies: Vec<String>,
+ metadata: HashMap<String, String>,
+}
+
+#[derive(ForyObject, Debug, PartialEq)]
+struct Address {
+ street: String,
+ city: String,
+ country: String,
+}
+
+let mut fory = Fory::default();
+fory.register::<Address>(100);
+fory.register::<Person>(200);
+
+let person = Person {
+ name: "John Doe".to_string(),
+ age: 30,
+ address: Address {
+ street: "123 Main St".to_string(),
+ city: "New York".to_string(),
+ country: "USA".to_string(),
+ },
+ hobbies: vec!["reading".to_string(), "coding".to_string()],
+ metadata: HashMap::from([
+ ("role".to_string(), "developer".to_string()),
+ ]),
+};
+
+let bytes = fory.serialize(&person);
+let decoded: Person = fory.deserialize(&bytes)?;
+assert_eq!(person, decoded);
+```
+
+## 支持的类型
+
+### 原始类型
+
+| Rust 类型 | 描述 |
+| ------------------------- | ------------ |
+| `bool` | 布尔值 |
+| `i8`, `i16`, `i32`, `i64` | 有符号整数 |
+| `f32`, `f64` | 浮点数 |
+| `String` | UTF-8 字符串 |
+
+### 集合类型
+
+| Rust 类型 | 描述 |
+| ---------------- | -------- |
+| `Vec<T>` | 动态数组 |
+| `VecDeque<T>` | 双端队列 |
+| `LinkedList<T>` | 双向链表 |
+| `HashMap<K, V>` | 哈希映射 |
+| `BTreeMap<K, V>` | 有序映射 |
+| `HashSet<T>` | 哈希集合 |
+| `BTreeSet<T>` | 有序集合 |
+| `BinaryHeap<T>` | 二叉堆 |
+| `Option<T>` | 可选值 |
+
+### 智能指针
+
+| Rust 类型 | 描述 |
+| ------------ | -------------------------------------- |
+| `Box<T>` | 堆分配 |
+| `Rc<T>` | 引用计数（跟踪共享引用） |
+| `Arc<T>` | 线程安全引用计数（跟踪共享引用） |
+| `RcWeak<T>` | 指向 `Rc<T>` 的弱引用（打破循环引用） |
+| `ArcWeak<T>` | 指向 `Arc<T>` 的弱引用（打破循环引用） |
+| `RefCell<T>` | 内部可变性（运行时借用检查） |
+| `Mutex<T>` | 线程安全内部可变性 |
+
+### 日期和时间
+
+| Rust 类型 | 描述 |
+| ----------------------- | ---------------- |
+| `chrono::NaiveDate` | 不带时区的日期 |
+| `chrono::NaiveDateTime` | 不带时区的时间戳 |
+
+### 自定义类型
+
+| 宏 | 描述 |
+| ----------------------- | ------------ |
+| `#[derive(ForyObject)]` | 对象图序列化 |
+| `#[derive(ForyRow)]` | 行格式序列化 |
+
+## 序列化 API
+
+```rust
+use fory::{Fory, Reader};
+
+let mut fory = Fory::default();
+fory.register::<MyStruct>(1)?;
+
+let obj = MyStruct { /* ... */ };
+
+// 基础序列化/反序列化
+let bytes = fory.serialize(&obj)?;
+let decoded: MyStruct = fory.deserialize(&bytes)?;
+
+// 序列化到现有缓冲区
+let mut buf: Vec<u8> = vec![];
+fory.serialize_to(&mut buf, &obj)?;
+
+// 从 reader 反序列化
+let mut reader = Reader::new(&buf);
+let decoded: MyStruct = fory.deserialize_from(&mut reader)?;
+```
+
+## 性能优化建议
+
+- **零拷贝反序列化**：行格式支持直接内存访问而无需复制
+- **缓冲区预分配**：在序列化期间最小化内存分配
+- **紧凑编码**：变长编码以提高空间效率
+- **小端序**：为现代 CPU 架构优化
+- **引用去重**：共享对象仅序列化一次
+
+## 相关主题
+
+- [类型注册](type-registration.md) - 注册类型
+- [引用](references.md) - 共享引用和循环引用
+- [自定义序列化器](custom-serializers.md) - 手动序列化
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/configuration.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/configuration.md
new file mode 100644
index 000000000..6e2a99225
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/configuration.md
@@ -0,0 +1,125 @@
+---
+title: 配置
+sidebar_position: 1
+id: rust_configuration
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+本页涵盖 Fory 配置选项和序列化模式。
+
+## 序列化模式
+
+Apache Fory™ 支持两种序列化模式：
+
+### SchemaConsistent 模式（默认）
+
+类型声明必须在对等方之间完全匹配：
+
+```rust
+let fory = Fory::default(); // 默认为 SchemaConsistent
+```
+
+### Compatible 模式
+
+允许独立的 schema 演化：
+
+```rust
+let fory = Fory::default().compatible(true);
+```
+
+## 配置选项
+
+### 最大动态对象嵌套深度
+
+Apache Fory™ 提供针对反序列化期间深度嵌套动态对象导致的栈溢出保护。默认情况下，trait 对象和容器的最大嵌套深度设置为 5 层。
+
+**默认配置：**
+
+```rust
+let fory = Fory::default(); // max_dyn_depth = 5
+```
+
+**自定义深度限制：**
+
+```rust
+let fory = Fory::default().max_dyn_depth(10); // 允许最多 10 层
+```
+
+**何时调整：**
+
+- **增加**：用于合法的深度嵌套数据结构
+- **减少**：用于更严格的安全要求或浅层数据结构
+
+**受保护的类型：**
+
+- `Box<dyn Any>`、`Rc<dyn Any>`、`Arc<dyn Any>`
+- `Box<dyn Trait>`、`Rc<dyn Trait>`、`Arc<dyn Trait>`（trait 对象）
+- `RcWeak<T>`、`ArcWeak<T>`
+- 集合类型（Vec、HashMap、HashSet）
+- Compatible 模式下的嵌套结构体类型
+
+注意：静态数据类型（非动态类型）本质上是安全的，不受深度限制约束，因为它们的结构在编译时就已知。
+
+### 跨语言模式
+
+启用跨语言序列化：
+
+```rust
+let fory = Fory::default()
+ .compatible(true)
+ .xlang(true);
+```
+
+## 构建器模式
+
+```rust
+use fory::Fory;
+
+// 默认配置
+let fory = Fory::default();
+
+// 用于 schema 演化的兼容模式
+let fory = Fory::default().compatible(true);
+
+// 跨语言模式
+let fory = Fory::default()
+ .compatible(true)
+ .xlang(true);
+
+// 自定义深度限制
+let fory = Fory::default().max_dyn_depth(10);
+
+// 组合配置
+let fory = Fory::default()
+ .compatible(true)
+ .xlang(true)
+ .max_dyn_depth(10);
+```
+
+## 配置摘要
+
+| 选项 | 描述 | 默认值 |
+| -------------------- | ---------------------- | ------- |
+| `compatible(bool)` | 启用 schema 演化 | `false` |
+| `xlang(bool)` | 启用跨语言模式 | `false` |
+| `max_dyn_depth(u32)` | 动态类型的最大嵌套深度 | `5` |
+
+## 相关主题
+
+- [基础序列化](basic-serialization.md) - 使用已配置的 Fory
+- [Schema 演化](schema-evolution.md) - Compatible 模式详情
+- [跨语言](cross-language.md) - XLANG 模式
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/cross-language.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/cross-language.md
new file mode 100644
index 000000000..c114176d1
--- /dev/null
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.14/docs/guide/rust/cross-language.md
@@ -0,0 +1,165 @@
+---
+title: 跨语言序列化
+sidebar_position: 8
+id: rust_cross_language
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Apache Fory™ 支持在多种语言（包括 Java、Python、C++、Go 和 JavaScript）之间无缝进行数据交换。
+
+## 启用跨语言模式
+
+```rust
+use fory::Fory;
+
+// 启用跨语言模式
+let mut fory = Fory::default()
+ .compatible(true)
+ .xlang(true);
+
+// 使用跨语言一致的 ID 注册类型
+fory.register::<MyStruct>(100);
+
+// 或使用基于命名空间的注册
+fory.register_by_namespace::<MyStruct>("com.example", "MyStruct");
+```
+
+## 跨语言类型注册
+
+### 按 ID 注册
+
+对于使用跨语言一致 ID 的快速、紧凑序列化：
+
+```rust
+let mut fory = Fory::default()
+ .compatible(true)
+ .xlang(true);
+
+fory.register::<User>(100); // 在 Java、Python 等中使用相同的 ID
+```
+
+### 按命名空间注册
+
+对于更灵活的类型命名：
+
+```rust
+fory.register_by_namespace::<User>("com.example", "User");
+```
+
+## 跨语言示例
+
+### Rust（序列化器）
+
+```rust
+use fory::Fory;
+use fory::ForyObject;
+
+#[derive(ForyObject)]
+struct Person {
+ name: String,
+ age: i32,
+}
+
+let mut fory = Fory::default()
... 21068 lines suppressed ...
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org