# OpenMesh Skills 撰写规范

本文档定义了 OpenMesh Skills 的撰写标准，确保模型能够正确理解和使用技能。

---

## 一、文件结构规范

### 必需文件

每个 Skill 必须包含以下文件：

| 文件 | 用途 |
|------|------|
| `SKILL.md` | 技能的入口文档，包含元数据、使用说明、依赖、示例 |
| `LICENSE.txt` | 许可证文件（参考现有技能使用 Proprietary 许可证） |
| `scripts/` | 脚本目录，包含所有可执行脚本 |
| `scripts/*.py` | Python 脚本 |
| `scripts/*.js` 或 `*.cjs` | Node.js 脚本（可选） |

### 可选文件

| 文件 | 用途 |
|------|------|
| `reference.md` | 高级功能或详细 API 参考 |
| `forms.md` | 表单处理等特定功能的专门指南 |
| `pptxgenjs.md` | PPT 创建的专门指南 |
| `editing.md` | 编辑操作的专门指南 |

---

## 二、SKILL.md 必填结构

### 2.1 YAML 前言（必须）

```yaml
---
name: <skill-name>           # 技能名称，模型用此名称调用
description: "<触发描述>"     # 触发条件描述，模型据此决定何时使用此技能
license: Proprietary. LICENSE.txt has complete terms
metadata:
  builtin_skill_version: "1.0"  # 版本号
---
```

### 2.2 工具说明（必须）

**必须放在 YAML 前言之后、第一个标题之前：**

```markdown
> **重要：** 所有 `scripts/` 路径均相对于此技能目录。
> 运行方式：使用 `run_shell` 工具执行命令，例如：
> ```bash
> cd {skill_dir} && python scripts/example.py arg1 arg2
> ```
> `run_shell` 不支持 `cwd` 参数，必须使用 `cd` 命令切换目录。
```

**禁止使用以下不存在的工具名称：**
- ❌ `execute_shell_command`
- ❌ `run_shell_command`
- ❌ `execute_shell`
- ❌ 任何未在 OpenMesh 中注册的工具名

**禁止使用以下不存在的参数：**
- ❌ `cwd` — `run_shell` 不支持此参数，必须用 `cd` 命令切换目录
- ✅ `command` — 命令字符串（必填）
- ✅ `description` — 简短描述（可选）
- ✅ `timeout_seconds` — 超时秒数（可选，默认 120 秒）
- ✅ `run_in_background` — 后台运行（可选）

### 2.3 前置依赖说明

列出所有依赖，并注明：
- 依赖是否已在打包环境中可用
- 如何检测依赖是否存在
- 缺失时的处理方式

```markdown
## 前置依赖

- **pypdf**：PDF 读写（打包环境中已包含）
- **pptxgenjs**（`npm`）：从零创建 PPT（打包环境中已包含）
- **LibreOffice**（`soffice`）：PDF 转换（打包环境中已包含）
- **pandoc**：文档格式转换（打包环境中已包含）

如果某依赖缺失，请报告依赖问题并停止（不要反复重试）。
```

### 2.4 快速参考

提供表格形式的快速命令索引：

```markdown
## 快速参考

| 任务 | 方法 |
|------|------|
| 读取文件 | `python scripts/read.py file.ext` |
| 编辑文件 | 解压 → 编辑 → 打包（见下方详细流程） |
| 验证输出 | `python scripts/validate.py output.ext` |
```

### 2.5 详细使用说明

按功能模块组织，每个模块包含：
- **用途说明**
- **输入/输出**
- **命令示例**
- **注意事项**

### 2.6 常见错误与解决方案

列出常见问题和解决方法：

```markdown
## 常见问题

### 问题 1：XXX 错误
**原因：** ...
**解决：** ...
```

---

## 三、脚本规范

### 3.1 Python 脚本

#### 命名
- 使用小写下划线命名：`create_document.py`、`parse_content.py`
- 避免使用大写或驼峰命名

#### 入口模式
- **首选**：接受命令行参数
  ```python
  import argparse
  
  parser = argparse.ArgumentParser()
  parser.add_argument("input_file", help="输入文件路径")
  parser.add_argument("-o", "--output", default="output.ext", help="输出文件路径")
  args = parser.parse_args()
  ```
- **备选**：接受 stdin 或配置文件

#### 错误处理
- 脚本失败时返回非零退出码
- 错误信息输出到 stderr
- 包含 Python 回溯但不暴露敏感信息

#### 依赖声明
- 仅使用标准库和 SKILL.md 中声明的依赖
- 不要隐式依赖未声明的库

### 3.2 Node.js 脚本

#### 入口模式
```javascript
// 接受命令行参数
const args = process.argv.slice(2);
// 或使用 yargs 等工具库
```

#### 依赖
- 所有 npm 依赖必须在 `package.json` 中声明
- 优先使用打包环境中已包含的包：
  - `docx`
  - `pptxgenjs`
  - `jszip`

### 3.3 Shell 脚本（可选）

- 优先使用 Python 或 Node.js 脚本
- Shell 脚本仅用于简单包装或命令串联

---

## 四、文档编写规范

### 4.1 代码块

**必须指定语言：**

```bash
# ✅ 正确
```bash
python script.py --input file.pdf
```

```python
# ✅ 正确
```python
from pypdf import PdfReader
```

**避免无语言代码块：**

````markdown
<!-- ❌ 错误 -->
```
python script.py
```
````

### 4.2 命令示例

所有命令行示例必须：
- 使用完整路径或相对于 `{skill_dir}` 的路径
- 包含输入输出参数说明
- 示例输出（如果有助于理解）

### 4.3 绝对路径 vs 相对路径

| 场景 | 写法 |
|------|------|
| SKILL.md 中描述脚本位置 | `{skill_dir}/scripts/example.py` |
| 模型实际执行命令 | `cd {skill_dir} && python scripts/example.py` |
| 用户文件（不确定位置） | 使用传入的参数，示例用 `./input.ext` |

### 4.4 链接

引用同技能的其他文档：

```markdown
详细说明请参阅 [editing.md](editing.md)。
```

引用外部资源：

```markdown
PptxGenJS 文档：https://github.com/gitbrent/PptxGenJS
```

---

## 五、模型执行指引

### 5.1 正确的工具调用方式

```markdown
# 读取帮助信息
> run_shell
> command=python --help

# 执行脚本
> run_shell
> command=cd {skill_dir} && python scripts/example.py --input ./document.ext
```

### 5.2 常见任务执行流程

**流程 1：读取并分析**
```markdown
1. 使用 `read_file` 工具读取输入文件
2. 使用 `run_shell` 执行分析脚本
3. 根据分析结果规划处理步骤
```

**流程 2：创建新文件**
```markdown
1. 规划文件结构和内容
2. 编写生成脚本（Python 或 Node.js）
3. 使用 `write_file` 保存脚本
4. 使用 `run_shell` 执行脚本
5. 使用 `run_shell` 验证输出
```

**流程 3：编辑现有文件**
```markdown
1. 解包文件（如需要）
2. 使用 `read_file` 读取待编辑部分
3. 使用 `Edit` 工具修改内容
4. 重新打包（如需要）
5. 验证结果
```

### 5.3 工作目录处理

**重要：** `run_shell` 工具在 Windows 上默认使用 PowerShell，在 POSIX 上使用 bash。

```bash
# Windows 路径
cd D:\project\workspace && python script.py

# 使用绝对路径
python D:\project\workspace\scripts\script.py --input "D:\project\workspace\file.ext"
```

---

## 六、质量检查清单

完成技能编写后，检查以下各项：

### 文档检查
- [ ] YAML 前言完整（name、description、license、metadata）
- [ ] 工具说明正确（使用 `run_shell`，无错误工具名）
- [ ] 前置依赖已列出
- [ ] 快速参考表格完整
- [ ] 代码块指定了语言
- [ ] 命令示例可执行
- [ ] 链接指向正确文件

### 脚本检查
- [ ] 所有脚本有入口参数说明
- [ ] 脚本在命令行可独立运行
- [ ] 错误处理完善
- [ ] 依赖已在 SKILL.md 中声明

### 可用性检查
- [ ] 模型能正确识别何时使用此技能
- [ ] 模型能正确调用 `run_shell` 执行命令
- [ ] 模型能正确解析脚本输出
- [ ] 模型能正确处理错误情况

---

## 七、常见错误

### 错误 1：使用不存在的工具名

```markdown
<!-- ❌ 错误 -->
> 或使用 `execute_shell_command` 的 `cwd` 参数。

<!-- ✅ 正确 -->
> 运行方式：使用 `run_shell` 工具执行命令，例如：
> ```bash
> cd {skill_dir} && python scripts/example.py
> ```
```

### 错误 2：命令示例缺少上下文

```markdown
<!-- ❌ 错误 -->
```bash
python script.py
```

<!-- ✅ 正确 -->
```bash
cd {skill_dir} && python scripts/script.py --input ./document.ext
```
```

### 错误 3：依赖声明不完整

```markdown
<!-- ❌ 错误 -->
## 前置依赖
- Python 库（已包含）

<!-- ✅ 正确 -->
## 前置依赖
- **pypdf**：PDF 读写（打包环境中已包含）
- **pandas**：数据分析（打包环境中已包含）
- **openpyxl**：Excel 操作（打包环境中已包含）
```

### 错误 4：文档引用错误的文件

```markdown
<!-- ❌ 错误 -->
详细说明请参阅 [advanced.md](advanced.md)。  <!-- 文件不存在 -->

<!-- ✅ 正确 -->
详细说明请参阅 [reference.md](reference.md)。
```

---

## 八、版本规范

### 版本号格式
使用语义化版本：`major.minor.patch`

- `1.0.0` - 初始版本
- `1.1.0` - 新增功能
- `1.1.1` - Bug 修复

### 版本更新记录

在 SKILL.md 末尾添加：

```markdown
---

## 版本历史

### 1.1.0 (2024-01-15)
- 新增 XXX 功能
- 修复 YYY 问题

### 1.0.0 (2024-01-01)
- 初始版本
```