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.

dstalk-core/include/dstalk/dstalk_host.h

@@ -1,3 +1,10 @@
+/**
+ * @file dstalk_host.h
+ * @brief Host API declarations: plugin lifecycle, service registry, event bus, config, logging, memory.
+ * 主机 API 声明：插件生命周期、服务注册表、事件总线、配置、日志、内存管理。
+ * Copyright (c) 2026 dstalk contributors. GPLv3.
+ */
+
 #ifndef DSTALK_HOST_H
 #define DSTALK_HOST_H
 
@@ -8,7 +15,7 @@
 extern "C" {
 #endif
 
-// === 平台导出宏 ===
+/* ---- 平台导出宏 / Platform export macros ---- */
 #ifndef DSTALK_API
 #if defined(_WIN32)
   #ifdef DSTALK_BUILD_DLL
@@ -21,21 +28,23 @@ extern "C" {
 #endif
 #endif
 
-// === 插件导出宏 ===
+/* ---- 插件导出宏 / Plugin export macro ---- */
 #if defined(_WIN32)
   #define DSTALK_PLUGIN_EXPORT __declspec(dllexport)
 #else
   #define DSTALK_PLUGIN_EXPORT __attribute__((visibility("default")))
 #endif
 
-// === API 版本 ===
-#define DSTALK_API_VERSION 1
-#define DSTALK_MAX_DEPS 8
+/* ---- API 版本常量 / API version constants ---- */
+#define DSTALK_API_VERSION 1       // 当前主机 API 版本，插件必须匹配 / current host API version plugins must match
+#define DSTALK_MAX_DEPS 8          // 插件可声明的最大依赖项数量 / maximum dependency entries a plugin can declare
 
-// === 诊断 ===
+/* ---- 诊断回调 / Diagnostics callback ---- */
+/* 主机调用此回调用于断言失败和内部诊断 / Called by the host for assertion failures and internal diagnostics */
 typedef void (*dstalk_diag_cb)(int severity, const char* file,
     int line, const char* func, const char* message);
 
+/* 断言宏: 当 expr 为假时记录错误并返回 retval / Assertion macro: logs error and returns retval if expr is false */
 #define DSTALK_ERROR_RETURN(expr, retval)  do { \
     if (!(expr)) { \
         dstalk_log(DSTALK_LOG_ERROR, "[%s:%d] %s: assertion '%s' failed", \
@@ -44,85 +53,107 @@ typedef void (*dstalk_diag_cb)(int severity, const char* file,
     } \
 } while(0)
 
+/* 注册诊断回调用于内部错误报告 / Register a diagnostic callback for internal error reporting */
 DSTALK_API void dstalk_set_diag_callback(dstalk_diag_cb cb);
 
-// === 事件处理器 ===
+/* ---- 事件处理器类型 / Event handler type ---- */
+/* 当已订阅的事件被触发时由主机调用 / Called by the host when a subscribed event is emitted */
 typedef void (*dstalk_event_handler_fn)(int event_type, const void* data, void* userdata);
 
-// === Host 提供给插件的 API 表 ===
+/* ---- 主机 API vtable (传递给插件的 on_init) / Host API vtable (passed to plugin's on_init) ---- */
 typedef struct {
-    // 服务注册/查询
+    /* --- 服务注册表 / service registry --- */
     int  (*register_service)(const char* name, int version, void* vtable);
     void*(*query_service)(const char* name, int min_version);
 
-    // 事件
+    /* --- 事件总线 / event bus --- */
     int  (*event_subscribe)(int event_type, dstalk_event_handler_fn handler, void* userdata);
     int  (*event_emit)(int event_type, const void* data);
     void (*event_unsubscribe)(int sub_id);
 
-    // 配置
+    /* --- 配置管理 / configuration --- */
     const char* (*config_get)(const char* key);
     int (*config_set)(const char* key, const char* value);
 
-    // 日志
+    /* --- 日志记录 / logging --- */
     void (*log)(int level, const char* fmt, ...);
 
-    // 内存
+    /* --- 内存管理 / memory management --- */
     void* (*alloc)(size_t size);
     void  (*free)(void* ptr);
     char* (*strdup)(const char* s);
 } dstalk_host_api_t;
 
-// === 插件信息结构 ===
+/* ---- 插件描述符 / Plugin descriptor ---- */
+/* 每个插件通过 dstalk_plugin_init() 导出此结构体 / Every plugin exports this via dstalk_plugin_init() */
 typedef struct {
-    const char* name;                    // 插件名称（唯一标识）
-    const char* version;                 // 语义化版本号，如 "1.0.0"
-    const char* description;             // 描述
-    int api_version;                     // 必须 == DSTALK_API_VERSION
+    const char* name;                    // 唯一插件标识符 / unique plugin identifier
+    const char* version;                 // 语义版本号，如 "1.0.0" / semantic version, e.g. "1.0.0"
+    const char* description;             // 人类可读的描述信息 / human-readable description
+    int api_version;                     // 必须等于 DSTALK_API_VERSION / must equal DSTALK_API_VERSION
 
-    // 依赖声明（以 NULL 结尾）
+    /* null-terminated 依赖插件名称列表 / null-terminated list of dependency plugin names */
     const char* dependencies[DSTALK_MAX_DEPS];
 
-    // 生命周期回调
+    /* 生命周期回调 / lifecycle callbacks */
     int  (*on_init)(const dstalk_host_api_t* host);
     void (*on_shutdown)(void);
 
-    // 事件处理（可选）
+    /* 可选: 事件总线上每个事件通过时调用 / optional: called for every event passing through the bus */
     void (*on_event)(int event_type, const void* data);
 } dstalk_plugin_info_t;
 
-// === 插件入口函数 ===
+/* ---- 插件入口点 / Plugin entry point ---- */
+/* 每个共享库插件必须导出一个与此签名匹配的函数 / Every shared library plugin must export a function with this signature */
 typedef dstalk_plugin_info_t* (*dstalk_plugin_init_fn)(void);
 
-// === Host 公共 API ===
+/* ========================================================================
+ * 主机公共 API / Host public API
+ * ======================================================================== */
 
-// 初始化/销毁
+/* 使用给定的配置文件路径初始化 dstalk 主机 / Initialize the dstalk host with the given config file path */
 DSTALK_API int  dstalk_init(const char* config_path);
+
+/* 关闭主机: 卸载插件, 释放资源 / Shut down the host: unload plugins, free resources */
 DSTALK_API void dstalk_shutdown(void);
 
-// 插件管理
+/* 从共享库路径加载插件; 返回 plugin_id, 出错返回 -1 / Load a plugin from a shared library path; returns plugin_id or -1 on error */
 DSTALK_API int  dstalk_plugin_load(const char* path);
+
+/* 按 id 卸载之前加载的插件 / Unload a previously loaded plugin by its id */
 DSTALK_API int  dstalk_plugin_unload(int plugin_id);
+
+/* 将已加载插件信息的 JSON 数组写入 *output_json (调用方释放) / Write a JSON array of loaded plugin info to *output_json (caller frees) */
 DSTALK_API int  dstalk_plugin_list(char** output_json);
 
-// 服务查询
+/* 按名称和最低版本号查找已注册的服务 vtable / Look up a registered service vtable by name and minimum version */
 DSTALK_API void* dstalk_service_query(const char* service_name, int min_version);
 
-// 事件系统
+/* 为特定事件类型订阅处理器; 返回 subscription_id / Subscribe handler to a specific event type; returns subscription_id */
 DSTALK_API int  dstalk_event_subscribe(int event_type, dstalk_event_handler_fn handler, void* userdata);
+
+/* 向所有已订阅该类型事件的订阅者发送事件 / Emit an event to all subscribers of the given type */
 DSTALK_API int  dstalk_event_emit(int event_type, const void* data);
+
+/* 按 id 移除订阅 / Remove a subscription by its id */
 DSTALK_API void dstalk_event_unsubscribe(int subscription_id);
 
-// 配置
+/* 通过键名获取配置值 (未找到返回 NULL) / Retrieve a config value by key (returns NULL if not found) */
 DSTALK_API const char* dstalk_config_get(const char* key);
+
+/* 设置配置键值对; 成功返回 0 / Set a config key/value pair; returns 0 on success */
 DSTALK_API int  dstalk_config_set(const char* key, const char* value);
 
-// 日志
+/* 以给定严重等级记录日志消息 / Log a message at the given severity level */
 DSTALK_API void dstalk_log(int level, const char* fmt, ...);
 
-// 内存
+/* 使用主机的内存分配器分配内存 / Allocate memory using the host's allocator */
 DSTALK_API void* dstalk_alloc(size_t size);
+
+/* 释放之前由主机分配的内存 / Free memory previously allocated by the host */
 DSTALK_API void  dstalk_free(void* ptr);
+
+/* 使用主机的内存分配器复制 C 字符串 / Duplicate a C-string using the host's allocator */
 DSTALK_API char* dstalk_strdup(const char* s);
 
 #ifdef __cplusplus

dstalk-core/include/dstalk/dstalk_lsp.h

@@ -1,3 +1,10 @@
+/**
+ * @file dstalk_lsp.h
+ * @brief Convenience C API for Language Server Protocol operations (delegates to "lsp" plugin).
+ * LSP（语言服务器协议）操作的便捷 C API（委托给 "lsp" 插件）。
+ * Copyright (c) 2026 dstalk contributors. GPLv3.
+ */
+
 #ifndef DSTALK_LSP_H
 #define DSTALK_LSP_H
 
@@ -7,51 +14,51 @@
 extern "C" {
 #endif
 
-/* ---- LSP 服务器生命周期 ---- */
+/* ---- LSP 服务器生命周期 / LSP Server Lifecycle ---- */
 
 /*
- * 启动语言服务器进程
- *   server_cmd: 命令字符串，例如 "clangd" 或 "pyright --stdio" 或完整路径
- *   language:   语言标识，例如 "c", "cpp", "python", "javascript", "rust"
- *   returns: 0 成功, -1 失败
+ * 启动语言服务器进程 / Start the language server process
+ *   server_cmd: 命令字符串，例如 "clangd" 或 "pyright --stdio" 或完整路径 / command string, e.g. "clangd" or "pyright --stdio" or full path
+ *   language:   语言标识，例如 "c", "cpp", "python", "javascript", "rust" / language identifier, e.g. "c", "cpp", "python", "javascript", "rust"
+ *   returns: 0 成功, -1 失败 / 0 success, -1 failure
  */
 DSTALK_API int  dstalk_lsp_start(const char* server_cmd, const char* language);
 
 /*
- * 停止语言服务器
- *   发送 shutdown 请求，然后发送 exit 通知
- *   关闭管道，终止子进程
+ * 停止语言服务器 / Stop the language server
+ *   发送 shutdown 请求，然后发送 exit 通知 / sends shutdown request, then exit notification
+ *   关闭管道，终止子进程 / closes pipes, terminates child process
  */
 DSTALK_API void dstalk_lsp_stop(void);
 
-/* ---- 文档管理 ---- */
+/* ---- 文档管理 / Document Management ---- */
 
 /*
- * 在语言服务器中打开一个文档
- *   uri:         文件 URI，例如 "file:///path/to/file.c"
- *   content:     文件内容文本
- *   language_id: 语言 ID，例如 "c", "cpp", "python", "javascript"
- *   returns: 0 成功, -1 失败
+ * 在语言服务器中打开一个文档 / Open a document in the language server
+ *   uri:         文件 URI，例如 "file:///path/to/file.c" / file URI, e.g. "file:///path/to/file.c"
+ *   content:     文件内容文本 / file content text
+ *   language_id: 语言 ID，例如 "c", "cpp", "python", "javascript" / language ID, e.g. "c", "cpp", "python", "javascript"
+ *   returns: 0 成功, -1 失败 / 0 success, -1 failure
  */
 DSTALK_API int  dstalk_lsp_open(const char* uri, const char* content,
                                  const char* language_id);
 
 /*
- * 关闭语言服务器中的文档
- *   uri: 文件 URI
- *   returns: 0 成功, -1 失败
+ * 关闭语言服务器中的文档 / Close a document in the language server
+ *   uri: 文件 URI / file URI
+ *   returns: 0 成功, -1 失败 / 0 success, -1 failure
  */
 DSTALK_API int  dstalk_lsp_close(const char* uri);
 
-/* ---- 查询操作 ---- */
+/* ---- 查询操作 / Query Operations ---- */
 
 /*
- * 获取诊断信息 (编译错误、警告等)
- *   uri:    文件 URI
- *   output: 输出参数，JSON 格式的诊断列表 (调用方通过 dstalk_free 释放)
- *   returns: 0 成功, -1 失败
+ * 获取诊断信息 (编译错误、警告等) / Get diagnostics (build errors, warnings, etc.)
+ *   uri:    文件 URI / file URI
+ *   output: 输出参数，JSON 格式的诊断列表 (调用方通过 dstalk_free 释放) / output param, JSON list of diagnostics (caller frees via dstalk_free)
+ *   returns: 0 成功, -1 失败 / 0 success, -1 failure
  *
- * JSON 输出格式示例:
+ * JSON 输出格式示例 / JSON output format example:
  * [
  *   {
  *     "range": { "start": {"line":0,"character":0}, "end":{"line":0,"character":5} },
@@ -63,23 +70,23 @@ DSTALK_API int  dstalk_lsp_close(const char* uri);
 DSTALK_API int  dstalk_lsp_diagnostics(const char* uri, char** output);
 
 /*
- * 获取悬停信息 (类型、文档等)
- *   uri:       文件 URI
- *   line:      行号 (0-based)
- *   character: 列号 (0-based, UTF-16 code units)
- *   output:    输出参数，JSON 格式的悬停信息 (调用方通过 dstalk_free 释放)
- *   returns: 0 成功, -1 失败
+ * 获取悬停信息 (类型、文档等) / Get hover info (type, documentation, etc.)
+ *   uri:       文件 URI / file URI
+ *   line:      行号 (0-based) / line number (0-based)
+ *   character: 列号 (0-based, UTF-16 code units) / column number (0-based, UTF-16 code units)
+ *   output:    输出参数，JSON 格式的悬停信息 (调用方通过 dstalk_free 释放) / output param, JSON hover info (caller frees via dstalk_free)
+ *   returns: 0 成功, -1 失败 / 0 success, -1 failure
  */
 DSTALK_API int  dstalk_lsp_hover(const char* uri, int line, int character,
                                   char** output);
 
 /*
- * 获取代码补全建议
- *   uri:       文件 URI
- *   line:      行号 (0-based)
- *   character: 列号 (0-based, UTF-16 code units)
- *   output:    输出参数，JSON 格式的补全列表 (调用方通过 dstalk_free 释放)
- *   returns: 0 成功, -1 失败
+ * 获取代码补全建议 / Get code completion suggestions
+ *   uri:       文件 URI / file URI
+ *   line:      行号 (0-based) / line number (0-based)
+ *   character: 列号 (0-based, UTF-16 code units) / column number (0-based, UTF-16 code units)
+ *   output:    输出参数，JSON 格式的补全列表 (调用方通过 dstalk_free 释放) / output param, JSON completion list (caller frees via dstalk_free)
+ *   returns: 0 成功, -1 失败 / 0 success, -1 failure
  */
 DSTALK_API int  dstalk_lsp_completion(const char* uri, int line, int character,
                                       char** output);

dstalk-core/include/dstalk/dstalk_services.h

@@ -1,3 +1,10 @@
+/**
+ * @file dstalk_services.h
+ * @brief Service vtable definitions for all plugin-provided services (AI, Session, HTTP, etc.).
+ * 所有插件提供的服务 vtable 定义（AI、会话、HTTP 等）。
+ * Copyright (c) 2026 dstalk contributors. GPLv3.
+ */
+
 #ifndef DSTALK_SERVICES_H
 #define DSTALK_SERVICES_H
 
@@ -7,46 +14,64 @@
 extern "C" {
 #endif
 
-// === AI 服务 vtable (实际服务名由插件注册: "ai.deepseek" / "ai.anthropic") ===
+/* ---- AI 服务 vtable / AI service vtable ---- */
+/* 以名称如 "ai.deepseek" 或 "ai.anthropic" 注册 / Registered under names such as "ai.deepseek" or "ai.anthropic" */
 typedef struct {
+    /* 配置服务商连接 (base_url, api_key, model 等) / Configure provider connection (base_url, api_key, model, etc.) */
     int (*configure)(const char* provider, const char* base_url,
                      const char* api_key, const char* model,
                      int max_tokens, double temperature);
+    /* 发送单轮聊天补全请求 (阻塞) / Send a single-turn chat completion (blocking) */
     dstalk_chat_result_t (*chat)(
         const dstalk_message_t* history, int history_len,
         const char* user_input,
         const char* tools_json);
+    /* 通过回调实现流式令牌传输的聊天补全 / Send a chat completion with streaming tokens via callback */
     dstalk_chat_result_t (*chat_stream)(
         const dstalk_message_t* history, int history_len,
         const char* user_input,
         dstalk_stream_cb cb, void* userdata);
+    /* 释放 dstalk_chat_result_t 持有的资源 / Free resources held by a dstalk_chat_result_t */
     void (*free_result)(dstalk_chat_result_t* result);
 } dstalk_ai_service_t;
 
-// === Session 服务 (service name: "session") ===
+/* ---- 会话服务 vtable / Session service vtable ---- */
+/* 以服务名称 "session" 注册 / Registered under service name "session" */
 typedef struct {
+    /* 将消息追加到会话历史 / Append a message to the session history */
     void (*add)(const dstalk_message_t* msg);
+    /* 清除会话历史中的所有消息 / Clear all messages from the session history */
     void (*clear)(void);
+    /* 将会话历史保存到文件 (JSON); 成功返回 0 / Save session history to a file (JSON); returns 0 on success */
     int  (*save)(const char* path);
+    /* 从文件 (JSON) 加载会话历史; 成功返回 0 / Load session history from a file (JSON); returns 0 on success */
     int  (*load)(const char* path);
+    /* 获取完整消息历史; out_count 接收数组长度 / Get the full message history; out_count receives the array length */
     const dstalk_message_t* (*history)(int* out_count);
+    /* 返回当前会话历史的近似令牌数 / Return the approximate token count of the current session history */
     int  (*token_count)(void);
 } dstalk_session_service_t;
 
-// === Context 服务 (service name: "context") ===
+/* ---- 上下文服务 vtable / Context service vtable ---- */
+/* 以服务名称 "context" 注册 / Registered under service name "context" */
 typedef struct {
+    /* 计算消息数组中近似的令牌数 / Count approximate tokens in an array of messages */
     size_t (*count_tokens)(const dstalk_message_t* msgs, int count);
+    /* 裁剪消息历史以适应 max_tokens; out/out_count 为新分配 / Trim message history to fit within max_tokens; out/out_count are newly allocated */
     int    (*trim)(const dstalk_message_t* in, int in_count,
                    dstalk_message_t** out, int* out_count,
                    size_t max_tokens);
 } dstalk_context_service_t;
 
-// === HTTP 服务 (service name: "http") ===
+/* ---- HTTP 服务 vtable / HTTP service vtable ---- */
+/* 以服务名称 "http" 注册 / Registered under service name "http" */
 typedef struct {
+    /* POST JSON 体到主机; 返回响应体和 HTTP 状态码 / POST JSON body to a host; returns response body and HTTP status code */
     int (*post_json)(const char* host, const char* port,
                      const char* target, const char* body,
                      const char* headers_json,
                      char** response_body, int* status_code);
+    /* POST 带流式响应; 令牌通过回调传递 / POST with streaming response; tokens are delivered via callback */
     int (*post_stream)(const char* host, const char* port,
                        const char* target, const char* body,
                        const char* headers_json,
@@ -54,38 +79,61 @@ typedef struct {
                        char** response_body, int* status_code);
 } dstalk_http_service_t;
 
-// === File IO 服务 (service name: "file_io") ===
+/* ---- 文件 I/O 服务 vtable / File I/O service vtable ---- */
+/* 以服务名称 "file_io" 注册 / Registered under service name "file_io" */
 typedef struct {
+    /* 读取整个文件内容到 *content; 成功返回 0 / Read entire file content into *content; returns 0 on success */
     int (*read)(const char* path, char** content);
+    /* 将内容写入文件 (覆盖已有文件); 成功返回 0 / Write content to a file (overwrites if exists); returns 0 on success */
     int (*write)(const char* path, const char* content);
 } dstalk_file_io_service_t;
 
-// === Config 服务 (service name: "config") ===
+/* ---- 配置服务 vtable / Config service vtable ---- */
+/* 以服务名称 "config" 注册 / Registered under service name "config" */
 typedef struct {
+    /* 通过键名获取配置值; 未找到返回 NULL / Get a config value by key; returns NULL if not found */
     const char* (*get)(const char* key);
+    /* 设置配置键值对; 成功返回 0 / Set a config key/value pair; returns 0 on success */
     int (*set)(const char* key, const char* value);
+    /* 从 JSON 配置文件加载并合并键值对 / Load and merge key/value pairs from a JSON config file */
     int (*load_file)(const char* path);
 } dstalk_config_service_t;
 
-// === Tools 服务 (service name: "tools") ===
+/* ---- 工具服务 vtable / Tools service vtable ---- */
+/* 以服务名称 "tools" 注册 / Registered under service name "tools" */
+
+/* 已注册工具被调用时触发的处理器; 接收 JSON 参数, 返回 JSON 结果 / Handler invoked when a registered tool is called; receives JSON args, returns JSON result */
 typedef char* (*dstalk_tool_handler_fn)(const char* args_json);
+
 typedef struct {
+    /* 注册工具，包含名称、描述和 JSON Schema 参数 / Register a tool with name, description, and JSON Schema parameters */
     int (*register_tool)(const char* name, const char* desc,
                          const char* params_schema,
                          dstalk_tool_handler_fn handler);
+    /* 取消注册之前注册的工具 / Unregister a previously registered tool */
     void (*unregister_tool)(const char* name);
+    /* 获取所有已注册工具为 JSON 数组 (OpenAI 工具格式) / Get all registered tools as a JSON array (OpenAI tool format) */
     char* (*get_tools_json)(void);
+    /* 按名称执行已注册工具，传入 JSON 参数 / Execute a registered tool by name with the given JSON arguments */
     char* (*execute)(const char* name, const char* args_json);
 } dstalk_tools_service_t;
 
-// === LSP 服务 (service name: "lsp") ===
+/* ---- LSP 服务 vtable / LSP service vtable ---- */
+/* 以服务名称 "lsp" 注册 / Registered under service name "lsp" */
 typedef struct {
+    /* 启动指定语言的 LSP 服务器进程 / Start an LSP server process for the given language */
     int (*start)(const char* server_cmd, const char* language);
+    /* 停止 LSP 服务器并清理资源 / Stop the LSP server and clean up resources */
     void (*stop)(void);
+    /* 在 LSP 服务器中打开文档 / Open a document in the LSP server */
     int (*open_document)(const char* uri, const char* content, const char* lang_id);
+    /* 在 LSP 服务器中关闭文档 / Close a document in the LSP server */
     int (*close_document)(const char* uri);
+    /* 获取文档的诊断信息 (错误、警告) 以 JSON 格式返回 / Retrieve diagnostics (errors, warnings) for a document as JSON */
     int (*get_diagnostics)(const char* uri, char** json_out);
+    /* 获取指定位置的悬停信息以 JSON 格式返回 / Retrieve hover information at a given position as JSON */
     int (*get_hover)(const char* uri, int line, int col, char** json_out);
+    /* 获取指定位置的代码补全建议以 JSON 格式返回 / Retrieve code completion suggestions at a given position as JSON */
     int (*get_completion)(const char* uri, int line, int col, char** json_out);
 } dstalk_lsp_service_t;
 

dstalk-core/include/dstalk/dstalk_types.h

@@ -1,3 +1,10 @@
+/**
+ * @file dstalk_types.h
+ * @brief Shared data types used across the dstalk host and all plugins.
+ * 跨主机和所有插件共享的数据类型定义。
+ * Copyright (c) 2026 dstalk contributors. GPLv3.
+ */
+
 #ifndef DSTALK_TYPES_H
 #define DSTALK_TYPES_H
 
@@ -7,42 +14,42 @@
 extern "C" {
 #endif
 
-// 消息结构（跨插件共享）
+/* 所有插件共享的消息结构体 / Shared message structure used across plugins */
 typedef struct {
-    const char* role;           // "user", "assistant", "system", "tool"
-    const char* content;        // 消息内容
-    const char* tool_call_id;   // tool 响应时必填
-    const char* tool_calls_json;// assistant 返回的工具调用（JSON 数组）
+    const char* role;           // 角色标识 / Role identifier ("user", "assistant", "system", "tool")
+    const char* content;        // 消息正文文本 / Message body text
+    const char* tool_call_id;   // 工具调用响应消息所需 / Required for tool response messages
+    const char* tool_calls_json;// 助手工具调用的 JSON 数组 / JSON array of tool calls from assistant
 } dstalk_message_t;
 
-// 聊天结果
+/* 聊天/补全调用返回的结果 / Result returned from a chat / completion call */
 typedef struct {
-    int ok;
-    const char* content;        // dstalk_strdup 分配，调用方 dstalk_free
-    const char* error;          // dstalk_strdup 分配
-    int http_status;
-    const char* tool_calls_json;// dstalk_strdup 分配
+    int ok;                     // 0=失败, 非零=成功 / 0 = failure, non-zero = success
+    const char* content;        // dstalk_strdup 分配; 调用方用 dstalk_free 释放 / allocated by dstalk_strdup; caller frees with dstalk_free
+    const char* error;          // dstalk_strdup 分配; 成功时为 NULL / allocated by dstalk_strdup; NULL on success
+    int http_status;            // 服务商返回的 HTTP 状态码 / HTTP status code from the provider
+    const char* tool_calls_json;// dstalk_strdup 分配; 工具调用的 JSON 数组 / allocated by dstalk_strdup; JSON array of tool calls
 } dstalk_chat_result_t;
 
-// 流式回调
+/* 流式令牌回调: 返回非零值提前中止流传输 / Streaming token callback: return non-zero to abort the stream early */
 typedef int (*dstalk_stream_cb)(const char* token, void* userdata);
 
-// 事件类型
+/* 事件类型代码 (匿名枚举) / Event type codes (anonymous enum) */
 enum {
-    DSTALK_EVENT_MESSAGE = 1,       // data = dstalk_message_t*
-    DSTALK_EVENT_SESSION_CLEAR,
-    DSTALK_EVENT_CONFIG_CHANGED,
-    DSTALK_EVENT_PLUGIN_LOADED,     // data = plugin info JSON string
-    DSTALK_EVENT_PLUGIN_UNLOADED,
-    DSTALK_EVENT_CUSTOM = 1000,     // 插件自定义事件起始值
+    DSTALK_EVENT_MESSAGE = 1,       // 数据为 dstalk_message_t* / data = dstalk_message_t*
+    DSTALK_EVENT_SESSION_CLEAR,     // 会话历史已清除 / session history cleared
+    DSTALK_EVENT_CONFIG_CHANGED,    // 配置键/值已更新 / configuration key/value updated
+    DSTALK_EVENT_PLUGIN_LOADED,     // 数据为插件信息 JSON 字符串 / data = plugin info JSON string
+    DSTALK_EVENT_PLUGIN_UNLOADED,   // 插件已卸载 / plugin unloaded
+    DSTALK_EVENT_CUSTOM = 1000,     // 插件自定义事件的基础值 / base value for plugin-defined custom events
 };
 
-// 日志级别
+/* 日志严重等级 (匿名枚举) / Log severity levels (anonymous enum) */
 enum {
-    DSTALK_LOG_DEBUG = 0,
-    DSTALK_LOG_INFO = 1,
-    DSTALK_LOG_WARN = 2,
-    DSTALK_LOG_ERROR = 3,
+    DSTALK_LOG_DEBUG = 0,   // 详细调试消息 / verbose debug messages
+    DSTALK_LOG_INFO  = 1,   // 信息性消息 / informational messages
+    DSTALK_LOG_WARN  = 2,   // 警告条件 / warning conditions
+    DSTALK_LOG_ERROR = 3,   // 错误条件 / error conditions
 };
 
 #ifdef __cplusplus