Merge pull request 'sync: 迭代文档更新模式 + implementation-artifacts + 强制验证门禁' (#6) from sync/d8d-skills-20260408-071911 into master
Reviewed-on: http://gitea.d8d.fun/d8dfun/bmad-method-template/pulls/6
This commit is contained in:
@@ -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 规格文件中读取关联的原型文件路径
|
||||
|
||||
@@ -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
|
||||
|
||||
文档首页功能：
|
||||
|
||||
142
.claude/skills/d8d-prototype/steps/step-05b-update-docs.md
Normal file
142
.claude/skills/d8d-prototype/steps/step-05b-update-docs.md
Normal file
@@ -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
|
||||
<a href="view-doc.html?doc=implementation-artifacts/1-1-project-init.md">
|
||||
```
|
||||
|
||||
### 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 类型
|
||||
- [ ] 状态文件已更新
|
||||
|
||||
**完成后，向用户展示更新结果和预览地址。**
|
||||
@@ -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) => {
|
||||
|
||||
@@ -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 验证流程
|
||||
|
||||
@@ -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] 查看当前原型（启动服务器）
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user