63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# Design
|
||
|
||
## Architecture
|
||
|
||
```text
|
||
App -> typed Port -> selected Adapter -> Worker supervisor -> Component Protocol -> Lib
|
||
```
|
||
|
||
Port 保持现有 compiler-owned Function ID 和闭合实现集合。外部 Adapter 是新的实现种类，不是新业务调用层；checker 从 Port 合同合成 Worker operation schema，并把显式 capability 纳入既有 effect/dependency 分析。
|
||
|
||
## Source Contract
|
||
|
||
建议外部 Adapter 保持现有 topic identity：
|
||
|
||
```text
|
||
module/ai/embedding/port.dever
|
||
module/ai/embedding/adapter/python.dever
|
||
module/ai/embedding/adapter/python/main.py
|
||
```
|
||
|
||
```dever
|
||
setting {
|
||
model: Text
|
||
}
|
||
|
||
external pip "python/main.py" {
|
||
lib "sentence-transformers@3.3.1"
|
||
allow gpu
|
||
}
|
||
```
|
||
|
||
一个外部 Adapter 文件恰好有一个 `external` 声明，可选现有 typed `setting`，没有 Dever operation body/helper。它由编译器合成该 Port 的全部实现，Worker handshake 必须提供全部 operation。入口必须是所属 Adapter 目录内的规范化相对路径。
|
||
|
||
## Component Protocol
|
||
|
||
传输使用专用双向管道和四字节大端长度分帧 JSON，复用现有 wire codec 的 16 MiB、64 层、65536 值预算。stderr 只承载日志，不能进入协议。
|
||
|
||
消息固定为：`hello/ready/call/result/error/cancel/health/shutdown`。每次握手包含协议版本、Port identity、schema hash、Adapter identity 和 capability 集；不匹配立即结束 Worker。请求 ID 在单 Worker 生命周期内唯一，输出必须属于当前未完成请求。
|
||
|
||
## Worker Ownership
|
||
|
||
每个选中外部 Adapter 启动一个长驻 Worker 和有界请求队列。supervisor 属于现有应用 Scope；入口启动完成后才允许用户代码，关闭时停止 admission、取消未完成请求、发送 shutdown 并在期限内 join/kill。崩溃使当前请求 fault；后续调用可以受限重启，但绝不重放已发送请求。
|
||
|
||
## Lib Resolution
|
||
|
||
生态 resolver 共用请求/锁模型：requested spec -> exact artifacts -> content hashes -> runtime pack -> target set。resolver 只能在显式 `lib add/update` 联网，结果写 canonical `dever.lock` 并原子替换。项目命令只验证 lock 与缓存，不重新解析版本。
|
||
|
||
机器级 cache 和 runtime pack 消费 `09-28-shared-toolchain` 的全局工具链合同；在该合同完成前，生态子任务只使用测试自有 fixture store，不新增临时用户缓存协议。
|
||
|
||
## Build Packaging
|
||
|
||
每个 Adapter 生成目标专用 Worker artifact。`build` 将所有运行时可选 Adapter、runtime pack、lock manifest 和摘要作为只读资源嵌入应用。首次使用时写入 `data/cache/lib/<digest>` 的私有 staging，校验后原子发布；主程序只执行匹配 manifest 的文件。
|
||
|
||
## Extension Boundary
|
||
|
||
新增生态只实现四个固定面：spec parser、resolver、runtime/build packager、SDK。它不能扩展语法、Port 协议、业务类型系统、setting 来源或进程生命周期。
|
||
|
||
## Dependencies
|
||
|
||
- 通用协议子任务可以先实现和验证。
|
||
- 生态解析依赖机器级共享工具链目录/缓存合同。
|
||
- 生产自包含打包依赖父发行任务提供可分发 runtime/target pack；本地 fixture 可以先验证封装格式。
|