dynamic

中级（动态）技能

操作

操作	描述	示例
init	项目初始化（/init-dynamic 功能）	/dynamic init my-saas
guide	显示开发指南	/dynamic guide
help	BaaS 集成帮助	/dynamic help

init（项目初始化）

1. 创建 Next.js + Tailwind 项目结构
2. 配置 bkend.ai MCP（.mcp.json）
3. 创建 CLAUDE.md（指定级别：Dynamic）
4. 创建 docs/ 文件夹结构
5. 创建 src/lib/bkend.ts 客户端模板
6. 初始化 .bkit-memory.json

guide（开发指南）

• bkend.ai 身份验证/数据配置指南
• 阶段 1-9 完整 Pipeline 指南
• API 集成模式

help（BaaS 帮助）

• 解释 bkend.ai 基本概念
• 身份验证、数据库、文件存储的用法
• MCP 集成方法

目标受众

• 前端开发者
• 独立创业者
• 希望快速构建全栈服务的人员

技术栈

Frontend:
- React / Next.js 14+
- TypeScript
- Tailwind CSS
- TanStack Query (data fetching)
- Zustand (state management)

Backend (BaaS):
- bkend.ai
  - Auto REST API
  - MongoDB database
  - Built-in authentication (JWT)
  - Real-time features (WebSocket)

Deployment:
- Vercel (frontend)
- bkend.ai (backend)

语言层级指南（v1.3.0）

推荐：Tier 1-2 语言

Dynamic 级别支持与 AI 兼容性强的全栈开发。

层级	允许	原因
Tier 1	✅ 首选	全面支持 AI
Tier 2	✅ 支持	移动端（Flutter/RN）、现代 Web（Vue、Astro）
Tier 3	⚠️ 有限支持	仅适用于平台特定需求
Tier 4	❌ 不支持	建议迁移

移动端开发：

• React Native（通过 TypeScript 属于 Tier 1）- 推荐
• Flutter（通过 Dart 属于 Tier 2）- 支持

项目结构

project/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/            # Auth-related routes
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── (main)/            # Main routes
│   │   │   ├── dashboard/
│   │   │   └── settings/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   │
│   ├── components/             # UI components
│   │   ├── ui/                # Basic UI (Button, Input...)
│   │   └── features/          # Feature-specific components
│   │
│   ├── hooks/                  # Custom hooks
│   │   ├── useAuth.ts
│   │   └── useQuery.ts
│   │
│   ├── lib/                    # Utilities
│   │   ├── bkend.ts           # bkend.ai client
│   │   └── utils.ts
│   │
│   ├── stores/                 # State management (Zustand)
│   │   └── auth-store.ts
│   │
│   └── types/                  # TypeScript types
│       └── index.ts
│
├── docs/                       # PDCA documents
│   ├── 01-plan/
│   ├── 02-design/
│   │   ├── data-model.md      # Data model
│   │   └── api-spec.md        # API specification
│   ├── 03-analysis/
│   └── 04-report/
│
├── .mcp.json                   # bkend.ai MCP config (type: http)
├── .env.local                  # Environment variables
├── package.json
└── README.md

核心模式

bkend.ai 客户端设置

// lib/bkend.ts - REST Service API Client
const API_BASE = process.env.NEXT_PUBLIC_BKEND_API_URL || 'https://api.bkend.ai/v1';
const PROJECT_ID = process.env.NEXT_PUBLIC_BKEND_PROJECT_ID!;
const ENVIRONMENT = process.env.NEXT_PUBLIC_BKEND_ENV || 'dev';

async function bkendFetch(path: string, options: RequestInit = {}) {
  const token = localStorage.getItem('bkend_access_token');
  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'x-project-id': PROJECT_ID,
      'x-environment': ENVIRONMENT,
      ...(token && { Authorization: `Bearer ${token}` }),
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

export const bkend = {
  auth: {
    signup: (body: {email: string; password: string}) => bkendFetch('/auth/email/signup', {method: 'POST', body: JSON.stringify(body)}),
    signin: (body: {email: string; password: string}) => bkendFetch('/auth/email/signin', {method: 'POST', body: JSON.stringify(body)}),
    me: () => bkendFetch('/auth/me'),
    refresh: (refreshToken: string) => bkendFetch('/auth/refresh', {method: 'POST', body: JSON.stringify({refreshToken})}),
    signout: () => bkendFetch('/auth/signout', {method: 'POST'}),
  },
  data: {
    list: (table: string, params?: Record<string,string>) => bkendFetch(`/data/${table}?${new URLSearchParams(params)}`),
    get: (table: string, id: string) => bkendFetch(`/data/${table}/${id}`),
    create: (table: string, body: any) => bkendFetch(`/data/${table}`, {method: 'POST', body: JSON.stringify(body)}),
    update: (table: string, id: string, body: any) => bkendFetch(`/data/${table}/${id}`, {method: 'PATCH', body: JSON.stringify(body)}),
    delete: (table: string, id: string) => bkendFetch(`/data/${table}/${id}`, {method: 'DELETE'}),
  },
};

身份验证 Hook

// hooks/useAuth.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { bkend } from '@/lib/bkend';

interface AuthState {
  user: User | null;
  isLoading: boolean;
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
}

export const useAuth = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      isLoading: false,

      login: async (email, password) => {
        set({ isLoading: true });
        const { user, token } = await bkend.auth.login({ email, password });
        set({ user, isLoading: false });
      },

      logout: () => {
        bkend.auth.logout();
        set({ user: null });
      },
    }),
    { name: 'auth-storage' }
  )
);

数据获取（TanStack Query）

// List query
const { data, isLoading, error } = useQuery({
  queryKey: ['items', filters],
  queryFn: () => bkend.collection('items').find(filters),
});

// Single item query
const { data: item } = useQuery({
  queryKey: ['items', id],
  queryFn: () => bkend.collection('items').findById(id),
  enabled: !!id,
});

// Create/Update (Mutation)
const mutation = useMutation({
  mutationFn: (newItem) => bkend.collection('items').create(newItem),
  onSuccess: () => {
    queryClient.invalidateQueries(['items']);
  },
});

受保护的路由

// components/ProtectedRoute.tsx
'use client';

import { useAuth } from '@/hooks/useAuth';
import { redirect } from 'next/navigation';

export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { user, isLoading } = useAuth();

  if (isLoading) return <LoadingSpinner />;
  if (!user) redirect('/login');

  return <>{children}</>;
}

数据模型设计原则

// Base fields (auto-generated)
interface BaseDocument {
  _id: string;
  createdAt: Date;
  updatedAt: Date;
}

// User reference
interface Post extends BaseDocument {
  userId: string;        // Author ID (reference)
  title: string;
  content: string;
  tags: string[];        // Array field
  metadata: {            // Embedded object
    viewCount: number;
    likeCount: number;
  };
}

MCP 集成

Claude Code CLI（推荐）

claude mcp add bkend --transport http https://api.bkend.ai/mcp

.mcp.json（按项目配置）

{
  "mcpServers": {
    "bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp"
    }
  }
}

身份验证

• OAuth 2.1 + PKCE（浏览器自动身份验证）
• 无需 API Key/环境变量
• 首次 MCP 请求会打开浏览器 -> 登录 bkend 控制台 -> 选择 Organization -> 批准权限
• 验证：“Show my bkend projects”

## Environment Variables (.env.local)

NEXT_PUBLIC_BKEND_API_URL=https://api.bkend.ai/v1 NEXT_PUBLIC_BKEND_PROJECT_ID=your-project-id NEXT_PUBLIC_BKEND_ENV=dev

Note: Project ID is found in bkend console (console.bkend.ai).
Via MCP: "Show my project list" -> backend_project_list

## Limitations

❌ 复杂的后端逻辑（无服务器函数有数量限制） ❌ 大规模流量（受 BaaS 限制） ❌ 自定义基础设施控制 ❌ 微服务架构

## When to Upgrade

Move to **Enterprise Level** if you need:

→ “流量将大幅增长” → “我想拆分为微服务” → “我需要自己的服务器/基础设施” → “我需要复杂的后端逻辑”

## bkit Features for Dynamic Level (v1.5.1)

### Output Style: bkit-pdca-guide (Recommended)

For optimal PDCA workflow experience, activate the PDCA guide style:

/output-style bkit-pdca-guide

This provides:
- PDCA status badges showing current phase progress
- Gap analysis suggestions after code changes
- Automatic next-phase guidance with checklists

### Agent Teams (2 Teammates)

Dynamic projects support Agent Teams for parallel PDCA execution:

| Role | Agents | PDCA Phases |
|------|--------|-------------|
| developer | bkend-expert | Do, Act |
| qa | qa-monitor, gap-detector | Check |

**To enable:**
1. Set environment: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
2. Start team mode: `/pdca team {feature}`
3. Monitor progress: `/pdca team status`

### Agent Memory (Auto-Active)

All bkit agents automatically remember project context across sessions.
No setup needed — agents use `project` scope memory for this codebase.

---

## Common Mistakes

| Mistake | Solution |
|---------|----------|
| CORS error | Register domain in bkend.ai console |
| 401 Unauthorized | Token expired, re-login or refresh token |
| Data not showing | Check collection name, query conditions |
| Type error | Sync TypeScript type definitions with schema |