mcpField
1
1k-architecture

1k-architecture

github.com/onekeyhq开发2.5k70 次安装今天更新
代码仓库

关于 1k-architecture

面向 OneKey 多平台钱包单体仓库贡献者的架构技能，介绍应用与软件包的边界、导入规则，以及跨平台保持代码一致性的检查方法。

主要功能

  1. 01多平台应用与软件包结构图
  2. 02严格的软件包导入层级
  3. 03平台专属文件约定
  4. 04跨平台 UI 与状态模式
  5. 05架构审查清单

适用场景

  1. 01为代码更改定位合适的软件包
  2. 02检查导入是否违反依赖规则
  3. 03评估更改对各应用平台的影响

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/onekeyhq/app-monorepo --skill 1k-architecture

安装后在 Claude Code 中输入/1k-architecture确认已加载。

详细介绍

OneKey 架构概览

平台结构

  • apps/desktop/ - Electron 桌面应用（Windows、macOS、Linux）
  • apps/mobile/ - React Native 移动应用（iOS、Android）
  • apps/ext/ - 浏览器扩展（Chrome、Firefox、Edge、Brave）
  • apps/web/ - 渐进式 Web 应用
  • apps/web-embed/ - 可嵌入的钱包组件

核心包

  • packages/core/ - 区块链协议实现、密码学、硬件钱包通信
  • packages/kit/ - 应用逻辑、状态管理、API 集成
  • packages/kit-bg/ - 后台服务和工作进程
  • packages/components/ - 基于 Tamagui 的跨平台 UI 组件
  • packages/shared/ - 平台抽象、实用工具、构建配置
  • packages/qr-wallet-sdk/ - 用于隔离钱包 QR 通信的 SDK

关键架构模式

  • 多链支持：支持 40 多条区块链，链实现可插拔
  • 跨平台 UI：使用 Tamagui 构建通用组件，并进行平台特定适配
  • 平台特定文件：使用 .native.ts、.desktop.ts、.web.ts、.ext.ts 后缀
  • 硬件钱包集成：自定义 @onekeyfe/hd-* SDK 包
  • 状态管理：使用 Jotai 进行原子状态管理

代码组织

文件命名约定
  • 平台特定实现使用以下后缀：.native.ts、.web.ts、.desktop.ts、.ext.ts
  • 组件文件使用 PascalCase：ComponentName.tsx
  • Hook 文件使用以 use 为前缀的 camelCase：useHookName.ts
  • 工具文件使用 camelCase：utilityName.ts
导入模式
  • 使用工作区引用：@onekeyhq/components、@onekeyhq/core、@onekeyhq/kit
  • 通过 @onekeyhq/shared/src/platformEnv 检测平台
  • 根据平台能力进行条件导入
导入层级规则 - 严格执行

重要：违反这些规则会导致构建失败并造成循环依赖。

层级（绝不可违反此顺序）：

  • @onekeyhq/shared - 禁止从其他任何 OneKey 包导入
  • @onekeyhq/components - 仅允许从 shared 导入
  • @onekeyhq/kit-bg - 仅允许从 shared 和 core 导入（绝不可从 components 或 kit 导入）
  • @onekeyhq/kit - 可从 shared、components 和 kit-bg 导入
  • 应用（desktop/mobile/ext/web）- 可从所有包导入

添加任何导入之前：

  1. 确认导入符合上述层级规则
  2. 检查该导入是否会造成循环依赖
  3. 如有疑问，请寻找符合层级规则的替代方案

应避免的常见违规情况：

  • ❌ 在 @onekeyhq/components 中从 @onekeyhq/kit 导入
  • ❌ 在 @onekeyhq/kit-bg 中从 @onekeyhq/components 导入
  • ❌ 在 @onekeyhq/core 中从 @onekeyhq/kit 导入
  • ❌ 层级中的任何“向上”导入
组件结构
  • UI 组件位于 packages/components/src/
  • 业务逻辑位于 packages/kit/src/
  • 链特定代码位于 packages/core/src/chains/

深度分析与架构一致性框架

修改前分析协议

强制分析步骤（任何代码更改前执行）：

  1. 评估影响范围

    • 确定受更改影响的所有软件包/应用
    • 梳理将受到影响的依赖关系（必要时使用 yarn why <package>）
    • 评估跨平台影响（桌面端/移动端/Web/扩展）
    • 评估向后兼容性要求

  2. 验证模式一致性

    • 检查代码库中现有的类似实现
    • 识别已确立的模式和惯例
    • 验证新代码是否遵循相同模式
    • 检查命名惯例是否与现有代码一致

  3. 检查架构完整性

    • 根据单仓库导入层级规则进行验证
    • 确保保持关注点分离
    • 验证平台专用代码是否使用正确的文件扩展名
    • 检查业务逻辑是否位于适当的软件包中

  4. 评估性能影响

    • 考虑对捆绑包大小的影响（尤其是 Web/扩展）
    • 评估对运行时性能的影响
    • 评估对内存使用的影响
    • 考虑对应用启动时间的影响
代码模式识别框架

添加新功能时：

  1. 查找类似示例：在代码库中搜索类似实现
  2. 提取模式：识别常见方法、命名和结构
  3. 遵循惯例：准确复用现有模式
  4. 验证一致性：确保新代码与现有代码风格一致

修改现有代码时：

  1. 了解上下文：阅读周边代码和导入内容
  2. 保留模式：维护现有架构决策
  3. 保持风格一致：匹配现有代码风格和结构
  4. 验证集成：确保更改能够无缝集成
架构验证清单

提交任何更改前：

  • 遵守导入层级规则（不得向上导入）
  • 平台专用文件使用正确的扩展名
  • 保持安全模式（尤其是加密操作）
  • 错误处理遵循已确立的模式
  • 一致地应用状态管理模式
  • 遵循 UI 组件模式（Tamagui 用法）
  • 正确实现翻译模式
  • 保持并扩展测试模式

评论

支持 Markdown