docs(runtime): document subpath-only public API and shared composition entry - #5200
Conversation
…n entry
- State that the public API is the declared package.json exports subpaths;
the package root is not exported (import('@maka/runtime') fails with
ERR_PACKAGE_PATH_NOT_EXPORTED)
- Add explicit subpath import examples for SessionManager, BackendRegistry,
AiSdkBackend, and buildBuiltinTools
- Point contributors to the shared Runtime Host execution composition
instead of the stale apps/desktop/src/main/main.ts entry
Fixes apache#5141
There was a problem hiding this comment.
PR 5200 Review
结论
APPROVE
Docs-only：packages/runtime/README.md 的 root-barrel 误述已修正，补 subpath 导入示例，并把 composition 指针换到 Runtime Host。是四个竞争 PR 里改动最克制的一个。
发现
[P3] 与 #5142、#5165 修同一缺陷、同一文件（issue #5141），三者不能同时合并
- 文件: packages/runtime/README.md
- 问题：本 PR、#5142、#5165 都只改
packages/runtime/README.md的 "Public seam" 段，修的是同一个 root-barrel 误述（同一 issue #5141）。三个 PR 不能同时合并，后合者会因同段改动产生 diff 冲突。 - 建议：维护者三选一合并，其余关闭即可。本 PR 改动最小、最贴近奥卡姆剃刀，若求最小 diff 可优先它。纯流程提示，不影响技术正确性。
- 另：PR 描述称"follow the cross-package README convention (packages/eval, packages/computer-use)"，但
eval/README.md对同 packages 下文件用单层../，computer-use的../../是因其指向 repo 根docs/。本 PR 指向同 packages 下的 runtime-host，却用了../../packages/...（多绕一层）。两种写法都能正确解析，仅与"同 packages 引用用../"的惯例略不一致，若想统一可改../runtime-host/src/server/execution-composition.ts（与 #5165 一致）。可改可不改。
验证
package.json#exports无'.'键 → root 确实不导出，原文档说法确为缺陷。- 示例导入的
SessionManager/BackendRegistry（@maka/runtime/session-manager）、AiSdkBackend（@maka/runtime/ai-sdk-backend）、buildBuiltinTools（@maka/runtime/builtin-tools@196）三者均真实导出。 - 相对链接
../../packages/runtime-host/src/server/execution-composition.ts从packages/runtime/出发能正确解析到目标文件。
…e path Review feedback on apache#5200: a reference into a sibling package uses one '../' hop (packages/runtime/ -> packages/runtime-host/...), matching the convention in packages/eval's README.
|
Adopted the review suggestion: the composition link now uses the same-packages relative path ( |
me2seeks
left a comment
me2seeks
left a comment
There was a problem hiding this comment.
Maka auto review
Approved after comparing #5142, #5165, and #5200 against their latest heads. This version preserves the README structure, supplies four useful named-import examples, and clearly points Desktop contributors to the shared Runtime Host composition. The requested relative-link adjustment is present in 0427744.
Verified the package-root import rejection, declared subpaths and named source exports, the relative composition link, and the BackendRegistry/SessionManager construction sites. Diff whitespace checks pass; current CI is successful. This is documentation-only; no runtime behavior changes.
中文说明
比较三个竞争 PR 后选择本 PR：保留原文结构，提供四个常用导入示例，明确 Desktop 通过 Runtime Host 执行，并已落实相对链接建议。已核对根路径导入错误、子路径声明与命名导出、文档链接和实际组装位置；差异检查与当前 CI 通过。本次只修改文档。
2 participants
Summary
packages/runtime/README.mdadvertised two things that no longer hold onmain:packages/runtime/package.jsonexports only named subpaths, soimport('@maka/runtime')fails withERR_PACKAGE_PATH_NOT_EXPORTED.apps/desktop/src/main/main.tsas the place where Runtime is composed — but the shared execution composition now lives in the Runtime Host.Changes
package.jsonexportsmap, say explicitly that the package root is not exported, and add concrete subpath import examples (SessionManager,BackendRegistry,AiSdkBackend,buildBuiltinTools— the same subpaths the shared composition imports).packages/runtime-host/src/server/execution-composition.ts— whereBackendRegistryandSessionManagerare constructed — via a relative link, following the cross-package README convention (packages/eval,packages/computer-use).package.jsonsubpath" with the subpath-only rule.Verification
mainfrompackages/runtime:node --input-type=module -e "import('@maka/runtime')"→ERR_PACKAGE_PATH_NOT_EXPORTED("No exports main defined").session-manager.ts,ai-sdk-backend.ts,builtin-tools.ts), matching howexecution-composition.tsconsumes the package.packages/segment) — fixed and re-verified on disk.docs/archive/, versioned design docs), untouched here.Fixes #5141