From 92bf47ffcc0f2d8139b2b3a1de7b4d6359d2e653 Mon Sep 17 00:00:00 2001 From: yourname Date: Wed, 8 Apr 2026 07:19:51 +0000 Subject: [PATCH] =?UTF-8?q?sync:=20=E8=BF=AD=E4=BB=A3=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=A8=A1=E5=BC=8F=20+=20implementation-artif?= =?UTF-8?q?acts=20=E6=94=AF=E6=8C=81=20+=20=E5=BC=BA=E5=88=B6=E9=AA=8C?= =?UTF-8?q?=E8=AF=81=E9=97=A8=E7=A6=81=20+=20phase-03=20=E5=B9=B3=E5=8F=B0?= =?UTF-8?q?=E6=A3=80=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 变更内容 - d8d-prototype/workflow.md: [U] 增量更新细分为 [D]/[P]/[A] 子选项 + evidence 格式 + 验证门禁 - d8d-prototype/step-05: 扫描范围增加 implementation-artifacts/ + 文档分组策略 - d8d-prototype/step-05b: 新增迭代文档更新步骤（d8d-dev 产物自动发现） - d8d-prototype/step-06: server.js 模板添加 .yaml/.yml MIME 类型 - d8d-prototype/step-07: 合并强制验证门禁（禁止 curl 替代截图） - d8d-dev/phase-03: 多应用/单应用检查 + Next.js/uni-app 平台专项检测 ## 测试 - [ ] 在新项目中运行 SETUP 阶段验证 - [ ] 执行 /d8d-prototype 后选择 [U] → [D] 验证文档中心更新 --- .claude/skills/d8d-dev/phase-03-implement.md | 8 +- .../steps/step-05-generate-docs.md | 18 ++- .../steps/step-05b-update-docs.md | 142 ++++++++++++++++++ .../steps/step-06-generate-server.md | 2 + .../d8d-prototype/steps/step-07-validate.md | 8 +- .claude/skills/d8d-prototype/workflow.md | 53 ++++--- 6 files changed, 197 insertions(+), 34 deletions(-) create mode 100644 .claude/skills/d8d-prototype/steps/step-05b-update-docs.md diff --git a/.claude/skills/d8d-dev/phase-03-implement.md b/.claude/skills/d8d-dev/phase-03-implement.md index ee22cc1..30a0a85 100644 --- a/.claude/skills/d8d-dev/phase-03-implement.md +++ b/.claude/skills/d8d-dev/phase-03-implement.md @@ -7,10 +7,12 @@ 1. **前置检查** - 数据库连接：`psql -U postgres -h localhost -c "SELECT 1"` （容器内置 PG 17） - Redis 连接：`redis-cli ping` （容器内置 Redis 7） - - 数据库迁移状态：`cd api && npx prisma migrate status` - - Dev server 状态：`pm2 list` 检查 api/admin/mini-h5 是否 `online` - - 未运行则启动：`pm2 start ecosystem.config.js` 并等待 ready（`curl -sf http://localhost:3001/api/health`） + - 数据库迁移状态：`cd api && npx prisma migrate status`（多应用）或 `npx prisma migrate status`（单 Next.js 应用） + - Dev server 状态：`pm2 list` 检查服务是否 `online` + - 未运行则启动并等待 ready - 失败时自动修复：创建数据库、运行迁移、重启 pm2 服务 + - **Next.js 平台检查**：按 `./reference/platform-nextjs.md` 逐项检测（NextAuth trustHost、Prisma 7 adapter 等） + - **uni-app 平台检查**：按 `./reference/platform-uni-app.md` 逐项检测（图标、导航栏等） 2. **加载原型参考** - 从 Story 规格文件中读取关联的原型文件路径 diff --git a/.claude/skills/d8d-prototype/steps/step-05-generate-docs.md b/.claude/skills/d8d-prototype/steps/step-05-generate-docs.md index 8fb9e5b..87078c6 100644 --- a/.claude/skills/d8d-prototype/steps/step-05-generate-docs.md +++ b/.claude/skills/d8d-prototype/steps/step-05-generate-docs.md @@ -10,12 +10,26 @@ ### 5.1 扫描项目文档 -扫描以下目录中的 `.md` 文件，作为文档系统的内容来源： +扫描以下目录中的 `.md` 和 `.yaml` 文件，作为文档系统的内容来源： -- `_bmad-output/` 下的所有文档 +- `_bmad-output/planning-artifacts/` — 规划文档（PRD、架构、UX 设计、产品简报等） +- `_bmad-output/implementation-artifacts/` — 实现产物（Story 规格、旅程验证、Pipeline 状态等，**可能不存在**） +- `_bmad-output/` 根目录下的文件 - 项目根目录的 README.md、DESIGN.md 等 - docs/ 目录下的文档 +#### 文档分组策略 + +按类型将文档卡片分组展示： + +| 分组 | 来源目录 | 文件模式 | 图标色 | +|------|---------|---------|--------| +| **Planning** | `planning-artifacts/` | 全部 .md | 蓝色/绿色/紫色/琥珀色 | +| **Implementation - Story 规格** | `implementation-artifacts/` | `X-Y-title.md` | 蓝色 | +| **Implementation - 旅程验证** | `implementation-artifacts/` | `epic-N-journeys.md` | 绿色 | +| **Implementation - Pipeline** | `implementation-artifacts/` | `pipeline-*.md`, `pipeline-*.yaml`, `sprint-status.yaml` | 橙色 | +| **Other** | 项目根目录 | README.md 等 | 灰色 | + ### 5.2 生成 docs-index.html 文档首页功能： diff --git a/.claude/skills/d8d-prototype/steps/step-05b-update-docs.md b/.claude/skills/d8d-prototype/steps/step-05b-update-docs.md new file mode 100644 index 0000000..484d810 --- /dev/null +++ b/.claude/skills/d8d-prototype/steps/step-05b-update-docs.md @@ -0,0 +1,142 @@ +# Step 5b: 迭代文档更新 + +**Progress: 迭代模式** — 仅在 [U] → [D] 更新文档中心 时执行 + +## STEP GOAL + +重新扫描 `_bmad-output/` 所有子目录，更新 `docs-index.html` 和 `view-doc.html`，使文档中心反映最新的项目文档（包括 d8d-dev 技能生成的 implementation-artifacts）。 + +与 step-05 的区别： +- step-05 是**首次生成**（从零创建） +- step-05b 是**迭代更新**（扫描新内容，重建文档页面，不影响其他原型页面） + +## 执行序列 + +### 5b.1 全量扫描 _bmad-output/ + +扫描 `_bmad-output/` 下所有子目录的 `.md` 和 `.yaml` 文件： + +``` +_bmad-output/ +├── planning-artifacts/ ← 规划阶段产物（首次即存在） +│ ├── product-brief.md +│ ├── prd.md +│ ├── ux-design-specification.md +│ ├── architecture.md +│ └── epics.md +├── implementation-artifacts/ ← 实现阶段产物（d8d-dev 后才存在） +│ ├── X-Y-title.md ← Story 规格 +│ ├── epic-N-journeys.md ← 旅程验证 +│ ├── pipeline-context.md ← Pipeline 上下文 +│ ├── pipeline-state.yaml ← Pipeline 状态 +│ └── sprint-status.yaml ← Sprint 状态 +└── (未来可能的新子目录) +``` + +**扫描逻辑**（使用 Bash 命令）： +```bash +find ../_bmad-output -type f \( -name "*.md" -o -name "*.yaml" -o -name "*.yml" \) | sort +``` + +### 5b.2 按类型分组 + +将扫描到的文件按以下规则分组： + +| 分组 | 匹配规则 | 卡片图标色 | 说明 | +|------|---------|-----------|------| +| Planning | `planning-artifacts/*.md` | 各文档独立配色 | PRD、架构、UX 等 | +| Story 规格 | `implementation-artifacts/\d+-\d+-*.md` | 蓝色 | X-Y-title.md 格式 | +| 旅程验证 | `implementation-artifacts/epic-*-journeys.md` | 绿色 | Epic 级别的 E2E 验证 | +| Pipeline 状态 | `implementation-artifacts/pipeline-*.md`, `pipeline-*.yaml`, `sprint-status.yaml` | 橙色 | 开发流程状态文件 | +| Other | 不匹配上述规则的文件 | 灰色 | 兜底分组 | + +### 5b.3 重建 docs-index.html + +**保留原有的整体设计风格**（Tailwind CSS、卡片布局），但增加分组标题和更多卡片。 + +#### 布局结构 + +``` +┌─────────────────────────────────────────────┐ +│ Documentation Center [← Back] │ +├─────────────────────────────────────────────┤ +│ │ +│ 📋 Planning │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Product Brief│ │ PRD │ ... │ +│ └──────────────┘ └──────────────┘ │ +│ │ +│ 🔧 Implementation — Story Specs │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ 1-1 Project │ │ 1-2 Database │ ... │ +│ └──────────────┘ └──────────────┘ │ +│ │ +│ ✅ Implementation — Journey Tests │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Epic 2 │ │ Epic 3 │ ... │ +│ └──────────────┘ └──────────────┘ │ +│ │ +│ 📊 Implementation — Pipeline │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Pipeline Ctx │ │ Pipeline St │ ... │ +│ └──────────────┘ └──────────────┘ │ +│ │ +└─────────────────────────────────────────────┘ +``` + +#### 卡片链接格式 + +对于 implementation-artifacts 中的文件，使用子目录前缀： +```html + +``` + +### 5b.4 更新 view-doc.html fetch 路径 + +更新 fetch 路径数组，确保覆盖所有 `_bmad-output/` 子目录： + +```javascript +const paths = [ + `../_bmad-output/planning-artifacts/${docName}`, + `../_bmad-output/implementation-artifacts/${docName}`, + `../_bmad-output/${docName}`, + `../${docName}` +]; +``` + +注意：当 `docName` 包含子目录前缀时（如 `implementation-artifacts/1-1-project-init.md`），需要正确处理路径： + +```javascript +// 如果 docName 包含子目录，直接拼接到 _bmad-output/ 下 +const paths = [ + `../_bmad-output/${docName}`, // 带子目录前缀的完整路径 + `../_bmad-output/planning-artifacts/${docName}`, + `../_bmad-output/implementation-artifacts/${docName}`, + `../${docName}` +]; +``` + +### 5b.5 更新 server.js（如需） + +检查 server.js 是否已支持 `.yaml`/`.yml` MIME 类型，如缺失则补充： + +```javascript +'.yaml': 'text/yaml; charset=utf-8', +'.yml': 'text/yaml; charset=utf-8', +``` + +### 5b.6 更新状态文件 + +- 更新 `last_updated` +- 将 `step-05b-update-docs` 加入 `completed_steps`（如该字段存在） + +## 完成标志 + +- [ ] `_bmad-output/` 所有子目录已扫描 +- [ ] 文件按类型分组正确 +- [ ] docs-index.html 已重建，包含所有文档的分组卡片 +- [ ] view-doc.html fetch 路径覆盖所有子目录 +- [ ] server.js 支持 .yaml/.yml MIME 类型 +- [ ] 状态文件已更新 + +**完成后，向用户展示更新结果和预览地址。** diff --git a/.claude/skills/d8d-prototype/steps/step-06-generate-server.md b/.claude/skills/d8d-prototype/steps/step-06-generate-server.md index 3419e9c..a63fe6a 100644 --- a/.claude/skills/d8d-prototype/steps/step-06-generate-server.md +++ b/.claude/skills/d8d-prototype/steps/step-06-generate-server.md @@ -34,6 +34,8 @@ const MIME_TYPES = { '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', + '.yaml': 'text/yaml; charset=utf-8', + '.yml': 'text/yaml; charset=utf-8', }; const server = http.createServer((req, res) => { diff --git a/.claude/skills/d8d-prototype/steps/step-07-validate.md b/.claude/skills/d8d-prototype/steps/step-07-validate.md index 2462502..3b5481e 100644 --- a/.claude/skills/d8d-prototype/steps/step-07-validate.md +++ b/.claude/skills/d8d-prototype/steps/step-07-validate.md @@ -2,6 +2,10 @@ **Progress: Step 7 of 7** — Next: 完成 +## STEP GOAL + +使用 Playwright MCP 和图片 MCP 对所有已生成的页面进行自动化验证，输出验证报告。 + ## ⚠️ 强制验证（不可跳过） 本步骤**禁止**用以下方式替代： @@ -16,10 +20,6 @@ 3. 发现问题 → 修复 → 重新截图验证 4. 全部通过 → 写入验证报告 → 标记完成 -## STEP GOAL - -使用 Playwright MCP 和图片 MCP 对所有已生成的页面进行自动化验证，输出验证报告。 - ## 执行序列 ### 7.1 验证流程 diff --git a/.claude/skills/d8d-prototype/workflow.md b/.claude/skills/d8d-prototype/workflow.md index 7e439d7..24fae1b 100644 --- a/.claude/skills/d8d-prototype/workflow.md +++ b/.claude/skills/d8d-prototype/workflow.md @@ -20,30 +20,6 @@ - 💾 **始终**在每步/每页面完成后更新状态文件 - 🎯 **始终**严格遵循步骤文件中的指令 -## 🔒 步骤完成门禁（强制） - -每个步骤标记完成前，**必须**满足以下条件，无证据 = 未完成： - -### 通用门禁（所有步骤） -1. ✅ 已完整 Read 当前步骤文件 -2. ✅ 步骤文件中每条指令都已执行 -3. ✅ 状态文件 `completed_steps` 包含 `evidence` 字段 - -### 验证步骤门禁（Step 7 专属） -1. ✅ 使用 `mcp__playwright__browser_take_screenshot` 对平铺入口截图 -2. ✅ 使用 `mcp__zai-mcp-server__analyze_image` 分析截图，验证： - - 桌面端页面：布局列数正确，内容按桌面端比例缩放 - - 移动端页面：手机框架包裹，375×812 尺寸 - - 文字可读、UI 元素清晰 -3. ✅ 生成验证报告文件 `prototype/VALIDATION-REPORT.md` -4. ✅ 分析结果中无 ❌ 级别问题（有则必须修复后重新验证） - -### ❌ 禁止的替代行为 -- ❌ 用 curl/wget HTTP 状态码代替截图验证 -- ❌ 只检查文件是否存在 -- ❌ 跳过图片分析直接标记完成 -- ❌ 自行声称"验证通过"而不提供截图证据 - ## 状态文件：.prototype-state.md 状态文件位于输出目录 `prototype/.prototype-state.md`，用于跟踪前后台每个页面的生成进度。 @@ -95,6 +71,30 @@ page_counts: 3. **每个步骤完成时**：将步骤名和 evidence 加入 `completed_steps`（必须有 evidence，描述具体做了什么） 4. **全部完成时**：设置 `status: completed` +## 🔒 步骤完成门禁（强制） + +每个步骤标记完成前，**必须**满足以下条件，无证据 = 未完成： + +### 通用门禁（所有步骤） +1. ✅ 已完整 Read 当前步骤文件 +2. ✅ 步骤文件中每条指令都已执行 +3. ✅ 状态文件 `completed_steps` 包含 `evidence` 字段 + +### 验证步骤门禁（Step 7 专属） +1. ✅ 使用 `mcp__playwright__browser_take_screenshot` 对平铺入口截图 +2. ✅ 使用 `mcp__zai-mcp-server__analyze_image` 分析截图，验证： + - 桌面端页面：布局列数正确，内容按桌面端比例缩放 + - 移动端页面：手机框架包裹，375×812 尺寸 + - 文字可读、UI 元素清晰 +3. ✅ 生成验证报告文件 `prototype/VALIDATION-REPORT.md` +4. ✅ 分析结果中无 ❌ 级别问题（有则必须修复后重新验证） + +### ❌ 禁止的替代行为 +- ❌ 用 curl/wget HTTP 状态码代替截图验证 +- ❌ 只检查文件是否存在 +- ❌ 跳过图片分析直接标记完成 +- ❌ 自行声称"验证通过"而不提供截图证据 + ## 状态机：启动与恢复 ### 初始化流程 @@ -115,7 +115,10 @@ page_counts: +-- [有状态文件，status=completed] → 已完成 → 询问用户： [R] 重新生成（删除状态文件，从头开始） - [U] 增量更新（选择前台/后台/特定页面） + [U] 增量更新 — 选择更新范围： + [D] 更新文档中心 — 重新扫描 _bmad-output/，更新 docs-index.html + view-doc.html + [P] 更新特定页面 — 选择前台/后台/特定页面重新生成 + [A] 全部更新 — 文档 + 页面一起更新 [V] 查看当前原型（启动服务器） ```