Initial Dever 0.0.1

sdk/README.md

@@ -0,0 +1,53 @@
+# 外部 Worker SDK
+
+通过 Port 和外部 Adapter，把 Python、JavaScript、Go 或 C/C++ 库接入 Dever。Worker 在独立进程中运行，Dever 负责通信、取消和回收。
+
+应用接入先看 [完整示例](../skills/references/external-lib.md)，无需手写协议或操作注册表。
+
+## 处理函数
+
+| 语言 | 接口 |
+| --- | --- |
+| Python | 异步函数，使用 `Worker.from_manifest(manifest, handlers)` |
+| JavaScript | 接收 AbortSignal，使用 `Worker.fromManifest(manifest, handlers)` |
+| Go | 接收 context.Context，使用 `NewFromManifest` 和 `RegisterHandlers` |
+| C/C++ | 同步 `dever_ffi_handler` 回调，使用 `dever_ffi_serve` |
+
+函数名对应 Port 操作名，输入输出及业务错误由编译器生成的接口定义检查。结果按命名字段返回 JSON；业务拒绝使用已声明的 BusinessError。stdout 只用于协议，日志写 stderr。
+
+Python/JavaScript/Go 处理函数须响应取消信号。一秒内不退出会使 Worker 停止接收新调用；已取消调用的结果不再交付。自行调用 Go Serve 时，还须解除自己提供的 Reader 阻塞。
+
+Worker 调用没有统一的固定倒计时，启动握手、写入和停止清理各自有限时。Worker 不是不可信代码沙箱，文件、网络和设备权限由运行环境管理。
+
+## 接口与运行资源
+
+编译器通过 `ExternalWorkerContract::sdk_manifest()` 生成接口定义，SDK 在 hello 时核对身份并读取配置。通信为 4 字节大端长度加 UTF-8 JSON；示例中的 fixture-schema-v1 仅用于测试。
+
+运行时使用锁定的目标解释器、依赖和 Worker 资源，不借用宿主 PATH。Python 使用 `-I -S -B` 启动，再加载打包的 SDK、Adapter 和依赖。
+
+`dever lib install <project>` 恢复已有锁；当前 CLI 不提供 Lib add/update。源码构建及目标运行资源由发行方准备，不能用本机 Python/Node/Go 代替缺失资源。
+
+## C/C++
+
+使用 `external exec "worker/native" {}`，shim 包含 `c/dever_ffi.h` 并与 `c/dever_ffi.c` 编译为目标平台程序。
+
+- ABI 为 DEVER_FFI_ABI_V1。open 初始化一次，invoke 串行处理操作，close 释放状态。
+- operation、setting 和 payload 是当前回调借用的字节或 JSON，不保证 NUL 结尾，不得保留指针。
+- 输出缓冲由 SDK 分配。只写容量以内的数据并设置 size，不替换或释放缓冲。
+- DEVER_FFI_OK 返回结果 JSON；DEVER_FFI_ERROR 返回声明错误及 payload；其他状态作为运行故障。
+- C++ 异常不得跨 C ABI。同步原生调用不保证协作取消，宽限结束后由进程监管终止。
+
+原生库须与目标系统 ABI 匹配。它们运行在 Worker 中，不直接加载进 Dever 主进程。
+
+## 验证
+
+从仓库根执行，指定已准备好的工具绝对路径：
+
+```sh
+python3 -B test/external-sdk/check.py --python /path/to/python3 --node /path/to/node --go /path/to/go
+python3 -B test/external-sdk/test_c_ffi.py --cc /path/to/cc
+```
+
+未提供的语言会报告 unavailable。SDK 测试验证真实通信和类型，普通应用测试使用 Port fake；后者不证明第三方库可以实际运行。
+
+`sdk/python-runtime.py` 可从锁定摘要的 Python Build Standalone 归档准备解释器输入，参数见 `--help`；它不下载资源。脚本验证目标 ELF、glibc、模块及移动后的解释器，并保留许可证，默认 glibc 上限为 2.17。