Version

3.2.20

Reproduction link

codesandbox.io

Steps to reproduce

Reactivity API 我注意到这份文档里面并没有有关响应式API互相嵌套时的具体行为，有时候解包，有时候不解包，这很令人困惑。 只有当你看完源码才能大概知道那些行为是解包，那些行为是不解包的；

比如，当reactive里面嵌套着shallowReactive时，无法得知到底具体行为是什么? 点击例子 这时候由于reactive和shallowReactive两个API的返回类型有问题，实际上是可以正常运行的，但是typescript并不能很好推导出来正确的类型

这样的例子很容易列举出来，例如 #4732，我认为这样的TS类型和具体逻辑不一致的情况，在vue3中很容易出现。 困难的地方就是不同的响应式API可以组合的情况太多了。 所以我认为问题的根源是响应式API的具体行为不明确导致的，文档里面应该清楚描述这些API互相嵌套时的具体行为，用于指导这些类型互相嵌套时的具体行为，然后用以指引TS类型。

What is expected?

• 文档清晰描述响应式API互相嵌套时的行为
• typescript推导的类型与实际运行结果保持一致

What is actually happening?

typescript推导的类型与实际运行结果不一致

• 新版本的文档还在重写当中 see https://vue-docs-preview.netlify.app/api/reactivity-core.html 会对类型进行说明。
• 你提到的类型错误确实存在。能否重新提一个issue，尽量用英文。这样如果还有其他人遇到了类似的问题，也能找到相关的解决方案。

1. 内部的运行时行为定义是非常明确的：任何 shallow 的 ref 或者 object 都会中断 unwrapping
2. 类型定义也应该是明确的，你所举出的例子和 #4732 都属于类型的 bug (fixed by https://github.com/vuejs/vue-next/commit/20a361541cc5faffa82cbf3f2d49639a97b3b678)
3. 虽然文档也确实可以改善，但这本质上不是文档的问题，只是单纯的类型没写对。