📦 安装

从 PyPI 安装（推荐）

pip install autocom

从 GitHub 直接安装

pip install git+https://github.com/iFishin/AutoCom.git

从源码安装

git clone https://github.com/iFishin/AutoCom.git
cd AutoCom
pip install -r requirements.txt
pip install -e .

🚀 快速开始

命令行使用

# 初始化项目结构（创建 dicts/、configs/、temps/ 目录及示例文件）
autocom --init

# 执行配置文件（循环3次）
autocom -d dicts/dict.yaml -l 3

# 无限循环模式（按 Ctrl+C 停止）
autocom -d dicts/dict.yaml -i

# 使用配置文件
autocom -d dicts/dict.yaml -c configs/config.yaml

# 执行文件夹内所有执行配置文件
autocom -f dicts/

# 监控模式（监听文件夹，自动执行新文件）
autocom -m temps/

Python API 使用

from autocom import CommandDeviceDict, CommandExecutor, CommonUtils

# 加载配置
dict_data = {...}  # 你的执行配置文件数据
device_dict = CommandDeviceDict(dict_data)

# 创建执行器
executor = CommandExecutor(device_dict)

# 执行指令
result = executor.execute()

# 清理资源
device_dict.close_all_devices()
executor.data_store.stop()

📁 项目结构

AutoCom/
├── components/         # 核心组件模块（Device、Logger、TablePrinter、CommandDeviceDict、DataStore、CommandExecutor）
├── utils/              # 工具类和辅助函数（ActionHandler、common、dirs）
├── tests/              # 测试文件
├── scripts/            # 构建和维护脚本（dev.py、update_actions_doc.py）
├── docs/               # 项目文档
├── dicts/              # 执行配置文件目录
├── configs/            # 设备配置文件目录
├── AutoCom.py          # 主程序入口
├── cli.py              # 命令行接口
├── version.py          # 版本信息
└── CHANGELOG.md        # 变更日志

📚 文档

📖 格式框架详解（Devices、Commands、Actions 的 JSON 格式说明）参见 docs/About.md。

🔧 核心功能

Monitor 命令高级参数

当设备在 Devices 中开启了 monitor: true 时，Commands 支持以下高级参数：

completion_rules 支持字段：

示例：

Devices:
  - name: DeviceA
    status: enabled
    port: COM22
    baud_rate: 921600
    monitor: true

Commands:
  - command: AT+QVERSION
    device: DeviceA
    timeout: 2000
    expected_responses: ["OK"]
    priority: 8
    completion_rules:
      expected_required: true
      terminal_patterns: ["OK", "ERROR"]
      complete_patterns: ["+READY"]
      idle_timeout: 0.6
      settle_after_terminal: 0.05

🤖 MCP Server（AI Agent 接口）

AutoCom MCP Server 基于 Model Context Protocol (MCP) 实现，让 AI Agent（如 Claude Desktop、Cursor 等）能够直接控制串口设备。

安装

# 安装 MCP 依赖
pip install autocom[mcp]

启动

# Stdio 模式（默认，适合 Claude Desktop）
autocom mcp

# SSE (HTTP) 模式（适合远程调用）
autocom mcp --sse --port 8888
 
# Streamable HTTP 模式（长连接/双向通道，适合需要持续双向消息流的客户端）
autocom mcp --streamable --port 8888 --host 0.0.0.0

认证/鉴权

若在公网或不受信任网络中运行 HTTP 接口，建议启用简单的 API Key 鉴权：

autocom mcp --streamable --port 8888 --host 0.0.0.0 --auth-key s3cr3t

请求需包含 Authorization: Bearer s3cr3t 或 X-API-Key: s3cr3t 头部。 安全建议（简要）：

• 使用反向代理（Nginx/Traefik）对外提供 TLS；避免直接将服务暴露到公网。
• 把密钥放在环境变量或机密管理系统里，不要提交到仓库。
• 配置访问日志、频率限制与防火墙规则来限制滥用。

详情参见 docs/MCP.md。

可用的 MCP 工具

配置 Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "autocom": {
      "command": "autocom",
      "args": ["mcp"]
    }
  }
}

SSE 模式

SSE 模式启动后可通过浏览器或 MCP Inspector 调试：

# 健康检查
http://localhost:8888/health

# MCP Inspector 调试
npx @modelcontextprotocol/inspector
# 连接地址: http://localhost:8888/mcp/sse

使用示例（Python API）

# 扫描设备
result = await client.call_tool("list_devices", {})

# 发送指令
result = await client.call_tool("execute_command", {
    "port": "COM3",
    "command": "AT+GMR",
    "baud_rate": 115200,
    "timeout": 5.0,
})

# 批量执行
result = await client.call_tool("execute_commands", {
    "port": "/dev/ttyUSB0",
    "commands": ["AT", "AT+GMR", "AT+CSQ"],
    "parallel": False,
})

🤝 贡献

欢迎提交 Issue 和 Pull Request！详见 CONTRIBUTING.md。

📄 许可证

MIT License © 2025 iFishin