diff --git a/docs/csm-module-skill.md b/docs/csm-module-skill.md index beacd98..d926939 100644 --- a/docs/csm-module-skill.md +++ b/docs/csm-module-skill.md @@ -34,6 +34,7 @@ | 章节 | 是否必须 | 说明 | | --- | --- | --- | | **功能简述** | ✅ 必须 | 1～3 句话。模块做什么？ | +| **模块信息** | ✅ 必须 | LabVIEW 版本、操作系统、RT 支持等元数据 | | **依赖项** | ✅ 必须 | CSM 核心框架 + 所需插件 | | **API 接口** | ✅ 必须 | 模块接受的所有 `API:` 消息 | | **状态广播接口** | ✅ 如果模块有广播 | 所有 `Status`/`Interrupt` 广播 | @@ -43,6 +44,34 @@ | **模块交互图** | 可选 | 展示消息流的 Mermaid `stateDiagram-v2` | | **备注** | 可选 | 实现说明和已知限制 | +### 3.1 模块信息格式 + +使用表格列出模块的运行环境元数据： + +```markdown +## 模块信息 + +| 属性 | 值 | +| --- | --- | +| LabVIEW 版本 | ≥ [版本号，例如 2019] | +| 支持的操作系统 | [Windows / Linux / macOS] | +| 支持 RT | [✅ 支持 / ❌ 不支持] | +| 支持 64-bit | [✅ 支持 / ❌ 不支持] | +``` + +### 3.2 依赖项格式 + +使用 2 列表格（依赖名含链接，类型列标注必须/可选）： + +```markdown +## 依赖项 + +| 依赖 | 类型 | +| --- | --- | +| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 | +| [CSM-API-String-Arguments-Support](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | 可选 | +``` + --- ## 4. API 接口规则 @@ -53,21 +82,42 @@ - 或**没有 `:` 分割的非内置 case 分支**（例如用户自定义的 `ReadData`、`GetValue`）。 - **不要**将内置系统状态（`Macro: Initialize`、`Macro: Exit`、`Error Handler`、`Response`、`Async Response` 等）记录为 API，除非它们是有意公开的。 -### 4.2 表格列说明 +### 4.2 接口描述格式 + +每个 API 使用独立的三级段落（`###`），按以下结构填写： -| **API** | **描述** | **参数数据类型** | **参数描述** | **响应数据类型** | **响应描述** | -| --- | --- | --- | --- | --- | --- | -| 完整消息字符串，包含前缀，例如 `` `API: Start` `` | 一句话说明该 API 的作用 | 参数的数据类型（例如 `APIString`、`MassData`、`${FilePath}` 等）。无参数时写 `N/A`。 | `>>` 之后传递的数据含义。无参数时写 `N/A`。 | 响应的数据类型。无响应或异步调用时写 `N/A`。 | 模块返回内容的含义。无响应或异步调用时写 `N/A`。 | +````markdown +### `API: 名称` + +一句话说明该 API 的作用。 + +- **参数**：`[CSM参数类型]` — `[数据类型]`：[数据描述]。无参数时写 `N/A`。 +- **响应**：`[CSM参数类型]` — `[数据类型]`：[数据描述]。无响应时写 `N/A`。 +```` + +对于包含多个字段的复合数据（如 Cluster），使用子列表展开： + +````markdown +- **参数**：`HexStr` — `Cluster`： + - `Flag`：Boolean + - `Level`：DBL +```` ### 4.3 参数类型标注规范 -始终在值描述之后用括号注明类型： +每个 `**参数**` / `**响应**` 行按以下模式填写： ```text -数据文件夹的完整路径 (APIString) -一维波形数组 (MassData) -包含配置的簇 (HexStr) -文件路径 (SafeStr) ← 由 INI 静态变量 `${FilePath}` 提供 +`[CSM参数类型]` — `[数据类型]`：[数据描述] +``` + +示例： + +```text +`APIString` — `String`：配置文件路径 +`MassData` — `Waveform[]`：一维波形数组 +`HexStr` — `Cluster`：（见子列表） +`SafeStr` — `String`：经 %[HEX] 编码的文件路径 ``` 支持的类型： @@ -91,14 +141,19 @@ | `Status` | 正常的、预期中的状态转换（例如"Acquired Waveform"、"Logging Complete"） | | `Interrupt` | 需要立即处理的错误、警告或事件 | -### 5.2 表格列说明 +### 5.2 接口描述格式 -| 列 | 填写内容 | -| --- | --- | -| **状态** | 精确的状态字符串，例如 `` `Acquired Waveform` `` | -| **广播类型** | `Status` 或 `Interrupt` | -| **描述** | 一句话说明该广播何时发出 | -| **参数** | 广播携带的数据，包含类型标注。无参数时写 `N/A`。 | +每个状态广播使用独立的三级段落（`###`），按以下结构填写： + +````markdown +### `状态名称` + +**广播类型**：`Status` 或 `Interrupt` + +一句话说明该广播何时发出。 + +- **参数**：广播携带的数据，包含类型标注。无参数时写 `N/A`。 +```` ### 5.3 订阅语法示例 @@ -229,10 +284,12 @@ direction LR - [ ] 文件名与模块 VI 名称一致。 - [ ] 功能简述在 ≤ 3 句话内回答"这个模块做什么？"。 -- [ ] 每一个 `API:` case 分支都列在 API 表中。 -- [ ] 参数类型使用标准标注格式（例如 `(APIString)`、`(MassData)`）。 -- [ ] 所有 `Status`/`Interrupt` 广播都列在状态广播表中。 -- [ ] 每行明确标注广播类型为 `Status` 或 `Interrupt`。 +- [ ] 模块信息表包含 LabVIEW 版本、操作系统、RT 支持和 64-bit 支持。 +- [ ] 依赖项使用 2 列表格（链接名 + 类型）。 +- [ ] 每一个 `API:` case 分支都有独立的三级段落（`###`）。 +- [ ] 每个 API 段落包含描述、`**参数**` 和 `**响应**` 字段（含 CSM 参数类型和数据描述）。 +- [ ] 所有 `Status`/`Interrupt` 广播都有独立的三级段落（`###`）。 +- [ ] 每个广播段落明确标注广播类型为 `Status` 或 `Interrupt`。 - [ ] 配置说明涵盖所有前面板控件和 INI 键值。 - [ ] 调用限制说明包含初始化顺序和任何单例规则。 - [ ] 至少包含一个带注释的使用示例。 @@ -247,11 +304,13 @@ direction LR | 错误 | 正确做法 | | --- | --- | | 将内部状态记录为 API | 只记录 API case（包括以 `API:` 为前缀的 case 和无 `:` 分隔的非内置 case） | -| 省略参数类型 | 始终在参数列写 `(类型)` | -| 同步/异步箭头用错 | 同步：`-@`，异步：`->`，无应答：`->|` | +| 用表格列出 API 或广播 | 每个 API / 广播使用独立的 `###` 段落，描述在段落正文中 | +| 参数只写描述，不写 CSM 参数类型 | 始终使用 `` `[CSM参数类型]` — `[数据类型]`：[描述] `` 格式 | +| 复合数据只写数据类型，不展开字段 | 使用子列表逐一列出 Cluster 的每个字段及其类型 | | 订阅时忘写 `@模块名` | 始终使用 `Status@源模块 >> API:Handler@目标模块 ->` | -| 空单元格不写 N/A | 无参数或无响应时明确写 `N/A` | +| 无参数或无响应时留空 | 明确写 `N/A` | | 使用 VI 文件名代替运行时模块名 | 模块名是启动时传入的字符串；在文档中说明这一区别 | +| 依赖项使用 3 列表格或项目列表 | 改用 2 列表格（依赖名含链接 + 类型） | --- diff --git a/module-template.md b/module-template.md index b092230..f9989b7 100644 --- a/module-template.md +++ b/module-template.md @@ -16,16 +16,27 @@ --- +## 模块信息 + +| 属性 | 值 | +| --- | --- | +| LabVIEW 版本 | ≥ [版本号，例如 2019] | +| 支持的操作系统 | [Windows / Linux / macOS] | +| 支持 RT | [✅ 支持 / ❌ 不支持] | +| 支持 64-bit | [✅ 支持 / ❌ 不支持] | + +--- + ## 依赖项 -| 依赖 | 类型 | 链接 | -| --- | --- | --- | -| Communicable State Machine (CSM) | 必须 | [GitHub](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | -| CSM API String Arguments Support | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | -| CSM MassData Parameter Support | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-MassData-Parameter-Support) | -| CSM INI Static Variable Support | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-INI-Static-Variable-Support) | -| CSM Mermaid Plugin | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-Mermaid-Plugin) | -| CSM TCP Router | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-TCP-Router-App) | +| 依赖 | 类型 | +| --- | --- | +| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 | +| [CSM-API-String-Arguments-Support](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | 可选 | +| [CSM-MassData-Parameter-Support](https://github.com/NEVSTOP-LAB/CSM-MassData-Parameter-Support) | 可选 | +| [CSM-INI-Static-Variable-Support](https://github.com/NEVSTOP-LAB/CSM-INI-Static-Variable-Support) | 可选 | +| [CSM-Mermaid-Plugin](https://github.com/NEVSTOP-LAB/CSM-Mermaid-Plugin) | 可选 | +| [CSM-TCP-Router-App](https://github.com/NEVSTOP-LAB/CSM-TCP-Router-App) | 可选 | > 删除不需要的行。 @@ -35,16 +46,51 @@ 以下是外部调用者可以发送给本模块的消息。 -| API | 描述 | 参数数据类型 | 参数描述 | 响应数据类型 | 响应描述 | -| --- | --- | --- | --- | --- | --- | -| `API: Initialize` | 初始化内部资源。必须在其他 API 之前调用。 | `APIString` | 配置文件路径 | N/A | N/A | -| `API: Start` | 启动模块的主要操作。 | N/A | N/A | N/A | N/A | -| `API: Stop` | 优雅地停止主要操作。 | N/A | N/A | N/A | N/A | -| `API: [示例：传递结构体数据]` | [描述] | `HexStr` | 配置簇 | N/A | N/A | -| `API: [示例：传递大块数据]` | [描述] | `MassData` | 一维波形数组 | N/A | N/A | -| `API: Get Status` | 查询当前状态。 | N/A | N/A | `APIString` | 状态描述 | +### `API: Initialize` + +初始化内部资源。必须在其他 API 之前调用。 + +- **参数**：`APIString` — `String`：配置文件路径 +- **响应**：N/A + +### `API: Start` + +启动模块的主要操作。 + +- **参数**：N/A +- **响应**：N/A + +### `API: Stop` + +优雅地停止主要操作。 + +- **参数**：N/A +- **响应**：N/A + +### `API: [示例：传递结构体数据]` + +[描述] -> 根据需要增减行。请记录每一个对外可调用的 `API:` 消息。 +- **参数**：`HexStr` — `Cluster`： + - `[字段名]`：[类型，例如 Boolean] + - `[字段名]`：[类型，例如 DBL] +- **响应**：N/A + +### `API: [示例：传递大块数据]` + +[描述] + +- **参数**：`MassData` — `Waveform[]`：一维波形数组 +- **响应**：N/A + +### `API: Get Status` + +查询当前状态。 + +- **参数**：N/A +- **响应**：`APIString` — `String`：状态描述 + +> 根据需要增减段落。请记录每一个对外可调用的 `API:` 消息。 ### 参数类型说明 @@ -62,10 +108,22 @@ 以下是本模块**发出**的消息，用于通知订阅者内部状态变化。 -| 状态 | 广播类型 | 描述 | 参数数据类型 | 参数描述 | -| --- | --- | --- | --- | --- | -| `[状态名称 A]` | `Status` | [发生了什么 / 哪些数据已就绪] | `HexStr` | 数据内容 | -| `[状态名称 B]` | `Interrupt` | [错误或需要立即处理的中断事件描述] | `APIString` | 错误信息 | +### `[状态名称 A]` + +**广播类型**：`Status` + +[发生了什么 / 哪些数据已就绪] + +- **参数**：`HexStr` — `Cluster`： + - `[字段名]`：[类型，例如 DBL] + +### `[状态名称 B]` + +**广播类型**：`Interrupt` + +[错误或需要立即处理的中断事件描述] + +- **参数**：`APIString` — `String`：错误信息 > - 使用 **`Status`** 表示正常的、预期中的状态转换。 > - 使用 **`Interrupt`** 表示需要立即关注的错误或事件。