Skip to content

docs: replace interface tables with sub-paragraph format; add module meta-info; expand param format #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nevstop merged 4 commits into from
Mar 20, 2026
Merged

docs: replace interface tables with sub-paragraph format; add module meta-info; expand param format #2

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
873cd4c
Initial plan
Copilot Mar 20, 2026
596d5a3
Replace interface tables with sub-paragraph format; use repo names fo…
Copilot Mar 20, 2026
c8b6443
Add module meta-info section, calling-convention field, simplify depe…
Copilot Mar 20, 2026
70174d6
Revert dep table to 2-col, remove calling-convention field, expand pa…
Copilot Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 65 additions & 17 deletions docs/csm-module-skill.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
| 章节 | 是否必须 | 说明 |
| --- | --- | --- |
| **功能简述** | ✅ 必须 | 1～3 句话。模块做什么？ |
| **模块信息** | ✅ 必须 | LabVIEW 版本、操作系统、RT 支持等元数据 |
| **依赖项** | ✅ 必须 | CSM 核心框架 + 所需插件 |
| **API 接口** | ✅ 必须 | 模块接受的所有 `API:` 消息 |
| **状态广播接口** | ✅ 如果模块有广播 | 所有 `Status`/`Interrupt` 广播 |
Expand All @@ -43,6 +44,35 @@
| **模块交互图** | 可选 | 展示消息流的 Mermaid `stateDiagram-v2` |
| **备注** | 可选 | 实现说明和已知限制 |

### 3.1 模块信息格式

使用表格列出模块的运行环境元数据：

```markdown
## 模块信息

| 属性 | 值 |
| --- | --- |
| LabVIEW 版本 | ≥ [版本号，例如 2019] |
| 支持的操作系统 | [Windows / Linux / macOS] |
| 支持 RT | [✅ 支持 / ❌ 不支持] |
| 支持 64-bit | [✅ 支持 / ❌ 不支持] |
```

### 3.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 接口规则
Expand All @@ -53,11 +83,19 @@
- 或**没有 `:` 分割的非内置 case 分支**（例如用户自定义的 `ReadData`、`GetValue`）。
- **不要**将内置系统状态（`Macro: Initialize`、`Macro: Exit`、`Error Handler`、`Response`、`Async Response` 等）记录为 API，除非它们是有意公开的。

### 4.2 表格列说明
### 4.2 接口描述格式

每个 API 使用独立的三级段落（`###`），按以下结构填写：

````markdown
### `API: 名称`

一句话说明该 API 的作用。

| **API** | **描述** | **参数数据类型** | **参数描述** | **响应数据类型** | **响应描述** |
| --- | --- | --- | --- | --- | --- |
| 完整消息字符串，包含前缀，例如 `` `API: Start` `` | 一句话说明该 API 的作用 | 参数的数据类型（例如 `APIString`、`MassData`、`${FilePath}` 等）。无参数时写 `N/A`。 | `>>` 之后传递的数据含义。无参数时写 `N/A`。 | 响应的数据类型。无响应或异步调用时写 `N/A`。 | 模块返回内容的含义。无响应或异步调用时写 `N/A`。 |
- **调用方式**：异步 (`->`) / 同步 (`-@`) / 无应答 (`->|`)
Copy link
Copy Markdown
Contributor

@nevstop nevstop Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

不需要调用方式，因为任何消息都可以被当作同步和异步调用

Copy link
Copy Markdown
Contributor Author

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已从所有 API 段落和 skill 文档规范中移除 **调用方式** 字段（提交：70174d6）。

- **参数**：参数的数据类型 — `>>` 之后传递的数据含义。无参数时写 `N/A`。
- **响应**：响应的数据类型 — 模块返回内容的含义。无响应或异步调用时写 `N/A`。
````

### 4.3 参数类型标注规范

Expand Down Expand Up @@ -91,14 +129,19 @@
| `Status` | 正常的、预期中的状态转换（例如"Acquired Waveform"、"Logging Complete"） |
| `Interrupt` | 需要立即处理的错误、警告或事件 |

### 5.2 表格列说明
### 5.2 接口描述格式

| 列 | 填写内容 |
| --- | --- |
| **状态** | 精确的状态字符串，例如 `` `Acquired Waveform` `` |
| **广播类型** | `Status` 或 `Interrupt` |
| **描述** | 一句话说明该广播何时发出 |
| **参数** | 广播携带的数据，包含类型标注。无参数时写 `N/A`。 |
每个状态广播使用独立的三级段落（`###`），按以下结构填写：

````markdown
### `状态名称`

**广播类型**：`Status` 或 `Interrupt`

一句话说明该广播何时发出。

- **参数**：广播携带的数据，包含类型标注。无参数时写 `N/A`。
````

### 5.3 订阅语法示例

Expand Down Expand Up @@ -229,10 +272,12 @@ direction LR

- [ ] 文件名与模块 VI 名称一致。
- [ ] 功能简述在 ≤ 3 句话内回答"这个模块做什么？"。
- [ ] 每一个 `API:` case 分支都列在 API 表中。
- [ ] 参数类型使用标准标注格式（例如 `(APIString)`、`(MassData)`）。
- [ ] 所有 `Status`/`Interrupt` 广播都列在状态广播表中。
- [ ] 每行明确标注广播类型为 `Status` 或 `Interrupt`。
- [ ] 模块信息表包含 LabVIEW 版本、操作系统、RT 支持和 64-bit 支持。
- [ ] 依赖项使用分组列表格式，链接文字为仓库名称。
- [ ] 每一个 `API:` case 分支都有独立的三级段落（`###`）。
- [ ] 每个 API 段落包含描述、`**调用方式**`、`**参数**` 和 `**响应**` 字段。
- [ ] 所有 `Status`/`Interrupt` 广播都有独立的三级段落（`###`）。
- [ ] 每个广播段落明确标注广播类型为 `Status` 或 `Interrupt`。
- [ ] 配置说明涵盖所有前面板控件和 INI 键值。
- [ ] 调用限制说明包含初始化顺序和任何单例规则。
- [ ] 至少包含一个带注释的使用示例。
Expand All @@ -247,11 +292,14 @@ direction LR
| 错误 | 正确做法 |
| --- | --- |
| 将内部状态记录为 API | 只记录 API case（包括以 `API:` 为前缀的 case 和无 `:` 分隔的非内置 case） |
| 省略参数类型 | 始终在参数列写 `(类型)` |
| 用表格列出 API 或广播 | 每个 API / 广播使用独立的 `###` 段落，描述在段落正文中 |
| 省略 API 调用方式 | 始终在每个 API 段落中标注 `**调用方式**`（`->`/`-@`/`->|`） |
| 省略参数类型 | 始终在 `**参数**` 行中注明数据类型 |
| 同步/异步箭头用错 | 同步：`-@`，异步：`->`，无应答：`->|` |
| 订阅时忘写 `@模块名` | 始终使用 `Status@源模块 >> API:Handler@目标模块 -><register>` |
| 空单元格不写 N/A | 无参数或无响应时明确写 `N/A` |
| 无参数或无响应时留空 | 明确写 `N/A` |
| 使用 VI 文件名代替运行时模块名 | 模块名是启动时传入的字符串；在文档中说明这一区别 |
| 依赖项使用表格 | 改用 **必须** / **可选** 分组列表，链接文字为仓库名 |

---

Expand Down
104 changes: 83 additions & 21 deletions module-template.md
View file
Open in desktop
Copy link
Copy Markdown
Contributor

@nevstop nevstop Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

也要增加一些 模块的 meta 信息，如支持的系统版本，labview版本, 是否支持 RT 等

Copy link
Copy Markdown
Contributor Author

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

在 ## 功能简述 之后新增了 ## 模块信息 章节：

## 模块信息

| 属性 | 值 |
| --- | --- |
| LabVIEW 版本 | ≥ [版本号，例如 2019] |
| 支持的操作系统 | [Windows / Linux / macOS] |
| 支持 RT | [✅ 支持 / ❌ 不支持] |
| 支持 64-bit | [✅ 支持 / ❌ 不支持] |

docs/csm-module-skill.md 中也同步更新了章节列表和 AI 检查清单。提交：c8b6443

Original file line number Diff line number Diff line change
Expand Up @@ -16,16 +16,28 @@

---

## 模块信息

| 属性 | 值 |
| --- | --- |
| 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) |
**必须**
Copy link
Copy Markdown
Contributor

@nevstop nevstop Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

保留表格，删除最后一列即可

Copy link
Copy Markdown
Contributor

@nevstop nevstop Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot 修改这个

Copy link
Copy Markdown
Contributor Author

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已恢复为 2 列表格，链接嵌入依赖名称列，移除单独的链接列（提交：70174d6）：

| 依赖 | 类型 |
| --- | --- |
| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 |
| [CSM-API-String-Arguments-Support](...) | 可选 |

- [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)

> 删除不需要的行。

Expand All @@ -35,16 +47,55 @@

以下是外部调用者可以发送给本模块的消息。

| 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`
Comment thread
nevstop marked this conversation as resolved.

初始化内部资源。必须在其他 API 之前调用。

- **调用方式**：异步 (`->`)
- **参数**：`APIString` — 配置文件路径
Copy link
Copy Markdown
Contributor

@nevstop nevstop Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

参数/响应都应该要有 CSM参数类型(APIString/MassData/HexStr等）和数据描述。

CSM参数类型：APIString
数据类型:Cluster
数据描述：
Flag:Boolean
Level:DBL

Copy link
Copy Markdown
Contributor Author

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

已更新参数/响应格式，同时标注 CSM 参数类型和数据类型+描述（提交：70174d6）。简单值：

- **参数**：`APIString` — `String`：配置文件路径

复合数据（Cluster）展开字段：

- **参数**：`HexStr` — `Cluster`：
  - `Flag`：Boolean
  - `Level`：DBL

- **响应**：N/A

### `API: Start`

启动模块的主要操作。

- **调用方式**：异步 (`->`)
- **参数**：N/A
- **响应**：N/A

### `API: Stop`

优雅地停止主要操作。

- **调用方式**：异步 (`->`)
- **参数**：N/A
- **响应**：N/A

### `API: [示例：传递结构体数据]`

> 根据需要增减行。请记录每一个对外可调用的 `API:` 消息。
[描述]

- **调用方式**：异步 (`->`)
- **参数**：`HexStr` — 配置簇
- **响应**：N/A

### `API: [示例：传递大块数据]`

[描述]

- **调用方式**：异步 (`->`)
- **参数**：`MassData` — 一维波形数组
- **响应**：N/A

### `API: Get Status`

查询当前状态。

- **调用方式**：同步 (`-@`)
- **参数**：N/A
- **响应**：`APIString` — 状态描述

> 根据需要增减段落。请记录每一个对外可调用的 `API:` 消息。

### 参数类型说明

Expand All @@ -62,10 +113,21 @@

以下是本模块**发出**的消息，用于通知订阅者内部状态变化。

| 状态 | 广播类型 | 描述 | 参数数据类型 | 参数描述 |
| --- | --- | --- | --- | --- |
| `[状态名称 A]` | `Status` | [发生了什么 / 哪些数据已就绪] | `HexStr` | 数据内容 |
| `[状态名称 B]` | `Interrupt` | [错误或需要立即处理的中断事件描述] | `APIString` | 错误信息 |
### `[状态名称 A]`

**广播类型**：`Status`

[发生了什么 / 哪些数据已就绪]

- **参数**：`HexStr` — 数据内容

### `[状态名称 B]`

**广播类型**：`Interrupt`

[错误或需要立即处理的中断事件描述]

- **参数**：`APIString` — 错误信息

> - 使用 **`Status`** 表示正常的、预期中的状态转换。
> - 使用 **`Interrupt`** 表示需要立即关注的错误或事件。
Expand Down
Loading