Custom Commands
介绍
Tuanjie AI Custom Commands（自定义命令）让您能够将最常用或最喜爱的提示词保存为快捷方式。通过将复杂的提示词封装成简洁的命令，您可以大幅简化工作流程，确保团队使用统一的标准，并提高日常开发效率。
什么是 Custom Commands？
Custom Commands 是以 TOML 格式定义的可重用提示词模板。它们允许您：
- 将重复使用的复杂提示词保存为简短的命令
- 支持参数注入，使命令能够动态响应用户输入
- 执行 Shell 命令并注入结果到提示词中
- 直接嵌入文件内容到提示词中
- 创建命名空间命令，便于组织和管理
Custom Commands 的核心价值
- 提高效率：用简短的命令（如
/commit）替换冗长的提示词 - 保持一致性：确保团队使用相同的工作流程和标准
- 减少输入：避免重复输入相同的提示词内容
- 上下文感知：命令可以接收参数并动态生成提示词
- 可维护性：集中管理常用的工作流程，便于更新和共享
适合用 Custom Commands 的场景
- 经常重复使用的复杂提示词（如代码审查、提交消息生成、文档编写）
- 需要特定格式的输出（如 Conventional Commits、API 文档、测试报告）
- 团队需要统一的标准流程（如代码风格检查、安全审计）
- 需要结合 Shell 命令或文件内容的任务（如 Git 操作、文件分析）
不适合用 Custom Commands 的场景：
- 简单的一次性任务
- 需要复杂逻辑和条件判断的任务（考虑使用 Skills 或 Subagents）
- 需要持久状态的任务（考虑使用 Extension）
通过 GUI 管理 Commands
- 在对话框输入
/，在下拉菜单中选择 "Manage commands"。或者直接输入/commands。 - 在打开的对话框中，您可以查看所有可用的命令及其描述。
- 创建新的 command 后，请运行
/commands reload以加载更改。 - 在对话窗口中直接输入命令名称（如
/commit）即可执行。
创建 command 时 Project 与 Global 的区别：
- Project：该命令仅在当前项目中使用，会随项目仓库共享给团队
- Global：该命令在所有项目中都可以使用，适合个人常用的命令
通过 CLI 管理 Commands
Command 发现路径与优先级
Tuanjie AI 会自动从两个位置加载 Command，优先级从高到低：
项目命令（Project Commands）
- 路径：
.codely/commands/或.agents/commands/ - 作用：团队共享，跟随项目，优先级最高
- 可以提交到版本控制中与团队共享
用户命令（User Commands）
- 路径：
~/.codely/commands/或~/.agents/commands/ - 作用：个人全局使用，所有项目都生效
优先级规则 ：
项目命令 > 用户命令
同层级内：.agents/commands/ 优先于 .codely/commands/
Command 工作原理
- 发现：新建会话或运行
/commands reload时，Tuanjie AI 扫描所有路径，加载命令名称与描述 - 执行：用户输入命令（如
/commit），Tuanjie AI 加载对应的 TOML 文件 - 处理：解析命令中的特殊语法（
{{args}}、!{...}、@{...}） - 注入：将参数、Shell 命令输出或文件内容注入到提示词中
- 发送：将最终生成的提示词发送给 AI 模型
命令命名和命名空间
命令的名称由其文件路径相对于命令目录的位置决定。子目录用于创建命名空间命令，路径分隔符（/ 或 \）会被转换为冒号（:）。
~/.codely/commands/test.toml→ 命令/test<项目>/.codely/commands/git/commit.toml→ 命令/git:commit<项目>/.codely/commands/review/security.toml→ 命令/review:security
交互式会话内管理
在 Tuanjie AI 对话输入框中使用 /commands 系列命令：
# 列出所有可用的命令
/commands list
# 重新扫描并加载所有命令
/commands reload
如何触发并使用 Command
- 确保命令已被发现：
/commands list能看到 - 在对话中直接输入命令名称，例如：
/commit
/git:fix Button is misaligned
/review FileCommandLoader.ts --verbose - Tuanjie AI 会加载对应的 TOML 文件，处理其中的特殊语法，然后将生成的提示词发送给 AI
创建自定义 Commands
手动创建
标准目录结构
~/.codely/commands/ # 用户命令目录
├── git/
│ ├── commit.toml # Git 提交命令
│ ├── fix.toml # Git 修复命令
│ └── push.toml # Git 推送命令
├── refactor/
│ ├── pure.toml # 纯函数重构
│ └── clean.toml # 代码清理
└── test/
├── unit.toml # 单元测试
└── integration.toml # 集成测试
TOML 文件格式
命令定义文件必须使用 TOML 格式编写，并使用 .toml 文件扩展名。
基本示例：
# ~/.codely/commands/commit.toml
# 通过以下方式调用：/commit
description = "生成基于暂存更改的 Conventional Commit 提交消息。"
prompt = """
请基于以下 git diff 生成一个 Conventional Commit 提交消息：
!{git diff --staged}
提交消息格式：
<type>(<scope>): <subject>
<body>
<footer>
类型（type）必须是以下之一：
- feat: 新功能
- fix: 修复 bug
- docs: 文档更改
- style: 代码格式（不影响代码运行的变动）
- refactor: 重构（既不是新增功能，也不是修复 bug）
- perf: 性能优化
- test: 增加测试
- chore: 构建过程或辅助工具的变动
"""
必需字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| prompt | String | 执行命令时将发送给 Tuanjie AI 模型的提示词。可以是单行或多行字符串。 |
可选字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| description | String | 命令功能的简短单行描述。此文本将显示在 /help 菜单中命令的旁边。 |
参数处理
Custom Commands 支持两种强大的参数处理方法。
1. 使用 {{args}} 进行精确控制
如果您的提示词包含特殊占位符 {{args}}，CLI 会用用户在命令名后输入的文本替换该占位符。
示例：
# git/fix.toml
description = "为给定问题生成代码修复。"
prompt = "请为以下描述的问题提供代码修复：{{args}}。"
调用：/git:fix Button is misaligned
模型接收：请为以下描述的问题提供代码修复：Button is misaligned。
2. 默认参数处理
如果您的提示词不包含 {{args}}，CLI 会将用户输入的完整命令附加到提示词末尾，用两个换行符分隔。
示例：
# review.toml
description = "审查提供的代码。"
prompt = """
你是一个专业的代码审查专家。
请审查用户提供的代码，关注以下方面：
- 代码风格和格式
- 潜在的 bug
- 性能问题
- 安全漏洞
**用户的原始命令将附加在您的指令下方。**
"""
调用：/review FileCommandLoader.ts
模型接收：原始提示词 + 换行符 + FileCommandLoader.ts
执行 Shell 命令（!{...}）
您可以通过在提示词内直接执行 Shell 命令并注入其输出来使命令动态化。
工作原理：
- 使用
!{command}语法执行 Shell 命令 - 如果
{{args}}存在于块内，会自动进行 Shell 转义 - CLI 会提示您确认后再执行命令（安全措施）
- 命令输出会替换
!{...}块
示例：
# git/commit.toml
description = "基于暂存更改生成 Git 提交消息。"
prompt = """
请基于以下 git diff 生成一个 Conventional Commit 提交消息：
!{git diff --staged}
"""
调用：/git:commit
CLI 执行 git diff --staged，将输出注入到提示词中，然后发送给 AI。
安全提示： 始终确认 Shell 命令执行，避免在命令中硬编码敏感信息。
注入文件内容（@{...}）
您可以使用 @{...} 语法直接将文件或目录列表的内容嵌入到提示词中。
工作原理：
- 文件注入：
@{path/to/file.txt}被 file.txt 的内容替换 - 多模态支持：支持图像（PNG、JPEG）、PDF、音频或视频文件
- 目录列表：
@{path/to/dir}会遍历目录，插入所有文件内容 - 工作区感知：命令在当前目录和工作区目录中搜 索路径
- 处理顺序：文件注入在 Shell 命令和参数替换之前处理
示例：
# review.toml
description = "使用最佳实践指南审查提供的上下文。"
prompt = """
你是一个专业的代码审查专家。
请审查 `{{args}}`。
使用以下最佳实践进行审查：
@{docs/best-practices.md}
"""
调用：/review FileCommandLoader.ts
CLI 将 docs/best-practices.md 的内容注入到提示词中，{{args}} 替换为 FileCommandLoader.ts，然后发送给 AI。
示例：创建"纯函数"重构命令
让我们创建一个全局命令，要求模型重构一段代码为纯函数。
步骤 1：创建文件和目录
macOS/Linux:
mkdir -p ~/.codely/commands/refactor
touch ~/.codely/commands/refactor/pure.toml
Windows (PowerShell):
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codely\commands\refactor"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.codely\commands\refactor\pure.toml"
步骤 2：向文件添加内容
# ~/.codely/commands/refactor/pure.toml
# 通过以下方式调用：/refactor:pure
description = "要求模型将当前上下文重构为纯函数。"
prompt = """
请分析我在当前上下文中提供的代码。
将其重构为纯函数。
你的回复应包括：
1. 重构后的纯函数代码块。
2. 对你所做的主要更改及其如何贡献于纯度的简要解释。
纯函数的特点：
- 相同输入总是产生相同输出
- 不修改外部状态
- 没有副作用
- 不依赖外部可变状态
"""
步骤 3：运行命令
# 首先将文件添加到上下文
@my-messy-function.js
# 然后调用命令
/refactor:pure
最佳实践
- 描述优化：编写清晰、具体的描述，帮助理解命令的用途
- 组织命令：为相关命令创建子目录，使用命名空间保持结构清晰
- 参数处理：根据需要选择合适的参数处理方法（
{{args}}或默认行为） - 安全第一：始终确认 Shell 命令执行，避免硬编码敏感信息
- 文档化命令：在命令文件内添加注释，解释其用途和用法
- 版本控制：将项目命令纳入版本控制，便于团队协作
命令参考表
| 功能 | 语法 | 说明 |
|---|---|---|
| 参数注入 | {{args}} | 将用户输入注入到提示词中 |
| Shell 命令 | !{command} | 执行 shell 命令并注入输出 |
| 文件注入 | @{path} | 注入文件或目录的内容 |
| 命令分隔 | / 或 : | 创建命名空间命令 |
| 换行 | """ | 创建多行提示词 |
常见问题
如何重新加载命令？
运行 /commands reload 以在不重启 CLI 的情况下重新加载命令。
如何查看所有可用命令？
运行 /commands list 或 /help 查看所有可用命令及其描述。
项目命令可以覆盖全局命令吗？
可以。如果项目目录中的命令与用户目录中的命令同名，项目命令将优先使用。
如何删除命令？
直接删除对应的 .toml 文件，然后运行 /commands reload。
命令支持嵌套吗？
支持。您可以创建任意深度的子目录来组织命令，例如 /tools:database:migrate。
文档版本：1.0 最后更新：2026 年 3 月 26 日