Merge pull request #2 from Awesome-Embedded-Learning-Studio/optimize/volume1_rewrite

Author: Charliechen114514

.env.example

@@ -0,0 +1,6 @@
+# Claude API 配置（用于 cppref_card_generator.py 和 translate.py）
+# 不要将此文件提交到 Git — 复制为 .env 并填入真实值
+
+ANTHROPIC_AUTH_TOKEN=your-anthropic-api-key-here
+ANTHROPIC_BASE_URL=https://api.anthropic.com
+ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-20250514

.github/workflows/build-examples.yml

@@ -0,0 +1,51 @@
+# Build Examples Workflow
+# Compiles all CMake projects under code/ to ensure code examples remain buildable
+
+name: Build Examples
+
+on:
+  pull_request:
+    paths:
+      - 'code/**'
+      - 'scripts/build_examples.py'
+      - '.github/workflows/build-examples.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'code/**'
+      - 'scripts/build_examples.py'
+
+jobs:
+  build-host:
+    name: Host Examples
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake g++ ninja-build
+
+      - name: Build host examples
+        run: python3 scripts/build_examples.py --host
+
+  build-stm32:
+    name: STM32 Examples
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake gcc-arm-none-eabi libnewlib-arm-none-eabi ninja-build
+
+      - name: Build STM32 examples
+        run: python3 scripts/build_examples.py --stm32

.github/workflows/content-quality.yml

@@ -0,0 +1,34 @@
+# Content Quality Workflow
+# Runs comprehensive quality checks on documentation Markdown files
+
+name: Content Quality
+
+on:
+  pull_request:
+    paths:
+      - 'documents/**/*.md'
+      - 'scripts/check_quality.py'
+  push:
+    branches: [main]
+    paths:
+      - 'documents/**/*.md'
+
+jobs:
+  quality-check:
+    name: Quality Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Run quality checks
+        run: python3 scripts/check_quality.py documents/

.github/workflows/deploy.yml

@@ -35,11 +35,11 @@ jobs:
       # 3. 安装依赖
       - name: 安装依赖
         run: pip install -e ./scripts
-      
+
       # 4. 构建网站
       - name: 构建网站
         run: mkdocs build --clean
-      
+
       # 5. 自动部署到 gh-pages 分支（这一步会自动触发 GitHub Pages）
       - name: 部署到 GitHub Pages
         uses: peaceiris/actions-gh-pages@v4

.gitignore

@@ -1,5 +1,6 @@
 # AI
 .claude
+CLAUDE.md
 
 # Build directories
 build/
@@ -36,3 +37,9 @@ __pycache__/
 
 # pip editable install artifacts
 *.egg-info/
+
+# cppreference crawler cache (contains API keys in env)
+scripts/cppref_cache/
+
+# Environment variables
+.env

.templates/reference-card-template.md

@@ -0,0 +1,67 @@
+---
+title: "特性名称"
+description: "一句话摘要"
+chapter: 99
+order: 0
+tags:
+  - host
+  - cpp-modern
+  - beginner
+difficulty: beginner
+cpp_standard: [11, 14, 17]
+---
+
+<!--
+参考卡模板 (Reference Card Template)
+用于 documents/cpp-reference/ 下的特性速查页。
+与 article-template.md 不同，参考卡走精炼的结构化格式，不需要叙事风格。
+
+标签使用规则：
+1. 必须包含 1 个 platform 标签（参考卡统一用 host）
+2. 必须包含 1 个 difficulty 标签
+3. 至少包含 1 个 topic 标签
+4. 从 scripts/validate_frontmatter.py 的 VALID_TAGS 集合中选取
+-->
+
+# 特性名称（C++XX）
+
+## 一句话
+
+用一句人话说清楚这是什么、解决什么问题。
+
+## 头文件
+
+`#include <...>`
+
+## 核心 API 速查
+
+| 操作 | 签名 | 说明 |
+|------|------|------|
+| ...  | `...` | ... |
+
+## 最小示例
+
+```cpp
+// 完整可编译的最小示例，不超过 20 行
+// Standard: C++XX
+```
+
+## 嵌入式适用性：高/中/低
+
+- 要点 1
+- 要点 2
+
+## 编译器支持
+
+| GCC | Clang | MSVC |
+|-----|-------|------|
+| X.Y | X.Y   | 19.X |
+
+## 另见
+
+- [教程：对应章节](相对路径)
+- [cppreference: 特性名](https://en.cppreference.com/w/cpp/...)
+
+---
+
+*部分内容参考自 [cppreference.com](https://en.cppreference.com/)，采用 [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) 许可*

code/examples/chapter05/01_dynamic_memory_problems/fragmentation_demo.cpp

@@ -53,7 +53,7 @@ void fragmentation_scenario_1() {
     std::vector<void*> allocations;
 
     // 分配不同大小的块
-    sizes_t sizes[] = {16, 32, 64, 128, 256, 512, 1024};
+    size_t sizes[] = {16, 32, 64, 128, 256, 512, 1024};
 
     for (int round = 0; round < 3; ++round) {
         for (size_t size : sizes) {

code/examples/chapter05/02_static_vs_stack_allocation/static_allocation_demo.cpp

@@ -11,7 +11,7 @@ int global_initialized = 100;
 int global_uninitialized;
 
 // 3. 只读常量 (.rodata段 - 通常在Flash中)
-static const uint16_t sine_table[16] = {
+static const int16_t sine_table[16] = {
     0,  6424,  11773,  15836,
     18479,  19595,  19151,  17205,
     13938,  9605,   4479,    0,
@@ -59,7 +59,7 @@ void constexpr_static_demo() {
 }
 
 // 演示静态存储用于查表
-uint16_t fast_sin(uint8_t angle) {
+int16_t fast_sin(uint8_t angle) {
     // 简化版：只演示查表访问
     return sine_table[angle % 16];
 }

code/examples/chapter05/03_object_pool_pattern/object_pool.cpp

@@ -1,6 +1,7 @@
 #include <iostream>
 #include <cstddef>
 #include <cstdint>
+#include <cstring>
 #include <new>
 #include <type_traits>
 #include <cassert>
@@ -117,7 +118,7 @@ class ObjectPool {
     size_t free_head_ = kInvalidIndex;
     size_t used_count_ = 0;
 
-    static size_t ptr_to_index(T* ptr) {
+    size_t ptr_to_index(T* ptr) {
         uintptr_t base = reinterpret_cast<uintptr_t>(&storage_[0]);
         uintptr_t p = reinterpret_cast<uintptr_t>(ptr);
         EP_ASSERT(p >= base);

code/examples/chapter05/04_placement_new/basic_placement_new.cpp

@@ -3,6 +3,7 @@
 #include <cstddef>
 #include <cstdint>
 #include <type_traits>
+#include <stdexcept>
 
 // 演示placement new的基础用法
 
@@ -157,40 +158,40 @@ void alignment_check_demo() {
         if (aligned) {
             int* p = new (ptr) int(42);
             std::cout << "    Successfully constructed int at " << p << "\n";
-            p->~int();
+            // No explicit destructor needed for trivial types
         }
     }
 }
 
 // 在栈上构造"动态"大小的对象
-void stack_vector_demo() {
-    std::cout << "\n=== Stack-Allocated \"Dynamic\" Container ===\n\n";
-
-    template<size_t N>
-    class StackVector {
-        alignas(double) unsigned char buffer_[N * sizeof(double)];
-        size_t size_ = 0;
-
-    public:
-        void push(double v) {
-            if (size_ < N) {
-                new (buffer_ + size_ * sizeof(double)) double(v);
-                ++size_;
-            }
+template<size_t N>
+class StackVector {
+    alignas(double) unsigned char buffer_[N * sizeof(double)];
+    size_t size_ = 0;
+
+public:
+    void push(double v) {
+        if (size_ < N) {
+            new (buffer_ + size_ * sizeof(double)) double(v);
+            ++size_;
         }
+    }
 
-        double& operator[](size_t i) {
-            return *reinterpret_cast<double*>(buffer_ + i * sizeof(double));
-        }
+    double& operator[](size_t i) {
+        return *reinterpret_cast<double*>(buffer_ + i * sizeof(double));
+    }
 
-        size_t size() const { return size_; }
+    size_t size() const { return size_; }
 
-        ~StackVector() {
-            for (size_t i = 0; i < size_; ++i) {
-                reinterpret_cast<double*>(buffer_ + i * sizeof(double))->~double();
-            }
+    ~StackVector() {
+        for (size_t i = 0; i < size_; ++i) {
+            reinterpret_cast<double*>(buffer_ + i * sizeof(double)); // trivial destructor, no-op
         }
-    };
+    }
+};
+
+void stack_vector_demo() {
+    std::cout << "\n=== Stack-Allocated \"Dynamic\" Container ===\n\n";
 
     StackVector<10> vec;
     for (int i = 0; i < 5; ++i) {