mycli

name	mycli
description	一个专为 AI Agent 调用设计的 CLI 工具，支持结构化 JSON 输出。通过 exec 工具调用，支持 calc（数学计算）、search（文件搜索）、sysinfo（系统信息）三个命令。
version	0.1.0
author	AI Agent 学习项目

mycli - Agent-Friendly CLI Tool

一个专为 AI Agent 调用设计的 CLI 工具，支持结构化 JSON 输出，可被 OpenClaw 等 Agent 框架直接调用。

前置条件

CLI 已安装在 /Users/kirito/miniconda3/bin/mycli（通过 pip install -e . 安装在 python-demo 目录）

命令一览

1. calc - 安全数学计算

通过 AST 解析安全求值，支持常用数学函数和运算符。

# 基础运算
mycli calc "2 ** 10"                    # 1024
mycli calc "sqrt(144) + pi"             # 15.141593
mycli calc "log(1024) / log(2)"         # 10.0

# JSON 输出（供 Agent 解析）
mycli calc --json "1 + 2 * 3"

JSON 输出示例：

{
  "success": true,
  "data": {
    "expression": "1 + 2 * 3",
    "result": 7
  },
  "command": "calc"
}

支持的运算：

• 算术：+ - * / // % **
• 函数：sqrt, log, log2, log10, sin, cos, tan, abs, round, ceil, floor, min, max, sum
• 常量：pi, e

2. search - 文件搜索

搜索文件和内容，输出结构化结果供 Agent 处理。

# 按模式搜索文件
mycli search ./src -p "*.py"

# 按内容关键词搜索
mycli search ./src -k "TODO"

# 组合搜索 + JSON 输出
mycli search . -p "*.md" -k "agent" --json

JSON 输出示例：

{
  "success": true,
  "data": {
    "directory": "/path/to/src",
    "pattern": "*.py",
    "keyword": null,
    "total_results": 3,
    "files": [
      {
        "path": "main.py",
        "absolute_path": "/path/to/src/main.py",
        "size_bytes": 1024,
        "extension": ".py"
      }
    ]
  },
  "command": "search"
}

3. sysinfo - 系统信息

获取当前系统环境信息，Agent 可据此调整行为。

# 查看全部信息
mycli sysinfo

# 只看 Python 信息
mycli sysinfo --section python

# JSON 输出
mycli sysinfo --json

JSON 输出示例：

{
  "success": true,
  "data": {
    "system": {"os": "Darwin", "machine": "arm64", ...},
    "python": {"version": "3.13.0", "executable": "/path/to/python", ...},
    "environment": {"cwd": "/Users/kirito", "user": "kirito", ...},
    "timestamp": "2026-04-24T20:00:00"
  },
  "command": "sysinfo"
}

Agent 调用示例

通过 OpenClaw 的 exec 工具调用：

# 计算表达式
mycli calc --json "2 ** 10"

# 搜索 Python 文件
mycli search --json /Users/kirito/repos -p "*.py" -k "TODO"

# 获取系统信息
mycli sysinfo --json

设计原则

原则	说明
JSON 优先	所有命令支持 --json，输出可解析的结构化数据
自描述	--help 提供完整用法，Agent 可自动发现能力
安全求值	calc 使用 AST 白名单，不执行任意代码
统一响应	成功返回 {"success": true, "data": ...}，失败返回 {"success": false, "error": ...}
退出码	0 = 成功，1 = 失败

项目位置

源代码：/Users/kirito/repos/ai-agent/cli/python-demo/mycli/