快速开始
简介
KossJS 是一个高性能的嵌入式 JavaScript 运行时引擎，原生支持 HTTP/HTTPS 下载（Fetch API）和 Node.js 标准库模块。KossJS 采用 Rust 语言编写，核心逻辑编译为动态链接库 (DLL/SO/DYLIB)，可供 Python、C++、C#、TypeScript/Node.js、Java/Kotlin 等多种语言调用。
本文档将指导您如何在 Python 项目中快速集成和使用 KossJS。
开源协议
本项目采用 GNU AGPL v3.0 协议并附带 TT23XR Studio 第 7 节附加权限《独立模块闭源组合例外》开源。
安装指南
1. 系统要求
- 操作系统: Windows (x64), Linux (Ubuntu 22.04+), macOS, Android, iOS, 鸿蒙
- Python 版本: Python 3.11 及以上
- 依赖项: 不需要额外安装 Python 依赖库，通过 ctypes 直接调用内核
2. 获取内核文件
动态链接库文件：
- Windows: kossjs.dll
- Linux: kossjs.so
- macOS: kossjs.dylib
3. 获取 Python 接口封装
为了简化调用，官方提供了封装好的 Python 接口文件 kossjs_interface.py。
- 下载 kossjs_interface.py
- 将 内核文件 和 kossjs_interface.py 放置在您的 Python 项目根目录下
基本用法
初始化与执行
首先，导入模块并创建实例。
`python from kossjs_interface import KossJS
1. 创建实例（stable=True，生产模式）
koss = KossJS()
2. 执行 JavaScript 代码
result = koss.eval("1 + 2") print(result) # 输出: 3
3. 使用更复杂的代码
code = """ const sum = (a, b) => a + b; sum(10, 20); """ result = koss.eval(code) print(result) # 输出: 30
4. 设置全局变量
koss.set_global("myVar", "Hello from Python") result = koss.eval("myVar") print(result) # 输出: Hello from Python
5. 销毁实例
koss.destroy() `
使用 Fetch API
KossJS 内置了原生 Fetch API 支持。异步代码使用 un_async() 执行：
`python from kossjs_interface import KossJS
koss = KossJS()
使用 run_async() 处理异步 fetch
result = koss.run_async(''' (async () => { try { const response = await fetch("https://jsonplaceholder.typicode.com/todos/1"); const data = await response.json(); return JSON.stringify(data); } catch (error) { return "Error: " + error.message; } })(); ''', timeout_ms=30000) print(result)
koss.destroy() `
运行 JavaScript 文件
`python from kossjs_interface import KossJS
koss = KossJS()
运行 .js 文件
result = koss.run_file("./script.js") print(result)
运行 ES Module 文件
result = koss.run_module("./module.mjs") print(result)
koss.destroy() `
注册 Native 函数
可以将 Python 函数注册为 JavaScript 可调用的函数：
`python from kossjs_interface import KossJS, JsError
def add(a, b): return str(int(a) + int(b))
koss = KossJS()
注册 Python 函数
koss.register_function("add", add)
在 JavaScript 中调用
result = koss.eval("add(10, 20)") print(result) # 输出: 30
koss.destroy() `
使用上下文管理器
`python from kossjs_interface import KossJS
使用上下文管理器自动管理资源
with KossJS() as koss: result = koss.eval("'Hello ' + 'World'") print(result) # 输出: Hello World
自动销毁
`
KossJS 的特性
安全与沙箱
KossJS 支持通过 28 个细粒度能力位精确控制实例权限，以及三层安全机制（能力位 + 审核掩码 + 审核回调）：
`python from kossjs_interface import KossJS
沙箱模式：纯计算，禁止所有 IO
with KossJS(capabilities=KossJS.KOSS_CAP_SANDBOX) as koss: result = koss.eval("1 + 1") print(result) # 正常工作
只允许网络 + 加密
with KossJS(capabilities=KossJS.KOSS_CAP_ALL_NET | KossJS.KOSS_CAP_ALL_CRYPTO) as koss: result = koss.run_async(''' (async () => { const r = await fetch("https://api.github.com/users/github"); const d = await r.json(); return d.login; })(); ''') `
稳定模式（stable）
stable 参数控制实例的生产就绪模式：
`python from kossjs_interface import KossJS
生产模式（默认，禁用 FFI 和 Worker）
koss = KossJS() print(koss.is_stable) # True
开发模式（启用所有功能）
koss_dev = KossJS(stable=False) print(koss_dev.is_stable) # False `
详见 安全与沙箱指南。
TIP
stable 模式下 FFI 和 Worker 被禁用？查看 stable 模式替代方案 了解如何在生产环境中实现相同功能。
高性能
- Rust 实现：极低的内存占用
- 极短 GC 停顿：Rust 侧无 GC，JS 引擎 GC 停顿极短
- 快速启动：实例创建开销极低
完整 JS 支持
- ES2022：最新的 ECMAScript 支持
- ES Modules：原生 import/export 支持
- Async/Await：异步编程支持
内置模块
- Fetch API：原生 HTTP 请求
- Node.js 兼容：标准库模块（assert、buffer、crypto、events、http、net、stream、url、zlib 等）
- Buffer：Node.js 兼容的 Buffer 实现
- Path/URL/Querystring：完整的路径和 URL 处理
FFI（Foreign Function Interface）
- Senri FFI：从 JS 调用 native C 库
- N-API 兼容：加载 .node 原生插件
- process.dlopen：动态库加载
下一步
- 了解 API 详解 以掌握更多高级功能
- 安全与沙箱指南 了解权限控制
- Python 接口使用 - Python 开发指南