前端项目架构（基于 monorepo）

在构建前端项目库时，架构的首要目标是 "资产的高内聚与低耦合"。我们采用 Monorepo 架构，旨在构建一个既能独立迭代 UI 原子能力，又能快速集成文档与 AI 业务场景的工程闭环。本章我们将完成 k-ai-ui 的基础搭建，确立工程的规范化约束。

顶层目录设计与 Workspace 拓扑

不同于传统的 Monorepo，AI 组件库的目录结构需要考虑到知识库索引（RAG）的便利性。我们将核心资产（packages）与消费场景（websites）严格物理隔离。

目录结构规划

plainText 复制代码

1  k-ai-ui/ 
2  ├── packages/ #【核心资产区】 
3  │ ├── ui/ # 基于Tailwind的AI原子组件库 
4  │ ├── utils/ # 共享工具函数（可被AI Agent调用的工具集） 
5  │ └── ts-config/ # 统一TypeScript配置 
6  ├── websites/ #【应用消费区】 
7  │ └── docs/ # 基于Rspress的组件文档 & 演练场 
8  ├── .husky/ # Git Hooks脚本 
9  ├── .vscode/ # 编辑器配置 
10 ├── .npmrc # npm镜像与提升配置 
11 ├── pnpm-workspace.yaml # Workspace拓扑定义 
12 └── package.json # 根依赖管理

pnpm Workspace 配置

创建 pnpm-workspace.yaml

架构思考（面试官视角）：为什么选 pnpm？

除了 "快" 和 "省空间"，对于 AI 项目，pnpm 的非扁平化 node_modules 结构天然解决了 "幽灵依赖（Phantom Dependencies）"。这不仅保证了代码的健壮性，更重要的是，它为 AI 代码扫描工具提供了干净的依赖树，减少了 LLM 在分析项目依赖时的 "幻觉"。

YAML 复制代码

packages: 
- 'packages/*' 
- 'websites/*'

工程化规范体系构建

规范不是为了限制开发，而是为了降低 LLM 理解代码的熵。统一的格式意味着更高的 Token 利用率和更精准的代码补全。

ESLint 9 (Flat Config) 现代配置

ESLint 9 引入了革命性的 Flat Config 系统，废弃了复杂的 .eslintrc 层级继承。这是当前的一线主流。

安装依赖：

bash 复制代码

pnpm add -D eslint @eslint/js typescript typescript-eslint globals -w

根目录创建eslint.config.js：

我们采用 "配置即代码" 的理念，显式定义规则。

js 复制代码

import js from '@eslint/js'; 
import tseslint from 'typescript-eslint'; 
import globals from 'globals'; 
export default tseslint.config(
  { ignores: ['**/dist', '**/node_modules', '**/.rspress'] }, 
  // 基础 JS 规则 
  js.configs.recommended, 
  // TS 推荐规则 
  ...tseslint.configs.recommended, 
  { 
    languageOptions: { 
      ecmaVersion: 2022, 
      sourceType: 'module', 
      globals: { 
        ...globals.browser, ...globals.node, 
      }, 
    }, 
    rules: { 
      // 架构思考：AI 生成的代码容易出现 unused vars，// 在开发阶段设为 warn，避免打断 AI 辅助开发的流畅性
      '@typescript-eslint/no-unused-vars': 'warn', 
      '@typescript-eslint/no-explicit-any': 'warn', 
      'no-console': ['warn', { allow: ['warn', 'error'] }], 
    }, 
  } 
);

提交规范：Git Workflow 的语义化

清晰的 Commit Message 是生成 Changelog 的基础，也是未来让 AI 自动生成周报、理解项目演进历史的数据源。

安装依赖：

bash 复制代码

pnpm add -D husky commitlint @commitlint/cli @commitlint/config-conventional commitizen

配置 commitlint.config.js (集成 cz-git)：

这是一个对开发者极其友好的交互式配置。

js 复制代码

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  prompt: {
    alias: { fd: 'docs: fix typos' },
    messages: {
      type: '选择你要提交的变更类型 :',
      scope: '选择一个提交范围 (可选):',
      customScope: '请输入自定义的提交范围 :',
      subject: '填写简短精炼的变更描述 :\n',
      body: '填写更加详细的变更描述 (可选)。使用 "|" 换行 :\n',
      breaking: '列举非兼容性重大的变更 (可选)。使用 "|" 换行 :\n',
      footerPrefixSelect: '选择关联issue前缀 (可选):',
      customFooterPrefix: '输入自定义issue前缀 :',
      footer: '列举关联issue (可选) 例如: #31, #I3244 :\n',
      confirmCommit: '是否提交或修改commit？',
    },
    types: [
      { value: 'feat', name: 'feat: ✨ 新增功能' }, 
      { value: 'fix', name: 'fix: 🐛 修复缺陷' }, 
      { value: 'docs', name: 'docs: 📝 文档变更' }, 
      { value: 'style', name: 'style: 💄 代码格式' }, 
      { value: 'refactor', name: 'refactor: ♻️ 代码重构' }, 
      { value: 'perf', name: 'perf: ⚡ 性能优化' }, 
      { value: 'test', name: 'test: ✅ 测试用例' }, 
      { value: 'build', name: 'build: 📦 构建流程、外部依赖变更' }, 
      { value: 'ci', name: 'ci: 🎡 集成流程' }, 
      { value: 'chore', name: 'chore: 🔨 构建过程或辅助工具的变动' }, 
      { value: 'revert', name: 'revert: ⏪ 回退代码' },
    ],
    skipQuestions: ['body', 'footer'],
   }
 }

配置 package.json 脚本与 Husky 钩子：

代码块（package.json script 部分）

js 复制代码

// package.json script 
"scripts": { 
  "commit": "git-cz", 
  "prepare": "husky install" 
}

执行初始化：

bash 复制代码

npm run prepare 
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

拼写检查：上下文的精准度

在 AI 应用开发中，变量名的拼写错误不仅仅是 Bug，它会导致 Prompt 上下文失效或 Embedding 检索失败。CSpell 是 AI 时代的 "语法纠错员"。

安装依赖：

bash 复制代码

pnpm add -D cspell -w

根目录创建 cspell.json：

json 复制代码

{ 
  "version": "0.2", 
  "language": "en,en-US", 
  "ignorePaths": [ 
    "node_modules", 
    "dist", 
    "**/*.svg", 
    ".git" 
  ], 
  "words": [ 
    "k", // 项目名
    "rspress", // 技术栈
    "zustand", 
    "monorepo", 
    "clsx", 
    "tailwind", 
    "langgraph", // AI 技术栈
    "langchain" 
  ] 
}

集成到 Husky：

在 pre-commit 阶段拦截拼写错误。

代码块（Bash）

bash 复制代码

npx husky add .husky/pre-commit 'npx cspell lint "**/*.{ts,tsx,js,jsx,md}"'