Interop

Interop

Interop 是一款功能强大的命令行界面工具，旨在通过提供统一的界面来管理项目、执行命令以及与 AI 助手集成，从而提升开发者的工作效率。

什么是 Interop？

Interop 充当开发项目、自定义命令与 AI 助手之间的桥梁。它支持：

• 使用元数据、命令和验证功能组织多个项目
• 定义并执行能够感知项目上下文的命令
• 配置多个 MCP（模型上下文协议）服务，以便与 AI 集成
• 简化不同领域中的重复开发任务

核心功能

• 项目管理：跟踪并验证多个项目目录
• 命令执行：在项目上下文中运行命令并传入参数
• 动态命令加载：根据优先级规则从多个目录加载命令
• 远程配置系统：从 Git 仓库获取并同步配置，同时解决冲突
• AI 集成：通过多个 MCP 服务向 AI 助手提供命令，并附带增强的元数据
• 配置管理：基于 TOML 的配置，支持验证和冲突检测
• 跨平台支持：可在 Linux、macOS 和 Windows 上运行

安装

使用 Homebrew（macOS/Linux）

brew install yigitozgumus/formulae/interop

从源代码构建

1. 克隆仓库：

git clone https://github.com/yigitozgumus/interop.git
cd interop

2. 构建项目：

go build -o interop ./cmd/cli

配置

Interop 使用位于 ~/.config/interop/settings.toml 的 TOML 配置文件。编辑该文件：

interop edit

配置结构

# Global settings
log_level = "verbose"  # Options: error, warning, verbose
executable_search_paths = ["~/.local/bin", "~/bin"]
command_dirs = ["~/.config/interop/commands.d", "~/projects/shared/interop-commands"]
mcp_port = 8081  # Default MCP server port

# MCP Server Configurations
[mcp_servers.domain1]
name = "domain1"
description = "Domain-specific commands"
port = 8082

[mcp_servers.domain2]
name = "domain2"
description = "Another domain for commands"
port = 8083

# Project Definitions
[projects.project1]
path = "~/projects/project1"
description = "Project 1 description"
commands = [
  { command_name = "build", alias = "b" },
  { command_name = "test" }
]

[projects.project2]
path = "~/projects/project2"
description = "Project 2 description"
commands = [
  { command_name = "deploy", alias = "d" }
]

# Command Definitions
[commands.build]
cmd = "go build ./..."
description = "Build the project"
is_enabled = true
is_executable = false
# Assign to a specific MCP server
mcp = "domain1"

[commands.test]
cmd = "go test ./..."
description = "Run tests"
is_enabled = true
is_executable = false

[commands.deploy]
cmd = "deploy.sh"
description = "Deploy the project"
is_enabled = true
is_executable = true
mcp = "domain2"

# Command with Arguments, Version, and Examples
[commands.build-app]
cmd = "go build -o ${output_file} ${package}"
description = "Build a Go application"
version = "1.1.0"
is_enabled = true
is_executable = false
arguments = [
  { name = "output_file", type = "string", description = "Output file name", required = true },
  { name = "package", type = "string", description = "Package to build", default = "./cmd/app" }
]
examples = [
  {
    description = "Build the main application",
    command = "interop run build-app output_file=my-app"
  },
  {
    description = "Build a specific package",
    command = "interop run build-app output_file=my-tool package=./cmd/tool"
  }
]

项目管理

项目是 Interop 的核心组织单元。

列出项目

interop projects

输出示例：

PROJECTS:
=========

📁 Name: project1
   Path: ~/projects/project1
   Status: Valid: ✓  |  In $HOME: ✓
   Description: Project 1 description
   Commands:
      ⚡ build (alias: b)
         Build the project
      ⚡ test
         Run tests

📁 Name: project2
   Path: ~/projects/project2
   Status: Valid: ✓  |  In $HOME: ✓
   Description: Project 2 description
   Commands:
      ⚡ deploy (alias: d)
         Deploy the project

项目配置

每个项目包含：

• 路径：目录位置（会验证其是否存在）
• 描述：可选的项目描述
• 命令：包含可选别名的命令列表

动态配置加载

Interop 支持从多个目录加载配置定义，从而更好地组织和扩展大型配置集合。

配置

在全局设置中添加 command_dirs，以指定包含配置定义文件的目录：

command_dirs = [
  "~/.config/interop/config.d",
  "~/projects/shared/interop-configs"
]

配置目录结构

每个目录可以包含多个定义配置的 *.toml 文件：

~/.config/interop/config.d/
├── git-commands.toml
├── docker-commands.toml
├── dev-projects.toml
└── ai-prompts.toml

git-commands.toml 示例：

[commands.git-status]
cmd = "git status"
description = "Show the working tree status"
version = "1.0.0"
is_enabled = true
mcp = "dev-tools"

[commands.git-pull]
cmd = "git pull --rebase"
description = "Fetch from and integrate with another repository"
version = "1.0.0"
is_enabled = true
mcp = "dev-tools"

dev-projects.toml 示例：

[projects.my-api]
path = "~/projects/my-api"
description = "Main API project"
commands = [
  { command_name = "build", alias = "b" },
  { command_name = "test", alias = "t" }
]

可包含的内容

这些目录中的配置文件可以包含：

• 命令（[commands.name]）——命令定义
• 项目（[projects.name]）——项目配置
• 提示词（[prompts.name]）——AI 提示词模板
• MCP 服务（[mcp_servers.name]）——MCP 服务定义

优先级规则

当配置名称冲突时，Interop 遵循明确的优先级顺序：

1. 主 settings.toml（最高优先级）
2. 配置目录，按照 command_dirs 中指定的顺序
3. 目录中的文件，按字母顺序排列

这能确保配置解析结果可预测，并便于覆盖共享配置。

优势

• 组织管理：将相关配置分组到不同文件中
• 共享：在团队或项目之间共享配置集合
• 模块化：通过目录启用或禁用整套配置

远程配置系统

Interop 内置了功能强大的远程配置系统，可从 Git 仓库获取和管理配置。借助此功能，团队可以共享命令定义、维护集中式配置库，并使本地设置与远程来源保持同步。

概述

远程配置系统：

• 从 Git 仓库获取配置
• 在 config.d.remote 和 executables.remote 目录中维护本地副本
• 使用 SHA-256 哈希跟踪文件更改，以便增量更新
• 自动将远程配置与本地配置集成
• 检测并解决冲突，优先采用本地配置

管理远程配置

添加远程仓库

# Add a remote Git repository
interop config remote add my-team https://github.com/myteam/interop-configs.git

# Add with SSH (recommended for private repositories)
interop config remote add my-team [email protected]:myteam/interop-configs.git

列出远程仓库

interop config remote show

输出示例：

Remote Configurations:
======================

🔗 my-team
   URL: [email protected]:myteam/interop-configs.git
   Status: ✓ Valid Git URL

🔗 shared-tools  
   URL: https://github.com/company/shared-tools.git
   Status: ✓ Valid Git URL

获取远程配置

# Fetch from all configured remotes
interop config remote fetch

# Fetch from a specific remote
interop config remote fetch my-team

获取过程：

1. 克隆 仓库到临时目录
2. 验证 仓库结构（需要 config.d 和／或 executables 文件夹）
3. 比较 文件哈希以检测更改
4. 同步 仅修改过的文件到本地远程目录
5. 更新 版本跟踪信息，包括提交信息
6. 清理 远程已删除的文件

移除远程仓库

# Remove a specific remote
interop config remote remove my-team

# Clear all remote configurations and cached files
interop config remote clear

仓库结构要求

远程仓库必须遵循以下结构：

your-repo/
├── config.d/              # Configuration files (required)
│   ├── commands.toml      # Command definitions
│   ├── projects.toml      # Project configurations
│   └── mcp-servers.toml   # MCP server definitions
└── executables/           # Executable files (optional)
    ├── deploy.sh
    ├── build-tool
    └── scripts/
        └── helper.py

远程配置示例

config.d/team-commands.toml：

[commands.team-deploy]
cmd = "deploy.sh"
description = "Deploy using team standards"
is_executable = true
mcp = "team-tools"
version = "2.1.0"
arguments = [
  { name = "environment", type = "string", required = true, description = "Target environment" },
  { name = "force", type = "bool", default = false, description = "Force deployment" }
]

[commands.team-test]
cmd = "run-team-tests.sh"
description = "Run standardized team tests"
is_executable = true
mcp = "team-tools"

[mcp_servers.team-tools]
name = "team-tools"
description = "Team standardized tools"
port = 8084

本地集成

远程配置会自动集成到本地设置中：

目录结构

~/.config/interop/
├── settings.toml           # Your local settings
├── config.d/              # Local configurations
│   └── personal.toml
├── config.d.remote/       # Remote configurations (auto-managed)
│   ├── team-commands.toml
│   └── shared-tools.toml
├── executables/           # Local executables
├── executables.remote/    # Remote executables (auto-managed)
│   ├── deploy.sh
│   └── build-tool
└── versions.toml          # Remote tracking metadata (auto-managed)

优先级规则

发生配置冲突时，Interop 按照以下优先级处理：

1. 本地配置（config.d/）——最高优先级
2. 远程配置（config.d.remote/）——较低优先级
3. 主 settings.toml——全局设置的回退选项

这样既能确保本地自定义设置始终优先，又能利用共享的远程配置。

冲突检测与解决

验证系统可全面检测冲突：

interop validate

冲突输出示例：

Configuration Overview
=====================

Configuration Sources:
---------------------
🏠 Main Settings: /Users/user/.config/interop/settings.toml
🏠 Command Directories:
   🏠 /Users/user/.config/interop/config.d (2 files)
☁️ Remote Configuration:
   ✓ config.d.remote: Available (3 files)
   ✓ executables.remote: Available (5 files)
   ✓ Remote tracking: Active

⚠️ Potential Conflicts:
   ⚠️ Command 'deploy' exists in both local and remote configs
   ⚠️ Command 'test-suite' exists in both local and remote configs
   → Local configurations take precedence

Commands:
--------
🌐 ✓ deploy (Shell) (🏠 Local)
   └─ My custom deploy script
   └─ 🔌 Default MCP server (Port: 8081)

🌐 ✓ team-deploy (Shell) (☁️ Remote)
   └─ Deploy using team standards
   └─ 🔌 Assigned to MCP server: team-tools (Port: 8084)

版本跟踪与增量更新

Interop 会详细跟踪远程配置：

版本信息

系统会跟踪：

• 文件哈希（SHA-256），用于检测更改
• 最近一次提交 ID，用于记录仓库状态
• 获取时间戳，用于记录更新历史
• 文件路径，用于清理已删除的文件

增量更新

后续获取会进行优化：

• 仅下载已更改的文件
• 在本地清理已删除的文件
• 保留提交历史，以便回滚
• 尽量减少网络使用量

Git URL 验证

系统会验证 Git URL，确保其兼容性：

支持的格式

SSH 格式：

[email protected]:user/repo.git
[email protected]:user/repo.git
[email protected]:user/repo.git

HTTPS 格式：

https://github.com/user/repo.git
https://gitlab.com/user/repo.git
https://bitbucket.org/user/repo.git

自定义 Git 服务：

https://git.company.com/team/configs.git
[email protected]:team/configs.git

使用场景

团队标准化

# Set up team-wide configurations
interop config remote add company-standards [email protected]:company/interop-standards.git
interop config remote fetch

# Now all team members have access to:
# - Standardized deployment scripts
# - Common development commands  
# - Shared MCP server configurations
# - Team-specific project templates

多环境管理

# Different configurations for different environments
interop config remote add prod-tools [email protected]:company/prod-tools.git
interop config remote add dev-tools [email protected]:company/dev-tools.git

# Fetch environment-specific tools
interop config remote fetch prod-tools
interop config remote fetch dev-tools

开源工具集合

# Add community-maintained tool collections
interop config remote add awesome-dev-tools https://github.com/community/awesome-dev-tools.git
interop config remote fetch

最佳实践

仓库组织

1. 划分职责：为不同领域使用不同的仓库
2. 为配置添加版本：通过标记版本发布稳定的配置集
3. 记录命令：提供全面的描述和示例
4. 测试配置：推送前验证配置

安全注意事项

1. 私有仓库使用 SSH 密钥
2. 获取前 检查远程配置
3. 将敏感数据保留在本地——不要在远程配置中存放密钥
4. 定期 审查远程来源

团队工作流

1. 在团队仓库中 集中管理常用工具
2. 允许本地覆盖，以满足个人偏好
3. 对共享配置的更改进行 版本控制
4. 共享配置发生变化时 及时沟通

故障排除

常见问题

找不到仓库：

# Check URL and access permissions
git clone <your-repo-url>  # Test manually

仓库结构无效：

# Ensure repository has config.d/ or executables/ directory
# Check repository contents match expected structure

与本地配置冲突：

# Use validation to identify conflicts
interop validate

# Rename local commands if needed
# Or remove remote repository if not needed

网络问题：

# Check internet connectivity
# Verify Git credentials are set up
# Try fetching manually: git clone <repo-url>

命令管理

Interop 提供灵活的命令系统，可适应你的工作流。

列出命令

interop commands

输出示例：

COMMANDS:
=========

⚡ Name: build
   Status: Enabled: ✓  |  Source: Script
   Description: Build the project
   MCP Server: domain1

⚡ Name: test
   Status: Enabled: ✓  |  Source: Script
   Description: Run tests
   
⚡ Name: deploy
   Status: Enabled: ✓  |  Source: Executable
   Description: Deploy the project
   MCP Server: domain2

命令类型

1. Shell 命令：通过系统 Shell 运行

   [commands.list]
   cmd = "ls -la"
   

2. 可执行命令：直接从已配置的路径运行

   [commands.deploy]
   cmd = "deploy.sh"
   is_executable = true
   

3. 项目绑定命令：在特定项目的上下文中运行

   [projects.project1]
   commands = [{ command_name = "build" }]
   

4. 带参数的命令：经过验证的模板化命令

   [commands.build-app]
   cmd = "go build -o ${output_file} ${package}"
   arguments = [
     { name = "output_file", type = "string", required = true },
     { name = "package", type = "string", default = "./cmd/app" }
   ]
   

执行命令

按名称或别名运行命令：

# Simple command
interop run build

# Command with alias
interop run b  # Runs the build command

# Command with arguments
interop run build-app output_file=myapp.exe

对于项目绑定命令，Interop 会自动：

1. 切换到项目目录
2. 执行命令
3. 返回原始目录

MCP 服务集成

Interop 通过 MCP（Model Context Protocol）服务，为 AI 集成提供了强大的支持。

什么是 MCP 服务？

MCP 服务会将你的命令作为工具公开，供 Claude 等 AI 助手调用。每个服务都可以提供不同的命令集，从而按领域进行组织。

管理 MCP 服务

# Start servers
interop mcp start                # Start default server
interop mcp start domain1        # Start specific server
interop mcp start --all          # Start all servers

# Check status
interop mcp status               # Default shows all servers
interop mcp status domain1       # Check specific server

# Stop servers
interop mcp stop domain1         # Stop specific server
interop mcp stop --all           # Stop all servers

# Restart servers
interop mcp restart domain1      # Restart specific server
interop mcp restart --all        # Restart all servers

# Port management
interop mcp port-check           # Check if ports are available

# Get configuration for AI tools
interop mcp export               # Export JSON configuration

多个 MCP 服务

你可以按领域组织命令：

[mcp_servers.work]
name = "work"
description = "Work-related commands"
port = 8082

[mcp_servers.personal]
name = "personal"
description = "Personal project commands"
port = 8083

[commands.work-task]
cmd = "work-script.sh"
mcp = "work"  # This command is available on the work server

[commands.personal-task]
cmd = "personal-script.sh"
mcp = "personal"  # This command is available on the personal server

每个服务只公开分配给它的命令，从而清晰地划分不同领域。

AI 助手集成

AI 助手连接到 MCP 服务后，可以：

1. 查看可用命令及其说明
2. 使用参数执行命令
3. 接收命令的输出和错误

这就创建了一个强大的交互界面，AI 可以根据自然语言指令帮助你执行任务。

命令参数

命令可以使用带验证的类型化参数：

[commands.generate]
cmd = "generate.sh ${type} ${name} ${force}"
description = "Generate a new component"
arguments = [
  { name = "type", type = "string", description = "Component type", required = true },
  { name = "name", type = "string", description = "Component name", required = true },
  { name = "force", type = "bool", description = "Overwrite if exists", default = false }
]

参数类型

• string：文本值
• number：数值（整数或小数）
• bool：布尔值（true/false）

参数特性

• 必填：标记必须提供的参数
• 默认值：为可选参数设置回退值
• 说明：说明每个参数的用途
• 前缀：指定参数使用的命令行标志（例如，--key）

使用参数

# Named arguments
interop run generate type=component name=Button

# Positional arguments (in order of definition)
interop run generate component Button true

带前缀的参数

带前缀的参数允许你定义带有特定前缀（例如 --keys 或 -f）的命令行参数。这在使用需要特定参数格式的脚本或工具时尤其有用：

[commands.update-strings]
cmd="python3 scripts/update_strings.py"
description="Update localization strings"
arguments=[
  {name = "keys", type="string", required = false, description = "Keys to update", prefix = "--keys"},
  {name = "language", type="string", required = false, description = "Language code", prefix = "--language"},
  {name = "verbose", type="bool", required = false, description = "Verbose output", prefix = "--verbose"}
]

执行时：

interop run update-strings --keys "key1 key2" --language en --verbose true

实际执行的命令将是：

python3 scripts/update_strings.py --keys key1 key2 --language en --verbose

带前缀的参数如何工作

1. 对于带前缀的参数：Interop 会将它们连同前缀一起附加到命令中
2. 对于不带前缀的参数：Interop 会使用 ${arg_name} 占位符将它们替换到命令字符串中
3. 对于带前缀的布尔参数：如果值为 true，则只添加前缀；否则会省略该参数
4. 对于带前缀的非布尔参数：前缀和值会一起添加

带前缀参数的优势

• 在所有 Shell（bash、fish、zsh 等）中都能保持一致
• 参数可以按任意顺序提供
• 无需转义参数值中的特殊字符
• 兼容需要特定参数格式的工具

增强的命令元数据

Interop 支持为命令添加丰富的元数据，以改进 AI 助手集成和文档。

版本信息

为命令添加版本跟踪：

[commands.deploy]
cmd = "deploy.sh"
description = "Deploy the application"
version = "2.1.0"
is_enabled = true

使用示例

提供命令用法的具体示例：

[commands.create-component]
cmd = "generate.sh ${type} ${name}"
description = "Generate a new component"
version = "1.0.0"
arguments = [
  { name = "type", type = "string", description = "Component type", required = true },
  { name = "name", type = "string", description = "Component name", required = true }
]
examples = [
  {
    description = "Create a React component",
    command = "interop run create-component type=react name=Button"
  },
  {
    description = "Create a Vue component", 
    command = "interop run create-component type=vue name=Header"
  }
]

对 AI 集成的优势

命令包含版本和示例时：

• AI 助手可以提供更准确的建议
• 文档会自动生成
• 通过具体示例，团队入职会更加轻松
• 版本跟踪有助于兼容性管理和更新

验证与诊断

增强的配置验证

interop validate

验证系统会对你的配置进行全面分析：

配置源分析

• 主设置：验证 settings.toml 是否存在且可访问
• 本地目录：显示 config.d/ 的文件数量和可访问性
• 远程目录：显示 config.d.remote/ 和 executables.remote/ 的状态
• 远程跟踪：指示远程版本跟踪是否已启用

冲突检测

• 命令冲突：识别在多个来源中定义的命令
• 优先级规则：显示哪项配置优先
• 视觉指示：使用符号突出显示冲突和警告
• 来源归属：显示每个命令来自本地还是远程来源

验证检查

• 项目路径存在且可访问
• 命令引用有效
• 同一作用域内没有冲突的别名
• 必需的命令参数已正确定义
• MCP 服务端口没有冲突
• 命令目录可访问且 TOML 语法正确
• 符合远程仓库结构要求
• Git URL 格式验证

验证输出示例

Configuration Overview
=====================

Configuration Sources:
---------------------
🏠 Main Settings: /Users/user/.config/interop/settings.toml
🏠 Command Directories:
   🏠 /Users/user/.config/interop/config.d (2 files)
☁️ Remote Configuration:
   ✓ config.d.remote: Available (3 files)
   ✓ executables.remote: Available (5 files)
   ✓ Remote tracking: Active

⚠️ Potential Conflicts:
   ⚠️ Command 'deploy' exists in both local and remote configs
   → Local configurations take precedence

MCP Servers:
-----------
🔌 Default MCP Server (Port: 8081)
   └─ Commands: (commands with no MCP field)

🔌 team-tools MCP Server (Port: 8084)
   └─ Team standardized tools
   └─ Commands: 5

Commands:
--------
🌐 ✓ deploy (Shell) (🏠 Local)
   └─ My custom deploy script
   └─ 🔌 Default MCP server (Port: 8081)

🌐 ✓ team-deploy (Shell) (☁️ Remote)
   └─ Deploy using team standards
   └─ 🔌 Assigned to MCP server: team-tools (Port: 8084)

Legend:
-------
🌐 Global Command        🏠 Local Configuration
📂 Project-bound Command ☁️ Remote Configuration  
🔄 Command Alias         ⚠️ Warning/Conflict
✓ Enabled Command        🔌 MCP Server Association
❌ Disabled Command

✅ Configuration is valid!

端口检查

interop mcp port-check

此处显示：

• 哪些端口可用
• 哪些端口正在使用
• 哪些进程正在使用端口

日志级别

在设置中配置详细程度：

log_level = "verbose"  # Options: error, warning, verbose

高级功能

可执行文件搜索路径

Interop 会按以下顺序搜索可执行文件：

1. 配置目录（~/.config/interop/executables/）
2. 配置中指定的其他路径
3. 系统 PATH

executable_search_paths = ["~/.local/bin", "~/bin"]

开发

项目结构

.
├── cmd/
│   └── cli/          # Main application entry point
├── internal/
│   ├── command/      # CLI command implementations
│   ├── display/      # Output formatting utilities
│   ├── edit/         # Project editing functionality
│   ├── logging/      # Logging with color control
│   ├── mcp/          # MCP server implementation
│   ├── project/      # Project management core
│   ├── settings/     # Configuration management
│   └── util/         # Shared utilities
├── dist/             # Distribution files
└── .github/          # GitHub workflows and templates

测试

运行测试套件：

go test ./...

快速参考

远程配置命令

# Remote repository management
interop config remote add <name> <git-url>     # Add remote repository
interop config remote remove <name>            # Remove remote repository
interop config remote show                     # List all remotes
interop config remote clear                    # Remove all remotes and cached files

# Fetching configurations
interop config remote fetch                    # Fetch from all remotes
interop config remote fetch <name>             # Fetch from specific remote

# Validation and diagnostics
interop validate                               # Comprehensive configuration validation
interop mcp port-check                         # Check MCP server port availability

配置文件位置

~/.config/interop/settings.toml               # Main configuration file
~/.config/interop/config.d/                   # Local configuration directory
~/.config/interop/config.d.remote/            # Remote configurations (auto-managed)
~/.config/interop/executables/                # Local executable files
~/.config/interop/executables.remote/         # Remote executables (auto-managed)
~/.config/interop/versions.toml               # Remote tracking metadata (auto-managed)

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。