diff --git a/docs/父类字段序列化方案.md b/docs/父类字段序列化方案.md
index 39fdd37..46a490e 100644
--- a/docs/父类字段序列化方案.md
+++ b/docs/父类字段序列化方案.md
@@ -171,7 +171,7 @@ soulsoft 的 API 带泛型约束 `where T <: ISerializable`，不标宏的类在
 ### 3.1 宏定义
 
 ```cangjie
-// 文件：src/json/SerializerParentMacro.cj
+// 文件：src/macros/SerializerParentMacro.cj
 // 包：simapi_serialization.json（宏包需单独编译，见 3.3）
 
 macro package simapi_serialization.json
@@ -535,7 +535,7 @@ main() {
 
 ## 9. 实施步骤（评审通过后）
 
-1. 新建宏文件 `src/json/SerializerParentMacro.cj`（或独立宏包），实现 `SerializerParent` 宏；
+1. 新建宏文件 `src/macros/SerializerParentMacro.cj`（或独立宏包），实现 `SerializerParent` 宏；
 2. 验证 cjpm 对宏包的编译流程（风险 #1），必要时调整项目结构；
 3. 改 `JsonWriter.writeObject`：superClass 链调用 `exportJsonFields`；
 4. 改 `JsonReader.readObject`：superClass 链调用 `importJsonFields`；
diff --git a/src/json/JsonAnnotations.cj b/src/Annotations.cj
similarity index 68%
rename from src/json/JsonAnnotations.cj
rename to src/Annotations.cj
index fe689bc..c1d687f 100644
--- a/src/json/JsonAnnotations.cj
+++ b/src/Annotations.cj
@@ -1,8 +1,8 @@
 /*
  * Copyright (c) 2025 SimcuTeam. All rights reserved.
- * 对齐 .NET System.Text.Json.Serialization 特性：
- *   - [SerializerPropertyName("xxx")]  → @SerializerPropertyName["xxx"]  指定字段的 JSON 名称
- *   - [SerializerIgnore]               → @SerializerIgnore               序列化/反序列化时忽略该字段
+ * 序列化注解（对齐 .NET System.Text.Json.Serialization 特性）：
+ *   - [JsonPropertyName("xxx")]  → @SerializerPropertyName["xxx"]  指定字段的序列化名称
+ *   - [JsonIgnore]               → @SerializerIgnore               序列化/反序列化时忽略该字段
  *
  * 设计决策：本库序列化/反序列化只处理「var 成员变量」（std.reflect 的 instanceVariables），
  * 不处理 prop 属性（instanceProperties）。因此注解 target 仅限 MemberVariable：
@@ -12,10 +12,10 @@
  * https://docs.cangjie-lang.cn/en/docs/1.0.0/libs/std/reflect/reflect_samples/annotation.html
  */
 
-package simapi_serialization.json
+package simapi_serialization
 
 /**
- * 指定字段的 JSON 名称（对齐 .NET SerializerPropertyNameAttribute）。
+ * 指定字段的序列化名称（对齐 .NET JsonPropertyNameAttribute）。
  * 用法：@SerializerPropertyName["user_name"] public var _username: String = ""
  */
 @Annotation[target: [MemberVariable]]
@@ -28,7 +28,7 @@ public class SerializerPropertyName {
 }
 
 /**
- * 标记字段不做 JSON 处理（对齐 .NET SerializerIgnoreAttribute）。
+ * 标记字段不做序列化处理（对齐 .NET JsonIgnoreAttribute）。
  * 用法：@SerializerIgnore public var _temp: String = ""
  */
 @Annotation[target: [MemberVariable]]
diff --git a/src/SimApiSerialization.cj b/src/SimApiSerialization.cj
index d523683..df1763d 100644
--- a/src/SimApiSerialization.cj
+++ b/src/SimApiSerialization.cj
@@ -1,12 +1,12 @@
 /*
  * Copyright (c) 2025 SimcuTeam. All rights reserved.
  *
- * simapi_serialization 根包锚点（cjpm 要求 src 根目录至少有一个 .cj 文件，否则不扫描子目录）。
- * 全部实现位于子包 simapi_serialization.json（对应 .NET System.Text.Json）。
- * 通过 public import 重导出：`import simapi_serialization.*` 仍可直接使用
- * JsonSerializer / JsonOption / @SerializerPropertyName / @SerializerIgnore 等。
+ * simapi_serialization 根包锚点：注解类（@SerializerPropertyName / @SerializerIgnore）同包于此。
+ * 序列化器位于子包 simapi_serialization.json（对应 .NET System.Text.Json）。
+ *
+ * 用法：
+ *   import simapi_serialization.*         // 注解
+ *   import simapi_serialization.json.*    // JsonSerializer / JsonOption
  */
 
 package simapi_serialization
-
-public import simapi_serialization.json.*
diff --git a/src/json/JsonSerializer_test.cj b/src/json/JsonSerializer_test.cj
index e39ad95..bcecd50 100644
--- a/src/json/JsonSerializer_test.cj
+++ b/src/json/JsonSerializer_test.cj
@@ -13,6 +13,7 @@ package simapi_serialization.json
 import std.collection.*
 import std.unittest.*
 import std.unittest.testmacro.*
+import simapi_serialization.*
 import simapi_serialization.macros.*
 
 enum Role {
diff --git a/src/json/ReflectionCache.cj b/src/json/ReflectionCache.cj
index 4ccc154..6b57550 100644
--- a/src/json/ReflectionCache.cj
+++ b/src/json/ReflectionCache.cj
@@ -11,6 +11,7 @@ package simapi_serialization.json
 
 import std.collection.*
 import std.reflect.*
+import simapi_serialization.*
 
 /**
  * 单个字段的序列化元数据。