sdd-flow-kit 1.3.14 → 1.3.18

package/src/templates/skills/confluence-doc.py.template

@@ -5,6 +5,7 @@ import json
 import sys
 import os
 import re
+import shutil
 from pathlib import Path
 from urllib.parse import quote, urlencode, urljoin, urlparse, unquote
 from urllib.request import Request, urlopen
@@ -66,6 +67,10 @@ def version_slug(prefix: str, version: str) -> str:
     return prefix.lower() + "-v" + version.replace(".", "")
 
 
+# 图片统一放在版本目录下的 image/ 子目录，与 PRD Markdown 同级
+IMAGE_SUBDIR = "image"
+
+
 def dedupe_keywords(items: list[str]) -> list[str]:
     """去重并保持顺序。"""
     seen: set[str] = set()
@@ -564,10 +569,11 @@ def download_images_http(
     token: str,
     content_html: str,
     version_dir: Path,
-    slug: str,
     request_get=None,
 ) -> str:
-    """下载正文图片并改写相对路径；request_get 可注入 Playwright page.request.get。"""
+    """下载正文图片到版本目录下的 image/ 并改写相对路径；request_get 可注入 Playwright page.request.get。"""
+    image_dir = version_dir / IMAGE_SUBDIR
+    image_dir.mkdir(parents=True, exist_ok=True)
     img_urls = re.findall(r'<img[^>]*src="([^"]+)"', content_html)
     for i, img_url in enumerate(img_urls):
         original_url = img_url
@@ -583,7 +589,7 @@ def download_images_http(
         parsed = urlparse(img_url)
         ext = os.path.splitext(parsed.path)[1] or ".png"
         filename = f"image_{i + 1}{ext}"
-        filepath = version_dir / filename
+        filepath = image_dir / filename
         try:
             if request_get:
                 resp = request_get(img_url)
@@ -600,7 +606,7 @@ def download_images_http(
             if ok and body:
                 filepath.write_bytes(body)
                 content_html = content_html.replace(
-                    f'src="{original_url}"', f'src="{slug}/{filename}"'
+                    f'src="{original_url}"', f'src="{IMAGE_SUBDIR}/{filename}"'
                 )
         except Exception:
             pass
@@ -608,7 +614,6 @@ def download_images_http(
 
 
 def write_prd_markdown(
-    docs_root: Path,
     title: str,
     matched_keyword: str,
     target_url: str,
@@ -617,12 +622,12 @@ def write_prd_markdown(
     base_url: str,
     token: str,
     version_dir: Path,
-    slug: str,
     request_get=None,
 ) -> Path:
-    """将 HTML 转 Markdown 并写入 docs 目录。"""
+    """将 HTML 转 Markdown 并写入版本目录（与 image/ 同级）。"""
+    version_dir.mkdir(parents=True, exist_ok=True)
     html = clean_confluence_storage_html(content_html)
-    html = download_images_http(base_url, token, html, version_dir, slug, request_get)
+    html = download_images_http(base_url, token, html, version_dir, request_get)
     content_md = parse_html_to_markdown(html)
     md_content = f"""# {title}
 
@@ -636,19 +641,57 @@ def write_prd_markdown(
     md_filename = sanitize_filename(title) + ".md"
     if not re.search(rf"{prefix}[-_]?V", md_filename, flags=re.IGNORECASE):
         md_filename = f"{matched_keyword}-{md_filename}"
-    md_path = docs_root / md_filename
+    md_path = version_dir / md_filename
     md_path.write_text(md_content, encoding="utf-8")
     return md_path
 
 
+def ensure_prd_image_dir_metadata(content: str) -> str:
+    """在 PRD 头部写入原型图片相对路径，供 OPSX UI 解析。"""
+    if "原型图片目录" in content:
+        return content
+    lines = content.split("\n")
+    title_idx = next(
+        (i for i, line in enumerate(lines) if line.strip().startswith("# ")),
+        -1,
+    )
+    insert_at = title_idx + 1 if title_idx >= 0 else 0
+    lines.insert(insert_at, "")
+    lines.insert(insert_at + 1, f"> 原型图片目录: {IMAGE_SUBDIR}/")
+    return "\n".join(lines)
+
+
+def sync_to_openspec_source(md_path: Path, version_dir: Path) -> Path | None:
+    """将 PRD 与 image/ 同步到 openspec source/（需设置环境变量 SDD_SYNC_SOURCE_DIR）。"""
+    raw = env("SDD_SYNC_SOURCE_DIR")
+    if not raw:
+        return None
+    source_dir = Path(raw).expanduser()
+    if not source_dir.is_absolute():
+        source_dir = (Path.cwd() / source_dir).resolve()
+    source_dir.mkdir(parents=True, exist_ok=True)
+    content = ensure_prd_image_dir_metadata(md_path.read_text(encoding="utf-8"))
+    dest_md = source_dir / "PRD.md"
+    dest_md.write_text(content, encoding="utf-8")
+    src_image = version_dir / IMAGE_SUBDIR
+    dest_image = source_dir / IMAGE_SUBDIR
+    if src_image.is_dir():
+        if dest_image.exists():
+            shutil.rmtree(dest_image)
+        shutil.copytree(src_image, dest_image)
+        print(f"📋 已同步到 openspec source: {dest_md}")
+        print(f"🖼️ 已同步图片目录: {dest_image}")
+    else:
+        print(f"📋 已同步到 openspec source: {dest_md}")
+    return dest_md
+
+
 def try_rest_download(
     base_url: str,
     prefix: str,
     version: str,
     keywords: list[str],
-    docs_root: Path,
     version_dir: Path,
-    slug: str,
 ) -> bool:
     """REST API 主路径：Bearer Token 拉取 PRD，不依赖 Playwright 登录。"""
     token = get_api_token()
@@ -664,7 +707,6 @@ def try_rest_download(
         print(f"✅ [REST] 命中: {matched_keyword} | {title[:80]}")
         page = rest_fetch_page(base_url, token, page_id)
         md_path = write_prd_markdown(
-            docs_root,
             page["title"],
             matched_keyword,
             target_url,
@@ -673,13 +715,13 @@ def try_rest_download(
             base_url,
             token,
             version_dir,
-            slug,
         )
         if md_path.stat().st_size < 80:
             raise RuntimeError("生成的 Markdown 过短")
+        sync_to_openspec_source(md_path, version_dir)
         print("\n✅ 获取完成（REST API）！")
         print(f"📄 主文档: {md_path}")
-        print(f"🖼️ 图片目录: {version_dir}")
+        print(f"🖼️ 图片目录: {version_dir / IMAGE_SUBDIR}")
         return True
     except Exception as e:
         print(f"   REST 拉取失败: {e}")
@@ -916,8 +958,9 @@ def main():
 
     print(f"\n📥 开始获取 {prefix} {keywords[0]} 需求文档")
     print(f"🔍 将依次尝试: {', '.join(keywords)}")
-    print(f"📁 输出目录: {docs_root}")
-    print(f"🖼️ 图片目录: {version_dir}")
+    print(f"📁 输出根目录: {docs_root}")
+    print(f"📁 版本目录: {version_dir}")
+    print(f"🖼️ 图片目录: {version_dir / IMAGE_SUBDIR}")
 
     headed = env_bool("CONFLUENCE_HEADED") or env("CONFLUENCE_HEADLESS", "1").lower() in (
         "0",
@@ -944,9 +987,7 @@ def main():
                 prefix=prefix,
                 version=version,
                 keywords=keywords,
-                docs_root=docs_root,
                 version_dir=version_dir,
-                slug=slug,
                 headless=headless,
                 slow_mo=slow_mo,
             )
@@ -958,7 +999,7 @@ def main():
 
     if use_rest:
         print("\n🌐 Playwright 未成功，回退 REST API（Bearer Token）...")
-        if try_rest_download(base_url, prefix, version, keywords, docs_root, version_dir, slug):
+        if try_rest_download(base_url, prefix, version, keywords, version_dir):
             return
 
     print("\n❌ PRD 拉取失败：Playwright 与 REST 均未成功。")
@@ -978,9 +1019,7 @@ def _download_via_playwright(
     prefix: str,
     version: str,
     keywords: list[str],
-    docs_root: Path,
     version_dir: Path,
-    slug: str,
     headless: bool,
     slow_mo: int,
 ) -> bool:
@@ -1017,7 +1056,7 @@ def _download_via_playwright(
                 )
 
             if not target_url or not matched_keyword:
-                debug_path = docs_root / "confluence-search-debug.png"
+                debug_path = version_dir / "confluence-search-debug.png"
                 try:
                     page.screenshot(path=str(debug_path), full_page=True)
                     print(f"   已保存调试截图: {debug_path}")
@@ -1075,7 +1114,6 @@ def _download_via_playwright(
 
             token = get_api_token()
             md_path = write_prd_markdown(
-                docs_root,
                 title,
                 matched_keyword,
                 target_url,
@@ -1084,13 +1122,14 @@ def _download_via_playwright(
                 base_url,
                 token,
                 version_dir,
-                slug,
                 request_get=page.request.get,
             )
 
+            sync_to_openspec_source(md_path, version_dir)
+
             print("\n✅ 获取完成（Playwright）！")
             print(f"📄 主文档: {md_path}")
-            print(f"🖼️ 图片目录: {version_dir}")
+            print(f"🖼️ 图片目录: {version_dir / IMAGE_SUBDIR}")
             return True
         except Exception as e:
             print(f"\n❌ Playwright 获取失败: {e}")

package/src/templates/skills/demo-reference-mandatory-workflow.md

@@ -0,0 +1,77 @@
+# 演示代码强制迁移工作流（SDD / OpenSpec 通用）
+
+> 适用于 **Vue / React / 其他** 演示仓库。验收标准不是「技术栈一致」，而是 **交互与功能与演示代码等价**。
+
+## 原则
+
+1. **演示代码是 UI/交互 SSOT**（高于 PRD 文字摘要、高于 AI 自拟骨架）。
+2. **禁止** 用「一个 FinanceDetailDrawer 读接口」代替「按演示拆分的多子模块」。
+3. **禁止** 在 08 报告用 `index.vue:1` 或注释登记冒充实现。
+4. 演示可为 React、生产为 Vue（或反之）——须在映射表注明技术栈，迁移的是 **模块边界 + 交互信号**，不是复制粘贴 DOM 库。
+
+## 阶段 B — 04 技术文档
+
+在 `04-技术文档草稿.md` 增加 **§2.4 演示代码参照**（propose 时迁入 `design.md`）：
+
+```markdown
+## 2.4 演示代码参照
+
+- 演示代码根路径：`/path/to/demo` 或相对路径
+- 技术栈：vue | react | 其他
+- 说明：（可选）Element Plus 演示 → 生产 Naive UI
+
+| 演示模块 | 演示文件/组件 | 计划生产组件路径 | 关键交互信号 |
+|---------|--------------|-----------------|-------------|
+| BD预估 | ProjectDetail.vue §BD预估 | src/views/.../BdEstimateSection.vue | 编辑预估、BD预计开票日期、距今天数 |
+| 红票及其他 | ProjectDetail.vue §红票 | src/views/.../RedInvoiceSection.vue | 红票及其他、添加记录、红票 |
+```
+
+纯后端 / 无 UI 演示时，在 `design.md` 首行写：`DEMO_REFERENCE_EXEMPT: <原因>`
+
+## 阶段 C — Propose
+
+`design.md` **必须**含 `## 演示代码参照` 与上表（可从 04 复制并细化路径）。
+
+`tasks.md` **必须**含：
+
+```markdown
+## 演示模块迁移（强制，对齐 design 映射表）
+
+### Red
+- [ ] D.1 为每个映射行编写失败测试（组件存在 / 交互文案 / API mock）
+### Green
+- [ ] D.2 按演示结构实现生产组件（禁止合并为单文件只读骨架）
+```
+
+**门禁**：`gate propose-ready` / `gate ac-ready` 执行 `checkDemoReferenceArtifacts`。
+
+## 阶段 D — Apply
+
+实现顺序：
+
+1. 读演示文件对应段落（无关技术栈）
+2. 拆分为生产 `components/*.vue`（或 tsx）
+3. 接已有 API（`config/api/modules`）
+4. 每完成一行映射，勾选 tasks 并跑该行单测
+
+## 阶段 E — Validate / Deliver
+
+- `assess-demo-implementation-coverage.mjs`：映射表中的生产文件存在，且含「关键交互信号」
+- `assess-e2e-assertion-depth.mjs`：E2E 须点到演示中的主按钮/区块（非 placeholder-only）
+- 08 报告证据须指向 **具体组件文件 + 行号 + 交互文案**
+
+## 05 验收清单
+
+详情类 AC 验收标准须写清演示模块，例如：
+
+- `详情 Tab「财务明细」含金额与返点卡片、财务链路、红票及其他（对齐演示 ProjectDetail.vue）`
+- `BD预估区含编辑预估按钮，保存 toast「BD预估已保存」`
+
+## 豁免
+
+| 场景 | 写法 |
+|------|------|
+| 纯 API/配置 | `DEMO_REFERENCE_EXEMPT: 无 UI` |
+| 演示待补 | 禁止进入 impl；须先补演示或用户书面确认 |
+
+环境变量（仅紧急）：`OPSX_SKIP_DEMO_REFERENCE=1`

package/src/templates/skills/doc-skill.SKILL.md.template

@@ -2,7 +2,7 @@
 name: {{SKILL_NAME}}
 description: |
   当用户说「获取 {{PRODUCT}} Vx.y.z 需求文档」「下载 {{PRODUCT}}-Vx.y.z PRD」「查询 {{PRODUCT}} x.y.z 版本需求」时触发。
-  自动从 Confluence 搜索对应版本 PRD 页面；`技术文档`、`后端`、`详细设计` 类页面会被拒绝，避免误下载为 PRD；下载图片并生成 Markdown 到本仓库 `docs/`。
+  自动从 Confluence 搜索对应版本 PRD 页面；`技术文档`、`后端`、`详细设计` 类页面会被拒绝，避免误下载为 PRD；下载图片并生成 Markdown 到本仓库 `docs/<版本目录>/`。
 ---
 
 # {{PRODUCT}} 需求文档获取（docs/{{SKILL_DIR}}）
@@ -80,14 +80,21 @@ CONFLUENCE_PAGE_URL="https://confluence.huan.tv/spaces/yyzcpt/pages/109609740/..
 
 ## 输出结构
 
+每个版本独占一个目录（目录名由产品前缀 + 版本号自动生成，如 `adi-v234`）：
+
 ```
-<repo>/docs/
-├── {{PRODUCT_PREFIX}}-V1.2.3-xxx.md
-└── {{PRODUCT_PREFIX_LOWER}}-v123/
-    ├── image_1.png
-    └── image_2.png
+<docs根目录>/
+└── {{PRODUCT_PREFIX_LOWER}}-v123/          # 版本目录（相对脚本所在 docs/ 或 DOC_DOWNLOAD_DIR）
+    ├── {{PRODUCT_PREFIX}}_V1.2.3-xxx.md    # PRD 主文档
+    └── image/                               # 正文图片
+        ├── image_1.png
+        └── image_2.png
 ```
 
+- **docs 根目录**：默认为脚本上级目录（`docs/` 或 monorepo 下的 `frontend/docs/`）；可用环境变量 `DOC_DOWNLOAD_DIR` 覆盖为任意绝对/相对路径。
+- **版本目录**：`<docs根目录>/<prefix>-v<版本号去点>`，便于多版本并存、按目录定位 PRD。
+- **openspec 同步**：在 SDD run 中执行脚本时设置 `SDD_SYNC_SOURCE_DIR`（由 `01-获取需求文档指引.md` 自动注入），下载成功后自动写入 `source/PRD.md` 与 `source/image/`；亦可 `npx sdd-flow-kit sync-source-prd --run-id <runId>`。
+
 ## 注意事项
 
 {{CONFLUENCE_SPACE_NOTE}}

package/src/templates/skills/layered-testing-strategy.md

@@ -4,12 +4,19 @@
 
 ## 四层模型
 
-| 层级 | 覆盖范围 | 典型断言 | 缺失风险 |
-|------|---------|---------|---------|
-| **L1 能力** | API、状态机、mapper、脏数据 | 接口封装、枚举映射、mutation 参数 | 主流程不通 |
-| **L2 交互契约** | 列序、disabled、toast、tooltip、placeholder | **完整字符串**（禁止 `toContain('成功')`） | PRD 细节漏项 |
-| **L3 路径** | 每页面/每主链路一条 E2E | 登录 → 设规则 → 结果页重审 | 只 smoke 一条路径 |
-| **L4 视觉** | 原型图 / Figma / `playwright-pic` | 列位置、紫色摘要、布局两行限制 | UI 与原型偏差 |
+| 层级 | 覆盖范围 | 典型断言 | 缺失风险 | 门禁 |
+|------|---------|---------|---------|------|
+| **L1 能力** | API、状态机、mapper、脏数据 | 接口封装、枚举映射、mutation 参数、**snake/camel normalize** | 主流程不通、列表空数据 | `assess-api-field-contract.mjs` + unit |
+| **L2 交互契约** | 列序、disabled、toast、tooltip、placeholder | **完整字符串**（禁止 `toContain('成功')`） | PRD 细节漏项 | AC 映射须 test 块内 `expect` |
+| **L3 路径** | 每页面/每主链路一条 E2E | 登录 → 列表有数据 → 点详情 → **演示映射中的按钮/区块** | 只 smoke placeholder | `assess-e2e-assertion-depth.mjs` |
+| **L3.5 演示迁移** | 演示模块 → 生产组件 1:1 | design 映射表每行在生产代码有「关键交互信号」 | 单文件只读骨架代替演示 | `assess-demo-implementation-coverage.mjs` |
+| **L4 视觉** | 原型图 / Figma / `playwright-pic` | 列位置、紫色摘要、布局两行限制 | UI 与原型偏差 | 人工 + 截图 |
+
+## 禁止伪覆盖
+
+- **禁止** `prd-atoms-coverage.spec.ts` 等仅 `toBeGreaterThan(0)` 或注释登记 PRD-ID 的文件计入 semantic/e2e 覆盖。
+- **禁止** 仅 `getByPlaceholder` 可见即宣布列表类 AC 通过；须 `waitForResponse` / `getByRole('cell')` / `toContainText` 等数据断言。
+- **禁止** 用单个 DetailDrawer 只读骨架代替演示中的 BD预估/红票/可编辑金额等子模块；须遵循 `demo-reference-mandatory-workflow` skill。
 
 ## 与 05-验收清单的绑定
 

package/src/templates/skills/version-trigger.SKILL.md.template

@@ -0,0 +1,56 @@
+---
+name: 00-sdd-flow-kit-version-trigger
+description: 最高优先级触发。凡用户表达“开发/进行/实现 <产品> <版本> 需求/版本”，例如 ADI_V2.3.4、OMS V1.24.5、BreakX 1.0.2、欢盟 V2.1.0，必须第一步执行 `npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}`。禁止先执行 openspec new change、OPSX Propose 或修改 src/e2e。
+---
+
+# SDD Flow Kit 版本开发强制入口
+
+## 适用范围
+
+当用户输入匹配以下任一意图时，本 skill 优先于普通 OpenSpec / OPSX 流程：
+
+- `开发 <产品> <版本>`
+- `进行 <产品> <版本> 需求`
+- `实现 <产品> <版本> 版本`
+- `<产品>_V<版本>` / `<产品>-V<版本>`
+- 示例：`开发 ADI_V2.3.4版本`、`开发 OMS V1.24.5`、`进行 BreakX 1.0.2 需求`、`欢盟 V2.1.0 版本开发`
+
+## 第一动作（必须）
+
+在项目根目录立即执行：
+
+```bash
+npx sdd-flow-kit guard "<用户原话>" -y --agent {{AGENT_NAME}}
+```
+
+若 `guard` 不可用，退化为：
+
+```bash
+npx sdd-flow-kit invoke "开发 <产品> <版本> 需求" -y --agent {{AGENT_NAME}}
+```
+
+## 严格禁止
+
+在 `guard/invoke` 成功前，禁止：
+
+- 创建 `openspec/changes/**`
+- 执行 `openspec new change`
+- 执行 OPSX / OpenSpec Propose
+- 修改 `src/**`、`frontend/src/**`、`e2e/**`
+- 用自然语言计划替代脚本入口
+
+## 成功后继续
+
+`guard/invoke` 成功后，必须读取并遵循：
+
+- `openspec/PRD/<runId>/NEXT.md`
+- `openspec/PRD/<runId>/.session-state.json`
+
+若 `.session-state.json` 中 `docModeOnly=true`，仍然禁止修改业务代码，直到 `gate docs-closed`、`gate ac-ready`、`phase impl` 与 `gate impl-allowed` 全部通过。
+
+## 优先级
+
+```text
+版本开发意图 → sdd-flow-kit guard/invoke → NEXT.md
+普通代码需求 → OPSX/OpenSpec
+```