Auto Develop

OPC-Starter 智能开发技能

项目定位: OPC-Starter (一人公司启动器) 是一个 AI 亲和的 React Boilerplate，专为使用 Cursor、Qoder 等 AI Coding 工具的开发者设计。

>

核心理念: 像高级研发专家 Amelia 一样执行 —— 测试即规范，代码即实现，精准定位，无冗余输出。

---

🎯 动态上下文系统

上下文感知规则

根据任务类型自动加载相关文档和约束，避免无关信息干扰。

执行前自检

开始任务前，检测以下条件并动态加载规则：

context_check:
  - keyword_match: 检测任务描述关键词
  - file_scope: 检测涉及的文件路径
  - change_type: 判断是新功能/Bug修复/重构
  
auto_load:
  agent_module: "app/src/components/agent/**" | "app/src/lib/agent/**"
  ui_module: "app/src/components/**" | "app/src/pages/**"
  data_module: "app/src/services/data/**" | "app/supabase/**"
  test_module: "**/*.test.ts" | "**/*.spec.ts" | "cypress/**"

---

📊 项目核心架构

技术栈

目录结构

opc-starter/
├── app/                          # 主应用
│   ├── src/
│   │   ├── auth/                 # 认证模块
│   │   ├── components/
│   │   │   ├── agent/            # Agent Studio ⭐
│   │   │   │   └── a2ui/         # A2UI 渲染系统
│   │   │   ├── business/         # 业务组件
│   │   │   ├── layout/           # 布局组件
│   │   │   ├── organization/     # 组织架构
│   │   │   └── ui/               # 基础 UI (shadcn)
│   │   ├── pages/                # 页面组件
│   │   ├── services/
│   │   │   └── data/             # DataService (核心) ⭐
│   │   ├── stores/               # Zustand Store
│   │   ├── lib/
│   │   │   ├── agent/            # Agent 客户端 ⭐
│   │   │   │   └── tools/        # 前端工具执行器
│   │   │   └── supabase/         # Supabase 客户端
│   │   ├── hooks/                # 自定义 Hooks
│   │   ├── types/                # TypeScript 类型
│   │   └── mocks/                # MSW Mock
│   └── supabase/
│       ├── functions/
│       │   └── ai-assistant/    # Agent SSE 网关 ⭐
│       └── setup.sql             # 数据库脚本 (所有变更集中于此)
├── docs/
│   ├── Architecture.md           # 系统架构
│   └── Epics.yaml                # 项目进度
├── _bmad/                        # BMAD 方法论 (可选参考)
└── AGENTS.md                     # AI Coding 快速指南

核心能力模块

---

🔴🟢🔵 TDD 核心原则

红-绿-重构循环

┌─────────────────────────────────────────────────────────────┐
│                    TDD 循环 (每个功能点)                     │
│                                                             │
│     🔴 RED          🟢 GREEN         🔵 REFACTOR           │
│   ┌─────────┐     ┌─────────┐     ┌─────────┐              │
│   │ 写失败  │────▶│ 写最小  │────▶│ 优化    │──┐           │
│   │ 的测试  │     │ 实现代码 │     │ 重构    │  │           │
│   └─────────┘     └─────────┘     └─────────┘  │           │
│        ▲                                        │           │
│        └────────────────────────────────────────┘           │
│                    (下一个功能点)                            │
└─────────────────────────────────────────────────────────────┘

测试先行原则 ⚠️ MANDATORY

❌ 禁止：先写代码再补测试
❌ 禁止：提交没有测试覆盖的新功能
❌ 禁止：修改代码后不运行测试就提交

✅ 必须：新功能先写测试用例
✅ 必须：Bug 修复先写复现测试
✅ 必须：每次提交前运行完整测试套件

测试金字塔

---

🤖 Agent Studio 开发规范

当任务涉及 Agent 相关开发时，自动加载此章节。

架构流程

用户 ←→ AgentWindow (悬浮对话框)
           ↓
      useAgentChat Hook
           ↓
      SSE Client ←→ ai-assistant (Edge Function)
           ↓                    ↓
      Tool Executor         Qwen-Plus (百炼 API)
           ↓
      A2UI Renderer (动态 UI)

核心文件

添加新 Agent Tool

1. 后端: 在 ai-assistant/tools.ts 添加工具定义 (OpenAI 格式) 2. 前端: 在 app/src/lib/agent/tools/ 创建工具目录 3. 注册: 在 app/src/lib/agent/tools/registry.ts 注册 4. System Prompt: 在 ai-assistant/sse.ts 的 buildSystemPrompt() 中添加使用说明

// 工具定义示例 (OpenAI 格式)
{
  type: "function",
  function: {
    name: "myNewTool",
    description: "工具描述",
    parameters: {
      type: "object",
      properties: { /* ... */ },
      required: ["param1"],
    },
  },
}

添加新 A2UI 组件

1. 在 app/src/components/agent/a2ui/components/ 创建组件 2. 在 registry.ts 注册组件 (白名单模式) 3. 在 app/src/types/a2ui.ts 添加类型定义

// registry.ts 注册示例
export const A2UI_REGISTRY: A2UIComponentRegistry = {
  'my-component': MyComponent,
};

A2UI Action ID 规范

Mock LLM 测试

使用 MSW 模拟 Agent 响应：

// app/src/mocks/handlers/agentHandlers.ts
http.post('*/functions/v1/ai-assistant', async ({ request }) => {
  // 返回 SSE 流式响应
});

---

🎨 设计系统规范

当任务涉及 UI 组件开发时，自动加载此章节。

Tailwind CSS v4 语法 (Mandatory)

// ❌ 禁止：v2/v3 语法
className="bg-opacity-50 bg-gradient-to-r"

// ✅ 正确：v4 语法
className="bg-black/50 bg-linear-to-r"

语义化颜色 (暗色模式适配)

核心原则: 使用语义化颜色，禁止硬编码颜色值。

// ❌ 禁止：硬编码颜色
<div className="bg-white text-gray-900 border-gray-200">

// ✅ 正确：语义化颜色
<div className="bg-card text-foreground border">

移动端覆盖组件 ⚠️ CRITICAL

Sidebar、Modal、Dropdown 等覆盖层必须使用显式颜色 + `dark:` 前缀

// ❌ 错误：CSS 变量在移动端覆盖层可能失效
<aside className="bg-card text-foreground">

// ✅ 正确：显式颜色
<aside className="bg-white dark:bg-slate-900 text-gray-900 dark:text-gray-100">

---

💾 数据访问规范

DataService 统一访问

// ✅ 正确：通过 DataService 访问
import { dataService } from '@/services/data/DataService'
await dataService.getAll('profiles')

// ❌ 禁止：直接访问
import { supabase } from '@/lib/supabase/client'  // 禁止

数据流架构

┌─────────────────────────────────────────────────┐
│  UI Layer → Zustand Stores → DataService        │
│                                   │             │
│                    ┌──────────────┼──────────┐  │
│                    │         IndexedDB       │  │
│                    │    • 读: 100% 本地      │  │
│                    │    • 写: 乐观更新       │  │
│                    │    • 同步: Realtime     │  │
│                    └──────────────┼──────────┘  │
│                                   │             │
│                    ┌──────────────┼──────────┐  │
│                    │         Supabase        │  │
│                    │    • Postgres Changes   │  │
│                    └─────────────────────────┘  │
└─────────────────────────────────────────────────┘

SQL 变更集中管理

所有数据库变更 → app/supabase/setup.sql（禁止创建独立 SQL 文件）

---

🐛 Bug 修复规范

当任务为 Bug 修复时，自动加载此章节。

核心原则：先查数据，再改代码

发现问题 → 浏览器调试验证 → 定位根因 → 一次性修复 → 验证通过

调试步骤

1. 使用浏览器 DevTools

• Network 面板：检查 API 请求和响应数据
• Console 面板：查看日志和错误信息

2. 添加临时调试日志

   console.log('[Debug] 数据状态:', JSON.stringify(data, null, 2));

3. 常见数据完整性问题

防御性编码

// ❌ 假设数据一定有效
const coverUrl = await getPhotoUrl(album.photoIds[0]);

// ✅ 遍历找到第一个有效项
for (const photoId of album.photoIds) {
  const url = photoUrlMap.get(photoId);
  if (url) {
    album.coverPhotoUrl = url;
    break;
  }
}

---

✅ 开发工作流

完整流程

需求/Bug → BMAD 方案讨论(可选) → Epic/Story/Task → 🔴测试先行 → 🟢代码实现 → 🔵重构优化 → 质量验证 → 人工审查 → 上线

Phase 1: TDD 测试先行 🔴

npm run test:watch    # 监听模式（开发时）

测试文件命名: *.test.ts 或 *.spec.ts，与源文件同目录

// app/src/services/example.test.ts
import { describe, it, expect, vi } from 'vitest'

describe('ExampleService', () => {
  it('应该完成预期功能', async () => {
    // Arrange - 准备测试数据
    // Act - 执行待测函数
    // Assert - 验证结果
  })
})

Phase 2: 代码实现 🟢

遵循技术约束完成代码实现。详见 references/coding-constraints.md。

Phase 3: 重构优化 🔵

✅ 测试全部通过后再重构
✅ 每次小步重构后运行测试
✅ 提取公共方法、消除重复

❌ 不要在重构时添加新功能

Phase 4: 质量验证

# 一键质量验证
./scripts/quality_check.sh

# 核心校验（不含 E2E）
npm run ai:check

# 或手动执行
npm run lint:check        # ESLint 检查
npm run format:check      # Prettier 格式检查
npm run type-check        # TypeScript 类型检查
npm run test              # 单元测试
npm run test:e2e:headless # E2E 回归测试
npm run build             # 构建验证

---

🚫 禁止清单

编码禁止

TDD 禁止

---

📚 参考文档

按需加载

外部文档

BMAD 方法论参考 (可选)

当需要规范化需求分析、方案设计时，可参考 BMAD 工作流：

---

🚀 快速命令

# 开发
npm run dev           # 启动开发服务器
npm run dev:test      # 测试模式 (MSW mock)

# TDD 测试
npm run test          # 运行单元测试
npm run test:watch    # 监听模式（开发时推荐）
npm run coverage      # 生成覆盖率报告

# E2E 测试
npm run cypress:open  # 在已启动 dev:test 时交互运行 Cypress
npm run test:e2e      # 启动 dev:test 后无头运行 E2E
npm run test:e2e:headless  # Cypress 无头模式 (CI)

# 质量检查
npm run lint          # ESLint 检查并修复
npm run format        # Prettier 格式化
npm run type-check    # TypeScript 类型检查
npm run build         # 生产构建

# 一键质量验证
npm run ai:check
./scripts/quality_check.sh

推荐工作流

# 1. 启动测试监听（新终端窗口）
npm run test:watch

# 2. 启动开发服务器（另一个终端窗口）
npm run dev:test

# 3. 🔴 编写测试 → 看到红色失败
# 4. 🟢 实现代码 → 看到绿色通过
# 5. 🔵 重构优化
# 6. 提交前运行完整质量检查
./scripts/quality_check.sh

OPC-Starter 系统架构

一人公司启动器 - AI 亲和的 React Boilerplate

技术栈

架构图

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            前端 (React 19)                                       │
│  UI 组件 → Zustand Store → DataService → IndexedDB                              │
└─────────────────────────────────────────────────────────────────────────────────┘
                               ↓ ↑
┌─────────────────────────────────────────────────────────────────────────────────┐
│                         Supabase (BaaS 平台)                                     │
│            Auth + PostgreSQL + Storage + Edge Functions + Realtime              │
└─────────────────────────────────────────────────────────────────────────────────┘
                               ↓ ↑
┌─────────────────────────────────────────────────────────────────────────────────┐
│                      百炼 AI API (OpenAI 兼容)                                   │
│                          Qwen-Plus Agent                                         │
└─────────────────────────────────────────────────────────────────────────────────┘

数据流架构

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    简化架构: Cache + Realtime                                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│  UI Layer → Zustand Stores → DataService                                        │
│                                    │                                             │
│                    ┌───────────────┼───────────────┐                            │
│                    │               ▼               │                            │
│                    │         IndexedDB             │                            │
│                    │  ┌─────────────────────────┐  │                            │
│                    │  │ profiles│organizations │  │                            │
│                    │  └─────────────────────────┘  │                            │
│                    │               │               │                            │
│                    │         CacheManager          │                            │
│                    │    • 读: 100% 本地            │                            │
│                    │    • 写: 乐观更新             │                            │
│                    │    • 同步: Realtime          │                            │
│                    └───────────────┼───────────────┘                            │
│                                    │                                             │
│                    ┌───────────────┼───────────────┐                            │
│                    │         Supabase              │                            │
│                    │  • Postgres Changes (全表)    │                            │
│                    │  • profiles/organizations    │                            │
│                    └───────────────────────────────┘                            │
└─────────────────────────────────────────────────────────────────────────────────┘

Agent Studio 架构

用户 ←→ AgentWindow (悬浮对话框)
           ↓
      useAgentChat Hook
           ↓
      SSE Client ←→ ai-assistant (Edge Function)
           ↓                    ↓
      Tool Executor         Qwen-Plus (百炼 API)
           ↓
      A2UI Renderer (动态 UI)

Agent 核心组件

核心模块

1. 认证系统 (Auth)

• Supabase Auth 集成
• JWT Token 管理
• 会话持久化

2. 组织架构 (Organization)

• 多层级组织结构
• 角色权限管理 (admin/manager/member)
• RLS 策略保护

3. 数据同步层 (DataService)

• 统一数据访问入口
• IndexedDB 本地缓存
• Supabase Realtime 同步
• 乐观更新模式

数据访问模式

所有数据操作必须通过 `DataService`

Edge Functions

核心 Store

RLS 策略

使用 SECURITY DEFINER 函数处理层级数据，避免无限递归：

CREATE FUNCTION get_user_accessible_organizations(user_uuid UUID)
RETURNS TABLE(organization_id UUID)
SECURITY DEFINER;

Edge Functions

可用函数

Agent Gateway 架构

用户请求 → ai-assistant (Edge Function)
                ↓
        ┌───────┴───────┐
        ↓               ↓
   Qwen-Plus (百炼)  工具调用
        ↓               ↓
        └───────┬───────┘
                ↓
          SSE 流式响应 → 前端

核心文件

添加新 Agent Tool

1. 在 tools.ts 添加工具定义：

{
  type: "function",
  function: {
    name: "myNewTool",
    description: "工具描述",
    parameters: {
      type: "object",
      properties: {
        param1: { type: "string", description: "参数描述" }
      },
      required: ["param1"],
    },
  },
}

2. 在前端 app/src/lib/agent/tools/ 创建对应执行器 3. 在 registry.ts 注册工具

部署

# 部署 ai-assistant
cd app/supabase && supabase functions deploy ai-assistant

# 本地开发
cd app/supabase && supabase functions serve ai-assistant

位置

所有 Edge Functions 位于 app/supabase/functions/

环境变量

ai-assistant 需要以下环境变量：

在 Supabase Dashboard → Settings → Edge Functions → Secrets 中配置。

OPC-Starter 项目结构

一人公司启动器 - AI 亲和的 React Boilerplate

目录结构

opc-starter/
├── app/                          # 主应用
│   ├── src/
│   │   ├── auth/                 # 认证模块
│   │   │   ├── components/       # 认证组件
│   │   │   └── pages/            # 认证页面
│   │   ├── components/
│   │   │   ├── agent/            # Agent Studio ⭐
│   │   │   │   ├── a2ui/         # A2UI 渲染系统
│   │   │   │   │   ├── components/  # A2UI 业务组件
│   │   │   │   │   ├── registry.ts  # 组件白名单
│   │   │   │   │   └── A2UIRenderer.tsx
│   │   │   │   ├── AgentWindow.tsx
│   │   │   │   ├── AgentThread.tsx
│   │   │   │   └── AgentInput.tsx
│   │   │   ├── business/         # 业务组件
│   │   │   ├── layout/           # 布局组件
│   │   │   │   ├── Header/
│   │   │   │   ├── MainLayout/
│   │   │   │   └── Sidebar/
│   │   │   ├── organization/     # 组织架构
│   │   │   └── ui/               # 基础 UI (shadcn)
│   │   ├── pages/                # 页面组件
│   │   │   ├── DashboardPage.tsx
│   │   │   ├── ProfilePage.tsx
│   │   │   └── SettingsPage.tsx
│   │   ├── services/
│   │   │   ├── data/             # DataService (核心) ⭐
│   │   │   │   └── DataService.ts
│   │   │   ├── api/              # API 服务
│   │   │   └── storage/          # 存储服务
│   │   ├── stores/               # Zustand Store
│   │   │   ├── useAuthStore.ts
│   │   │   ├── useProfileStore.ts
│   │   │   ├── useAgentStore.ts
│   │   │   └── useUIStore.ts
│   │   ├── lib/
│   │   │   ├── agent/            # Agent 客户端 ⭐
│   │   │   │   ├── sseClient.ts     # SSE 流客户端
│   │   │   │   ├── toolExecutor.ts  # 工具执行器
│   │   │   │   └── tools/           # 前端工具
│   │   │   │       ├── registry.ts
│   │   │   │       ├── navigation/
│   │   │   │       └── context/
│   │   │   ├── reactive/         # 响应式适配器
│   │   │   └── supabase/         # Supabase 客户端
│   │   │       └── client.ts
│   │   ├── hooks/                # 自定义 Hooks
│   │   │   ├── useAgentChat.ts
│   │   │   ├── useOrganization.ts
│   │   │   ├── useSyncStatus.ts
│   │   │   └── useTheme.ts
│   │   ├── types/                # TypeScript 类型
│   │   │   ├── a2ui.ts
│   │   │   ├── agent.ts
│   │   │   ├── auth.ts
│   │   │   └── person.ts
│   │   ├── config/               # 配置
│   │   │   ├── routes.tsx
│   │   │   └── constants.ts
│   │   ├── utils/                # 工具函数
│   │   └── mocks/                # MSW Mock
│   │       ├── handlers/
│   │       │   ├── authHandlers.ts
│   │       │   ├── agentHandlers.ts
│   │       │   └── supabaseRestHandlers.ts
│   │       └── data/
│   └── supabase/
│       ├── functions/
│       │   └── ai-assistant/    # Agent SSE 网关 ⭐
│       │       ├── index.ts
│       │       ├── tools.ts
│       │       └── prompts/
│       ├── setup.sql             # 数据库脚本 (所有变更集中于此)
│       └── SUPABASE_COOKBOOK.md
├── cypress/                      # E2E 测试
│   ├── e2e/
│   ├── fixtures/
│   │   └── users.json            # 测试用户凭证
│   └── support/
├── docs/
│   ├── Architecture.md           # 系统架构
│   └── Epics.yaml                # 项目进度
├── _bmad/                        # BMAD 方法论 (可选参考)
│   ├── bmm/agents/               # Agent 角色定义
│   └── bmm/workflows/            # 标准化工作流
├── .qoder/skills/                # Qoder 技能
│   └── auto-develop/             # 当前技能
├── AGENTS.md                     # AI Coding 快速指南
└── package.json

核心文件

核心 Store

文档更新策略

扩展指南

添加新页面

1. 在 app/src/pages/ 创建页面组件 2. 在 app/src/config/routes.tsx 添加路由 3. 在 app/src/components/layout/MainLayout/ 添加导航入口

添加新数据实体

1. 在 app/src/types/ 定义类型 2. 在 app/src/services/data/adapters/ 创建适配器 3. 在 app/src/stores/ 创建 Zustand Store 4. 更新 app/supabase/setup.sql 添加表结构

添加新 Agent Tool

1. 后端: 在 ai-assistant/tools.ts 添加工具定义 (OpenAI 格式) 2. 前端: 在 app/src/lib/agent/tools/ 创建工具目录 3. 注册: 在 app/src/lib/agent/tools/registry.ts 注册 4. System Prompt: 在 ai-assistant/prompts/ 添加使用说明

添加新 A2UI 组件

1. 在 app/src/components/agent/a2ui/components/ 创建组件 2. 在 registry.ts 注册组件 (白名单模式) 3. 在 app/src/types/a2ui.ts 添加类型定义

NPM Scripts

# 开发
npm run dev           # 启动开发服务器
npm run dev:test      # 测试模式 (MSW mock)

# 测试
npm run test          # 单元测试
npm run test:watch    # 监听模式
npm run coverage      # 覆盖率报告
npm run cypress:open  # 在已启动 dev:test 时交互运行 Cypress
npm run test:e2e      # 启动 dev:test 后无头运行 E2E
npm run test:e2e:headless  # Cypress 无头模式

# 质量检查
npm run lint          # ESLint 检查并修复
npm run lint:check    # ESLint 仅检查
npm run format        # Prettier 格式化
npm run format:check  # Prettier 检查
npm run type-check    # TypeScript 类型检查
npm run ai:check      # 核心 AI 迭代校验

# 构建
npm run build         # 生产构建
npm run preview       # 预览构建结果