AI导哈

命令包装生成器

Universal Command Wrapper (UCW) 是一个强大的命令包装生成器，可作为独立工具或SMCP插件使用，通过智能命令解析和包装生成，桥接命令行工具与Python应用。

  • by actuallyrizzn
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 actuallyrizzn/ucw

使用说明

通用命令封装器（UCW）

一个强大的命令封装生成器，既可独立使用，也可作为SMCP插件使用。UCW能够自动分析系统命令，并生成可调用的封装或MCP插件文件，通过智能命令解析和封装生成，弥合了命令行工具与Python应用程序之间的鸿沟。

🚀 特性

  • 跨平台支持在Windows上运行/?）和POSIX（--help， man) 系统
  • 零依赖仅使用Python标准库
  • 智能解析自动提取选项、标志和位置参数
  • 类型推断从帮助文本描述中推断参数类型
  • 双输出模式:
    • 库模式：生成可调用的Python封装器
    • 构建模式：生成完整的MCP插件文件
  • 文件管理创建新的CLI文件或更新现有的CLI文件
  • SMCP 插件主要用例作为SMCP插件（只需复制文件夹）
  • 独立工具可独立用于开发/测试
  • MCP 兼容性生成与MCP服务器兼容的插件

📋 目录

🛠 安装

作为SMCP插件（主要用途）

UCW主要设计为SMCP（简单MCP）的插件使用

  1. 克隆仓库：

    git clone https://github.com/actuallyrizzn/ucw.git

  2. 放在SMCP插件目录中:

    # Copy to your SMCP plugins directory
cp -r ucw /path/to/smcp/plugins/

  3. 使CLI可执行:

    chmod +x /path/to/smcp/plugins/ucw/cli.py

独立使用（开发/测试）

用于开发、测试或独立使用：

# Clone the repository
git clone https://github.com/actuallyrizzn/ucw.git
cd ucw

# Install production dependencies (zero external dependencies)
pip install -r requirements.txt

# Install testing dependencies (for development/testing)
pip install -r requirements-testing.txt

# Run tests
python -m pytest tests/

# Use CLI directly
python cli.py wrap ls

🚀 快速入门

CLI 使用方法

SMCP 插件模式（默认 - JSON 输出）

# Generate wrapper in memory (JSON output)
python cli.py wrap ls

# Generate wrapper and save to file (JSON output)
python cli.py wrap ls --output cli.py

# Parse command specification (JSON output)
python cli.py parse ls

# Execute command (JSON output)
python cli.py execute ls --args "/root" --options '{"--all": true}'

独立模式（可读输出）

# Generate wrapper in memory (human-readable output)
python cli.py --standalone wrap ls
python cli.py --human wrap ls  # Alternative flag

# Parse command specification (human-readable output)
python cli.py --standalone parse ls

# Execute command (human-readable output)
python cli.py --standalone execute ls --args "/root" --options '{"--all": true}'

# Generate CLI file (human-readable output)
python cli.py --standalone wrap tar --output cli.py

# Update existing CLI file (human-readable output)
python cli.py --standalone wrap find --update cli.py

图书馆使用

from ucw import UniversalCommandWrapper

# Initialize UCW
ucw = UniversalCommandWrapper(platform_name="auto")

# Parse and wrap a command
spec = ucw.parse_command("echo")
wrapper = ucw.build_wrapper(spec)

# Execute the command with arguments
result = wrapper.run("hello", "world")
print(result.stdout)

📖 使用方法

如需全面的使用文档，请参阅 使用指南。

快速示例

CLI 使用方法：

# Generate wrapper
python cli.py wrap echo

# Parse command
python cli.py parse ls

# Execute command
python cli.py execute echo --args "hello" "world"

图书馆使用指南：

from __init__ import UniversalCommandWrapper

ucw = UniversalCommandWrapper()
spec = ucw.parse_command("echo")
wrapper = ucw.build_wrapper(spec)
result = wrapper.run("hello", "world")
print(result.stdout)

🏗 建筑学

ucw/
├── __init__.py              # Main UCW class and exports
├── cli.py                   # Command-line interface
├── models.py                # Core data models
├── wrapper.py               # CommandWrapper implementation
├── parser/                  # Platform-specific parsers
│   ├── __init__.py
│   ├── base.py             # Abstract base parser
│   ├── windows.py          # Windows command parser
│   └── posix.py            # POSIX command parser
├── generator/               # Wrapper and file generation
│   ├── __init__.py
│   ├── wrapper_builder.py  # Wrapper building logic
│   └── file_writer.py      # File writing utilities
├── tests/                   # Test suite
│   └── test_basic.py       # Basic functionality tests
├── docs/                    # Documentation
│   ├── plugin-development-guide.md
│   └── project-idea.md
├── requirements.txt         # Production dependencies (zero external deps)
├── requirements-testing.txt # Testing and development dependencies
└── README.md               # This file

数据流

  1. 命令分析UCW 使用平台特定的方法获取帮助文本
  2. 解析帮助文本被解析以提取选项和位置参数
  3. 类型推断类型根据描述和参数名称进行推断
  4. 封装生成CommandSpec 被转换为可执行的 CommandWrapper
  5. 执行命令在执行时会正确处理参数

支持的命令格式

Windows 命令

  • 格式： command /?
  • 选项： /option， /option:value
  • 示例： dir /?， copy /?

POSIX 命令

  • 格式： command --help 或者 man command
  • 选项： -o， --option， --option=value
  • 示例： ls --help， grep --help

🤝 贡献

我们欢迎投稿！请参阅 CONTRIBUTING.md 翻译为中文是：“贡献指南.md” 或 “如何贡献.md”（具体翻译可能根据上下文有所调整，但基本意思是指向一个关于如何为项目做出贡献的指南文件） 详情如下。

开发环境设置

# Clone repository
git clone https://github.com/actuallyrizzn/ucw.git
cd ucw

# Install in development mode
pip install -e .

# Install production dependencies (zero external dependencies)
pip install -r requirements.txt

# Install testing dependencies (for development/testing)
pip install -r requirements-testing.txt

# Run tests
python -m pytest tests/

添加新功能

  1. 为仓库创建分支
  2. 创建一个特性分支
  3. 做出你的更改
  4. 添加测试
  5. 提交一个拉取请求

📄 许可证

代码许可证

这个项目遵循GNU Affero通用公共许可证第3版（AGPL-3.0）授权 - 详见 许可证 文件中有详细信息。

文档许可证

本文件依据知识共享署名-相同方式共享4.0国际许可协议（CC BY-SA 4.0）进行许可——详见 许可证文档 文件中详述。

🔒 安全考虑事项

UCW执行系统命令，因此需考虑其安全影响：

  • 命令验证UCW不验证命令安全性
  • **特权提升（或权限提升）**以当前用户权限运行命令
  • **输入消毒（或输入清理）**在传递给UCW之前验证输入

UCW安全模型

UCW假设运行时环境定义了自己的边界。为了实现隔离，应在容器或受限用户命名空间内部署SMCP。UCW完全在这些边界内运行——它既不会强制执行这些边界，也不会绕过它们。

推荐的安全实践：

  • 在Docker容器中运行SMCP 或者轻量级虚拟机
  • 仅挂载目录 或您希望代理看到的设备
  • 使用受限服务帐户 或没有sudo权限的UID
  • CPU/内存/网络限制 带有容器或cgroup限制

这种方法使代理拥有全面的覆盖范围 在那个定义好的沙盒范围内同时保持UCW（统一内容仓库/用户创建内容等，具体含义根据上下文确定）在理念上的纯粹性： 最大能力，用户定义的主权.

🙏 致谢

  • 受无缝集成命令行工具需求的启发
  • 专为Animus、SanctumOS和Letta MCP服务器生态系统打造
  • 感谢Python社区提供的出色标准库工具

📞 支持

通用命令封装器 - 使命令行工具能够被Python应用程序访问。

相关 MCP