开发指南
共享工具与常量规范
重复代码的识别、共享归属、运行环境边界与行为兼容要求。
抽取重复代码的目的是让同一规则只有一处实现。先核对调用方的输入、输出和失败路径，再决定是否共享。
共享代码放在哪里
| 场景 | 归属 |
|---|---|
| 跨 workspace 的纯函数 | @pure/utils 的明确子路径 |
| DOM、剪贴板与 Blob 下载 | @pure/utils/client |
| Node、密钥或服务端资源 | @pure/utils/server 或服务端领域模块 |
| 跨包稳定常量、枚举与简单规则 | @pure/const |
| 模型目录与默认模型 | @pure/model-bank |
| 仅在主应用复用的常量 | src/const |
| 社区、后台或渠道专属行为 | 对应功能域的共享 helper / hook |
共享包不得反向导入主应用。客户端不得因一个校验函数导入数据库或服务端模块；优先使用只包含所需能力的入口，避免通过巨型 index 混入不兼容依赖。
抽取条件
- 至少两个真实调用方承担同一业务规则，或已有公共工具可以直接复用。
- 优先使用标准库和已经安装的依赖，不为小 helper 新增依赖或转发封装。
- 细微差异用少量有含义的参数或字段访问函数表达；若需要一串开关描述不同流程，应保留独立实现。
- UI 提示留在组件 / hook；工具只返回结果或抛出原有错误。
- 不把一个页面的所有局部变量搬进全局 const。跨页面稳定常量才上提，领域常量就近维护。
- 不合并仅仅数值相同的超时、上限和默认值。历史迁移快照必须独立维护。
- 只读常量可以共享；会被修改的默认对象由调用端创建，避免页面之间共享可变状态。
必须保留的行为
评估空值、空字符串、数组、非法输入、排序、时区、地区、精度和异常回退。尤其注意：
isObjectLike接受数组，isRecord排除数组，不能机械替换。getErrorMessage只读取真正的 Error；不自动接受带 message 字段的普通对象，也不把空消息替换成回退文案。- URL 校验按用途命名。服务商地址的严格规则不能替代搜索链接或下载地址的规则。
- 可取消等待必须保留调用端原来的 resolve / reject 选择。
- 带剪贴板降级的函数和需要展示权限失败的复制交互不能混用。
- 保留接口响应、存储键、历史配置版本与外部可见导出；重命名内部实现时同步迁移全部调用方。
检查与后续治理
每次修改相关功能时搜索同类 helper 和常量，优先复用。记录重复位置、行为差异、共享归属与验证结果；无法保持行为的候选记录原因后保留。
纯函数测试覆盖实际分支和边界，副作用测试验证资源清理与错误传播，不新增只断言页面骨架的组件测试。根项目与 workspace package 分开运行测试，交付前执行 质量检查。样式共享遵循 Tailwind 规范。