fix: 修复了部分问题：

信号处理器安全	移除了信号处理器中的 cleanup_terminal() 调用
线程取消安全	添加 pthread_cleanup_push/pop 确保终端恢复
Socket 竞态条件	添加 send_message_safe() 和 get_socket_fd() 辅助函数
资源泄漏	使用 goto cleanup 统一错误处理路径
poll 事件检查	添加 POLLERR/POLLHUP/POLLNVAL 检查
鼠标解析安全	添加临时缓冲区和数值范围验证
条件变量改进	支持 CLOCK_MONOTONIC
载荷验证	添加写入字节数验证
注释完善	添加详细的函数和模块文档

src/client.h

@@ -15,7 +15,52 @@
 #define SOCKET_PATH "/var/run/bash-smart.sock"
 #define MAX_BUF_SIZE 4096
 
-// 函数声明
-int seeking_solutions(const char *filename, char *const argv[], char *const envp[], const char *logPath, int *output_fd);
-
+/**
+ * @brief 建立与服务端的连接并进入交互模式
+ * 
+ * 此函数会：
+ * 1. 连接到 Unix Domain Socket 服务端
+ * 2. 发送初始化信息（文件名、参数、环境变量、终端信息等）
+ * 3. 启动多个线程处理输入输出和窗口事件
+ * 4. 阻塞直到服务端关闭连接或收到退出信号
+ * 
+ * 线程模型：
+ * - 响应监听线程：接收服务端消息并输出到 output_fd
+ * - 窗口监听线程：监听 SIGWINCH 信号，发送窗口大小更新
+ * - 终端输入线程：捕获键盘和鼠标输入，发送到服务端
+ * 
+ * 信号处理：
+ * - SIGWINCH：触发窗口大小更新
+ * - SIGINT/SIGTERM：触发优雅退出
+ * 
+ * @param filename 要执行的文件路径
+ * @param argv 命令行参数数组，以 NULL 结尾
+ * @param envp 环境变量数组，以 NULL 结尾
+ * @param logPath 日志/错误文件路径（可以是相对路径或绝对路径）
+ * @param output_fd 指向输出文件描述符的指针，通常为 STDOUT_FILENO
+ * 
+ * @return 0 成功完成，-1 发生错误
+ * 
+ * @note 此函数会修改终端设置（原始模式、鼠标跟踪），
+ *       但保证在退出时恢复原始状态
+ * @note 调用者应确保在调用前服务端已经启动
+ * 
+ * @code
+ * // 使用示例
+ * int output_fd = STDOUT_FILENO;
+ * char* argv[] = {"my_command", "--option", NULL};
+ * extern char** environ;
+ * 
+ * int result = seeking_solutions("/usr/bin/my_command", 
+ *                                 argv, environ, 
+ *                                 "/tmp/error.log", 
+ *                                 &output_fd);
+ * if (result < 0) {
+ *     fprintf(stderr, "连接失败\n");
+ * }
+ * @endcode
+ */
+int seeking_solutions(const char* filename, char* const argv[],
+                      char* const envp[], const char* logPath, int* output_fd);
+                      
 #endif // EXEC_SOCKET_H