KossJS

Appearance

KossJS 社区 FAQ ​

编者注：本文档整理自 KossJS 作者跟部分有意愿使用 KossJS 的开发者在群聊中的发言，旨在帮助社区用户更清晰地理解项目的设计边界、维护策略和推荐用法。内容已被作者明确允许。

关于这份 FAQ ​

官方文档介绍的是 KossJS “设计成什么样” 以及 “如何使用”，这份 FAQ 补充的是作者 “实际维护中怎么想”。两者不冲突，建议配合阅读。

1. 项目现状与代码质量 ​

Q1：KossJS 的代码是纯手工写的吗？我可以信任它吗？ ​

A：代码主要由 AI 辅助生成，作者本人会进行部分代码的审查，但作者不擅长 Rust（能看懂部分但不会修改，也无法确定 Rust 代码是否正确）。因此：

  • JS 层（src/js_shims/）和 Python 测试：作者完全能审，可信度较高。
  • Rust 胶水层（src/runtime.rs、src/sandbox.rs、src/module_loader.rs、src/resolver.rs、src/_senri_ffi/ 等）：作者看不太懂，可能存在 AI 生成的边界错误，欢迎社区 Rust 开发者帮忙 Review。

Q2：现在能上生产环境吗？ ​

A：不建议。当前版本（0.1.0-dev.x）是开发预览版，仅供测试尝鲜。建议等到正式发布的版本，且 Rust 胶水层经过社区充分 Review 后再用于生产。

2. FFI（_senri_ffi）与原生调用 ​

Q3：KossJS 内置的 _senri_ffi 能在桌面端用吗？ ​

A：不推荐。虽然它能用，但：

  • 依赖 libffi，跨平台（尤其不同 glibc 版本）调试极其困难。
  • 一旦出问题（段错误、堆栈撕裂），作者因不熟 Rust 和 libffi 内部机制，无法修复。
  • 作者建议：在宿主层（Python/C++/C#）直接调用动态库，然后通过 koss_register_function 绑定给 JS。

Q4：_senri_ffi 在移动端（Android/iOS/HarmonyOS）支持吗？ ​

A：不支持。移动端加载外部动态库本身就很麻烦（iOS 签名限制、Android ABI 匹配），且作者没有足够的移动端测试环境。移动端请务必走“宿主封装 + 注册函数”的路线。

Q5：如果我非要开 stable=False 用 FFI，出了问题怎么办？ ​

A：作者会看 Issue，但大概率修不了。 因为 Rust + libffi 的调试堆栈信息极其模糊，作者缺乏定位能力。强烈建议放弃，走宿主封装。

3. Worker（多线程） ​

Q6：KossJS 的 Worker 功能稳定吗？ ​

A：测试覆盖不全，不稳定。 作者明确将其排除在 stable 模式之外。除非你非常熟悉 Rust 多线程和 Boa 的 Send/Sync 约束，否则不要碰。

Q7：为什么 Worker 和 FFI 被强制放在 stable=False 里？ ​

A：这是作者的防御性维护策略：

  1. 这两个功能技术风险高，作者无法兜底。
  2. 如果放 stable=True，用户用了出问题会涌来大量无效 Issue（比如“我调了 C 库崩了，快修”）。
  3. 放在 stable=False 是为了明确告诉用户：用这两个功能代表你是高级用户，出了问题请先审查自己的代码，再来找项目。

4. 安全模型（Capability 与 Audit） ​

Q8：能力位（Capability）是怎么工作的？是运行时检查吗？ ​

A：不是运行时检查，是物理剔除。

  • 创建实例时，未被授予的能力对应的原生函数根本不会注册到 JS 引擎的 Context 中。
  • 如果 JS 代码尝试调用，会直接报 TypeError: xxx is not a function，不会触发任何“权限不足”的运行时开销。
  • 性能零损耗，且无法通过原型链篡改绕过。

Q9：能力位未定义的能力，会触发审核回调（Audit Callback）吗？ ​

A：不会。 因为函数根本不存在，审核回调找不到拦截目标。审核回调只作用于 “已被能力位授予，但额外开启了审核掩码” 的 API。

Q10：我通过 koss_register_function 注入的宿主函数，受能力位控制吗？ ​

A：不受。 因为能力位只在初始化时控制“哪些 Rust 原生绑定要挂载”。宿主注入是实例创建后的动态行为，如果能力位能事后剔除宿主函数，那这个注入功能本身就是矛盾的。

注意：虽然不受能力位控制，但审核回调（Audit Callback）仍然可以对宿主注入的函数生效（例如审核参数路径是否在安全目录内）。你可以利用审核回调实现“读取特定文件”等精细权限控制。

5. 平台支持 ​

Q11：KossJS 在桌面端（Windows/Linux/macOS）表现如何？ ​

A：相对最稳定。 作者在这三个平台有测试环境，JS Shim 层和基础 C ABI 已经过充分验证。如果只使用 stable=True 模式（不碰 FFI/Worker），可以作为脚本引擎集成。

Q12：Android 和 HarmonyOS 能用吗？ ​

A：历史版本（dev.5）测试过，最新版本尚未测试。 可能存在回归风险，但架构上可行。欢迎有设备的开发者帮忙测试并反馈结果。

Q13：iOS 能上 App Store 吗？ ​

A：不能，且作者没打算支持。

  • 作者明确表示 iOS 动态库仅用于内部测试使用。
  • 如果企业内部分发（不需上架）可以自行签名折腾；但面向公众的 App Store 应用，请勿依赖 KossJS。

6. 贡献与社区 ​

Q14：我不会 Rust，能帮上什么忙？ ​

A：能！ 作者最缺的反而是 JavaScript 和 Python 方向的贡献者：

  • 审查 src/js_shims/ 里的 Node/Bun/Deno 兼容层代码逻辑。
  • 编写或完善 kossjs_interface.py 的 Python 测试用例。
  • 补充文档和示例代码。

Q15：我懂 Rust，想帮忙，从哪里开始？ ​

A：作者原话：“不清楚”
以下是基于当前源码（dev.9）的社区建议审查重点：

  • src/runtime.rs

    • 所有 extern "C" 导出的 C ABI 函数（如 koss_eval、koss_run_async 等）目前没有 catch_unwind 保护，Rust panic 会直接跨 FFI 边界导致宿主进程崩溃。建议在每一个导出函数入口处添加 std::panic::catch_unwind 并返回合理的错误结果。
    • Boa 引擎与 Tokio 异步运行时的桥接逻辑（KossEventLoop::process_io_results 中的 block_on、spawn 等），需要检查是否存在嵌套运行时阻塞或死锁风险。

  • src/sandbox.rs

    • 能力位（Capability）和审核回调（Audit）的实现逻辑，注意审核回调是同步的，若用户回调执行耗时操作会阻塞事件循环，文档中应明确警告。

  • src/module_loader.rs 与 src/resolver.rs

    • 模块加载和路径解析涉及文件系统访问，需检查路径遍历（Path Traversal）漏洞，确保 normalize_path 能正确防止 .. 逃逸。

  • src/_senri_ffi/ 目录

    • FFI 实现（桌面端可用），但作者明确不推荐使用，若需要可审查其内存安全和跨平台兼容性。

7. 其他 ​

Q16：作者不懂 Rust 为什么要使用 Rust ？ ​

A：作者本人并不熟悉系统级编程语言（如 C、C++、Rust），但项目本身需要在宿主程序中嵌入一个现代的 JavaScript 运行时。经过技术选型，Rust 生态下的 Boa 引擎在性能、跨平台支持以及通过 C ABI 暴露接口的便利性上，最符合项目的技术目标。

该项目最初是为了满足作者自身的实际开发需求而创建的。选择开源，是“顺手的事情”，同时让项目真正变得对社区可用。

Q17：本项目的许可证解读是什么？ ​

A：简单来说：用官方发布的二进制库，闭源商用是允许的。

KossJS 用的是 AGPL v3.0，但作者加了一条 “独立模块闭源组合例外”（附加权限）。只要满足三个条件，你的业务代码就不用开源：

  1. 用官方发布的库：必须用作者官方发布的 .dll/.so/.dylib，不能自己编译。
  2. 不改官方库：官方发布的二进制文件中的二进制内容并未被修改。
  3. 加一句声明：在你的软件“关于”页面、README 或用户手册等用户可看到的界面里加一句：

    “本软件使用了 KossJS ，遵循 GNU AGPL v3.0 协议及 TT23XR Studio 的附加权限。”

什么情况下必须开源？ ​

你的操作后果
用官方发布的二进制库，闭源集成合规，只需署名
修改了 KossJS 源代码必须把你自己修改后的代码以 AGPL 开源
自己从源码编译（即使没改代码）必须遵守完整的 AGPL v3.0
把 KossJS 源码直接放进你的项目必须遵守完整的 AGPL v3.0

额外注意 ​

  • 第三方库不受影响：KossJS 依赖的 Boa、Tokio 等库有自己的许可证（MIT、Apache 等），按它们的规矩来。
  • 商业许可：作者目前不卖商业许可。有特殊需求得等作者成年后再联系。
  • 静态链接：有争议，建议用动态链接，别给自己找麻烦。

一句话总结： ​

用官方发布的 .dll/.so/.dylib，加一句声明，就可以闭源商用

8. 总结性建议 ​

使用场景推荐做法
内部工具、原型开发、学习研究直接使用 stable=True 模式，JS 逻辑和标准 Shim 层是可以使用的。
生产环境（桌面端）仅限 stable=True，且避开 FFI/Worker。原生能力走宿主封装。且标准 Shim 层可能存在问题。
生产环境（移动端/App Store）不建议。Android 需自行验证回归，iOS 直接放弃。
调用 C/C++ 动态库不用 _senri_ffi。在宿主层封装好，用 register_function 注入。

最后，作者想对大家说：“我知道这项目有很多不完美的地方，但所有源码均开源。欢迎会 Rust 的大佬来修，也欢迎所有人来提 Issues 和 PR。开源的意义就在于我们一起把它变好。”