@deepstorm/cli 0.1.0

package/dist/skills/reef-style-backend/variants/python/examples/pytest-fixture.md

@@ -0,0 +1,60 @@
+# 示例：pytest Fixture
+
+```python
+# tests/conftest.py
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
+
+from app.main import app
+from app.models.base import Base
+from app.dependencies import get_async_session
+
+# 测试用内存数据库
+TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"
+
+@pytest.fixture(scope="session")
+def event_loop():
+    """session 级别的 event loop"""
+    import asyncio
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
+
+
+@pytest_asyncio.fixture(scope="session")
+async def engine():
+    """测试用引擎"""
+    engine = create_async_engine(TEST_DATABASE_URL, echo=False)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield engine
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+    await engine.dispose()
+
+
+@pytest_asyncio.fixture
+async def db_session(engine):
+    """每个测试独立事务"""
+    async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+    async with async_session() as session:
+        async with session.begin():
+            yield session
+        await session.rollback()
+
+
+@pytest_asyncio.fixture
+async def client(db_session: AsyncSession):
+    """HTTP 测试客户端"""
+
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_async_session] = override_get_db
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac
+    app.dependency_overrides.clear()
+```

package/dist/skills/reef-style-backend/variants/python/examples/sqlalchemy-model.md

@@ -0,0 +1,31 @@
+# 示例：SQLAlchemy Model
+
+```python
+# app/models/user.py
+from datetime import datetime
+from sqlalchemy import String, Integer, DateTime, Boolean, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from app.models.base import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, server_default=func.now(), nullable=False
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    # 关联关系
+    posts: Mapped[list["Post"]] = relationship(back_populates="author", lazy="selectin")
+
+    def __repr__(self) -> str:
+        return f"User(id={self.id}, name={self.name}, email={self.email})"
+```

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

@@ -0,0 +1,111 @@
+# 后端编码快速参考 — Python（FastAPI）
+
+按需加载。仅当你需要编写对应组件类型时阅读相关章节。
+
+> 已安装子维度的规范，通过该维度的 `{value}.md` 文件阅读。本页只包含 Python 语言通用的核心规范。
+>
+> **跨维度规范（适用所有后端代码）：**
+> - [API 规范](api-spec.md) — RESTful 命名、统一响应体、OpenAPI、版本策略
+> - [依赖管理规范](dependency-management.md) — pyproject.toml、版本声明、CVE
+> - [异常处理深度规范](exception-handling.md) — AppError 层次、错误码、全局处理
+> - [安全红线](security-redlines.md) — P0/P1 安全规则（必须遵守）
+
+## 推荐项目结构
+
+```
+app/
+├── api/v1/           # FastAPI routers（按领域分组）
+├── core/             # 配置、中间件、全局依赖
+├── models/           # SQLAlchemy ORM models
+├── schemas/          # Pydantic request/response schemas
+├── services/         # 业务逻辑层
+├── migrations/       # Alembic migration files
+├── tasks/            # 后台任务（Celery/ARQ）
+└── tests/            # pytest tests
+    ├── unit/         # 纯逻辑测试
+    └── integration/  # 集成测试（DB/API）
+```
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 字符串格式化 | 用 f-string（`f"Hello {name}"`），不用 `％` 或 `.format()` |
+| 类型分发 | 用多态 / Protocol，不用 `isinstance()` 链 |
+| 类型注释 | 都标注返回类型和参数类型（mypy 检查通过） |
+| 参数顺序 | 路由可见参数 → body → query → dependency |
+| 模块名 | snake_case，禁止驼峰 |
+| 弃用 API | mypy / ruff 警告中的废弃 API 在同一次 PR 中替换为新 API |
+| 类命名 | PascalCase（如 `UserService`、`CreateUserRequest`） |
+| 函数/变量命名 | snake_case（如 `get_user()`、`user_service`） |
+| 常量命名 | UPPER_SNAKE_CASE（如 `MAX_RETRY_COUNT`） |
+
+## 代码风格
+
+### 通用约定
+
+- 变量命名有意义，禁止单字母（循环计数器 `i`/`j`/`k` 除外）
+- 优先用类型别名 / Protocol 而不是裸字典或 `Any`
+- f-string 替代 `％` 格式化或 `.format()`
+- 用枚举（`StrEnum`）替代魔法字符串常量
+- 用 `is` / `is not` 比较 `None`，不用 `== None`
+- ruff 规则 `F`(Pyflakes) + `E`(pycodestyle) + `I`(isort) + `N`(pep8-naming) 全部通过
+- 100 列折行（black 默认），运算符放行首
+
+### Capability 模式
+
+当实体层次需要按子类暴露能力时，在基类中用 `ABC.abstractmethod` 声明，各子类按需实现：
+
+```python
+from abc import ABC, abstractmethod
+
+class FormControl(ABC):
+    @abstractmethod
+    def supports_importing(self) -> bool: ...
+
+class TextControl(FormControl):
+    def supports_importing(self) -> bool: return True
+
+class NumberControl(FormControl):
+    def supports_importing(self) -> bool: return False
+```
+
+**适用场景：** 基类有多个子类，且某个操作只在部分子类上有意义。
+**替代方案：** 用 `isinstance()` 判断 → ✗ 不推荐，违反开闭原则。
+**优势：** 开闭原则 — 新增子类只需在自己的类中覆盖方法；新增能力只需在基类加方法 + 各子类实现。
+
+## 类型注释规则
+
+| 声明位置 | 需要类型注释 |
+|---------|-------------|
+| 函数参数 | ✓ 是 |
+| 函数返回值 | ✓ 是（`-> None` 也必须标注） |
+| 模块级变量 | ✓ 是 |
+| 类属性 / Pydantic Field | ✓ 是 |
+| 循环变量 / 列表推导 | ✗ 否 |
+
+## 错误处理模式
+
+```python
+# ✅ 好：统一异常 + 全局 handler
+from fastapi import HTTPException
+
+class AppError(HTTPException):
+    def __init__(self, code: str, message: str, status_code: int = 400):
+        self.code = code
+        super().__init__(status_code=status_code, detail=message)
+
+# ✅ 好：Service 层抛自定义业务异常
+class UserNotFoundError(AppError):
+    def __init__(self, user_id: int):
+        super().__init__(code="USER_NOT_FOUND", message=f"User {user_id} not found", status_code=404)
+```
+
+## 常见坑
+
+| 场景 | 问题 | 正确做法 |
+|------|------|---------|
+| `isinstance()` 分发 | Service 层用 `isinstance()` 链判断所有子类型 | 优先在基类中用抽象方法 / Protocol |
+| 裸 `async` 阻塞 | `async` 函数内调了同步 IO 操作 | 用 `httpx.AsyncClient`、`asyncio.to_thread`、异步 ORM |
+| N+1 查询 | 循环内访问关联对象的属性，逐条 SELECT | 用 `selectinload()` / `joinedload()` 主动预加载 |
+| 类型不兼容 | mypy strict 模式通不过 | 所有函数标注类型，`None` 必须显式声明 |

package/dist/skills/reef-style-frontend/SKILL.md.tmpl

@@ -0,0 +1,70 @@
+---
+name: reef-style-frontend
+description: 前端编码规范（{{reef.frontend.framework.label}}）。创建/修改前端代码时必须按本技能输出。
+user-invocable: false
+allowed-tools: Bash(git:*), Bash({{reef.frontend.framework.buildTool}})
+model: opus
+deepstorm:
+  tool: reef
+  configKey: reef.frontend.framework
+---
+
+# 前端编码规范
+
+## ⚠️ 触发条件（必须遵守）
+
+创建或修改任何前端文件时，必须通过 Skill tool 加载本技能，并按本技能中所有规范输出代码。对应技术栈：{{reef.frontend.framework.label}}。
+
+> **仅对本次新增/修改的代码应用规范，不格式化已有代码。** 已有的、本次未修改的代码行保持原样。
+
+## 维度规范
+
+{{#if reef.frontend.framework.styleRef}}
+### 框架规范
+{{reef.frontend.framework.styleRef}}
+{{/if}}
+
+{{#if reef.frontend.tsConfig.styleRef}}
+### TypeScript 配置
+{{reef.frontend.tsConfig.styleRef}}
+{{/if}}
+
+{{#if reef.frontend.css.styleRef}}
+### CSS 方案
+{{reef.frontend.css.styleRef}}
+{{/if}}
+
+{{#if reef.frontend.uiLibrary.styleRef}}
+### UI 组件库
+{{reef.frontend.uiLibrary.styleRef}}
+{{/if}}
+
+{{#if reef.frontend.test.styleRef}}
+### 🧪 测试规范
+
+#### 通用原则
+- **测试金字塔**：Unit（单元测试）→ Integration（集成测试）→ E2E（端到端测试）。越底层测试越多，运行速度越快
+- **FIRST 原则**：Fast（快速）、Independent（独立）、Repeatable（可重复）、Self-validating（自验证）、Timely（及时）
+- **AAA 模式**：Arrange（准备）→ Act（执行）→ Assert（断言）
+
+#### 框架规范
+{{reef.frontend.test.styleRef}}
+{{/if}}
+
+## 知识文件
+
+以下文件位于本技能目录，安装时自动复制。内容按所选维度定制。
+
+加载本技能时先用 `Read` 读取 `quick-reference.md` 了解核心规范，再按照上方「维度规范」中的链接选择对应文件加载（如 `primeng.md`、`vitest.md`），最后根据当前变更类型在 `examples/` 目录中选择示例文件：
+
+| 文件 | 说明 |
+|------|------|
+| `quick-reference.md` | **编码规范速查**。包含核心规则和约定 |
+| `{value}.md` | **维度规范**（如 `primeng.md`、`tailwind.md`）。按上方链接加载 |
+| `examples/{文件}` | 按需加载示例文件（仅读与当前变更相关的） |
+
+## 使用方式
+
+- **创建/修改前端代码时**：Skill tool 自动加载（见触发条件）
+- `reef:reef-gen-frontend` — 编写前端代码时自动加载
+- `reef:reef-review-frontend` — 审查前端代码时自动加载

package/dist/skills/reef-style-frontend/fragments/css/tailwind/quick-reference.md

@@ -0,0 +1,79 @@
+# Tailwind CSS 规范
+
+## 概述
+
+使用 Tailwind CSS v4 的 utility-first 方式编写样式，不编写自定义 CSS。
+
+## 核心原则
+
+- **优先使用 Tailwind utility class**，不写手写 CSS
+- **组件样式写在模板的 `class` 属性中**，不在独立 CSS 文件中
+- **仅在以下场景使用 `@apply`**：多个重复使用的 utility 组合
+- **响应式**：使用 `sm:` / `md:` / `lg:` / `xl:` 前缀
+
+## 常用模式
+
+### 布局
+
+```html
+<!-- Flex 布局 -->
+<div class="flex items-center justify-between gap-4">
+  <div class="flex-1">左侧</div>
+  <div>右侧</div>
+</div>
+
+<!-- Grid 布局 -->
+<div class="grid grid-cols-3 gap-6">
+  <div class="col-span-2">主区域</div>
+  <div>侧边栏</div>
+</div>
+```
+
+### 间距
+
+```html
+<!-- 内边距 -->
+<div class="p-4 px-6 py-2 pt-0">
+
+<!-- 外边距 -->
+<div class="m-4 mt-2 mx-auto">
+```
+
+### 颜色
+
+```html
+<!-- 使用 Tailwind 色板 -->
+<div class="bg-blue-500 text-white hover:bg-blue-600">
+<button class="text-gray-700 border border-gray-300 rounded">
+```
+
+### 圆角与阴影
+
+```html
+<div class="rounded-lg shadow-sm">
+<button class="rounded-full shadow-md">
+```
+
+### 暗色模式
+
+```html
+<div class="bg-white dark:bg-gray-900 text-black dark:text-white">
+```
+
+## 自定义配置
+
+```css
+/* app.css — 仅添加 Tailwind 不支持的全局样式 */
+@import "tailwindcss";
+
+@theme {
+  --color-primary: #3b82f6;
+  --color-secondary: #8b5cf6;
+}
+```
+
+## 禁止事项
+
+- ❌ 不写手写 CSS 覆盖 Tailwind utility
+- ❌ 不使用 `!important`（Tailwind 的优先级系统已足够）
+- ❌ 不创建大量 `@apply` 封装（失去 utility-first 的优势）

package/dist/skills/reef-style-frontend/fragments/test/vitest/examples/testing.md

@@ -0,0 +1,150 @@
+# 前端测试示例
+
+## 1. 组件测试
+
+```typescript
+describe('FormListComponent', () => {
+  let fixture: ComponentFixture<FormListComponent>;
+
+  beforeEach(async () => {
+    TestBed.configureTestingModule({
+      imports: [FormListComponent],
+      providers: [provideHttpClient(withInterceptorsFromDi())],
+    });
+    fixture = TestBed.createComponent(FormListComponent);
+  });
+
+  it('should render form list', () => {
+    expect(fixture.nativeElement.querySelector('p-table')).toBeTruthy();
+  });
+});
+```
+
+关键点：Standalone 组件直接 `imports: [Component]`；PrimeNG 子组件用 `overrideComponent` 跳过渲染；`provideHttpClientTesting()` + `HttpTestingController` 模拟请求。
+
+## 2. Service 测试
+
+```typescript
+describe('FormService', () => {
+  let service: FormService;
+  let httpMock: HttpTestingController;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [FormService, provideHttpClient(withInterceptorsFromDi()), provideHttpClientTesting()],
+    });
+    service = TestBed.inject(FormService);
+    httpMock = TestBed.inject(HttpTestingController);
+  });
+
+  it('should GET forms', () => {
+    service.list(1).subscribe(res => expect(res.items.length).toBe(2));
+    const req = httpMock.expectOne('/api/v1/apps/1/forms');
+    expect(req.request.method).toBe('GET');
+    req.flush({ items: [{ id: 1 }, { id: 2 }], totalItems: 2 });
+  });
+});
+```
+
+## 3. Unit 测试（Pipe / Signal / E2E）
+
+```typescript
+// Pipe — 直接 new 实例，不依赖 TestBed
+it('should format LocalDateTime', () => {
+  const pipe = new LocalDateTimePipe();
+  expect(pipe.transform(LocalDateTime.of(2025, 1, 15, 14, 30), 'yyyy-MM-dd')).toBe('2025-01-15');
+});
+
+// Signal
+it('should update signal on submit', () => {
+  const comp = TestBed.createComponent(MyComponent).componentInstance;
+  comp.submit();
+  expect(comp.submitted()).toBe(true);
+});
+
+// E2E（Playwright）
+test('should display form list', async ({ page }) => {
+  await page.goto('/apps/1/forms');
+  await expect(page.locator('p-table')).toBeVisible();
+});
+```
+
+## 4. Testing Library 组件测试（推荐方式）
+
+```typescript
+import { render, screen, fireEvent } from '@testing-library/angular';
+
+describe('ButtonComponent', () => {
+  it('应使用 Testing Library render 渲染组件', async () => {
+    await render(ButtonComponent, { inputs: { label: '提交', disabled: false } });
+    expect(screen.getByRole('button', { name: '提交' })).toBeTruthy();
+  });
+
+  it('disabled 态应不可点击', async () => {
+    const onClick = vi.fn();
+    await render(ButtonComponent, { inputs: { label: '不可用', disabled: true, onClick } });
+    fireEvent.click(screen.getByRole('button'));
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});
+```
+
+关键点：`render()` 自动处理编译和变更检测；`screen.getByRole()` / `screen.getByText()` 按用户视角查找元素。
+
+## 5. 异步操作测试
+
+```typescript
+describe('UserListComponent（异步加载）', () => {
+  it('加载完成后应显示用户列表', async () => {
+    const mockService = {
+      getUsers: vi.fn().mockResolvedValue([{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]),
+    };
+    await render(UserListComponent, {
+      componentProviders: [{ provide: UserService, useValue: mockService }],
+    });
+    expect(await screen.findByText('Alice')).toBeTruthy();
+    expect(await screen.findByText('Bob')).toBeTruthy();
+  });
+
+  it('加载失败时应显示错误提示', async () => {
+    await render(UserListComponent, {
+      componentProviders: [{ provide: UserService, useValue: { getUsers: vi.fn().mockRejectedValue(new Error('fail')) } }],
+    });
+    expect(await screen.findByText(/加载失败/i)).toBeTruthy();
+  });
+});
+```
+
+## 6. 带依赖注入的 Service 测试
+
+```typescript
+describe('UserService（httpResource）', () => {
+  let service: UserService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [UserService, provideHttpClient(withInterceptorsFromDi()), provideHttpClientTesting()],
+    });
+    service = TestBed.inject(UserService);
+  });
+
+  it('应发送带 appId 的 GET 请求', () => {
+    const httpMock = TestBed.inject(HttpTestingController);
+    service.getUsers(1).subscribe(res => expect(res.items.length).toBe(1));
+    const req = httpMock.expectOne('/api/v1/apps/1/users');
+    expect(req.request.method).toBe('GET');
+    req.flush({ items: [{ id: 1, name: 'Alice' }], totalItems: 1 });
+    httpMock.verify();
+  });
+
+  it('应发送 POST 请求创建用户', () => {
+    const httpMock = TestBed.inject(HttpTestingController);
+    service.createUser(1, { name: 'Charlie' }).subscribe();
+    const req = httpMock.expectOne('/api/v1/apps/1/users');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual({ name: 'Charlie' });
+    req.flush({ id: 3, name: 'Charlie' });
+    httpMock.verify();
+  });
+});
+```

package/dist/skills/reef-style-frontend/fragments/test/vitest/quick-reference.md

@@ -0,0 +1,141 @@
+# Vitest 测试规范
+
+按需加载。编写测试时阅读相关章节。
+
+> **完整示例代码见 `examples/testing.md`**。
+
+## 概述
+
+使用 Vitest 作为单元测试框架，配合 Testing Library 进行组件测试。
+
+## 文件与命名规范
+
+- 测试文件放在 `__tests__/` 目录下，与被测文件同层级
+- 测试文件后缀：`.test.ts` 优先于 `.spec.ts`
+- describe/it 描述使用中文，说明被测功能
+- 固定 import 写法：
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/angular';
+```
+
+## 测试类型
+
+| 测试类型 | 范围 | 工具 | 关键关注点 |
+|---------|------|------|-----------|
+| 单元测试 | 单个函数/方法 | Vitest | 逻辑正确性、边界条件 |
+| 组件测试 | 单个组件 | Testing Library | 渲染、交互、事件 |
+
+## 基本模式
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/angular';
+import { ButtonComponent } from './button.component';
+
+describe('ButtonComponent', () => {
+  // 初始化
+  beforeEach(async () => {
+    await render(ButtonComponent, {
+      inputs: { label: '提交' },
+    });
+  });
+
+  // 验证渲染
+  it('应该渲染带 label 的按钮', () => {
+    expect(screen.getByText('提交')).toBeTruthy();
+  });
+
+  // 验证交互
+  it('点击按钮时应触发 click 事件', async () => {
+    const onClick = vi.fn();
+    await render(ButtonComponent, {
+      inputs: { onClick },
+    });
+    fireEvent.click(screen.getByRole('button'));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+## 异步测试
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/angular';
+
+describe('UserProfileComponent', () => {
+  it('异步加载用户数据后应显示用户名', async () => {
+    // 使用 fake timers 控制异步行为
+    vi.useFakeTimers();
+
+    await render(UserProfileComponent, {
+      componentProviders: [
+        {
+          provide: UserService,
+          useValue: {
+            getUser: () => Promise.resolve({ name: 'Alice' }),
+          },
+        },
+      ],
+    });
+
+    // 等待异步操作完成
+    vi.runAllTimers();
+
+    expect(await screen.findByText('Alice')).toBeTruthy();
+
+    vi.useRealTimers();
+  });
+});
+```
+
+## Signal 组件测试
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/angular';
+import { CounterComponent } from './counter.component';
+
+describe('CounterComponent (Signal)', () => {
+  it('点击按钮后计数应增加', async () => {
+    await render(CounterComponent);
+
+    const button = screen.getByRole('button', { name: /增加/i });
+    expect(screen.getByText('计数: 0')).toBeTruthy();
+
+    fireEvent.click(button);
+
+    // Signal 是同步更新的，不需要额外等待
+    expect(screen.getByText('计数: 1')).toBeTruthy();
+  });
+});
+```
+
+## Mock 规范
+
+```typescript
+import { vi } from 'vitest';
+
+// 模拟服务
+const mockUserService = {
+  getUser: vi.fn().mockResolvedValue({ id: 1, name: 'Test' }),
+};
+
+// 模拟模块
+vi.mock('./user.service', () => ({
+  UserService: vi.fn().mockImplementation(() => mockUserService),
+}));
+
+// 异步 mock
+const mockFetch = vi.fn().mockRejectedValue(new Error('Network error'));
+vi.stubGlobal('fetch', mockFetch);
+```
+
+## 覆盖率要求
+
+- 语句覆盖率: ≥80%
+- 分支覆盖率: ≥75%
+- 函数覆盖率: ≥85%
+- 行覆盖率: ≥80%