@runweave/server-linux-x64 0.1.7 → 0.1.9

package/payload/plugins/toolkit/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,138 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test("login flow", async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto("https://example.com/login");
+  await page.getByRole("textbox", { name: "Email" }).fill("user@example.com");
+  await page.getByRole("textbox", { name: "Password" }).fill("password123");
+  await page.getByRole("button", { name: "Sign In" }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole("button", { name: "Submit" }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator("#submit-btn").click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:
+
+- `toBeVisible()` — element is rendered and visible
+- `toHaveText(text)` — element text content matches
+- `toHaveValue(value) / toBeEmpty()` — input/select value matches
+- `toBeChecked() / toBeUnchecked()` — checkbox state matches
+- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot
+
+Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.
+
+When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.
+
+Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.
+
+```bash
+# Get a stable locator for an element ref to use in the assertion
+playwright-cli --raw generate-locator e5
+# getByRole('button', { name: 'Submit' })
+
+# Capture expected text content for toHaveText
+playwright-cli --raw eval "el => el.textContent" e5
+
+# Capture expected input value for toHaveValue/toBeEmpty
+playwright-cli --raw eval "el => el.value" e5
+
+# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked
+# (whole page, or use a ref to scope to a region)
+playwright-cli --raw snapshot
+playwright-cli --raw snapshot e5
+```
+
+```typescript
+// Generated action
+await page.getByRole("button", { name: "Submit" }).click();
+
+// Manual assertions using the outputs above:
+await expect(page.getByRole("alert", { name: "Success" })).toBeVisible();
+await expect(page.getByTestId("main-header")).toHaveText("Welcome, user");
+await expect(page.getByRole("textbox", { name: "Email" })).toHaveValue(
+  "user@example.com",
+);
+await expect(
+  page.getByRole("checkbox", { name: "Enable notifications" }),
+).toBeChecked();
+
+// toMatchAriaSnapshot on the whole page, finds a matching region
+await expect(page).toMatchAriaSnapshot(`
+  - heading "Welcome, user"
+  - link /\\d+ new messages?/
+  - button "Sign out"
+`);
+
+// toMatchAriaSnapshot scoped to a region
+await expect(page.getByRole("navigation")).toMatchAriaSnapshot(`
+  - link "Home"
+  - link /\\d+ new messages?/
+  - link "Profile"
+`);
+```

package/payload/plugins/toolkit/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,142 @@
+# 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/payload/plugins/toolkit/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,157 @@
+# 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/payload/plugins/toolkit/skills/playwright-cli/templates/standalone.config.json

@@ -0,0 +1,7 @@
+{
+  "browser": {
+    "cdpEndpoint": null,
+    "remoteEndpoint": null,
+    "isolated": true
+  }
+}

package/payload/plugins/toolkit/skills/product-exploration/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: product-exploration
+description: "仅在用户明确调用本技能或要求围绕指定功能、用户目标做探索式产品体检时使用。通过真实操作发现缺陷和体验问题，提供复现证据与建议；不用于日常改代码后的自动验收、固定用例执行或测试代码生成。"
+---
+
+# 产品探索
+
+围绕用户指定目标发现值得处理的问题，不建立回归测试资产。终点是有证据的报告，修复另行确认。
+
+## 启动与范围
+
+- 只在用户明确要求本轮探索时执行。修改代码、提交、PR 或普通“修复这个 bug”不构成探索授权，不接自动触发 Hook。
+- 用户只需提供功能或用户目标，例如“检查文件搜索体验”。先从任务上下文、必要代码和项目入口理解预期；不要求填写表格、编写 YAML 或提供测试步骤。
+- 简短确认本轮目标、环境、数据权限和预算。已有上下文明确的内容不重复提问；目标或资源归属不清时，先问一个关键问题。
+- 自主选择相关路径，不全仓扫描、不扩大到无关功能。偶遇范围外问题可简记为待确认，不展开调查。
+
+## 环境与权限
+
+- 浏览器探索使用同插件的 [playwright-cli](../playwright-cli/SKILL.md)，先读取其完整指令并遵循页面、Profile、附着和 detach 规则。工具不可用时报告阻塞，不拿静态阅读代替真实操作。
+- 可复用已确认身份的真实环境。需要操作 Runweave Dev Session 时，先读取并使用 [runweave-dev-session](../runweave-dev-session/SKILL.md)；不得按旧端口、窗口外观或 ambient endpoint 猜目标，不默认升级为完整打包。
+- 只做必要的环境准备，不趁机修基础设施、安装整套 Test Agents 或扩充工具权限。没有新的诊断线索时，不反复重试同一个准备失败。
+- 真实数据默认只读。写操作只作用于可证明属于本轮的临时数据；更改真实数据或账号配置、发布提交内容、发送消息等外部动作，须单独说明对象和影响并取得授权。
+- 写操作归属或副作用不确定时，先停下该路径请求确认，或继续独立的只读路径。不得为了复现重复制造有风险的副作用。
+- 探索权限不包含修改产品源码、自动修复、提交 issue/PR、推送代码或调整现有测试预期。
+
+## 时间与探索策略
+
+默认探索上限 **30 分钟**，用户可覆盖或追加。环境准备时间单独记录，不计入探索预算。
+
+页面可操作、开始探索时读取时钟，记录开始时间和截止时间；进入新分支或长耗时操作前检查剩余时间。合理限制单次等待，不依靠固定 sleep 推进。到期后不展开新路径，在安全点结束操作并完成报告、清理；说明实际耗时和超时部分。Skill 不是计时器或安全沙箱，不能保证强制中断工具，也不替代宿主权限控制。
+
+优先顺序由用户目标和现场观察决定：
+
+- 先走一条核心用户路径，确认用户是否能完成目标。
+- 根据暴露的状态转换和风险，选择相关的空数据、边界输入、取消返回、重复操作、错误恢复等分支。不是固定清单，不必逐项执行。
+- 异常出现后收窄复现步骤，区分用户可见失败、预期不明确与工具/环境问题；只读查看必要代码、控制台或网络证据帮助解释，不修产品。
+- 等待可观察的业务状态，优先语义定位和可重试断言；不用强制点击、mock 或 DOM 状态注入把失败路径改成成功。确需模拟环境条件时，限定自有环境并明确证据限制。
+- 一条路径失败不要求停止整轮；可以继续独立且在范围内的路径。预算耗尽、没有高价值新路径或无法安全继续时结束，不为凑数量或用满时间继续消耗。
+
+可使用内存中的自动化片段或本轮临时脚本帮助操作和取证；不生成持久化测试代码、`*.spec.*` / `*.test.*`、YAML 测试计划或 CI 配置，不把临时动作包装成需要维护的测试套件。执行固定验收合同是另一项任务，不自动转入 `run-test-cases`。
+
+## 结论与证据
+
+将观察分开报告：
+
+- **已确认缺陷**：通过真实操作发现并安全复核至少一次；有明确预期依据、实际差异和用户影响。附最短复现步骤、复核结果、必要证据及建议。
+- **待确认疑点**：未复现、不可安全复核、预期不明确或仅有代码推测。说明还缺什么证据，不给出确定的缺陷结论。
+- **体验建议**：说明如何妨碍用户完成目标及建议理由，不把个人审美偏好作为功能错误。
+
+取证前缩小范围，优先裁剪或遮罩无关真实数据；不落盘或输出凭证、Cookie、Token、完整敏感响应、无关个人信息。可读取不等于可导出或发送。无法安全保留证据时只描述现象，并标注证据限制；不默认上传外部平台。
+
+交付简短中文结论和本地报告，默认保存在 `artifacts/product-exploration/<本轮唯一标识>/`，只留报告和必要证据，不留需要维护的执行代码。报告按实际发现组织，不强制每类有内容，包含：
+
+- 本轮目标、实际环境、数据权限、准备与探索耗时；覆盖了什么、哪些未覆盖及原因。
+- 按用户影响排列的缺陷、疑点和建议，各自附对应证据或证据限制。
+- 清理结果、仍需授权或后续确认的事项。
+
+没有发现问题就如实报告；未覆盖不等于通过，不宣称完整验收或产品“没有 bug”。最终报告后停止探索，等待用户决定是否修复或继续。
+
+## 收尾
+
+关闭本轮自建终端、删除本轮临时数据和执行文件，仅操作已核实归属的资源；停止本轮创建的 Dev Session 并 detach。已有用户会话、真实目录、账号配置与 Cookie 保持原状，不为“隔离”或“清理”而重置它们。
+
+失败、中断或预算耗尽时也应尝试安全清理；无法清理则明确列出遗留资源和原因，不声称已清理完成。报告和经过最小化处理的证据可以保留。

package/payload/plugins/toolkit/skills/product-exploration/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  default_prompt: "使用 $toolkit:product-exploration，围绕我指定的功能或用户目标做一轮最多 30 分钟的真实探索，只取证报告，不自动修复。"
+
+policy:
+  allow_implicit_invocation: false

package/payload/plugins/toolkit/skills/prototype-first-development/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: prototype-first-development
+description: 创建和调整可运行的产品 UI 原型。仅当用户明确提到“HTML”或“原型”，或显式调用本技能时使用。
+---
+
+# 原型先行开发
+
+使用这个技能，在产品实现前先把交互意图落成具体可看的东西。产物是一个小型可运行原型，不是生产代码，也不能证明后端、协议或运行时能力已经存在。
+
+这个技能不是“生成一个 HTML 模板”就结束，而是一套从需求到原型、从原型到计划、从计划到实现的开发方式。除非用户明确要求跳过，否则不要压缩或改写这条路径。
+
+## 核心规则
+
+当用户还在收敛行为、布局、状态或工作流时，先创建本地、可读、无需构建的原型。原型稳定后，再更新实施计划；只有用户明确推进实现时，才修改产品代码。
+
+原型的用户可见界面必须按最终产品方案绘制：除技术实现方式和数据来源外，UI、文案、交互入口、状态反馈都应与计划落地后的产品一致。不要在产品画面里加入解释性文案、操作指引、快捷键说明、需求备注、标注、教学卡片或为了让人理解原型而临时增加的按钮。
+
+如果确实需要用于演示的状态切换、mock 触发器或备注说明，必须放在 README，或放在默认隐藏、视觉上与产品画面隔离的 prototype helper 区域，并明确标记为不进入实施计划。任何 agent 都不能从这类辅助内容反推最终产品 UI。
+
+## 默认产物
+
+优先使用这个结构：
+
+```text
+docs/prototypes/<feature-slug>/
+  README.md
+  index.html
+  app.js
+  mock-state.json
+  prototype-preview.png   # 可选，浏览器验证后保存
+```
+
+从零开始时，使用技能自带模板 `references/html-prototype-template/`。把它复制到目标仓库并替换占位内容，不要重新发明目录结构。
+
+需要过程检查时，读取 `references/prototype-workflow-checklist.md`。需要从原型整理实施计划时，读取 `references/implementation-plan-handoff-template.md`，并优先结合 `$toolkit:write-plan` 落盘计划。
+
+## 工作流
+
+1. 原型简报：
+   - 用户目标
+   - 用户动作
+   - 主要流程
+   - 关键状态
+   - 明确的非目标
+   - 原型要影响的真实产品界面或模块
+
+2. 可运行原型：
+   - 默认保持静态、无需构建，除非仓库已经有更强的约定
+   - 首屏只呈现最终产品会出现的界面，不放需求解释、操作教程或设计备注
+   - 仅使用最终产品需要的用户操作入口；不要为了演示方便额外加“下一步”“切状态”“模拟事件”等可见控件
+   - 把布局和挂载点放在 `index.html`
+   - 把状态流转和事件处理放在 `app.js`
+   - 把领域对象、模拟事件和样例记录放在 `mock-state.json`
+   - 除非用户明确要求代码与原型对齐，否则不要导入产品源码
+
+3. 调整循环：
+   - 优先保证可读性，不追求炫技
+   - 组件和函数命名贴近业务领域
+   - 状态流转保持容易修改
+   - 只添加最终产品会保留的交互控件
+   - 如需切换 mock 状态，优先用 URL 参数、README 步骤或默认隐藏的 helper 面板，不把它画进产品画面
+   - 用户点、改、截图、反馈时，只调整原型，不碰产品代码
+
+4. 原型冻结：
+   - 在 README 中更新启动命令、验证点、边界和非目标
+   - 浏览器验证重要时，保存 `prototype-preview.png`
+   - 在 Runweave 仓库中，浏览器页面复现、修复或验收必须使用 `$toolkit:playwright-cli` 完成打开页面、交互、截图或 DOM 检查
+   - 冻结前确保 README 记录了最后采用的交互方案和被放弃的方向
+
+5. 实施计划：
+   - 在计划中引用原型目录
+   - 区分“原型表达的意图”和“当前代码真实现状”
+   - 声称可行前，先检查产品代码
+   - 把协议、后端、运行时缺口与 UI 工作分开列出
+   - 计划必须写清产品行为、协议变化、代码落点、验收方式
+
+6. 产品实现：
+   - 实现时再回到真实代码，不从原型直接推断已有能力
+   - 产品代码修改必须以当前代码现状为准
+   - 保留原型作为交互基准，但不要照搬原型代码
+   - 验证时同时覆盖产品行为和原型中冻结的关键交互
+
+## 质量目标
+
+让生成内容像人类写的、后续能维护：
+
+- 可读：文件名清楚，函数小，状态名朴素，事件处理直观。
+- 易调：模拟数据放 JSON，样式按 UI 区域组织，不生成晦涩代码。
+- 高效：无构建步骤；除非能明显提升该原型的开发速度，否则不引入框架。
+- 真实：用户可见界面不夹带说明、备注或脚手架控件，截图应能直接作为最终产品体验的参考。
+- 诚实：README 写清楚哪些是模拟的，真实实现还缺什么。
+
+## 功能分类账
+
+原型中可能出现两类元素，必须显式分开记录：
+
+- 产品核心功能：最终需要落地到产品里的能力、状态、入口、反馈或业务规则。
+- 原型辅助功能：为了演示、切换状态、模拟数据、触发事件、方便用户理解或截图而临时加入的控件和面板。
+
+具体分类表和检查项写在原型 README 与 `references/prototype-workflow-checklist.md` 中，`SKILL.md` 只保留原则。
+
+原型辅助功能的默认处理：
+
+- 默认不要出现在用户可见产品画面里；能用 README 或 URL 参数完成的，不要做成 UI。
+- 必须与产品画面视觉隔离，并用 `data-prototype-helper="true"` 或等价标识标记。
+- 不进入实施计划的产品范围。
+- 不作为最终 UI、API、协议或数据模型的依据。
+- 如果用户希望保留到产品中，必须在原型冻结时把它改列为产品核心功能或单独写入后续需求。
+
+## 约束
+
+- 不要把原型当成产品合约已经存在的证据。
+- 不要把原型代码直接照搬进生产代码。
+- 不要模拟每个边界情况；只模拟用户需要看见或验证的关键决策。
+- 除非仓库明确要求，否则不要为原型文件新增单元测试。
+- 遵守仓库关于浏览器验证、测试层级和文档路径的要求。
+- 不要在用户还处于原型调整阶段时提前写实施计划或改产品代码。
+- 产品 UI 原型默认使用可运行 HTML；技术架构、事件流或故障因果可视化改用 `$toolkit:architecture-flow-prototyping`。
+- 不要把原型辅助功能当作默认产品需求。
+- 不要在产品画面里写“快捷键”“操作说明”“这里展示”“用于验证”“模拟状态”等说明性内容，除非这些文案本来就是最终产品 UI 的一部分。
+
+## 启动方式
+
+对于 `docs/prototypes/<feature-slug>` 下的原型：
+
+```bash
+python3 -m http.server 6188 --directory docs/prototypes/<feature-slug>
+```
+
+打开：
+
+```text
+http://127.0.0.1:6188/
+```