增加设计说明和测试说明文档

This commit is contained in:
xiahb 2026-06-24 15:11:45 +08:00
parent 8a702c0b7d
commit e3e42c8044
11 changed files with 529 additions and 0 deletions

View File

@ -0,0 +1,329 @@
# YHFT DSP 工作台侧边栏设计文档
## 1. 概述
YHFT DSP 工作台是 VSCode 侧边栏中的 Webview 面板,作为 DSP IDE 的统一入口,集中展示环境状态、工程信息和常用操作。用户无需记住命令名称,通过面板按钮即可完成工具安装、工程管理、构建和调试等操作。
### 1.1 设计目标
- **一站式入口**:将分散的 DSP 命令整合到一个可视化面板中
- **状态感知**:实时显示工具链安装状态、工程上下文、芯片/模块配置
- **操作引导**:根据当前状态提示下一步操作,降低使用门槛
- **主题适配**:自动跟随 VSCode 深色/浅色主题
### 1.2 技术栈
- **渲染引擎**Vue 2 Runtime通过 `vue.min.js` 引入)
- **构建工具**:自定义 `build-webview.js` 脚本,从 `.vue` 文件提取 `<script>``<style>`
- **通信机制**VSCode Webview `postMessage` API
- **安全策略**CSPContent Security Policy+ nonce 机制
## 2. 架构设计
### 2.1 整体架构
```
┌─────────────────────────────────────────────────┐
│ VSCode 侧边栏 │
│ ┌─────────────────────────────────────────────┐ │
│ │ DspWorkbenchViewProvider │ │
│ │ ┌───────────────────────────────────────┐ │ │
│ │ │ Webview (Vue 2 渲染) │ │ │
│ │ │ ┌─────────┐ ┌──────────┐ ┌────────┐ │ │ │
│ │ │ │ 快速开始 │ │ 工程配置 │ │常用操作│ │ │ │
│ │ │ └─────────┘ └──────────┘ └────────┘ │ │ │
│ │ └───────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
│ postMessage ▲ postMessage
▼ │
┌─────────────────────────────────────────────────┐
│ 扩展宿主 (extension.ts) │
│ - 注册命令 - 管理状态 - 调用模块 API │
└─────────────────────────────────────────────────┘
│ │
┌────┴────┐ ┌──────┴──────┐
│dsp-core │ │dsp-mod-* │
│核心服务 │ │功能模块 │
└─────────┘ └─────────────┘
```
### 2.2 组件结构
```
dsp-core/
├── src/
│ └── extension.ts # DspWorkbenchViewProvider 实现
├── webview/
│ └── workbench/
│ ├── build-webview.js # 构建脚本
│ └── src/
│ └── App.vue # Vue 2 组件源码
├── media/
│ ├── static/
│ │ └── workbench.html # HTML 模板
│ ├── generated/
│ │ ├── workbench.js # 构建产物(从 App.vue 提取)
│ │ └── workbench.css # 构建产物(从 App.vue 提取)
│ └── vue.min.js # Vue 2 运行时
```
### 2.3 数据流
```
激活扩展 → 创建 WorkbenchViewProvider → resolveWebviewView()
├── 读取配置/状态 → buildWorkbenchState()
│ ├── getProfile() → 芯片/模块配置
│ ├── getToolchainStatus() → 工具链安装状态
│ ├── getProjectContext() → 当前工程上下文
│ └── getOfflineIndexStatus() → 离线索引状态
├── 渲染 HTML → renderWorkbenchHtml()
│ ├── 读取 workbench.html 模板
│ ├── 注入 Vue/JS/CSS 资源路径
│ ├── 注入 nonceCSP 安全)
│ └── 注入状态 JSON__DSP_WORKBENCH_STATE__
└── 用户点击按钮 → postMessage → onDidReceiveMessage()
├── "refresh" → 重新渲染面板
└── "execute" → vscode.commands.executeCommand(target)
```
## 3. 面板布局
### 3.1 视觉结构
```
┌──────────────────────────────────────┐
│ YHFT [刷新] │
├──────────────────────────────────────┤
│ 环境已就绪 · 当前工程test03 / c6000 │
│ [c6000] [debug, build] │
├──────────────────────────────────────┤
│ 快速开始 │
│ ┌──────────────────────────────────┐ │
│ │ 安装工具包 │ │
│ │ 进入正式安装页面,选择在线或离线 │ │
│ ├──────────────────────────────────┤ │
│ │ 修复工具包 │ │
│ │ 检查安装源和安装位置 │ │
│ ├──────────────────────────────────┤ │
│ │ 查看安装状态 │ │
│ │ 查看当前工具包安装记录 │ │
│ └──────────────────────────────────┘ │
├──────────────────────────────────────┤
│ 工程配置 │
│ ┌──────────────────────────────────┐ │
│ │ 新建 C6X 工程 │ │
│ │ 通过向导创建新的 C6X 工程 │ │
│ ├──────────────────────────────────┤ │
│ │ 打开工程 │ │
│ │ 打开已有的 DSP 工程目录 │ │
│ ├──────────────────────────────────┤ │
│ │ 工程属性配置 │ │
│ │ 管理工程构建属性 │ │
│ ├──────────────────────────────────┤ │
│ │ 调试配置 │ │
│ │ 管理 launch 调试配置 │ │
│ └──────────────────────────────────┘ │
├──────────────────────────────────────┤
│ 常用操作 │
│ ┌──────────────────────────────────┐ │
│ │ 构建 │ │
│ │ 执行构建 │ │
│ ├──────────────────────────────────┤ │
│ │ 调试 │ │
│ │ 检查环境并启动调试 │ │
│ ├──────────────────────────────────┤ │
│ │ AI 助手 │ │
│ │ 打开 AI 入口 │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────┘
```
### 3.2 分组说明
| 分组 | 按钮 | 功能 |
|------|------|------|
| 快速开始 | 安装工具包 | 打开安装向导面板,支持在线/离线安装 |
| | 修复工具包 | 同上,用于重新安装或修复 |
| | 查看安装状态 | 输出安装记录到 Output 面板 |
| 工程配置 | 新建 C6X 工程 | 打开 C6X 工程创建向导 |
| | 打开工程 | 选择并打开 DSP 工程目录 |
| | 工程属性配置 | 打开工程属性配置面板 |
| | 调试配置 | 打开调试配置面板 |
| 常用操作 | 构建 | 执行增量构建 |
| | 调试 | 检查环境后启动调试 |
| | AI 助手 | 打开 AI 功能入口 |
## 4. 通信协议
### 4.1 Webview → 扩展宿主
```javascript
// 刷新面板状态
vscode.postMessage({ command: "refresh" });
// 执行 VSCode 命令
vscode.postMessage({ command: "execute", target: "dspide.build" });
```
### 4.2 扩展宿主 → Webview
通过注入初始状态 JSON 实现:
```html
<script>
window.__DSP_WORKBENCH_STATE__ = {
installMode: "offline",
profile: { toolchain: ["c6000"], modules: ["debug", "build"] },
platform: "win32",
toolchainState: "installed",
toolchainPath: "C:\\Users\\...\\dsp-toolchain",
installSummary: "已安装 5 / 5失败 0",
offlineIndexReady: true,
nextStep: "环境已具备基础条件...",
projectContext: { projectName: "test03", chip: "c6000", ... },
quickActions: [...],
sections: [...]
};
</script>
```
### 4.3 命令映射
| 按钮 | VSCode 命令 | 所属模块 |
|------|-------------|----------|
| 安装工具包 | `dsp.core.openInstaller` | dsp-core |
| 修复工具包 | `dsp.core.openInstaller` | dsp-core |
| 查看安装状态 | `dsp.core.installStatus` | dsp-core |
| 新建 C6X 工程 | `dspide.project.createC6x` | dsp-mod-project |
| 打开工程 | `dspide.project.open` | dsp-mod-project |
| 工程属性配置 | `dspide.project.openPropertyConfig` | dsp-mod-project |
| 调试配置 | `dspide.project.openDebugConfig` | dsp-mod-project |
| 构建 | `dspide.build` | dsp-mod-build |
| 调试 | `dspide.debugStartWithSavedConfig` | dsp-mod-debug |
| AI 助手 | `ai.application` | dsp-mod-ai |
## 5. 样式设计
### 5.1 主题变量
面板使用 VSCode 内置 CSS 变量,自动适配深色/浅色主题:
| 变量 | 用途 |
|------|------|
| `--vscode-sideBar-background` | 页面背景 |
| `--vscode-foreground` | 主文字颜色 |
| `--vscode-descriptionForeground` | 描述文字颜色 |
| `--vscode-badge-background` | 标签背景 |
| `--vscode-badge-foreground` | 标签文字 |
| `--vscode-button-background` | 主要按钮背景 |
| `--vscode-button-foreground` | 主要按钮文字 |
| `--vscode-button-secondaryBackground` | 次要按钮背景 |
| `--vscode-button-secondaryForeground` | 次要按钮文字 |
| `--vscode-textLink-foreground` | 链接颜色 |
### 5.2 按钮样式
- **主要按钮**(如"安装工具包"):使用 `--vscode-button-background`,突出显示
- **次要按钮**:使用 `--vscode-button-secondaryBackground`,常规显示
- **圆角**6px
- **内边距**8px 10px
- **标题**13px 加粗
- **描述**11px85% 透明度
## 6. 安全设计
### 6.1 CSP 策略
```html
<meta http-equiv="Content-Security-Policy"
content="default-src 'none'; style-src __CSP_SOURCE__; script-src 'nonce-__NONCE__';">
```
- `default-src 'none'`:禁止所有默认资源加载
- `style-src __CSP_SOURCE__`:只允许扩展自身的样式
- `script-src 'nonce-__NONCE__'`:只允许带 nonce 的脚本执行
### 6.2 Nonce 机制
每次渲染生成 32 位随机字符串,确保每次加载的 nonce 不同,防止 XSS 攻击。
## 7. 构建流程
### 7.1 构建脚本
`webview/workbench/build-webview.js` 执行以下步骤:
1. 读取 `webview/workbench/src/App.vue` 源码
2. 提取 `<script>` 块,替换 `export default` 为工厂函数
3. 提取 `<style>` 块,添加生成注释
4. 输出到 `media/generated/workbench.js``workbench.css`
### 7.2 构建命令
```bash
# 重新生成 workbench 产物
node packages/dsp-core/webview/workbench/build-webview.js
# 完整构建 dsp-core
npm run build -w packages/dsp-core
```
### 7.3 注意事项
- 修改 `App.vue` 后必须重新运行构建脚本
- `media/workbench.js` 是旧版文件,不要直接编辑
- 实际加载的是 `media/generated/workbench.js`
## 8. 扩展指南
### 8.1 添加新按钮
1. 在 `App.vue` 的对应 computed 属性中添加按钮配置:
```javascript
projectActions: function () {
return [
// ... 现有按钮
{
title: "新按钮标题",
description: "按钮描述",
command: "your.command.id"
}
];
}
```
2. 确保命令已在 `package.json` 中声明
3. 运行构建脚本重新生成产物
### 8.2 添加新分组
1. 在 `App.vue``render` 函数中添加新的 `section`
```javascript
h("section", { class: "group" }, [
h("div", { class: "group-title" }, "新分组标题"),
h("div", { class: "btn-list" },
vm.newGroupActions.map(function (item) {
return renderActionButton(h, vm, item, false);
})
)
])
```
2. 在 `computed` 中添加对应的 action 数组
### 8.3 修改样式
直接编辑 `App.vue``<style>` 块,重新运行构建脚本。所有样式使用 VSCode 主题变量,确保主题适配。
## 9. 已知限制
1. **无动态更新**:面板状态通过注入 JSON 初始化,按钮操作后需手动刷新或由扩展宿主触发刷新
2. **无颜色高亮**VSCode Webview 不支持终端 ANSI 颜色,状态通过文字和图标区分
3. **无交互式配置**:按钮仅触发命令,复杂配置通过独立 Webview 面板实现
4. **Vue 2 限制**:使用 Vue 2 Runtime 而非完整版,不支持模板编译(使用 `h` 函数渲染)

Binary file not shown.

After

Width:  |  Height:  |  Size: 59 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 173 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 171 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 140 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 133 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 205 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 142 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 149 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 160 KiB

View File

@ -0,0 +1,200 @@
# YHFT DSP 工作台侧边栏 — 手动测试说明
## 测试环境
- **VSCode 版本**1.124.2 或以上
- **扩展版本**dsp-suite 0.1.0
- **操作系统**Windows 10/11
- **前置条件**:已安装 DSP 工具包,至少有一个 C6X 工程可打开
---
## 主界面总览
打开 VSCode 后,点击左侧活动栏的 **YHFT** 图标,展开 DSP 工作台侧边栏。
![主界面](imgs/主界面.png)
面板分为三个区域:
- **快速开始**:安装工具包、修复工具包、查看安装状态。不在本次测试范围
- **工程配置**:新建 C6X 工程、打开工程、工程属性配置、调试配置
- **常用操作**构建、调试、AI 助手
---
## 一、工程配置
### 测试 1新建 C6X 工程
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证 C6X 工程创建向导能正常打开并创建工程 |
| **操作步骤** | 1. 在工作台面板中点击 **"新建 C6X 工程"** |
| | 2. 在弹出的向导中填写工程名称 |
| | 3. 选择工程创建位置 |
| | 4. 选择芯片型号(如 C66xx |
| | 5. 点击 **"创建"** |
| **预期结果** | 1. 向导面板正常打开,无白屏或报错 |
| | 2. 填写信息后点击创建,工程目录被创建 |
| | 3. 工程目录中包含 attrConfig.json、launch.json、src/main.c 等文件 |
| | 4. 创建完成后自动打开新工程文件夹 |
| **实际结果** | **通过,可以正常创建成功并打开工程** |
![新建C6X工程](imgs/新建C6X工程.png)
---
### 测试 2打开工程
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证能正确打开已有的 DSP 工程目录 |
| **操作步骤** | 1. 在工作台面板中点击 **"打开工程"** |
| | 2. 在弹出的文件夹选择器中选择一个 DSP 工程目录 |
| | 3. 点击 **"打开 DSP 工程目录"** |
| **预期结果** | 1. 文件夹选择器正常弹出 |
| | 2. 选择工程目录后VSCode 打开该文件夹 |
| | 3. 工作台面板刷新,显示新的工程名称和芯片信息 |
| **实际结果** | **通过,正常打开并刷新工程信息** |
![打开工程](imgs/打开工程.png)
![打开工程](imgs/打开工程1.png)
---
### 测试 3工程属性配置
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证工程属性配置面板能正常打开并读取配置 |
| **前提条件** | 已打开一个 C6X 工程 |
| **操作步骤** | 1. 在工作台面板中点击 **"工程属性配置"** |
| | 2. 查看面板中显示的配置信息(工具链路径、编译参数等) |
| | 3. 修改某个配置项(如编译参数) |
| | 4. 点击保存 |
| **预期结果** | 1. 配置面板正常打开,无白屏 |
| | 2. 面板正确读取 attrConfig.json 中的配置值 |
| | 3. 修改后保存,配置写入 attrConfig.json |
| | 4. 关闭面板后重新打开,修改后的值仍然存在 |
| **实际结果** | **通过,可以正常读取和写入配置** |
![工程属性配置](imgs/工程属性配置.png)
---
### 测试 4调试配置
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证调试配置面板能正常打开并管理 launch.json |
| **前提条件** | 已打开一个 C6X 工程 |
| **操作步骤** | 1. 在工作台面板中点击 **"调试配置"** |
| | 2. 查看面板中显示的调试配置ccxml 路径、会话名称等) |
| | 3. 修改某个配置项(如选择不同的 ccxml 文件) |
| | 4. 点击保存 |
| **预期结果** | 1. 调试配置面板正常打开 |
| | 2. 面板正确读取 .vscode/launch.json 中的 dss-dap 配置 |
| | 3. 修改后保存,配置写入 launch.json |
| | 4. 在 VSCode 的 launch.json 中可以看到更新后的配置 |
| **实际结果** | **通过,可以正常读取和写入配置** |
![调试配置](imgs/调试配置.png)
---
## 二、常用操作
### 测试 5构建
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证构建功能能正确执行并输出结果 |
| **前提条件** | 已打开一个 C6X 工程,且工程中包含源代码 |
| **操作步骤** | 1. 在工作台面板中点击 **"构建"** |
| | 2. 观察输出面板DSP Build的输出 |
| | 3. 检查工程目录下是否生成了构建产物(如 .out 文件) |
| **预期结果** | 1. 点击后输出面板显示构建日志 |
| | 2. 显示使用的 gmake 路径和编译命令 |
| | 3. 编译成功时显示 "summary: errors=0, warnings=0" |
| | 4. 工程目录下生成 .out 文件或对应的构建产物 |
| | 5. 编译失败时,问题面板显示错误信息,可双击跳转 |
| **实际结果** | |
| **通过,可以成功编译,失败时问题面板显示错误信息** | |
![构建](imgs/构建.png)
![构建](imgs/构建1.png)
---
### 测试 6调试
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证调试功能能正确检查环境并启动调试会话 |
| **前提条件** | 已打开一个 C6X 工程,已安装 DSS 调试工具,已配置 ccxml 文件 |
| **操作步骤** | 1. 在工作台面板中点击 **"调试"** |
| | 2. 观察输出面板DSP Debug的输出 |
| | 3. 检查是否启动了调试会话 |
| **预期结果** | 1. 输出面板显示环境检查信息(平台、芯片、调试类型) |
| | 2. C6X 工程显示 "调试类型=dss-dap" |
| | 3. 成功启动调试后,显示悬浮调试控制按钮 |
| | 4. 调试控制台显示 DSS 连接信息 |
| **实际结果** | **通过,可以显示正确的调试信息并正常启动调试** |
![调试](imgs/调试.png)
---
### 测试 7AI 助手
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证 AI 助手入口能正常打开 |
| **操作步骤** | 1. 在工作台面板中点击 **"AI 助手"** |
| **预期结果** | 1. AI 功能面板或对话框正常打开 |
| | 2. 无白屏或报错 |
| **实际结果** | **通过,目前是空白实现** |
---
## 三、异常场景测试
### 测试 8未打开正确工程时操作
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证未打开工程时的容错处理 |
| **操作步骤** | 1. 关闭所有工程文件夹(使用"文件 → 打开文件夹"打开一个空目录) |
| | 2. 依次点击工程属性配置、调试配置、构建、调试 |
| **预期结果** | 1. 工作台面板显示 "请先打开一个包含 .vscode/attrConfig.json 的 DSP 工程目录。" |
| | 2. 点击工程属性配置/调试配置时构建时,进行同样的提示 |
| **实际结果** | **通过,出现打开提示** |
### 测试 9未打开文件夹时操作
| 项目 | 内容 |
|------|------|
| **测试目的** | 验证未打开文件夹时的容错处理 |
| **操作步骤** | 1. 关闭文件夹 |
| | 2. 查看工作台 |
| **预期结果** | 1. 提示未打开DSP工程 |
| | 2. 不会崩溃或无响应 |
| | 3. 可以新建工程 |
| **实际结果** | **通过,出现正确提示并可以新建工程** |
---
## 四、测试结果汇总
| 测试编号 | 测试项 | 结果 |
|----------|--------|------|
| 1 | 新建 C6X 工程 | 通过 |
| 2 | 打开工程 | 通过 |
| 3 | 工程属性配置 | 通过 |
| 4 | 调试配置 | 通过 |
| 5 | 构建 | 通过 |
| 6 | 调试 | 通过 |
| 7 | AI 助手 | 通过 |
| 8 | 未打开正确工程时操作 | 通过 |
| 9 | 未打开文件夹时操作 | 通过 |