docs: 整理文档

Author: Ryan-CW-Code

README.md

@@ -3,35 +3,35 @@
 >
 > 🎯 内存占用降低 **50%** | 🛡️ **100%** 模糊测试覆盖 | 🚀 **零递归**栈依赖
 
-📢 **使用中遇到问题，欢迎提交 Issue 或在 [RT-Thread 社区](https://club.rt-thread.org/index.html) 提问。** 
+📢 **使用中遇到问题，欢迎提交 Issue 或在 [RT-Thread 社区](https://club.rt-thread.org/index.html) 提问。**
 
 **快速入口：**`example/`、`./run_local_base.sh`、`AGENTS.md`
 
-### 1、介绍
+## 1、介绍
 
-#### ✅ 特性亮点
+RyanJson 面向 MCU、RTOS 等资源受限场景，重点优化节点内存布局、深层嵌套可用性，以及嵌入式语义下的可验证性。
 
-- 💡 **极致内存优化：** 通过动态内存扩展 + 紧凑布局，兼容未对齐访问，相较 cJSON 内存占用约降低 **50%**（详见 [内存占用对比报告](memoryUsageCompareQemu.md)）。
-- 💡 **适配 malloc 头部与对齐策略：** 通过配置匹配不同平台的分配器特性，平衡内联阈值与内存占用。
+### 特性亮点
+
+- 💡 **极致内存优化：** 通过动态内存扩展 + 紧凑布局，兼容未对齐访问，相较 cJSON 内存占用约降低 **50%**（详见 [内存占用对比报告](reports/memory/qemu.md)）。
 - 🧱 **零递归栈依赖：** 采用线索化链表 + 迭代 DFS，避免递归栈依赖，深层嵌套栈占用可控。
-- 🔍 **模糊测试护城河：** 基于 [LLVM LibFuzzer](https://llvm.org/docs/LibFuzzer.html) 进行上亿纪随机用例生成与回归，分支覆盖率100%。**[点击在线查看覆盖率信息](https://ryan-cw-code.github.io/RyanJson/)** 
-- 🧪 **单元测试矩阵与 QEMU 语义验证一体化：** 覆盖 double、重复 key、深层嵌套、链表稳定性等路径，并在 Cortex-M 语义下校验未对齐访问与 HardFault，核心语义宏组合覆盖。
+- 🔍 **模糊测试护城河：** 基于 [LLVM LibFuzzer](https://llvm.org/docs/LibFuzzer.html) 进行上亿级随机用例生成与回归，覆盖率信息可在线查看。**[点击在线查看覆盖率信息](https://ryan-cw-code.github.io/RyanJson/)**
+- 🧪 **单元测试矩阵与 QEMU 语义验证：** 覆盖 double、重复 key、深层嵌套、链表稳定性等路径，并在 Cortex-M 语义下校验未对齐访问与 HardFault。
 - 🛡️ **运行时安全分析验证：** 使用 **[Sanitizer](https://clang.llvm.org/docs/index.html#sanitizers)** 系列工具，捕获内存越界、Use-after-free、数据竞争、未定义行为、内存泄漏等问题，提升代码健壮性与安全性。
 - 📐 **高质量代码保障：** 引入 **[clang-tidy](https://clang.llvm.org/extra/clang-tidy/#clang-tidy)** 与 **[Cppcheck](https://cppcheck.sourceforge.io/)** 进行静态分析，目标是接近语法级“零缺陷”。
-- 🤖 **AI 辅助开发与审查：** 结合 **[Codex](https://openai.com/codex)**、**[Gemini Code Assist](https://codeassist.google/)**、**[coderabbitai](https://www.coderabbit.ai)**、**[Copilot](https://github.com/features/copilot)**，用于编码与代码审查，持续优化代码质量。
-- 👩‍💻 **开发者友好：** 类 cJSON 接口设计，迁移成本低
-- 📜 **严格但不严苛：** 默认配置通过 **[RFC 8259](https://github.com/nst/JSONTestSuite)** 测试集；支持深层嵌套（受限于内存与平台栈配置），支持注释与尾随逗号（可配置）
+- 🤖 **AI 辅助开发与审查：** 结合 **[Codex](https://openai.com/codex)**、**[coderabbitai](https://www.coderabbit.ai)**、**[Copilot](https://github.com/features/copilot)**，用于编码与代码审查，持续优化代码质量。
+- 📜 **严格但不严苛：** 默认配置通过 **[RFC 8259](https://github.com/nst/JSONTestSuite)** 测试集。
+- 👩‍💻 **开发者友好：** 类 cJSON 接口设计，迁移成本低。
 
-### 2、设计
+## 2、设计
 
-**设计参考与语法背景**
-- **借鉴：**[json](https://api.gitee.com/Lamdonn/json) 和 [cJSON](https://github.com/DaveGamble/cJSON)
-- **语法参考：**[JSON 规范](https://www.json.org/json-en.html)、[Parsing JSON is a Minefield](https://seriot.ch/projects/parsing_json.html)
+### 设计参考与语法背景
+- **借鉴：** [json](https://api.gitee.com/Lamdonn/json) 和 [cJSON](https://github.com/DaveGamble/cJSON)
+- **语法参考：** [JSON 规范](https://www.json.org/json-en.html)、[Parsing JSON is a Minefield](https://seriot.ch/projects/parsing_json.html)
 
 RyanJson 的核心竞争力在于对内存布局的精细控制，**结构体表示最小存储单元（键值对）**，通过单链表组织数据，结构如下：
 
 ```c
-
 // Json 最基础节点，所有 Json 元素都由该节点表示。
 // 结构体仅包含固定的 next 指针，用于单向链表串联。
 // 其余数据（如 flag/key/strValue/intValue/doubleValue/objValue 等）均通过动态内存分配管理。
@@ -143,7 +143,7 @@ struct RyanJsonNode
 typedef struct RyanJsonNode *RyanJson_t;
 ```
 
-#### ✅ 核心源码与模块入口
+### 核心源码与模块入口
 - `RyanJson/RyanJson.h`：公开 API 与节点结构体定义
 - `RyanJson/RyanJsonParse.c`：解析主流程与输入校验
 - `RyanJson/RyanJsonPrint.c`：序列化输出与格式化策略
@@ -154,7 +154,7 @@ typedef struct RyanJsonNode *RyanJson_t;
 - `run_local_*.sh`：本地脚本入口
 - `skills/shared/architecture.md`：架构与内部实现说明（AI 入口）
 
-#### ✅ 目录结构速查
+### 目录结构速查
 | 目录 | 说明 |
 | --- | --- |
 | `RyanJson/` | 核心库源码与头文件 |
@@ -166,13 +166,13 @@ typedef struct RyanJsonNode *RyanJson_t;
 | `build/` | 构建输出 |
 | `localLogs/` | 覆盖率与脚本日志输出 |
 
-### 3、测试与质量保障
+## 3、测试与质量保障
 
-**测试体系概览**
-- **组成：**单元测试矩阵 + 模糊测试 + QEMU 语义验证
-- **目标：**将稳定性验证前置到研发阶段
+### 测试体系概览
+- **组成：** 单元测试矩阵 + 模糊测试 + QEMU 语义验证
+- **目标：** 将稳定性验证前置到研发阶段
 
-#### ✅ 本地测试脚本
+### 本地测试脚本
 | 脚本                            | 用途               | 推荐场景                |
 | --- | --- | --- |
 | `./run_local_base.sh`           | 单元测试矩阵       | 修改测试用例后          |
@@ -182,7 +182,7 @@ typedef struct RyanJsonNode *RyanJson_t;
 | `./run_local_format.sh --check` | 格式检查           | 代码风格调整            |
 | `./run_local_skills.sh`         | skills 同步与校验  | 更新文档后 |
 
-#### 🧪 专项功能单元测试覆盖域
+### 专项功能单元测试覆盖域
 
 | 分组目录 | 说明 |
 | --- | --- |
@@ -196,12 +196,12 @@ typedef struct RyanJsonNode *RyanJson_t;
 | `utils` | 工具函数与辅助路径的正确性验证 |
 | `RFC8259` | RFC8259 标准样例与一致性检验 |
 
-#### 🛰️ QEMU 语义验证（嵌入式硬件语义）
+### QEMU 语义验证（嵌入式硬件语义）
 - 通过 QEMU 模拟 Cortex-M 语义路径，覆盖未对齐访问与 HardFault 处理等硬件级关键行为（`UNALIGN_TRP=1` 强制触发未对齐异常）。
 - 面向嵌入式场景的“语义级一致性”保障，不仅是“能跑通”，更是“语义正确”。
 - 脚本入口：`./run_local_qemu.sh`
 
-#### 🔍 **LLVM LibFuzzer 模糊测试**（核心亮点）
+### LLVM LibFuzzer 模糊测试
 
 LLVM LibFuzzer 模糊测试是 RyanJson 的 **稳定性护城河**，用于持续验证异常输入与极端边界。
 
@@ -224,7 +224,7 @@ LLVM LibFuzzer 模糊测试是 RyanJson 的 **稳定性护城河**，用于持
 | **随机压力复制安全测试**   | 覆盖大规模深拷贝的内存池利用效率与拓扑安全               |
 | **动态类型切换压力测试**   | 覆盖运行期类型切换与动态扩展的内存安全                   |
 
-#### 🛡️ 工具链集成
+### 工具链集成
 
 运行时、静态分析与格式化三位一体，形成持续质量防线。
 
@@ -234,99 +234,102 @@ LLVM LibFuzzer 模糊测试是 RyanJson 的 **稳定性护城河**，用于持
 | **[clang-tidy](https://clang.llvm.org/extra/clang-tidy/#clang-tidy)** | 静态分析潜在缺陷（空指针、资源泄漏等）                       |
 | **[Cppcheck](https://cppcheck.sourceforge.io/)**             | 深度扫描内存与资源问题                                       |
 | **[ClangFormat](https://clang.llvm.org/docs/ClangFormat.html)** | 统一代码风格                                                 |
-| AI 代码审查                                                  | **[Codex](https://openai.com/codex)**、**[Gemini Code Assist](https://codeassist.google/)**、**[coderabbitai](https://www.coderabbit.ai)**、**[Copilot](https://github.com/features/copilot)** 辅助优化逻辑，构建多层安全防线 |
+| AI 代码审查                                                  | **[Codex](https://openai.com/codex)**、**[coderabbitai](https://www.coderabbit.ai)**、**[Copilot](https://github.com/features/copilot)** 辅助优化逻辑，构建多层安全防线 |
 | **编译器警告**                                               | `-Wall -Wextra`（默认）、`-Weffc++`/`-Weverything`（Clang 可选，CI 强化时开启） |
 
-#### ✅ 当前主机侧单测基线（脚本默认）
+### 当前主机侧单测基线（脚本默认）
 - 默认构建目标：`RyanJson`
 - 默认工具链：`clang + linux x86`（当前主要验证环境，见 `xmake/host.lua`）
 - 默认启用：Sanitizer 与链接期安全硬化（见 `xmake/host.lua`）
 
-### 4、基准测试
+## 4、基准测试
 
 *测试与示例代码见本项目根目录 `test/` 和 `example/` 文件夹。*
 
-#### 性能测试
+### 性能测试
 **性能测试结果见 RyanDocs 文档中心（基于 [yyjson_benchmark](https://github.com/ibireme/yyjson_benchmark)，已过时，仅供参考）。**
 
-
-#### 内存占用测试
+### 内存占用测试
 RyanJson 支持按平台配置 `malloc` 头部空间与对齐粒度（见 `RyanJson/RyanJsonConfig.h`）
 
-- Host 报告：[memoryUsageCompareHost.md](memoryUsageCompareHost.md)
-- QEMU 报告：[memoryUsageCompareQemu.md](memoryUsageCompareQemu.md)
+- Host 报告：[reports/memory/host.md](reports/memory/host.md)
+- QEMU 报告：[reports/memory/qemu.md](reports/memory/qemu.md)
 
-生成方式：
-
-```
 测试用例代码：`test/unityTest/cases/performance/testMemory.c`
 
+生成方式：
+
+```bash
 bash run_local_memory.sh              			# 同时生成 host + qemu
 MEM_PLATFORM=host bash run_local_memory.sh   	# 仅主机侧
 MEM_PLATFORM=qemu bash run_local_memory.sh   	# 仅 QEMU
 ```
 
-#### [RFC 8259](https://github.com/nst/JSONTestSuite) 标准符合性测试
+### [RFC 8259](https://github.com/nst/JSONTestSuite) 标准符合性测试
 RFC8259 测试结果已独立输出为 Markdown 文档，避免 README 过长。
 
-- Host 报告：[rfc8259ReportHost.md](rfc8259ReportHost.md)
-- QEMU 报告：[rfc8259ReportQemu.md](rfc8259ReportQemu.md)
+- Host 报告：[reports/rfc8259/host.md](reports/rfc8259/host.md)
+- QEMU 报告：[reports/rfc8259/qemu.md](reports/rfc8259/qemu.md)
 
-生成方式：
+测试代码入口：`test/unityTest/cases/RFC8259/testRfc8259.c`
 
-```
-测试代码入口：`test/unityTest/cases/RFC8259/testRfc8259.c`。
+生成方式：
 
+```bash
 bash run_local_rfc8259.sh              			# 同时生成 host + qemu
 RFC_PLATFORM=host bash run_local_rfc8259.sh   	# 仅主机侧
 RFC_PLATFORM=qemu bash run_local_rfc8259.sh   	# 仅 QEMU
 ```
 
-### 5、使用限制与注意事项
+## 5、使用限制与注意事项
 
 - **数值精度**：内部使用 `int` / `double` 存储 Number。对于超过 double 精度的 64 位整数或高精度浮点数，内部使用 snprintf 打印；如果平台不支持科学计数法，建议使用 String 类型存储以避免精度丢失。
 - **重复 Key**：严格模式下解析阶段拒绝重复 key；非严格模式允许重复 key，`GetObjectByKey`/`DetachByKey` 命中首个重复项，`DeleteByKey` 每次删除一个，`Compare` 在非严格模式按同 key 的出现序号对齐比较。
 
-### 6、文档
-- 📂 示例代码：`example/` 文件夹
-- 📖 文档中心：RyanDocs
+## 6、文档与资料
+- 📂 示例代码：`example/` 文件夹，包含创建、解析、修改等基础示例
+- 🧭 架构说明：`skills/shared/architecture.md`，补充节点布局与内部实现说明
+- 📊 验证报告：`reports/memory/host.md`、`reports/memory/qemu.md`、`reports/rfc8259/host.md`、`reports/rfc8259/qemu.md`
+- 🌐 在线覆盖率：<https://ryan-cw-code.github.io/RyanJson/>
 - 📧 联系与支持：如有任何疑问或商业合作需求，请联系：`1831931681@qq.com`
 
-### 7、快速开始
+## 7、快速开始
 
-#### ✅ 编译工具链需要加入的文件
+### 编译工具链需要加入的文件
 - `RyanJson/*.c`（核心源码）
 - `RyanJson/RyanJson.h`（公开 API）
 - `RyanJson/RyanJsonConfig.h`（宏配置与平台差异）
 - 头文件搜索路径加入 `RyanJson/`
 
-#### ✅ 最小初始化要求
+### 最小初始化要求
 - 在任何 JSON API 前调用 `RyanJsonInitHooks(malloc, free, realloc)`
 - 业务代码包含 `#include "RyanJson.h"`
 - 如需调整宏（例如 `RyanJsonStrictObjectKeyCheck`），在包含头文件前定义或在 `RyanJsonConfig.h` 中配置
 
-#### ✅ 示例入口
+### 示例入口
 - 参考 `example/` 目录的最小示例
 
-### 8、AI 与知识库入口
+## 8、AI 与知识库入口
 - 使用方式：先阅读 `AGENTS.md`，按问题类型进入对应技能文档，即可快速获得可落地方案。
 - 提问建议：说明平台、宏前提、目标场景与是否需要代码示例，AI 会据此给出最短路径与稳妥的失败语义说明。
 - 总入口与路由：`AGENTS.md`
+- 项目导航、构建脚本与报告路径：`skills/ryanjson-project-guide/SKILL.md`
 - 架构与数据结构：`skills/shared/architecture.md`
 - API 使用与所有权：`skills/ryanjson-api-usage/SKILL.md`
 - 内部优化与语义边界：`skills/ryanjson-optimization/SKILL.md`
 - 单元测试工程：`skills/ryanjson-test-engineering/SKILL.md`
 
-### 9、贡献与验证
+## 9、贡献与验证
 
-#### ✅ xmake 构建快速开始（主机侧）
+### xmake 构建快速开始（主机侧）
 - xmake 官网：https://xmake.io
 - 默认验证环境：linux x86
 - `xmake f`
 - `xmake -b RyanJson`
 
-#### ✅ 场景与脚本建议
+### 场景与脚本建议
 按变更场景选脚本，确保修改可验证、可复现、可回归。
+
 | 变更场景 | 推荐脚本 |
 | --- | --- |
 | 仅修改单元测试用例 | `./run_local_base.sh` |

reports/memory/host.md

@@ -0,0 +1,48 @@
+# 内存占用对比（Host）
+
+更新时间：2026-03-16 14:44:57
+
+说明：
+- host 与 QEMU 结果可能不同：平台 ABI 与对齐规则差异会改变结构体布局与 padding。
+- 即使同为 32 位，x86(i386) 与 ARM EABI 的 double/uint64_t 对齐也可能不同。
+- 需要严格一致时，请以 QEMU 结果为准，或在同一 ABI/工具链下对比。
+
+### malloc 头部空间=12 字节，对齐=4 字节
+| 用例 | 文本长度 | RyanJson 内存 | cJSON 内存 | yyjson 内存 | 相比 cJSON 节省% | 相比 yyjson 节省% |
+| --- | --- | --- | --- | --- | --- | --- |
+| 混合对象 | 2265 | 7612 | 15444 | 8860 | **50.71%** | **14.09%** |
+| 经典天气对象 | 3991 | 11540 | 22172 | 13024 | **47.95%** | **11.39%** |
+| 深度数组 | 1205 | 6012 | 11540 | 5112 | **47.90%** | **-17.61%** |
+| 小型混合对象 | 90 | 256 | 540 | 692 | **52.59%** | **63.01%** |
+| 小型字符串对象 | 100 | 276 | 656 | 692 | **57.93%** | **60.12%** |
+| 压缩业务对象 | 551 | 2040 | 4952 | 3064 | **58.80%** | **33.42%** |
+
+### malloc 头部空间=8 字节，对齐=8 字节
+| 用例 | 文本长度 | RyanJson 内存 | cJSON 内存 | yyjson 内存 | 相比 cJSON 节省% | 相比 yyjson 节省% |
+| --- | --- | --- | --- | --- | --- | --- |
+| 混合对象 | 2265 | 7292 | 14948 | 8852 | **51.22%** | **17.62%** |
+| 经典天气对象 | 3991 | 11300 | 21068 | 13016 | **46.36%** | **13.18%** |
+| 深度数组 | 1205 | 5644 | 11284 | 5104 | **49.98%** | **-10.58%** |
+| 小型混合对象 | 90 | 252 | 520 | 676 | **51.54%** | **62.72%** |
+| 小型字符串对象 | 100 | 272 | 620 | 676 | **56.13%** | **59.76%** |
+| 压缩业务对象 | 551 | 2028 | 4872 | 3056 | **58.37%** | **33.64%** |
+
+### malloc 头部空间=8 字节，对齐=4 字节
+| 用例 | 文本长度 | RyanJson 内存 | cJSON 内存 | yyjson 内存 | 相比 cJSON 节省% | 相比 yyjson 节省% |
+| --- | --- | --- | --- | --- | --- | --- |
+| 混合对象 | 2265 | 6744 | 13920 | 8848 | **51.55%** | **23.78%** |
+| 经典天气对象 | 3991 | 10284 | 19680 | 13012 | **47.74%** | **20.97%** |
+| 深度数组 | 1205 | 5256 | 10512 | 5100 | **50.00%** | **-3.06%** |
+| 小型混合对象 | 90 | 228 | 484 | 672 | **52.89%** | **66.07%** |
+| 小型字符串对象 | 100 | 244 | 580 | 672 | **57.93%** | **63.69%** |
+| 压缩业务对象 | 551 | 1812 | 4328 | 3052 | **58.13%** | **40.63%** |
+
+### malloc 头部空间=4 字节，对齐=4 字节
+| 用例 | 文本长度 | RyanJson 内存 | cJSON 内存 | yyjson 内存 | 相比 cJSON 节省% | 相比 yyjson 节省% |
+| --- | --- | --- | --- | --- | --- | --- |
+| 混合对象 | 2265 | 5876 | 12396 | 8844 | **52.60%** | **33.56%** |
+| 经典天气对象 | 3991 | 9036 | 17384 | 13008 | **48.02%** | **30.54%** |
+| 深度数组 | 1205 | 4500 | 9484 | 5096 | **52.55%** | **11.70%** |
+| 小型混合对象 | 90 | 200 | 428 | 668 | **53.27%** | **70.06%** |
+| 小型字符串对象 | 100 | 212 | 508 | 668 | **58.27%** | **68.26%** |
+| 压缩业务对象 | 551 | 1584 | 4024 | 3048 | **60.64%** | **48.03%** |