# webai_lua_runtime

**Repository Path**: jimonik/webai_lua_runtime

## Basic Information

- **Project Name**: webai_lua_runtime
- **Description**: ai内核，热更新，配合web_ai_agent_lib使用
- **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

# webai_lua_runtime

`web_ai_agent_lib` 热更新的 Lua 业务内核。AI 来源、登录、云端会话、聊天和 MCP 均在 Lua 中实现；C ABI 与平台无关。

## 相关仓库与调用关系

当前有六个应用项目直接接入 `web_ai_agent_lib`，再由 C 加载本仓库；独立的 `update_service` 负责保存版本和更新包。宿主之间没有调用关系；本仓库也不直接引用 Android、Electron、Python 或 Node API，所有平台能力都经过 C 注入的 `waal` 接口和事件返回：

```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 (C11 ABI)
project_manager (Node/SEA) ───────── Koffi ─────────┤              │
spec / DevSpec (Node Web) ────────── Koffi ─────────┘              │ 加载、强制更新、pump
                                                                  ▼
update_service ── 版本清单和压缩包 ───────────────────> webai_lua_runtime (本仓库)
                                                                  │ mcp.call / 事件
                                                                  └──> 对应宿主工具
```

| 仓库 | 与本仓库的调用关系 |
| --- | --- |
| [xide](https://gitee.com/jimonik/xide) | Android 宿主，向 Lua 注册 XIDE 项目工具并消费登录、会话和对话状态。 |
| [quick_account_opening](https://gitee.com/jimonik/quick_account_opening) | Electron 开户宿主，向 Lua 注册经审批的开户与本地工具。 |
| [wai](https://gitee.com/jimonik/wai) | 终端宿主，向 Lua 注册工作区、终端、Git 和 Skill 工具。 |
| [ai_adb_debugger](https://gitee.com/jimonik/ai_adb_debugger) | Electron/ADB 宿主，向 Lua 注册受限 ADB 与授权源码工具。 |
| [project_manager](https://gitee.com/code_87/project_manager)（本机：`/Users/jimo/PycharmProjects/project_manager`） | Node/SEA 项目管理宿主，提供用户 AI 登录与新会话 Shell 编排生成，上下文只来自当前用户的仓库、环境、运行时、服务和编辑器。 |
| [spec / DevSpec](https://gitee.com/code_87/spec) | Node Web 宿主，用于用户 AI 绑定、文章生成与提炼。 |
| [webai_lua_runtime](https://gitee.com/jimonik/webai_lua_runtime)（本仓库） | 实现 `waal_dispatch/waal_tick`、AI 来源协议和 MCP 循环，只依赖 C 提供的平台能力。 |
| [web_ai_agent_lib](https://gitee.com/jimonik/web_ai_agent_lib) | 唯一直接加载本仓库的公共 C 内核，负责强制更新、Lua 生命周期、HTTP/TCP 和事件桥。 |
| `update_service` | 通用文件更新服务；只保存渠道、数字版本和制品，所有新版本固定强制更新。 |

## 入口与目录

- `main.lua`：注册 `login.*`、`providers.*`、`chat.*`、`mcp.*`，提供 `main/waal_tick/waal_dispatch/waal_on_stop`。
- `core/`：生命周期、HTTP、JSON、事件、存储。
- `login/providers/`、`chat/providers/`：各来源协议插件。
- `mcp/`：工具注册、调用与结果状态机。
- `lib/`：纯 Lua 库。
- `vendor/`：随包第三方资产；`qrcode.js` 供本地扫码页生成二维码，许可证必须保留；`deepseek_pow.wasm` 是当前未被 Lua 引用的 DeepSeek PoW 遗留资产。

凭证和缓存只写 `waal.paths.storage`，不写源码目录。停止会取消任务并释放 HTTP、TCP 和 Lua 状态。

## 宿主方法

- `runtime.info`：返回唯一的 Lua 内核名称和版本；版本来自 `core/app.lua`。
- `runtime.update_status`：返回 C 内核最近一次更新检查、当前/最新版本、更新服务地址和错误状态，供宿主及 AI 查询；新版本固定强制更新。
- `providers.list`：来源、名称、图标键、登录/可用状态、能力和同一份 `runtime` 版本信息。
- `login.start/status/account/accounts/cancel/security/action`；也支持 `login.<provider>`。`login.action` 用于提交登录任务的交互步骤；WAI 的元宝登录在微信授权后用 `login.security` 刷新一次签名，再提交登录请求。
- `chat.send/status/cancel`。
- `chat.session.list/history/delete`。
- `mcp.register/result`。
- `settings.ai.enable/remove`、`security.yuanbao.get/set`、`app.stop`。

参数和结果均为 JSON。异步状态通过统一事件回调发送，如 `login.waiting_scan/scanned/authorized/success/error`、`chat.model_request`、`mcp.call`。

所有接入项目都应在自己的 AI 界面或终端标题中展示 `Lua 内核 v<runtime.version>`，不得把 Lua 版本写死在宿主中。旧运行时未提供该字段时，宿主可显示“Lua 内核版本未知”，但不能用 C ABI 版本冒充 Lua 版本。

登录 `mode="qr"` 时宿主显示事件载荷；`qr_kind=content|image_url|image_base64` 决定编码或解码方式。`mode="web"` 启动登录页，监听地址由宿主选择：终端宿主通常优先传入局域网私有 IPv4，没有可用网卡时回退到 `127.0.0.1`。页面负责渲染二维码、说明扫码客户端并在过期后换码，而不是把平台图片地址直接暴露给用户；五个来源的页面均支持各自官方手机号验证码登录。千问、Kimi 和腾讯元宝页面只显示固定 `+86` 手机号和验证码输入；Kimi 发送短信前使用官方网易易盾验证，腾讯元宝使用官方腾讯验证码。短信与登录接口均由 Lua 内核调用，宿主不实现平台协议；元宝宿主只按 Lua 状态要求为每次受保护请求刷新 QIMEI 安全头。重复登录会替换未完成任务，但只在新登录成功后原子覆盖旧凭证；页面关闭、宿主取消或进程停止都会进入 `login.cancel` 并释放服务。

## AI 来源

`providers.lua` 是唯一来源目录；宿主不得硬编码清单。当前包含 DeepSeek、豆包、通义千问、Kimi、腾讯元宝。

- 各来源实现真实登录、对话与其已支持的会话操作。
- 元宝受保护请求接收宿主按请求生成的 QIMEI 安全头，Lua 只接受白名单字段；WAI 宿主在无浏览器内核的 Node 沙箱中运行元宝当前官方模块，设备状态仍通过 `security.yuanbao.get/set` 由 Lua 写入私有缓存。
- HAR 只用于离线对齐协议，不是运行时输入，不得发布或提交。
- 状态返回脱敏信息，不返回 Cookie/Token。

## 对话与 MCP

- `chat.send.message` 只含本轮用户输入，最大 20000 字节；平台上下文由远端 session/message 状态续接，禁止回灌界面历史。
- `chat.send.system_context` 是宿主提供的完整 Agent 协议和项目摘要，只在新会话或尚未初始化 Agent 时注入；`turn_context` 是当前任务需要的增量约束。运行时用 `agent_initialized` 记录协议是否已经进入远端会话，续接任意可用的云端历史后不会每条消息重复整套提示。
- DeepSeek 会话列表请求附加禁缓存参数和请求头；Kimi 通过官方 Feed、ListMessages 与 DeleteChat 接口支持会话列表、历史恢复和删除。宿主删除会话后应重新拉取列表并确认目标 ID 消失，不能只凭删除接口返回成功就向用户报告完成。
- 完整 Agent 协议只在新会话首轮注入；续接 Web 会话时复用云端记忆，只有实时状态或安装任务才增量附加本轮必需工具的单项定义。
- 每轮增量提示都包含平台无关的行动契约：模型必须区分方法咨询和实际行动请求；明确行动请求要根据当前真实平台、工具、权限和审批边界执行并验证，不能退化成教程。软件安装和卸载在此基础上另有真实包管理器执行及存在性结果门禁。
- 模型返回可明确恢复的缺 `agent` 键工具 JSON 时会安全补全；历史清理复用同一解析器，不向用户展示内部工具协议。
- 软件安装被标记为强制终端任务；包管理器执行后仍需通过目标命令路径和版本的独立检查，未验证时不得提前结束。
- 宿主规则和项目摘要放 `system_context`。历史展示必须过滤内部提示、工具结果与 Agent JSON，仅返回用户/助手正文。
- 模型返回 final 或 agent JSON；Lua 循环执行 AI → MCP → 结果 → AI，直到完成、失败、超时或取消。
- 宿主用 `mcp.register` 注册工具；无 Lua handler 时收到 `mcp.call`，执行后用 `mcp.result` 回传。迟到结果不得污染新任务。
- 文件权限、忽略目录、结果上限和执行均由宿主管理。模型应先按文件名/内容搜索，再分段读取；复杂 `rg/find/jq` 仅作补充。

### 工具任务状态机

运行时会在本轮开始时判断用户是否要求读取真实系统状态或安装软件。命中后设置 `tool_required` 和唯一的 `required_tool`；终端类任务当前要求 `terminal.execute`。处理顺序如下：

```text
用户任务
  │
  ├─ 普通问答 ───────────────> 模型正文 ──> 完成
  │
  └─ 强制工具任务 ──> 模型请求工具 ──> mcp.call
                                      │ 宿主执行并回传 mcp.result
                                      ▼
                                  模型继续判断
                                      │
                                      ├─ 仍需操作 ──> 再次调用工具
                                      └─ 已有真实证据 ──> 最终回答
```

模型第一次在未调用必需工具时直接给出结论，或只说“需要先检查、请允许我调用工具”却没有真正调用时，运行时会附加一次纠正提示并重新请求；连续漏调才终止任务，避免展示臆造的端口、进程或安装结果。包含明确绝对路径的任务会直接要求真实文件工具，路径与后续中文连写也能识别。工具已经成功执行后，后续简短追问仍可复用同一云端会话的记忆，但新的实时判断必须重新取得当时的数据。

安装任务还会记录从用户请求中识别出的目标命令；“你帮我安装”等依赖上一轮包名的简短续接同样会强制进入终端工具链，而且只有真实包管理器安装命令成功后才允许收尾，环境探测、包搜索或只展示命令均不算完成。显式识别出目标时，模型还必须独立执行 `command -v 目标 && 目标 --version`（或 `-version`），且结果退出码为 0；带 `|| echo`、分号或其他会吞掉失败码的后缀不能通过验收。Termux、Debian 等平台采用什么非交互恢复命令由宿主提示词和真实环境决定，Lua 不硬编码具体安装命令。

### 工具调用兼容与历史清理

标准工具调用是带 `type="agent"`、工具名和 `arguments` 的 JSON。对于模型偶发输出的以下确定性格式，运行时会补上缺失的 `agent` 字段：

```json
{"type":"agent","terminal.execute","arguments":{"command":"ps aux"}}
```

只有工具名唯一且只包含字母、数字、点、下划线或短横线时才允许修复；存在歧义或无法解析的内容不会执行。标准与修复后的内部工具 JSON、系统提示、MCP 结果都会从云端历史的可见消息中移除，恢复会话时只返回用户与助手正文。

Lua 负责判定工具、等待结果和推进状态机；PID、实时 stdout/stderr、进程取消与输出截断属于宿主职责。例如 WAI 收到 `mcp.call` 后在 Node 进程中执行命令并持续渲染，再把最终受限结果作为 `mcp.result` 交回 Lua。

终端宿主还可在最终展示前复查工具 JSON；若某个来源边界条件下把合法工具对象误送入回答通道，宿主通过 `chat.recover_tool` 将原任务恢复到 `waiting_tool`，执行并继续循环，而不是向用户显示内部协议。

Agent 提示包含强制完成契约：技能只提供方法，不能成为拒绝原始问题的理由；工具证据足够后必须停止探索并给出结合真实环境的完整答案。运行时保留最近 8 条、每条最多 8000 字节的工具证据；DeepSeek 在工具链末尾偶发返回空正文时会刷新消息分支并最多触发两次强制收尾，避免已经完成检查却以“没有返回正文”终止。

## 发布约束

- 仓库只放生产运行代码和必需第三方资产；不放测试、模拟服务、HAR、凭证、缓存或临时文件。
- Lua JSON 空对象/数组必须遵守 `AGENTS.md`。
- 发布由 `web_ai_agent_lib/scripts/package_runtime.sh` 编译并打包，再通过 `update_service/scripts/publish_release.sh` 上传到更新服务器，不使用 Git 仓库分发 Lua 内核。

## 验证与集成检查

本仓库是被 C 内核加载的生产运行目录，不单独发布模拟宿主。修改对话、登录或 MCP 状态机后，至少应完成：Lua 源码语法/加载检查、通过 `web_ai_agent_lib` 的 runtime 冒烟，以及在一个真实宿主中验证对应事件闭环。WAI 可使用：

单独检出本仓库时，可先运行不依赖其他源码仓库的 Lua 加载与版本接口检查：

```bash
./scripts/check.sh
```

```bash
cd /你安装WAI的位置
./scripts/check-env.sh
npm run check
```

真实来源登录和对话测试需要已授权账号；验证日志和缓存仍应留在宿主的私有数据目录，不得提交到本仓库。