adspecs 0.1.19 → 0.1.21

package/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,143 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+playwright-cli open
+
+# Start recording
+playwright-cli video-start demo.webm
+
+# Add a chapter marker for section transitions
+playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+playwright-cli goto https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+
+# Add another chapter
+playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-start recordings/login-flow-2024-01-15.webm
+playwright-cli video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows inserting appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
+2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3) Use playwright-cli run-code --filename your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async page => {
+  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
+  await page.goto('https://demo.playwright.dev/todomvc');
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter('Adding Todo Items', {
+    description: 'We will add several items to the todo list.',
+    duration: 2000,
+  });
+
+  // Perform action
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter('Verifying Results', {
+    description: 'Checking the item appeared in the list.',
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText('Walk the dog').boundingBox();
+  await page.screencast.showOverlay(`
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `, { duration: 2000 });
+
+  await page.screencast.stop();
+}
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method | Use Case |
+|--------|----------|
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
+| `disposable.dispose()` | Remove a sticky overlay added without duration |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

package/skills/playwright-trace/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: playwright-trace
+description: Inspect Playwright trace files from the command line — list actions, view requests, console, errors, snapshots and screenshots.
+allowed-tools: Bash(npx:*)
+---
+
+# Playwright Trace CLI
+
+Inspect `.zip` trace files produced by Playwright tests without opening a browser.
+
+## Workflow
+
+1. Start with `trace open <trace.zip>` to extract the trace and see its metadata.
+2. Use `trace actions` to see all actions with their action IDs.
+3. Use `trace action <action-id>` to drill into a specific action — see parameters, logs, source location, and available snapshots.
+4. Use `trace requests`, `trace console`, or `trace errors` for cross-cutting views.
+5. Use `trace snapshot <action-id>` to get the DOM snapshot, or run a browser command against it.
+6. Use `trace close` to remove the extracted trace data when done.
+
+All commands after `open` operate on the currently opened trace — no need to pass the trace file again. Opening a new trace replaces the previous one.
+
+## Commands
+
+### Open a trace
+
+```bash
+# Extract trace and show metadata: browser, viewport, duration, action/error counts
+npx playwright trace open <trace.zip>
+```
+
+### Close a trace
+
+```bash
+# Remove extracted trace data
+npx playwright trace close
+```
+
+### Actions
+
+```bash
+# List all actions as a tree with action IDs and timing
+npx playwright trace actions
+
+# Filter by action title (regex, case-insensitive)
+npx playwright trace actions --grep "click"
+
+# Only failed actions
+npx playwright trace actions --errors-only
+```
+
+### Action details
+
+```bash
+# Show full details for one action: params, result, logs, source, snapshots
+npx playwright trace action <action-id>
+```
+
+The `action` command displays available snapshot phases (before, input, after) and the exact command to extract them.
+
+### Requests
+
+```bash
+# All network requests: method, status, URL, duration, size
+npx playwright trace requests
+
+# Filter by URL pattern
+npx playwright trace requests --grep "api"
+
+# Filter by HTTP method
+npx playwright trace requests --method POST
+
+# Only failed requests (status >= 400)
+npx playwright trace requests --failed
+```
+
+### Request details
+
+```bash
+# Show full details for one request: headers, body, security
+npx playwright trace request <request-id>
+```
+
+### Console
+
+```bash
+# All console messages and stdout/stderr
+npx playwright trace console
+
+# Only errors
+npx playwright trace console --errors-only
+
+# Only browser console (no stdout/stderr)
+npx playwright trace console --browser
+
+# Only stdout/stderr (no browser console)
+npx playwright trace console --stdio
+```
+
+### Errors
+
+```bash
+# All errors with stack traces and associated actions
+npx playwright trace errors
+```
+
+### Snapshots
+
+The `snapshot` command loads the DOM snapshot for an action into a headless browser and runs a single browser command against it. Without a browser command, it returns the accessibility snapshot.
+
+```bash
+# Get the accessibility snapshot (default)
+npx playwright trace snapshot <action-id>
+
+# Use a specific phase
+npx playwright trace snapshot <action-id> --name before
+
+# Run eval to query the DOM
+npx playwright trace snapshot <action-id> -- eval "document.title"
+npx playwright trace snapshot <action-id> -- eval "document.querySelector('#error').textContent"
+
+# Eval on a specific element ref (from the snapshot)
+npx playwright trace snapshot <action-id> -- eval "el => el.getAttribute('data-testid')" e5
+
+# Take a screenshot of the snapshot
+npx playwright trace snapshot <action-id> -- screenshot
+
+# Redirect output to a file
+npx playwright trace snapshot <action-id> -- eval "document.body.outerHTML" --filename=page.html
+npx playwright trace snapshot <action-id> -- screenshot --filename=screenshot.png
+```
+
+Only three browser commands are useful on a frozen snapshot: `snapshot`, `eval`, and `screenshot`.
+
+### Attachments
+
+```bash
+# List all trace attachments
+npx playwright trace attachments
+
+# Extract an attachment by its number
+npx playwright trace attachment 1
+npx playwright trace attachment 1 -o out.png
+```
+
+## Typical investigation
+
+```bash
+# 1. Open the trace and see what's inside
+npx playwright trace open test-results/my-test/trace.zip
+
+# 2. What actions ran?
+npx playwright trace actions
+
+# 3. Which action failed?
+npx playwright trace actions --errors-only
+
+# 4. What went wrong?
+npx playwright trace action 12
+
+# 5. What did the page look like at that moment?
+npx playwright trace snapshot 12
+
+# 6. Query the DOM for more detail
+npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent"
+
+# 7. Any relevant network failures?
+npx playwright trace requests --failed
+
+# 8. Any console errors?
+npx playwright trace console --errors-only
+```

package/skills/project-init/SKILL.md

@@ -302,7 +302,7 @@ questions: [
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
-       templates_decision:   "update" | "skip",   # .adspecs 为 skip 且 templates/ 有文件时
+       templates_decision:   { "<文件名>": "replace" | "keep", ... },  # .adspecs 为 skip 且 templates/ 有文件时，逐文件确认
      }
      ```
 
@@ -317,7 +317,7 @@ questions: [
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
-       templates_decision:   "update" | "skip",   # .adspecs 为 skip 且 templates/ 有文件时
+       templates_decision:   { "<文件名>": "replace" | "keep", ... },  # .adspecs 为 skip 且 templates/ 有文件时，逐文件确认
      }
      ```
 
@@ -334,7 +334,7 @@ questions: [
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
-       templates_decision:   "update" | "skip",   # .adspecs 为 skip 且 templates/ 有文件时
+       templates_decision:   { "<文件名>": "replace" | "keep", ... },  # .adspecs 为 skip 且 templates/ 有文件时，逐文件确认
      }
      ```
 
@@ -351,7 +351,7 @@ questions: [
      }
      子目录决策 = {
        conventions_decision: "update" | "skip",   # docs 为 skip 且 40-project_conventions/ 有文件时
-       templates_decision:   "update" | "skip",   # .adspecs 为 skip 且 templates/ 有文件时
+       templates_decision:   { "<文件名>": "replace" | "keep", ... },  # .adspecs 为 skip 且 templates/ 有文件时，逐文件确认
      }
      固定技术栈：
        FRONT_DEMO_SOURCE = "antd-front-demo"      # Ant Design React（无需询问用户）
@@ -421,27 +421,79 @@ questions: [
      - 记录子决策：`conventions_decision` = `"update"` | `"skip"`
      - 如果 `40-project_conventions/` 不存在或仅包含空目录 → 跳过此检查，`conventions_decision` = `"skip"`
 
-   - **子目录更新检查（.adspecs/templates/）**：当 `.adspecs/` 已存在且 `.adspecs` 决策为 `skip`，且 `.adspecs/templates/` 下已包含实际文件时，需额外询问用户是否更新模板目录：
-     - 使用 **AskUserQuestion** 工具询问：
+   - **子目录更新检查（.adspecs/templates/）**：当 `.adspecs/` 已存在且 `.adspecs` 决策为 `skip`，且 `.adspecs/templates/` 下已包含实际文件时，需**逐文件**询问用户是否替换模板文件（因用户可能在首次初始化后根据项目实际情况修改了模板内容）：
+
+     **步骤 1：扫描目标目录已有模板文件**
+     - 列出 `$TARGET/.adspecs/templates/` 下所有 `.md` 文件
+     - 同时列出 `$PLUGIN_DIR/.adspecs/templates/` 下所有 `.md` 文件（插件根目录的最新模板）
+     - 计算两组文件集合：
+       - `existing_files`：目标目录中已有的模板文件名列表
+       - `new_files`：插件根目录中存在但目标目录中不存在的模板文件（需要新增）
+       - `common_files`：两边都存在的模板文件（需要逐一确认是否替换）
+
+     **步骤 2：先处理新增文件（无需确认）**
+     - 如果 `new_files` 非空 → 直接复制到目标目录，输出：`📦 模板新增：已添加 {N} 个新模板文件：{文件列表}`
+     - 如果 `new_files` 为空 → 不输出
+
+     **步骤 3：逐文件确认（批量询问）**
+     - 对 `common_files` 中的每个文件，使用 **AskUserQuestion** 工具批量询问（每次最多 4 个文件，因为 AskUserQuestion 最多支持 4 个问题，需要分多轮询问）：
 
        ```
+       # 第 1 轮（文件 1~4）
        questions: [
          {
-           question: ".adspecs/templates/ 目录已存在且包含文件，是否使用最新模板文件更新？",
-           header: "templates/",
+           question: "模板文件 {文件名1} 已存在，是否使用最新版本替换？",
+           header: "{文件名1}",
+           options: [
+             { label: "保留现有", description: "保留当前项目中的版本，不做修改（用户可能已按项目实际情况调整过）" },
+             { label: "替换为最新", description: "使用插件根目录中的最新版本覆盖现有文件" }
+           ],
+           multiSelect: false
+         },
+         {
+           question: "模板文件 {文件名2} 已存在，是否使用最新版本替换？",
+           header: "{文件名2}",
            options: [
-             { label: "更新", description: "使用 references 中最新的模板文件覆盖现有内容（已有模板将被替换）" },
-             { label: "跳过", description: "保留现有 .adspecs/templates/ 内容，不做任何修改" }
+             { label: "保留现有", description: "保留当前项目中的版本，不做修改" },
+             { label: "替换为最新", description: "使用插件根目录中的最新版本覆盖现有文件" }
+           ],
+           multiSelect: false
+         },
+         ...  # 最多 4 个问题一轮
+       ]
+       ```
+
+     - 如果 `common_files` 数量超过 4 个，需要分多轮调用 AskUserQuestion，每轮最多 4 个文件
+     - 每轮询问结束后，将用户选择记录到 `templates_decision` 映射中
+
+     **步骤 4：提供批量快捷选项（可选）**
+     - 在首轮询问前，可先通过 AskUserQuestion 提供一个全局快捷选项：
+
+       ```
+       questions: [
+         {
+           question: ".adspecs/templates/ 目录已存在且包含 {N} 个模板文件，是否需要逐文件确认？（选择"否"将统一保留现有文件）",
+           header: "批量确认",
+           options: [
+             { label: "逐文件确认", description: "对每个已修改的模板文件逐一询问是否替换（推荐，用户可能已按项目情况调整过模板）" },
+             { label: "全部保留现有", description: "保留所有现有模板文件不做修改（跳过逐文件确认）" },
+             { label: "全部替换为最新", description: "使用插件根目录中的最新版本覆盖所有模板文件" }
            ],
            multiSelect: false
          }
        ]
        ```
 
-     - 记录子决策：`templates_decision` = `"update"` | `"skip"`
-     - 如果 `.adspecs/templates/` 不存在或仅包含空目录 → 跳过此检查，`templates_decision` = `"skip"`
+     - 如果用户选择"逐文件确认" → 执行步骤 3 的逐文件询问
+     - 如果用户选择"全部保留现有" → `templates_decision` 中所有文件标记为 `"keep"`
+     - 如果用户选择"全部替换为最新" → `templates_decision` 中所有文件标记为 `"replace"`
+
+     **步骤 5：记录子决策**
+     - 记录子决策映射：`templates_decision` = `{ "<文件名>": "replace" | "keep", ... }`
+     - 其中 `"replace"` 表示使用插件根目录最新版本覆盖，`"keep"` 表示保留目标目录现有版本
+     - 如果 `.adspecs/templates/` 不存在或仅包含空目录 → 跳过此检查，`templates_decision` = `{}`（空映射）
 
-7. **输出初始化计划摘要**，包含项目信息（项目名称、项目短名称、公司名称、文件密级、项目目录）、初始化模式、前端技术栈（如适用）、每个区域的操作（创建 / 重新创建 / 跳过）、子目录更新决策（40-project_conventions/ 和 templates/ 的更新/跳过）、feature.json/project.json 属性补全计划以及补充检查结果，等待用户确认后继续执行
+7. **输出初始化计划摘要**，包含项目信息（项目名称、项目短名称、公司名称、文件密级、项目目录）、初始化模式、前端技术栈（如适用）、每个区域的操作（创建 / 重新创建 / 跳过）、子目录更新决策（40-project_conventions/ 的更新/跳过、templates/ 的逐文件确认结果：哪些文件将被替换、哪些将被保留）、feature.json/project.json 属性补全计划以及补充检查结果，等待用户确认后继续执行
 
 ## 工作流程
 
@@ -862,8 +914,7 @@ find "$TARGET/front-demo" -type f | wc -l
 根据区域决策执行：
 
 - `.adspecs` 决策为 `skip` → 输出 `⏭ 阶段 6 跳过：.adspecs/ 已存在，保留现有内容`，但需检查以下子决策和属性补全：
-  - 如果 `templates_decision` = `"update"` → 执行 `cp -r "$PLUGIN_DIR/.adspecs/templates/"* "$TARGET/.adspecs/templates/"`，从插件根目录覆盖更新 `templates/` 下的模板文件，输出：`🔄 阶段 6 补充更新：.adspecs/templates/ 已从插件根目录更新`
-  - 如果 `templates_decision` = `"skip"` → 不做额外处理
+  - 根据 `templates_decision` 逐文件映射执行模板更新（见下方"模板逐文件更新执行逻辑"）
   - 执行 **feature.json 与 project.json 属性补全检查**（见下方）
   - 处理完子决策和属性补全后进入阶段 7
 - `.adspecs` 决策为 `recreate` → 先备份已存在的 `feature.json` 和 `project.json`，然后执行 `rm -rf "$TARGET/.adspecs"`，按下方步骤完整重建，最后恢复备份文件并执行属性补全检查（见下方"feature.json 与 project.json 属性补全"）
@@ -967,13 +1018,33 @@ find "$TARGET/.adspecs" -type f | wc -l
 - 无缺失时：`✅ 阶段 6：feature.json 属性完整，无需补全`
 - 文件不存在时：`✅ 阶段 6：feature.json 已从 references 创建`
 
+#### 模板逐文件更新执行逻辑
+
+当 `.adspecs` 决策为 `skip` 且 `templates_decision` 映射不为空时，按以下方式执行模板文件的逐文件更新：
+
+1. **新增文件**：对于存在于 `$PLUGIN_DIR/.adspecs/templates/` 但不存在于 `$TARGET/.adspecs/templates/` 的文件，直接复制到目标目录
+2. **已有文件逐一处理**：对于 `templates_decision` 映射中的每个文件：
+   - `"replace"` → 执行 `cp "$PLUGIN_DIR/.adspecs/templates/{文件名}" "$TARGET/.adspecs/templates/{文件名}"`，用最新版本覆盖
+   - `"keep"` → 保留目标目录中的现有文件，不做任何操作
+3. **仅复制已标记为 replace 的文件**，不要使用通配符一次性覆盖整个 templates 目录
+
+```bash
+# 示例：逐文件复制被标记为 replace 的模板
+for file in "${REPLACE_FILES[@]}"; do
+  cp "$PLUGIN_DIR/.adspecs/templates/$file" "$TARGET/.adspecs/templates/$file"
+done
+
+# 统计实际更新的模板文件数量
+echo "更新了 ${#REPLACE_FILES[@]} 个模板文件，保留了 ${#KEEP_FILES[@]} 个模板文件"
+```
+
 完成后输出：
 
 - 新建时：`✅ 阶段 6 完成：.adspecs/ 配置与脚本目录已复制（{N} 个文件）`
 - 重建时：`🔄 阶段 6 完成：.adspecs/ 已重新复制（{N} 个文件）`
 - 重建且有文件恢复时：`🔄 阶段 6 完成：.adspecs/ 已重新复制 + 🔧 feature.json/project.json 已恢复并补全属性`
 - 跳过时：`⏭ 阶段 6 跳过：.adspecs/ 已存在，保留现有内容`
-- 跳过但更新模板时：`⏭ 阶段 6 跳过：.adspecs/ 已存在 + 🔄 templates/ 已从插件根目录更新`
+- 跳过但部分更新模板时：`⏭ 阶段 6 跳过：.adspecs/ 已存在 + 🔄 templates/ 已部分更新（{N} 个文件替换，{M} 个文件保留）`
 - 跳过但属性补全时：`⏭ 阶段 6 跳过：.adspecs/ 已存在 + 🔧 feature.json/project.json 已补全缺失属性`
 
 ---
@@ -1101,7 +1172,7 @@ mkdir -p "$TARGET/.adspecs"
 | 区域                      | 状态                              | 说明                                                                       |
 | ------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
 | .adspecs/                 | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 插件配置、脚本、模板（extensions.yml、feature.json、templates/、scripts/） |
-| └ templates/              | 🔄 已更新 / ⏭ 已跳过             | .adspecs/ 跳过时，模板子目录的更新决策                                     |
+| └ templates/              | 🔄 部分更新 / ⏭ 全部跳过         | .adspecs/ 跳过时，逐文件确认结果（{N} 个替换，{M} 个保留）                 |
 | └ feature.json            | 🔧 已补全 / ✅ 已完整 / ✅ 已创建 | 属性补全检查（已有属性保留，缺失属性补充）                                 |
 | docs/                     | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 11 个骨架目录，40 仅创建空目录                                             |
 | └ 40-project_conventions/ | 🔄 已更新 / ⏭ 已跳过             | docs/ 跳过时，40 子目录的更新决策                                          |
@@ -1114,7 +1185,7 @@ mkdir -p "$TARGET/.adspecs"
 | 区域                      | 状态                              | 说明                                                                       |
 | ------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
 | .adspecs/                 | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 插件配置、脚本、模板（extensions.yml、feature.json、templates/、scripts/） |
-| └ templates/              | 🔄 已更新 / ⏭ 已跳过             | .adspecs/ 跳过时，模板子目录的更新决策                                     |
+| └ templates/              | 🔄 部分更新 / ⏭ 全部跳过         | .adspecs/ 跳过时，逐文件确认结果（{N} 个替换，{M} 个保留）                 |
 | └ feature.json            | 🔧 已补全 / ✅ 已完整 / ✅ 已创建 | 属性补全检查（已有属性保留，缺失属性补充）                                 |
 | docs/                     | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 11 个骨架目录 + 40 从 references 复制                                      |
 | └ 40-project_conventions/ | 🔄 已更新 / ⏭ 已跳过             | docs/ 跳过时，40 子目录的更新决策                                          |
@@ -1128,7 +1199,7 @@ mkdir -p "$TARGET/.adspecs"
 | 区域                      | 状态                              | 说明                                                                       |
 | ------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
 | .adspecs/                 | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 插件配置、脚本、模板（extensions.yml、feature.json、templates/、scripts/） |
-| └ templates/              | 🔄 已更新 / ⏭ 已跳过             | .adspecs/ 跳过时，模板子目录的更新决策                                     |
+| └ templates/              | 🔄 部分更新 / ⏭ 全部跳过         | .adspecs/ 跳过时，逐文件确认结果（{N} 个替换，{M} 个保留）                 |
 | └ feature.json            | 🔧 已补全 / ✅ 已完整 / ✅ 已创建 | 属性补全检查（已有属性保留，缺失属性补充）                                 |
 | docs/                     | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 11 个骨架目录 + 40 从 references 复制                                      |
 | └ 40-project_conventions/ | 🔄 已更新 / ⏭ 已跳过             | docs/ 跳过时，40 子目录的更新决策                                          |
@@ -1144,7 +1215,7 @@ mkdir -p "$TARGET/.adspecs"
 | 区域                      | 状态                              | 说明                                                                       |
 | ------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
 | .adspecs/                 | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 插件配置、脚本、模板（extensions.yml、feature.json、templates/、scripts/） |
-| └ templates/              | 🔄 已更新 / ⏭ 已跳过             | .adspecs/ 跳过时，模板子目录的更新决策                                     |
+| └ templates/              | 🔄 部分更新 / ⏭ 全部跳过         | .adspecs/ 跳过时，逐文件确认结果（{N} 个替换，{M} 个保留）                 |
 | └ feature.json            | 🔧 已补全 / ✅ 已完整 / ✅ 已创建 | 属性补全检查（已有属性保留，缺失属性补充）                                 |
 | docs/                     | ✅ 已创建 / 🔄 已重建 / ⏭ 已跳过 | 11 个骨架目录 + 40 按 Python+React 技术栈复制前后端规范                    |
 | └ 40-project_conventions/ | 🔄 已更新 / ⏭ 已跳过             | docs/ 跳过时，40 子目录的更新决策                                          |
@@ -1159,7 +1230,7 @@ mkdir -p "$TARGET/.adspecs"
 
 - ✅ 已创建：目录原本不存在，新建完成
 - 🔄 已重建：目录原本存在，按用户选择删除后重新创建
-- 🔄 已更新：父目录跳过，但子目录按用户选择使用 references 最新文件覆盖更新
+- 🔄 已更新：父目录跳过，但子目录按用户选择使用 references 最新文件覆盖更新（templates/ 支持逐文件确认，部分文件可替换、部分保留）
 - 🔧 已补全：已有文件属性与 references 对比后，补充缺失属性（已有属性不覆盖）
 - ⏭ 已跳过：目录原本存在，按用户选择保留未动
 
@@ -1278,7 +1349,7 @@ mkdir -p "$TARGET/.adspecs"
 - [ ] service/ 目录已创建/重建/跳过（仅完整/轻量模式）
 - [ ] front-demo/ 已从 references 按技术栈选择复制/重建/跳过（经典/完整/轻量模式，排除 node_modules、.git、.vite）
 - [ ] .adspecs/ 配置与脚本目录已从插件根目录完整复制/重建/跳过
-- [ ] .adspecs/templates/ 子目录更新检查已完成（.adspecs/ 跳过且模板目录已包含文件时，已通过 AskUserQuestion 获取更新/跳过决策并按决策执行）
+- [ ] .adspecs/templates/ 子目录逐文件更新检查已完成（.adspecs/ 跳过且模板目录已包含文件时，已通过 AskUserQuestion 逐文件确认替换/保留决策并按决策执行）
 - [ ] feature.json 属性补全检查已完成（recreate/skip 时，已对比 references 初始版本并补全缺失属性，已有属性不覆盖）
 - [ ] project.json 属性补全检查已完成（recreate/skip 时，已对比 references 初始版本并补全缺失属性）
 - [ ] .adspecs/project.json 项目元数据文件已生成或更新