Add metadata validation script and module documentation

- Introduced a new Python script `check_agents_metadata.py` for validating agent metadata, including YAML parsing, rating ranges, and cross-references.
- Added usage instructions and exit codes for the script.
- Created a new markdown file `模块目录和功能说明.md` to outline the directory structure and functionality of the modules.
- Added a text file `说明此文件不可AI修改.txt` to specify that certain files should not be modified by AI, including important information about the `dstalk` framework and its modules.

tests/event_bus_test.cpp

@@ -1,8 +1,10 @@
-// ============================================================================
-// event_bus_test.cpp — EventBus 单元测试
-// ============================================================================
-// 测试: subscribe / unsubscribe / emit / 多订阅者 / 空总线
-// ============================================================================
+/*
+ * @file event_bus_test.cpp
+ * @brief EventBus unit tests: subscribe, emit, unsubscribe, multi-handler
+ *        dispatch order, independent event types.
+ * EventBus 单元测试：订阅、发布、取消订阅、多处理器分发顺序、独立事件类型。
+ * Copyright (c) 2026 dstalk contributors. GPLv3.
+ */
 
 #include <algorithm>
 #include <iostream>
@@ -13,6 +15,7 @@
 
 // ---- 轻量断言 ----
 static int g_failures = 0;
+// Lightweight assertion helper: increments g_failures counter on failure
 #define TCHECK(cond, msg) do {                            \
     if (cond) {                                           \
         std::cout << "[OK] " << (msg) << "\n";            \
@@ -22,13 +25,16 @@ static int g_failures = 0;
     }                                                     \
 } while (0)
 
-// ============================================================
+// EventBus 单元测试：订阅+发布、取消订阅、多处理器分发顺序、空总线、独立事件类型路由、取消不存在的订阅。
+// EventBus unit tests: subscribe+emit, unsubscribe, multi-handler dispatch order,
+// empty bus, independent event type routing, and non-existent unsubscribe safety.
 int main()
 {
     std::cout << "=== dstalk event_bus unit tests ===\n\n";
 
     // ====================================================================
     // Test 1: subscribe + emit — 基本发布订阅流程
+    // Test 1: subscribe + emit — basic pub/sub flow
     // ====================================================================
     {
         dstalk::EventBus bus;
@@ -49,6 +55,7 @@ int main()
 
     // ====================================================================
     // Test 2: unsubscribe — 取消订阅后 handler 不再被调用
+    // Test 2: unsubscribe — handler NOT called after unsubscription
     // ====================================================================
     {
         dstalk::EventBus bus;
@@ -64,6 +71,7 @@ int main()
 
     // ====================================================================
     // Test 3: 多订阅者 — 同一事件多个 handler 按订阅顺序全部调用
+    // Test 3: multi-subscriber — all handlers for same event invoked in subscription order
     // ====================================================================
     {
         dstalk::EventBus bus;
@@ -77,13 +85,14 @@ int main()
         TCHECK(emitted == 3, "emit returns 3 handlers called");
         TCHECK(order.size() == 3, "all 3 handlers invoked");
 
-        // 验证订阅顺序 (FIFO: 按 subscribe 顺序触发)
+        // 验证订阅顺序 (FIFO: 按 subscribe 顺序触发) / Verify subscription order (FIFO: in subscribe order)
         bool ordered = (order[0] == 1 && order[1] == 2 && order[2] == 3);
         TCHECK(ordered, "handlers invoked in subscription order (1,2,3)");
     }
 
     // ====================================================================
     // Test 4: 空总线 emit 不崩溃，返回 0
+    // Test 4: emit on empty bus no crash, returns 0
     // ====================================================================
     {
         dstalk::EventBus bus;
@@ -93,6 +102,7 @@ int main()
 
     // ====================================================================
     // Test 5: 不同 event_type 独立分发 — 只触发匹配的 handler
+    // Test 5: independent event_type dispatch — only matching handler triggered
     // ====================================================================
     {
         dstalk::EventBus bus;
@@ -112,15 +122,16 @@ int main()
 
     // ====================================================================
     // Test 6: 退订不存在的 ID 不崩溃
+    // Test 6: unsubscribe non-existent ID does not crash
     // ====================================================================
     {
         dstalk::EventBus bus;
-        bus.unsubscribe(99999);  // 不存在的 ID
+        bus.unsubscribe(99999);  // 不存在的 ID / non-existent ID
         std::cout << "[OK] unsubscribe non-existent ID (99999) did not crash\n";
     }
 
     // ====================================================================
-    // 结果
+    // 结果 / Result
     // ====================================================================
     std::cout << "\n";
     if (g_failures == 0) {