@mison/ag-kit-cn 2.0.1

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

@@ -0,0 +1,187 @@
+---
+name: webapp-testing
+description: Web 应用测试原则。覆盖端到端（E2E）、Playwright 与深度审计策略。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Web 应用测试
+
+> 发现并测试一切，不放过任何路由。Web 应用测试（Web App Testing）以完整覆盖为目标。
+
+## 运行时脚本（Runtime Scripts）
+
+**使用以下脚本执行自动化浏览器测试：**
+
+| 脚本（Script） | 用途（Purpose） | 用法（Usage） |
+|---------------|----------------|---------------|
+| `scripts/playwright_runner.py` | 基础浏览器测试 | `python scripts/playwright_runner.py <网址>` |
+| | 带截图输出 | `python scripts/playwright_runner.py <网址> --screenshot` |
+| | 可访问性检查 | `python scripts/playwright_runner.py <网址> --a11y` |
+
+**依赖要求：** `pip install playwright && playwright install chromium`
+
+---
+
+## 1. 深度审计方法（Deep Audit Approach）
+
+### 先做发现（Discovery First）
+
+| 目标（Target） | 如何发现（How to Find） |
+|---------------|------------------------|
+| 路由（Routes） | 扫描 app/、pages/、router 文件 |
+| API 端点（API Endpoints） | 用 Grep 检索 HTTP 方法 |
+| 组件（Components） | 查找组件目录 |
+| 功能点（Features） | 阅读相关文档 |
+
+### 系统化测试（Systematic Testing）
+
+1. **Map（建图）** - 列出全部路由/API
+2. **Scan（扫描）** - 验证是否可响应
+3. **Test（测试）** - 覆盖关键路径
+
+---
+
+## 2. Web 测试金字塔（Testing Pyramid for Web）
+
+```
+        /\          端到端（E2E，少量）
+       /  \         关键用户流程
+      /----\
+     /      \       集成测试（Integration，中量）
+    /--------\      API、数据流
+   /          \
+  /------------\    组件测试（Component，大量）
+                    单个 UI 单元
+```
+
+---
+
+## 3. 端到端（E2E）测试原则
+
+### 测什么（What to Test）
+
+| 优先级（Priority） | 测试内容（Tests） |
+|-------------------|------------------|
+| 1 | Happy Path（主流程） |
+| 2 | 鉴权流程（Authentication flows） |
+| 3 | 关键业务动作 |
+| 4 | 错误处理 |
+
+### 端到端（E2E）最佳实践
+
+| 实践（Practice） | 原因（Why） |
+|----------------|------------|
+| 使用 `data-testid` | 选择器稳定 |
+| 等待元素就绪 | 避免不稳定测试（flaky tests） |
+| 保持干净状态 | 用例彼此独立 |
+| 避免依赖实现细节 | 面向用户行为测试 |
+
+---
+
+## 4. Playwright 原则（Playwright Principles）
+
+### 核心概念（Core Concepts）
+
+| 概念（Concept） | 用途（Use） |
+|----------------|-----------|
+| Page Object Model（页面对象模型） | 封装页面逻辑 |
+| Fixtures（测试夹具） | 复用测试准备过程 |
+| Assertions（断言） | 内置自动等待能力 |
+| Trace Viewer（追踪查看器） | 调试失败用例 |
+
+### 配置建议（Configuration）
+
+| 设置项（Setting） | 建议（Recommendation） |
+|-----------------|------------------------|
+| 重试次数（Retries） | CI 中设为 2 |
+| Trace（追踪） | `on-first-retry` |
+| Screenshots（截图） | `on-failure` |
+| Video（视频） | `retain-on-failure` |
+
+---
+
+## 5. 视觉回归测试（Visual Testing）
+
+### 何时使用（When to Use）
+
+| 场景（Scenario） | 价值（Value） |
+|-----------------|--------------|
+| 设计系统（Design system） | 高 |
+| 营销页面（Marketing pages） | 高 |
+| 组件库（Component library） | 中 |
+| 动态内容页面 | 相对较低 |
+
+### 策略（Strategy）
+
+- 先建立基线截图（Baseline screenshots）
+- 变更后做对比
+- 审查视觉差异
+- 对有意变更更新基线
+
+---
+
+## 6. API 测试原则（API Testing Principles）
+
+### 覆盖范围（Coverage Areas）
+
+| 范围（Area） | 测试内容（Tests） |
+|-------------|------------------|
+| 状态码（Status codes） | 200, 400, 404, 500 |
+| 响应结构（Response shape） | 与 schema（模式）匹配 |
+| 错误信息（Error messages） | 对用户友好 |
+| 边界场景（Edge cases） | 空值、大输入、特殊字符 |
+
+---
+
+## 7. 测试组织方式（Test Organization）
+
+### 文件结构（File Structure）
+
+```
+tests/
+├── e2e/           # 全链路用户流程
+├── integration/   # API、数据流
+├── component/     # UI 单元
+└── fixtures/      # 共享数据
+```
+
+### 命名约定（Naming Convention）
+
+| 模式（Pattern） | 示例（Example） |
+|---------------|----------------|
+| 按功能命名（Feature-based） | `login.spec.ts` |
+| 描述性命名（Descriptive） | `user-can-checkout.spec.ts` |
+
+---
+
+## 8. CI 集成（CI Integration）
+
+### 流水线步骤（Pipeline Steps）
+
+1. 安装依赖
+2. 安装浏览器
+3. 执行测试
+4. 上传产物（trace（追踪）、截图）
+
+### 并行策略（Parallelization）
+
+| 策略（Strategy） | 用途（Use） |
+|-----------------|-----------|
+| 按文件并行（Per file） | Playwright 默认策略 |
+| 分片（Sharding） | 大规模测试集 |
+| Workers（并发工作者）并发 | 多浏览器/多进程执行 |
+
+---
+
+## 9. 反模式（Anti-Patterns）
+
+| ❌ 避免（Don't） | ✅ 建议（Do） |
+|----------------|-------------|
+| 测实现细节 | 测用户行为 |
+| 硬编码等待时间 | 使用自动等待 |
+| 跳过清理步骤 | 确保用例隔离 |
+| 忽略不稳定测试（flaky tests） | 修复根因 |
+
+---
+
+> **牢记：** 端到端（E2E）成本高，只用于关键路径。

package/.agent/skills/webapp-testing/scripts/playwright_runner.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# 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
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+    """Run basic browser test on URL."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {
+            "error": "Playwright not installed",
+            "fix": "pip install playwright && playwright install chromium"
+        }
+    
+    result = {
+        "url": url,
+        "timestamp": datetime.now().isoformat(),
+        "status": "pending"
+    }
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                viewport={"width": 1280, "height": 720},
+                user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            )
+            page = context.new_page()
+            
+            # Navigate
+            response = page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic info
+            result["page"] = {
+                "title": page.title(),
+                "url": page.url,
+                "status_code": response.status if response else None
+            }
+            
+            # Health checks
+            result["health"] = {
+                "loaded": response.ok if response else False,
+                "has_title": bool(page.title()),
+                "has_h1": page.locator("h1").count() > 0,
+                "has_links": page.locator("a").count() > 0,
+                "has_images": page.locator("img").count() > 0
+            }
+            
+            # Console errors
+            console_errors = []
+            page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+            
+            # Performance metrics
+            result["performance"] = {
+                "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+                "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+            }
+            
+            # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+            if take_screenshot:
+                # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+                screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+                os.makedirs(screenshot_dir, exist_ok=True)
+                screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+                page.screenshot(path=screenshot_path, full_page=True)
+                result["screenshot"] = screenshot_path
+                result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+            
+            # Element counts
+            result["elements"] = {
+                "links": page.locator("a").count(),
+                "buttons": page.locator("button").count(),
+                "inputs": page.locator("input").count(),
+                "images": page.locator("img").count(),
+                "forms": page.locator("form").count()
+            }
+            
+            browser.close()
+            
+            result["status"] = "success" if result["health"]["loaded"] else "failed"
+            result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+        result["summary"] = f"[X] Error: {str(e)[:100]}"
+    
+    return result
+
+
+def run_accessibility_check(url: str) -> dict:
+    """Run basic accessibility check."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {"error": "Playwright not installed"}
+    
+    result = {"url": url, "accessibility": {}}
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic a11y checks
+            result["accessibility"] = {
+                "images_with_alt": page.locator("img[alt]").count(),
+                "images_without_alt": page.locator("img:not([alt])").count(),
+                "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+                "links_with_text": page.locator("a:has-text('')").count(),
+                "form_labels": page.locator("label").count(),
+                "headings": {
+                    "h1": page.locator("h1").count(),
+                    "h2": page.locator("h2").count(),
+                    "h3": page.locator("h3").count()
+                }
+            }
+            
+            browser.close()
+            result["status"] = "success"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+    
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+            "examples": [
+                "python playwright_runner.py https://example.com",
+                "python playwright_runner.py https://example.com --screenshot",
+                "python playwright_runner.py https://example.com --a11y"
+            ]
+        }, indent=2))
+        sys.exit(1)
+    
+    url = sys.argv[1]
+    take_screenshot = "--screenshot" in sys.argv
+    check_a11y = "--a11y" in sys.argv
+    
+    if check_a11y:
+        result = run_accessibility_check(url)
+    else:
+        result = run_basic_test(url, take_screenshot)
+    
+    print(json.dumps(result, indent=2))

package/.agent/workflows/brainstorm.md

@@ -0,0 +1,113 @@
+---
+description: 面向项目与功能的结构化头脑风暴。在落地实现前探索多个可选方案。
+---
+
+# /brainstorm - 结构化思路探索
+
+$ARGUMENTS
+
+---
+
+## 目的
+
+此命令激活 BRAINSTORM（头脑风暴）模式以进行结构化的思路探索。当你在决定具体的实现方案之前需要探索多个可选选项时，请使用此命令。
+
+---
+
+## 行为
+
+当 `/brainstorm` 被触发时：
+
+1. **理解目标**
+   - 我们要解决什么问题？
+   - 目标用户是谁？
+   - 存在哪些约束条件？
+
+2. **生成方案**
+   - 提供至少 3 种不同的处理方法
+   - 每种方法都包含 Pros（优点）与 Cons（缺点）
+   - 考虑非传统的解决方案
+
+3. **比较与推荐**
+   - 汇总 tradeoffs（权衡）
+   - 给出带有理由的建议方案
+
+---
+
+## 输出格式
+
+```markdown
+## 🧠 Brainstorm（头脑风暴）：[主题]
+
+### 背景
+[简要的问题描述]
+
+---
+
+### 方案 A：[名称]
+[方案描述]
+
+✅ **Pros（优点）：**
+- [优点 1]
+- [优点 2]
+
+❌ **Cons（缺点）：**
+- [缺点 1]
+
+📊 **Effort（工作量）：** 低 | 中 | 高
+
+---
+
+### 方案 B：[名称]
+[方案描述]
+
+✅ **Pros（优点）：**
+- [优点 1]
+
+❌ **Cons（缺点）：**
+- [缺点 1]
+- [缺点 2]
+
+📊 **Effort（工作量）：** 低 | 中 | 高
+
+---
+
+### 方案 C：[名称]
+[方案描述]
+
+✅ **Pros（优点）：**
+- [优点 1]
+
+❌ **Cons（缺点）：**
+- [缺点 1]
+
+📊 **Effort（工作量）：** 低 | 中 | 高
+
+---
+
+## 💡 推荐
+
+**方案 [X]**，因为 [理由]。
+
+你想继续探索哪个方向？
+```
+
+---
+
+## 示例
+
+```
+/brainstorm 身份验证系统
+/brainstorm 复杂表单的状态管理
+/brainstorm 社交类应用的数据库 Schema（架构）设计
+/brainstorm 缓存策略
+```
+
+---
+
+## 核心原则
+
+- **不涉及代码** —— 本阶段侧重于思路，而非具体实现。
+- **必要时可视化** —— 对于架构设计，使用图表进行说明。
+- **诚实的权衡** —— 不要隐瞒方案的复杂度。
+- **选择权交给用户** —— 展示所有选项，由用户进行最终决策。

package/.agent/workflows/create.md

@@ -0,0 +1,59 @@
+---
+description: 新建应用命令。触发 App Builder（应用构建器）技能并启动与用户的交互式对话。
+---
+
+# /create - 创建应用
+
+$ARGUMENTS
+
+---
+
+## 任务
+
+此命令用于启动一个全新的应用创建流程。
+
+### 步骤：
+
+1. **需求分析**
+   - 理解用户的具体需求
+   - 如果信息缺失，使用 `conversation-manager` 技能进行提问
+
+2. **项目规划**
+   - 使用 `project-planner` Agent（智能体）进行任务拆解
+   - 确定技术栈
+   - 规划文件结构
+   - 创建计划文件并进入构建阶段
+
+3. **应用构建（审批后）**
+   - 调度 `app-builder` 技能
+   - 协调专家 Agent（智能体）：
+     - `database-architect` → Schema（架构）
+     - `backend-specialist` → API（接口）
+     - `frontend-specialist` → UI（界面）
+
+4. **预览**
+   - 完成后使用 `auto_preview.py` 启动预览
+   - 将 URL（链接）呈现给用户
+
+---
+
+## 使用示例
+
+```
+/create 博客网站
+/create 包含产品列表和购物车的电商应用
+/create 待办事项（Todo）应用
+/create Instagram 克隆
+/create 具备客户管理功能的 CRM（客户关系管理）系统
+```
+
+---
+
+## 在开始之前
+
+如果需求不清晰，请提出以下问题：
+- 应用属于什么类型？
+- 基础功能有哪些？
+- 谁会使用它？
+
+先使用默认值，后续再添加细节。

package/.agent/workflows/debug.md

@@ -0,0 +1,103 @@
+---
+description: 调试命令。激活 DEBUG（调试）模式并进行系统化问题排查。
+---
+
+# /debug - 系统化问题排查
+
+$ARGUMENTS
+
+---
+
+## 目的
+
+该命令用于激活 DEBUG（调试）模式，以系统化调查异常、报错或非预期行为。
+
+---
+
+## 行为
+
+当 `/debug` 被触发时：
+
+1. **收集信息**
+   - 错误信息
+   - 复现步骤
+   - 预期行为 vs 实际行为
+   - 最近代码变更
+
+2. **形成假设**
+   - 列出可能原因
+   - 按概率排序
+
+3. **系统化调查**
+   - 逐条验证假设
+   - 检查日志与数据流
+   - 用排除法收敛根因
+
+4. **修复并预防**
+   - 应用修复
+   - 解释根因
+   - 增加预防措施
+
+---
+
+## 输出格式
+
+```markdown
+## 🔍 Debug（调试）：[问题]
+
+### 1. 症状
+[发生了什么]
+
+### 2. 已收集信息
+- 错误：`[错误信息]`
+- 文件：`[文件路径]`
+- 行号：[行号]
+
+### 3. 假设
+1. ❓ [最可能的原因]
+2. ❓ [第二可能性]
+3. ❓ [较低可能性]
+
+### 4. 调查
+
+**验证假设 1：**
+[检查内容] → [结果]
+
+**验证假设 2：**
+[检查内容] → [结果]
+
+### 5. 根因
+🎯 **[为何会发生的解释]**
+
+### 6. 修复
+```[language]
+// Before
+[broken code]
+
+// After
+[fixed code]
+```
+
+### 7. 预防
+🛡️ [如何避免再次发生]
+```
+
+---
+
+## 示例
+
+```
+/debug 登录无法使用
+/debug API（接口）返回 500
+/debug 表单无法提交
+/debug 数据未保存
+```
+
+---
+
+## 核心原则
+
+- **先问再判** —— 先拿到完整错误上下文
+- **验证假设** —— 不要凭感觉乱改
+- **解释原因** —— 不只说“怎么修”，还要说“为何坏”
+- **防止复发** —— 补上测试与校验策略