forge 自定义命令（Custom Commands）完整指南：从 YAML Frontmatter 到 `＜lint＞`/`＜test＞`/`＜shell＞` 自动化工作流

人工智能AI Agent代码智能体AI 应用CLI开发工具【免费下载链接】forgecodeAI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300 models项目地址https://gitcode.com/gh_mirrors/forge39/forgecode点击查看免费下载本指南讲解在 forgecode-forge中创建与管理自定义命令的完整方法命令文件存放位置、YAML Frontmatter 与 Markdown 正文的结构规范、lint/test/shell三种自动化标签的用法以及如何通过forge list command验证命令被正确识别。读完本文你将能够为任意 forge 项目编写可复用的单步命令、多步工作流命令和带自动化检查的提交前校验命令并理解命令在源码层面的加载与优先级机制。什么是 forge 自定义命令forge 的自定义命令Custom Commands是一种模块化工作流以.md文件形式存储在项目目录中通过 YAML Frontmatter 声明命令的name与description正文部分则用 Markdown 列表描述需要执行的步骤。命令被 forge 加载后即可在会话中作为快捷指令调用用于执行 lint、测试、构建、部署、文档更新等特定任务。从源码结构看命令模型定义在 crates/forge_domain/src/command.rs一个Command结构体由三个字段组成name命令名称用于在会话中调用description命令列表中展示的简短说明promptFrontmatter 之后的 Markdown 正文作为命令执行时注入给 Agent 的提示词模板。命令文件存放位置关键前提必须将命令文件放在cwd/.forge/commands目录中其中cwd是当前 forge 项目的当前工作目录。这是 forge 发现并加载自定义命令的位置目录cwd/.forge/commands文件格式{command-name}.md示例如果项目位于/home/user/my-project命令文件应放在/home/user/my-project/.forge/commands/这一点在加载实现中有明确支撑CommandLoaderService::init见 crates/forge_services/src/command.rs会依次读取内置命令、全局目录和当前工作目录下的命令其中项目本地目录通过command_path_local()得到其实现为cwd.join(.forge/commands)见 crates/forge_domain/src/env.rs。命令放在其他位置将不会被 forge 发现。需要说明的是仓库实现还支持全局命令目录command_path()返回base_path/commands即~/forge/commandsREADME 中也确认了.forge/commands/项目级与~/forge/commands/全局两种位置见 README.md。此外README 还提供了第三种方式在forge.yaml中以内联commands:键定义命令见 README.md。加载优先级CWD 全局 内置CommandLoaderService的加载顺序与冲突解决规则是理解命令系统的关键crates/forge_services/src/command.rs先加载内置命令优先级最低例如仓库自带的 commands/github-pr-description.md 通过include_str!嵌入二进制再加载全局目录~/forge/commands下的自定义命令最后加载当前工作目录.forge/commands下的命令优先级最高resolve_command_conflicts使用 HashMap 按名称去重并保留最后一次出现的定义从而形成CWD 覆盖全局、全局覆盖内置的优先级。同名命令在项目中定义时会覆盖全局乃至内置版本。命令文件结构每个命令文件必须包含两部分YAML Frontmatter必填name命令标识符多词名称使用连字符description命令作用的说明。命令正文必填需要执行的步骤列表自动化工作流使用的特殊标签每一步的清晰指令。示例命令文件--- name: check description: Checks if the code is ready to be committed --- - Run the lint and test commands and verify if everything is fine. lintcargo nightly fmt --all; cargo nightly clippy --fix --allow-staged --allow-dirty --workspace/lint testcargo insta test --accept --unreferenceddelete/test - Fix every issue found in the process三种标签的完整示例下面的示例演示了全部三种标签类型lint、test、shell--- name: sample-command description: Sample command demonstrating the command file structure --- This is a sample command that demonstrates the structure of command files. - First step: Perform an initial action lintecho Running linting.../lint - Second step: Execute tests testecho Running tests.../test - Third step: Complete the workflow shellecho Workflow complete!/shell - Final step: Verify everything worked correctly解析机制解析由parse_command_file完成它使用gray_matter库以类型安全的反序列化方式解析 YAML Frontmatter并将 Frontmatter 之外的内容作为prompt保存crates/forge_services/src/command.rs。对应的解析测试覆盖了基础命令、多行正文与非法 Frontmatter 报错三种场景测试夹具见 crates/forge_services/src/fixtures/commands/basic.md、multiline.md 与 invalid.md。创建新命令的步骤第 1 步确定命令目的明确命令要完成什么它将执行什么任务涉及哪些步骤是否需要自动化检查或测试用户应如何处理执行结果第 2 步选择命令名称使用动词开头的名称多词命令用连字符连接好check、fixme、pr-description、run-tests差checker、fixing、PRdescription第 3 步编写命令文件在cwd/.forge/commands目录中按{command-name}.md格式创建文件。重要文件必须位于cwd/.forge/commands放在其他任何位置都不会被 forge 发现。Frontmatter--- name: your-command-name description: Clear, concise description of what this command does ---命令正文使用 Markdown 列表描述步骤。每一步应当以清晰的动作动词开头具体且可执行包含必要的上下文说明。特殊命令标签lint、test、shell三种标签用于自动化工作流分别对应三类不同的 shell 操作lint标签lint / 格式化命令lintcargo nightly fmt --all; cargo nightly clippy --fix --allow-staged --allow-dirty --workspace/linttest标签测试命令testcargo insta test --accept --unreferenceddelete/testshell标签通用 shell 命令shellrm -rf target/debug/shell标签放置规范标签应放在步骤描述之后、独占一行- Run linting and testing lintyour-lint-command/lint testyour-test-command/test命令类型简单命令Simple Commands单步或纯指令型命令--- name: fixme description: Looks for all the fixme comments in the code and attempts to fix them --- Find all the FIXME comments in source-code files and attempt to fix them.多步命令Multi-Step Commands包含多个顺序步骤的命令--- name: pr-description description: Updates the description of the PR --- - I have created a Pull Request with all the accepted changes - Understand the current PR deeply using the GH CLI and update the PR title and description - Make sure the title follows conventional commits standard - Top-level summary should contain 2-3 lines about the core functionality improvements仓库自带的 commands/github-pr-description.md 正是这类多步命令的实例它被作为内置命令嵌入应用正文中还使用了{{parameters}}模板变量语法。自动化工作流命令Automated Workflow Commands包含自动化检查的命令--- name: check description: Checks if the code is ready to be committed --- - Run the lint and test commands and verify if everything is fine. lintcargo nightly fmt --all; cargo nightly clippy --fix --allow-staged --allow-dirty --workspace/lint testcargo insta test --accept --unreferenceddelete/test - Fix every issue found in the process命令模板库简单命令模板--- name: simple-command description: Does one specific thing --- Single clear instruction or description.自动化工作流模板--- name: automated-workflow description: Runs automated checks and performs follow-up actions --- - Run automated checks lintyour-lint-command/lint testyour-test-command/test - Review and fix any issues found - Complete the workflow多步工作流模板--- name: multi-step-workflow description: Performs multiple sequential steps --- - First step with clear action - Second step with context - Third step with specific requirements - Final step with verificationGit 工作流模板--- name: git-workflow description: Performs git operations --- - Stage changes shellgit add ./shell - Run pre-commit checks lintcargo fmt --all/lint testcargo test/test - Commit with message shellgit commit -m your commit message/shell - Push to remote shellgit push/shell最佳实践命名使用小写字母用连字符分隔单词使用动词开头的名称祈使形式名称保持简短但具有描述性。描述清晰、简洁描述命令做什么而不是怎么做包含主要目的和关键产出避免实现细节。命令步骤顺序步骤使用编号列表每个步骤以动作动词开头明确具体要做什么复杂步骤包含上下文说明使用现在时态。特殊标签标签放在步骤之后、独占一行只使用lint、test、shell三种标签写入可直接执行的完整命令根据你的工作流使用合适的命令标志。常见模式Git 工作流命令--- name: commit-check description: Verifies code is ready to commit --- - Run linting and tests lintcargo fmt --all; cargo clippy --fix --allow-staged/lint testcargo test/test - Review and fix any issues - Stage all changes文档命令--- name: update-docs description: Updates documentation for recent changes --- - Review recent code changes - Identify functions or modules that need documentation - Update inline documentation comments - Regenerate any auto-generated docs - Verify documentation builds successfully清理命令--- name: cleanup description: Cleans up temporary files and artifacts --- - Remove build artifacts shellrm -rf target/debug/shell - Remove temporary files shellfind . -name *.tmp -delete/shell - Clean up dependency caches if needed - Verify the project still builds构建与部署命令--- name: build-deploy description: Builds the project and deploys to staging --- - Build the project in release mode shellcargo build --release/shell - Run integration tests testcargo test --test integration/test - Build Docker image shelldocker build -t myapp:latest ./shell - Tag image for staging shelldocker tag myapp:latest myapp:staging/shell - Push to registry shelldocker push myapp:staging/shell - Deploy to staging environment shellkubectl set image deployment/myapp myappmyapp:staging/shell验证清单编写完成后用以下清单逐项检查命令是否完整正确文件结构文件位于cwd/.forge/commands目录关键文件名与命令名一致例如name: check对应check.md文件扩展名为.mdYAML Frontmatter 使用---分隔符Frontmatter存在name字段name使用小写字母name多词时使用连字符name为动词开头祈使形式存在description字段description清晰简洁description描述做什么而非怎么做命令正文至少定义了一个步骤步骤使用项目符号-每个步骤以动作动词开头步骤具体且可执行复杂步骤包含上下文步骤按逻辑顺序排列特殊标签标签位于步骤描述之后、独占一行只使用合法标签lint、test、shell标签内命令完整可执行标签命令使用了合适的标志标签命令格式正确内容质量命令名称具有描述性步骤清晰无歧义无冗余或重复步骤步骤符合逻辑顺序特殊需求已记录已考虑错误处理测试命令可以成功执行所有步骤按预期完成特殊标签正常工作输出符合预期边界情况已处理命令被 forge 识别运行forge list command --custom或forge list cmd并确认命令出现在列表中常见错误与规避Frontmatter 错误错误分隔符不完整缺少结尾------ name: my-command description: My command正确写法--- name: my-command description: My command ---错误缺少必填字段缺少description--- name: my-command ---正确写法--- name: my-command description: Does something useful ---命名错误错误CamelCase 命名--- name: myCommand description: Does something ---正确写法使用连字符--- name: my-command description: Does something ---错误名词而非动词--- name: checker description: Checks something ---正确写法使用动词--- name: check description: Checks something ---步骤错误错误步骤无动作动词--- name: test description: Runs tests --- - The tests - The code正确写法--- name: test description: Runs tests --- - Run all tests - Verify code quality错误步骤过于模糊--- name: deploy description: Deploys application --- - Do the deployment - Make sure it works正确写法具体、可执行--- name: deploy description: Deploys application to production --- - Build the Docker image shelldocker build -t myapp:latest ./shell - Push to registry shelldocker push myapp:latest/shell - Deploy to production shellkubectl set image deployment/myapp myappmyapp:latest/shell - Verify deployment is healthy标签错误错误标签与步骤同行- Run tests testcargo test/test正确写法标签独占一行- Run tests testcargo test/test错误使用非法标签check不是合法标签- Run checks checkcargo clippy/check正确写法- Run checks lintcargo clippy/lint错误命令不完整缺少--all标志- Format code lintcargo fmt/lint正确写法- Format code lintcargo fmt --all/lint快速参考文件位置目录cwd/.forge/commandscwd为当前工作目录格式{command-name}.md关键命令必须放在该确切位置才会被 forge 发现合法标签lint用于 lint / 格式化命令test用于测试命令shell用于其他通用 shell 命令命名规则仅使用小写字母多词名称用连字符动词开头祈使形式简短但具有描述性步骤编写准则以动作动词开头具体明确复杂步骤包含上下文使用现在时态保持步骤聚焦标签使用时机运行格式化或 lint 工具时使用lint运行测试套件时使用test其他 shell 命令使用shell标签放在步骤描述之后、独占一行如果步骤只是指令不要使用标签测试你的命令创建命令后按以下流程测试1. 语法检查验证 YAML 是否合法# 如果安装了 yamllint yamllint path/to/your-command.md2. 手动审查通读命令内容每个步骤是否合理顺序是否符合逻辑所有命令是否完整3. 执行测试运行命令每个步骤是否成功执行输出是否符合预期是否有报错4. forge 识别测试验证命令被 forge 识别# 方式一列出所有命令自定义命令标记为 type: custom forge list command # 方式二只列出自定义命令 forge list cmd # 方式三只列出自定义命令新版本 forge list command --custom命令是否出现在列表中名称是否正确描述是否正确从 CLI 定义看crates/forge_main/src/cli.rsforge cmd命令组带有command、commands别名其子命令包含List与Executecrates/forge_main/src/cli.rs因此forge list command、forge cmd list、forge command list --custom都是有效的识别验证方式此外还可以通过forge cmd execute custom-command arg1 arg2直接执行自定义命令并传入参数。5. 边界情况考虑异常场景某一步失败会发生什么如果环境不同会怎样如果文件缺失会怎样创建后的验证步骤创建命令后完成以下验证验证文件位置确认文件在cwd/.forge/commands目录中关键——放在其他位置的命令不会被找到检查 YAML Frontmatter 合法使用---分隔符确保命令名称与文件名一致不含.md后缀验证命令被 forge 识别# 方式一列出所有命令自定义命令标记为 type: custom forge list command # 方式二只列出自定义命令 forge list cmd # 方式三只列出自定义命令新版本 forge list command --custom新命令应连同名称与描述一起出现在列表中。测试命令按预期工作验证特殊标签格式正确。如果命令没有出现在列表中按顺序检查文件位置文件必须在cwd/.forge/commands目录这是最常见的问题文件名与 Frontmatter 中的name字段一致YAML Frontmatter 使用---分隔符且格式正确name与description两个字段都存在。深入命令加载的源码链路理解命令系统的底层机制有助于排查问题。从源码可以看到完整的加载链路入口CommandLoaderService::get_commands通过cache_or_init做一次性缓存加载crates/forge_services/src/command.rs命令在同一会话内保持有效扫描init_command_dir使用DirectoryReaderInfra::read_directory_files(dir, Some(*.md))并行读取目录下所有.md文件并以文件名不含后缀作为命令名解析parse_command_file通过gray_matter解析 YAML Frontmatter 生成Command名称、描述、提示词正文解析失败会以Failed to parse command: name报错合并内置命令、全局命令、CWD 命令依次合并同名冲突时保留最后加载者即 CWD 优先调用命令通过forge cmd execute name或会话内快捷方式执行Execute子命令允许追加任意参数crates/forge_main/src/cli.rs。仓库单元测试对以上行为均有覆盖test_parse_basic_command、test_parse_command_with_multiline_prompt、test_parse_invalid_frontmatter验证了解析逻辑test_resolve_command_conflicts_with_duplicates与test_resolve_command_conflicts_multiple_duplicates验证了 CWD 覆盖全局、全局覆盖内置的优先级规则。结语自定义命令是 forge 将重复性开发流程固化为可复用工作流的核心机制。掌握cwd/.forge/commands目录约定、YAML Frontmatter 结构、lint/test/shell三类自动化标签以及forge list command --custom的验证方法即可为团队沉淀一套标准化的代码检查、构建部署与文档维护流程。遇到命令未被识别时优先检查文件是否位于.forge/commands目录、文件名与name字段是否一致、Frontmatter 是否完整——这三个原因覆盖了绝大多数故障场景。赞分享人工智能AI Agent代码智能体AI 应用CLI开发工具【免费下载链接】forgecodeAI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300 models项目地址https://gitcode.com/gh_mirrors/forge39/forgecode点击查看免费下载相关推荐ServerBox 自定义命令Custom Commands完整指南在服务器详情页展示任意 Shell 命令输出ServerBox 自定义命令Custom Commands完整指南在服务器详情页展示任意 Shell 命令输出 导读 ServerBox本仓库 Git运维观测指标监控监控大盘运维Reactotron 自定义命令Custom Commands完全指南从注册、传参到桌面端触发的实战解析Reactotron 自定义命令Custom Commands完全指南从注册、传参到桌面端触发的实战解析 Reactotron 允许开发者注册自定义命令开发工具Slate 命令Commands体系详解从内置命令到自定义命令与 Transforms 的完整实战Slate 命令Commands体系详解从内置命令到自定义命令与 Transforms 的完整实战 在 Slate 中用户的一切富文本编辑行为——插入文前端富文本UI组件上一篇如何快速实现 Vue 电子签名功能超简单的 canvas 手写签字组件教程下一篇Firebase移动端适配终极指南PWA与响应式设计完美实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考