### Build and Run EchoTrace from Source

Source: https://github.com/ycccccccy/echotrace/blob/main/README.md

Follow these steps to clone the repository, install dependencies, and run or build the application locally.

```bash
# 1. 克隆项目到本地
git clone https://github.com/ycccccccy/echotrace.git
cd echotrace

# 2. 安装项目依赖
flutter pub get

# 3. 运行应用（调试模式）
flutter run

# 4. 打包可执行文件 (以 Windows 为例)
flutter build windows
```

--------------------------------

### 命令行导出聊天记录

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/beginner_guide.md

使用命令行模式进行自动化备份。需在程序所在目录通过 PowerShell 或 CMD 执行，且必须先在 UI 界面完成配置和解密。

```powershell
# 场景 1：导出所有会话为 HTML 网页
.\echotrace.exe -e C:\MyBackup --format html --all

# 场景 2：仅导出 2024 年的数据（默认格式为 JSON）
.\echotrace.exe -e C:\MyBackup --start 2024-01-01 --end 2024-12-31
```

--------------------------------

### 调试日志获取接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

获取内部运行日志以排查错误。获取的字符串同样需要调用 wcdb_free_string 释放。

```c
wcdb_status wcdb_get_logs(char** out_json);
```

--------------------------------

### Lifecycle Management

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

Functions for initializing and shutting down the WCDB environment.

```APIDOC
## wcdb_init

### Description
Initializes the log buffer and internal state. Should be called once at process startup.

### Signature
wcdb_status wcdb_init();

## wcdb_shutdown

### Description
Cleans up all internal states and forces the closure of all unclosed account handles. Recommended to call before process exit.

### Signature
wcdb_status wcdb_shutdown();
```

--------------------------------

### 群聊工具接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

用于获取群成员数量及包含头像信息的群成员列表。

```c
// 获取群成员数量
wcdb_status wcdb_get_group_member_count(wcdb_handle handle, const char* chatroom_id, int32_t* out_count);

// 获取群成员列表（含头像信息）
wcdb_status wcdb_get_group_members(wcdb_handle handle, const char* chatroom_id, char** out_json);
```

--------------------------------

### 消息统计接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

快速获取指定会话的消息总数。

```c
wcdb_status wcdb_get_message_count(wcdb_handle handle, const char* username, int32_t* out_count);
```

--------------------------------

### 完整调用流程示例

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

展示了从初始化、打开账号、查询数据到最终清理的完整 C/C++ 调用流程。

```c
// 1. 全局初始化
wcdb_init();

wcdb_handle handle = 0;
const char* db_path = "C:\\Users\\...\\Msg\\MicroMsg.db";
const char* key = "a1b2...e8f9"; // 64位密钥

// 2. 打开账号
if (wcdb_open_account(db_path, key, &handle) == 0) {
    
    // 3. 获取会话列表
    char* sessions_json = NULL;
    if (wcdb_get_sessions(handle, &sessions_json) == 0) {
        printf("Sessions: %s\n", sessions_json);
        wcdb_free_string(sessions_json); // 记得释放！
    }

    // 4. 获取某个会话的消息
    char* msgs_json = NULL;
    // 获取最新 50 条
    if (wcdb_get_messages(handle, "wxid_target", 50, 0, &msgs_json) == 0) {
        printf("Messages: %s\n", msgs_json);
        wcdb_free_string(msgs_json); // 记得释放！
    }

    // 5. 关闭账号
    wcdb_close_account(handle);
} else {
    // 打开失败，查看日志
    char* logs = NULL;
    wcdb_get_logs(&logs);
    printf("Error Logs: %s\n", logs);
    wcdb_free_string(logs);
}

// 6. 全局清理
wcdb_shutdown();
```

--------------------------------

### 消息记录查询接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

获取指定用户的消息记录，支持分页查询。内部会自动扫描所有分库并按时间排序。

```c
wcdb_status wcdb_get_messages(wcdb_handle handle, const char* username, int32_t limit, int32_t offset, char** out_json);
```

--------------------------------

### 会话列表查询接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

获取所有聊天会话的 JSON 数组。若操作失败，返回包含 _error 字段的 JSON。

```c
wcdb_status wcdb_get_sessions(wcdb_handle handle, char** out_json);
```

--------------------------------

### 联系人信息获取接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

批量获取联系人的昵称或头像 URL，输入为 JSON 字符串数组。

```c
// 批量获取昵称
wcdb_status wcdb_get_display_names(wcdb_handle handle, const char* usernames_json, char** out_json);

// 批量获取头像 URL
wcdb_status wcdb_get_avatar_urls(wcdb_handle handle, const char* usernames_json, char** out_json);
```

--------------------------------

### Account Connection

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

Functions for managing database account handles.

```APIDOC
## wcdb_open_account

### Description
Opens a database account using the provided path and hex key. Automatically mounts associated message and contact databases.

### Signature
wcdb_status wcdb_open_account(const char* session_db_path, const char* hex_key, wcdb_handle* out_handle);

## wcdb_close_account

### Description
Closes the specified account handle and releases database connection resources.

### Signature
wcdb_status wcdb_close_account(wcdb_handle handle);
```

--------------------------------

### 账号连接管理接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

用于打开和关闭数据库账号句柄。打开账号时需提供数据库路径与 64 位十六进制密钥。

```c
wcdb_status wcdb_open_account(const char* session_db_path, const char* hex_key, wcdb_handle* out_handle);
```

```c
wcdb_status wcdb_close_account(wcdb_handle handle);
```

--------------------------------

### 初始化与清理接口

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

在进行任何业务操作前调用初始化，并在进程退出前调用清理以释放资源。

```c
wcdb_status wcdb_init();
```

```c
wcdb_status wcdb_shutdown();
```

--------------------------------

### Diagnostics

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

Functions for retrieving internal logs for debugging.

```APIDOC
## wcdb_get_logs

### Description
Retrieves internal operation logs for troubleshooting errors.

### Signature
wcdb_status wcdb_get_logs(char** out_json);
```

--------------------------------

### Data Querying

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

Functions for retrieving sessions, messages, and contact information.

```APIDOC
## wcdb_get_sessions

### Description
Retrieves a JSON array of all chat sessions.

### Signature
wcdb_status wcdb_get_sessions(wcdb_handle handle, char** out_json);

## wcdb_get_messages

### Description
Retrieves a paginated list of messages for a specific user.

### Signature
wcdb_status wcdb_get_messages(wcdb_handle handle, const char* username, int32_t limit, int32_t offset, char** out_json);

## wcdb_get_message_count

### Description
Gets the total message count for a specific session.

### Signature
wcdb_status wcdb_get_message_count(wcdb_handle handle, const char* username, int32_t* out_count);

## wcdb_get_display_names

### Description
Batch retrieves display names for a list of usernames provided as a JSON array.

### Signature
wcdb_status wcdb_get_display_names(wcdb_handle handle, const char* usernames_json, char** out_json);

## wcdb_get_avatar_urls

### Description
Batch retrieves avatar URLs for a list of usernames provided as a JSON array.

### Signature
wcdb_status wcdb_get_avatar_urls(wcdb_handle handle, const char* usernames_json, char** out_json);
```

--------------------------------

### Group Chat Tools

Source: https://github.com/ycccccccy/echotrace/blob/main/docs/wcdb_realtime.md

Functions for interacting with group chat data.

```APIDOC
## wcdb_get_group_member_count

### Description
Gets the number of members in a specific chatroom.

### Signature
wcdb_status wcdb_get_group_member_count(wcdb_handle handle, const char* chatroom_id, int32_t* out_count);

## wcdb_get_group_members

### Description
Retrieves a list of group members including avatar information.

### Signature
wcdb_status wcdb_get_group_members(wcdb_handle handle, const char* chatroom_id, char** out_json);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.