feat: 平台识别规则+空项目处理+UI对比度修复+代码先行零章

Author: zcj220

AGENTS.md

@@ -5,6 +5,46 @@
 
 ---
 
+## 零、平台识别规则（写蓝本前必须先确定 platform）
+
+**在 platform 确定之前，禁止生成任何蓝本内容。** 错误的 platform 会导致规则、选择器、动作全部用错，整个蓝本无法运行。
+
+### 识别顺序（按优先级从高到低）
+
+1. **检查已有蓝本** — 读 `testpilot/*.json`，看 `platform` 字段；**但必须与代码特征核对（见下表）**，若明显矛盾则以代码为准并纠正
+2. **检查代码文件特征**（唯一客观依据）：
+
+| 文件/特征 | platform |
+|-----------|----------|
+| `pubspec.yaml` / `AndroidManifest.xml` / `*.kt` / `*.java` | `android` |
+| `*.xcodeproj` / `*.swift` / `Info.plist` | `ios` |
+| `app.json` + `pages/` 目录（小程序结构） | `miniprogram` |
+| `*.xaml` / `*.wxs` / `tkinter` / `pywinauto` / Electron + `BrowserWindow` | `desktop` |
+| `package.json` + `*.html` / React / Vue / Angular / 纯HTML | `web` |
+
+3. **读 `testpilot/CHANGELOG.md`**（如存在）— 里面可能已注明平台
+4. **以上都无法确定 → 停下来，明确问用户**：「这个项目是 Web / Android / iOS / 小程序 / 桌面应用 中的哪一种？」
+
+### 发现平台写错了，如何纠正
+
+- 发现已有蓝本的 `platform` 与代码特征矛盾 → **立即停止**，告知用户「检测到蓝本 platform 字段为 xxx，但项目代码特征显示应为 yyy，已自动修正」
+- 修正步骤：① 更新所有蓝本的 `platform` 字段 ② 重读正确平台规则文件 ③ 检查选择器/动作是否需要同步修改
+- **不要沉默地继续写错误的蓝本**
+
+### 空项目或无法判断时的处理规则
+
+1. **项目完全为空**（无任何源码文件）→ **不写蓝本，静默等待**。空项目没有可测功能，无需操作，也不要打扰用户。
+2. **代码特征模糊**（如只有 README、配置文件，看不出平台）→ 同上，继续等待直到出现明确的代码文件。
+3. **用户描述与代码矛盾** → 以代码为准。用户说"这是 Android 项目"但目录里只有 `index.html` → 判断为 web，告知用户。
+
+**已生成错误蓝本后如何纠正：**
+1. 你发现代码特征与蓝本 `platform` 矛盾（如蓝本写 `"platform": "web"` 但项目有 `AndroidManifest.xml`）
+2. **主动告知用户**：「检测到蓝本 platform=web，但项目代码显示应为 android，正在自动修正」
+3. 自动执行：修改所有蓝本的 `platform` 字段 → 重读 `.testpilot/platforms/android.md` → 检查所有选择器和动作是否符合 android 规范 → 修正不符规范的部分
+4. **不需要等用户确认，直接修正并告知结果**
+
+---
+
 ## 一、蓝本自动生成（最重要）
 
 当项目中**不存在** `testpilot.json` 或 `testpilot/` 目录时，你在完成功能开发后**必须**自动生成蓝本文件。

extension/src/rulesInjector.ts

@@ -81,7 +81,7 @@ function detectAllIDEs(): string[] {
  * 模板版本号。每次更新模板内容时递增。
  * rulesInjector 会检测已注入文件的版本号，低于此版本则自动更新。
  */
-const TEMPLATE_VERSION = 2;
+const TEMPLATE_VERSION = 5;
 
 /** 从文件内容中提取版本号，找不到返回 0（旧版无版本标记） */
 function extractVersion(content: string): number {
@@ -115,6 +115,41 @@ function getTemplateContent(): string {
 
 ---
 
+## 零（前）、平台识别规则（写蓝本前必须先确定 platform）
+
+**在 platform 确定之前，禁止生成任何蓝本内容。**
+
+### 识别顺序（按优先级）
+
+1. **检查代码文件特征**（唯一客观依据）：
+
+| 文件/特征 | platform |
+|-----------|----------|
+| \`pubspec.yaml\` / \`AndroidManifest.xml\` / \`*.kt\` / \`*.java\` | \`android\` |
+| \`*.xcodeproj\` / \`*.swift\` / \`Info.plist\` | \`ios\` |
+| \`app.json\` + \`pages/\` 目录（小程序结构） | \`miniprogram\` |
+| \`*.xaml\` / \`tkinter\` / \`pywinauto\` / Electron + \`BrowserWindow\` | \`desktop\` |
+| \`package.json\` + \`*.html\` / React / Vue / Angular | \`web\` |
+
+2. **检查已有蓝本的 platform 字段** — 但必须与代码特征核对，若矛盾以代码为准
+3. **读 \`testpilot/CHANGELOG.md\`**（如存在）— 里面可能已注明平台
+4. **以上都无法确定 → 停下来问用户**：「这是 Web / Android / iOS / 小程序 / 桌面 中的哪种？」
+
+### 空项目或无法判断时的处理规则
+
+- **项目完全为空**（无源码）→ **不写蓝本，静默等待**，不要打扰用户
+- **代码特征模糊** → 同上，等待出现明确代码文件
+- **用户描述与代码矛盾** → 以代码为准，告知用户
+
+### 发现平台写错时如何纠正
+
+1. 发现代码特征与蓝本 \`platform\` 矛盾（如蓝本写 \`"web"\` 但项目有 \`AndroidManifest.xml\`）
+2. **主动告知**：「检测到蓝本 platform=web，但项目代码显示应为 android，正在自动修正」
+3. 自动执行：更新所有蓝本 \`platform\` → 重读 \`.testpilot/platforms/android.md\` → 修正不符规范的选择器和动作
+4. **不需要等用户确认，直接修正并告知结果**
+
+---
+
 ## 零、蓝本语言规则
 
 蓝本中的 \`name\`、\`description\`、\`expected\`、\`app_name\` 等文字内容**必须使用用户项目的语言**：

extension/src/sidebarProvider.ts

@@ -523,6 +523,36 @@ export class SidebarProvider implements vscode.WebviewViewProvider {
   }
 
   private async _handleCopyBlueprintPrompt(platform: string, projectDir: string = ""): Promise<void> {
+    const platformNames: Record<string, string> = {
+      web: "Web",
+      miniprogram: "微信小程序",
+      android: "Android/Flutter",
+      desktop: "Windows桌面",
+      ios: "iOS/SwiftUI",
+    };
+    const pName = platformNames[platform] || "Web";
+
+    const lines: string[] = [];
+    if (projectDir) {
+      lines.push(`当前项目路径：${projectDir.replace(/\\/g, "/")}`);
+      lines.push(`请直接读取该目录下的源代码生成蓝本，无需再次询问项目路径。`);
+      lines.push(``);
+    }
+    lines.push(`请为当前【${pName}】项目生成测试蓝本。`);
+    lines.push(``);
+    lines.push(`⚠️ 生成前请先按顺序完成以下步骤（缺一不可）：`);
+    lines.push(`1. 阅读 AGENTS.md（蓝本通用规则）`);
+    lines.push(`2. 阅读 .testpilot/platforms/${platform}.md（${pName}平台专属规则、选择器规范和完整模板）`);
+    lines.push(`3. 通读项目源代码，确认已实现的功能列表`);
+    lines.push(`4. 按规则要求生成完整蓝本，保存到 testpilot/ 目录`);
+
+    const prompt = lines.join("\n");
+    await vscode.env.clipboard.writeText(prompt);
+    vscode.window.showInformationMessage(`✅ ${pName}蓝本提示词已复制！请粘贴给编程AI，它会先读规则文件再生成蓝本。`);
+  }
+
+  // ── 以下为旧版长提示词备份（已废弃，改用短口令模式） ──
+  private async _handleCopyBlueprintPrompt_LEGACY(platform: string, projectDir: string = ""): Promise<void> {
     const commonRules = `══════ 测试设计黄金规则（必须严格遵守） ══════
 
 【铁律0：每个项目必须有独立蓝本】
@@ -1119,18 +1149,19 @@ ${commonRules}`;
   <title>TestPilot AI</title>
   <style>
     :root {
-      --bg: var(--vscode-sideBar-background);
-      --fg: var(--vscode-sideBar-foreground);
-      --input-bg: var(--vscode-input-background);
-      --input-border: var(--vscode-input-border);
-      --input-fg: var(--vscode-input-foreground);
-      --btn-bg: var(--vscode-button-background);
-      --btn-fg: var(--vscode-button-foreground);
-      --btn-hover: var(--vscode-button-hoverBackground);
+      --bg: var(--vscode-sideBar-background, #1e1e1e);
+      --fg: var(--vscode-sideBar-foreground, #cccccc);
+      --input-bg: var(--vscode-input-background, #3c3c3c);
+      --input-border: var(--vscode-input-border, rgba(255,255,255,0.35));
+      --input-fg: var(--vscode-input-foreground, #cccccc);
+      --btn-bg: var(--vscode-button-background, #0e639c);
+      --btn-fg: var(--vscode-button-foreground, #ffffff);
+      --btn-hover: var(--vscode-button-hoverBackground, #1177bb);
+      --muted: var(--vscode-descriptionForeground, rgba(204,204,204,0.55));
       --success: #4ec9b0;
       --error: #f44747;
       --warn: #cca700;
-      --info: var(--vscode-descriptionForeground);
+      --info: var(--vscode-descriptionForeground, #9d9d9d);
     }
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body { font-family: var(--vscode-font-family); font-size: 13px; color: var(--fg); padding: 12px; }
@@ -1155,11 +1186,12 @@ ${commonRules}`;
     button {
       width: 100%; padding: 7px; margin-top: 8px; font-size: 13px; font-weight: 600;
       background: var(--btn-bg); color: var(--btn-fg);
-      border: none; border-radius: 3px; cursor: pointer;
+      border: 1px solid rgba(255,255,255,0.55); border-radius: 3px; cursor: pointer;
     }
-    button:hover { background: var(--btn-hover); }
+    button:hover { background: var(--btn-hover); border-color: rgba(255,255,255,0.85); }
     button:disabled { opacity: 0.5; cursor: not-allowed; }
-    .btn-secondary { background: transparent; border: 1px solid var(--input-border); color: var(--fg); }
+    .btn-secondary { background: rgba(255,255,255,0.08); border: 1px solid rgba(255,255,255,0.6); color: var(--fg); }
+    .btn-secondary:hover { background: rgba(255,255,255,0.15); border-color: rgba(255,255,255,0.85); }
     .btn-row { display: flex; gap: 6px; margin-top: 8px; }
     .btn-row button { flex: 1; margin-top: 0; }
     .btn-danger { background: var(--error); }

extension/templates/platforms/android.md

@@ -1,4 +1,4 @@
-<!-- TestPilot-Template-Version: 2 -->
+<!-- TestPilot-Template-Version: 3 -->
 # Android/Flutter 平台蓝本规则（platform = "android"）
 
 > 本文件定义 Android 原生应用和 Flutter 应用蓝本的完整规则。
@@ -7,6 +7,24 @@
 
 ---
 
+## 零、生成蓝本前必须先通读源代码（强制执行）
+
+**蓝本的唯一依据是代码，不是猜测，不是常识，不是用户描述。**
+
+在写任何 JSON 之前，必须按顺序完成：
+
+0. **先读 `testpilot/CHANGELOG.md`（如果存在）** — 了解当前已覆盖的功能和尚未测试的模块，避免重复写或漏写；如果不存在则跳过
+1. **读入口/路由文件** — 了解应用整体结构和页面列表（如 `main.dart`、`AndroidManifest.xml`）
+2. **读每个页面的 UI 文件** — 找出所有可操作元素（按钮、输入框、下拉框、导航项）
+3. **记录元素的真实标识** — `hint` / `label` / `contentDescription` / `tooltip`（这是选择器的唯一来源）
+4. **读业务逻辑** — 确认每个操作的真实结果（跳转哪里、显示什么文字）
+5. **确认提示方式** — 成功/失败提示是 SnackBar/Toast（瞬态，**不可断言**）还是持久化 Text（可断言）
+6. **列出已实现功能** — 代码里有什么就测什么，未实现的功能不写蓝本
+
+**禁止跳过代码阅读直接生成蓝本。凭想象写的选择器和断言几乎必然失败。**
+
+---
+
 ## 一、必填字段
 
 | 字段 | 说明 | 示例 |

extension/templates/platforms/desktop.md

@@ -1,4 +1,4 @@
-<!-- TestPilot-Template-Version: 2 -->
+<!-- TestPilot-Template-Version: 3 -->
 # Windows 桌面应用平台蓝本规则（platform = "desktop"）
 
 > 本文件定义 Windows 桌面应用（WPF/WinForms/Electron/Qt 等）蓝本的完整规则。
@@ -7,6 +7,24 @@
 
 ---
 
+## 零、生成蓝本前必须先通读源代码（强制执行）
+
+**蓝本的唯一依据是代码，不是猜测，不是常识，不是用户描述。**
+
+在写任何 JSON 之前，必须按顺序完成：
+
+0. **先读 `testpilot/CHANGELOG.md`（如果存在）** — 了解当前已覆盖的功能和尚未测试的模块，避免重复写或漏写；如果不存在则跳过
+1. **读主窗口/入口文件** — 了解应用结构（如 `MainWindow.xaml`、`main.py`、`app.py`）
+2. **读每个窗口的 UI 文件** — 找出所有控件，记录真实的 `Name`、`AutomationId`、`Content` 属性
+3. **记录元素的真实标识** — `automationid:xxx` 或 `name:控件显示文字`（选择器的唯一来源）
+4. **读事件处理逻辑** — 确认每个按钮点击的真实结果（弹出什么窗口、显示什么文字）
+5. **确认提示方式** — 成功/失败提示是 `MessageBox`（阻塞弹窗，需 click 关闭）还是标签文字（可断言）
+6. **列出已实现功能** — 代码里有什么就测什么，未实现的功能不写蓝本
+
+**禁止跳过代码阅读直接生成蓝本。凭想象写的选择器和断言几乎必然失败。**
+
+---
+
 ## 一、必填字段
 
 | 字段 | 说明 | 示例 |

extension/templates/platforms/ios.md

@@ -1,4 +1,4 @@
-<!-- TestPilot-Template-Version: 2 -->
+<!-- TestPilot-Template-Version: 3 -->
 # iOS/SwiftUI 平台蓝本规则（platform = "ios"）
 
 > 本文件定义 iOS 原生应用和 SwiftUI 应用蓝本的完整规则。
@@ -7,6 +7,24 @@
 
 ---
 
+## 零、生成蓝本前必须先通读源代码（强制执行）
+
+**蓝本的唯一依据是代码，不是猜测，不是常识，不是用户描述。**
+
+在写任何 JSON 之前，必须按顺序完成：
+
+0. **先读 `testpilot/CHANGELOG.md`（如果存在）** — 了解当前已覆盖的功能和尚未测试的模块，避免重复写或漏写；如果不存在则跳过
+1. **读入口/路由文件** — 了解应用整体结构和页面列表（如 `ContentView.swift`、`@main App`）
+2. **读每个页面的 UI 文件** — 找出所有可操作元素（Button、TextField、NavigationLink 等）
+3. **记录 accessibilityIdentifier** — `.accessibilityIdentifier("xxx")` 是选择器的唯一来源，没有则无法定位
+4. **读业务逻辑** — 确认每个操作的真实结果（跳转哪里、显示什么文字）
+5. **确认提示方式** — 成功/失败提示是 `.alert()`（瞬态，**不可断言**）还是持久化 `Text`（可断言）
+6. **列出已实现功能** — 代码里有什么就测什么，未实现的功能不写蓝本
+
+**禁止跳过代码阅读直接生成蓝本。凭想象写的选择器和断言几乎必然失败。**
+
+---
+
 ## 一、必填字段
 
 | 字段 | 说明 | 示例 |

extension/templates/platforms/miniprogram.md

@@ -1,4 +1,4 @@
-<!-- TestPilot-Template-Version: 2 -->
+<!-- TestPilot-Template-Version: 3 -->
 # 微信小程序平台蓝本规则（platform = "miniprogram"）
 
 > 本文件定义微信小程序蓝本的完整规则。
@@ -7,6 +7,23 @@
 
 ---
 
+## 零、生成蓝本前必须先通读源代码（强制执行）
+
+**蓝本的唯一依据是代码，不是猜测，不是常识，不是用户描述。**
+
+在写任何 JSON 之前，必须按顺序完成：
+
+0. **先读 `testpilot/CHANGELOG.md`（如果存在）** — 了解当前已覆盖的功能和尚未测试的模块，避免重复写或漏写；如果不存在则跳过
+1. **读 `app.json`** — 了解所有页面路由和 TabBar 配置
+2. **读每个页面的 `.wxml` 文件** — 找出所有可操作元素，记录真实的 `class`、`placeholder`、`bindtap` 属性
+3. **读对应的 `.js` 文件** — 确认每个操作的真实结果（跳转哪里、显示什么文字）
+4. **确认提示方式** — 成功/失败提示是 `wx.showToast()`（瞬态，**不可断言**）还是页面内文字节点（可断言）
+5. **列出已实现功能** — 代码里有什么就测什么，未实现的功能不写蓝本
+
+**禁止跳过代码阅读直接生成蓝本。凭想象写的选择器和断言几乎必然失败。**
+
+---
+
 ## 一、必填字段
 
 | 字段 | 说明 | 示例 |

extension/templates/platforms/web.md

@@ -1,11 +1,29 @@
-<!-- TestPilot-Template-Version: 2 -->
+<!-- TestPilot-Template-Version: 3 -->
 # Web 平台蓝本规则（platform = "web"）
 
 > 本文件定义 Web 应用（React/Vue/Angular/纯HTML）蓝本的完整规则。
 > 生成蓝本前**必须**通读本文件，不得跳过任何章节。
 
 ---
 
+## 零、生成蓝本前必须先通读源代码（强制执行）
+
+**蓝本的唯一依据是代码，不是猜测，不是常识，不是用户描述。**
+
+在写任何 JSON 之前，必须按顺序完成：
+
+0. **先读 `testpilot/CHANGELOG.md`（如果存在）** — 了解当前已覆盖的功能和尚未测试的模块，避免重复写或漏写；如果不存在则跳过
+1. **读入口/路由文件** — 了解页面结构和路由配置（如 `App.js`、`router/index.js`、`index.html`）
+2. **读每个页面的模板/HTML** — 找出所有可操作元素，记录真实的 `id`、`class`、`name` 属性
+3. **记录元素的真实选择器** — 只用代码中实际存在的 `#id` 或稳定 `.class`，禁止猜测
+4. **读业务逻辑** — 确认每个操作的真实结果（跳转哪里、显示什么文字、调用什么 API）
+5. **确认提示方式** — 成功/失败提示是短暂 Toast（不可断言）还是持久化 DOM 元素（可断言）
+6. **列出已实现功能** — 代码里有什么就测什么，未实现的功能不写蓝本
+
+**禁止跳过代码阅读直接生成蓝本。凭想象写的选择器和断言几乎必然失败。**
+
+---
+
 ## 一、必填字段
 
 | 字段 | 说明 | 示例 |