OPC-Starter 智能开发技能

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

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

---

🎯 动态上下文系统

上下文感知规则

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

任务关键词	触发上下文	加载文档
Agent、工具、Tool、A2UI	Agent Studio 开发	AGENTS.md → Agent 规范章节
组件、页面、UI、样式	前端 UI 开发	references/coding-constraints.md → 设计系统
数据库、SQL、表、字段	数据库变更	references/db-sync-checklist.md
测试、TDD、Cypress、Vitest	测试开发	references/tdd-workflow.md
Bug、修复、异常、报错	问题排查	references/troubleshooting.md
架构、模块、服务	系统设计	docs/Architecture.md

执行前自检

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

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/**"

---

📊 项目核心架构

技术栈

技术	版本	注意事项
React	19.1	最新稳定版
TypeScript	5.9	严格类型
Vite	7.1	构建工具
Tailwind CSS	4.1	⚠️ 必须使用 v4 语法
Supabase	2.80	Auth + Storage + Realtime + Edge Functions
Zustand	5.0	状态管理
Vitest	4.0	单元测试框架
Cypress	15.7	E2E 测试框架
Qwen-Plus	via 百炼 API	Agent LLM（通义千问）
A2UI	v0.8	Agent 动态 UI 协议

目录结构

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 快速指南

核心能力模块

模块	关键文件	说明
认证系统	app/src/auth/	Supabase Auth + JWT
组织架构	app/src/components/organization/	多层级团队、成员、角色
Agent Studio	app/src/components/agent/	自然语言 AI 助手 ⭐
数据同步	app/src/services/data/DataService.ts	IndexedDB + Realtime
个人中心	app/src/pages/ProfilePage.tsx	用户信息、头像

---

🔴🟢🔵 TDD 核心原则

红-绿-重构循环

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

阶段	目标	规则
🔴 RED	编写失败的测试	测试必须明确表达需求意图
🟢 GREEN	写最小代码通过测试	只写刚好让测试通过的代码
🔵 REFACTOR	优化代码结构	测试保持通过，消除重复

测试先行原则 ⚠️ MANDATORY

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

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

测试金字塔

层级	测试类型	覆盖目标	运行频率
底层	单元测试 (Vitest)	工具函数、Services、Hooks	每次保存
中层	集成测试 (Vitest)	DataService、Store 交互	每次提交
顶层	E2E 测试 (Cypress)	登录、核心用户流程	PR 合并前

---

🤖 Agent Studio 开发规范

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

架构流程

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

核心文件

文件	职责
app/src/components/agent/AgentWindow.tsx	悬浮对话窗口
app/src/hooks/useAgentChat.ts	Agent 对话状态管理
app/src/lib/agent/sseClient.ts	SSE 流式客户端
app/src/lib/agent/toolExecutor.ts	本地工具执行器
app/src/components/agent/a2ui/A2UIRenderer.tsx	A2UI 组件渲染器
app/src/components/agent/a2ui/registry.ts	组件白名单注册表
app/supabase/functions/ai-assistant/	Agent 后端网关

添加新 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 规范

类别	Action ID 格式	示例
导航	navigation.*	navigation.goTo
用户	user.*	user.updateProfile
组织	org.*	org.createTeam

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"

禁止 (v2/v3)	使用 (v4)
bg-opacity-*	bg-color/opacity
bg-gradient-to-*	bg-linear-to-*

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

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

语义化颜色	用途	❌ 禁止使用
bg-background	页面背景	bg-gray-50, bg-white
bg-card	卡片/容器背景	bg-white
text-foreground	主要文字	text-gray-900, text-black
text-muted-foreground	次要文字	text-gray-500
border	边框	border-gray-200
bg-primary	主色按钮	bg-blue-600
bg-destructive	危险操作	bg-red-600

// ❌ 禁止：硬编码颜色
<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. 常见数据完整性问题

问题场景	症状	排查方法
外键引用失效	关联查询返回 null	检查被引用记录是否存在
数组包含无效 ID	批量查询返回部分数据	对比请求 ID 和响应数据
字段为空	功能不生效	检查数据库记录实际值

防御性编码

// ❌ 假设数据一定有效
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             # 构建验证

检查项	命令	通过标准
ESLint	npm run lint:check	0 错误
TypeScript	npm run type-check	0 错误
单元测试	npm run test	全部通过
E2E 测试	npm run test:e2e:headless	全部通过
构建	npm run build	成功

---

🚫 禁止清单

编码禁止

类别	禁止事项
Tailwind	*-opacity-* 语法、bg-gradient-to-*
颜色	硬编码颜色如 bg-white、text-gray-900、bg-blue-600
覆盖层	Sidebar/Modal/Dropdown 使用 CSS 变量颜色
数据访问	直接导入 supabase client
文件管理	创建独立 SQL 迁移文件、创建新文档文件
TypeScript	使用 any 类型
React Hooks	useCallback 作为 useEffect 依赖（无 ref guard）
Agent	在 A2UI 中使用未注册的组件类型
Agent	直接调用 LLM API（必须通过 ai-assistant Edge Function）

TDD 禁止

禁止事项	后果
先写代码再补测试	代码设计不佳，难以测试
提交无测试覆盖的新功能	回归风险，无法保证质量
不运行测试就提交代码	CI 失败，阻塞其他人
忽略测试失败继续开发	问题堆积，修复成本增加

---

📚 参考文档

按需加载

文档	内容	触发关键词
references/tdd-workflow.md	TDD 完整流程、测试编写规范	vitest, cypress, test
references/coding-constraints.md	编码约束、React Hooks 反模式	useEffect, hooks, ltree
references/project-structure.md	项目结构、NPM 命令	structure, npm
references/db-sync-checklist.md	数据库一致性检查	CHECK, migration, sql
references/troubleshooting.md	常见问题与解决方案	error, fix, debug

外部文档

文档	用途
docs/Architecture.md	完整系统架构
docs/Epics.yaml	项目进度追踪
AGENTS.md	AI Coding 快速指南
app/supabase/SUPABASE_COOKBOOK.md	数据库操作手册

BMAD 方法论参考 (可选)

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

Agent	用途
_bmad/bmm/agents/dev.md (Amelia)	高级研发专家，精准执行 Story
_bmad/bmm/agents/architect.md	系统架构师，技术方案设计
_bmad/bmm/workflows/	标准化工作流

---

🚀 快速命令

# 开发
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