@deepstorm/cli 0.1.0

package/dist/skills/reef-style-backend/fragments/python/fastapi-quick-reference/quick-reference.md

@@ -0,0 +1,101 @@
+# FastAPI 最佳实践
+
+## 路由组织
+
+```python
+# ✅ 好：按领域分组路由
+# app/api/v1/users.py
+router = APIRouter(prefix="/api/v1/users", tags=["users"])
+
+@router.get("/", response_model=list[UserResponse])
+async def list_users(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    user_service: UserService = Depends(),
+):
+    return await user_service.list_users(skip=skip, limit=limit)
+```
+
+**规范：**
+- 每个模块一个 `APIRouter`，在 `app/api/v1/__init__.py` 中 `include_router`
+- 路径用 kebab-case：`/api/v1/user-roles`，不用 `/api/v1/userRoles`
+- 路径变量用 snake_case：`/api/v1/users/{user_id}`
+- 列表接口**必须**有分页参数
+
+## 依赖注入
+
+```python
+# ✅ 好：用 Depends() 隐式注入
+@app.get("/users/{user_id}")
+async def get_user(
+    user_id: int,
+    user_service: UserService = Depends(),
+):
+    return await user_service.get_user(user_id)
+
+# ❌ 坏：在 Router 中直接实例化 Service
+@app.get("/users/{user_id}")
+async def get_user(user_id: int):   # ← 没有依赖注入
+    service = UserService()          # ← 手动实例化
+    return await service.get_user(user_id)
+```
+
+**规范：**
+- Service 类使用 `__init__` 接收依赖，注册为 `Depends()`
+- 不要用全局单例模式
+- DAO / Repository 也通过 `Depends()` 注入到 Service
+
+## Pydantic Schema
+
+```python
+# ✅ 好：Request / Response Schema 分开
+class CreateUserRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    email: EmailStr
+    role: UserRole = UserRole.USER
+
+class UserResponse(BaseModel):
+    id: int
+    name: str
+    email: EmailStr
+    role: UserRole
+    created_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)  # ORM 模式
+```
+
+**规范：**
+- Request Schema 用 `BaseModel`，加输入约束
+- Response Schema 用 `ConfigDict(from_attributes=True)` 以支持 ORM 序列化
+- CRUD 接口用 `Create*Request` / `Update*Request` / `*Response` 命名
+
+## 全局异常处理器
+
+```python
+# ✅ 好：统一注册
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"code": exc.code, "message": exc.detail},
+    )
+```
+
+## 异步配置
+
+```python
+# ✅ 好：FastAPI 原生异步
+@app.get("/health")
+async def health():
+    # 异步 HTTP 调用
+    async with httpx.AsyncClient() as client:
+        resp = await client.get("https://status.example.com")
+    return {"status": "ok"}
+```
+
+**红线：** `async def` handler 内部不得调同步的 `time.sleep()` / `requests.get()` / 同步 ORM 操作。需要调同步操作时用 `asyncio.to_thread()` 包裹。

package/dist/skills/reef-style-backend/fragments/python/langchain/quick-reference.md

@@ -0,0 +1,135 @@
+# LangChain 开发规范
+
+## 概述
+
+LangChain 是 Python 生态中的 AI 集成框架，提供统一的 API 来调用 LLM、管理对话、构建 RAG 应用。
+
+## 核心概念
+
+### ChatModel
+LangChain 的中央 API，用于与大语言模型交互。
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import SystemMessage, HumanMessage
+
+# 初始化
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+
+# 基础调用
+response = llm.invoke([
+    SystemMessage(content="你是一个专业的 Python 开发者助手"),
+    HumanMessage(content="解释 FastAPI 的依赖注入")
+])
+print(response.content)
+```
+
+**最佳实践：**
+- `ChatOpenAI` / `ChatAnthropic` 在应用初始化时创建一次，通过依赖注入传递
+- 不要在每个请求中重新创建 LLM 实例
+- `temperature=0` 用于确定性结果，`temperature>0` 用于创意场景
+- API Key 通过环境变量读取，不硬编码
+
+### Prompt Template
+
+结构化提示词模板：
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "你是一个{role}，请用{language}回答"),
+    ("human", "{question}"),
+])
+
+chain = prompt | llm
+result = chain.invoke({"role": "Python专家", "language": "中文", "question": "什么是异步编程？"})
+```
+
+### Tool / 函数调用
+
+AI 模型调用外部函数的能力：
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def get_user_order(user_id: str) -> list[dict]:
+    """获取用户订单信息"""
+    # 实际业务逻辑调用 Service 层
+    return order_service.get_orders(user_id)
+
+
+# 绑定工具后调用
+llm_with_tools = llm.bind_tools([get_user_order])
+```
+
+**最佳实践：**
+- `@tool` 的 docstring 会被模型理解，写清楚参数含义和返回值格式
+- 工具函数内部调用 Service 层，不在工具内写业务逻辑
+- `bind_tools([])` 传工具数组，不逐个 `.bind()` 调用
+
+### Chain / LCEL
+
+LangChain Expression Language — 声明式管道：
+
+```python
+from langchain_core.output_parsers import StrOutputParser
+
+# 链式组装
+chain = prompt | llm | StrOutputParser()
+
+# 执行
+result = chain.invoke({"question": "Python 异步编程的最佳实践？"})
+```
+
+### RAG（检索增强生成）
+
+```python
+from langchain_core.vectorstores import InMemoryVectorStore
+from langchain_openai import OpenAIEmbeddings
+
+# 创建向量存储
+vector_store = InMemoryVectorStore.from_texts(
+    texts=["文档内容1", "文档内容2"],
+    embedding=OpenAIEmbeddings()
+)
+
+# 检索
+retriever = vector_store.as_retriever(search_kwargs={"k": 3})
+
+# RAG 链
+from langchain.chains import create_retrieval_chain
+from langchain.chains.combine_documents import create_stuff_documents_chain
+
+combine_docs_chain = create_stuff_documents_chain(llm, prompt)
+rag_chain = create_retrieval_chain(retriever, combine_docs_chain)
+result = rag_chain.invoke({"question": "某个话题"})
+```
+
+## 依赖管理
+
+```bash
+# 基础安装
+uv add langchain langchain-openai
+
+# 按需安装其他 provider
+uv add langchain-anthropic   # Claude
+uv add langchain-google-ai   # Gemini
+
+# 向量存储
+uv add langchain-community
+
+# RAG 相关
+uv add chromadb tiktoken
+```
+
+## 常见坑
+
+| 场景 | 问题 | 正确做法 |
+|------|------|---------|
+| API Key 管理 | 硬编码在代码中 | 从 `os.getenv("OPENAI_API_KEY")` 读取 |
+| 每次请求新建 LLM | 性能差、连接池耗尽 | 应用启动时创建单例，通过 DI 注入 |
+| 工具函数逻辑过重 | 工具内包含全部业务逻辑 | 工具只做参数解析 + 调用 Service |
+| 忽略 `async` 支持 | LCEL 链中调同步 IO | 使用 `ainvoke()` 和 async retriever |
+| prompt 不设 system message | 模型行为不可控 | 始终设置 system message 定义角色和约束 |

package/dist/skills/reef-style-backend/fragments/python/pytest-testing/quick-reference.md

@@ -0,0 +1,111 @@
+# pytest 测试规范
+
+## 目录结构
+
+```
+tests/
+├── conftest.py           # 全局 fixture
+├── unit/                 # 纯逻辑单元测试
+│   ├── test_services/
+│   └── test_schemas/
+└── integration/          # 集成测试（DB / API）
+    ├── test_api/
+    └── conftest.py       # 集成测试专用 fixture
+```
+
+**规范：**
+- `tests/unit/` — 不依赖外部服务的纯逻辑测试
+- `tests/integration/` — 依赖数据库、HTTP 调用的测试
+- 测试文件以 `test_` 开头，函数以 `test_` 开头
+
+## pytest fixture
+
+```python
+# ✅ 好：conftest.py 中的共享 fixture
+import pytest
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import AsyncSession
+
+@pytest_asyncio.fixture
+async def db_session():
+    # 每个测试独立事务，测试后回滚
+    async with async_session() as session:
+        async with session.begin():
+            yield session
+        await session.rollback()
+
+@pytest_asyncio.fixture
+async def user_service(db_session: AsyncSession):
+    return UserService(db=db_session)
+```
+
+**规范：**
+- 测试用 `pytest-asyncio` 支持异步 fixture 和 test
+- fixture 只在 `conftest.py` 中定义，不在测试文件中
+- fixture 范围默认 `function`，仅共享资源用 `session` / `module`
+
+## 异步测试
+
+```python
+# ✅ 好：pytest-asyncio 异步测试
+import pytest
+
+@pytest.mark.asyncio
+async def test_create_user(user_service: UserService):
+    user = await user_service.create_user(name="Alice", email="alice@example.com")
+    assert user.id is not None
+    assert user.name == "Alice"
+```
+
+## 集成测试标记
+
+```python
+import pytest
+
+# ✅ 好：用 mark 区分测试类型
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_api_list_users(client: httpx.AsyncClient):
+    response = await client.get("/api/v1/users")
+    assert response.status_code == 200
+    data = response.json()
+    assert isinstance(data, list)
+```
+
+## HTTP 测试
+
+```python
+# ✅ 好：用 httpx AsyncClient 配合 FastAPI TestClient
+from httpx import AsyncClient, ASGITransport
+
+@pytest_asyncio.fixture
+async def client():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_get_user(client: AsyncClient):
+    response = await client.get("/api/v1/users/1")
+    assert response.status_code == 200
+    assert response.json()["id"] == 1
+```
+
+## 运行命令
+
+```bash
+# 运行全部测试
+python -m pytest
+
+# 指定目录
+python -m pytest tests/unit/
+
+# 包含覆盖率
+python -m pytest --cov=app --cov-report=term-missing
+
+# 仅集成测试
+python -m pytest -m integration
+
+# 并行运行
+python -m pytest -n auto
+```

package/dist/skills/reef-style-backend/fragments/python/ruff-mypy-toolchain/quick-reference.md

@@ -0,0 +1,83 @@
+# ruff + mypy 工具链规范
+
+## ruff 配置（pyproject.toml）
+
+```toml
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "F",   # Pyflakes — 检测未使用导入、未定义变量等
+    "E",   # pycodestyle — PEP 8 风格错误
+    "W",   # pycodestyle — 警告
+    "I",   # isort — 导入排序
+    "N",   # pep8-naming — 命名规范
+    "UP",  # pyupgrade — 新版语法建议
+    "B",   # flake8-bugbear — 常见 bug 模式
+]
+ignore = [
+    "E501",  # 行长度交给 black，不在 ruff 中检查
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["N"]  # 测试文件放宽命名规范
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+```
+
+**规范：**
+- ruff 负责 lint（`ruff check`）和 format（`ruff format`）双重职责
+- 启用 `F` + `E` + `W` + `I` + `N` + `UP` + `B` 规则组
+- 行长度检查（`E501`）交给 black / ruff format，不在 lint 中重复
+
+## mypy 配置（pyproject.toml）
+
+```toml
+[tool.mypy]
+strict = true
+python_version = "3.10"
+check_untyped_defs = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_return_any = true
+no_implicit_optional = true
+disallow_any_unimported = true
+disallow_untyped_defs = true
+disallow_untyped_calls = true
+
+[[tool.mypy.overrides]]
+module = [
+    "tests.*",
+]
+ignore_missing_imports = true
+disallow_untyped_defs = false
+```
+
+**规范：**
+- 生产代码使用 `strict = true`
+- 所有函数必须有类型注释
+- 测试文件放宽类型要求
+
+## 常用命令
+
+```bash
+# 快速 lint
+ruff check .
+
+# 自动修复
+ruff check --fix .
+
+# 格式化
+ruff format
+
+# 类型检查
+mypy .
+
+# 完整检查（推荐 CI 用）
+ruff check . && ruff format --check && mypy .
+```

package/dist/skills/reef-style-backend/fragments/python/security-redlines/quick-reference.md

@@ -0,0 +1,207 @@
+# 安全红线（Python / FastAPI）
+
+## 🔴 红线速查
+
+| 红线 | 禁止行为 | 正确做法 | 违反后果 |
+|------|---------|---------|---------|
+| 密码存储 | 明文存储密码 | `hashlib` / `bcrypt` / `passlib` 哈希后存储 | P0 — 安全漏洞 |
+| SQL 拼接 | f-string / format 拼接 SQL | SQLAlchemy ORM 或 参数化查询 | P0 — SQL 注入 |
+| 硬编码密钥 | 代码中硬编码 Secret / Token | 环境变量 `os.getenv()` 或 `pydantic-settings` | P0 — 凭据泄露 |
+| 敏感信息打印 | `print()` 敏感数据 | `logging` + 脱敏 + 生产级别过滤 | P1 — 信息泄露 |
+| 输入验证缺失 | 不验证用户输入 | Pydantic model + 严格约束 | P1 — 注入/越权 |
+| 不安全的 CORS | `allow_origins=["*"]` | 明确指定允许源列表 | P1 — CORS 安全 |
+| 调试接口 | 生产暴露 `/docs` / 调试路由 | 根据环境变量控制开启 | P1 — 信息泄露 |
+
+## 🔴 红线详情
+
+### 1. 密码存储 — 禁止明文 （P0）
+
+```python
+# ❌ 坏：明文存储
+user.password = request.password
+
+# ✅ 好：哈希后存储
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+class UserService:
+    def create_user(self, request: CreateUserRequest) -> User:
+        hashed = pwd_context.hash(request.password)
+        user = User(email=request.email, hashed_password=hashed)
+        return await user_repository.save(user)
+
+    def verify_password(self, plain: str, hashed: str) -> bool:
+        return pwd_context.verify(plain, hashed)
+
+# 验证密码
+is_valid = pwd_context.verify(plain_password, user.hashed_password)
+```
+
+### 2. SQL 拼接 — 禁止字符串拼接 （P0）
+
+```python
+# ❌ 坏：f-string 拼接 — SQL 注入
+query = f"SELECT * FROM users WHERE email = '{email}'"
+result = await db.execute(query)
+
+# ❌ 坏：format 拼接
+query = "SELECT * FROM users WHERE email = '{}'".format(email)
+result = await db.execute(query)
+
+# ✅ 好：SQLAlchemy ORM（首选）
+user = await db.query(User).filter(User.email == email).first()
+
+# ✅ 好：参数化查询（原生 SQL 时）
+from sqlalchemy import text
+query = text("SELECT * FROM users WHERE email = :email")
+result = await db.execute(query, {"email": email})
+
+# ✅ 好：原始 SQL 用 bind 参数
+cursor.execute("SELECT * FROM users WHERE email = %s", (email,))
+```
+
+**红线规则：**
+- 禁止在 SQL 中使用 `f"..."` 或 `"".format()` 拼接用户输入
+- 优先使用 SQLAlchemy ORM 的查询构建器
+- 必须使用原生 SQL 时，必须使用参数化查询（`:name` 或 `%s`）
+
+### 3. 硬编码密钥 — 禁止代码中内联 （P0）
+
+```python
+# ❌ 坏：硬编码 Secret
+SECRET_KEY = "sk-abc123..."
+API_KEY = "my-secret-key-12345"
+
+# ✅ 好：pydantic-settings 从环境变量读取
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    secret_key: str
+    api_key: str
+    database_url: str
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+    )
+
+settings = Settings()  # 从 .env 或环境变量加载
+```
+
+```bash
+# ❌ 坏：提交到 Git 的配置文件中有明文密钥
+# config.py
+SECRET_KEY = "my-secret-key"  # ← 硬编码
+
+# ✅ 好：.env 本地开发（不提交 Git）
+SECRET_KEY=my-secret-key
+API_KEY=sk-abc123...
+DATABASE_URL=postgresql://localhost:5432/dev
+
+# ✅ 好：CI/CD 中使用 CI Secrets 或 Vault
+# GitHub Actions Secrets / GitLab CI Variables
+```
+
+### 4. 敏感脱敏 — 日志中禁止打印敏感信息 （P1）
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+# ❌ 坏：直接打印敏感信息
+logger.info(f"User login: {email}, password: {password}")  # ← 密码泄露
+logger.info(f"Token: {token}")                               # ← Token 泄露
+print(f"Auth token: {token}")                                # ← 禁止 print
+
+# ✅ 好：脱敏后打印
+def mask_email(email: str) -> str:
+    at = email.find("@")
+    if at <= 1:
+        return email
+    return email[0] + "***" + email[at:]
+
+def mask_phone(phone: str) -> str:
+    if not phone or len(phone) < 7:
+        return phone
+    return phone[:3] + "****" + phone[-4:]
+
+logger.info(f"User login: {mask_email(email)}")
+logger.info(f"User [id={user_id}] logged in")
+```
+
+**红线规则：**
+- 禁止打印密码、Token、完整手机号、完整身份证号
+- 响应体中密码字段不输出（Pydantic `model_config` 排除或 response schema 中忽略）
+- 禁止 `print()` — 必须使用 `logging` 模块
+
+### 5. 输入验证红线 （P1）
+
+```python
+# ✅ 好：Pydantic model 严格约束
+from pydantic import BaseModel, Field, EmailStr, field_validator
+
+class CreateUserRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    email: EmailStr
+    age: int = Field(..., ge=0, le=150)
+    role: UserRole = UserRole.USER
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("名称不能为纯空格")
+        return v.strip()
+
+# ❌ 坏：不验证或用裸 dict
+@app.post("/users")
+async def create_user(name: str, email: str):  # ← 无约束
+    ...
+
+# ✅ 好：Router 中必须使用 Pydantic model
+@app.post("/users", response_model=ApiResponse[UserResponse])
+async def create_user(request: CreateUserRequest, ...):
+    ...
+```
+
+### 6. CORS 配置红线 （P1）
+
+```python
+# ❌ 坏：允许所有来源
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],        # ← 生产环境禁止
+    allow_credentials=True,     # ← allow_origins=["*"] 时配合 allow_credentials=True 无效且不安全
+)
+
+# ✅ 好：明确指定允许的来源
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "https://app.example.com",
+        "https://admin.example.com",
+    ],
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
+    allow_headers=["Authorization", "Content-Type"],
+)
+```
+
+### 7. 生产环境禁用调试接口 （P1）
+
+```python
+# ✅ 好：根据环境控制
+from app.core.config import settings
+
+app = FastAPI(
+    title="My App",
+    docs_url="/api/docs" if settings.ENV != "production" else None,
+    redoc_url=None,
+)
+
+# ❌ 坏：生产环境也暴露
+app = FastAPI(docs_url="/api/docs")  # ← 生产环境暴露 API 文档
+```