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.

plugins/file-io/src/file_io_plugin.cpp

@@ -1,3 +1,10 @@
+/*
+ * @file file_io_plugin.cpp
+ * @brief File I/O plugin: basic file read/write service.
+ * 文件 I/O 插件：基本文件读写服务。
+ * Copyright (c) 2026 dstalk contributors. GPLv3.
+ */
+
 #include "dstalk/dstalk_host.h"
 #include "dstalk/dstalk_services.h"
 
@@ -6,20 +13,21 @@
 #include <cstring>
 
 // ============================================================
-// Global state
+// 全局状态 / Global state
 // ============================================================
 static const dstalk_host_api_t* g_host = nullptr;
 
 // ============================================================
-// Service implementations
+// 服务实现 / Service implementations
 // ============================================================
+// 读取文件全部内容到主机分配的缓冲区，调用方须通过 host->free 释放 / Read the entire contents of a file into a host-allocated buffer. Caller must free via host->free.
 static int file_read(const char* path, char** content) {
     if (!path || !content) return -1;
 
     FILE* fp = fopen(path, "rb");
     if (!fp) return -1;
 
-    // Get file size
+    // 获取文件大小 / Get file size
     fseek(fp, 0, SEEK_END);
     long fsize = ftell(fp);
     fseek(fp, 0, SEEK_SET);
@@ -29,7 +37,7 @@ static int file_read(const char* path, char** content) {
         return -1;
     }
 
-    // Allocate buffer via host allocator (+1 for null terminator)
+    // 通过主机分配器分配缓冲区（+1 用于空终止符） / Allocate buffer via host allocator (+1 for null terminator)
     char* buf = (char*)g_host->alloc((size_t)fsize + 1);
     if (!buf) {
         fclose(fp);
@@ -49,6 +57,7 @@ static int file_read(const char* path, char** content) {
     return 0;
 }
 
+// 将字符串写入文件，覆盖已有内容 / Write a string to a file, overwriting any existing content.
 static int file_write(const char* path, const char* content) {
     if (!path || !content) return -1;
 
@@ -68,28 +77,31 @@ static dstalk_file_io_service_t g_service = {
 };
 
 // ============================================================
-// Plugin lifecycle
+// 插件生命周期 / Plugin lifecycle
 // ============================================================
+// 插件初始化：保存主机指针并注册 file_io 服务 / Plugin init: store host pointer and register the file_io service.
 static int on_init(const dstalk_host_api_t* host) {
     g_host = host;
     return host->register_service("file_io", 1, &g_service);
 }
 
+// 插件关闭：无需清理 / Plugin shutdown: nothing to clean up.
 static void on_shutdown() {
-    // nothing to clean up
+    // 无需清理 / nothing to clean up
 }
 
 static dstalk_plugin_info_t g_info = {
-    "file-io",             // name
-    "1.0.0",               // version
-    "Basic file I/O service",  // description
+    "file-io",             // name 名称
+    "1.0.0",               // version 版本
+    "Basic file I/O service",  // description 描述
     DSTALK_API_VERSION,    // api_version
-    {nullptr},             // dependencies (none)
+    {nullptr},             // dependencies 依赖 (none)
     on_init,               // on_init
     on_shutdown,           // on_shutdown
     nullptr                // on_event
 };
 
+// 必须入口点：返回插件描述符给主机 / Mandatory entry point: returns the plugin descriptor to the host.
 extern "C" DSTALK_PLUGIN_EXPORT dstalk_plugin_info_t* dstalk_plugin_init(void) {
     return &g_info;
 }