Initial Dever 0.0.1

skills/references/external-lib.md

@@ -0,0 +1,46 @@
+# 外部库接入
+
+[external-lib 项目](../assets/examples/external-lib/) 使用现成 Markdown 库，App 调用 Port，外部程序实现 render。示例可运行 fake 测试，真实依赖与运行资源另行准备。生成 HTML 未清洗，展示不可信输入前需处理。
+
+| 生态 | external 声明 | lib 声明 | setting.json 的 lib 项 |
+| --- | --- | --- | --- |
+| Python | external pip "python/render.py" | markdown@3.8.2 | pip:markdown@3.8.2 |
+| JavaScript | external npm "javascript/render.mjs" | marked@15.0.12 | npm:marked@15.0.12 |
+| Go | external go "go/render.go" | github.com/yuin/goldmark@v1.7.8 | go:github.com/yuin/goldmark@v1.7.8 |
+
+源码：[Adapter](../assets/examples/external-lib/module/document/markup/adapter.dever)
+
+```dever
+external pip "python/render.py" {
+  lib "markdown@3.8.2"
+}
+```
+
+切换生态时同步 Adapter 和配置，Port、App 和测试的接口不变。版本是示例固定输入，各库的 Markdown 方言和换行可能不同。
+
+## 处理函数
+
+| 生态 | 导出签名 |
+| --- | --- |
+| Python | async def render(payload, setting) |
+| JavaScript | async function render(payload, setting, signal) |
+| Go | func Render(context.Context, any, any) (any, error) |
+
+Go 声明 package main，入口由工具生成。操作名按单词转 UpperCamelCase。Worker 接口定义和运行器由编译器按 Port 生成，不手写协议、hash 或操作注册表。
+
+输入为 `{"source":"# Report"}`，成功输出为 `{"html":"..."}`。单输出也须保留命名字段；没有 setting 时传 null/nil。
+
+业务拒绝使用 SDK BusinessError，identity 为 document.markup.RenderResult.Rejected，payload 为 `{"message":"..."}`。其他异常为运行失败。stdout 专用于协议，日志写 stderr；处理函数须响应各生态的取消信号。
+
+配置通过 Adapter setting 传入。文件、网络、进程或 GPU 用 allow 声明，实际权限由运行环境管理；Worker 不是不可信代码沙箱。
+
+## 验证与运行
+
+```sh
+dever check <root>
+dever test <root> --filter document.markup --timeout-ms 5000
+```
+
+rendered/rejected 分别验证成功和拒绝，每例独立 fake。真实运行需可信的 dever.lock、目标运行时及 Worker 资源；当前 CLI 只提供 lib install 恢复已有锁，不提供 add/update 解析新锁。
+
+准备好资源后运行 `dever run <root> -- document.markup.render '{"source":"# Report"}'`。fake 不验证第三方库的实际输出或跨架构运行。