用途：url-state 是一套面向仪表盘的 URL 查询状态处理规范，用于统一管理页面会响应的查询参数，例如标签页、过滤器、分页、深链接和演示标志。其核心要求是让这些参数经由 nuqs 的 useQueryState 或 useQueryStates 以及来自 nuqs 的解析器读写，避免直接操作历史记录或手工解析查询串。
主要能力与约束：技能明确禁止对这类状态调用 window.history.pushState 或 replaceState、手工编辑 URLSearchParams，或用 useSearchParams().get(...) 解析，因为原始写入会绕过 nuqs，使同一键上的其他 hook 数据过期，并可能被排队中的 nuqs 更新覆盖。校验应在解析器中完成而非读取后再校验：枚举用 parseAsStringLiteral，整数用 parseAsInteger，布尔用 parseAsBoolean，列表用 parseAsArrayOf，默认值用 withDefault，自定义线格式（例如 demo=1）用 createParser。解析器映射应保存在模块常量中，并在同一键的所有读取方和写入方之间共享。
使用方式：清空参数时调用 setter(null)，nuqs 会保留无关参数与 hash。更新默认替换历史记录，若希望该变更成为一次可后退步骤则传入 { history: "push" }。对于到达时只消费一次的参数（如深链接或 OAuth 返回标志），可在 useState 初始化器中从 hook 值捕获，然后在挂载副作用中用 setter 清除。一次性读取且不会因 URL 变化而重新渲染的场景可以直接读原始参数，包括 OAuth 回调页、登录页、旧版 ?page= 重定向以及 networking.tsx。新增 hook 前应优先复用现有辅助实现：src/hooks/useUrlTab.ts 中的 useUrlTab、src/components/shared/DataTable 中的 useUrlTableState，以及路由模块 src/components/lens/route.ts 和 src/components/logs/request/logDetailRouting.ts。
测试：测试中使用 tests/test-utils.tsx 的 renderWithProviders 渲染，传入 searchParams 作为初始 URL，并用 onUrlUpdate 断言写入。当测试直接断言 window.location 时，需将渲染包裹在来自 nuqs/adapters/react 的 NuqsAdapter 中；写入是异步刷新的，因此应在 waitFor 内断言。对于绑定到 URL 状态的输入，应使用一次 fireEvent.change 设置值，而不是 user.type，因为按键之间发生重新渲染导致焦点移动时后者容易不稳定。解析器与选项的更多细节可参阅 nuqs 文档。