Top 5 错误模式（编码前必查）

CLAUDE.md

Version: 4.1 | Updated: 2026-01-23 | 核心原则：计划 → 确认 → 执行到底 → 验收

🎯 核心原则

工作模式

1️⃣ 收到任务 → TodoList 规划 → 2️⃣ 展示计划 → 用户确认 → 3️⃣ 执行到底（不问问题）→ 4️⃣ 总结验收

4 种致命阻塞（唯一允许提问）

1. ❗ 缺少关键凭证 - 数据库密码、API key
2. ❗ 多个对立方案 - 无法从代码库判断
3. ❗ 需求本质矛盾 - 用户要求冲突
4. ❗ 不可逆高风险 - 删除生产数据、强制推送

禁止提问（自行决策）

文件命名/代码风格/依赖版本/测试策略/UI细节 → 遵循现有规范或最佳实践

⚠️ Top 5 错误模式（编码前必查）

E001: 异步未并行 | 🔴 严重 | 高频

// ❌ 错误：顺序执行 (13次 × 2秒 = 26秒)
for (const term of searchTerms) {
  const results = await api.search(term);
  allResults.push(...results);
}

// ✅ 正确：并行执行 (max 2秒)
const searchPromises = searchTerms.map(term =>
  api.search(term)
    .then(results => ({ term, results, success: true }))
    .catch(error => ({ term, results: [], success: false, error: error.message }))
);
const searchResults = await Promise.all(searchPromises);

自检: 多个独立异步操作是否用 Promise.all()？

E002: 轮询无超时 | 🔴 严重 | 高频

// ❌ 错误：无限轮询
scanPollInterval = setInterval(async () => {
  const data = await fetchStatus(scanId);
  if (data.status === 'completed') clearInterval(scanPollInterval);
}, 2000);

// ✅ 正确：带超时
function pollStatus(scanId, maxAttempts = 30) {
  let attempts = 0;
  scanPollInterval = setInterval(async () => {
    attempts++;
    if (attempts > maxAttempts) {
      clearInterval(scanPollInterval);
      showError('轮询超时');
      return;
    }
    try {
      const data = await fetchStatus(scanId);
      if (data.status === 'completed' || data.status === 'failed') {
        clearInterval(scanPollInterval);
        updateUI(data);
      }
    } catch (error) {
      clearInterval(scanPollInterval);
      showError(error.message);
    }
  }, 2000);
}

自检: 轮询是否设置 maxAttempts？失败/超时是否 clearInterval？

E003: 错误未重新抛出 | 🔴 严重 | 中频

// ❌ 错误：错误被吞掉
async function fetchUser(id) {
  try {
    return await fetch(`/api/users/${id}`).then(r => r.json());
  } catch (error) {
    console.error('获取失败:', error);
    // 没有 throw，调用者无法感知
  }
}

// ✅ 正确：重新抛出
async function fetchUser(id) {
  try {
    return await fetch(`/api/users/${id}`).then(r => r.json());
  } catch (error) {
    console.error('获取失败:', error);
    throw new Error(`无法获取用户 ${id}: ${error.message}`);
  }
}

自检: catch 块是否 throw error？

E004: SQL 未用 CTE 预过滤 | 🟡 中等 | 中频

-- ❌ 错误：JOIN 后再过滤，全表扫描
SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.created_at > '2026-01-01';

-- ✅ 正确：CTE 预过滤
WITH recent_orders AS (
  SELECT user_id, total
  FROM orders
  WHERE created_at > '2026-01-01'
)
SELECT u.name, ro.total
FROM users u
JOIN recent_orders ro ON u.id = ro.user_id;

自检: 是否用 CTE 预过滤大表？避免 JOIN 后过滤？

E007: 忘记资源清理 | 🔴 严重 | 低频

// ❌ 错误：只在成功时清理
scanPollInterval = setInterval(async () => {
  const data = await fetchStatus(scanId);
  if (data.status === 'completed') {
    clearInterval(scanPollInterval); // 只有这里清理
    updateUI(data);
  }
  // 失败时泄漏！
}, 2000);

// ✅ 正确：所有退出路径都清理
scanPollInterval = setInterval(async () => {
  try {
    const data = await fetchStatus(scanId);
    if (data.status === 'completed' || data.status === 'failed') {
      clearInterval(scanPollInterval);
      updateUI(data);
    }
  } catch (error) {
    clearInterval(scanPollInterval); // 错误时也清理
    showError(error.message);
  }
}, 2000);

自检: 所有退出路径（成功/失败/超时）都清理资源？

E008: 数据查询前未验证ID类型 | 🔴 严重 | 高频

-- ❌ 错误：看到数字直接当作ID，没有验证来源
-- 用户给了 1769012250，我误认为是 Unix 时间戳
SELECT * FROM user WHERE id = 1769012250;  -- 查不到数据！

-- 正确流程：先确认数字的含义
-- 1. 询问用户："这些是什么ID？bot_id、user_id、还是order_id？"
-- 2. 或者根据上下文推断（用户说"art_task"→ 应该是 bot_id）
-- 3. 查询正确的表：
SELECT * FROM art_task WHERE bot_id = 1769012250 AND created_date >= DATE_SUB(NOW(), INTERVAL 7 DAY);

关键上下文记忆：

• bot_id 范围: 1747227835 - 1769012250（10位数字）
• user.id 范围: 1 - 48607088（最多8位数字）
• 表结构:
  • art_task 表有 bot_id 字段（Art 任务）
  • user_energy_bot_usage_logs 表有 bot_id 字段（主站电量）
  • user 表只有 id 字段（用户ID）

自检清单（收到数字ID时必做）:

1. ✅ 这是什么ID？（bot_id / user_id / order_id / task_id）
2. ✅ 用户提到了哪个表？（art_task / user / order / bot）
3. ✅ 数字的位数和范围合理吗？（10位通常是 bot_id，8位通常是 user_id）
4. ✅ 如果不确定，立即询问用户，不要猜测

案例回顾（2026-01-23）:

• 用户给了 7 个 10 位数字：1769012250, 1769002640, 1750651225...
• 我错误地用 FROM_UNIXTIME() 转换为日期
• 用户明确说："这些都是 bot id, bytebase art_task 查看下"
• 正确做法: 第一时间应该问"这些是什么ID"，或者看到10位数字直接联想到 bot_id

E011: Git Bash npm install 失败 | 🟡 中等 | 高频

# ❌ 错误：在 Git Bash 中运行 npm install
$ npm install
# 命令卡住，没有输出

# ✅ 正确：在 PowerShell/CMD 中运行
# 打开 PowerShell 或 CMD
cd "E:\Bobo's Coding cache\bo-work\project"
npm install

自检: 是否在 PowerShell/CMD 而非 Git Bash 中运行 npm 命令？

原因: Git Bash 的输出重定向问题，Windows 原生命令可能无法正确显示进度

E012: Pre-commit Hook 权限问题 | 🟡 中等 | 中频

# ❌ 错误：Hook 文件没有可执行权限
$ git commit -m "test"
# 直接提交，没有运行检查

# ✅ 正确：添加可执行权限
chmod +x .husky/pre-commit

# 验证
ls -la .husky/pre-commit
# 应该看到: -rwxr-xr-x (包含 x)

自检: 创建 pre-commit hook 后是否设置了可执行权限？

E013: 知识库每次请求加载 | 🔴 严重 | 中频

// ❌ 错误：每次请求都加载文件
async chat(message: string) {
  const docs = await loadAllDocs(); // 慢！~150ms
  return process(message, docs);
}

// ✅ 正确：启动时加载到内存
class KnowledgeBaseService {
  private loadedDocs: Map<string, string> = new Map();

  async init() {
    const docs = await this.loadAllDocs();
    this.loadedDocs = new Map(docs);
    console.log(`[KnowledgeBase] 加载完成: ${this.loadedDocs.size} 文件`);
  }

  getSystemPrompt(): string {
    return Array.from(this.loadedDocs.values()).join('\n\n'); // 快！~1ms
  }
}

// 在服务启动时初始化
const kb = new KnowledgeBaseService();
await kb.init();

自检: 大文件或频繁访问的资源是否在启动时预加载？

权衡: 启动慢一点（+100ms），响应快很多（-149ms），内存占用可接受（~120KB）

E014: 跨平台路径处理未统一 | 🟡 中等 | 中频

// ❌ 错误：直接使用原始路径
const psCommand = `cd "${userProvidedPath}" && claude`;
// Windows: E:\Bobo's Coding cache ✅
// WSL: /mnt/e/Bobo's Coding cache ❌ （PowerShell 不认识）

// ✅ 正确：统一路径转换层
function normalizePath(path: string, targetEnv: 'windows' | 'wsl'): string {
  if (targetEnv === 'windows' && path.startsWith('/mnt/')) {
    // WSL → Windows
    return path.replace(/^\/mnt\/([a-z])\//, (_, drive) => `${drive.toUpperCase()}:\\`);
  }
  if (targetEnv === 'wsl' && /^[A-Z]:\\/.test(path)) {
    // Windows → WSL
    return path.replace(/^([A-Z]):\\/, (_, drive) => `/mnt/${drive.toLowerCase()}/`);
  }
  return path;
}

// 使用
const windowsCwd = normalizePath(userProvidedPath, 'windows');
const psCommand = `cd "${windowsCwd}" && claude`;

自检:

• 是否有路径转换的统一入口？
• 是否考虑了所有路径格式（Windows/WSL/Unix/相对路径）？
• 是否处理了特殊字符（空格/单引号）？

案例回顾（2026-01-27）:

• Vibecraft 项目在 WSL 中无法启动 Windows Terminal
• 原因：WSL 路径 /mnt/e/ 直接传给 PowerShell，无法识别
• 修复：添加 convertWindowsPathToWSL() 和 normalizePath() 函数

E015: Hook 系统未验证完整链路 | 🔴 严重 | 低频

// ❌ 错误：只设置环境变量，未检查 Hook 安装
process.env.VIBECRAFT_EVENTS_FILE = eventsFile;
// Claude CLI 启动...
// 结果：Claude Code 不调用 hook（因为 settings.json 未配置）

// ✅ 正确：启动前验证完整链路
async function validateEventCapture(): Promise<boolean> {
  // 1. 检查 Hook 脚本安装
  const hookPath = path.join(os.homedir(), '.vibecraft', 'hooks', 'vibecraft-hook.js');
  if (!fs.existsSync(hookPath)) {
    console.error("❌ Hook 脚本未安装，运行: npx vibecraft setup");
    return false;
  }

  // 2. 检查 Claude settings.json 配置
  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
  const hasHooks = settings.hooks && Object.keys(settings.hooks).length > 0;
  if (!hasHooks) {
    console.error("❌ Claude settings.json 未配置 hooks");
    return false;
  }

  // 3. 检查环境变量
  if (!process.env.VIBECRAFT_EVENTS_FILE) {
    console.error("❌ 环境变量 VIBECRAFT_EVENTS_FILE 未设置");
    return false;
  }

  console.log("✅ 事件捕获链路验证通过");
  return true;
}

自检:

• 是否验证了每一层（注册 → 调用 → 执行 → 输出）？
• 是否在启动时就暴露问题，而不是运行时？
• 是否提供了清晰的修复指导？

案例回顾（2026-01-27）:

• Vibecraft 前端一直显示 "Waiting for activity"，无事件流
• 第一次诊断：只修复了环境变量（Layer 2），Hook 未安装（Layer 1）
• 第二次诊断：发现需要两层都修复
  • Layer 1: npx vibecraft setup 安装 Hook 到 Claude Code
  • Layer 2: 启动 Claude CLI 时设置 VIBECRAFT_EVENTS_FILE 环境变量

🧠 核心方法论

三文件模式（长任务必用）

task_plan.md     - 任务规划和进度追踪（重要决策点重新读取！）
notes.md         - 研究笔记和发现记录
[deliverable].md - 最终产出物

关键机制: 每个重要决策点前 重新读取 task_plan.md，刷新注意力窗口，防止目标漂移。

失败追踪（避免重复错误）

## Errors Encountered
### [时间] 错误类型
**Error**: 具体错误信息
**Root Cause**: 根本原因
**Solution**: 解决方案
**Learning**: 经验教训

阶段门控（关键决策点等待确认）

Phase 1: 需求理解 → [用户确认 "ready"] → Phase 2: 设计方案 → [确认] → Phase 3: 实现代码

原则: 永远不进入下一阶段，直到用户明确确认。

🔧 能力速查

MCP Servers（外部数据访问）

CLI 工具（高性能补充）

Skills（自动化任务）

Plugins（自动激活，无需显式调用）

直接描述需求，相关 plugins 自动参与：

• 架构设计 → backend-development, cloud-infra
• 代码审查 → code-review-ai, security-scanning
• 数据分析 → data-engineering, database-design

快速决策树

需要外部数据？     → MCP (bytebase/honeycomb/stripe/context7)
需要自动化？       → Skills (/commit, /write-tests, browser-use)
需要建议？         → Plugins（自动激活，直接描述需求）
需要营销研究？     → Vibe Marketing (Firecrawl/Perplexity/n8n)
需要营销优化？     → Marketing Skills (转化/文案/SEO/定价)
需要动画/视觉设计？ → Processing（粒子/流场/渐变/数据图表）
需要 UI 组件？     → ui-ux-pro-max（自动激活）
需要 UI 代码审查？ → web-design-guidelines（无障碍/性能/体验）⭐ 新增
需要浏览器自动化？ → 智能决策（见下方）⭐ 新增

浏览器自动化决策树 ⭐ 新增

收到浏览器操作请求
  ├─ 对话中实时操作？ → Playwright MCP ⭐ 主力工具
  │   ✓ 无缝集成，结果自动返回
  │   ✓ 探索式任务、调试、演示
  │   ✓ 示例：browser_navigate, browser_snapshot
  │
  ├─ 需要网络拦截/录制？ → Playwright MCP ⭐ 唯一选择
  │   ✓ Route请求、Mock响应、Codegen
  │   ✓ 完整测试框架、Trace追踪
  │
  ├─ 批量操作（>50次）？ → agent-browser CLI 🚀 高性能
  │   ✓ Rust核心，启动<1秒
  │   ✓ 性能提升1.85-2.9x
  │   ✓ 示例：agent-browser open URL
  │
  ├─ 脚本化/定时任务？ → agent-browser CLI 🚀 轻量级
  │   ✓ CLI命令，适合cron/CI
  │   ✓ Unix风格管道组合
  │
  ├─ AI Agent系统？ → agent-browser CLI 🚀 AI专属
  │   ✓ Accessibility Tree + Refs (@e1, @e2)
  │   ✓ 语义定位器（find role/text/label）
  │
  └─ 不确定/首次使用？ → Playwright MCP ⭐ 默认选择
      ✓ 功能最全面，学习成本最低

详细决策树: ~/.claude/capabilities/browser-automation-decision-tree.md

设计场景主动触发：

• 落地页背景/Hero 动画 → Processing 粒子系统或流场
• 数据可视化动画 → Processing 图表（比静态图更吸引人）
• PPT/演示素材 → Processing 导出 PNG/GIF
• 交互式背景 → Processing + React/Vue 组件

🎨 Vibe Marketing 工具包

核心概念

Vibe Marketing = AI驱动的营销自动化系统，将2周研究压缩到1小时：

• Research → Strategy → Content → Revenue

推荐 MCP (营销专用)

营销工作流

Site Audit (Firecrawl) → Market Research (Perplexity) → Content Strategy (Claude) → Automation (n8n)

输出模板

n8n 自动化

详细文档

• Vibe Marketing 完整指南
• MCP 设置指南
• n8n 工作流指南

🎯 营销技能 Skills（24 个专业 Skills）

核心概念

Marketing Skills = 由 Corey Haines 创建的专业营销技能包，涵盖转化优化、文案撰写、SEO、付费广告、定价策略等全栈营销能力。

Skills 总览（按类别）

📈 转化率优化（CRO）- 6 个

✍️ 内容与文案 - 4 个

🔍 SEO 与发现 - 4 个

💰 付费广告与分发 - 1 个

📊 测量与测试 - 2 个

🚀 增长工程 - 2 个

💡 策略与货币化 - 5 个

快速选择指南

使用方式

方式 1：自然对话（推荐）

"帮我优化这个落地页的转化率"
→ 自动激活 page-cro skill

"写一个SaaS首页的文案"
→ 自动激活 copywriting skill

"设置GA4事件追踪"
→ 自动激活 analytics-tracking skill

方式 2：直接调用

/page-cro
/copywriting
/seo-audit

典型工作流

营销页面优化:
  1. seo-audit → 技术审计
  2. copywriting → 重写文案
  3. page-cro → 转化优化
  4. ab-test-setup → 测试方案

产品发布:
  1. launch-strategy → 发布计划
  2. copywriting → 发布文案
  3. email-sequence → 发布邮件
  4. social-content → 社交内容

增长实验:
  1. marketing-ideas → 寻找灵感
  2. free-tool-strategy → 工具策划
  3. ab-test-setup → 实验设计
  4. analytics-tracking → 追踪设置

详细文档

• Marketing Skills GitHub 仓库
• 完整 Skills 清单
• Corey Haines 官网

🎨 Processing 创意编程

触发关键词（主动识别）

当用户提到以下内容时，自动建议使用 Processing：

• 动态背景、动画背景、Hero 动画
• 粒子效果、流场、波浪动画
• 数据可视化动画、实时图表
• 生成艺术、创意编码、generative art
• 交互式视觉、鼠标跟随效果
• PPT 素材、演示动画、GIF 导出

6 种视觉模式

16 种配色主题

输出格式

使用示例

用户: "给落地页做一个科技感的动态背景"
Claude: 建议使用 Processing 粒子系统 + tech-matrix 配色
        → 生成 React 组件 + 预览截图

用户: "做一个数据增长的动画图表"
Claude: 建议使用 Processing Data Viz 模式
        → 生成动态柱状图/折线图

用户: "需要PPT里用的流动背景素材"
Claude: 建议使用 Processing Flow Field + 渐变模式
        → 导出 GIF 或 PNG 序列

详细文档

• Processing Skill 完整指南
• GitHub 仓库

📊 PPT 制作优化工作流

核心原则（持久化规则）

当收到 PPT 制作需求时，必须按以下优先级执行：

1️⃣ Nano Banana Pro → 生成页面图片设计
2️⃣ Python-pptx → 组装 PPT（插入图片）
3️⃣ Processing + p5.js → 创建 HTML 演示（显示图片 + 页面转换动画）
4️⃣ 三格式输出 → .pptx 文件 + 每页图片文件 + .html 交互演示

重要原则 ⭐:

• Processing 动画 = 页面转换效果（0.5-1秒），不是整页背景
• HTML 展示 PPT 图片内容，动画只在页面切换时出现
• PPT 中的静态图片无法展示动态效果，因此 HTML 文件是必需的交付物

工作流程

快速命令模板

生成页面设计（Nano Banana Pro）:

uv run ~/.claude/skills/nano-banana-pro/scripts/generate_image.py \
  --prompt "Professional PPT slide: [主题], [风格], 16:9, [配色]" \
  --filename "YYYY-MM-DD-HH-MM-SS-slide-[N]-[描述].png" \
  --resolution 4K

生成 HTML 演示（Processing + p5.js - 自动激活）:

"Create an HTML slideshow that displays PPT images (slide-01.png to slide-12.png)
with p5.js transition animations between pages. Use [动画类型] effect for
transitions. Keep animations subtle (under 1 second)."

动画类型选择：
- particle connections（粒子连线）- 科技感
- light wave sweep（光波扫过）- 数据主题
- block flip（方块翻转）- 几何风格
- gradient flow（渐变流动）- 柔和过渡

组装PPT:

from pptx import Presentation
from pptx.util import Inches

prs = Presentation()
prs.slide_width = Inches(10)
prs.slide_height = Inches(5.625)

for img_path in image_paths:
    slide = prs.slides.add_slide(prs.slide_layouts[6])
    slide.shapes.add_picture(img_path, 0, 0,
                             Inches(10), Inches(5.625))

prs.save("output.pptx")

必须输出（三格式交付）

✅ PPT文件: output.pptx - 静态演示版本（适合投影仪） ✅ HTML文件: output-interactive.html - 🌟 交互演示版本（PPT图片 + 页面转换动画） ✅ 图片文件夹: output_slides/ - 包含每一页的PNG图片

HTML 文件关键特征：

• 每页展示对应的 PPT 图片（slide-01.png, slide-02.png...）
• Processing 动画仅在页面切换时出现（0.5-1秒）
• 动画结束后完整显示新页面内容
• 支持键盘（← →）和按钮导航

错误示例 ❌：整页动态背景遮挡 PPT 内容 正确示例 ✅：显示 PPT 图片 → 切换时播放动画 → 显示新图片

配色主题库

完整设计风格库（30种）

📚 UI/UX 设计风格完整参考手册 - 包含：

• 6 种主流风格（极简/玻璃态/新拟物化/粗野主义/扁平/拟物化）
• 5 种现代趋势（粘土态/极光UI/液态玻璃/新粗野/便当盒网格）
• 5 种复古风格（复古未来/千禧年/蒸汽波/孟菲斯/像素艺术）
• 4 种科技美学（赛博朋克/HUD科幻/深色模式/AI原生）
• 3 种自然风格（有机亲生物/仿生/电子墨水）
• 4 种动效驱动（动效驱动/微交互/动态排版/视差）
• 3 种特殊风格（空间UI/Z世代混乱/维度分层）

每种风格包含：Nano Banana Pro 提示词模板、配色建议、适用场景

详细文档

• PPT 制作完整工作流
• UI/UX 设计风格参考库 ⭐
• 设计大师人格指南 🎯 新增
• Nano Banana Pro Skill
• Processing Skill
• Python-pptx 文档

设计标准: 所有 UI/UX 设计任务必须遵循设计大师人格的标准：

• 适用范围: PPT设计、网页设计、前端页面、移动应用界面、产品设计、品牌视觉
• 深度挖掘用户真实需求（不只是表面需求）
• 提供多层次方案（安全/激进/理想）
• 遵循8px网格、60fps动画、WCAG可访问性标准
• 输出完整可运行代码（不接受半成品）
• 30种设计风格可供选择（参考UI_DESIGN_STYLES_REFERENCE.md）

🎬 Remotion 视频创作（自动化生产）

核心理念

用代码创作电影级别的程序化视频 - 用户只需简单描述需求，系统自动匹配设计风格、生成完整代码。

触发关键词（自动识别）

当用户提到以下内容时，自动启动 Remotion 视频创作流程：

• "视频"、"动画"、"演示视频"、"产品介绍视频"
• "Instagram"、"YouTube"、"TikTok"、"社交媒体视频"
• "数据可视化动画"、"图表动画"
• "品牌视频"、"宣传片"、"教程视频"

自动化工作流程

用户简单描述 → 自动分析场景类型 → 自动匹配设计风格 → 自动选择技术栈 → 直接生成代码

用户不需要做：

• ❌ 填写复杂模板
• ❌ 选择设计风格（除非特别指定）
• ❌ 决定技术栈
• ❌ 计算时长分配
• ❌ 写配色方案
• ❌ 选择动画类型

用户只需要做：

• ✅ 描述视频的目的（产品演示/教育/社交媒体/数据报告）
• ✅ 描述视频的内容（展示什么/讲什么故事）
• ✅ 可选：时长（默认30秒）、平台（默认 YouTube）

自动匹配规则

快速示例

用户说：

做一个30秒的产品介绍视频，我们的产品是 AI 写作工具

系统自动处理：

// 自动分析
场景类型：产品演示
设计风格：Glassmorphism + Tech Innovation
配色方案：科技蓝 (#0066ff) + 霓虹青 (#00ffff)
时长：30秒 | 分辨率：1920x1080 | 帧率：60fps

// 自动生成场景
Scene 1 (0-5s): Logo 弹性入场 + 粒子特效
Scene 2 (5-15s): 3个核心功能卡片滑入（毛玻璃）
Scene 3 (15-25s): 数据图表从0递增到目标值
Scene 4 (25-30s): CTA 按钮脉冲 + 联系方式

// 自动生成素材指令
Nano Banana Pro: 生成3张功能截图（4K，Glassmorphism风格）
Processing: 科技感粒子背景（particle connections）

// 输出完整的 Remotion 项目代码

三大核心能力组合

Remotion 核心技术（29个最佳实践）

完整文档

• 主指南: E:\Bobo's Coding cache\bo-skill-research\REMOTION_VIDEO_CREATION_GUIDE.md ⭐
• 自动化规则: C:\Users\Administrator\.claude\rules\remotion-auto-production.md 🎯
• Skills 目录: ~/.claude/skills/remotion-dev/skills/remotion/ (29个规则)
• 设计风格库: ~/.claude/design/UI_DESIGN_STYLES_REFERENCE.md (30种风格)

输出格式

每次处理视频需求后，自动输出：

1. 分析总结（场景类型、设计风格、配色、技术规格）
2. 完整 Remotion 项目代码（Root.tsx + 所有 Scene 组件 + 配置）
3. 素材生成指令（Nano Banana Pro + Processing）
4. 渲染命令（预览 + 高质量渲染）

📊 数据分析 Skills（6 个核心 Skills）

Skills 总览

快速选择指南

分析流程建议

月初: 收入与订阅分析 → 了解整体表现
  ├─ 收入下降 → Bot毛利率分析 + 整体毛利率分析
  ├─ 成本过高 → 成本趋势分析 + 主站电量分析
  └─ 特定bot异常 → Bot收入成本趋势
定期维护: 每月运行失活邮箱域名分析 → 优化白名单

♿ 无障碍性自动化系统

核心能力

多层次自动化检查（WCAG 2.0-2.2 AA 标准）：

• 开发时：ESLint 实时检查（13 个 jsx-a11y 规则）
• 提交前：Pre-commit Hook 自动验证
• 推送后：GitHub Actions CI/CD 检查
• 定期：每周 Component Audit 自动审计

配置文件（10 个）

Playwright 测试用例（11 个）

1. 键盘导航测试
2. 屏幕阅读器支持测试
3. 焦点管理测试
4. ARIA 属性测试
5. 色彩对比度测试
6. 表单标签和验证测试
7. 链接和按钮可访问性测试
8. 图片 alt 文本测试
9. 标题层级结构测试
10. 交互元素可点击区域测试
11. 语义化 HTML 测试

常用命令

# ESLint 检查（立即可用）
npm run lint

# Playwright 测试（需要先安装依赖）
npm run test:accessibility

# Pre-commit Hook 测试
echo "// test" > test.tsx
git add test.tsx
git commit -m "test"
git reset HEAD~1 && rm test.tsx

关键依赖

{
  "@axe-core/playwright": "^4.10.0",
  "@playwright/test": "^1.48.0",
  "eslint-plugin-jsx-a11y": "^6.10.2"
}

环境要求 ⚠️

重要: npm 命令需要在 PowerShell 或 CMD 中运行，Git Bash 存在输出重定向问题。

# ❌ 不要在 Git Bash 中运行
npm install  # 会卡住

# ✅ 在 PowerShell/CMD 中运行
cd "项目路径"
npm install
npx playwright install chromium

文档体系

最佳实践

1. 分层自动化：不同阶段不同检查，减少人工审查负担
2. 立即可用功能：ESLint 和 Pre-commit Hook 无需安装额外依赖
3. 渐进式披露文档：从快速开始到深度技术，满足不同需求
4. 环境兼容性声明：明确说明 Git Bash 限制，提供替代方案

项目路径

• 示例项目：E:\Bobo's Coding cache\bo-work\big_dashboard
• 文档目录：项目根目录
• 测试目录：tests/accessibility.spec.ts

🤖 AI Agent 知识库系统

核心能力

知识库集成（12 个核心文档，116 KB）：

• 在服务启动时加载到内存（~100ms）
• 每次请求从内存读取（~1ms）
• 支持分类加载和热重载

知识库文档（12 个）

核心规则（3 个）:

• core/CLAUDE.md - 核心工作流程和原则
• core/DECISION_TREE.md - 能力决策树
• core/QUICK_START.md - 快速开始指南

能力指南（6 个）:

• capabilities/mcp-servers.md - MCP 服务器指南
• capabilities/skills-guide.md - Skills 使用指南
• capabilities/plugins-auto.md - 自动激活插件
• capabilities/MARKETING_SKILLS_GUIDE.md - 营销技能
• capabilities/PPT_WORKFLOW.md - PPT 制作流程
• capabilities/PROCESSING_SKILL.md - Processing 创意编程

设计规范（2 个）:

• design/DESIGN_MASTER_PERSONA.md - 设计大师人格
• design/UI_DESIGN_STYLES_REFERENCE.md - 30 种设计风格

错误处理（1 个）:

• errors/ERROR_CATALOG.md - 错误知识库

实现模式

// ✅ 正确：启动时加载到内存
export class KnowledgeBaseService {
  private loadedDocs: Map<string, string> = new Map();
  private isInitialized = false;

  async init() {
    console.log('[KnowledgeBase] 加载中...');
    const docs = await this.loadAllDocs();
    this.loadedDocs = new Map(docs.map(doc => [doc.path, doc.content]));
    console.log(`[KnowledgeBase] 加载完成: ${this.loadedDocs.size} 文件, ${totalSize / 1024} KB`);
    this.isInitialized = true;
  }

  getSystemPrompt(category?: string): string {
    // 从内存读取，而不是文件系统
    return Array.from(this.loadedDocs.values()).join('\n\n');
  }
}

// server.ts
const knowledgeBase = new KnowledgeBaseService();
await knowledgeBase.init();

性能对比

推荐: 启动时加载

• 启动慢一点（+100ms），响应快很多（-149ms）
• 内存占用可接受（~120KB）
• 确保知识库一致性

项目路径

• 示例项目：E:\Bobo's Coding cache\bo-work\craft-agents-oss
• 后端服务：apps/server/src/services/KnowledgeBaseService.ts
• 知识库路径：~/.claude/ (12 个文档)

📊 当前项目

名称: 数据分析和自动化（DAA） 技术栈: TypeScript + PostgreSQL (Vercel) + MySQL (my_shell_prod) + MCP 目录: E:\Bobo's Coding cache Skills目录: bo-skill-research/shane-skill/data-analysis-agent/skills/

常用命令

cd functions && npm test    # 测试
vercel dev                  # 本地开发
vercel --prod               # 部署

核心数据表

• daaf_bot_revenue_snapshots - Bot收入归因
• daaf_daily_summary_snapshots - 每日汇总
• daaf_cost_daily_snapshots - 每日成本
• user_energy_bot_usage_logs - 电量消耗（主站+Art）
• art_task - Art任务表

用户分类（6 种）

1. 付费用户 - user_membership_type != 'FREE'
2. 免费-临时邮箱 - 56个临时邮箱域名
3. 免费-白名单邮箱 - 153个白名单域名
4. 免费-其他邮箱 - 未分类邮箱
5. 免费-已删除 - 已删除用户
6. 免费-访客 - user.source = 'visitor'

归因模型（Last-Touch 优化版）

订单窗口: start_date 到 end_date
任务窗口: start_date - 7天 到 end_date + 7天
- 订单前归因: 最后使用的 bot
- 订单后归因: 首次使用的 bot（如果订单前无使用）
预期覆盖率: 70-80% 订单

典型工作流

数据分析: bytebase 查询 → chart 生成图表 → content-writer 写报告
调试: honeycomb traces → bytebase 慢查询 → 根因分析
支付: context7 文档 → stripe MCP → /write-tests
Bot分析: @bot-margin-analysis.md 查询最近30天
成本监控: @cost-trend-by-user-type.md 显示最近7天

base44 部署链接

🔧 开发环境

• OS: Windows 10.0.26200 | Shell: Git Bash
• 路径格式: Windows (Git Bash 中用正斜杠)
• 换行: CRLF (配置 Git autocrlf)

Playwright 配置

• 截图: ./CCimages/screenshots/
• PDF: ./CCimages/pdfs/
• 版本问题修复: cd ~/AppData/Local/ms-playwright && cmd //c "mklink /J chromium-1179 chromium-1181"

📚 深度参考（按需读取）

外部资源链接

准备接收任务 🚀

Development Environment

• OS: Windows 10.0.26200
• Shell: Git Bash
• Path format: Windows (use forward slashes in Git Bash)
• File system: Case-insensitive
• Line endings: CRLF (configure Git autocrlf)

Playwright MCP Guide

File paths:

• Screenshots: ./CCimages/screenshots/
• PDFs: ./CCimages/pdfs/

Browser version fix:

• Error: "Executable doesn't exist at chromium-1179" → Version mismatch
• Quick fix: cd ~/AppData/Local/ms-playwright && cmd //c "mklink /J chromium-1179 chromium-1181"
• Or install: npx playwright@1.40.0 install chromium