صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
188-template-179
/
mini-starter
برگرفته از 155-template-138/mini-starter
2
0
انشعاب 0
پرونده‌ها
درخت: 9f1e019a69
شاخه‌ها تگ‌ها
mini-starter
/
CLAUDE.md

CLAUDE.md 8.6 KB
تاريخچه خام

开发环境说明

  • 多八多云端开发容器环境
  • Node.js 20.19.2
  • PostgresSQL 17 (默认数据库: postgres)
  • Redis 7
  • MinIO(默认存储桶: d8dai)
  • 所有服务使用默认参数连接，正式环境参数相同
  • 默认开放8080端口供外网访问
  • 开发服务器在8080端口默认开机自动启动，无需手动启动
  • 日志记录: pnpm run dev 会自动记录日志到 logs/dev-logs/
    • logs/dev-logs/dev-current.log 是当前日志文件（追加模式）
    • AI 代理排查问题时可以先查看日志：cat logs/dev-logs/dev-current.log
    • 参考 logs/README.md 了解更多日志管理说明

  • 小程序测试账号:

  • Claude Code

  • use pnpm

  • 数据库在同一容器组的另一个容器中，需要运行 psql -h 127.0.0.1 -U postgres 来访问

  • vitest中，只有console.debug会显示，其他的都屏蔽了

  • vitest中，用import 来配合 vi.mocked，而不是require

  • E2E测试:

    • 工作流程: 编写 E2E 测试前，先使用子代理运行 Playwright MCP 手动走一遍测试流程
    • 使用 Playwright MCP 工具（如 browser_navigate、browser_click、browser_snapshot 等）探索页面结构
    • 验证测试流程的可行性，熟悉页面交互
    • 将验证过的流程转化为自动化测试代码
    • 这样可以减少测试编写时的反复调试，提高效率
    • 测试策略要点:
    • 即时验证: 在 Story 开发过程中立即使用 Playwright MCP 进行测试验证
    • 模块化验证: 每完成一个功能模块立即验证，不等到专门的 E2E 测试 Story
    • 减少返工: 早期发现问题可以减少后期返工成本
    • 示例流程: Page Object 开发 → Playwright MCP 探索验证 → 代码修复 → 提交
    • SSR 超时排查: 当使用 Playwright MCP 发现页面 SSR 超时时，需检查页面控制台日志（这是页面运行时错误，非后端 API 问题）
    • 使用 browser_console_messages 工具获取控制台日志
    • 检查 error 级别的日志
    • 常见问题：模块导入失败（如 Failed to resolve import）、组件渲染错误、TypeScript/JavaScript 运行时错误
    • 示例场景：SSR 渲染超时（渲染超时，终止请求）、页面 #root 元素为空、模块脚本加载失败
    • 图片 MCP 配合使用: Playwright MCP 与图片 MCP（如 zai-mcp-server）配合使用可以更高效地进行测试验证
    • 工作流程:
      1. 使用 Playwright MCP 导航到页面并截图：browser_take_screenshot
      2. 使用图片 MCP 查看截图内容，分析页面状态
      3. 根据分析结果进行调试或修复问题
      4. 在代码审查时使用图片 MCP 验证测试截图的正确性
    • 优点:
      • 可以直观看到页面实际渲染效果
      • AI 可以识别页面元素和布局问题
      • 验证测试数据是否正确显示（如脱敏、格式等）
      • 快速定位 UI 问题而不需要手动查看截图
    • 示例提示词: "使用 Playwright MCP 截图后，用图片 MCP 分析截图中的页面元素和测试结果"
    • 推荐使用子代理运行: 运行 Playwright E2E 测试时，使用 Task 工具的 Bash 子代理方式运行，速度更快且多个 Playwright 进程不会冲突
    • 示例提示词: "在 web 目录下运行 pnpm exec playwright test --config=tests/e2e/playwright.config.ts --project=chromium --grep \"测试名称\""
    • 运行所有E2E测试: pnpm test:e2e:chromium
    • 运行单个测试文件: pnpm test:e2e:chromium <测试文件名> (如: pnpm test:e2e:chromium disability-person-complete)
    • 快速失败模式 (推荐调试时使用): 使用 Linux timeout 命令限制总运行时间
    • timeout 30 pnpm test:e2e:chromium (所有测试，30秒后中断)
    • timeout 60 pnpm test:e2e:chromium disability-person-complete (单文件测试，60秒后中断)
    • E2E测试失败时先查看页面结构 test-results/**/error-context.md
    • E2E测试在 web 目录下运行: cd web && pnpm test:e2e:chromium
    • 配置文件超时: playwright.config.ts 中已设置 timeout: 60000 (60秒，单个测试的默认超时)

  • 前端是 hono/client hc rpc 的，不是直接fetch

🚨 BMM 工作流指令 - 必读！

⚠️ 调用链（重要！）

主对话 → Task 工具启动子代理 → 子代理内部调用 Skill 工具执行工作流

正确的使用方式

// 主对话中的操作
Task({
  subagent_type: "general-purpose",
  prompt: "调用 Skill 工具执行 bmad:bmm:workflows:dev-story，参数为 10.11"
})

为什么这样设计？

  1. Token 管理: 工作流包含大量上下文加载，在子代理中执行不消耗主对话 token
  2. 隔离执行: 子代理在独立上下文中执行，不干扰主对话的连续性
  3. 状态管理: 完整的工作流状态管理和错误恢复
  4. 并行执行: 多个工作流可以在不同子代理中并行执行

常用 BMM 工作流

工作流 Skill 名称 说明
开发 Story bmad:bmm:workflows:dev-story 实现 Story 的任务和子任务
创建 Story bmad:bmm:workflows:create-story 从 Epic 创建下一个 Story
代码审查 bmad:bmm:workflows:code-review AI 代码审查
Sprint 状态 bmad:bmm:workflows:sprint-status 查询当前 Sprint 状态
Sprint 规划 bmad:bmm:workflows:sprint-planning Sprint 规划

示例：开发 Story 10.11

用户: "开发 Story 10.11"

主对话响应:
Task({
  subagent_type: "general-purpose",
  prompt: "调用 Skill 工具执行 bmad:bmm:workflows:dev-story，参数为 10.11"
})

→ 子代理启动，内部执行 Skill 工具调用 BMM 工作流
→ 工作流在子代理中完成，不消耗主对话 token

工作流状态文件位置

  • Sprint 状态: _bmad-output/implementation-artifacts/sprint-status.yaml
  • Story 文件: _bmad-output/implementation-artifacts/*.md
  • Epic 文件: _bmad-output/planning-artifacts/epics.md

⚠️ API 并发错误处理

当子代理在运行时遇到 API 并发报错（如 "您当前使用该API的并发数过高"）时：

  • 不要停止工作，只需要等待 1-2 秒后继续重试即可
  • 这是因为同时启动了多个子代理导致的暂时性限制
  • 系统会自动恢复，重试通常能够成功

其他开发说明

  • project-context.md 路径: _bmad-output/project-context.md
  • 必须用中文回答
  • git提交: 当遇到git锁文件冲突时，使用单条命令：rm -f /mnt/code/184-172-template-6/.git/index.lock && git add <文件> && git commit -m "提交信息"
  • 测试调试: 使用 pnpm test --testNamePattern "测试名称" 来运行特定测试查看详细信息 (mini使用Jest，其他包使用Vitest)
    • Vitest: 支持 -t 或 --testNamePattern
    • Jest: 只支持 --testNamePattern，mini是Jest
    • Mini测试: 需要先进入mini目录再运行 pnpm test --testNamePattern "测试名称"
  • 表单调试: 表单提交失败时，在表单form onsubmit=form.handleSubmit的第二个参数中加console.debug来看表单验证错误，例如：form.handleSubmit(handleSubmit, (errors) => console.debug('表单验证错误:', errors))
  • 类型检查 可以用 pnpm typecheck 加 grep来过滤要检查的 指定文件
  • 长文档分段生成: 如果文档（如 story 文档）太长一次生成不完，应该分段生成：
    1. 先使用 Write 工具创建文件的基础部分（header、requirements）
    2. 使用 Edit 工具逐步添加其他部分（dev notes、references、dev agent record 等）
    3. 每次添加一个主要部分，确保不会超过单次生成的长度限制

工具调用最佳实践

Playwright E2E 测试

  • 推荐方式：使用 Task 工具调用 Bash 子代理运行 E2E 测试
  • 优点：
    • 速度快，在独立上下文中执行
    • 多个 Playwright 测试之间不会冲突
    • 方便并行运行多个测试

  • 示例：

    // 使用 Task 工具 + Bash 子代理
Task({
subagent_type: "Bash",
prompt: "在 web 目录下运行 pnpm exec playwright test --config=tests/e2e/playwright.config.ts --project=chromium --grep \"测试名称\""
})

其他工具

  • 对于其他长时间运行的任务（如构建、测试套件），建议使用 Task 工具的 Bash 子代理
  • 对于复杂的多步骤任务，可以使用 Task 工具的 general-purpose 子代理