docs: update skills

Author: OpportunityLiu

skills/mirascript-cli/SKILL.md

@@ -1,192 +1,127 @@
 ---
 name: mirascript-cli
-description: Guide AI to use MiraScript CLI to run and format MiraScript code
-author: CloudPSS
-license: MIT
+description: 使用官方 MiraScript CLI 运行、验证、调试和格式化 MiraScript 脚本或模板。需要执行 .mira/.miratpl 文件、验证生成的代码片段、注入变量、检查 CLI 错误、进入 REPL，或安全地预览及写回格式化结果时使用。
 ---
 
-# MiraScript CLI 技能
+# 使用 MiraScript CLI
 
-MiraScript CLI 是验证、运行和格式化 MiraScript 代码的官方命令行工具。本技能指导 AI **在生成代码后主动使用 CLI 验证代码正确性并根据错误迭代修复**。
+## 选择调用方式
 
-## When to use
+优先使用目标项目已固定的版本：
 
-当需要执行、验证或格式化 MiraScript 代码时使用本技能，尤其是在生成代码后应立即用 CLI 进行验证。
-
----
-
-## 安装与调用方式
-
-无需全局安装，可直接通过包管理器调用最新版本：
-
-```sh
-# 推荐方式（三选一）
-npx @mirascript/cli <command>
-pnpm dlx @mirascript/cli <command>
-yarn dlx @mirascript/cli <command>
+```powershell
+pnpm exec mirascript --version
 ```
 
-若已在本地项目安装（`devDependencies`），则直接使用：
+按以下顺序选择命令：
 
-```sh
-npx mirascript <command>
-```
-
----
+1. 在已安装 `@mirascript/cli` 的 pnpm 项目中使用 `pnpm exec mirascript`。
+2. 已有全局或环境提供的二进制时使用 `mirascript`。
+3. 项目未安装 CLI 且允许联网下载时，使用 `pnpm dlx @mirascript/cli` 或 `npx --package=@mirascript/cli mirascript`。不要仅为验证代码擅自修改项目依赖。
 
-## 命令：`run`（默认命令）
+后文用 `pnpm exec mirascript` 展示命令；若选择了其他入口，保持子命令和参数不变。在自动化流程中始终传入脚本、`--eval` 或子命令，避免无意进入交互式 REPL。
 
-执行 MiraScript 脚本，是 CLI 的默认命令（可省略 `run`）。
+## 运行与验证
 
-### 语法
+运行脚本文件：
 
-```sh
-mirascript run [options] [script]
-# 或省略 run：
-mirascript [options] [script]
+```powershell
+pnpm exec mirascript run script.mira
 ```
 
-### 选项
-
-| 选项                       | 说明                                             |
-| -------------------------- | ------------------------------------------------ |
-| `-e, --eval <script>`      | 直接执行字符串代码（不传文件路径时使用）         |
-| `-v, --variable <key=val>` | 设置全局变量，值支持 MiraScript 表达式；可多次用 |
-| `-t, --template`           | 以模板模式运行（`.miratpl` 文件或模板字符串）    |
-| `--no-template`            | 强制以脚本模式运行                               |
-| `--timeout <ms>`           | 执行超时时间（毫秒），`0` 表示不超时，默认 3000  |
+`run` 是默认子命令，因此也可写 `pnpm exec mirascript script.mira`。显式写出 `run` 可让自动化日志更清楚。
 
-### 示例
+对不含复杂 shell 字符的短代码使用 `--eval`：
 
-```sh
-# 执行脚本文件
-mirascript script.mira
+```powershell
+pnpm exec mirascript run --eval 'let x = 1 + 2; x'
+```
 
-# 执行内联代码片段（AI 验证代码的主要方式）
-mirascript -e "let x = 1 + 2; debug_print(x)"
+对多行代码、插值或复杂引号优先使用 stdin。PowerShell 使用单引号 here-string，防止 PowerShell 展开 MiraScript 的 `$`：
 
-# 使用标准输入传递多行代码（script 为 -）
-mirascript - <<EOF
+```powershell
+@'
 fn factorial(n) {
-  if n <= 1 { return 1; }
-  n * factorial(n - 1)
+  if n <= 1 { 1 } else { n * factorial(n - 1) }
 }
-factorial(10)
-EOF
-
-# 带变量执行
-mirascript -e "debug_print(name)" -v "name='Alice'"
-
-# 变量值为 MiraScript 表达式
-mirascript -e "debug_print(data::map(fn { it * 2 }))" -v "data=[1,2,3]"
-
-# 模板模式执行文件
-mirascript --template template.miratpl
-
-# 不超时执行（长计算）
-mirascript --timeout 0 heavy.mira
+factorial(5)
+'@ | pnpm exec mirascript run -
 ```
 
-### 输出行为
-
-- **脚本模式**：打印最终表达式的值（格式化后）
-- **模板模式**：打印渲染结果字符串
-- **错误**：错误信息输出到 stderr，退出码 `2`；文件不存在退出码 `2`，权限不足退出码 `3`
-
----
-
-## 命令：`format`
-
-格式化 MiraScript 脚本文件。
-
-### 语法
+POSIX shell 使用带引号的 heredoc：
 
 ```sh
-mirascript format [options] <script...>
+pnpm exec mirascript run - <<'MIRA'
+let values = [1, 2, 3];
+values::map(fn { it * 2 })
+MIRA
 ```
 
-`<script...>` 支持多个文件路径、glob 模式，或 `-` 表示从标准输入读取。
+脚本模式会在 stdout 打印最后表达式的值，`debug_print` 会产生额外输出。验证时同时检查退出码、stderr 和预期 stdout；不要只检查“命令有输出”。
 
-### 选项
+### 常用运行选项
 
-| 选项             | 说明                                          |
-| ---------------- | --------------------------------------------- |
-| `-w, --write`    | 直接将格式化结果写回文件（否则输出到 stdout） |
-| `-t, --template` | 对无法通过扩展名推断类型的文件使用模板模式    |
+| 选项                         | 用途                                                     |
+| ---------------------------- | -------------------------------------------------------- |
+| `-e, --eval <script>`        | 执行内联脚本；不可同时传脚本路径                         |
+| `-v, --variable <key=value>` | 注入全局变量；可重复使用，值优先按 MiraScript 表达式解析 |
+| `-t, --template`             | 对 `--eval`、stdin 或需强制覆盖的输入启用模板模式        |
+| `--no-template`              | 即使文件名为 `.miratpl` 也强制使用脚本模式               |
+| `--timeout <ms>`             | 设置检查点超时；默认 3000，`0` 表示不超时                |
 
-### 示例
+```powershell
+pnpm exec mirascript run script.mira --variable "name='Mira'" --variable 'count=3'
+pnpm exec mirascript run --template --eval 'Hello, $name!' --variable "name='World'"
+```
 
-```sh
-# 检查格式化结果（输出到 stdout，不修改文件）
-mirascript format script.mira
+运行文件时会根据 `.miratpl` 扩展名自动选择模板模式；对 stdin 和 `--eval` 必须显式传 `--template`。仅对可信且确定会终止的代码使用 `--timeout 0`。
 
-# 直接格式化并写回文件
-mirascript format -w script.mira
+## 格式化
 
-# 格式化目录下所有 .mira 文件
-mirascript format -w "src/**/*.mira"
+先预览，再决定是否写回：
 
-# 从 stdin 格式化（管道）
-echo 'let x=1+2' | mirascript format -
+```powershell
+pnpm exec mirascript format script.mira
+pnpm exec mirascript format --write script.mira
 ```
 
----
-
-## AI 工作流：生成→验证→迭代
+不带 `--write` 时，文件输入的格式化结果写到 stdout，并带 `// File: ...` 标题；不会执行专用的 check 模式。从 stdin 格式化时只输出格式化后的代码：
 
-**生成 MiraScript 代码后，必须遵循以下验证流程：**
-
-### 1. 语法与运行时验证
+```powershell
+@'
+let x=1+2;
+x
+'@ | pnpm exec mirascript format -
+```
 
-使用 `run -e` / `run -` 验证代码片段：
+为模板格式化显式传 `--template`：
 
-```sh
-npx mirascript -e "<生成的代码>"
+```powershell
+pnpm exec mirascript format --template template.miratpl
 ```
 
-**注意**：`-e` 传入的代码会被当作完整脚本执行，最后一个表达式的值会被打印。
-
-### 2. 解读错误并修复
+当前 `format` 实现不会像 `run` 那样根据 `.miratpl` 文件名切换输入模式。对多个文件或 glob，把模式作为单个参数交给 CLI，并在 `--write` 后检查实际改动：
 
-根据错误信息定位问题，修改代码后重新验证，直到运行成功。
+```powershell
+pnpm exec mirascript format --write 'src/**/*.mira'
+```
 
-### 3. 典型验证场景
+不要对超出任务范围的宽泛 glob 使用 `--write`。格式化时还要检查 stderr 和匹配到的文件；无匹配项或个别文件格式化失败时，退出码本身不足以证明全部成功。
 
-```sh
-# 验证函数定义和调用
-mirascript - <<EOF
-fn factorial(n) {
-  if n <= 1 { return 1; }
-  n * factorial(n - 1)
-}
-factorial(10)
-EOF
+## REPL
 
-# 验证带变量的逻辑
-mirascript - <<EOF
-let items = [1, 2, 3, 4, 5];
-items::filter(fn { it > 2 })::map(fn { it * 2 })
-EOF
+仅在用户需要交互探索时运行：
 
-# 验证模板
-mirascript --template -e "Hello, \${name}!" -v "name='World'"
+```powershell
+pnpm exec mirascript repl
 ```
 
-### 4. 常见错误代码
-
-| 退出码 | 含义                        |
-| ------ | --------------------------- |
-| `0`    | 成功                        |
-| `1`    | 内部错误                    |
-| `2`    | 语法/运行时错误或文件不存在 |
-| `3`    | 权限不足                    |
-
-退出码非 `0` 时必须检查 stderr 输出并修复。
-
----
+没有脚本路径和 `--eval` 的默认 `run` 也会进入 REPL。不要在非交互验证或 CI 中这样调用。
 
-## 注意事项
+## 错误处理与完成标准
 
-- **多行代码**：在 shell 中传递多行代码时，使用 heredoc；在 PowerShell 中使用 `echo @''@| mirascript -` 避免 `npx` 传递参数错误
-- **引号转义**：`-v` 中的字符串字面量须注意 shell 引号转义，优先使用逐字字符串 `@"..."@` 避免转义冲突
-- **超时限制**：默认超时 3000ms，复杂算法或循环测试时加 `--timeout 0`
+- 退出码 `0` 表示命令进程成功；运行时编译或执行错误通常为 `2`，权限错误为 `3`，其他访问、内部或 stdin 格式化错误可能为 `1`。多文件格式化可能只记录单个文件的失败，因此仍要检查 stderr。
+- 根据错误中的文件名、行列和诊断信息修复代码，并重新执行同一代表性输入。
+- 对 `--variable` 解析、模板渲染、超时和宿主全局等行为分别保留针对性用例。
+- 只有在退出码、stderr 和实际输出都符合预期后，才报告运行验证通过。
+- 格式化写回后检查 diff，确认只修改了预期文件且语义未改变。

skills/mirascript-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'MiraScript CLI'
+  short_description: 'Run, validate, and format MiraScript code'
+  default_prompt: 'Use $mirascript-cli to run and validate this MiraScript code.'