参数 $1 / $@ 与默认值

模板怎么调用

先看官方示例。模板文件 component.md，正文引用参数：

---
description: Create a component
---
Create a React component named $1 with features: $@

调用方式：

/component Button
/component Button "click handler"
/component Button "onClick handler" "disabled support"

/模板名 参数1 参数2 ...——空格分隔，多个参数用引号包裹。参数会被填进模板正文的对应占位符。

---

参数语法全家桶

官方把支持的参数语法列得很全：

写法	含义
$1, $2, ...	位置参数（第几个）
$@ 或 $ARGUMENTS	所有参数拼接
${1:-default}	参数 1 有值时用它，否则用默认值
${@:-default} 或 ${ARGUMENTS:-default}	全部参数有值时用它，否则用默认值
${@:N}	从第 N 个参数开始（从 1 计数）
${@:N:L}	从第 N 个取 L 个

对 md-tools，最常用的就是 $1（文件路径）和 ${1:-默认值}（可选的默认文件）。

---

默认值：可选参数的好帮手

官方特别强调默认值适合处理可选参数。它给的例子：

Summarize the current state in ${1:-7} bullet points.

意思是：给了参数就按参数来，没给就用 7 个要点。对我们的 md-tools 模板：

用 md-tools 检查 markdown 文件：${1:-README.md}
- 用 stats 统计字数、段落数、标题数
- 如文件不存在，提示可用文件

这样 /mdcheck 默认检查 README.md，/mdcheck 别的.md 就检查别的。

---

一个完整的带参数 md-tools 模板

把前面的都串起来，一个实用的检查模板：

---
description: 用 md-tools 检查一个 markdown 文件的质量
argument-hint: "<file.md>"
---
用 md-tools 检查 markdown 文件：$1
- 用 stats 统计该文件的字数、段落数、标题数
- 输出统计结果后，指出明显的结构或格式问题

（argument-hint 会在自动补全里提示期望的参数，下一节细说。）调用：

/mdcheck README.md
/mdcheck docs/guide.md "重点看标题层级"

---

落地练习：给模板加参数

1. 在 ~/.pi/agent/prompts/mdcheck.md 写一个用 $1 引用文件名的模板
2. 分别调用 /mdcheck（无参数）和 /mdcheck 某个.md（带参数），观察展开结果
3. 给可选参数加上 ${1:-README.md} 默认值，再试一次无参调用

怎么判断做对了？——带参数时文件名填进正文，无参数时用默认值；两次展开的提示词不同且都正确。

卡住了怎么办？ 参数没替换 → 检查是不是用了 $1 且调用时写了参数。多个参数串了 → 用引号包裹 "click handler"。默认值不生效 → 确认写成 ${1:-xxx} 的完整写法。

---

常见坑：忘记「多参数要用引号」

最容易翻车的是多参数调用。官方示例里 "/component Button "click handler"" 用引号包裹了带空格的值。

记住：参数用空格分隔，含空格的参数要加引号。 否则 click handler 会被当成两个参数，填到 $1 和 $2，结果完全错位。写模板时也尽量让参数边界清晰。

---

小结

1. 调用：/模板名 参数1 参数2，多参数用引号
2. $1 位置参数、$@/$ARGUMENTS 全部参数
3. ${1:-default} 提供可选参数的默认值
4. ${@:N:L} 可做参数切片
5. 多参数记得加引号，否则会被拆开

下一节，聊聊加载规则和 argument-hint，把模板打磨到顺手。