القائمة
OPC-Starter 智能开发技能。AI 亲和的 React Boilerplate 项目开发规范，支持动态上下文感知、TDD 驱动开发、Agent Studio 扩展。适用于认证系统、组织架构、Agent 工具、数据同步等模块的迭代开发。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/alibaba/opc-starter --skill auto-developيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | auto-develop |
| description | OPC-Starter 智能开发技能。AI 亲和的 React Boilerplate 项目开发规范，支持动态上下文感知、TDD 驱动开发、Agent Studio 扩展。适用于认证系统、组织架构、Agent 工具、数据同步等模块的迭代开发。 |
项目定位: 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 循环 (每个功能点) │
│ │
│ 🔴 RED 🟢 GREEN 🔵 REFACTOR │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 写失败 │────▶│ 写最小 │────▶│ 优化 │──┐ │
│ │ 的测试 │ │ 实现代码 │ │ 重构 │ │ │
│ └─────────┘ └─────────┘ └─────────┘ │ │
│ ▲ │ │
│ └────────────────────────────────────────┘ │
│ (下一个功能点) │
└─────────────────────────────────────────────────────────────┘
| 阶段 | 目标 | 规则 |
|---|---|---|
| 🔴 RED | 编写失败的测试 | 测试必须明确表达需求意图 |
| 🟢 GREEN | 写最小代码通过测试 | 只写刚好让测试通过的代码 |
| 🔵 REFACTOR | 优化代码结构 | 测试保持通过，消除重复 |
❌ 禁止：先写代码再补测试
❌ 禁止：提交没有测试覆盖的新功能
❌ 禁止：修改代码后不运行测试就提交
✅ 必须：新功能先写测试用例
✅ 必须：Bug 修复先写复现测试
✅ 必须：每次提交前运行完整测试套件
| 层级 | 测试类型 | 覆盖目标 | 运行频率 |
|---|---|---|---|
| 底层 | 单元测试 (Vitest) | 工具函数、Services、Hooks | 每次保存 |
| 中层 | 集成测试 (Vitest) | DataService、Store 交互 | 每次提交 |
| 顶层 | E2E 测试 (Cypress) | 登录、核心用户流程 | PR 合并前 |
当任务涉及 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 后端网关 |
ai-assistant/tools.ts 添加工具定义 (OpenAI 格式)app/src/lib/agent/tools/ 创建工具目录app/src/lib/agent/tools/registry.ts 注册ai-assistant/sse.ts 的 buildSystemPrompt() 中添加使用说明// 工具定义示例 (OpenAI 格式)
{
type: "function",
function: {
name: "myNewTool",
description: "工具描述",
parameters: {
type: "object",
properties: { /* ... */ },
required: ["param1"],
},
},
}
app/src/components/agent/a2ui/components/ 创建组件registry.ts 注册组件 (白名单模式)app/src/types/a2ui.ts 添加类型定义// registry.ts 注册示例
export const A2UI_REGISTRY: A2UIComponentRegistry = {
'my-component': MyComponent,
};
| 类别 | Action ID 格式 | 示例 |
|---|---|---|
| 导航 | navigation.* | navigation.goTo |
| 用户 | user.* | user.updateProfile |
| 组织 | org.* | org.createTeam |
使用 MSW 模拟 Agent 响应：
// app/src/mocks/handlers/agentHandlers.ts
http.post('*/functions/v1/ai-assistant', async ({ request }) => {
// 返回 SSE 流式响应
});
当任务涉及 UI 组件开发时，自动加载此章节。
// ❌ 禁止：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">
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 访问
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 │ │
│ └─────────────────────────┘ │
└─────────────────────────────────────────────────┘
所有数据库变更 → app/supabase/setup.sql（禁止创建独立 SQL 文件）
当任务为 Bug 修复时，自动加载此章节。
发现问题 → 浏览器调试验证 → 定位根因 → 一次性修复 → 验证通过
使用浏览器 DevTools
添加临时调试日志
console.log('[Debug] 数据状态:', JSON.stringify(data, null, 2));
常见数据完整性问题
| 问题场景 | 症状 | 排查方法 |
|---|---|---|
| 外键引用失效 | 关联查询返回 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 → 🔴测试先行 → 🟢代码实现 → 🔵重构优化 → 质量验证 → 人工审查 → 上线
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 - 验证结果
})
})
遵循技术约束完成代码实现。详见 references/coding-constraints.md。
✅ 测试全部通过后再重构
✅ 每次小步重构后运行测试
✅ 提取公共方法、消除重复
❌ 不要在重构时添加新功能
# 一键质量验证
./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） |
| 禁止事项 | 后果 |
|---|---|
| 先写代码再补测试 | 代码设计不佳，难以测试 |
| 提交无测试覆盖的新功能 | 回归风险，无法保证质量 |
| 不运行测试就提交代码 | 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 工作流：
| 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