标准化技能栈：跨框架能力复用与路由机制解析

1. 项目概述：为什么“标准化技能栈”正在成为工程落地的分水岭

最近在带几个跨团队协作的项目时，反复被同一个问题卡住：前端组用 React 写完的组件，后端组想复用其状态管理逻辑到 NestJS 的服务层；移动端同事把 Vue 的表单校验规则封装成 JSON Schema，结果在桌面端 Electron 应用里跑不通——不是语法报错，而是校验上下文丢失、错误提示位置错乱、异步验证链路断裂。这类问题不再是个别现象，而是当项目规模突破三人协作、技术栈覆盖 Web/桌面/嵌入式三端时必然撞上的墙。我把它叫作“技能栈失重”：开发者熟练掌握某框架的 API，却无法把其中沉淀下来的业务逻辑、状态流转、错误处理等可复用能力，平滑迁移到另一个技术环境里。而“标准化技能栈的跨框架移植与路由机制解析”这个标题，说的正是如何把那些散落在 React、Vue、Svelte、甚至纯 JS 工具库中的“有效知识”，抽离成不依赖渲染层、不绑定生命周期、能被任意框架消费的标准化能力单元。它不是教你怎么写更好的组件，而是教你如何让组件里的“判断逻辑”“数据转换规则”“导航跳转策略”这些真正值钱的部分，像乐高积木一样，在不同框架底盘上自由拼插。关键词里反复出现的“跨框架”“路由机制”“标准化”，指向的其实是工程效率的底层重构——当一个表单验证函数能同时服务于 React 的 useForm、Vue 的useForm、甚至命令行工具的参数校验，你节省的就不是几行代码，而是整个团队在框架切换、技术债清理、多端同步上的决策成本和试错时间。

2. 核心设计思路：从“框架中心”到“能力中心”的范式迁移

2.1 为什么传统“封装组件”方案在跨框架场景下必然失效

很多人第一反应是：“那我把 React 组件封装成 Web Component 不就行了吗？”我试过，也带着团队在三个项目里落地过。结果很明确：Web Component 解决了 DOM 层的隔离，但彻底放弃了状态管理、副作用控制、响应式更新这些现代框架最核心的价值。举个具体例子：一个带防抖搜索的输入框组件，React 版本里用useEffect+useRef管理定时器，Vue 版本用watch+onBeforeUnmount清理，Svelte 版本靠$: debouncedValue = debounce(inputValue)声明式推导。如果强行塞进 Web Component，你得自己手写connectedCallback里的定时器管理、disconnectedCallback里的清理逻辑，还要手动触发CustomEvent通知外部状态变更——这等于把框架帮你屏蔽的复杂性，又亲手还给了开发者。更致命的是，Web Component 无法消费框架的响应式系统，你传进去的ref或reactive对象，在组件内部立刻退化成普通 JS 对象，响应式链路就此断裂。所以，“封装组件”这条路，本质是用 DOM 层的兼容性，换掉了框架层的生产力。这不是跨框架，这是降维兼容。

2.2 “标准化技能栈”的真实内涵：三层解耦模型

真正可行的路径，是把一个功能拆成三个正交层，并为每一层定义清晰、无歧义、可验证的契约：

• 能力层（Capability Layer）：这是最核心的“技能”所在。它只包含纯函数：输入是什么（数据结构、事件类型），输出是什么（新数据、副作用指令、导航动作），中间不涉及任何框架 API。比如一个“用户登录”能力，它的输入是{username: string, password: string}，输出是{status: 'success' | 'error', user?: User, redirect?: string}。它不关心useState怎么设，也不管this.$router.push怎么调，它只负责回答“登录这件事，逻辑上该怎么判、怎么走”。

• 适配层（Adapter Layer）：这是连接能力层和具体框架的“翻译官”。它接收能力层的输出，将其映射为当前框架的原生操作。比如能力层返回redirect: '/dashboard'，在 React 里适配层调用navigate('/dashboard')，在 Vue 里调用router.push('/dashboard')，在命令行工具里则打印Go to dashboard...并执行process.exit(0)。适配层是薄的、可替换的、按需加载的，一个项目里可以同时存在 ReactAdapter、VueAdapter、CLIAdapter。

• 编排层（Orchestration Layer）：这是业务逻辑的“指挥中心”。它不直接调用框架 API，也不硬编码能力实现，而是通过声明式配置，把能力层的函数、适配层的映射规则、以及它们之间的依赖关系（比如“登录成功后必须先加载用户权限，再跳转”）组织起来。我们常用一个轻量级的状态机（State Machine）来建模：每个状态代表一个业务阶段（idle,submitting,validating,redirecting），每个转移（Transition）由能力层的输出触发，每个状态的进入/退出动作由适配层执行。这样，整个业务流程就变成了一个可读、可测、可回溯的数据结构，而不是散落在各处的if-else和then-catch。

这个三层模型之所以能成立，关键在于它把“什么该做”（能力层）、“怎么做”（适配层）、“什么时候做”（编排层）彻底分开。我见过最成功的案例，是一个电商后台的“商品上架”流程：能力层有validateSku(),checkInventory(),generateSkuCode()三个纯函数；适配层为 Web 端（React）和审核 App（React Native）分别提供；编排层用一个 JSON 文件定义了所有校验失败时的错误码映射和重试策略。当审核 App 需要增加离线缓存能力时，我们只新增了一个cacheOnSubmit()能力函数，并在编排层的 JSON 里加了一行配置，前后不到 20 分钟，Web 端也自动获得了离线支持——因为能力层和编排层是共享的，适配层只是把“缓存”这个动作翻译成AsyncStorage.setItem而已。

2.3 路由机制为何是跨框架移植的“压力测试场”

路由看似只是 URL 映射，但它集中暴露了框架间最根本的差异：状态管理粒度、副作用触发时机、错误边界处理方式。比如一个典型的“详情页”路由：

• 在 React Router v6 中，你可能用useLoaderData()在组件挂载前预取数据，用useNavigate()处理跳转，用ErrorBoundary捕获子组件错误；
• 在 Vue Router 中，你用beforeRouteEnter守卫预取，用router.push()跳转，用onErrorCaptured捕获；
• 在 SvelteKit 中，你用load()函数预取，用$app.navigation.goto()跳转，用+error.svelte统一处理。

如果把路由逻辑硬编码在组件里，跨框架移植就是一场灾难。而标准化技能栈的解法，是把路由抽象为“导航能力”（Navigation Capability）：它的输入是目标路径、携带参数、跳转模式（push/replace），输出是一个标准化的导航指令对象{type: 'NAVIGATE', path: '/user/123', params: {tab: 'profile'}, mode: 'push'}。真正的跳转动作，由适配层根据当前运行环境决定。更进一步，我们把“页面守卫”（Route Guard）也能力化：canAccessPage({userRole, routePath})返回true/false或{allowed: true, redirect: '/login'}，这个函数本身不调用任何路由 API，它只做逻辑判断。这样，当公司安全策略要求所有/admin/*路径必须二次验证时，你只需要修改canAccessPage这一个函数，所有框架下的路由守卫就同步生效了。路由机制因此从“框架特性”变成了“可配置的业务规则”，这才是它在标准化技能栈中不可替代的价值。

3. 核心细节解析：能力层契约设计与实操要点

3.1 能力函数的“四不原则”：定义不可妥协的边界

一个函数是否属于合格的“能力层”，我用四个硬性标准来卡：

• 不依赖框架实例（No Framework Instance）：函数体内绝对不能出现this.$router、useNavigate、document.getElementById这类强绑定环境的调用。它只能接收显式传入的参数，返回显式定义的输出。哪怕是一个简单的“格式化日期”函数，也不能直接new Date().toLocaleString()，而必须接收date: Date | string和options: Intl.DateTimeFormatOptions两个参数，因为Intl的行为在不同浏览器/Node 版本下有差异，必须可控。

• 不持有外部状态（No External State）：能力函数必须是纯函数（Pure Function）或至少是“引用透明”（Referential Transparent）。这意味着对同一组输入，它必须始终返回相同输出，且不产生任何可观察的副作用（如修改全局变量、发网络请求、写 localStorage）。网络请求这类副作用，必须被包装成一个返回Promise<Output>的函数，并明确标注其副作用类型（如@sideEffect: 'network'）。这样，适配层才能决定是在 React 的useEffect里调用，还是在 Vue 的onMounted里调用，或者干脆在服务端 Node.js 环境里预执行。

• 不处理 UI 渲染（No UI Rendering）：能力层绝不返回 JSX、VNode、Svelte 组件实例，甚至不返回 HTML 字符串。它只返回数据结构（对象、数组、字符串、数字）或标准化指令（如{type: 'SHOW_TOAST', message: 'Success!'}）。UI 渲染是适配层的职责，能力层只负责“告诉 UI 该做什么”，绝不“告诉 UI 怎么做”。

• 不假设执行环境（No Environment Assumption）：函数不能假设自己一定在浏览器里运行。window、localStorage、navigator.onLine这些浏览器专属 API，必须作为可选参数传入，或通过一个统一的EnvironmentContext对象注入。这样，同一个fetchUser()能力函数，既能用于 Web 端（传入window.fetch），也能用于 Node.js 后端（传入node-fetch），甚至能用于 Deno 环境（传入Deno.fetch）。我见过最优雅的实践，是把环境依赖抽象成一个IO接口：

  interface IO { fetch: (url: string, options?: RequestInit) => Promise<Response>; storage: { get: (key: string) => Promise<string | null>; set: (key: string, value: string) => Promise<void> }; timer: { setTimeout: (cb: () => void, ms: number) => number }; }

  能力函数签名变成fetchUser(userId: string, io: IO): Promise<User>，彻底解耦。

提示：初学者常犯的错误是把“获取用户信息”和“显示用户头像”写在一个函数里。前者是能力，后者是 UI。正确的做法是fetchUser()返回User对象，renderAvatar(user: User)由适配层根据框架特性实现——React 用img标签，Vue 用v-img组件，Svelte 用<img src={user.avatar}>。能力层只管“数据从哪来”，不管“数据长啥样”。

3.2 路由能力的标准化契约：从 URL 字符串到语义化指令

路由能力的标准化，是整个体系中最考验设计功力的部分。我们摒弃了直接操作 URL 字符串的原始方式，定义了一套语义化的导航指令集（Navigation Instruction Set），它包含五种基础指令：

指令类型	输入参数	典型用途	适配层示例（React）
NAVIGATE	path: string,params: Record<string, any>,mode: 'push' | 'replace'	页面跳转	navigate(generatePath(path, params), { replace: mode === 'replace' })
REDIRECT	to: string | { path: string, params: Record<string, any> },permanent: boolean	服务端重定向语义	res.redirect(301, to)(Node.js) /window.location.replace(to)(客户端)
BACK	steps: number	浏览器后退	navigate(-steps)
GO	delta: number	浏览器前进/后退	navigate(delta)
RELOAD	hard: boolean	页面刷新	window.location.reload(hard)

关键点在于，这些指令不是最终执行动作，而是“意图声明”。一个能力函数handleLoginSuccess(user: User)可能返回：

{ "type": "NAVIGATE", "path": "/dashboard", "params": { "welcome": true }, "mode": "push" }

适配层收到这个指令后，才决定是调用navigate()还是router.push()。更妙的是，这个指令可以被拦截、被审计、被模拟。比如在 E2E 测试中，我们不需要真的跳转页面，而是断言能力函数返回的指令是否符合预期：

// 测试代码，不依赖任何框架 const result = handleLoginSuccess(mockUser); expect(result).toEqual({ type: 'NAVIGATE', path: '/dashboard', params: { welcome: true } });

这种测试方式，比在 Jest 里 mockuseNavigate稳定十倍，因为它是测试“业务逻辑”，而不是测试“框架调用”。

3.3 编排层的实战：用状态机驱动复杂业务流

编排层不是简单的函数调用链，而是对业务状态变迁的精确建模。我们采用 XState（一个轻量级、可序列化的状态机库）作为事实标准，原因有三：一是它的状态图可导出为 JSON，方便非技术人员（如产品经理）参与评审；二是它天然支持并行状态、历史状态、延迟转移，覆盖绝大多数业务场景；三是它的send()方法返回一个确定性的State对象，便于测试和调试。

以“订单支付”这个经典流程为例，其状态机定义（简化版）如下：

{ "id": "orderPayment", "initial": "idle", "states": { "idle": { "on": { "START_PAYMENT": "preparing" } }, "preparing": { "invoke": { "src": "preparePayment", "onDone": "ready", "onError": "error" } }, "ready": { "on": { "CONFIRM": "processing", "CANCEL": "idle" } }, "processing": { "invoke": { "src": "processPayment", "onDone": "success", "onError": "failed" } }, "success": { "entry": ["logSuccess", "sendNotification"], "on": { "DONE": "idle" } } } }

这里的关键设计是：

• preparePayment和processPayment是能力层函数，它们只负责业务逻辑，不碰任何 UI；
• logSuccess和sendNotification是副作用函数，由适配层注入，比如在 Web 端调用console.log和fetch('/api/notify')，在 App 端调用PushNotification.send()；
• 所有状态转移（START_PAYMENT,CONFIRM,DONE）都由用户交互或能力函数输出触发，而不是硬编码在组件里。

实操心得：状态机的初始状态（initial）和最终状态（done）必须与业务语言一致。我们曾把一个“文件上传”状态机的初始状态命名为uploading，结果开发、测试、产品都理解为“已经开始上传了”，实际应该是idle（等待用户选择文件）。后来我们强制规定：所有状态名必须是名词，且能被产品经理用自然语言描述出来，比如waitingForFile,validatingFile,uploadingToServer,processingResult。这看似琐碎，却极大降低了跨角色沟通成本。

4. 实操过程：从零搭建一个可复用的能力栈

4.1 工程结构与包管理：monorepo 是唯一合理选择

跨框架项目，monorepo 不是“推荐”，而是“必需”。我们使用 pnpm workspaces，结构如下：

my-standard-stack/ ├── packages/ │ ├── core/ # 能力层：所有纯函数、类型定义、状态机 schema │ ├── adapters/ # 适配层：react-adapter, vue-adapter, cli-adapter │ ├── orchestrators/ # 编排层：payment-orchestrator, auth-orchestrator │ └── examples/ # 示例项目：react-demo, vue-demo, svelte-demo ├── apps/ │ ├── web/ # React Web 应用，依赖 core + react-adapter │ └── admin/ # Vue Admin 应用，依赖 core + vue-adapter └── turbo.json # TurboRepo 配置，实现增量构建

core包是整个体系的基石，它必须满足：

• 零依赖（Zero Dependencies）：不引入任何第三方库，连lodash都不行。所有工具函数（如深克隆、对象合并）都自己实现，确保最小化体积和最大兼容性。
• TypeScript 优先（TS-First）：所有能力函数必须有完整的 JSDoc 注释和类型定义。我们约定：JSDoc 的@param必须精确到字段级，比如@param user - {id: number, name: string, email?: string}，而不是笼统的@param user - 用户对象。
• 可树摇（Tree-Shakable）：每个能力函数单独导出，不打包成大 bundle。import { validateEmail } from '@my-stack/core'能精准摇掉validatePhone。

adapters包则按框架划分，每个 adapter 只做一件事：把核心能力的输出，翻译成当前框架的原生操作。react-adapter的核心就是一个createReactAdapter()工厂函数：

export function createReactAdapter({ navigate, toast, router }: { navigate: ReturnType<typeof useNavigate>; toast: (msg: string) => void; router: ReturnType<typeof useRouter>; }) { return { navigate: (instruction: NavigateInstruction) => { // 将 instruction.path + params 转为实际 URL const url = generatePath(instruction.path, instruction.params); navigate(url, { replace: instruction.mode === 'replace' }); }, showToast: (message: string) => toast(message), // ... 其他能力映射 }; }

这样，React 应用在初始化时，只需传入useNavigate、useToast等 Hook 的返回值，就能获得一个完整的适配器实例。Vue 和 Svelte 的 adapter 也是同理，只是参数来源不同。

4.2 能力函数开发：一个真实的“表单提交”能力实现

我们以“用户注册表单提交”为例，展示从需求到能力函数的完整过程。业务需求是：

• 前端校验邮箱格式、密码强度、两次输入一致性；
• 后端校验邮箱是否已被注册；
• 提交成功后跳转到欢迎页，并显示欢迎消息；
• 任一环节失败，显示对应错误提示。

第一步：定义能力层接口（core/src/capabilities/register.ts）：

// 输入：用户填写的表单数据 export interface RegisterInput { email: string; password: string; confirmPassword: string; } // 输出：标准化的指令集 export type RegisterOutput = | { type: 'SUCCESS'; userId: number; redirect: { path: '/welcome', params: { email: string } } } | { type: 'ERROR'; code: 'INVALID_EMAIL' | 'WEAK_PASSWORD' | 'EMAIL_TAKEN' | 'NETWORK_ERROR'; message: string }; // 能力函数：纯逻辑，无副作用 export function validateRegisterInput(input: RegisterInput): RegisterOutput { if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input.email)) { return { type: 'ERROR', code: 'INVALID_EMAIL', message: '请输入有效的邮箱地址' }; } if (input.password.length < 8 || !/[A-Z]/.test(input.password)) { return { type: 'ERROR', code: 'WEAK_PASSWORD', message: '密码至少8位，且需包含大写字母' }; } if (input.password !== input.confirmPassword) { return { type: 'ERROR', code: 'PASSWORD_MISMATCH', message: '两次输入的密码不一致' }; } return { type: 'VALID', input }; // VALID 是中间态，表示前端校验通过 } // 异步能力：需要 IO 环境 export async function checkEmailExists( email: string, io: IO ): Promise<{ exists: boolean }> { try { const res = await io.fetch(`/api/check-email?email=${encodeURIComponent(email)}`); return await res.json(); } catch (e) { throw { type: 'NETWORK_ERROR', message: '网络异常，请稍后重试' }; } } // 主能力函数：组合其他能力 export async function registerUser( input: RegisterInput, io: IO ): Promise<RegisterOutput> { // 1. 前端校验 const validateResult = validateRegisterInput(input); if (validateResult.type === 'ERROR') return validateResult; // 2. 后端校验 try { const { exists } = await checkEmailExists(input.email, io); if (exists) { return { type: 'ERROR', code: 'EMAIL_TAKEN', message: '该邮箱已被注册' }; } } catch (e) { if ('type' in e && e.type === 'NETWORK_ERROR') { return e as RegisterOutput; } return { type: 'ERROR', code: 'NETWORK_ERROR', message: '服务器繁忙，请稍后重试' }; } // 3. 提交注册 try { const res = await io.fetch('/api/register', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input) }); const data = await res.json(); return { type: 'SUCCESS', userId: data.id, redirect: { path: '/welcome', params: { email: input.email } } }; } catch (e) { return { type: 'ERROR', code: 'NETWORK_ERROR', message: '注册失败，请检查网络' }; } }

第二步：在 React 应用中使用（apps/web/src/features/register/RegisterForm.tsx）：

import { useState } from 'react'; import { useNavigate } from 'react-router-dom'; import { registerUser } from '@my-stack/core'; import { createReactAdapter } from '@my-stack/adapters/react-adapter'; // 初始化适配器 const adapter = createReactAdapter({ navigate: useNavigate(), toast: (msg) => {/* 实现 toast */}, router: {/* 实现 router */} }); export function RegisterForm() { const [formData, setFormData] = useState({ email: '', password: '', confirmPassword: '' }); const [error, setError] = useState<string | null>(null); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); setError(null); try { // 调用核心能力函数 const result = await registerUser(formData, { fetch: window.fetch, storage: {/* ... */}, timer: {/* ... */} }); // 处理标准化输出 if (result.type === 'SUCCESS') { // 适配层执行跳转 adapter.navigate(result.redirect); } else { setError(result.message); } } catch (e) { setError('未知错误，请重试'); } }; return ( <form onSubmit={handleSubmit}> {/* 表单字段 */} {error && <div className="error">{error}</div>} <button type="submit">注册</button> </form> ); }

这个例子展示了标准化技能栈的核心价值：registerUser函数可以在任何 JavaScript 环境中运行，它的逻辑是稳定的、可测试的、可复用的。React 只是它的一个消费方，Vue、Svelte、甚至一个 CLI 工具，都可以用完全相同的函数，只是调用方式和错误处理略有不同。

4.3 编排层集成：将能力函数注入状态机

现在，我们把registerUser能力接入状态机，实现更健壮的流程控制。在orchestrators/src/register-orchestrator.ts中：

import { createMachine, assign, sendParent } from 'xstate'; import { registerUser } from '@my-stack/core'; export const registerMachine = createMachine({ id: 'register', initial: 'idle', context: { formData: { email: '', password: '', confirmPassword: '' }, error: null as string | null }, states: { idle: { on: { SUBMIT: 'submitting' } }, submitting: { invoke: { id: 'registerUser', src: (context) => async () => { try { // 调用能力函数 const result = await registerUser(context.formData, { fetch: window.fetch, // ... 其他 IO 依赖 }); return result; } catch (e) { return { type: 'ERROR', code: 'UNKNOWN', message: '系统错误' }; } }, onDone: { target: 'success', actions: assign({ // 从能力函数输出中提取数据 userId: (_, event) => event.data.type === 'SUCCESS' ? event.data.userId : undefined, redirect: (_, event) => event.data.type === 'SUCCESS' ? event.data.redirect : undefined }) }, onError: { target: 'error', actions: assign({ error: (_, event) => event.data.message }) } } }, success: { entry: ['logSuccess'], on: { DONE: 'idle' } }, error: { on: { RETRY: 'submitting' } } } });

然后在 React 组件中，用useMachine消费这个状态机：

import { useMachine } from '@xstate/react'; import { registerMachine } from '@my-stack/orchestrators'; function RegisterForm() { const [state, send] = useMachine(registerMachine); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); send('SUBMIT'); // 触发状态机转移 }; if (state.matches('submitting')) return <div>提交中...</div>; if (state.matches('success')) return <div>注册成功！<button onClick={() => send('DONE')}>完成</button></div>; if (state.matches('error')) return <div>{state.context.error}<button onClick={() => send('RETRY')}>重试</button></div>; return ( <form onSubmit={handleSubmit}> {/* 表单 */} </form> ); }

这里的关键是，registerMachine本身不关心useMachine是 React 的 Hook 还是 Vue 的 Composable，它只是一个纯数据结构。useMachine只是它的消费者之一。这种分离，让业务逻辑的演进完全独立于 UI 框架的升级——当 React 19 发布时，我们只需要更新@xstate/react的版本，registerMachine的定义一行代码都不用改。

5. 常见问题与排查技巧实录：踩过的坑比文档更值钱

5.1 问题速查表：高频故障与根因分析

现象	可能根因	排查步骤	解决方案
能力函数在 Node.js 环境报ReferenceError: window is not defined	能力函数或其依赖的工具函数中，隐式使用了浏览器全局变量（如window,document,localStorage）	1. 在 Node.js 环境运行node --trace-warnings your-script.js；2. 查看堆栈，定位到具体哪一行代码访问了window	严格遵守“不假设执行环境”原则。将所有环境依赖（fetch,storage,timer）作为参数传入，或通过IO接口注入。禁用任何未声明的全局变量访问。
跨框架路由跳转后，页面白屏或状态丢失	适配层的navigate函数没有正确处理params参数，导致生成的 URL 不匹配路由定义；或状态机在跳转前未持久化关键上下文	1. 在适配层navigate函数内console.log生成的最终 URL；2. 检查路由配置中path是否包含动态段（如/user/:id），params是否与之匹配；3. 检查状态机context是否在onEntry中被清空	使用generatePath（React Router）或router.resolve（Vue Router）等框架提供的 URL 生成工具，而非字符串拼接。状态机的关键数据（如userId）应存储在context中，并在跳转前通过sendParent传递给父状态机或全局 store。
能力函数返回的ERROR指令，在不同框架下错误提示样式不一致	适配层的showToast或showError函数，对同一message字符串做了不同的 UI 处理（如 React 用Snackbar，Vue 用Message，但图标、颜色、持续时间不同）	1. 检查adapters包中各框架的showError实现；2. 查看core包中RegisterOutput类型定义，确认message字段是否为纯文本	能力层只返回语义化错误码（code）和标准化消息（message），UI 样式由适配层根据当前框架规范实现。建立一份《错误码-UI 映射表》，规定EMAIL_TAKEN在所有框架下都显示为红色边框 + 图标，确保体验一致。
状态机在invoke状态卡死，既不进入onDone也不进入onError	能力函数（如registerUser）内部的Promise没有被正确resolve或reject，例如try/catch漏掉了某个分支，或async函数中await了一个永远不会 resolve 的 Promise	1. 在能力函数入口和出口添加console.log；2. 使用Promise.race([yourPromise, new Promise(r => setTimeout(r, 5000))])添加超时保护，强制进入onError	所有能力函数必须有明确的return或throw。在invoke的src函数中，务必包裹try/catch，并将所有可能的错误路径都return一个标准化的ERROR对象。为所有网络请求添加超时控制。
pnpm build时core包报Cannot find module '...'	core包的package.json中exports字段配置错误，或types字段指向的.d.ts文件不存在/路径错误	1. 运行pnpm tsc --noEmit --skipLibCheck检查 TypeScript 错误；2. 查看core/dist/index.d.ts是否生成，内容是否完整；3. 检查core/package.json的exports是否正确导出./dist/index.js和./dist/index.d.ts	core包的构建脚本必须同时生成 JS 和 TS 声明文件。package.json的exports字段应类似： "exports": { ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" } }。使用tsc -b进行增量构建，确保类型定义与 JS 代码同步。

5.2 实操心得：那些只有亲手做过才会懂的细节

• “能力函数的命名，要像 API 文档一样直白”：我曾经把一个处理用户头像裁剪的能力函数命名为processAvatar，结果在 Code Review 时被质疑：“process 是指压缩？裁剪？还是加水印？”后来我们统一了命名规范：动词 + 名词 + 场景，如cropAndResizeAvatarForProfile、generateThumbnailFromVideo。名字长一点没关系，它能让任何看到函数名的人，立刻明白它的输入、输出和边界。这比写一百行注释都管用。

• “适配层的‘薄’，是用大量样板代码换来的”：为了保持适配层的纯粹性，我们接受它看起来“啰嗦”。比如vue-adapter里，一个navigate函数要写十几行，因为它要处理router.push的Promise、catch错误、replace模式、query参数序列化……而 React 的navigate只有一行。这种“啰嗦”是值得的，因为它把所有框架特有的复杂性，都锁死在了适配层内部。一旦vue-router升级到 v5，我们只需要改vue-adapter，core和orchestrators一动不动。

• “状态机的context，是你的业务真相唯一可信源”：在复杂的多步骤流程中（如“退货申请”），用户可能在第 3 步关闭页面，5 分钟后回来继续。我们不会把临时数据存在useState里，而是全部存入状态机的context，并在onEntry时从localStorage或 IndexedDB 中恢复。这样，无论用户用什么设备、什么浏览器回来，状态机都能从上次中断的地方继续。context就是业务状态的“单一事实来源”（Single Source of Truth），比任何组件状态都可靠。

• “测试能力函数，永远比测试组件快十倍”：我们有一个core/test目录，里面全是针对能力函数