create-yss-spec 2.1.10 → 2.1.11

package/template/.cursor/skills/yss-ui/assets/docs/guide/llms.md

@@ -0,0 +1,295 @@
+---
+title: AI 工具集成指南（LLMs.txt）
+description: 如何在 Cursor、Windsurf 等 AI 编程工具中使用 YSS UI 文档
+toc: content
+---
+
+# AI 工具集成指南
+
+YSS UI 支持通过 <a href="https://llmstxt.org/" target="_blank">LLMs.txt</a> 文件向大语言模型（LLMs）提供文档。此功能可帮助 AI 工具更好地理解我们的组件库、API 及使用模式。
+
+## 什么是 LLMs.txt？
+
+LLMs.txt 是一个专门为大语言模型设计的文档格式规范。通过提供结构化的组件概览和完整文档，AI 编程工具能够：
+
+- 🤖 **自动获取组件文档** - AI 工具可以直接访问最新的组件 API 和用法
+- 💡 **提供准确的代码建议** - 基于真实文档生成正确的组件使用示例
+- 📚 **降低学习成本** - 开发时无需频繁切换到文档页面
+- ✨ **提高代码质量** - AI 能根据最佳实践自动提供建议
+
+## 可用资源
+
+我们提供两个 LLMs.txt 文件来帮助 AI 工具访问文档：
+
+### 推荐使用：llms-full.txt ⭐
+
+**<a href="/llms-full.txt" target="_blank">llms-full.txt</a>** - 完整文档
+
+包含所有组件的完整 API 文档、使用示例和最佳实践。**强烈推荐**作为默认配置，因为：
+- ✅ **更准确的代码生成** - AI 能看到完整的 Props、Events、Slots 定义
+- ✅ **真实示例参考** - 包含实际使用代码，避免 AI 猜测用法
+- ✅ **完整上下文** - 现代 AI 工具（Claude 200K、GPT-4 128K）完全支持这个大小
+
+### 轻量级索引：llms.txt
+
+**<a href="/llms.txt" target="_blank">llms.txt</a>** - 简版索引（1.6KB，70 行）
+
+仅包含组件列表和文档链接。适用于：
+- 上下文窗口受限的旧版 AI 工具
+- 只需要快速组件发现的场景
+- 网络带宽受限的环境
+
+> **建议**：优先使用 `llms-full.txt`，只有在遇到上下文限制时才降级使用 `llms.txt`。
+
+## 在 AI 工具中的使用
+
+### Cursor
+
+在 Cursor 中使用 `@Docs` 功能将 LLMs.txt 文件包含到您的项目中。这有助于 Cursor 为 YSS UI 组件提供更准确的代码建议和文档。
+
+**使用方法：**
+
+1. 在 Cursor 聊天窗口中输入 `@Docs`
+2. 输入 YSS UI 文档站点的 URL（部署后的地址）
+3. Cursor 会自动加载 llms.txt 文件
+
+**示例：**
+
+```
+@Docs http://192.168.164.27:3200
+```
+
+然后你可以直接询问：
+
+```
+如何使用 YTable 组件实现远程分页？
+```
+
+Cursor 将基于 YSS UI 的真实文档提供准确的回答和代码示例。
+
+<a href="https://docs.cursor.com/context/@-symbols/@-docs" target="_blank">详细了解 Cursor 中的 @Docs 功能</a>
+
+---
+
+### Windsurf
+
+通过 `@` 引用或在 `.windsurf/rules` 文件中配置 LLMs.txt 文件，以增强 Windsurf 对 YSS UI 组件的理解。
+
+**使用方法 1：临时引用**
+
+```
+@ http://192.168.164.27:3200/llms-full.txt
+```
+
+**使用方法 2：持久化配置**
+
+在项目根目录创建 `.windsurf/rules` 文件：
+
+```markdown
+# YSS UI Documentation
+
+Always reference the YSS UI documentation when working with components:
+- http://192.168.164.27:3200/llms-full.txt
+```
+
+<a href="https://docs.windsurf.com/windsurf/cascade/memories" target="_blank">详细了解 Windsurf Memories 功能</a>
+
+---
+
+### Claude Code
+
+在 Claude Code 中，将 LLMs.txt 添加到工作区的知识库（Docs / Context Files）配置中，即可在代码补全与解释时引用其中的内容。
+
+**使用方法：**
+
+1. 打开 Claude Code 设置
+2. 找到 "Docs / Context Files" 配置
+3. 添加 `http://192.168.164.27:3200/llms-full.txt`
+
+<a href="https://code.claude.com/docs" target="_blank">详细了解 Claude Code 文档上下文配置</a>
+
+---
+
+### Gemini CLI
+
+在 Gemini CLI 中，可以通过 `--context` 参数或在 `.gemini/config.json` 中指定 LLMs.txt 文件路径。
+
+**使用方法 1：命令行参数**
+
+```bash
+gemini --context http://192.168.164.27:3200/llms-full.txt "如何使用 YTable 组件？"
+```
+
+**使用方法 2：配置文件**
+
+在项目根目录创建 `.gemini/config.json`：
+
+```json
+{
+  "context": [
+    "http://192.168.164.27:3200/llms-full.txt"
+  ]
+}
+```
+
+<a href="https://ai.google.dev/gemini-api/docs" target="_blank">详细了解 Gemini CLI 上下文配置</a>
+
+---
+
+### Antigravity
+
+Antigravity（Google Gemini 官方 AI 编程助手）可以通过 `read_url_content` 工具直接读取在线文档。
+
+**方式 1：全局规则配置（强力推荐）** 🚀
+
+配置 `~/.gemini/GEMINI.md`，从根本上教会 AI "文档优先"，无需每次重复提示。
+
+```markdown
+## 核心原则：文档优先
+在回答关于 YSS UI 问题时，必须优先读取以下文档：
+http://192.168.164.27:3200/llms-full.txt
+```
+
+**方式 2：项目 README 配置**
+
+在项目根目录 `README.md` 中添加文档链接，Antigravity 读取项目概况时会自动发现。
+
+```markdown
+## 相关文档
+- YSS UI: http://192.168.164.27:3200/llms-full.txt
+```
+
+**方式 3：对话直接引用**
+
+临时询问时，直接在对话中粘贴 URL：
+
+```
+参考文档 http://192.168.164.27:3200/llms-full.txt，帮我写一个表格。
+```
+
+> **提示**：Antigravity 不支持类似 Cursor `@Docs` 的配置，主要依靠上下文理解和工具调用。
+
+---
+
+### Trae
+
+在 Trae 中，将 LLMs.txt 文件放入项目的 knowledge sources 并在设置里开启引用。
+
+**使用方法：**
+
+1. 打开 Trae 项目设置
+2. 找到 "Knowledge Sources" 配置
+3. 添加 `http://192.168.164.27:3200/llms-full.txt`
+4. 启用该知识源
+
+<a href="https://trae.ai/docs" target="_blank">详细了解 Trae 的知识源功能</a>
+
+---
+
+### Qoder
+
+在 Qoder 中，可以在 `.qoder/config.yml` 中添加 LLMs.txt 作为外部知识文件，或在对话中通过 `@docs` 进行临时引用。
+
+**使用方法 1：配置文件**
+
+在项目根目录创建 `.qoder/config.yml`：
+
+```yaml
+knowledge:
+  external_docs:
+    - url: http://192.168.164.27:3200/llms-full.txt
+      name: YSS UI Documentation
+```
+
+**使用方法 2：临时引用**
+
+```
+@docs http://192.168.164.27:3200/llms-full.txt
+```
+
+<a href="https://docs.qoder.com/" target="_blank">详细了解 Qoder 配置方法</a>
+
+---
+
+### 其他 AI 工具
+
+任何支持 LLMs.txt 的 AI 工具均可使用以上路径来更好地理解 YSS UI。
+
+<!-- ## 本地开发
+
+如果你在本地开发环境中使用 AI 工具，推荐使用完整文档：
+
+```
+http://localhost:8000/llms-full.txt
+```
+
+如果遇到上下文限制，可以降级使用：
+```
+http://localhost:8000/llms.txt -->
+```
+
+## 最佳实践建议
+
+### 选择合适的文件
+
+**大多数情况：使用 llms-full.txt** ✅
+- 开发新功能、编写业务代码
+- 需要 AI 提供准确的 API 用法
+- 学习组件库的使用方式
+
+**特殊情况：使用 llms.txt**
+- AI 工具报告上下文窗口不足
+- 只需要快速查找组件名称
+- 网络环境较差，需要减少传输量
+
+### 如何验证 AI 已正确加载文档
+
+询问 AI 一些特定的问题来验证：
+
+```
+Q: YTable 组件的 pagination 属性支持哪些配置项？
+Q: YssFormily 的 mode 属性有哪些可选值？各代表什么含义？
+Q: 如何使用 YTree 组件的搜索功能？
+```
+
+如果 AI 能准确回答这些问题并提供符合实际 API 的代码示例，说明文档已成功加载。
+
+## 自动更新
+
+LLMs.txt 文件会在每次 CI/CD 构建时自动生成和更新，确保 AI 工具始终访问到最新的文档。
+
+如需手动重新生成，可以运行：
+
+```bash
+pnpm run generate:llms
+```
+
+## 常见问题
+
+### Q: llms.txt 和 llms-full.txt 有什么区别？应该用哪个？
+
+**A:** 
+- **推荐使用 `llms-full.txt`**（71KB）- 包含完整的 API 文档、Props、Events、示例代码，让 AI 生成更准确的代码
+- `llms.txt`（1.6KB）- 仅包含组件列表和链接，适合上下文窗口受限的场景
+
+现代 AI 工具（Claude、GPT-4、Gemini 等）完全支持 `llms-full.txt` 的大小，优先使用它能获得更好的代码生成效果。
+
+### Q: 如何确认 AI 工具已成功加载文档？
+
+**A:** 
+你可以直接询问 AI 工具关于 YSS UI 特定组件的问题，如果它能准确回答并提供符合实际 API 的代码示例，说明已成功加载。
+
+### Q: 文档更新后 AI 工具没有获取到最新内容？
+
+**A:** 
+某些 AI 工具会缓存文档内容。尝试：
+1. 重新加载文档引用
+2. 清除 AI 工具缓存
+3. 使用新的会话窗口
+
+## 反馈与建议
+
+如果你在使用 AI 工具集成时遇到问题，或有改进建议，欢迎：
+
+- 提交 Issue 到项目仓库
+- 联系技术支持团队

package/template/.cursor/skills/yss-ui/assets/docs/guide/monorepo-versioning.md

@@ -0,0 +1,149 @@
+# Monorepo 版本管理说明
+
+## ⚠️ 当前方案的限制
+
+### 问题：所有包同步发版
+
+当前我们使用 `standard-version` 配置了统一的版本管理，这导致：
+
+```javascript
+// .versionrc.js
+bumpFiles: [
+  { filename: 'package.json' },
+  { filename: 'packages/components/package.json' },  // ← 所有包
+  { filename: 'packages/hooks/package.json' },       // ← 都会同步
+  { filename: 'packages/utils/package.json' },       // ← bump 版本
+  { filename: 'packages/theme/package.json' },
+]
+```
+
+**影响**：
+- ✅ 优点：版本号统一管理，简单清晰
+- ❌ 缺点：即使只修改了 `hooks`，`components`、`utils` 等所有包的版本号都会一起更新
+
+### 示例
+
+```bash
+# 提交了一个 hooks 的新功能
+git commit -m "feat(hooks): useFullscreen 新增功能"
+
+# 执行发版后
+pnpm release:minor
+
+# 结果：所有包版本号都从 1.0.3 升级到 1.0.4
+- @yss-ui/components: 1.0.3 → 1.0.4  (但实际没有修改)
+- @yss-ui/hooks: 1.0.3 → 1.0.4       (实际修改的包)
+- @yss-ui/utils: 1.0.3 → 1.0.4       (但实际没有修改)
+```
+
+---
+
+## 💡 解决方案（可选）
+
+如果需要独立管理各个包的版本号，有以下选择：
+
+### 方案 1：使用 Lerna + Conventional Commits
+
+```bash
+# 安装 Lerna
+pnpm add -D lerna
+
+# 配置 lerna.json
+{
+  "version": "independent",  // 独立版本模式
+  "command": {
+    "version": {
+      "conventionalCommits": true,
+      "message": "chore(release): publish"
+    }
+  }
+}
+
+# 发版命令
+lerna version --conventional-commits
+```
+
+**特点**：
+- ✅ 只更新有变更的包
+- ✅ 自动生成 CHANGELOG
+- ✅ 支持独立版本号
+- ❌ 配置相对复杂
+
+### 方案 2：使用 Changeset
+
+```bash
+# 安装 Changeset
+pnpm add -D @changesets/cli
+
+# 初始化
+pnpm changeset init
+
+# 工作流
+pnpm changeset       # 创建变更文件
+pnpm changeset version  # 消费变更并 bump 版本
+pnpm changeset publish  # 发布包
+```
+
+**特点**：
+- ✅ 精确控制哪些包需要发版
+- ✅ 支持独立版本号
+- ✅ 社区广泛使用
+- ❌ 需要手动创建 changeset 文件
+
+### 方案 3：保持当前方案（推荐 ⭐）
+
+如果你们的发版策略是：
+- 各个包通常一起发版
+- 版本号保持同步
+- 简化管理流程
+
+那么 **当前方案已经足够**，无需改动。
+
+---
+
+## 🔧 当前方案的使用建议
+
+### 1. 版本号语义
+
+即使所有包都同步 bump，但更新日志中会清晰标注哪个包有真实变更：
+
+```markdown
+## v1.0.4
+
+### ✨ Features
+- **[@yss-ui/hooks]** useFullscreen: 新增 Esc 键提示功能
+
+### 🐞 Bug Fixes
+(empty - components 和 utils 没有实际变更)
+```
+
+### 2. 发版时机
+
+建议按照实际需求发版：
+- **Patch** (1.0.0 → 1.0.1)：Bug 修复
+- **Minor** (1.0.0 → 1.1.0)：新功能
+- **Major** (1.0.0 → 2.0.0)：破坏性更新
+
+### 3. npm 发布策略
+
+如果发布到 npm，可以配置 Lerna 的 `--force-publish` 避免发布没有变更的包：
+
+```bash
+# 只发布有变更的包
+lerna publish from-package --no-git-tag-version
+```
+
+---
+
+## 📝 总结
+
+| 方案 | 版本管理 | 复杂度 | 适用场景 |
+|------|---------|--------|---------|
+| **当前方案** (standard-version) | 统一版本号 | ⭐ 简单 | 各包同步发版 |
+| **Lerna** | 独立版本号 | ⭐⭐⭐ 中等 | 需要独立管理版本 |
+| **Changeset** | 独立版本号 | ⭐⭐⭐⭐ 复杂 | 精确控制发版范围 |
+
+**建议**：
+- 如果当前工作流没有问题，保持现状即可
+- 如果需要独立版本管理，可以考虑引入 Changeset
+- 定期检查发版日志，确保每次发版都有相应的代码变更

package/template/.cursor/skills/yss-ui/assets/docs/guide/release-workflow.md

@@ -0,0 +1,251 @@
+# YSS UI 发版工作流指南
+
+## 📋 Commit Message 规范（必须遵守）
+
+### 格式
+
+```
+<type>(<scope>): <subject>
+
+[可选的 body]
+
+[可选的 footer]
+```
+
+### Type 类型
+
+| Type | Emoji | 说明 | 示例 |
+|------|-------|------|------|
+| `feat` | ✨ | 新功能 | `feat(@yss-ui/components): Table 新增远程筛选功能` |
+| `fix` | 🐞 | Bug 修复 | `fix(@yss-ui/hooks): useFullscreen 修复 iOS 兼容性` |
+| `docs` | 📝 | 文档更新 | `docs(components): 更新 Table 组件文档` |
+| `style` | 💅 | 代码格式 | `style(@yss-ui/components): 统一组件代码缩进` |
+| `refactor` | 🛠 | 重构 | `refactor(@yss-ui/hooks): 优化 useLoading 实现` |
+| `perf` | ⚡ | 性能优化 | `perf(@yss-ui/utils): 优化 formatDate 性能` |
+| `test` | ✅ | 测试 | `test(@yss-ui/components): 添加 Table 单元测试` |
+| `build` | 📦 | 构建系统 | `build: 升级 vite 到 5.0` |
+| `ci` | 🔧 | CI 配置 | `ci: 更新 GitLab CI 配置` |
+| `chore` | 🔨 | 其他 | `chore: 更新依赖包` |
+
+### Scope 范围
+
+- `@yss-ui/components` 或 `components` - 组件库
+- `@yss-ui/hooks` 或 `hooks` - Hooks 库
+- `@yss-ui/utils` 或 `utils` - 工具库
+- `@yss-ui/theme` 或 `theme` - 主题配置
+- `docs` - 文档
+- `scripts` - 脚本
+- `config` - 配置文件
+- `deps` - 依赖更新
+
+### 示例
+
+**✅ 正确示例**：
+
+```bash
+# 新功能
+git commit -m "feat(@yss-ui/components): Table 支持虚拟滚动"
+git commit -m "feat(@yss-ui/hooks): 新增 useDebounce Hook"
+
+# Bug 修复
+git commit -m "fix(@yss-ui/components): Table 修复空数据时的报错"
+git commit -m "fix(@yss-ui/utils): formatDate 修复时区问题"
+
+# 文档更新
+git commit -m "docs(components): 更新 Table API 文档"
+git commit -m "docs(hooks): 添加 useFullscreen 使用示例"
+
+# 重构
+git commit -m "refactor(@yss-ui/hooks): useLoading 采用模块化结构"
+
+# 多行 commit message（使用编辑器）
+```
+feat(@yss-ui/components): Table 新增远程筛选功能
+
+- 支持服务端分页
+- 支持多字段筛选
+- 新增 filterMethod 配置项
+
+Closes #123
+```
+```
+
+**❌ 错误示例**：
+
+```bash
+# 缺少 scope
+git commit -m "feat: 添加新功能"
+
+# type 错误
+git commit -m "add: 新增功能"
+
+# scope 不在枚举中
+git commit -m "feat(table): 新增功能"
+
+# 以句号结尾
+git commit -m "feat(@yss-ui/components): 新增功能。"
+```
+
+---
+
+## 🚀 发版流程
+
+### 本地发版（推荐）
+
+```bash
+# 步骤 1: 确保本地代码最新
+git pull origin main
+
+# 步骤 2: 选择发版类型
+
+# 发布补丁版本 (1.0.0 -> 1.0.1) - 修复 bug
+pnpm release:patch
+
+# 发布次版本 (1.0.0 -> 1.1.0) - 新增功能，向下兼容
+pnpm release:minor
+
+# 发布主版本 (1.0.0 -> 2.0.0) - 破坏性更新
+pnpm release:major
+
+# 首次发版（不改变版本号，只生成日志和 tag）
+pnpm release:first
+
+# 步骤 3: 脚本自动执行以下操作
+# - 根据 commit 历史生成 docs/changelog.md
+# - bump 所有 package.json 的版本号
+# - 创建 git commit 和 tag
+# - 等待你确认推送
+
+# 步骤 4: 检查生成的日志
+git diff HEAD~1 docs/changelog.md
+
+# 步骤 5: 如果满意，推送到远程
+git push --follow-tags origin main
+
+# 步骤 6: 在 GitLab UI 点击「手动发版」按钮触发 CI/CD
+```
+
+### GitLab CI 自动发版
+
+如果配置了 GitLab CI，可以自动化整个流程：
+
+```yaml
+# .gitlab-ci.yml 示例
+release:
+  stage: release
+  only:
+    - main
+  when: manual
+  script:
+    - git config user.name "GitLab CI"
+    - git config user.email "ci@gitlab.com"
+    - pnpm release  # 自动检测版本类型
+    - git push --follow-tags origin main
+```
+
+---
+
+## 📝 更新日志管理
+
+### 自动生成规则
+
+standard-version 会根据 commit message 自动生成更新日志：
+
+1. **Type 映射**：
+   - `feat` → ✨ Features
+   - `fix` → 🐞 Bug Fixes
+   - `docs` → 📝 Documentation
+   - `refactor` → 🛠 Refactoring
+   - `style` → 💅 Style
+
+2. **Scope 转换**：
+   - `@yss-ui/components` → `[@yss-ui/components]`
+   - `components` → `[@yss-ui/components]`
+   - `@yss-ui/hooks` → `[@yss-ui/hooks]`
+   - `hooks` → `[@yss-ui/hooks]`
+
+3. **分包日志**：
+   - 自动从综合日志提取各包的更新
+   - 生成 `docs/changelog/{components,hooks,utils}.md`
+
+### 手动调整日志
+
+如果自动生成的日志需要调整：
+
+```bash
+# 1. 发版后手动编辑综合日志
+vim docs/changelog.md
+
+# 2. 手动更新分包日志
+vim docs/changelog/hooks.md
+vim docs/changelog/components.md
+vim docs/changelog/utils.md
+
+# 3. 修正 commit（如果还没推送）
+git add docs/changelog*
+git commit --amend --no-edit
+
+# 4. 推送
+git push --follow-tags origin main
+```
+
+---
+
+## 🔧 常见问题
+
+### Q: Commit message 格式错误怎么办？
+
+A: Husky 的 commit-msg hook 会自动检查格式，不符合规范的 commit 会被拒绝：
+
+```bash
+$ git commit -m "add new feature"
+⧗   input: add new feature
+✖   subject may not be empty [subject-empty]
+✖   type may not be empty [type-empty]
+```
+
+修正方式：
+```bash
+git commit -m "feat(@yss-ui/components): Table 新增远程筛选功能"
+```
+
+### Q: 如何撤销错误的发版？
+
+A: 使用 Git 回退：
+
+```bash
+# 回退到上一个版本
+git reset --hard HEAD~1
+
+# 删除错误的 tag
+git tag -d v1.0.1
+git push origin :refs/tags/v1.0.1
+```
+
+### Q: 如何跳过某些 commit？
+
+A: 在 commit message 中添加 `[skip ci]` 或使用 `chore` type：
+
+```bash
+git commit -m "chore: 更新 README (不会出现在 changelog 中)"
+```
+
+### Q: 如何添加 Breaking Changes？
+
+A: 在 commit message 中添加 `BREAKING CHANGE:`：
+
+```bash
+git commit -m "feat(@yss-ui/components): 重构 Table API
+
+BREAKING CHANGE: `columns` 属性不再支持字符串数组
+"
+```
+
+---
+
+## 📚 参考资源
+
+- [Conventional Commits 规范](https://www.conventionalcommits.org/)
+- [Semantic Versioning](https://semver.org/lang/zh-CN/)
+- [standard-version 文档](https://github.com/conventional-changelog/standard-version)
+- [commitlint 文档](https://commitlint.js.org/)