@mison/ag-kit-cn 2.0.1

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

@@ -0,0 +1,84 @@
+---
+name: api-patterns
+description: API design principles and decision-making（API 设计原则与决策逻辑）。REST vs GraphQL vs tRPC selection（选择）、response formats（响应格式）、versioning（版本控制）、pagination（分页）。
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# API Patterns（API 模式）
+
+> API design principles and decision-making for 2025（2025 年 API 设计原则与决策逻辑）。
+> **Learn to THINK, not copy fixed patterns（学习如何思考，而非机械复制固定模式）。**
+
+## 🎯 选择性阅读规则（Selective Reading Rule）
+
+**仅阅读与当前请求相关的文件（Read ONLY files relevant to the request）！** 查阅内容地图并定位所需章节（Check the content map, find what you need）。
+
+---
+
+## 📑 内容地图（Content Map）
+
+| File（文件） | Description（描述） | When to Read（阅读时机） |
+| ---- | ---- | -------- |
+| `api-style.md` | REST vs GraphQL vs tRPC decision tree（决策树） | Choosing API type（选择 API 类型时） |
+| `rest.md` | Resource naming, HTTP methods, status codes（资源命名/HTTP 方法/状态码） | Designing REST API（设计 REST API 时） |
+| `response.md` | Envelope pattern, error format, pagination（信封模式/错误格式/分页） | Response structure（确定响应结构时） |
+| `graphql.md` | Schema design, when to use, security（模式设计/使用场景/安全性） | Considering GraphQL（考虑 GraphQL 时） |
+| `trpc.md` | TypeScript monorepo, type safety（TS 单仓/类型安全） | TS fullstack projects（TS 全栈项目） |
+| `versioning.md` | URI/Header/Query versioning（URI/请求头/查询参数版本控制） | API evolution planning（规划 API 演进） |
+| `auth.md` | JWT, OAuth, Passkey, API Keys（认证方案） | Auth pattern selection（选择认证模式） |
+| `rate-limiting.md` | Token bucket, sliding window（令牌桶/滑动窗口） | API protection（API 保护机制） |
+| `documentation.md` | OpenAPI/Swagger best practices（文档规范） | Documentation（编写 API 文档） |
+| `security-testing.md` | OWASP API Top 10, auth/authz testing（认证/授权测试） | Security audits（安全审计） |
+
+---
+
+## 🔗 相关技能（Related Skills）
+
+| Need（需求） | Skill（技能） |
+| ---- | ------------ |
+| API implementation（API 落地实现） | `@[skills/backend-development]` |
+| Data structure（数据库结构设计） | `@[skills/database-design]` |
+| Security details（安全加固细节） | `@[skills/security-hardening]` |
+
+---
+
+## ✅ 决策检查清单（Decision Checklist）
+
+设计 API 之前（Before designing an API）：
+
+- [ ] **Asked user about API consumers?（是否询问 API 消费者？）**
+- [ ] **Chosen API style for THIS context?（是否为当前上下文选择 API 风格？）** (REST/GraphQL/tRPC)
+- [ ] **Defined consistent response format?（是否定义统一响应格式？）**
+- [ ] **Planned versioning strategy?（是否规划版本控制策略？）**
+- [ ] **Considered authentication needs?（是否考虑认证需求？）**
+- [ ] **Planned rate limiting?（是否规划频率限制？）**
+- [ ] **Documentation approach defined?（是否定义文档方案？）**
+
+---
+
+## ❌ 反模式（Anti-Patterns）
+
+**不要（DON'T）：**
+
+- 任何场景都默认 REST（Default to REST for everything）。
+- REST 端点使用动词，如 `/getUsers`（Use verbs in REST endpoints）。
+- 响应格式不一致（Return inconsistent response formats）。
+- 向客户端暴露内部错误（Expose internal errors to clients）。
+- 忽略频率限制（Skip rate limiting）。
+
+**推荐做法（DO）：**
+
+- 根据上下文选择 API 风格（Choose API style based on context）。
+- 先询问客户端需求（Ask about client requirements）。
+- 编写详尽文档（Document thoroughly）。
+- 使用合适的 HTTP 状态码（Use appropriate status codes）。
+
+---
+
+## 运行脚本（Script）
+
+| Script（脚本） | Purpose（用途） | Command（命令） |
+| ---- | ---- | ---- |
+| `scripts/api_validator.py` | API endpoint validation（API 端点校验） | `python scripts/api_validator.py <project_path>`（项目路径） |
+
+---

package/.agent/skills/api-patterns/api-style.md

@@ -0,0 +1,42 @@
+# API 风格选择（2025）
+
+> REST vs GraphQL vs tRPC —— 在什么情况下选择哪种？
+
+## 决策树
+
+```
+谁是 API 消费者？
+│
+├── 公共 API / 多平台支持
+│   └── REST + OpenAPI（接口规范，最广泛的兼容性）
+│
+├── 数据需求复杂 / 多个前端
+│   └── GraphQL（灵活的查询）
+│
+├── TypeScript（TS）前端 + 后端（monorepo，单仓）
+│   └── tRPC（端到端类型安全）
+│
+├── 实时性 / 事件驱动
+│   └── WebSocket + AsyncAPI（异步 API 规范）
+│
+└── 内部微服务
+    └── gRPC（追求性能）或 REST（追求简单）
+```
+
+## 对比
+
+| 因素 | REST | GraphQL | tRPC |
+| :--- | :--- | :------ | :--- |
+| **最佳适用** | 公共 API | 复杂应用 | TS monorepos（TypeScript 单仓） |
+| **学习曲线** | 低 | 中 | 低（如果是 TS 用户） |
+| **过度/不足获取** | 常见（over/under fetching） | 已解决 | 已解决 |
+| **类型安全** | 手动（OpenAPI） | 基于 Schema（模式） | 自动 |
+| **缓存** | HTTP 原生支持 | 复杂 | 基于客户端 |
+
+## 选择问题
+
+1. 谁是 API 消费者？
+2. 前端是 TypeScript（TS）吗？
+3. 数据关系有多复杂？
+4. 缓存是否至关重要？
+5. 是公共 API 还是内部 API？

package/.agent/skills/api-patterns/auth.md

@@ -0,0 +1,24 @@
+# 认证模式
+
+> 根据用例选择认证模式。
+
+## 选择指南
+
+| 模式 | 最佳适用场景 |
+| :--- | :----------- |
+| **JWT（JSON Web Token）** | 无状态、微服务架构 |
+| **Session（会话）** | 传统 Web 应用、简单场景 |
+| **OAuth 2.0（授权协议）** | 第三方集成 |
+| **API Keys（API 密钥）** | 服务器间通信、公共 API |
+| **Passkey（通行密钥）** | 现代无密码认证（2025+） |
+
+## JWT（JSON Web Token）原则
+
+```
+重要事项:
+├── 始终验证签名
+├── 检查过期时间
+├── 仅包含最小必要的声明（Claims）
+├── 使用短过期时间 + 刷新令牌（Refresh tokens）
+└── 绝不在 JWT 中存储敏感数据
+```

package/.agent/skills/api-patterns/documentation.md

@@ -0,0 +1,26 @@
+# API 文档编写原则
+
+> 好的文档 = 快乐的开发者 = API 被广泛采用。
+
+## OpenAPI/Swagger 精要
+
+```
+应包含:
+├── 所有端点（Endpoints）及其示例
+├── 请求/响应 Schema（模式）
+├── 认证要求
+├── 错误响应格式
+└── 速率限制信息
+```
+
+## 优质文档包含
+
+```
+核心要素:
+├── 快速开始 / 入门指南
+├── 认证指南
+├── 完整的 API 参考手册
+├── 错误处理指南
+├── 代码示例（多种语言）
+└── 更新日志（Changelog）
+```

package/.agent/skills/api-patterns/graphql.md

@@ -0,0 +1,41 @@
+# GraphQL（图查询语言）原则
+
+> 为复杂、互联的数据提供灵活的查询。
+
+## 何时使用
+
+```
+✅ 适用场景:
+├── 数据关系复杂且互相连接
+├── 有多个前端平台
+├── 客户端需要灵活的查询
+├── 数据需求在不断演进
+└── 减少“过度获取（over-fetching）”非常重要
+
+❌ 不适用场景:
+├── 简单的 CRUD（增删改查）操作
+├── 包含大量的文件上传
+├── HTTP（超文本传输协议）级缓存非常重要
+└── 团队对 GraphQL（图查询语言）不熟悉
+```
+
+## Schema（模式）设计原则
+
+```
+设计原则:
+├── 以图（Graph）的方式思考，而不是端点（Endpoints）
+├── 设计要有可演进性（通常无版本号）
+├── 使用 Connections（连接）模式进行分页
+├── 类型定义要具体（不要使用通用的 "data"）
+└── 深思熟虑地处理空值（Nullability）
+```
+
+## 安全考量
+
+```
+防范措施:
+├── 查询深度攻击（Query depth attacks） → 设置最大深度
+├── 查询复杂度（Query complexity） → 计算查询成本
+├── 批量滥用（Batching abuse） → 限制批量大小
+└── 内省（Introspection） → 生产环境禁用
+```

package/.agent/skills/api-patterns/rate-limiting.md

@@ -0,0 +1,31 @@
+# 限流原则
+
+> 保护你的 API（接口）免受滥用和过载。
+
+## 为什么要限流
+
+```
+防范措施:
+├── 暴力破解攻击
+├── 资源耗尽
+├── 成本超支（如果是按量计费）
+└── 不公平的使用
+```
+
+## 策略选择
+
+| 类型 | 机制 | 适用场景 |
+| :--- | :--- | :------- |
+| **令牌桶（Token bucket）** | 允许突发流量，随时间填充 | 大多数 API |
+| **滑动窗口（Sliding window）** | 平滑分布 | 严格限制 |
+| **固定窗口（Fixed window）** | 每个窗口的简单计数器 | 基本需求 |
+
+## 响应头
+
+```
+要在响应头中包含:
+├── X-RateLimit-Limit（最大请求数）
+├── X-RateLimit-Remaining（剩余请求数）
+├── X-RateLimit-Reset（重置时间）
+└── 超出限制时返回 429
+```

package/.agent/skills/api-patterns/response.md

@@ -0,0 +1,37 @@
+# 响应格式原则
+
+> 一致性是关键——选择一种格式并坚持使用。
+
+## 常见模式
+
+```
+请选择一种:
+├── 信封模式（Envelope pattern）: { success, data, error }
+├── 直接返回数据（Direct data）: 仅返回资源内容
+└── HAL/JSON:API（超媒体模式）
+```
+
+## 错误响应
+
+```
+应包含:
+├── 错误代码（Error code）: 用于程序化处理
+├── 用户消息（User message）: 用于界面显示
+├── 详细信息（Details）: 用于调试、字段级错误
+├── 请求 ID（Request ID）: 用于支持查询
+└── 绝不包含内部实现细节（安全隐患）
+```
+
+## 分页类型
+
+| 类型 | 最佳适用场景 | 权衡 |
+| :--- | :----------- | :---------------- |
+| **Offset（偏移量）** | 简单，支持跳转页码 | 大数据集性能差 |
+| **Cursor（游标）** | 大数据集，无限滚动 | 无法跳转特定页 |
+| **Keyset（键集）** | 性能至关重要 | 需要可排序的键 |
+
+### 选择问题
+
+1. 数据集有多大？
+2. 用户需要跳转到特定页面吗？
+3. 数据是否频繁变化？

package/.agent/skills/api-patterns/rest.md

@@ -0,0 +1,40 @@
+# REST（表述性状态转移）原则
+
+> 基于资源的 API（接口）设计——使用名词而非动词。
+
+## 资源命名规则
+
+```
+设计原则:
+├── 使用名词，而非动词（资源，而非动作）
+├── 使用复数形式（/users 而不是 /user）
+├── 使用小写，连字符分隔（/user-profiles）
+├── 使用嵌套表示关系（/users/123/posts）
+└── 保持浅层嵌套（建议最多 3 层）
+```
+
+## HTTP（超文本传输协议）方法选择
+
+| 方法 | 目的 | 是否幂等（Idempotent）？ | 是否包含请求体（Body）？ |
+| :--- | :--- | :--------- | :----------------------- |
+| **GET** | 读取资源 | 是 | 否 |
+| **POST** | 创建新资源 | 否 | 是 |
+| **PUT** | 替换整个资源 | 是 | 是 |
+| **PATCH** | 部分更新资源 | 否 | 是 |
+| **DELETE** | 删除资源 | 是 | 否 |
+
+## 状态码选择
+
+| 场景 | 代码 | 原因 |
+| :--- | :--- | :--- |
+| 成功（读取） | 200 | 标准成功响应 |
+| 已创建 | 201 | 新资源已创建 |
+| 无内容 | 204 | 操作成功，无需返回内容 |
+| 错误请求 | 400 | 请求格式错误 |
+| 未授权 | 401 | 缺少认证信息或无效 |
+| 禁止访问 | 403 | 认证有效，但无权限 |
+| 未找到 | 404 | 资源不存在 |
+| 冲突 | 409 | 状态冲突（如重复资源） |
+| 验证错误 | 422 | 语法正确，但数据无效 |
+| 速率限制 | 429 | 请求过多 |
+| 服务器错误 | 500 | 服务器内部错误 |

package/.agent/skills/api-patterns/scripts/api_validator.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+API Validator - Checks API endpoints for best practices.
+Validates OpenAPI specs, response formats, and common issues.
+"""
+import sys
+import json
+import re
+from pathlib import Path
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+def find_api_files(project_path: Path) -> list:
+    """Find API-related files."""
+    patterns = [
+        "**/*api*.ts", "**/*api*.js", "**/*api*.py",
+        "**/routes/*.ts", "**/routes/*.js", "**/routes/*.py",
+        "**/controllers/*.ts", "**/controllers/*.js",
+        "**/endpoints/*.ts", "**/endpoints/*.py",
+        "**/*.openapi.json", "**/*.openapi.yaml",
+        "**/swagger.json", "**/swagger.yaml",
+        "**/openapi.json", "**/openapi.yaml"
+    ]
+    
+    files = []
+    for pattern in patterns:
+        files.extend(project_path.glob(pattern))
+    
+    # Exclude node_modules, etc.
+    return [f for f in files if not any(x in str(f) for x in ['node_modules', '.git', 'dist', 'build', '__pycache__'])]
+
+def check_openapi_spec(file_path: Path) -> dict:
+    """Check OpenAPI/Swagger specification."""
+    issues = []
+    passed = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        
+        if file_path.suffix == '.json':
+            spec = json.loads(content)
+        else:
+            # Basic YAML check
+            if 'openapi:' in content or 'swagger:' in content:
+                passed.append("[OK] OpenAPI/Swagger version defined")
+            else:
+                issues.append("[X] No OpenAPI version found")
+            
+            if 'paths:' in content:
+                passed.append("[OK] Paths section exists")
+            else:
+                issues.append("[X] No paths defined")
+            
+            if 'components:' in content or 'definitions:' in content:
+                passed.append("[OK] Schema components defined")
+            
+            return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'openapi'}
+        
+        # JSON OpenAPI checks
+        if 'openapi' in spec or 'swagger' in spec:
+            passed.append("[OK] OpenAPI version defined")
+        
+        if 'info' in spec:
+            if 'title' in spec['info']:
+                passed.append("[OK] API title defined")
+            if 'version' in spec['info']:
+                passed.append("[OK] API version defined")
+            if 'description' not in spec['info']:
+                issues.append("[!] API description missing")
+        
+        if 'paths' in spec:
+            path_count = len(spec['paths'])
+            passed.append(f"[OK] {path_count} endpoints defined")
+            
+            # Check each path
+            for path, methods in spec['paths'].items():
+                for method, details in methods.items():
+                    if method in ['get', 'post', 'put', 'patch', 'delete']:
+                        if 'responses' not in details:
+                            issues.append(f"[X] {method.upper()} {path}: No responses defined")
+                        if 'summary' not in details and 'description' not in details:
+                            issues.append(f"[!] {method.upper()} {path}: No description")
+        
+    except Exception as e:
+        issues.append(f"[X] Parse error: {e}")
+    
+    return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'openapi'}
+
+def check_api_code(file_path: Path) -> dict:
+    """Check API code for common issues."""
+    issues = []
+    passed = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        
+        # Check for error handling
+        error_patterns = [
+            r'try\s*{', r'try:', r'\.catch\(',
+            r'except\s+', r'catch\s*\('
+        ]
+        has_error_handling = any(re.search(p, content) for p in error_patterns)
+        if has_error_handling:
+            passed.append("[OK] Error handling present")
+        else:
+            issues.append("[X] No error handling found")
+        
+        # Check for status codes
+        status_patterns = [
+            r'status\s*\(\s*\d{3}\s*\)', r'statusCode\s*[=:]\s*\d{3}',
+            r'HttpStatus\.', r'status_code\s*=\s*\d{3}',
+            r'\.status\(\d{3}\)', r'res\.status\('
+        ]
+        has_status = any(re.search(p, content) for p in status_patterns)
+        if has_status:
+            passed.append("[OK] HTTP status codes used")
+        else:
+            issues.append("[!] No explicit HTTP status codes")
+        
+        # Check for validation
+        validation_patterns = [
+            r'validate', r'schema', r'zod', r'joi', r'yup',
+            r'pydantic', r'@Body\(', r'@Query\('
+        ]
+        has_validation = any(re.search(p, content, re.I) for p in validation_patterns)
+        if has_validation:
+            passed.append("[OK] Input validation present")
+        else:
+            issues.append("[!] No input validation detected")
+        
+        # Check for auth middleware
+        auth_patterns = [
+            r'auth', r'jwt', r'bearer', r'token',
+            r'middleware', r'guard', r'@Authenticated'
+        ]
+        has_auth = any(re.search(p, content, re.I) for p in auth_patterns)
+        if has_auth:
+            passed.append("[OK] Authentication/authorization detected")
+        
+        # Check for rate limiting
+        rate_patterns = [r'rateLimit', r'throttle', r'rate.?limit']
+        has_rate = any(re.search(p, content, re.I) for p in rate_patterns)
+        if has_rate:
+            passed.append("[OK] Rate limiting present")
+        
+        # Check for logging
+        log_patterns = [r'console\.log', r'logger\.', r'logging\.', r'log\.']
+        has_logging = any(re.search(p, content) for p in log_patterns)
+        if has_logging:
+            passed.append("[OK] Logging present")
+        
+    except Exception as e:
+        issues.append(f"[X] Read error: {e}")
+    
+    return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'code'}
+
+def main():
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    project_path = Path(target)
+    
+    print("\n" + "=" * 60)
+    print("  API VALIDATOR - Endpoint Best Practices Check")
+    print("=" * 60 + "\n")
+    
+    api_files = find_api_files(project_path)
+    
+    if not api_files:
+        print("[!] No API files found.")
+        print("   Looking for: routes/, controllers/, api/, openapi.json/yaml")
+        sys.exit(0)
+    
+    results = []
+    for file_path in api_files[:15]:  # Limit
+        if 'openapi' in file_path.name.lower() or 'swagger' in file_path.name.lower():
+            result = check_openapi_spec(file_path)
+        else:
+            result = check_api_code(file_path)
+        results.append(result)
+    
+    # Print results
+    total_issues = 0
+    total_passed = 0
+    
+    for result in results:
+        print(f"\n[FILE] {result['file']} [{result['type']}]")
+        for item in result['passed']:
+            print(f"   {item}")
+            total_passed += 1
+        for item in result['issues']:
+            print(f"   {item}")
+            if item.startswith("[X]"):
+                total_issues += 1
+    
+    print("\n" + "=" * 60)
+    print(f"[RESULTS] {total_passed} passed, {total_issues} critical issues")
+    print("=" * 60)
+    
+    if total_issues == 0:
+        print("[OK] API validation passed")
+        sys.exit(0)
+    else:
+        print("[X] Fix critical issues before deployment")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/.agent/skills/api-patterns/security-testing.md

@@ -0,0 +1,122 @@
+# API 安全测试
+
+> API 安全测试原则。OWASP API Top 10、认证与授权测试。
+
+---
+
+## OWASP API Top 10（安全前十）
+
+| 漏洞 | 测试重点 |
+|---------------|------------|
+| **API1: BOLA** | 访问其他用户资源 |
+| **API2: Broken Auth** | JWT、会话、凭证 |
+| **API3: Property Auth** | 批量赋值、数据暴露 |
+| **API4: Resource Consumption** | 速率限制、DoS |
+| **API5: Function Auth** | 管理端点、角色绕过 |
+| **API6: Business Flow** | 逻辑滥用、自动化 |
+| **API7: SSRF** | 内网访问 |
+| **API8: Misconfiguration** | 调试端点、CORS |
+| **API9: Inventory** | 影子 API、旧版本 |
+| **API10: Unsafe Consumption** | 第三方 API 信任 |
+
+---
+
+## 认证测试
+
+### JWT 测试
+
+| 检查项 | 测试内容 |
+|-------|--------------|
+| 算法 | None、算法混淆 |
+| 密钥 | 弱密钥、暴力破解 |
+| 声明 | 过期、签发者、受众 |
+| 签名 | 篡改、密钥注入 |
+
+### 会话测试
+
+| 检查项 | 测试内容 |
+|-------|--------------|
+| 生成 | 可预测性 |
+| 存储 | 客户端侧安全 |
+| 过期 | 超时强制 |
+| 失效 | 注销有效性 |
+
+---
+
+## 授权测试
+
+| 测试类型 | 方法 |
+|-----------|----------|
+| **水平** | 访问同级用户数据 |
+| **垂直** | 访问更高权限功能 |
+| **上下文** | 访问超出允许范围 |
+
+### BOLA/IDOR 测试
+
+1. 识别请求中的资源 ID
+2. 以用户 A 会话捕获请求
+3. 以用户 B 会话重放请求
+4. 检查是否存在未授权访问
+
+---
+
+## 输入验证测试
+
+| 注入类型 | 测试重点 |
+|----------------|------------|
+| SQL | 查询篡改 |
+| NoSQL | 文档查询 |
+| 命令 | 系统命令 |
+| LDAP | 目录查询 |
+
+**方法：** 测试所有参数，尝试类型强制，测试边界，检查错误信息。
+
+---
+
+## 速率限制测试
+
+| 方面 | 检查 |
+|--------|-------|
+| 存在性 | 是否有限制 |
+| 绕过 | 请求头（Header）、IP 轮换 |
+| 范围 | 每用户、每 IP、全局 |
+
+**绕过手法：** X-Forwarded-For、不同 HTTP 方法、大小写变体、API 版本。
+
+---
+
+## GraphQL 安全
+
+| 测试 | 重点 |
+|------|-------|
+| 内省 | Schema（模式）泄露 |
+| 批量 | 查询型 DoS |
+| 嵌套 | 深度型 DoS |
+| 授权 | 字段级访问 |
+
+---
+
+## 安全测试检查清单
+
+**认证：**
+- [ ] 测试绕过
+- [ ] 检查凭证强度
+- [ ] 验证令牌安全
+
+**授权：**
+- [ ] 测试 BOLA/IDOR
+- [ ] 检查权限提升
+- [ ] 验证功能访问
+
+**输入：**
+- [ ] 测试所有参数
+- [ ] 检查注入
+
+**配置：**
+- [ ] 检查 CORS
+- [ ] 验证请求头（Header）
+- [ ] 测试错误处理
+
+---
+
+> **记住：** API 是现代应用的骨干，像攻击者一样测试它们。