soul-yongping/.cursor/skills/kbone-miniprogram/README.md

# Kbone 小程序开发技能

## 概述

这个技能帮助 AI Agent 更好地处理使用 Kbone 框架将 React Web 应用转换为微信小程序的任务。

**适用场景**：
- 配置 Kbone 项目
- 优化 Kbone 构建
- 解决跨平台兼容性问题
- 排查 Kbone 相关错误

---

## 文件说明

### SKILL.md
主要技能文档，包含：
- Kbone 核心配置规范
- 常见问题快速解决方案
- 跨平台适配层设计
- 开发流程和最佳实践
- 快速检查清单

### troubleshooting.md
详细的故障排查指南，包含：
- 编译问题（chunk 文件、Babel、依赖）
- 运行时问题（URLSearchParams、localStorage、window/document）
- 样式问题（Grid、盒模型、Flexbox）
- 路由问题（导航、switchTab、动态路由）
- 网络问题（API 请求、跨域）
- 性能问题（加载慢、卡顿）
- 调试技巧和工具

---

## 技能使用指南

### 何时使用此技能

Agent 应该在以下情况下自动应用此技能：

1. **项目配置**
   - 用户提到 "kbone"、"小程序"、"miniprogram"
   - 需要配置 `miniprogram.config.js`
   - 需要配置 `webpack.mp.config.js`

2. **代码转换**
   - 将 React Web 应用转换为小程序
   - 需要创建跨平台适配层
   - 处理 Web 和小程序的 API 差异

3. **问题排查**
   - 编译错误（chunk 文件、Webpack 配置）
   - 运行时错误（API 不兼容）
   - 样式问题（Grid、布局错乱）
   - 路由问题（导航失败）

4. **优化任务**
   - 优化 Kbone 配置
   - 减小包体积
   - 提升性能

---

## 核心知识点

### 1. 配置规范

**router 配置**：每个页面单独配置
```javascript
router: {
  index: ['/', '/index.html'],
  my: ['/my', '/my.html'],
}
```

**pages 配置**：每个页面设置标题
```javascript
pages: {
  index: {
    extra: { navigationBarTitleText: '首页' }
  }
}
```

---

### 2. 兼容性处理

**必须避免的 API**：
- `URLSearchParams`（自定义实现）
- `localStorage`（使用适配器）
- `window`、`document`（条件使用）

**必须避免的 CSS**：
- CSS Grid（改用 Flexbox）
- 未设置 `box-sizing: border-box`

---

### 3. 代码分割策略

**中小型项目**（<20 页面）：
```javascript
splitChunks: false // 禁用，优先稳定性
```

**大型项目**（>50 页面）：
```javascript
splitChunks: { chunks: 'all' } // 启用，优化体积
```

---

### 4. 环境判断

```javascript
function isMiniProgram() {
  return typeof wx !== 'undefined' && wx.getSystemInfoSync
}
```

---

## 快速参考

### 常见问题速查

| 问题 | 文档位置 |
|------|---------|
| chunk 文件缺失 | SKILL.md > 问题 2 |
| URLSearchParams 错误 | SKILL.md > 问题 3 / troubleshooting.md > 运行时问题 1 |
| CSS Grid 不生效 | SKILL.md > 问题 1 / troubleshooting.md > 样式问题 1 |
| 底部导航动态显示 | SKILL.md > 问题 4 |
| 页面跳转失败 | troubleshooting.md > 路由问题 1 |
| API 请求失败 | troubleshooting.md > 网络问题 1 |

---

### 配置文件速查

| 配置 | 文件 | 关键点 |
|------|------|--------|
| 路由配置 | miniprogram.config.js | router 每个页面单独配置 |
| 页面标题 | miniprogram.config.js | pages 配置 navigationBarTitleText |
| 代码分割 | webpack.mp.config.js | optimization.splitChunks |
| 环境判断 | webpack.mp.config.js | mode 和 isOptimize |
| 入口文件 | webpack.mp.config.js | entry 每个页面一个入口 |

---

## 使用示例

### 场景 1：配置新项目

用户消息：
> "帮我配置一个 kbone 项目，有首页、目录、阅读三个页面"

Agent 应该：
1. 读取 SKILL.md
2. 创建 `miniprogram.config.js`，配置 router 和 pages
3. 创建 `webpack.mp.config.js`，配置 entry 和 optimization
4. 创建跨平台适配器（router、request、storage、env）
5. 提供构建和测试命令

---

### 场景 2：修复编译错误

用户消息：
> "编译报错：ENOENT: no such file or directory, open '.../default~chapters~index.js'"

Agent 应该：
1. 识别为 chunk 文件缺失问题
2. 读取 SKILL.md > 问题 2 或 troubleshooting.md > 编译问题 1
3. 判断项目规模
4. 禁用或配置 splitChunks
5. 重新构建并验证

---

### 场景 3：修复运行时错误

用户消息：
> "小程序报错：URLSearchParams is not defined"

Agent 应该：
1. 识别为 API 兼容性问题
2. 读取 SKILL.md > 问题 3 或 troubleshooting.md > 运行时问题 1
3. 创建 `buildQueryString` 函数
4. 替换所有 `URLSearchParams` 使用
5. 测试验证

---

### 场景 4：优化配置

用户消息：
> "根据 kbone 官方文档优化我的配置"

Agent 应该：
1. 读取 SKILL.md > 核心配置规范
2. 检查 router、pages、global 配置
3. 检查 webpack mode 和 isOptimize
4. 优化不规范的配置
5. 提供优化说明和测试指引

---

## 维护说明

### 更新触发条件

当以下情况发生时，应更新此技能：

1. **Kbone 官方更新**
   - 新版本配置变化
   - 新增功能或 API
   - 废弃旧配置

2. **发现新问题**
   - 遇到新的兼容性问题
   - 发现新的最佳实践
   - 用户反馈的常见问题

3. **项目实践积累**
   - 新的解决方案
   - 更好的配置策略
   - 优化的代码模式

---

### 更新流程

1. 在 troubleshooting.md 添加新问题和解决方案
2. 如果是常见问题，在 SKILL.md 添加快速方案
3. 更新本 README.md 的快速参考表
4. 在项目 `开发文档/8、部署/` 下创建详细文档

---

## 参考资源

### 官方文档
- [Kbone 官方文档](https://wechat-miniprogram.github.io/kbone/docs/)
- [React 项目模板](https://github.com/wechat-miniprogram/kbone-template-react)
- [小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)

### 项目文档
项目 `开发文档/8、部署/` 目录下有详细的实践文档：
- Kbone配置优化说明.md
- 小程序样式修复说明.md
- 自定义导航组件方案.md
- API接入说明.md
- Webpack代码分割问题修复.md

---

## 反馈与改进

如果在使用过程中发现：
- 文档不清楚的地方
- 缺少的问题和解决方案
- 更好的实践方法

请更新相应的文档文件，保持技能的时效性和准确性。