教程 & 最佳实践

一、研发场景实用工具推荐

本文面向实际研发场景，整理并推荐了一组可直接应用于日常开发流程的 Agent 工具——既有开箱即用的 Skill（技能），也有 MCP 服务器与 LSP 等能力。分别针对具体任务提供明确的能力边界与使用场景说明，帮助你在不同阶段选择合适的工具，提高开发效率。

CodeWave IDE 的能力主要来自内置（开箱即用，无需安装）与插件市场（在对话中输入 /plugin 打开插件市场，搜索插件名并安装）两部分，涵盖 Skill（技能）、MCP 服务器与 LSP 等。其中技能由 AI 根据任务描述自动匹配调用，也可以显式点名或用 /技能名 直接触发；MCP / LSP 安装后由 AI 按需自动调用。此外，gh / glab 这类平台 CLI 工具装好并认证后，AI 可直接驱动它们完成 PR / MR 相关操作，推荐一并配置。

1. 需求与规划

这一阶段的重点是：把模糊的想法变成清晰的规格，让后续编码有据可依。

• SDD（内置）——规格驱动开发：把模糊需求自动整理成功能规格说明（用户故事 + 验收场景），内置校验脚本统计规格完整性，并用单选衔接「技术方案（可选）→ 编码」。SDD 插件默认关闭，先在「设置 → 项目设置」启用「SDD」开关（写入项目 .wave/settings.json）。
  • 场景：新功能从想法到可执行规格的全过程。
  • 示例："把'支付模块改造'的需求写成规格说明，先 clarify 一下有哪些歧义。"
• /plan（内置）——进入计划模式：AI 只允许修改计划文件（.wave/plans/ 目录），用于协作制定和完善开发计划，不直接改动项目代码。/plan 查看当前计划，/plan <描述> 切换计划模式并立即开始规划。
  • 场景：动手写代码前先明确方案；规划阶段限制 AI 只产出计划。
  • 示例："用 /plan 先出一份支付模块迁移方案。"

2. 编码实现

进入编码阶段，以下技能帮助你设计高质量方案并落地实现。

• frontend-design（插件市场）——创建独特的、生产级的前端界面，避免千篇一律的"AI 风格"。
  • 场景：网页、着陆页、海报、React 组件等一切需要视觉设计的界面。
  • 示例："做一个分享海报"。
• typescript-lsp（插件市场）——TypeScript/JavaScript 语言服务器，提供代码补全、跳转定义、查找引用、符号搜索、类型提示与错误诊断。
  • 场景：大型 TS 项目的精准代码智能（对 IDE 内置能力的补充）。
  • 示例："用 typescript-lsp 检查这个接口的调用方有哪些，类型是否有误。"

3. 代码质量与提交

写完之后，用这一组技能把代码打磨干净并安全合入。

• gh / glab（CLI 工具）——GitHub CLI 与 GitLab CLI，分别对应 GitHub 与 GitLab / 内部 GitLab 仓库。安装并认证（gh auth login / glab auth login）后，AI 可以直接创建与查看 PR / MR、发表审查评论、查询 CI 状态，不必再手工复制粘贴链接；内置的 code-review 与插件市场的 commit-skills（提交、推送 MR/PR、等待合并）都依赖它们。
  • 场景：提交后自动开 PR / MR、按审查意见逐条回复、盯 CI 与合并状态。
  • 示例："把这次改动推上去开个 MR，并回复刚才的审查意见。"
• code-review（内置）——审查当前 diff，按力度查找正确性 bug 与简化机会，并直接给出修改建议。
  • 场景：提交前的自查、合并请求评审。
  • 示例："用 code-review 审查这次改动。"（/code-review 直接触发）
• simplify（内置）——审查并直接修复代码的复用、简化与效率问题（不找 bug）。
  • 场景：代码重复、过度设计、可读性差的清理。
  • 示例："用 simplify 优化这个模块，去掉重复逻辑。"
• commit-skills（插件市场）——简化 Git 工作流，包含 commit（提交）、commit-push-mr / commit-push-pr（提交并推送 MR/PR）、watch-merge-mr / watch-merge-pr（等待合并）5 个技能，覆盖从提交到合并的全流程。
  • 场景：规范的提交信息与自动化的 MR/PR 流程。
  • 示例："用 commit-skills 提交这次改动并推送 PR。"

4. 测试与调试

• 先诊断再修复（提示词实践）——遇到 bug 时明确要求 AI 先定位根因、给出证据，再动手改，避免盲试；新功能先用测试驱动，先写能复现的失败用例，实现后再确认转绿。
  • 场景：疑难 bug、测试失败、易回归的核心逻辑。
  • 示例："先写一个能复现这个偶发超时的测试，再修到它转绿。"
• Playwright CLI（命令行工具）——通过 Bash 直接驱动真实浏览器：页面导航、抓取可交互元素快照、点击、填充、执行脚本与断言。命令按需取数，不必把工具 schema 与整棵页面无障碍树塞进上下文，比 MCP 方案更省 token（安装：npm install -g @playwright/cli@latest）。
  • 场景：Web 应用端到端验证、抓取接口请求、复现前端问题。
  • 示例："用 playwright-cli 打开本地页面，检查登录流程的接口请求。"（详见第四部分）

5. 文档与知识沉淀

代码之外，文档质量同样决定团队效率。

• deep-wiki（插件市场）——AI 驱动的 Wiki 生成器，支持 Mermaid 图表、源码引用、入职指南与 llms.txt 生成，内置 3 个子代理（wiki-architect / wiki-researcher / wiki-writer）。
  • 场景：为新仓库快速搭建团队 Wiki、维护架构文档。
  • 示例："用 deep-wiki 为这个仓库生成一份带架构图的 Wiki。"
• document-skills（插件市场）——办公文档处理套件：docx（Word）、xlsx（Excel）、pptx（PowerPoint）、pdf，可读取、创建、编辑并支持格式转换。
  • 场景：需求文档、表格数据、汇报 PPT、PDF 解析。
  • 示例："帮我把这份 docx 转成带修订标记的版本。"
• artifact（内置）——把本地 HTML 或 Markdown 发布成可分享的网页链接，一键生成、可更新、默认私有。
  • 场景：把报告、原型、迁移计划分享给团队。
  • 示例："把这份 Markdown 做成可分享的网页。"
• init（内置）——分析代码库并生成 AGENTS.md，沉淀项目级与用户级指令，让 AI 在不同会话间保持一致。
  • 场景：新仓库起步、接手陌生项目。
  • 示例："用 init 分析这个仓库并生成 AGENTS.md。"

6. 调研与日常效率

• deep-research（内置）——深度调研：多路搜索 → 抓取来源 → 对抗性验证 → 输出带引用的报告。
  • 场景：技术选型调研、竞品分析、陌生领域学习。
  • 示例："用 deep-research 调研三种消息队列在支付场景的优劣。"
• tavily-search（插件市场）——Tavily AI 搜索引擎 MCP 服务器，为 Agent 提供实时网络搜索能力。
  • 场景：需要最新资料、文档查询、版本信息确认。
  • 示例："用 tavily-search 查一下这个 API 的最新变更。"
• loop（内置）——定时循环执行指令，适合轮询、监控、定期检查。
  • 场景：监控服务状态、定时跑检查脚本。
  • 示例：/loop 5m 检查服务状态
• settings（内置）——管理 Wave 配置（settings.json、hooks、MCP、插件等）。
  • 场景：调整模型、配置钩子、注册 MCP 服务。
  • 示例：/settings 帮我加一个 PreToolUse 钩子

提示：能力支持叠加使用——例如先用 SDD 把需求写成规格，再用 frontend-design 实现界面，最后用 commit-skills 走完提交到合并的流程（依赖 gh / glab 完成实际的 PR / MR 操作）。描述任务时直接说明目标，AI 会自动匹配合适的能力。

---

二、将 Figma 设计稿转化为前端代码

设计稿还原是前端开发的高频场景。通过 MCP（Model Context Protocol），CodeWave IDE 可以连接 Figma 设计稿数据，让 AI 直接读取设计稿的布局、颜色、字体与图片资源，一键生成与设计稿高度一致的响应式页面。

本教程以 Figma 的 MCP 服务器（figma-developer-mcp，社区版）为例，演示从配置到出码的完整流程。Figma 官方也提供 MCP 服务器，如果条件允许，官方 MCP 同样极力推荐。

1. 准备：获取 Figma Access Token

Figma 通过 Personal Access Token 授权第三方应用访问设计稿数据。

1. 登录 Figma，点击左上角用户头像 → Settings。
2. 在顶部菜单选择 Security，滚动到 Personal access tokens 部分，点击 Generate new token。
3. 输入 Token 名称（如 codewave-figma）、设置有效期，并勾选所需权限，点击 Generate token。
4. 复制生成的 Token（只显示一次，请妥善保存）。

注意：Token 仅授权访问其持有者账号有权限的设计稿；分享设计稿给该账号后再使用。

2. 在 CodeWave IDE 中添加 Figma MCP 服务器

打开 CodeWave IDE 设置 → MCP，点击「添加 MCP 服务」，选择类型并填写配置：

• stdio 类型（推荐，本地运行）：

  {
    "mcpServers": {
      "figma": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "figma-developer-mcp", "--stdio"],
        "env": { "FIGMA_API_KEY": "你的 Access Token" }
      }
    }
  }

• http 类型：如果使用远程托管的 Figma MCP 服务，填写服务 URL 并在 headers 中携带 Token。

保存后服务器自动连接，列表显示连接状态。

也可以直接在项目根目录创建 .mcp.json（同上的 mcpServers 结构），启动时自动加载。更多配置方式见 桌面版文档 - MCP。

3. 对话中粘贴设计稿链接，提出需求

在本地打开项目文件夹（CodeWave IDE 桌面端「打开项目」，或 IDE 插件中打开工作区），然后把 Figma 设计稿的选中区域链接复制到对话中：

1. 打开 Figma 设计稿，选中要还原的 Frame。
2. 右键 → Copy/Paste as → Copy link to selection，复制设计稿链接。
3. 在 CodeWave IDE 输入框中粘贴链接并描述需求，例如：

请严格按照这个 Figma 链接生成登录页的响应式 HTML，视觉细节要跟设计稿一致：https://www.figma.com/design/9xYkZ0vF/Login-Page（含移动端与桌面端两套布局）

AI 会自动匹配并调用 Figma MCP 工具：先读取设计稿布局信息（get_figma_data），再下载其中的图标与图片资源（download_figma_images），最后生成 index.html：

首次调用需授权：MCP 工具首次使用时弹出权限确认，勾选「总是允许」后存为信任规则，后续调用免确认：

4. 预览与迭代

生成完成后，在预览面板（或浏览器中）打开 index.html 查看效果，继续对话迭代优化：

• "背景色跟设计稿再贴近一点，改成 #4A90D9 的渐变"
• "移动端断点下把表单挤成单列"
• "图标用设计稿里的 SVG，不要用 iconfont"

每一次反馈都会在同一个对话上下文里继续，AI 会基于设计稿数据与你的意见持续调整。

常见问题

• 工具调用失败：确认 Token 有效且对设计稿有访问权限，服务器连接状态正常（设置 → MCP 可查看）。
• 链接无法读取：使用 Copy link to selection 复制的链接，而不是浏览器地址栏的链接；确保设计稿已分享给 Token 所属账号。
• 生成的样式与设计稿有偏差：在设计稿中确认 Frame 命名与图层结构清晰，描述需求时补充关键要求（如响应式断点、主色值）。

---

三、SDD开发案例

SDD（规格驱动开发）是随 CodeWave 内置的插件：在写代码之前先用功能规格说明（用户故事 + 验收场景）明确设计，走完「规格 → 技术方案（可选）→ 编码」的完整工作流。下面介绍插件的启用方式与工作流全流程。

1. 启用 SDD 插件

SDD 插件默认关闭，不干扰日常使用。启用方式：在设置页「项目设置」视图切换「SDD（规格驱动开发）」开关，切换后立即生效（无需重启会话），开关状态与项目 .wave/settings.json 的 enabledPlugins 保持同步：

2. 规格驱动开发工作流

启用 SDD 插件后，当你提出新的功能需求或修改需求时，AI 会引导你走完「规格 → 技术方案（可选）→ 编码」的工作流：先编写或更新功能规格说明并请你确认，再按需制定技术方案，最后开始编码。各阶段之间的衔接均通过单选按钮完成，全程进度实时显示在任务列表中。

第一阶段：规格编写与确认

提出需求后，AI 自动编写功能规格说明（用户故事 + 验收场景），任务列表显示「编写功能规格」进行中；编写完成后通过单选弹窗请你决策——选择「直接实现」即直接进入编码、选择「制定技术方案」进入可选的技术方案阶段；如需调整规格，选择弹窗末尾的「其他」并输入修改意见，AI 会按反馈更新规格后再次请求决策。

规格编写阶段：AI 产出规格说明并写入 docs/specs/ 文件，点击消息中的文件路径可在右侧文件面板预览完整 spec；编写完成后通过单选弹窗请你决策（「直接实现 / 制定技术方案」，「其他」用于输入调整意见）

第二阶段（可选）：技术方案

在规格决策弹窗中选择「制定技术方案」后，进入技术方案模式制定技术方案（技术选型、架构设计、实现步骤）。方案全文在桌面端的计划面板中展示（与对话并排的右侧面板）；确认框保持紧凑，方案正文不进入对话消息列表，方案经你批准后才开始编码。

技术方案预览：方案全文在右侧计划面板中展示，对话与方案并排对照；确认框保持紧凑（方案正文不进入消息列表），提供「批准并继续」「批准并自动接受后续修改」「提供反馈」等选项，批准后开始编码

第三阶段：编码实现

方案批准后进入编码阶段。任务列表全程记录各阶段进度——规格、技术方案标记为已完成、当前实现阶段标记为进行中；跳过的可选阶段不会出现在任务列表中。

编码阶段：任务列表展示完整工作流进度

迭代已有需求：更新既有规格

当需求是对已有功能的修改时，AI 不会另起新规格，而是直接更新对应的既有规格文件（沿用已有的规格目录与分组命名，新增用户故事和验收场景），任务列表显示「更新功能规格」进行中；更新完成后同样通过单选弹窗请你决策——选择「其他」并输入意见时按反馈继续调整，选择「直接实现」或「制定技术方案」后按更新后的规格重新汇入相应阶段。

迭代已有需求：AI 更新既有规格文件（Edit 修改以 diff 形式在消息中展示），右侧差异面板预览 spec 文件的具体改动；更新完成后通过单选弹窗请你决策（「直接实现 / 制定技术方案」，「其他」用于输入调整意见）

确认后重新汇入实现流程：任务列表展示「更新功能规格」已完成、「实现变更」进行中

3. 实际产出统计

以下为使用 CodeWave IDE SDD 实际产出的 spec 文档统计，这些来自真实项目实践的规格文件总结了最佳实践，帮助开发者更好地提效，并提升 AI 编码质量。

指标	数量
规格文件	66
用户故事	341
验收场景	1,263
测试用例	4,660

具体规格详见：docs/specs/。

---

四、实现网页自动化测试

功能验证与回归测试是保证页面质量的关键。CodeWave IDE 可以让 AI 直接驱动真实浏览器完成"打开页面 → 操作元素 → 校验结果"的自动化测试，并把结论整理成测试报告。

本教程推荐 Playwright CLI（playwright-cli）：它由 AI 通过 Bash 工具直接调用，无需安装插件或配置 MCP；命令简短、只在需要时抓取页面数据，不必把工具 schema 与整棵页面无障碍树塞进模型上下文，因此比 MCP 方案更省 token。

1. 安装 Playwright CLI

npm install -g @playwright/cli@latest   # 需要 Node.js 18+
playwright-cli --help                   # 确认安装成功

可选：把它的用法安装成技能，AI 会自动匹配加载（写入项目 .agents/skills/，Wave 会识别该目录）：

playwright-cli install --skills=agents

不装技能也可以——直接让 AI 读 playwright-cli --help 自己上手。

2. 对话驱动自动化测试

直接用自然语言描述测试目标即可。AI 会用 open 打开页面、snapshot 抓取可交互元素快照（每个元素带 ref）、再用 fill / click / select / press 操作元素，最后用 screenshot / eval 校验结果：

打开登录页 https://example.com/login，填写账号密码点击登录，检查是否跳转成功并截图，最后把测试结论写成 test-report.md

对应的命令大致如下：

playwright-cli open https://example.com/login --browser chrome
playwright-cli snapshot          # 拿到页面上各元素的 ref
playwright-cli fill e3 "dev@example.com"
playwright-cli fill e4 "******"
playwright-cli click e5
playwright-cli screenshot        # 校验渲染结果并留证

几个容易踩的点：

• ref 每次都变：页面一变就重新 snapshot，不要复用旧 ref。
• 本地服务优先用 127.0.0.1：部分环境下 localhost 会连接异常。
• --headed 可以看着浏览器跑（调试时好用）；--device "iphone 15" / --mobile 用于移动端视口校验。
• 快照文件默认落在当前目录的 .playwright-cli/。

Bash 命令首次执行时可能弹出权限确认，勾选「总是允许」后存为信任规则，后续免确认。

3. 常用测试指令

• 打开并校验页面："打开 https://example.com，检查标题和加载状态"
• 表单流程测试："注册流程：填写表单、提交、校验成功提示"
• 元素交互："点击首页的『了解更多』按钮，确认跳转到文档页"
• 视觉校验："对移动端视口截图，检查布局是否有溢出"
• 控制台检查："检查这个页面控制台有没有报错，把错误列出来"

4. 测试报告与回归

AI 会把测试结果整理为结构化的测试报告（用例、步骤、结果、控制台错误、截图），写入项目文件，便于跟踪与回归：

• 首次测试：让 AI 生成覆盖核心流程的测试步骤并执行
• 回归测试：修复后让 AI 重跑关键用例："按 test-report.md 里的用例重新跑一遍登录流程"
• 持续集成：把生成的测试脚本接入 CI，配合定时循环技能（/loop）定期巡检页面可用性