@mison/ag-kit-cn 2.0.1

package/.agent/skills/tailwind-patterns/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: tailwind-patterns
+description: Tailwind CSS v4 原则。CSS-first 配置、容器查询、现代化模式与 Design Token（设计令牌）架构。
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Tailwind CSS 模式（v4，2025）
+
+> 采用 CSS 原生配置的现代 Utility-first CSS（工具优先）。
+
+---
+
+## 1. Tailwind v4 架构
+
+### 相比 v3 的变化
+
+| v3（Legacy） | v4（Current） |
+|-------------|---------------|
+| `tailwind.config.js` | 基于 CSS 的 `@theme` 指令 |
+| PostCSS plugin | Oxide 引擎（约 10x 更快） |
+| JIT mode | 原生内建、始终开启 |
+| Plugin system | CSS 原生能力增强 |
+| `@apply` directive | 仍可用，但不推荐重度依赖 |
+
+### v4 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **CSS-first（CSS 优先）** | 配置写在 CSS 中，而不是 JavaScript |
+| **Oxide Engine** | Rust 编译引擎，速度更快 |
+| **Native Nesting** | 不依赖 PostCSS 的 CSS 嵌套 |
+| **CSS Variables** | 设计 token 通过 `--*` 变量暴露 |
+
+---
+
+## 2. 基于 CSS 的配置
+
+### 主题定义
+
+```
+@theme {
+  /* Colors - use semantic names */
+  --color-primary: oklch(0.7 0.15 250);
+  --color-surface: oklch(0.98 0 0);
+  --color-surface-dark: oklch(0.15 0 0);
+  
+  /* Spacing scale */
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 2rem;
+  
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+}
+```
+
+### 何时扩展与覆盖
+
+| 动作 | 适用场景 |
+|------|----------|
+| **Extend** | 在保留默认值的同时新增 |
+| **Override** | 需要整体替换默认刻度体系 |
+| **Semantic tokens** | 采用项目语义命名（primary、surface） |
+
+---
+
+## 3. 容器查询（v4 原生）
+
+### Breakpoint 与 Container 的区别
+
+| 类型 | 响应对象 |
+|------|----------|
+| **Breakpoint（断点）** (`md:`) | 视口宽度（viewport） |
+| **Container（容器）** (`@container`) | 父容器宽度 |
+
+### 容器查询用法
+
+| 模式 | 类名 |
+|------|------|
+| 定义容器 | 在父元素上添加 `@container` |
+| 容器断点 | 在子元素上使用 `@sm:`、`@md:`、`@lg:` |
+| 命名容器 | `@container/card` 提升语义与精确性 |
+
+### 何时使用
+
+| 场景 | 选择 |
+|------|------|
+| 页面级布局 | 视口断点 |
+| 组件级响应式 | 容器查询 |
+| 可复用组件 | 容器查询（与上下文解耦） |
+
+---
+
+## 4. 响应式设计
+
+### 断点系统
+
+| 前缀 | 最小宽度 | 目标 |
+|------|----------|------|
+| (none) | 0px | Mobile-first 基础样式 |
+| `sm:` | 640px | 大手机/小平板 |
+| `md:` | 768px | 平板 |
+| `lg:` | 1024px | 笔记本 |
+| `xl:` | 1280px | 桌面端 |
+| `2xl:` | 1536px | 大屏桌面 |
+
+### Mobile-first 原则
+
+1. 先写移动端基础样式（无前缀）
+2. 再用前缀添加大屏覆盖规则
+3. 示例：`w-full md:w-1/2 lg:w-1/3`
+
+---
+
+## 5. 深色模式
+
+### 配置策略
+
+| 方法 | 行为 | 适用场景 |
+|------|------|----------|
+| `class` | 通过 `.dark` 类切换 | 需要手动主题切换 |
+| `media` | 跟随系统主题 | 不提供用户开关 |
+| `selector` | 自定义选择器（v4） | 复杂多主题体系 |
+
+### 深色模式示例
+
+| 元素 | 浅色 | 深色 |
+|------|------|------|
+| Background | `bg-white` | `dark:bg-zinc-900` |
+| Text | `text-zinc-900` | `dark:text-zinc-100` |
+| Borders | `border-zinc-200` | `dark:border-zinc-700` |
+
+---
+
+## 6. 现代布局模式
+
+### Flexbox 模式
+
+| 模式 | 类名 |
+|------|------|
+| 双轴居中 | `flex items-center justify-center` |
+| 纵向堆叠 | `flex flex-col gap-4` |
+| 横向排列 | `flex gap-4` |
+| 两端对齐 | `flex justify-between items-center` |
+| 自动换行网格 | `flex flex-wrap gap-4` |
+
+### Grid 模式
+
+| 模式 | 类名 |
+|------|------|
+| Auto-fit 响应式网格 | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
+| 非对称（Bento） | `grid grid-cols-3 grid-rows-2` + spans |
+| 侧栏布局 | `grid grid-cols-[auto_1fr]` |
+
+> **说明：** 优先使用非对称/Bento（便当格）布局，避免千篇一律的对称三列网格。
+
+---
+
+## 7. 现代颜色系统
+
+### OKLCH 与 RGB/HSL
+
+| 格式 | 优势 |
+|------|------|
+| **OKLCH** | 感知均匀，更利于设计一致性 |
+| **HSL** | 色相/饱和度语义直观 |
+| **RGB** | 兼容性传统且广泛 |
+
+### 颜色 Token 架构
+
+| 层级 | 示例 | 作用 |
+|------|------|------|
+| **Primitive** | `--blue-500` | 原始色值层 |
+| **Semantic** | `--color-primary` | 语义命名层 |
+| **Component** | `--button-bg` | 组件局部层 |
+
+---
+
+## 8. 排版系统
+
+### 字体栈模式
+
+| 类型 | 推荐 |
+|------|------|
+| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
+| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
+| Display | `'Outfit', 'Poppins', sans-serif` |
+
+### 字号刻度
+
+| 类名 | 大小 | 用途 |
+|------|------|------|
+| `text-xs` | 0.75rem | 标签、说明文字 |
+| `text-sm` | 0.875rem | 次级文本 |
+| `text-base` | 1rem | 正文 |
+| `text-lg` | 1.125rem | 引导性文本 |
+| `text-xl`+ | 1.25rem+ | 标题 |
+
+---
+
+## 9. 动画与过渡
+
+### 内置动画
+
+| 类名 | 效果 |
+|------|------|
+| `animate-spin` | 持续旋转 |
+| `animate-ping` | 注意力脉冲效果 |
+| `animate-pulse` | 轻微透明度脉冲 |
+| `animate-bounce` | 弹跳效果 |
+
+### 过渡模式
+
+| 模式 | 类名 |
+|------|------|
+| 所有属性 | `transition-all duration-200` |
+| 指定属性 | `transition-colors duration-150` |
+| 缓动函数 | `ease-out` 或 `ease-in-out` |
+| Hover 动效 | `hover:scale-105 transition-transform` |
+
+---
+
+## 10. 组件抽取
+
+### 何时抽取
+
+| 信号 | 动作 |
+|------|------|
+| 同一类组合出现 3 次以上 | 抽为组件 |
+| 状态变体复杂 | 抽为组件 |
+| 设计系统核心元素 | 抽取并补文档 |
+
+### 抽取方式
+
+| 方法 | 适用场景 |
+|------|----------|
+| **React/Vue component** | 需要动态逻辑或 JS 行为 |
+| **@apply in CSS** | 静态样式、无需 JS |
+| **Design tokens（设计令牌）** | 复用基础值（颜色/间距/字号） |
+
+---
+
+## 11. 反模式
+
+| ❌ 不要这样做 | ✅ 推荐做法 |
+|-------------|------------|
+| 到处用任意值（arbitrary values） | 使用设计系统刻度 |
+| 滥用 `!important` | 正确处理样式优先级 |
+| 内联 `style=` | 优先使用 utilities |
+| 重复超长 class 列表 | 抽取组件 |
+| v3/v4 配置混用 | 完整迁移到 CSS-first |
+| 重度使用 `@apply` | 优先组件化抽象 |
+
+---
+
+## 12. 性能原则
+
+| 原则 | 实现方式 |
+|------|----------|
+| **清理未使用样式** | v4 默认自动处理 |
+| **避免动态 class 拼接** | 不要用模板字符串生成类名 |
+| **使用 Oxide** | v4 默认启用，速度更快 |
+| **构建缓存** | 在 CI/CD 中启用缓存 |
+
+---
+
+> **牢记：** Tailwind v4 是 CSS-first。应充分使用 CSS Variables、Container Queries 与原生能力。配置文件已是可选项。

package/.agent/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: tdd-workflow
+description: TDD（测试驱动开发）工作流原则。红-绿-重构循环。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# TDD（测试驱动开发）工作流
+
+> 先写测试，后写代码。
+
+---
+
+## 1. TDD 核心循环
+
+```
+🔴 红（RED）→ 编写一个失败的测试
+    ↓
+🟢 绿（GREEN）→ 编写最少量的代码使测试通过
+    ↓
+🔵 重构（REFACTOR）→ 优化代码结构与质量
+    ↓
+   循环往复...
+```
+
+---
+
+## 2. TDD 三大法则
+
+1. **除非是为了使一个失败的单元测试通过，否则不允许编写任何生产代码。**
+2. **只允许编写刚好能够证明失败的测试（编译失败也算失败）。**
+3. **只允许编写刚好能够使当前失败测试通过的生产代码。**
+
+---
+
+## 3. “红（RED）”阶段准则
+
+### 编写重点
+
+| 关注点                | 示例                         |
+| --------------------- | ---------------------------- |
+| Behavior（行为）       | “应当能够相加两个数字”       |
+| Edge Cases（边缘情况） | “应当能够处理空输入”         |
+| 错误状态              | “遇到无效数据时应当抛出异常” |
+
+### “红”阶段规则
+
+- 测试**必须**先失败。
+- 测试名称应清晰描述预期的行为。
+- 每个测试（最好）仅包含一个 Assertion（断言）。
+
+---
+
+## 4. “绿（GREEN）”阶段准则
+
+### 最少代码原则
+
+| 原则         | 含义                                        |
+| ------------ | ------------------------------------------- |
+| **YAGNI**    | You Aren't Gonna Need It（你不会需要它） |
+| **最简方案** | 编写能让测试通过的最少代码                  |
+| **暂不优化** | 此时只求“跑通”，不求“精炼”                  |
+
+### “绿”阶段规则
+
+- 不要编写多余的代码。
+- 暂时不要进行性能优化。
+- 仅仅是为了通过测试，不多做一点。
+
+---
+
+## 5. “重构（REFACTOR）”阶段准则
+
+### 优化方向
+
+| 领域     | 动作                |
+| -------- | ------------------- |
+| 重复逻辑 | 提取公共函数/代码块 |
+| 命名规范 | 使代码意图更加清晰  |
+| 代码结构 | 改善组织架构        |
+| 复杂度   | 简化逻辑判断        |
+
+### 重构规则
+
+- **所有测试必须保持绿色。**
+- 采取小步快跑的增量式改动。
+- 每次重构之后都进行 Commit（提交）。
+
+---
+
+## 6. AAA 模式
+
+每个测试均应遵循 AAA（Arrange-Act-Assert，准备-执行-断言）：
+
+| 步骤               | 目的                 |
+| ------------------ | -------------------- |
+| **Arrange（准备）** | 初始化测试数据与环境 |
+| **Act（执行）**     | 执行被测代码逻辑     |
+| **Assert（断言）**  | 验证结果是否符合预期 |
+
+---
+
+## 7. 何时使用 TDD
+
+| 场景               | TDD 价值                |
+| ------------------ | ----------------------- |
+| 新功能开发         | 极高                    |
+| Bug（缺陷）修复     | 极高（先写复现测试）     |
+| 复杂逻辑实现       | 极高                    |
+| Spike（探索性研究） | 较低（研究完后再补 TDD） |
+| UI（用户界面）布局调试 | 较低                 |
+
+---
+
+## 8. 测试优先级
+
+| 优先级 | 测试类型 |
+|----------|-----------|
+| 1 | Happy path（正常路径） |
+| 2 | Error cases（错误处理） |
+| 3 | Edge cases（边界情况） |
+| 4 | Performance（性能） |
+
+---
+
+## 9. 应避免的反模式
+
+| ❌ 禁止（Don't）        | ✅ 推荐（Do）               |
+| ---------------------- | -------------------------- |
+| 跳过“红”阶段直接写代码 | 亲眼见证测试失败后再写代码 |
+| 先写代码后补测试       | 先写测试作为规格说明       |
+| 初期就进行过度工程     | 保持简单，仅满足当前测试   |
+| 一个测试包含过多断言   | 每个测试仅验证一个行为     |
+| 测试内部实现细节       | 测试对外的行为表现         |
+
+---
+
+## 10. AI 增强型 TDD 协作模式
+
+### Multi-Agent（多智能体）编排视角
+
+| Agent | 角色 |
+|-------|------|
+| Agent A | 编写失败测试（RED） |
+| Agent B | 编写实现使其通过（GREEN） |
+| Agent C | 进行优化（REFACTOR） |
+
+---
+
+> **记住：** 测试就是规格。如果你写不出测试，说明你还没有真正理解需求。

package/.agent/skills/testing-patterns/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: testing-patterns
+description: 测试模式与原则。覆盖 Unit（单元测试）、Integration（集成测试）与 Mock（模拟）策略。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# 测试模式
+
+> 构建可靠测试体系的原则。
+
+---
+
+## 1. 测试金字塔
+
+```
+        /\          E2E（端到端，少量）
+       /  \         关键流程
+      /----\
+     /      \       Integration（集成测试，中量）
+    /--------\      API、数据库查询
+   /          \
+  /------------\    Unit（单元测试，大量）
+                    函数、类等基础逻辑
+```
+
+---
+
+## 2. AAA 模式
+
+| 步骤 | 目的 |
+|------|------|
+| **Arrange（准备）** | 准备测试数据与上下文 |
+| **Act（执行）** | 执行被测代码 |
+| **Assert（断言）** | 断言结果是否符合预期 |
+
+---
+
+## 3. 测试类型选择
+
+### 各类型使用时机
+
+| 类型 | 适用场景 | 速度 |
+|------|----------|------|
+| **Unit（单元测试）** | 纯函数、核心逻辑 | 快（<50ms） |
+| **Integration（集成测试）** | API、数据库、服务协作 | 中 |
+| **E2E（端到端测试）** | 关键用户流程 | 慢 |
+
+---
+
+## 4. 单元测试原则
+
+### 优秀单元测试特征
+
+| 原则 | 含义 |
+|------|------|
+| Fast（快速） | 单个用例 < 100ms |
+| Isolated（隔离） | 不依赖外部系统 |
+| Repeatable（可重复） | 每次结果一致 |
+| Self-checking（自校验） | 无需手工验证 |
+| Timely（及时） | 与代码同步编写 |
+
+### 单元测试该测什么
+
+| 应该测试 | 不应测试 |
+|----------|---------|
+| 业务逻辑 | 框架内部实现 |
+| 边界条件 | 第三方库本身 |
+| 错误处理 | 过于简单的 getter（取值器） |
+
+---
+
+## 5. 集成测试原则
+
+### 重点覆盖
+
+| 领域 | 关注点 |
+|------|--------|
+| API 端点 | 请求/响应链路 |
+| 数据库 | 查询与事务行为 |
+| 外部服务 | 契约一致性 |
+
+### Setup/Teardown（准备/清理）约定
+
+| 阶段 | 动作 |
+|------|------|
+| Before All（全局前置） | 建立资源连接 |
+| Before Each（用例前置） | 重置状态 |
+| After Each（用例清理） | 执行清理 |
+| After All（全局清理） | 释放连接 |
+
+---
+
+## 6. Mock（模拟）原则
+
+### 何时需要 Mock
+
+| 应该 Mock | 不应 Mock |
+|----------|----------|
+| 外部 API | 被测代码本身 |
+| 数据库（单元测试） | 简单依赖对象 |
+| 时间/随机数 | 纯函数 |
+| 网络请求 | 内存型替代实现 |
+
+### Mock 类型
+
+| 类型 | 用途 |
+|------|------|
+| Stub（桩） | 返回固定值 |
+| Spy（监视） | 跟踪调用行为 |
+| Mock（模拟） | 预设期望并校验 |
+| Fake（伪实现） | 提供简化实现 |
+
+---
+
+## 7. 测试组织方式
+
+### 命名规范
+
+| 模式 | 示例 |
+|------|------|
+| Should（行为式） | "should return error when..." |
+| When（条件式） | "when user not found..." |
+| Given-When-Then（前提-条件-结果） | "given X, when Y, then Z" |
+
+### 分组方式
+
+| 层级 | 用途 |
+|------|------|
+| describe（分组） | 归类相关测试 |
+| it/test（用例） | 单个测试用例 |
+| beforeEach（前置） | 共享初始化逻辑 |
+
+---
+
+## 8. 测试数据策略
+
+### 常见策略
+
+| 方法 | 用途 |
+|------|------|
+| Factories（工厂） | 动态生成测试数据 |
+| Fixtures（夹具） | 预定义数据集 |
+| Builders（构建器） | 链式构建对象 |
+
+### 基本原则
+
+- 使用贴近真实的数据
+- 非关键字段可随机化（faker 数据生成库）
+- 共享公共 fixtures（预置数据）
+- 保持最小必要数据集
+
+---
+
+## 9. 最佳实践
+
+| 实践 | 目的 |
+|------|------|
+| 单测关注单一断言目标 | 失败原因更清晰 |
+| 用例相互独立 | 避免顺序依赖 |
+| 保持测试快速 | 能高频执行 |
+| 命名具描述性 | 测试即文档 |
+| 严格清理状态 | 避免副作用污染 |
+
+---
+
+## 10. 反模式
+
+| ❌ 禁止（Don't） | ✅ 推荐（Do） |
+|-----------------|-------------|
+| 测实现细节 | 测可观察行为 |
+| 重复测试代码 | 使用 factories（工厂）复用 |
+| 测试前置过于复杂 | 简化或拆分场景 |
+| 忽略 flaky（不稳定）测试 | 修复根因 |
+| 不做清理 | 重置状态 |
+
+---
+
+> **牢记：** 测试本身就是文档。如果别人无法通过测试理解代码行为，就应该重写测试。