@mison/ag-kit-cn 2.0.1

package/.agent/skills/powershell-windows/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: powershell-windows
+description: PowerShell（任务自动化和配置管理框架）Windows 模式。包含关键陷阱、运算符语法（Operator Syntax）和错误处理。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# PowerShell Windows 实践模式
+
+> 针对 Windows PowerShell 的核心模式与关键陷阱。
+
+---
+
+## 1. 运算符语法规则
+
+### 关键：必须使用圆括号（Parentheses）
+
+| ❌ 错误做法                            | ✅ 正确做法                                |
+| -------------------------------------- | ------------------------------------------ |
+| `if (Test-Path "a" -or Test-Path "b")` | `if ((Test-Path "a") -or (Test-Path "b"))` |
+| `if (Get-Item $x -and $y -eq 5)`       | `if ((Get-Item $x) -and ($y -eq 5))`       |
+
+**准则：** 在使用逻辑运算符时，每一个 Cmdlet（命令）的调用**必须**封装在圆括号内。
+
+---
+
+## 2. Unicode（统一码）/Emoji（表情符号）限制
+
+### 关键：脚本中严禁使用 Unicode
+
+| 用途 | ❌ 禁止使用 | ✅ 推荐使用 |
+| ---- | ----------- | ----------- |
+| 成功 | ✅ ✓        | [OK] [+]    |
+| 错误 | ❌ ✗ 🔴     | [!] [X]     |
+| 警告 | ⚠️ 🟡       | [*] [WARN]  |
+| 信息 | ℹ️ 🔵       | [i] [INFO]  |
+| 进度 | ⏳          | [...]       |
+
+**准则：** 在 PowerShell 脚本中仅使用 ASCII（ASCII 码）字符。
+
+---
+
+## 3. 空值检查模式
+
+### 在访问前始终检查
+
+| ❌ 错误做法          | ✅ 正确做法                      |
+| -------------------- | -------------------------------- |
+| `$array.Count -gt 0` | `$array -and $array.Count -gt 0` |
+| `$text.Length`       | `if ($text) { $text.Length }`    |
+
+---
+
+## 4. 字符串内插（Interpolation）
+
+### 复杂表达式的处理
+
+**推荐做法：** 先存储到变量中，再进行内插。
+
+```powershell
+$value = $obj.prop.sub
+Write-Output "Value: $value"
+```
+
+---
+
+## 5. 错误处理
+
+### ErrorActionPreference（错误处理偏好）配置
+
+| 取值             | 使用场景             |
+| ---------------- | -------------------- |
+| Stop             | 开发阶段（快速失败） |
+| Continue         | 生产环境脚本         |
+| SilentlyContinue | 预期可能会发生错误时 |
+
+### Try/Catch（错误捕获）最佳实践
+
+- 不要在 try 块内部直接返回。
+- 始终使用 finally 块进行资源清理。
+- 在 try/catch 结构之后再执行返回操作。
+
+---
+
+## 6. 文件路径处理
+
+### Windows 路径规则
+
+| 模式       | 用途                                    |
+| ---------- | --------------------------------------- |
+| 字面量路径 | `C:\Users\User\file.txt`                |
+| 变量路径   | `Join-Path $env:USERPROFILE "file.txt"` |
+| 相对路径   | `Join-Path $ScriptDir "data"`           |
+
+**准则：** 使用 `Join-Path` 以确保跨平台的路径安全性。
+
+---
+
+## 7. 数组操作
+
+### 正确的语法模式
+
+| 操作项         | 语法                           |
+| -------------- | ------------------------------ |
+| 空数组         | `$array = @()`                 |
+| 添加元素       | `$array += $item`              |
+| ArrayList 添加 | `$list.Add($item) \| Out-Null` |
+
+---
+
+## 8. JSON（数据交换格式）操作
+
+### 关键：深度参数（Depth Parameter）
+
+| ❌ 错误做法      | ✅ 正确做法                |
+| ---------------- | -------------------------- |
+| `ConvertTo-Json` | `ConvertTo-Json -Depth 10` |
+
+**准则：** 处理嵌套对象时，务必显式指定 `-Depth`。
+
+### 文件读写操作
+
+| 操作项 | 模式                                                                |
+| ------ | ------------------------------------------------------------------- |
+| 读取   | `Get-Content "file.json" -Raw \| ConvertFrom-Json`                  |
+| 写入   | `$data \| ConvertTo-Json -Depth 10 \| Out-File "file.json" -Encoding UTF8` |
+
+---
+
+## 9. 常见错误速查
+
+| 错误消息               | 原因              | 修复方案                |
+| ---------------------- | ----------------- | ----------------------- |
+| "parameter 'or'"       | 缺失圆括号        | 使用 () 封装 Cmdlet     |
+| "Unexpected token"     | 存在 Unicode 字符 | 仅保留 ASCII 字符       |
+| "Cannot find property" | 对象为空（Null）  | 先执行空值检查          |
+| "Cannot convert"       | 类型不匹配        | 使用 `.ToString()` 转换 |
+
+---
+
+## 10. 脚本模板
+
+```powershell
+# 开启严格模式
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Continue"
+
+# 路径初始化
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# 主程序逻辑
+try {
+    # 在此处编写业务逻辑
+    Write-Output "[OK] Done"
+    exit 0
+}
+catch {
+    Write-Warning "Error: $_"
+    exit 1
+}
+```
+
+---
+
+> **谨记：** PowerShell 具有独特的语法规则。圆括号的使用、仅限 ASCII 以及空值检查是不可逾越的底线。
+
+---

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

@@ -0,0 +1,441 @@
+---
+name: python-patterns
+description: Python（编程语言）开发原则与决策方法。覆盖框架选型、异步模式、类型标注与项目结构。强调思考而非照抄。
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Python 模式
+
+> 面向 2025 的 Python 开发原则与决策方法。  
+> **学习如何思考，不要只记模式。**
+
+---
+
+## ⚠️ 本技能使用方式
+
+本技能强调**决策原则**，不是固定代码模板。
+
+- 需求不明确时，先询问用户框架偏好
+- 根据 Context（上下文）决定 async（异步）或 sync（同步）
+- 不要每次都默认同一框架
+
+---
+
+## 1. 框架选型（2025）
+
+### 决策树
+
+```
+你要构建什么？
+│
+├── API 优先（API-first）/ 微服务
+│   └── FastAPI（async、现代、速度快）
+│
+├── 全栈 Web / CMS / 管理后台
+│   └── Django（开箱即用，batteries-included）
+│
+├── 简单应用 / 脚本 / 学习
+│   └── Flask（极简、灵活）
+│
+├── AI/ML API 服务化
+│   └── FastAPI（Pydantic、async、Uvicorn）
+│
+└── 后台任务
+    └── Celery + 任意 Web 框架
+```
+
+### 对比原则
+
+| 维度 | FastAPI | Django | Flask |
+|------|---------|--------|-------|
+| **适用场景** | API、微服务 | 全栈、CMS | 简单项目、学习 |
+| **异步支持** | 原生支持 | Django 5.0+ | 依赖扩展 |
+| **管理后台** | 手动构建 | 内置 Admin（管理后台） | 依赖扩展 |
+| **ORM（对象关系映射）** | 自由选择 | Django ORM | 自由选择 |
+| **学习曲线** | 低 | 中 | 低 |
+
+### 选型前必须询问：
+1. 是纯 API 还是全栈应用？
+2. 是否需要后台管理界面？
+3. 团队是否熟悉 async？
+4. 是否有现有基础设施约束？
+
+---
+
+## 2. 异步与同步决策
+
+### 何时使用异步（async）
+
+```
+async def（异步函数）更适合：
+├── I/O 密集操作（数据库、HTTP、文件）
+├── 大量并发连接
+├── 实时交互场景
+├── 微服务通信
+└── FastAPI/Starlette/Django ASGI（异步服务器网关接口）
+
+def（同步函数）更适合：
+├── CPU 密集操作
+├── 简单脚本
+├── 遗留代码库
+├── 团队不熟悉 async
+└── 依赖阻塞型库（无 async 版本）
+```
+
+### 黄金法则
+
+```
+I/O bound（I/O 密集）→ async（等待外部资源）
+CPU bound（CPU 密集）→ sync + multiprocessing（本地计算）
+
+不要：
+├── 随意混用 sync 与 async
+├── 在 async 代码里调用阻塞库
+└── 为 CPU 任务强行上 async
+```
+
+### 异步库选型
+
+| 需求 | 异步库 |
+|------|--------|
+| HTTP 客户端 | httpx |
+| PostgreSQL | asyncpg |
+| Redis（内存数据库） | aioredis / redis-py async |
+| 文件 I/O | aiofiles |
+| 数据库 ORM | SQLAlchemy 2.0 async, Tortoise |
+
+---
+
+## 3. 类型标注策略
+
+### 哪些地方要标注
+
+```
+必须标注：
+├── 函数参数
+├── 返回类型
+├── 类属性
+├── 对外公开 API
+
+可省略：
+├── 局部变量（让推断工作）
+├── 一次性脚本
+├── 测试代码（通常可选）
+```
+
+### 常见类型模式
+
+```python
+# 下面是模式示例，请理解其语义：
+
+# Optional（可选）→ 可能为 None
+from typing import Optional
+def find_user(id: int) -> Optional[User]: ...
+
+# Union（联合类型）→ 多类型之一
+def process(data: str | dict) -> None: ...
+
+# 泛型集合
+def get_items() -> list[Item]: ...
+def get_mapping() -> dict[str, int]: ...
+
+# Callable（可调用）
+from typing import Callable
+def apply(fn: Callable[[int], str]) -> str: ...
+```
+
+### 用 Pydantic（数据校验库）做校验
+
+```
+适用场景：
+├── API 请求/响应模型
+├── 配置与 settings
+├── 数据校验
+├── 序列化
+
+收益：
+├── 运行时校验
+├── 自动生成 JSON Schema（JSON 模式）
+├── 与 FastAPI 原生协同
+└── 清晰错误提示
+```
+
+---
+
+## 4. 项目结构原则
+
+### 结构选择
+
+```
+小项目 / 脚本：
+├── main.py
+├── utils.py
+└── requirements.txt
+
+中型 API：
+├── app/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── models/
+│   ├── routes/
+│   ├── services/
+│   └── schemas/
+├── tests/
+└── pyproject.toml
+
+大型应用：
+├── src/
+│   └── myapp/
+│       ├── core/
+│       ├── api/
+│       ├── services/
+│       ├── models/
+│       └── ...
+├── tests/
+└── pyproject.toml
+```
+
+### FastAPI 结构原则
+
+```
+可按“分层”或“按功能”组织：
+
+按分层：
+├── routes/（API 端点）
+├── services/（业务逻辑）
+├── models/（数据库模型）
+├── schemas/（Pydantic 模型）
+└── dependencies/（共享依赖）
+
+按功能：
+├── users/
+│   ├── routes.py
+│   ├── service.py
+│   └── schemas.py
+└── products/
+    └── ...
+```
+
+---
+
+## 5. Django 原则（2025）
+
+### Django 异步能力（Django 5.0+）
+
+```
+Django 已支持 async（异步）：
+├── 异步视图（Async views）
+├── 异步中间件（Async middleware）
+├── 异步 ORM（部分能力）
+└── ASGI 部署
+
+Django 中适合 async（异步）的场景：
+├── 调用外部 API
+├── WebSocket（Channels）
+├── 高并发视图
+└── 触发后台任务
+```
+
+### Django 最佳实践
+
+```
+模型设计：
+├── 模型肥、视图薄（Fat models, thin views）
+├── 通过 manager 抽共用查询
+├── 共享字段放抽象基类
+
+视图选择：
+├── 复杂 CRUD 用类视图（class-based views）
+├── 简单接口用函数视图（function-based views）
+├── DRF（Django REST Framework）场景可用 viewsets（视图集）
+
+查询优化：
+├── 外键用 select_related()
+├── 多对多用 prefetch_related()
+├── 避免 N+1 查询
+└── 用 .only() 限定字段
+```
+
+---
+
+## 6. FastAPI 原则
+
+### FastAPI 中 `async def` 与 `def` 的选择
+
+```
+适用 async def：
+├── 使用 async 数据库驱动
+├── 发起 async HTTP 调用
+├── I/O 密集操作
+└── 需要高并发吞吐
+
+适用 def：
+├── 阻塞型操作
+├── sync 数据库驱动
+├── CPU 密集任务
+└── FastAPI 会自动放入线程池执行
+```
+
+### 依赖注入
+
+```
+依赖注入（Dependency Injection）适用：
+├── 数据库会话
+├── 当前用户 / 鉴权
+├── 配置对象
+├── 共享资源
+
+收益：
+├── 可测试性提升（可 mock/模拟）
+├── 职责清晰分离
+├── 可自动清理资源（yield）
+```
+
+### Pydantic v2 集成
+
+```python
+# FastAPI 与 Pydantic 深度集成：
+
+# 请求校验
+@app.post("/users")
+async def create(user: UserCreate) -> UserResponse:
+    # user 在进入业务前已完成校验
+    ...
+
+# 响应序列化
+# 返回类型会成为响应 schema
+```
+
+---
+
+## 7. 后台任务
+
+### 方案选择指南
+
+| 方案 | 适用场景 |
+|------|----------|
+| **BackgroundTasks** | 简单、进程内任务 |
+| **Celery** | 分布式、复杂工作流 |
+| **ARQ** | 异步 + Redis |
+| **RQ** | 简单 Redis 队列 |
+| **Dramatiq** | Actor 模式，比 Celery 更轻量 |
+
+### 各方案适用场景
+
+```
+FastAPI BackgroundTasks：
+├── 短平快任务
+├── 不要求持久化
+├── 即发即忘（Fire-and-forget）
+└── 与 Web 进程同进程运行
+
+Celery/ARQ：
+├── 长耗时任务
+├── 需要重试机制
+├── 分布式 worker（执行进程）
+├── 持久化队列
+└── 复杂工作流
+```
+
+---
+
+## 8. 错误处理原则
+
+### 异常策略
+
+```
+在 FastAPI 中：
+├── 定义自定义异常类
+├── 注册统一异常处理器
+├── 返回一致的错误格式
+└── 记录日志但不暴露内部细节
+
+推荐模式：
+├── service 层抛领域异常
+├── handler 层转换为 HTTP 响应
+└── 客户端收到干净错误对象
+```
+
+### 错误响应原则
+
+```
+应包含：
+├── 错误码（Error code，用于程序处理）
+├── 消息（Message，人类可读）
+├── 细节（Details，字段级，按需）
+└── 禁止返回堆栈（stack traces，出于安全）
+```
+
+---
+
+## 9. 测试原则
+
+### 测试策略
+
+| 类型 | 目的 | 工具 |
+|------|------|------|
+| **单元测试（Unit）** | 业务逻辑 | pytest |
+| **集成测试（Integration）** | API 端点 | pytest + httpx/TestClient |
+| **端到端测试（E2E）** | 完整工作流 | pytest + DB |
+
+### 异步测试
+
+```python
+# 异步测试使用 pytest-asyncio
+
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_endpoint():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        response = await client.get("/users")
+        assert response.status_code == 200
+```
+
+### Fixture 策略
+
+```
+常用 fixture（测试夹具）：
+├── db_session → 数据库连接
+├── client → 测试客户端
+├── authenticated_user → 带 token（令牌）的用户
+└── sample_data → 测试数据准备
+```
+
+---
+
+## 10. 决策检查清单
+
+开始实现前：
+
+- [ ] **是否询问了用户的框架偏好？**
+- [ ] **是否针对当前上下文选了框架？**（而非默认）
+- [ ] **是否明确了异步 vs 同步（async/sync）？**
+- [ ] **是否规划了类型标注策略？**
+- [ ] **是否确定了项目结构？**
+- [ ] **是否设计了错误处理方案？**
+- [ ] **是否评估了后台任务需求？**
+
+---
+
+## 11. 需要避免的反模式
+
+### ❌ 不要这样做：
+- 简单 API 也默认 Django（FastAPI 往往更合适）
+- 在 async 代码里用 sync 库
+- 对公开 API 跳过类型标注
+- 把业务逻辑塞进 routes/views
+- 忽略 N+1 查询
+- 粗糙混用 async 与 sync
+
+### ✅ 推荐做法：
+- 基于上下文选框架
+- 先确认 async 需求
+- 用 Pydantic 做数据校验
+- 分层解耦（routes → services → repos（仓储层））
+- 覆盖关键路径测试
+
+---
+
+> **牢记：** Python 模式的核心是“按当前场景做决策”。不要抄代码，先判断什么最适合你的应用。