core/.trellis/tasks/09-29-external-libs/prd.md

Dever 外部 Lib 生态

Goal

让 Dever Package 通过现有 Port/Adapter 边界安全复用 PyPI、npm、Go Modules 及后续其它语言生态。用户统一使用 dever lib 管理依赖，dever run/build 自动管理 Worker；业务源码不直接调用外语函数，也不接触语言工具链、环境变量或进程协议。

Definitions

• Package：Dever 组件的发行单位，包含 .dever 业务源码并接受完整静态检查。
• Lib：PyPI、npm、Go Modules 等外部生态依赖。
• Adapter：Port 与 Lib 之间唯一合法的桥接层。
• Worker：运行外部 Adapter 的隔离进程，不是用户可调用的业务层。

Requirements

Language Boundary

• 外部 Adapter 继续属于 module/<component>/<domain>/adapter，完整实现同领域一个 Port。
• App 只调用 Port；Domain、Model、API、Job 不直接调用 Lib、Worker 或外部 SDK。
• port.dever 仍是输入、输出、failure、effect 和 schema 的唯一来源；不得从 Python annotation、TypeScript 类型或 Go 接口反向定义业务合同。
• 外部 Adapter 使用严格的 external <ecosystem> <entry> 声明，可包含 Lib 与 capability 声明；禁止任意 shell/build 命令。
• 普通 Dever Adapter、测试 Port fake 与现有运行时选择合同保持不变。

Protocol And Lifecycle

• 所有语言共用一个版本化 Dever Component Protocol，而不是在编译器中增加 python_call、go_call、js_call 特例。
• 协议支持 handshake、schema identity、typed setting、call、result/error、cancel、health 和 shutdown。
• Worker 长驻并由结构化生命周期拥有；启动失败、崩溃、超时、取消和关闭均有界，不产生 detached 进程。
• 业务错误只能返回 Port 声明的 error variant；协议破坏、进程崩溃和非法输出成为安全 runtime fault，不自动重试。

Dependency Management

• 用户命令为 dever lib add/list/update/remove/doctor；生态使用 pip:、npm:、go: 等明确前缀。
• 解析结果写入编译器生成的项目根 dever.lock，记录精确版本、传递依赖、内容摘要、runtime、目标平台和 Port schema identity。
• dever.lock 是可提交、不可手改的构建输入，不替代只负责部署配置和 Secret 的 config/setting.json。
• 只有显式 lib add/update 可以联网；check/test/run/build 默认离线且不得从用户 PATH 或环境变量选择语言 runtime。
• 首批正式生态是 exec、pip、npm 和 go；Maven、NuGet、Composer、Gem 通过同一扩展合同后续增加，不修改语言核心和协议。

Security And Capabilities

• 外部源码不受 Dever 内部静态检查，因此默认无网络、项目外文件、子进程、设备和 GPU 权限。
• Adapter 必须显式声明所需 capability；声明参与 Port effect 的保守分析，并由 Worker sandbox 执行。
• Worker 只接收当前 Adapter 的 typed setting，不读取完整 setting.json；Secret 不进入日志、协议诊断或缓存身份明文。
• 安装脚本、路径、符号链接、归档解包和原生产物必须经过边界、摘要和所有权校验。

Run, Build And Package

• dever run 从机器级 Dever 缓存准备并监督选中的 Worker，不要求用户手动启动服务。
• dever build 把所有可运行时选择的外部 Adapter、runtime 与锁定依赖封装进自包含应用；目标机器不需要 Python、Node、Go 或包管理器。
• 嵌入资源以内容摘要验证后释放到应用 data/cache/lib，不覆盖项目源码、配置或用户文件。
• Dever Package 可以携带外部 Adapter 声明；普通使用者只执行 dever package add，项目解析时把传递 Lib 统一锁定。
• 不同 Adapter 的依赖环境隔离，允许同一外部包的不同版本共存；机器缓存按内容去重。

Acceptance Criteria

• 同一个 Port 可以分别由 Dever、exec、Python、JavaScript 和 Go Adapter 实现，App 调用代码不变。
• 协议 schema、operation、输入、输出或 error 不匹配在用户业务代码执行前失败。
• Worker 崩溃、取消、超时和主程序关闭不会遗留进程或把半条响应当成功结果。
• lib add/update 产生确定性 lock；断网 check/run/build 使用相同 lock 和机器缓存成功，缺失依赖明确失败且不隐式联网。
• Python、Node 和 Go 组件在目标机器没有对应系统 runtime/toolchain 时仍可由构建产物运行。
• 未声明 capability 的网络、文件、进程和设备访问被拒绝；Secret 与其他项目路径不出现在诊断或状态输出。
• 一个 Dever Package 可以封装外部 Lib，另一个项目只安装该 Package 即可构建和运行。
• 新增第四种生态只实现 resolver/runtime pack/SDK，不修改 Port、Component Protocol 或 App 调用规则。

Out Of Scope

• FFI、动态库加载和同进程外语解释器。
• 自动把任意第三方函数、类或对象模型暴露成 Dever API；普通生态库仍需要薄 Adapter bridge。
• 云端编译、源码上传或运行时联网安装。
• 外部 Adapter 热切换、请求级实现选择和无约束自动重试。
• 修改现有 Dever Package/Component/Domain 的业务命名和调用规则。

Child Deliverables

1. 09-29-external-lib-protocol：语言合同、统一协议、通用 exec Worker 和生命周期。
2. 09-29-external-lib-ecosystems：dever lib、dever.lock、共享缓存及 pip/npm/go resolver 和 SDK。
3. 09-29-external-lib-packaging：run/build 自包含打包与 Dever Package 传递依赖。