Effect 4.0.5 里怎么知道一个 API 是不是 unstable？

你在 v4 beta 里写过 effect/unstable/... 的 import，升到 4.0.5 之后发现这些路径没了，effect/http、effect/rpc、effect/sql、effect/ai 直接可用，于是很容易以为它们都稳定了。

**不能这么以为。4.0.5 里稳定性写在每个导出的 JSDoc 标签上：@stability stable、@stability unstable、@stability experimental，路径里没有 unstable，不等于它稳定。**HTTP、RPC、SQL、AI 这些模块里，大部分导出仍然带着 unstable 标签。

这样设计的好处是某个 API 晋升为稳定时，所有用户不用改 import。代价是你必须靠工具或名单才能看见它。下面讲怎么让这件事可见，以及版本怎么固定。如果你想先了解团队约定整体怎么分层管理，可以看 Effect 团队约定该交给机器检查，还是交给人？。

稳定性标签长什么样？

三个取值：@stability stable、@stability unstable、@stability experimental，写在导出的 JSDoc 里。beta 阶段的做法是把不稳定模块放在 effect/unstable/* 下，路径本身就是警告；4.0.5 里这条路径已经不存在。标签的机制与 4.0.5 里 unstable 模块的清单，见 Effect v4 的稳定性标注。

怎么让 unstable 的使用被看见？

默认让工具对 unstable 与 experimental 的 API 报警告，团队里每个用法都会被看见。据 @effect/tsgo 的 README，language service 里相应的诊断是 unstableApiUsage 与 experimentalApiUsage，并支持放行名单。

对决定接受风险的模块，在放行名单里显式写下来。这份名单就是「我们依赖的 unstable 清单」，升级前逐项对照变更记录。放行的粒度越小越好：放行单个导出，而不是整个模块。

依赖 unstable 模块时，版本该怎么写？

一个 unstable 模块在小版本里就可能有破坏性变更，所以依赖它的项目应该固定到精确版本，不用 ^。升级当成一次有计划的动作：读变更记录，对照放行名单，跑完类型检查与测试再合入。

相反，如果项目只用 stable 的 API，常规的语义化版本范围就足够了。

发布库的时候要注意什么？

如果你发布的是库，要留意公开类型里是否暴露了稳定性更低的类型，否则你的使用者间接依赖了它，你的版本承诺就悬空了。

项目里出现 0.x 的 @effect/* 包是怎么回事？

一个 v4 项目里出现了 0.x 线的 @effect/* 包，几乎总是迁移没做干净的信号，因为那些包提供的 API 现在已经并进了 effect 本体。这个判断是机械可证的，看 package.json 就够了。迁移相关见 Effect v3 到 v4 迁移。

本文基于 Effect 4.0.5。没有任何内容在本地运行过。诊断名 unstableApiUsage、experimentalApiUsage 与放行名单取自 @effect/tsgo 的 README，没有逐一运行验证，使用前请以你安装的版本为准；「大部分仍带 unstable 标签」的判断同样没有逐个导出核对。