# web_ai_agent_lib

**Repository Path**: jimonik/web_ai_agent_lib

## Basic Information

- **Project Name**: web_ai_agent_lib
- **Description**: 跨平台C库，内核用lua实现，给各种平台接入ai能力
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# web_ai_agent_lib

跨 macOS、Windows、Linux、Android、iOS 的 C11 ABI。负责 Lua runtime 更新、生命周期、HTTP/TCP 和宿主桥接；AI 平台协议只在 Lua 中实现。

## 运行流程

1. 宿主以运行时根目录和数据目录启动默认实例或 `waal_context`。
2. C 从更新服务读取版本清单；发现更高版本时下载并原子切换 `webai_lua_runtime`，更新失败则拒绝启动。
3. 加载 `main.lua`，调用 `main()`；`waal_call` 转发到 `waal_dispatch(method,json)`。
4. `waal_run()` 常驻，或由宿主调用 `waal_pump()`；停止时调用可选 `waal_on_stop()` 并释放资源。

同一实例独立持有 Lua、HTTP 队列、路径、状态和事件回调。同进程 C API 串行；回调与触发调用同线程，回调中不得重入 WAAL。

## 相关仓库与调用关系

`xide`、`quick_account_opening`、`wai`、`ai_adb_debugger`、`project_manager` 和 `spec` 是六个并列宿主，它们不互相调用；本仓库是共同的 C ABI 层，向下加载 Lua，向上把事件和 MCP 调用交还发起请求的宿主：

```text
xide (Android) ───────────── Java/JNI ───────────────┐
quick_account_opening (Electron) ── IPC/Koffi ──────┤
wai (终端) ───────────── AgentRunner/Koffi/ffi-rs ──┤
ai_adb_debugger (Electron) ── JSONL/Python ctypes ──┼──> web_ai_agent_lib (本仓库)
project_manager (Node/SEA) ───────── Koffi ─────────┤              │
spec / DevSpec (Node Web) ────────── Koffi ─────────┘              │
                                                                   │ waal_dispatch / waal_tick
                                                                   ▼
                                                        webai_lua_runtime (Lua)
                                                                   │ mcp.call / 事件
                                                                   └──> 对应宿主工具
```

| 仓库 | 与本仓库的调用关系 |
| --- | --- |
| [xide](https://gitee.com/jimonik/xide) | 通过本仓库的 Android JNI 包装创建 context、调用方法并接收事件。 |
| [quick_account_opening](https://gitee.com/jimonik/quick_account_opening) | Electron 主进程使用 Koffi 加载本仓库动态库。 |
| [wai](https://gitee.com/jimonik/wai) | Node 终端使用 Koffi 或 ffi-rs 加载本仓库动态库。 |
| [ai_adb_debugger](https://gitee.com/jimonik/ai_adb_debugger) | Electron 通过 Python JSONL 桥和 `ctypes` 加载本仓库动态库。 |
| [project_manager](https://gitee.com/code_87/project_manager) | Node/SEA 项目管理宿主通过 Koffi 加载本仓库，为普通用户提供 AI 登录与新会话 Shell 编排生成。 |
| [spec / DevSpec](https://gitee.com/code_87/spec) | Node Web 宿主通过 Koffi 加载本仓库，用于用户 AI 绑定、文章生成与提炼。 |
| [webai_lua_runtime](https://gitee.com/jimonik/webai_lua_runtime) | 被本仓库下载、加载和推进；通过 `waal_dispatch` 接收调用，通过 C 注入的 `waal.native_*` 使用 HTTP/TCP。 |
| [web_ai_agent_lib](https://gitee.com/jimonik/web_ai_agent_lib)（本仓库） | 稳定 ABI 与平台能力边界，不实现具体 AI 网站协议或产品工具。 |
| `update_service` | 通用更新服务；只保存渠道版本和制品，所有新版本固定强制更新。 |

## C API 最小用法

```c
char error[1024];
waal_context *ctx = waal_context_create();
waal_context_set_event_callback(ctx, on_event, user_data);
waal_context_start(ctx, runtime_root, data_root, NULL, NULL, error, sizeof(error));

char *json = waal_context_call_alloc(ctx, "chat.send", "{}", error, sizeof(error));
if (json) { use_json(json); waal_free(json); }

waal_context_stop(ctx, error, sizeof(error));
waal_context_destroy(ctx);
```

- 动态结果无固定长度；必须用 `waal_free()` 释放。
- 无 context 的旧 API 映射到默认实例。
- `waal_kill_all()` 停止所有实例但不销毁 context；调用方仍需 `waal_context_destroy()`。
- 首次启动必须传两个目录；后续 `waal_start(NULL,NULL,...)` 复用目录并检查更新。
- 旧凭证参数保留 ABI 但已忽略。

## Lua 能力

```lua
waal.paths.runtime_base
waal.paths.source   -- <runtime_base>/webai_lua_runtime
waal.paths.storage

local id = waal.native_http_start({url="https://example.com", method="GET", headers={}})
local result = waal.native_http_poll(id)
waal.native_http_cancel(id)

waal.native_tcp_listen(host, port)
waal.native_tcp_accept(server)
waal.native_tcp_receive(client, max_bytes)
waal.native_tcp_send(client, data)
waal.native_tcp_close(socket)

waal.emit(event_name, json_payload)
waal.stop()
```

HTTP 可并发轮询；结果含 `done/status/body/headers/error`。TCP 为非阻塞基础接口，路由由 Lua 实现。业务数据写 `waal.paths.storage`，不得写热更新源码目录。

文件搜索和修改必须由宿主提供有路径边界的 MCP：Electron 限制到用户授权目录，XIDE 限制到当前项目。C 只转发 `mcp.register/call/result`，不扫描任意文件系统。

## 强制更新与发布

默认服务：`http://42.193.21.75:18081/`，默认渠道：`webai_lua_runtime`。渠道使用产品级名称，避免多个产品都叫 `stable`。可在启动前设置 `WAAL_UPDATE_SERVER_URL`、`WAAL_UPDATE_CHANNEL`，或由各宿主调用 `waal_context_configure_update()` 配置完整清单地址。

```sh
WAAL_LUA_ABI=5.5 LUAC_BIN=/path/to/target-lua/luac \
scripts/package_runtime.sh \
  ../webai_lua_runtime ./dist/runtime 2026081403

../update_service/scripts/publish_release.sh \
  http://127.0.0.1:18081 webai_lua_runtime 2026081403 \
  ./dist/runtime/runtime-2026081403.tar.gz
```

打包脚本用目标 Lua 5.4 或 5.5 的 `luac` 把 `.lua` 编译为剥离调试信息的字节码，再生成 `runtime-<版本>.tar.gz`。更新服务本身不理解 Lua，只按渠道保存版本和文件。字节码与客户端 ABI 不兼容时会在加载阶段失败并回滚文件。

服务器不可达时可使用本地版本，以适应更新服务器暂时不稳定；一旦成功取得清单并发现更高版本，本次更新就是强制更新，下载、解包或新 runtime 启动任一步失败都拒绝启动。新 runtime 启动失败会先回滚文件，等待下次重试。Lua 可通过 `runtime.update_status` 读取服务版本、地址、当前版本、最新版本和最近错误。

## 构建

推荐直接使用统一入口，它会按当前目标安装 vcpkg、补齐锁定 baseline 并构建：

```sh
sh scripts/build.sh linux x86_64 Release
sh scripts/build.sh macos arm64 Release
```

macOS 上构建 Linux 制品时复用本机已保留的按架构构建镜像，避免每次重新下载、安装工具链和第三方依赖：

```sh
docker run --rm --platform linux/arm64 \
  -v "$PWD:/src" -w /src waal-linux-builder:arm64 \
  sh -lc 'VCPKG_ROOT=/tmp/vcpkg sh scripts/build.sh linux arm64 Release'

docker run --rm --platform linux/amd64 \
  -v "$PWD:/src" -w /src waal-linux-builder:amd64 \
  sh -lc 'VCPKG_ROOT=/tmp/vcpkg sh scripts/build.sh linux x86_64 Release'
```

`waal-linux-builder:arm64` 与 `waal-linux-builder:amd64` 是长期复用的本机构建镜像，不应在常规清理中删除。它们只用于生成 glibc Linux 制品。Android/Termux 制品仍通过本机 Android NDK 交叉编译，不进入 Docker：`sh scripts/build.sh android arm64-v8a Release`。

自动安装 vcpkg 时优先从 Gitee 镜像取得源码；首次 bootstrap 所需的 `vcpkg-glibc`、`vcpkg-glibc-arm64`、`vcpkg-muslc` 或 `vcpkg-macos` 启动程序，以及后续 CMake、OpenSSL、curl 等 GitHub 资源，均默认通过 `https://ghfast.top/` 加速，并继续按 vcpkg 官方元数据中的原始 SHA-512 校验文件。可用 `WAAL_GITHUB_MIRROR=https://你的镜像前缀/` 更换加速地址，或设置 `WAAL_GITHUB_MIRROR=off` 回退原始地址。如果已经配置 `X_VCPKG_ASSET_SOURCES`，构建脚本会完整保留外部配置。

项目构建优先使用 Ninja；精简服务器没有 Ninja 时自动改用系统已有的 Unix Makefiles，不要求为了发布 WAAL 额外安装 Ninja。开始配置 WAAL 前还会检查 `make`/`ninja` 和 C 编译器，缺少时给出明确错误。

推荐 vcpkg manifest：

```sh
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh        # Windows 使用 bootstrap-vcpkg.bat
export VCPKG_ROOT=/absolute/vcpkg
cmake --preset vcpkg-release
cmake --build --preset vcpkg-release
```

已安装系统依赖时可用 `cmake -S . -B build && cmake --build build`；pkg-config 仅作后备。

Android 使用 NDK toolchain；当前发布目标用 `sh scripts/build.sh android arm64-v8a Release` 生成 ARM64 `.so`。iOS 使用对应 toolchain 并设置 `-DWAAL_BUILD_SHARED=OFF`。

### 构建并发布预编译库

原生库直接发布到通用更新服务，不再使用 Git 仓库保存制品。版本必须是递增整数：

```sh
# macOS 构建机同时构建并发布 arm64、x86_64
sh scripts/publish_native.sh http://42.193.21.75:18081 2026083001

# Android ARM64 与 MinGW-w64 Windows x64
sh scripts/publish_native.sh http://42.193.21.75:18081 2026083001 android arm64-v8a
sh scripts/publish_native.sh http://42.193.21.75:18081 2026083001 windows x64
```

渠道分别为 `waal_macos_arm64`、`waal_macos_x86_64`、`waal_android_arm64_v8a`、`waal_windows_x64`；Linux 制品必须在对应架构的 Linux 构建机或上述保留镜像中生成，再发布到 `waal_linux_arm64` 或 `waal_linux_x86_64`。macOS 可用 MinGW-w64 交叉生成 Windows x64 DLL，第三方依赖静态链接，发布前用 `objdump -p` 检查 PE 架构和系统 DLL 依赖。

宿主也可独立下载最新版本：

```sh
WAAL_UPDATE_SERVER_URL=http://42.193.21.75:18081 \
  sh scripts/download_prebuilt macos arm64 latest
```

下载器每次查询目标渠道；服务不可用且本地文件存在时继续使用本地文件，没有本地文件则停止。服务已返回新版本后，下载失败会停止，不能绕过强制更新。原生库和 Lua runtime 均不使用 HMAC、签名或文件哈希。

## 安全边界

- 更新包仅接受 gzip+ustar；拒绝绝对路径、`..`、链接和特殊归档项。
- 更新接口公开，不校验 HMAC、制品签名或文件哈希；默认地址使用 HTTP，任何能控制链路或服务器的人都能替换更新包。HTTP 重定向仍限制协议和次数。
- Lua 标准库不是安全沙箱；更新服务的发布权限等同远程代码发布权限。
- 更新与 Lua 调用应在宿主后台线程运行；多进程不得同时操作同一 runtime 目录。