Skip to content

Commit 52aada8

Browse files
Copilotnevstop
Copilot
and
nevstop
authored
docs: replace interface tables with sub-paragraph format; add module meta-info; expand param format (#2)
* Initial plan * Replace interface tables with sub-paragraph format; use repo names for dependency links Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * Add module meta-info section, calling-convention field, simplify dependency list Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * Revert dep table to 2-col, remove calling-convention field, expand param format Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com>
1 parent 59c51fa commit 52aada8

2 files changed

Lines changed: 161 additions & 44 deletions

File tree

‎docs/csm-module-skill.md‎

Lines changed: 82 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
| 章节 | 是否必须 | 说明 |
3535
| --- | --- | --- |
3636
| **功能简述** | ✅ 必须 | 1～3 句话。模块做什么？ |
37+
| **模块信息** | ✅ 必须 | LabVIEW 版本、操作系统、RT 支持等元数据 |
3738
| **依赖项** | ✅ 必须 | CSM 核心框架 + 所需插件 |
3839
| **API 接口** | ✅ 必须 | 模块接受的所有 `API:` 消息 |
3940
| **状态广播接口** | ✅ 如果模块有广播 | 所有 `Status`/`Interrupt` 广播 |
@@ -43,6 +44,34 @@
4344
| **模块交互图** | 可选 | 展示消息流的 Mermaid `stateDiagram-v2` |
4445
| **备注** | 可选 | 实现说明和已知限制 |
4546

47+
### 3.1 模块信息格式
48+
49+
使用表格列出模块的运行环境元数据：
50+
51+
```markdown
52+
## 模块信息
53+
54+
| 属性 | 值 |
55+
| --- | --- |
56+
| LabVIEW 版本 | ≥ [版本号，例如 2019] |
57+
| 支持的操作系统 | [Windows / Linux / macOS] |
58+
| 支持 RT | [✅ 支持 / ❌ 不支持] |
59+
| 支持 64-bit | [✅ 支持 / ❌ 不支持] |
60+
```
61+
62+
### 3.2 依赖项格式
63+
64+
使用 2 列表格（依赖名含链接，类型列标注必须/可选）：
65+
66+
```markdown
67+
## 依赖项
68+
69+
| 依赖 | 类型 |
70+
| --- | --- |
71+
| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 |
72+
| [CSM-API-String-Arguments-Support](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | 可选 |
73+
```
74+
4675
---
4776

4877
## 4. API 接口规则
@@ -53,21 +82,42 @@
5382
- 或**没有 `:` 分割的非内置 case 分支**（例如用户自定义的 `ReadData`、`GetValue`）。
5483
- **不要**将内置系统状态（`Macro: Initialize`、`Macro: Exit`、`Error Handler`、`Response`、`Async Response` 等）记录为 API，除非它们是有意公开的。
5584

56-
### 4.2 表格列说明
85+
### 4.2 接口描述格式
86+
87+
每个 API 使用独立的三级段落（`###`），按以下结构填写：
5788

58-
| **API** | **描述** | **参数数据类型** | **参数描述** | **响应数据类型** | **响应描述** |
59-
| --- | --- | --- | --- | --- | --- |
60-
| 完整消息字符串，包含前缀，例如 `` `API: Start` `` | 一句话说明该 API 的作用 | 参数的数据类型（例如 `APIString`、`MassData`、`${FilePath}` 等）。无参数时写 `N/A`。 | `>>` 之后传递的数据含义。无参数时写 `N/A`。 | 响应的数据类型。无响应或异步调用时写 `N/A`。 | 模块返回内容的含义。无响应或异步调用时写 `N/A`。 |
89+
````markdown
90+
### `API: 名称`
91+
92+
一句话说明该 API 的作用。
93+
94+
- **参数**：`[CSM参数类型]` — `[数据类型]`：[数据描述]。无参数时写 `N/A`。
95+
- **响应**：`[CSM参数类型]` — `[数据类型]`：[数据描述]。无响应时写 `N/A`。
96+
````
97+
98+
对于包含多个字段的复合数据（如 Cluster），使用子列表展开：
99+
100+
````markdown
101+
- **参数**：`HexStr` — `Cluster`：
102+
- `Flag`：Boolean
103+
- `Level`：DBL
104+
````
61105

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

64-
始终在值描述之后用括号注明类型：
108+
每个 `**参数**` / `**响应**` 行按以下模式填写：
65109

66110
```text
67-
数据文件夹的完整路径 (APIString)
68-
一维波形数组 (MassData)
69-
包含配置的簇 (HexStr)
70-
文件路径 (SafeStr) ← 由 INI 静态变量 `${FilePath}` 提供
111+
`[CSM参数类型]` — `[数据类型]`：[数据描述]
112+
```
113+
114+
示例：
115+
116+
```text
117+
`APIString` — `String`：配置文件路径
118+
`MassData` — `Waveform[]`：一维波形数组
119+
`HexStr` — `Cluster`：（见子列表）
120+
`SafeStr` — `String`：经 %[HEX] 编码的文件路径
71121
```
72122

73123
支持的类型：
@@ -91,14 +141,19 @@
91141
| `Status` | 正常的、预期中的状态转换（例如"Acquired Waveform"、"Logging Complete"） |
92142
| `Interrupt` | 需要立即处理的错误、警告或事件 |
93143

94-
### 5.2 表格列说明
144+
### 5.2 接口描述格式
95145

96-
| 列 | 填写内容 |
97-
| --- | --- |
98-
| **状态** | 精确的状态字符串，例如 `` `Acquired Waveform` `` |
99-
| **广播类型** | `Status` 或 `Interrupt` |
100-
| **描述** | 一句话说明该广播何时发出 |
101-
| **参数** | 广播携带的数据，包含类型标注。无参数时写 `N/A`。 |
146+
每个状态广播使用独立的三级段落（`###`），按以下结构填写：
147+
148+
````markdown
149+
### `状态名称`
150+
151+
**广播类型**：`Status` 或 `Interrupt`
152+
153+
一句话说明该广播何时发出。
154+
155+
- **参数**：广播携带的数据，包含类型标注。无参数时写 `N/A`。
156+
````
102157

103158
### 5.3 订阅语法示例
104159

@@ -229,10 +284,12 @@ direction LR
229284

230285
- [ ] 文件名与模块 VI 名称一致。
231286
- [ ] 功能简述在 ≤ 3 句话内回答"这个模块做什么？"。
232-
- [ ] 每一个 `API:` case 分支都列在 API 表中。
233-
- [ ] 参数类型使用标准标注格式（例如 `(APIString)`、`(MassData)`）。
234-
- [ ] 所有 `Status`/`Interrupt` 广播都列在状态广播表中。
235-
- [ ] 每行明确标注广播类型为 `Status` 或 `Interrupt`。
287+
- [ ] 模块信息表包含 LabVIEW 版本、操作系统、RT 支持和 64-bit 支持。
288+
- [ ] 依赖项使用 2 列表格（链接名 + 类型）。
289+
- [ ] 每一个 `API:` case 分支都有独立的三级段落（`###`）。
290+
- [ ] 每个 API 段落包含描述、`**参数**` 和 `**响应**` 字段（含 CSM 参数类型和数据描述）。
291+
- [ ] 所有 `Status`/`Interrupt` 广播都有独立的三级段落（`###`）。
292+
- [ ] 每个广播段落明确标注广播类型为 `Status` 或 `Interrupt`。
236293
- [ ] 配置说明涵盖所有前面板控件和 INI 键值。
237294
- [ ] 调用限制说明包含初始化顺序和任何单例规则。
238295
- [ ] 至少包含一个带注释的使用示例。
@@ -247,11 +304,13 @@ direction LR
247304
| 错误 | 正确做法 |
248305
| --- | --- |
249306
| 将内部状态记录为 API | 只记录 API case（包括以 `API:` 为前缀的 case 和无 `:` 分隔的非内置 case） |
250-
| 省略参数类型 | 始终在参数列写 `(类型)` |
251-
| 同步/异步箭头用错 | 同步：`-@`，异步：`->`，无应答：`->|` |
307+
| 用表格列出 API 或广播 | 每个 API / 广播使用独立的 `###` 段落，描述在段落正文中 |
308+
| 参数只写描述，不写 CSM 参数类型 | 始终使用 `` `[CSM参数类型]` — `[数据类型]`：[描述] `` 格式 |
309+
| 复合数据只写数据类型，不展开字段 | 使用子列表逐一列出 Cluster 的每个字段及其类型 |
252310
| 订阅时忘写 `@模块名` | 始终使用 `Status@源模块 >> API:Handler@目标模块 -><register>` |
253-
| 空单元格不写 N/A | 无参数或无响应时明确写 `N/A` |
311+
| 无参数或无响应时留空 | 明确写 `N/A` |
254312
| 使用 VI 文件名代替运行时模块名 | 模块名是启动时传入的字符串；在文档中说明这一区别 |
313+
| 依赖项使用 3 列表格或项目列表 | 改用 2 列表格（依赖名含链接 + 类型） |
255314

256315
---
257316

‎module-template.md‎

Lines changed: 79 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,27 @@
1616

1717
---
1818

19+
## 模块信息
20+
21+
| 属性 | 值 |
22+
| --- | --- |
23+
| LabVIEW 版本 | ≥ [版本号，例如 2019] |
24+
| 支持的操作系统 | [Windows / Linux / macOS] |
25+
| 支持 RT | [✅ 支持 / ❌ 不支持] |
26+
| 支持 64-bit | [✅ 支持 / ❌ 不支持] |
27+
28+
---
29+
1930
## 依赖项
2031

21-
| 依赖 | 类型 | 链接 |
22-
| --- | --- | --- |
23-
| Communicable State Machine (CSM) | 必须 | [GitHub](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) |
24-
| CSM API String Arguments Support | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) |
25-
| CSM MassData Parameter Support | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-MassData-Parameter-Support) |
26-
| CSM INI Static Variable Support | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-INI-Static-Variable-Support) |
27-
| CSM Mermaid Plugin | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-Mermaid-Plugin) |
28-
| CSM TCP Router | 可选 | [GitHub](https://github.com/NEVSTOP-LAB/CSM-TCP-Router-App) |
32+
| 依赖 | 类型 |
33+
| --- | --- |
34+
| [Communicable-State-Machine](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) | 必须 |
35+
| [CSM-API-String-Arguments-Support](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support) | 可选 |
36+
| [CSM-MassData-Parameter-Support](https://github.com/NEVSTOP-LAB/CSM-MassData-Parameter-Support) | 可选 |
37+
| [CSM-INI-Static-Variable-Support](https://github.com/NEVSTOP-LAB/CSM-INI-Static-Variable-Support) | 可选 |
38+
| [CSM-Mermaid-Plugin](https://github.com/NEVSTOP-LAB/CSM-Mermaid-Plugin) | 可选 |
39+
| [CSM-TCP-Router-App](https://github.com/NEVSTOP-LAB/CSM-TCP-Router-App) | 可选 |
2940

3041
> 删除不需要的行。
3142
@@ -35,16 +46,51 @@
3546

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

38-
| API | 描述 | 参数数据类型 | 参数描述 | 响应数据类型 | 响应描述 |
39-
| --- | --- | --- | --- | --- | --- |
40-
| `API: Initialize` | 初始化内部资源。必须在其他 API 之前调用。 | `APIString` | 配置文件路径 | N/A | N/A |
41-
| `API: Start` | 启动模块的主要操作。 | N/A | N/A | N/A | N/A |
42-
| `API: Stop` | 优雅地停止主要操作。 | N/A | N/A | N/A | N/A |
43-
| `API: [示例：传递结构体数据]` | [描述] | `HexStr` | 配置簇 | N/A | N/A |
44-
| `API: [示例：传递大块数据]` | [描述] | `MassData` | 一维波形数组 | N/A | N/A |
45-
| `API: Get Status` | 查询当前状态。 | N/A | N/A | `APIString` | 状态描述 |
49+
### `API: Initialize`
50+
51+
初始化内部资源。必须在其他 API 之前调用。
52+
53+
- **参数**：`APIString` — `String`：配置文件路径
54+
- **响应**：N/A
55+
56+
### `API: Start`
57+
58+
启动模块的主要操作。
59+
60+
- **参数**：N/A
61+
- **响应**：N/A
62+
63+
### `API: Stop`
64+
65+
优雅地停止主要操作。
66+
67+
- **参数**：N/A
68+
- **响应**：N/A
69+
70+
### `API: [示例：传递结构体数据]`
71+
72+
[描述]
4673

47-
> 根据需要增减行。请记录每一个对外可调用的 `API:` 消息。
74+
- **参数**：`HexStr` — `Cluster`：
75+
- `[字段名]`：[类型，例如 Boolean]
76+
- `[字段名]`：[类型，例如 DBL]
77+
- **响应**：N/A
78+
79+
### `API: [示例：传递大块数据]`
80+
81+
[描述]
82+
83+
- **参数**：`MassData` — `Waveform[]`：一维波形数组
84+
- **响应**：N/A
85+
86+
### `API: Get Status`
87+
88+
查询当前状态。
89+
90+
- **参数**：N/A
91+
- **响应**：`APIString` — `String`：状态描述
92+
93+
> 根据需要增减段落。请记录每一个对外可调用的 `API:` 消息。
4894
4995
### 参数类型说明
5096

@@ -62,10 +108,22 @@
62108

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

65-
| 状态 | 广播类型 | 描述 | 参数数据类型 | 参数描述 |
66-
| --- | --- | --- | --- | --- |
67-
| `[状态名称 A]` | `Status` | [发生了什么 / 哪些数据已就绪] | `HexStr` | 数据内容 |
68-
| `[状态名称 B]` | `Interrupt` | [错误或需要立即处理的中断事件描述] | `APIString` | 错误信息 |
111+
### `[状态名称 A]`
112+
113+
**广播类型**：`Status`
114+
115+
[发生了什么 / 哪些数据已就绪]
116+
117+
- **参数**：`HexStr` — `Cluster`：
118+
- `[字段名]`：[类型，例如 DBL]
119+
120+
### `[状态名称 B]`
121+
122+
**广播类型**：`Interrupt`
123+
124+
[错误或需要立即处理的中断事件描述]
125+
126+
- **参数**：`APIString` — `String`：错误信息
69127

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

0 commit comments

Comments
 (0)