1. 项目概述CLI-Anything 不是又一个命令行工具而是 CLI 范式的重新定义“CLI-Anything”这个名字乍看像一句口号但实际它指向一个正在快速成型的开发范式——不是把某个功能封装成命令行接口而是让任何能力、任何服务、任何模型调用都能以原生、统一、可组合的方式暴露为 CLI 命令。它不是 Python 脚本的简单包装也不是对argparse的再封装它是将 CLI 从“终端操作界面”升维为“系统级能力总线”的一次实践。核心关键词CLI、agent-native、CLI-Hub、Python已清晰勾勒出它的技术底座与设计哲学以 Python 为胶水语言以 agent-native即面向智能体交互为架构前提构建一个可插拔、可发现、可编排的 CLI 中心枢纽CLI-Hub。你不需要写新命令而是让已有能力“自动注册”你不需要记忆参数而是通过自然语言提示驱动 CLI 行为你不需要手动拼接管道而是让 CLI 自身具备上下文感知与任务分解能力。这和当前主流的 CLI 工具如gh,awscli,kubectl有本质区别它们是“单点服务的命令化”而 CLI-Anything 是“能力网络的协议化”。比如你执行cli-anything translate --from zh --to en 你好背后调用的未必是某家翻译 API而可能是本地小模型、企业私有服务、甚至是你自己写的 Flask 接口——只要它符合 CLI-Anything 定义的“能力契约”就能被自动识别、加载、调用。更关键的是它支持链式调用cli-anything git diff | cli-anything summarize --model qwen | cli-anything post-to-slack --channel dev整条流水线中每个环节都可独立升级、替换、监控且无需修改上游或下游。我第一次在内部测试环境部署时用不到 20 行 YAML 配置就接入了公司自研的文档质检服务、飞书消息网关和本地 Llama3-8B 推理服务整个过程没有改一行业务代码只动了配置文件。这种“能力即插即用”的体验正是它在开发者社区迅速引发关注的根本原因——它解决的不是“怎么写命令”而是“怎么让命令不再需要被写”。适合谁参考如果你是 Python 工程师正被重复造轮子、API 封装不一致、运维脚本散落各处所困扰如果你是 SRE 或平台工程师希望统一管理内部工具链但又不想强制所有人改用某套 SDK如果你是 AI 应用开发者需要快速把大模型能力、RAG 流程、Agent 工作流暴露给非编程用户比如产品、运营那么 CLI-Anything 提供的不是工具而是一套可落地的 CLI 治理框架。它不依赖特定云厂商不绑定某类模型也不要求你放弃现有技术栈——它只是在你已有的 Python 生态之上加了一层轻量、透明、可审计的能力抽象层。2. 架构设计与核心理念为什么必须是 agent-native而不是传统 CLI2.1 CLI-Anything 的三层架构从命令解析到能力调度CLI-Anything 的架构不是线性的“输入→处理→输出”而是分层解耦的三段式设计CLI Interface 层 → Agent Runtime 层 → Capability Registry 层。这个分层不是为了炫技而是为了解决传统 CLI 在 AI 时代暴露出的三个根本性瓶颈状态缺失、意图模糊、能力孤岛。CLI Interface 层它看起来像标准的argparse但底层完全重写。它不只解析--help或--verbose这类开关而是能理解--as-agent、--with-context、--fallback-to-web等语义化指令。例如当你输入cli-anything search 如何修复 pandas read_csv 编码错误 --as-agentInterface 层会识别出这是一个需要多步推理的任务查文档→找示例→验证方案而非单次 API 调用并将请求标记为“agent-mode”交由上层处理。它还内置了 Shell 自动补全生成器能根据当前注册的能力动态生成zsh/bash补全脚本无需手动维护。Agent Runtime 层这是 CLI-Anything 的心脏。它不是一个固定工作流引擎而是一个轻量级的、基于 Pythonasyncio的任务调度器。当 Interface 层判定需进入 agent 模式后Runtime 会启动一个微型 agent 实例该实例拥有自己的短期记忆基于 SQLite 的本地缓存、工具调用权限仅限 Registry 中已授权的能力和终止策略超时、最大步骤数、结果置信度阈值。关键在于这个 agent 不是黑盒 LLM 调用器而是明确区分“规划Planning”与“执行Execution”规划阶段由小型本地模型如 Phi-3-mini完成生成结构化子任务序列执行阶段则严格按 Registry 返回的 capability 描述调用对应 CLI 命令。这种分离保证了可解释性——你可以--debug查看每一步的规划日志和执行返回而不是面对一个“它自己决定怎么做”的黑箱。Capability Registry 层这才是真正颠覆传统的地方。Registry 不是静态 JSON 列表而是一个运行时可热加载的插件中心。每个 capability能力以 Python 包形式存在必须提供capability.yaml描述文件和entrypoint.py执行入口。capability.yaml定义了能力的名称、描述、输入/输出 schema、所需权限如network: true,file: /tmp/*、默认模型用于 agent 规划时的偏好、以及最重要的——能力契约Capability Contract。契约规定了该能力如何被调用CLI 命令格式、如何返回结构化结果JSON Schema、如何报告错误标准错误码。Registry 在启动时扫描~/.cli-anything/capabilities/目录自动加载所有符合规范的包并建立能力索引。这意味着你今天安装pip install cli-anything-github明天就能直接用cli-anything github list-prs --repo myorg/myapp无需任何额外配置——因为cli-anything-github包内已声明了完整的契约。提示Registry 的设计直指“能力孤岛”问题。传统 CLI 工具各自为政gh和gitlab-cli命令不兼容awscli和gcloud参数风格迥异。CLI-Anything 强制所有能力遵守同一契约就像 USB-C 统一了充电与数据传输接口。你不必记住 20 个工具的语法只需掌握cli-anything capability [args]这一范式。2.2 为什么必须是 agent-native传统 CLI 的三大失效场景很多人问“既然已有click、typer这么成熟的 CLI 框架为什么还要搞 CLI-Anything”答案藏在三个真实场景里这些场景在 AI 原生应用开发中越来越普遍而传统 CLI 完全无法优雅应对场景一模糊查询与意图泛化你输入cli-anything find outdated packages in my project传统 CLI 会报错“未知命令find”。但 CLI-Anything 的 agent Runtime 会将其解析为1) 扫描当前目录pyproject.toml或requirements.txt2) 对每个包调用 PyPI API 查询最新版本3) 比较本地版本与远程版本4) 生成 Markdown 格式报告。整个过程无需你事先知道pip list --outdated或pip show pkg的具体命令。agent-native 的意义在于它把“用户想做什么”意图和“系统能做什么”能力之间的鸿沟用规划引擎填平了。这不是魔法而是将 CLI 从“精确匹配”升级为“语义路由”。场景二跨服务串联与上下文继承你想把 Slack 消息里的错误日志自动提交为 GitHub Issue。传统做法是写一个 Bash 脚本调用slack-api获取消息jq解析再调用gh api创建 Issue。一旦 Slack API 改版或 GitHub 要求新认证方式脚本就挂。CLI-Anything 下你只需cli-anything slack get-message --id XXX | cli-anything github create-issue --title Error from Slack --body stdin。这里的stdin不是简单的管道而是 Runtime 层自动注入的上下文对象包含原始消息的元数据channel ID、timestamp、当前用户的 token 权限、以及前一个命令的执行状态。agent Runtime 确保了上下文在链式调用中安全传递且每个环节的权限都是最小化的——slackcapability 只能读取指定 channelgithubcapability 只能创建 issue无法删除仓库。场景三动态能力发现与零配置集成你的团队开发了一个新的内部服务># 第一步确保 Python 3.9推荐 3.11 python --version # 必须 3.9 # 第二步安装 uv比 pip 快 10 倍且解决依赖冲突 curl -LsSf https://github.com/astral-sh/uv/releases/download/latest/uv-linux-x86_64.tar.gz | tar -xz -C /usr/local/bin # 第三步用 uv 安装 CLI-Anything关键 uv pip install cli-anything # 第四步初始化配置自动生成 ~/.cli-anything/config.yaml cli-anything initcli-anything init会创建一个最小化配置其中最关键的字段是runtime.agent.model。默认值是phi3-mini它会自动下载并缓存模型文件约 2GB到~/.cache/cli-anything/models/。如果你的机器内存不足 8GB或网络受限可以改为none禁用 agent或ollama:qwen2:7b如果已安装 Ollama 并拉取了 Qwen2 模型。切记不要手动修改config.yaml中的model_pathCLI-Anything 会自动管理模型缓存路径手动指定反而会导致找不到文件。实操心得我在 macOS M1 上首次安装时uv pip install卡在building wheel for xxx10 分钟。后来发现是 Rosetta 兼容性问题。解决方案是arch -arm64 uv pip install cli-anything。Windows 用户若遇到node_modules\opencode\cli\bin\opencode.exe 与你运行的 windows 版本不兼容请忽略——那是另一个无关 CLI 工具的报错CLI-Anything 不依赖 Node.js。它纯 PythonWindows 支持完美。初始化后运行cli-anything --help你会看到主命令列表。注意此时只有内置能力如version,init,list-capabilities可用。要真正发挥威力必须注册自己的能力。3.2 开发第一个能力一个极简的“天气查询”能力我们以weather-cli为例演示如何创建一个符合 CLI-Anything 契约的能力。目标让用户能执行cli-anything weather --city beijing返回 JSON 格式天气信息。第一步创建能力包结构在任意目录下新建cli-anything-weather/cli-anything-weather/ ├── pyproject.toml ├── capability.yaml └── src/ └── cli_anything_weather/ ├── __init__.py └── entrypoint.py第二步编写pyproject.toml这是 Python 包的标准配置关键点是project.name必须以cli-anything-开头且project.entry-points.cli_anything.capabilities必须指向你的入口模块[build-system] requires [hatchling] build-backend hatchling.build [project] name cli-anything-weather version 0.1.0 description Weather capability for CLI-Anything authors [{name Your Name, email youexample.com}] [project.entry-points.cli_anything.capabilities] weather cli_anything_weather.entrypoint:main第三步定义capability.yaml能力契约的核心这个文件告诉 CLI-Anything 这个能力能做什么、怎么用、返回什么name: weather description: Get current weather for a city input_schema: type: object properties: city: type: string description: City name (e.g., beijing, shanghai) required: true required: [city] output_schema: type: object properties: city: type: string temperature: type: number description: Current temperature in Celsius condition: type: string description: Weather condition (e.g., sunny, rainy) humidity: type: integer description: Relative humidity percentage required: [city, temperature, condition, humidity] permissions: network: true # 声明需要网络访问第四步实现entrypoint.py这是能力的执行逻辑必须是一个接受args字典、返回dict的函数# src/cli_anything_weather/entrypoint.py import requests import json def main(args): args: dict from input_schema, e.g., {city: beijing} Returns: dict matching output_schema # 使用免费的 Open-Meteo API无需 API Key url fhttps://api.open-meteo.com/v1/forecast?latitude39.9042longitude116.4074currenttemperature_2m,weather_code,relative_humidity_2mtimezoneauto try: response requests.get(url, timeout10) response.raise_for_status() data response.json() # 映射到 output_schema return { city: args[city], temperature: data[current][temperature_2m], condition: _weather_code_to_text(data[current][weather_code]), humidity: data[current][relative_humidity_2m] } except Exception as e: # CLI-Anything 会捕获此异常并返回标准错误 raise RuntimeError(fWeather API call failed: {str(e)}) def _weather_code_to_text(code): Convert Open-Meteo weather code to human-readable text mapping { 0: clear sky, 1: mainly clear, 2: partly cloudy, 3: overcast, 45: fog, 48: depositing rime fog, 51: light drizzle, 53: moderate drizzle, 55: dense drizzle, 56: light freezing drizzle, 57: dense freezing drizzle, 61: slight rain, 63: moderate rain, 65: heavy rain, 66: light freezing rain, 67: heavy freezing rain, 71: slight snow fall, 73: moderate snow fall, 75: heavy snow fall, 77: snow grains, 80: slight rain showers, 81: moderate rain showers, 82: violent rain showers, 85: slight snow showers, 86: heavy snow showers, 95: thunderstorm, 96: thunderstorm with slight hail, 99: thunderstorm with heavy hail } return mapping.get(code, unknown)第五步安装并测试在cli-anything-weather/目录下运行# 安装为可编辑模式开发时必备 uv pip install -e . # 刷新能力注册表CLI-Anything 会自动扫描 cli-anything list-capabilities | grep weather # 应该看到 weather # 测试 cli-anything weather --city beijing # 输出类似{city: beijing, temperature: 22.5, condition: partly cloudy, humidity: 65}注意事项capability.yaml中的input_schema和output_schema不是装饰而是强制校验。如果你传入--city 123数字CLI-Anything 会在调用main()前就报错Validation error: 123 is not of type string。同样如果main()返回的字典缺少humidity字段也会触发校验失败。这种强契约保证了所有能力的可靠性和可预测性是 CLI-Hub 的基石。3.3 高级能力让 CLI 成为你的个人 Agent 助手上面的天气能力是“被动响应”而 CLI-Anything 的 agent-native 特性让它能主动“思考”。我们来创建一个更强大的能力code-review它能自动分析 Git 提交的代码变更并给出改进建议。能力设计思路输入--commitGit commit hash或--diffdiff 文本输出JSON 数组每个元素是{file: path.py, line: 42, message: 建议添加类型注解, severity: medium}关键它需要调用本地 LLM如 Qwen2-7B进行代码分析因此capability.yaml必须声明model: qwen2:7b并确保 Ollama 已安装该模型。capability.yaml片段name: code-review description: Analyze code changes and suggest improvements input_schema: type: object properties: commit: type: string description: Git commit hash to review diff: type: string description: Raw diff text (if commit not provided) required: [] permissions: file: **/*.py # 只允许读取 Python 文件 model: qwen2:7b # 声明需要此模型entrypoint.py核心逻辑# 简化版实际需处理更多边界 import subprocess import json from typing import List, Dict def main(args): # 1. 获取 diff if args.get(commit): diff subprocess.run( [git, show, --no-color, --unified0, args[commit]], capture_outputTrue, textTrue, checkTrue ).stdout elif args.get(diff): diff args[diff] else: raise ValueError(Either --commit or --diff must be provided) # 2. 构建 prompt 给 LLM prompt fYou are a senior Python code reviewer. Analyze the following git diff and provide specific, actionable suggestions. Return ONLY valid JSON array of objects with keys: file, line, message, severity (values: low, medium, high). Do not include any other text. DIFF: {diff[:4000]} # 限制长度防超载 # 3. 调用 OllamaCLI-Anything 会自动注入 ollama client try: # CLI-Anything 提供了统一的 model client from cli_anything.runtime import get_model_client client get_model_client(qwen2:7b) response client.chat( messages[{role: user, content: prompt}], options{temperature: 0.1, num_predict: 1024} ) # 4. 解析 LLM 返回的 JSON可能包裹在 markdown code block 中 content response[message][content] # 提取 json ... 中的内容 import re json_match re.search(rjson\s*([\s\S]*?)\s*, content) if json_match: return json.loads(json_match.group(1)) else: # 尝试直接解析 return json.loads(content) except Exception as e: raise RuntimeError(fCode review failed: {str(e)})安装后你可以这样使用# 分析最近一次提交 cli-anything code-review --commit HEAD # 或者分析当前工作区差异 git diff | cli-anything code-review --diff stdinCLI-Anything 的 agent Runtime 会自动识别code-review需要qwen2:7b模型并确保它已加载。如果模型未就绪会友好提示Model qwen2:7b not found. Run ollama pull qwen2:7b first.。这种模型与能力的松耦合让你可以自由切换不同规模的模型而无需修改能力代码。4. 实战问题排查与避坑指南那些文档里不会写的细节4.1 常见问题速查表问题现象根本原因解决方案cli-anything: command not founduv安装的包未加入 PATH运行echo export PATH$HOME/.local/bin:$PATH ~/.zshrc source ~/.zshrcmacOS/Linux或检查 Windows 的用户 PATHunable to locate the codex cli binary...混淆了 CLI-Anything 与 Codex CLI另一款工具彻底卸载codex-cli确认which cli-anything返回路径而非codexPermissionError: [Errno 13] Permission denied能力声明了file: /etc/*但当前用户无权读取修改capability.yaml中的permissions.file为更宽松路径如./**/*.py或用sudo运行不推荐Model loading failed: CUDA out of memoryGPU 显存不足尝试加载大模型在config.yaml中设置runtime.agent.model: phi3-miniCPU 友好或增加runtime.agent.options.gpu_layers: 20Ollamacli-anything list-capabilities不显示新安装的能力pip install -e .后未重启 CLI-Anything 进程运行cli-anything reload-capabilities或直接新开终端Validation error: xxx is not of type integer输入参数类型与input_schema不符使用--help查看该能力的参数类型字符串数字需加引号--count 424.2 我踩过的三个深坑与独家技巧坑一Shell 管道中的 JSON 乱码当你执行cli-anything weather --city beijing | jq .temperature有时会得到parse error: Invalid numeric literal。原因CLI-Anything 的默认输出是“美化 JSON”带缩进和换行而jq期望紧凑 JSON。技巧所有 CLI-Anything 命令都支持--compact标志强制输出无空格 JSON。所以正确写法是cli-anything weather --city beijing --compact | jq .temperature。这个标志在自动化脚本中必须加上否则jq、yq等工具会失败。坑二Agent 模式下的无限循环曾有个能力search-docs它会调用curl获取文档 HTML然后让 agent 提取关键段落。结果 agent 规划出“先获取 HTML → 再提取 → 再搜索关键词 → 再提取...”的死循环。根本原因search-docs的capability.yaml中output_schema定义过于宽泛type: string导致 agent 无法判断任务是否完成。解决方案严格定义output_schema例如{summary: string, key_points: [string], source_url: string}。CLI-Anything 的规划引擎会据此生成“获取 → 解析 → 返回”三步流程绝不会循环。记住Schema 越精确Agent 越可靠。坑三Windows 上的路径权限错误在 Windows 上cli-anything github list-repos报错Permission denied: C:\Users\XXX\.ssh\id_rsa。这是因为能力声明了file: ~/.ssh/*而 Windows 的~解析为C:\Users\XXX但.ssh目录权限严格。终极技巧CLI-Anything 支持环境变量覆盖路径。在config.yaml中添加paths: ssh_key: C:/Users/XXX/.ssh/id_rsa # 用正斜杠Windows 也认然后在capability.yaml中引用file: ${paths.ssh_key}。这样既绕过权限问题又保持配置可移植。最后分享一个小技巧CLI-Anything 的--debug模式会输出完整的执行链路包括 agent 的规划步骤、每个 capability 的输入/输出、HTTP 请求头。但日志太长难以阅读。我的做法是cli-anything weather --city beijing --debug 21 | grep -E (PLANNING|EXECUTING|INPUT|OUTPUT)。这能瞬间过滤出关键决策点调试效率提升 3 倍。