Metadata-Version: 2.4
Name: autocom
Version: 1.2.4
Summary: 一款用于自动化执行串口指令的命令行工具，支持多设备、多指令的串行和并行执行
Author-email: iFishin <i@ifishin.top>
License: MIT
Project-URL: Homepage, https://github.com/iFishin/AutoCom
Project-URL: Bug Reports, https://github.com/iFishin/AutoCom/issues
Project-URL: Source, https://github.com/iFishin/AutoCom
Keywords: serial,automation,testing,embedded,iot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Requires-Dist: wcwidth
Requires-Dist: requests
Requires-Dist: pywifi
Provides-Extra: mcp
Requires-Dist: fastmcp>=0.1.0; extra == "mcp"
Requires-Dist: starlette; extra == "mcp"
Requires-Dist: uvicorn; extra == "mcp"
Requires-Dist: pyyaml; extra == "mcp"
Provides-Extra: yaml
Requires-Dist: pyyaml; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Dynamic: license-file

<div align="center">

# AutoCom

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

![Cross Platform](https://img.shields.io/badge/cross--platform-Windows%20%26%20Linux-success.svg)
![Serial Communication](https://img.shields.io/badge/communication-Serial%20Port-orange.svg)
![Multi-Device](https://img.shields.io/badge/support-Multi--Device-blueviolet.svg)
![Automation](https://img.shields.io/badge/type-Automation%20Tool-red.svg)
![PyPI](https://img.shields.io/badge/PyPI-autocom-blue.svg)

</div>

---

## 📦 安装

### 从 PyPI 安装（推荐）

```bash
pip install autocom
```

### 从 GitHub 直接安装

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

### 从源码安装

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

---

## 🚀 快速开始

### 命令行使用

```bash
# 初始化项目结构（创建 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 使用

```python
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()
```

---

## 📁 项目结构

```plain
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/About.md) | 项目背景与设计理念 |
| [docs/Started.md](docs/Started.md) | 开发快速指南与发布流程 |
| [docs/Actions.md](docs/Actions.md) | 所有 Action 操作项的详细说明 |
| [docs/DEV.md](docs/DEV.md) | 开发工具使用说明 |
| [docs/ToDO.md](docs/ToDO.md) | 待办事项与未来计划 |
| [CHANGELOG.md](CHANGELOG.md) | 版本变更历史 |
| [docs/MCP.md](docs/MCP.md) | MCP Server: AI Agent 接口 |

> 📖 **格式框架详解**（Devices、Commands、Actions 的 JSON 格式说明）参见 [docs/About.md](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` | 命中终止词后额外等待的收敛时间（秒）。 |

示例：

```yaml
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)](https://modelcontextprotocol.io/) 实现，让 AI Agent（如 Claude Desktop、Cursor 等）能够直接控制串口设备。

### 安装

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

### 启动

```bash
# 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 鉴权：

```bash
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](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` 中添加：

```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）

```python
# 扫描设备
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](CONTRIBUTING.md)。

## 📄 许可证

MIT License © 2025 iFishin
