Package 与入口矩阵
区分公开包、仅供仓库内部使用的能力和不可直接导入的实现入口。
先按你要完成的任务选包；通常插件作者从 @pluxel/runtime 开始，创建应用用 @pluxel/create，只有装配宿主时才直接使用 static/dynamic 包。
本页说明各包的用途和公开入口。private 和 exports 决定源码中的导入边界；实际可安装版本以 npm registry 和发布记录为准。
公开包
| Package | 用途 | 从哪里开始 |
|---|---|---|
@pluxel/create | 创建包含宿主、插件、前端和测试的示例项目 | 快速开始 |
@pluxel/context | 为独立宿主组合固定能力与惰性服务 | 组合 Context host |
@pluxel/core | 插件依赖、启动停止和资源生命周期 | Plugin 模型 |
@pluxel/runtime | Plugin、生命周期、配置、HTTP、日志和宿主共享契约 | 第一个 Plugin |
@pluxel/runtime-static | 使用固定 Plugin catalog 的宿主 | 配置插件宿主 |
@pluxel/runtime-dynamic | 插件可由固定列表和可变文件来源共同提供的宿主 | 配置插件宿主 |
@pluxel/cli | 脚手架、构建、数据库、发行物、HMR 与源码工作区命令 | CLI 与工具链 |
@pluxel/rolldown | Plugin package 与 static application 构建集成 | 开发和发布插件包 |
@pluxel/test | Vitest/Vite preset、filesystem fixture 与显式 unsafe lowering | 测试 Plugin |
@pluxel/commands | command 定义、校验、live registry 与 argv/message 参数路由 | Commands |
@pluxel/agent-tools | 可选 Agent Toolset 与 command allowlist Plugin | Agent tools |
valibot-form | Valibot 表单 metadata 与可选 Web adapter | Valibot 配置表单 |
@pluxel/auth | Workbench 与 Management API 认证 provider | Management 认证 |
@pluxel/wretch | Plugin-owned HTTP client | Wretch HTTP client |
@pluxel/fonts | 服务端字体注册与 provider | 字体 |
@pluxel/canvas | 有预算约束的服务端 Canvas、Pretext 文字准备与静态表格工具 | Canvas |
@pluxel/echarts | 服务端 ECharts 渲染 | ECharts |
@pluxel/takumi | 有预算约束的 HTML/node-tree 图片渲染 | Takumi |
@pluxel/takumi-markdown | 有预算约束的 GFM Markdown、表格与静态代码高亮图片渲染 | Markdown / Typst |
@pluxel/takumi-markdown-typst | 可选受限 Typst 数学 SVG Markdown extension | Markdown / Typst |
这些 package 未标记为 private，并声明了面向消费者的入口。消费者只从 package exports 导入；版本可用性以 registry 和 release metadata 为准。
@pluxel/runtime 还提供职责明确的 browser subpath：/web 是 Runtime session、Management Client 与 DTO；
/web/react 只提供 React Context adapter；/capnweb 提供固定 RPC object model；/workbench 提供
browser-safe Content、Direct View 和 Attachment definition；/workbench/client 提供 Shell layout/opened-handle client；
/workbench/react 提供 exact descriptor hook、host facade 和 Pane Kit。/web/react 与 /workbench/react 由宿主
提供 React singleton；internal registry、generated Bridge ABI 和 raw MF Runtime 不是第三方作者入口。
Workspace-only 能力
以下 package 标记为 private: true，不能作为普通 npm 安装依赖。只有在支持这些包的源码 workspace 中才能集成；跨仓库联调先看源码开发：
| Package | 能力 | 文档 |
|---|---|---|
@pluxel/cache | owner-scoped cache、single-flight、backend | 缓存 |
@pluxel/rates | 按 identity 计费的频率限制 | 请求频率控制 |
@pluxel/redis | Redis client、script 与 backend | Redis |
@pluxel/storage | local/remote object storage | 对象存储 |
@pluxel/otel | traces、metrics 与 exporters | OpenTelemetry |
@pluxel/package-manager | dynamic host package 管理 | Package manager |
@pluxel/pi-agent | Pi embedded engine、goal 与 subagent | Pi Agent |
仓库外项目不得把这些 package 视为可安装的公共依赖，也不得用源码相对路径绕过 package boundary。
不应成为用户入口的 package
@pluxel/runtime-dev是开发支持层。@pluxel/runtime-node是 static/dynamic launcher 共用的 Node srvx/crossws platform carrier，不是 Plugin API 或自定义 carrier SPI。@pluxel/workbench-app是组装后的应用，不是 Plugin UI SDK。@pluxel/runtime/internal*等带internal的 export 由框架自身使用，不承诺作者兼容性。
业务代码不得依赖这些实现入口。缺失的公开能力需要通过稳定 public contract 提供。
选择规则
- 写 Plugin 时从
@pluxel/runtime和一个明确的能力 package 开始。 - 装配宿主时选择 static 或 dynamic runtime，不在业务 Plugin 中依赖宿主实现。
- 测试 host 从所验证层的
@pluxel/core/test、@pluxel/runtime/test或@pluxel/runtime-static/test导入；@pluxel/test只使用/vitest、/fixtures或/unsafesubpath，不直接 new 内部 host。 - 导入路径必须存在于所安装版本的
exports，且目标 package 不能是 private。 package.json#exports与真实源码 export 是入口契约；文档必须与该契约保持一致。
最后更新于