autocom 1.2.4

一款用于自动化执行串口指令的命令行工具，支持多设备、多指令的串行和并行执行

AutoCom

一款用于自动化执行串口指令的命令行工具，支持多设备、多指令的串行和并行执行。

---

📦 安装

从 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        # 变更日志

---

📚 文档

文档	说明
docs/About.md	项目背景与设计理念
docs/Started.md	开发快速指南与发布流程
docs/Actions.md	所有 Action 操作项的详细说明
docs/DEV.md	开发工具使用说明
docs/ToDO.md	待办事项与未来计划
CHANGELOG.md	版本变更历史
docs/MCP.md	MCP Server: AI Agent 接口

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

---

🔧 核心功能

功能	说明
多设备支持	同时管理多个串口设备，支持不同配置
串行/并行执行	指令可按顺序执行或并行并发执行
Action 扩展系统	通过 ActionHandler 自定义指令成功/失败后的处理逻辑
配置覆盖机制	ConfigForDevices / ConfigForCommands 简化重复配置
常量和变量	Constants 支持用户输入变量，在指令参数中引用
文件夹遍历	批量执行文件夹内所有执行配置文件
监控模式	监听文件夹，新文件自动执行
持续日志监听	后台线程持续记录串口输出
MCP Server	为 AI Agent 提供串口操作接口，支持 Claude Desktop 等 MCP 客户端

Monitor 命令高级参数

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

参数	类型	默认值	说明
priority	int	0	命令排队优先级，值越大越先执行。用于在监听不断流时插队执行高优先级命令。
completion_rules	object	null	命令完成判定策略。可控制终止模式、空闲收敛时间与期望响应约束。

completion_rules 支持字段：

字段	类型	默认值	说明
expected_required	bool	false	为 true 时，即使命中终止词，也必须继续等待 expected_responses 命中才算完成。
terminal_patterns	string[]	["OK", "ERROR"]	终止词列表。
complete_patterns	string[]	[]	自定义完成词，任意命中即可完成。
idle_timeout	float	min(timeout/3, 2.0)	在有响应后，连续空闲多久判定采集完成（秒）。
settle_after_terminal	float	0.05	命中终止词后额外等待的收敛时间（秒）。

示例：

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 工具

工具名	描述	关键参数
list_devices	列出可用串口设备	无需参数
execute_command	发送单条指令并获取响应	port, command, baud_rate(可选)
execute_commands	批量执行多条指令	port, commands[], parallel(可选)
load_dict	加载 AutoCom 执行配置文件 JSON 配置	file_path, config_path(可选)
monitor_port	监听串口输出	port, duration(可选)

配置 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