跳到主要内容

Sub Command

功能概述：Sub Command是iFlow CLI的命令扩展系统，可以从在线市场安装和管理专业化的斜杠命令。
学习时间：10-15分钟
前置要求：已安装iFlow CLI，完成身份验证，了解基本的斜杠命令使用

什么是Sub Command​

Sub Command是iFlow CLI中的命令市场系统，允许您从在线市场安装专业化的斜杠命令来扩展CLI功能。类似于应用商店，您可以浏览、安装、管理各种功能丰富的自定义命令。

核心特点​

特点说明优势
市场化分发从在线市场获取经过验证的命令丰富的功能选择
即插即用安装后立即可用，无需额外配置简化使用流程
作用域管理支持项目级和全局级别的命令安装灵活的权限控制
版本追踪每个命令都有明确的版本信息确保功能稳定性
社区驱动支持社区贡献和第三方开发持续功能扩展

工作原理​

命令市场架构​

在线市场 → 本地安装 → CLI集成 → 斜杠命令
    ↓         ↓        ↓        ↓
[命令库] → [TOML配置] → [命令解析] → [功能执行]

作用域层级​

  • 全局作用域：安装到 ~/.iflow/commands/，所有项目都可使用
  • 项目作用域：安装到 {project}/.iflow/commands/，仅当前项目可用
  • 优先级规则：项目级命令优先于全局级命令

命令市场管理​

从开放市场中安装命令​

  • 进入命令开放市场

  • 搜索类型选择指令

  • 挑选心仪的指令

  • 点击安装按钮，复制对应的命令

  • 在自己的终端安装

在CLI中浏览在线市场​

命令功能说明
/commands online进入交互式市场浏览、搜索、安装命令
/commands get <name or id>查看命令详情获取特定命令的详细信息

市场导航操作​

交互式浏览快捷键

操作快捷键说明
向下浏览j 或 ↓移动到下一个命令
向上浏览k 或 ↑移动到上一个命令
查看详情l 或 Enter查看命令详细信息
安装命令i安装当前选中的命令
搜索过滤/按名称或分类搜索
退出浏览q退出市场浏览模式
刷新列表r重新加载命令列表
# 进入交互式命令市场
/commands online

# 浏览过程中的操作示例
# 1. 使用 j/k 或方向键浏览命令列表
# 2. 按 Enter 查看感兴趣命令的详细信息
# 3. 按 i 键直接安装命令
# 4. 按 / 键搜索特定功能的命令

查看命令详情​

# 查看特定命令的详细信息
/commands get 123

# 输出示例：
# 📋 Command Details
# 
# 🆔 ID: 123
# 📝 Name: code-reviewer
# 📄 Description: 专业代码审查工具，支持多语言代码质量检测
# 📁 Category: Development
# 🤖 Model: claude-3-5-sonnet-20241022
# 🏷️  Tags: code-review, quality, best-practices
# 👤 Author: iflow-community
# 📊 Version: 2
# 👁️  Visibility: public
# 📋 Status: published
# 
# 📖 Detail Context:
# 这是一个专业的代码审查助手，可以：
# - 检测代码质量问题
# - 提供最佳实践建议
# - 支持多种编程语言
# - 生成详细的审查报告
# 
# 💡 To add this command to your CLI, use: /commands add 123

安装命令介绍​

# 基本语法
iflow commands add <name or id> [--scope project|global]

# 安装到项目（默认）
iflow commands add 123
iflow commands add 123 --scope project

# 安装到全局
iflow commands add commit --scope global

# 实际示例
iflow commands add 456 --scope project   # 代码审查工具
iflow commands add docs --scope global    # 通用文档生成工具

# 更多详情查看
iflow commands -h

查看已安装命令​

# 列出所有已安装的命令
/commands list
/commands show      # 别名
/commands local     # 别名

# 输出示例：
# Installed commands:
# 
# 🌍 Global Commands (2):
#   /code-reviewer - 专业代码审查工具，支持多语言代码质量检测
#   📁 /Users/username/.iflow/commands/code-reviewer.toml
# 
#   /doc-generator - 自动文档生成工具
#   📁 /Users/username/.iflow/commands/doc-generator.toml
# 
# 📂 Project Commands (1):
#   /project-analyzer - 项目结构分析工具
#   📁 /path/to/project/.iflow/commands/project-analyzer.toml
# 
# 💡 Tips:
#   • Use /commands online to browse online marketplace
#   • Use /commands add <id> to install new commands
#   • Use /commands remove <name> to remove commands
#   • Use /commands get <id> to view command details

删除命令​

# 删除项目级命令（默认）
/commands remove <command-name>
/commands remove code-reviewer

# 删除全局命令
/commands remove code-reviewer --scope global

# 别名命令
/commands rm <command-name>
/commands delete <command-name>

# 删除成功示例：
# ✅ Successfully removed command 'code-reviewer' from project scope
# Location: /path/to/project/.iflow/commands/code-reviewer.toml
# 
# ⚠️  Please restart the CLI to see changes take effect.

命令分类与推荐​

开发工具类​

命令名称ID功能描述适用场景
refactor79重构代码，保持功能性的同时改进结构、可读性和可维护性代码优化和结构调整
implement80智能实现功能特性，完美适配项目架构新功能开发
test81基于当前上下文智能运行测试并帮助修复失败测试自动化
scaffold94从模式生成完整功能特性快速原型开发
fix-imports87重构后修复损坏的导入重构后维护
fix-todos88智能实现TODO修复任务管理
format89自动检测并应用项目格式化器代码格式化

代码质量类​

命令名称ID功能描述适用场景
review93多代理分析（安全、性能、质量、架构）代码审查
make-it-pretty90改善可读性而不改变功能代码美化
remove-comments92清理明显的注释，保留有价值的文档代码清理
predict-issues91主动问题检测与时间线估算风险预测

文档工具类​

命令名称ID功能描述适用场景
docs84智能文档管理和更新项目文档维护
contributing82项目贡献准备性完整分析开源项目
explain-like-senior85高级水平的代码解释和上下文分析代码学习

安全分析类​

命令名称ID功能描述适用场景
security-scan95扩展思考的漏洞分析和修复跟踪安全检查

实用工具类​

命令名称ID功能描述适用场景
commit78分析变更并创建有意义的提交信息Git工作流
cleanproject77清理开发工件同时保留工作代码项目维护
create-todos83基于分析结果添加上下文TODO注释任务管理
find-todos86定位和组织开发任务任务跟踪
session-end96总结和保存会话上下文会话管理

命令配置文件​

TOML文件结构​

安装的命令会在本地生成TOML配置文件：

# Command: code-reviewer
# Description: 专业代码审查工具，支持多语言代码质量检测
# Category: Development
# Version: 2
# Author: iflow-community

description = "专业代码审查工具，支持多语言代码质量检测"

prompt = """
你是一个专业的代码审查专家。请分析用户提供的代码，从以下方面进行评估：

1. 代码质量和可读性
2. 安全性问题检测
3. 性能优化建议
4. 最佳实践遵循情况
5. 潜在的bug或逻辑错误

请提供具体的改进建议和示例代码。
"""

md文件结构​

除了TOML格式，iFlow CLI还支持Markdown格式的配置文件。

# 创建命令目录
mkdir -p ~/.iflow/commands

# 创建Markdown格式的命令文件
echo "Review this code for security vulnerabilities:" > ~/.iflow/commands/security-review.md

也支持添加描述，例如

---
description: Create a git commit
---

## Context

- Current git status: !`git status`
- Current git diff (staged and unstaged changes): !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`

## Your task

Based on the above changes, create a single git commit.

配置文件位置​

作用域配置路径说明
全局~/.iflow/commands/所有项目都可访问
项目{project}/.iflow/commands/仅当前项目可访问

故障排除​

常见问题及解决方案​

问题可能原因解决方案
命令安装失败API密钥未设置或过期重新进行身份验证
命令不可用未重启CLI加载新配置重启iFlow CLI
权限错误目录权限不足检查文件系统权限
网络连接失败无法访问命令市场API检查网络连接和防火墙设置
命令冲突同名命令在不同作用域使用 --scope 明确指定

诊断步骤​

  1. 连接检查

    # 测试API连接
    /commands online

    # 检查身份验证状态
    /auth status

  2. 配置验证

    # 查看本地命令列表
    /commands list

    # 检查配置文件
    cat ~/.iflow/commands/command-name.toml

  3. 权限验证

    # 检查目录权限
    ls -la ~/.iflow/commands/
    ls -la ./.iflow/commands/

  4. 日志检查

    # 查看详细日志
    /log

    # 查看错误信息
    /debug

清理和重置​

# 清理项目级命令
rm -rf ./.iflow/commands/

# 清理全局命令（谨慎操作）
rm -rf ~/.iflow/commands/

# 重新初始化命令配置
iflow commands init

安全注意事项​

使用第三方命令时的安全建议​

验证命令来源：

  • ⚠️ 仅安装来自可信作者的命令
  • ⚠️ 检查命令的评分和社区反馈
  • ⚠️ 避免安装过于宽泛权限的命令

命令权限控制：

  • ✅ 优先使用项目作用域安装
  • ✅ 定期审核已安装的命令
  • ✅ 及时更新命令到最新版本
  • ✅ 移除不再使用的命令

开发自定义命令​

TOML配置文件完整规范​

基础配置结构​

# 命令描述（必需）
description = "命令的简短描述"

# 命令提示词（必需）
prompt = """
发送给AI模型的完整提示词内容
支持多行文本和特殊占位符
"""

高级功能特性​

1. 参数注入机制​

快捷参数注入：使用 {{args}} 占位符

description = "代码审查工具"

prompt = """
请审查以下代码并提供改进建议：

{{args}}

重点关注：代码质量、安全性、性能优化。
"""

默认参数处理：如果不使用 {{args}}，系统会自动将用户输入追加到提示词后

description = "文档生成器"

prompt = """
根据提供的内容生成专业文档。
"""
# 用户输入 "/docs 用户手册" 会变成：
# "根据提供的内容生成专业文档。\n\n/docs 用户手册"
2. Shell命令集成​

使用 !{command} 语法在提示词中执行Shell命令：

description = "项目分析工具"

prompt = """
当前项目信息：

文件结构：
!{find . -name "*.js" -o -name "*.ts" | head -20}

Git状态：
!{git status --porcelain}

请分析项目状态并提供建议。
"""

安全机制：

  • Shell命令需要通过安全检查
  • 支持全局和会话级别的命令白名单
  • 危险命令会要求用户确认
3. 提示词处理器链​

系统使用处理器链模式处理TOML配置：

处理器触发条件功能
ShellProcessor包含 !{...}执行Shell命令并替换输出
ShorthandArgumentProcessor包含 {{args}}替换参数占位符
DefaultArgumentProcessor默认追加用户输入到提示词

开发环境搭建​

目录结构管理​

# 全局命令目录
~/.iflow/commands/
├── my-command.toml
├── code-reviewer.toml
└── project-analyzer.toml

# 项目命令目录
/path/to/project/.iflow/commands/
├── deploy.toml
├── test-runner.toml
└── build-helper.toml

路径解析规则​

系统使用以下函数获取命令目录：

// 全局命令目录
getUserCommandsDir(): string {
  return path.join(os.homedir(), '.iflow', 'commands');
}

// 项目命令目录
getProjectCommandsDir(projectRoot: string): string {
  return path.join(projectRoot, '.iflow', 'commands');
}

文件命名规范​

  • 基础命名：command-name.toml
  • 层级命名：parent:child.toml → 创建嵌套命令结构
  • 文件名清理：非字母数字字符转换为连字符
  • 扩展命名空间：扩展命令自动获得 [extensionName] 前缀

实战开发示例​

示例1：简单信息查询命令​

# ~/.iflow/commands/system-info.toml
description = "显示系统信息摘要"

prompt = """
请执行以下系统检查并提供摘要：

操作系统：!{uname -a}
磁盘使用：!{df -h /}
内存使用：!{free -h}
当前目录：!{pwd}

请分析系统状态并给出建议。
"""

使用方式：/system-info

示例2：参数化代码生成器​

# ./iflow/commands/generate-component.toml  
description = "React组件生成器"

prompt = """
请生成一个React组件，需求如下：

{{args}}

请包含：
1. TypeScript接口定义
2. 完整的组件实现
3. 基础的CSS样式
4. 使用示例

遵循最佳实践和现代React模式。
"""

使用方式：/generate-component 用户登录表单组件

示例3：复杂项目管理工具​

# ./.iflow/commands/project:status.toml
description = "项目状态全面分析"

prompt = """
项目全面状态报告：

## 代码库状态
Git分支：!{git branch --show-current}
未提交变更：!{git status --porcelain | wc -l}
最近提交：!{git log --oneline -5}

## 依赖状态  
Package.json存在：!{test -f package.json && echo "✅ 存在" || echo "❌ 不存在"}
Node模块状态：!{test -d node_modules && echo "✅ 已安装" || echo "❌ 未安装"}

## 代码质量
TypeScript文件数：!{find . -name "*.ts" -o -name "*.tsx" | wc -l}
JavaScript文件数：!{find . -name "*.js" -o -name "*.jsx" | wc -l}
测试文件数：!{find . -name "*.test.*" -o -name "*.spec.*" | wc -l}

请分析项目健康状况并提供改进建议。
"""

使用方式：/project:status

示例4：动态脚本执行器​

# ~/.iflow/commands/run-with-context.toml
description = "在项目上下文中执行命令"

prompt = """
在当前项目环境中执行指定操作：

项目根目录：!{pwd}
操作内容：{{args}}

执行结果：
!{{{args}}}

请分析执行结果并提供后续建议。
"""

使用方式：/run-with-context npm test

调试和测试指南​

配置验证​

系统使用Zod进行TOML配置验证：

const TomlCommandDefSchema = z.object({
  prompt: z.string({
    required_error: "The 'prompt' field is required.",
    invalid_type_error: "The 'prompt' field must be a string.",
  }),
  description: z.string().optional(),
});

常见错误和解决方案​

错误类型原因解决方案
TOML解析错误语法不正确检查引号、缩进和转义字符
Schema验证失败缺少必需字段确保包含 prompt 字段
Shell命令被阻止安全策略限制添加到命令白名单或修改安全配置
命令不显示文件位置错误检查文件路径和重启CLI

开发工作流​

  1. 创建TOML文件

    mkdir -p ./.iflow/commands
    touch ./.iflow/commands/my-command.toml

  2. 编写配置内容

    description = "测试命令"
    prompt = "这是一个测试命令"

  3. 重启CLI加载新命令

    # 退出当前会话
    /quit
    # 重新启动
    iflow

  4. 测试命令功能

    /my-command 测试参数

  5. 查看调试信息

    /log  # 查看系统日志
    /debug # 启用调试模式