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/tools/src/tools_plugin.cpp

@@ -1,6 +1,13 @@
-// plugin-tools: 工具注册服务插件
-// 提供 dstalk_tools_service_t vtable 实现
-// 依赖: file_io (内置 file_read / file_write 工具)
+/*
+ * @file tools_plugin.cpp
+ * @brief Tools plugin: tool registration, schema management, and execution registry.
+ * 工具插件：工具注册、schema 管理和执行注册表。
+ * Copyright (c) 2026 dstalk contributors. GPLv3.
+ */
+
+// plugin-tools: 工具注册服务插件 / Tool registration service plugin
+// 提供 dstalk_tools_service_t vtable 实现 / Provides dstalk_tools_service_t vtable implementation
+// 依赖: file_io (内置 file_read / file_write 工具) / Depends on: file_io (built-in file_read / file_write tools)
 #include "dstalk/dstalk_host.h"
 #include "dstalk/dstalk_types.h"
 #include "dstalk/dstalk_services.h"
@@ -20,21 +27,22 @@
 namespace json = boost::json;
 
 // ============================================================
-// 路径安全校验 (W14.3: 防止路径遍历攻击)
+// 路径安全校验 (W14.3: 防止路径遍历攻击) / Path safety validation (W14.3: prevent path traversal attacks)
 // ============================================================
 
+// 验证文件路径是否安全（无绝对路径、无 ".." 遍历、非空） / Validate that a file path is safe (no absolute paths, no ".." traversal, no empty).
 static bool is_safe_path(const std::string& path) {
-    // 拒绝空路径
+    // 拒绝空路径 / Reject empty path
     if (path.empty()) return false;
 
-    // 拒绝绝对路径: Unix '/' 开头 或 Windows 盘符 (第二字符 ':')
+    // 拒绝绝对路径: Unix '/' 开头 或 Windows 盘符 (第二字符 ':') / Reject absolute paths: Unix '/' prefix or Windows drive letter (second char ':')
     if (path[0] == '/' || path[0] == '\\') return false;
     if (path.size() >= 2 && path[1] == ':') return false;
 
-    // 拒绝含 ".." 段的目录遍历
+    // 拒绝含 ".." 段的目录遍历 / Reject directory traversal with ".." segments
     if (path.find("..") != std::string::npos) return false;
 
-    // lexical_normal 消解相对组件后再次校验
+    // lexical_normal 消解相对组件后再次校验 / Re-validate after resolving relative components with lexical_normal
     std::string norm = std::filesystem::path(path).lexically_normal().string();
     if (norm.empty()) return false;
     if (norm[0] == '/' || norm[0] == '\\') return false;
@@ -45,10 +53,10 @@ static bool is_safe_path(const std::string& path) {
 }
 
 // ============================================================
-// 内部数据结构
+// 内部数据结构 / Internal data structures
 // ============================================================
 
-// W14.3: g_host / g_file_io 使用 atomic 指针，写入 acquire/release，读取无锁
+// W14.3: g_host / g_file_io 使用 atomic 指针，写入 acquire/release，读取无锁 / g_host / g_file_io use atomic pointers, write with acquire/release, read lock-free
 static std::atomic<const dstalk_host_api_t*> g_host{nullptr};
 static std::atomic<const dstalk_file_io_service_t*> g_file_io{nullptr};
 
@@ -59,14 +67,15 @@ struct ToolDef {
     dstalk_tool_handler_fn handler;
 };
 
-// W14.3: g_tools 使用 mutex 保护读写
+// W14.3: g_tools 使用 mutex 保护读写 / g_tools uses mutex to protect read/write
 static std::vector<ToolDef> g_tools;
 static std::mutex g_tools_mutex;
 
 // ============================================================
-// 内置工具: file_read, file_write
+// 内置工具: file_read, file_write / Built-in tools: file_read, file_write
 // ============================================================
 
+// 内置工具处理器：读取文件并以 JSON 字符串返回内容 / Built-in tool handler: read a file and return its contents as a JSON string.
 static char* builtin_file_read(const char* args_json) {
     const dstalk_host_api_t* host = g_host.load(std::memory_order_acquire);
     const dstalk_file_io_service_t* fio = g_file_io.load(std::memory_order_acquire);
@@ -83,7 +92,7 @@ static char* builtin_file_read(const char* args_json) {
         }
         std::string path = json::value_to<std::string>(*path_j);
 
-        // W14.3: 路径遍历防护
+        // W14.3: 路径遍历防护 / Path traversal protection
         if (!is_safe_path(path)) {
             if (host) host->log(DSTALK_LOG_ERROR, "builtin_file_read: unsafe path rejected");
             return host ? host->strdup("{\"error\":\"access denied: unsafe path\"}") : nullptr;
@@ -110,6 +119,7 @@ static char* builtin_file_read(const char* args_json) {
     }
 }
 
+// 内置工具处理器：将内容写入文件，返回成功/错误 JSON 对象 / Built-in tool handler: write content to a file, returning a success/error JSON object.
 static char* builtin_file_write(const char* args_json) {
     const dstalk_host_api_t* host = g_host.load(std::memory_order_acquire);
     const dstalk_file_io_service_t* fio = g_file_io.load(std::memory_order_acquire);
@@ -132,7 +142,7 @@ static char* builtin_file_write(const char* args_json) {
         std::string path = json::value_to<std::string>(*path_j);
         std::string content = json::value_to<std::string>(*content_j);
 
-        // W14.3: 路径遍历防护
+        // W14.3: 路径遍历防护 / Path traversal protection
         if (!is_safe_path(path)) {
             if (host) host->log(DSTALK_LOG_ERROR, "builtin_file_write: unsafe path rejected");
             return host ? host->strdup("{\"error\":\"access denied: unsafe path\"}") : nullptr;
@@ -155,18 +165,19 @@ static char* builtin_file_write(const char* args_json) {
 }
 
 // ============================================================
-// Tools 服务 vtable 实现 (W14.3: try/catch + mutex)
+// Tools 服务 vtable 实现 (W14.3: try/catch + mutex) / Tools service vtable implementation (W14.3: try/catch + mutex)
 // ============================================================
 
 static void tools_unregister_tool(const char* name);
 
+// 注册命名工具及其描述、JSON Schema 参数和处理函数 / Register a named tool with its description, JSON Schema parameters, and handler function.
 static int tools_register_tool(const char* name, const char* desc,
                                const char* params_schema,
                                dstalk_tool_handler_fn handler) {
     try {
         if (!name || !handler) return -1;
 
-        // 如果已存在同名工具，先注销
+        // 如果已存在同名工具，先注销 / If a tool with the same name exists, unregister first
         tools_unregister_tool(name);
 
         ToolDef td;
@@ -189,6 +200,7 @@ static int tools_register_tool(const char* name, const char* desc,
     }
 }
 
+// 按名称注销之前注册的工具 / Unregister a previously registered tool by name.
 static void tools_unregister_tool(const char* name) {
     try {
         if (!name) return;
@@ -207,6 +219,7 @@ static void tools_unregister_tool(const char* name) {
     }
 }
 
+// 将所有已注册工具序列化为 OpenAI function-calling 格式的 JSON 数组 / Serialize all registered tools into a JSON array in OpenAI function-calling format.
 static char* tools_get_tools_json() {
     try {
         const dstalk_host_api_t* host = g_host.load(std::memory_order_acquire);
@@ -249,6 +262,7 @@ static char* tools_get_tools_json() {
     }
 }
 
+// 按名称查找工具并分派执行到注册的处理器 / Look up a tool by name and dispatch execution to its registered handler.
 static char* tools_execute(const char* name, const char* args_json) {
     try {
         const dstalk_host_api_t* host = g_host.load(std::memory_order_acquire);
@@ -298,14 +312,15 @@ static dstalk_tools_service_t g_tools_service = {
 };
 
 // ============================================================
-// 插件生命周期
+// 插件生命周期 / Plugin lifecycle
 // ============================================================
 
+// 插件初始化：查询 file_io 依赖，注册内置文件工具，注册 tools 服务 / Plugin init: query file_io dependency, register built-in file tools, register tools service.
 static int on_init(const dstalk_host_api_t* host) {
     try {
         g_host.store(host, std::memory_order_release);
 
-        // 查询依赖服务: file_io
+        // 查询依赖服务: file_io / Query dependency service: file_io
         void* raw = host->query_service("file_io", 1);
         if (!raw) {
             host->log(DSTALK_LOG_ERROR, "[plugin-tools] required service 'file_io' not found");
@@ -313,7 +328,7 @@ static int on_init(const dstalk_host_api_t* host) {
         }
         g_file_io.store(static_cast<const dstalk_file_io_service_t*>(raw), std::memory_order_release);
 
-        // 向自身注册内置工具
+        // 向自身注册内置工具 / Register built-in tools with self
         tools_register_tool(
             "file_read",
             "Read the contents of a file at the given path",
@@ -340,6 +355,7 @@ static int on_init(const dstalk_host_api_t* host) {
     }
 }
 
+// 插件关闭：清空所有已注册工具并清空服务指针 / Plugin shutdown: clear all registered tools and null out service pointers.
 static void on_shutdown() {
     try {
         std::lock_guard<std::mutex> lock(g_tools_mutex);
@@ -358,7 +374,7 @@ static void on_shutdown() {
 static dstalk_plugin_info_t g_info = {
     "tools",
     "1.0.0",
-    "Tool registration and execution plugin with built-in file tools",
+    "Tool registration and execution plugin with built-in file tools    / 内置文件工具的工具注册和执行插件",
     DSTALK_API_VERSION,
     {"file_io", nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr},
     on_init,
@@ -366,6 +382,7 @@ static dstalk_plugin_info_t g_info = {
     nullptr
 };
 
+// 必须入口点：返回插件描述符给主机 / 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;
 }