背景

agent 和 ai 接入项目， 或者接入企业ai， 此时发现就像一个人有头脑 但是手上没工具， 很多事情知道想做 但是不知道怎么做， 没权限做，或者怕做的越界了。 此时就需要有这么个工具：

CLI 就是 AI 能够理解和执行的“结构化语言”。 CLI 统一封装了所有能力，让 Agent 从需要理解几十套系统的复杂逻辑，降维成只需调用 infra-cli 的标准化指令，从根本上解决了开发 AI Agent 时最头痛的 “工具碎片化”与“上下文缺失” 问题

集成的功能点

集成 SRE、中间件、可观测性、效能 四大领域的数十种原子操作

领域	子命令示例	功能说明
SRE	cmdb, db	CMDB 资产查询、数据库管理
Mid（中间件）	redis, nacos, etcd, mq, es	中间件实例管理、配置操作、集群查询等
Apm（可观测）	metric, log, trace, alarm-event	指标查询、日志检索、链路追踪、告警事件处理
Ep（效能）	dep, change, notice	部署、变更工单、通知发送

落地md

infra-cli 快速搭建指南

面向「换机器、新目录、给协作者照着做」的落地说明。本文档不包含域名、Token、账号等敏感信息；内网 PyPI、网关地址等

---

1. 环境与工具

项	要求
Python	>= 3.14（与 pyproject.toml 中 requires-python 一致）
Make	可选。若无 Make，可按下文「无 Make」小节用等价命令
操作系统	Makefile 按 Unix 习惯编写；Windows 建议使用 WSL2，或在 Git Bash 中自行改编命令

---

2. 安装

在项目根目录执行：

make install-dev

该目标会：

1. 若不存在则创建 .venv
2. 执行 .venv/bin/pip3 install -e ".[dev]"（可编辑安装 + 开发依赖）

3. 验证安装（与 make verify 一致）

make verify

能正常打印版本与顶层帮助即表示 可编辑安装成功。

---

4. 日常开发命令（与 Makefile 一致）

命令	作用
make fmt	black 格式化 src/、tests/
make lint	flake8 + mypy
make test	pytest
make test-cover	覆盖率，报告在 htmlcov/index.html
make build	构建 dist/（sdist + wheel；会短时改写 version.py 再恢复）
make clean	清理构建与常见缓存
make clean-all	同上并删除 .venv
make gen-docs	生成/更新 docs/CLI.md、docs/CLI.html
make check-docs	CI 用：检查 CLI 文档是否过期

---

5. 如何运行 infra-cli

推荐（安装路径固定，避免与 Keychain 等行为错位）：

.venv/bin/infra-cli <子命令> ...

全局输出、超时等与根命令一致，常用：

• -o json / -o yaml / 默认 table
• --timeout <秒>（默认以 cli.py 中定义为准，一般为 30）
• -e test|pre|prod（子命令若需要环境）

若仅用源码快速试一把（未走 pip install -e 时）：

PYTHONPATH=src .venv/bin/python -m infra_cli.cli --help

---

6. 配置文件

6.1 加载优先级（与代码一致）

优先级	方式	说明
L1（最高）	--config <路径> 或环境变量 INFRA_CLI_CONFIG	指定文件不存在会直接报错
L2	~/.infra-cli/config.yaml	用户目录常驻配置
L3	仓库内 config.example.yaml	仅在开发时从当前工作目录等规则下作为兜底；勿把真实密钥提交进仓库

环境名优先：命令行 -e > INFRA_CLI_ENV > 配置文件中的 default_env。

6.2 初始化用户配置（可选）

make init-config

会调用 .venv/bin/infra-cli config init，生成/更新用户侧配置路径（以命令实际行为为准）。勿将含真实 Token 的文件提交到 Git。

6.3 仓库内 config.example.yaml

仅作模板；本地可把 dev_mode 等改为适合调试的值，改动的含密内容不要提交。

6.4 Makefile 与 .env

Makefile 使用 -include .env，若存在 .env 会导出其中变量（常用于本地覆盖）。不要将 .env 或含密钥文件提交仓库；团队规范若提供 .env.example 可仅保留变量名。

---

7. 产物目录（建议勿提交）

路径	说明
.venv/	虚拟环境
dist/、build/、htmlcov/	构建与覆盖率
*.egg-info/	安装元数据（.gitignore 已忽略）
__pycache__/、.pytest_cache/	缓存

---

8. 排障清单

1. python3 --version 是否为 3.14+。
2. 是否在仓库根目录执行 make install-dev。
3. make verify 是否通过。
4. 私有依赖是否在公司网络 + 正确索引配置下安装成功。
5. make test / make lint 的具体报错。
6. nacos：是否已 export 对应 NACOS_OPENAPI_BASE_URL_*，以及本机/网络能否访问该 Base URL。

---

9. 延伸阅读

• AGENTS.md：架构与强制约定
• README.md：项目总览与目录说明
• docs/CLI命令开发指南.md：扩展命令
• docs/CLI.md：全量命令参考（make gen-docs 生成）

# infra-cli 延伸阅读汇总

---

## 第一部分：项目定位与领域（对应 `README.md` / `AGENTS.md` 概述）

**infra-cli** 是公司基建统一 CLI，Python 实现，统一入口 **`infra-cli`**，按领域提供运维与效能相关子命令。

| 领域 | 命令前缀（示例） | 职责概要 |

|------|------------------|----------|

| **Sre** | `cmdb`、`db` | CMDB / 数据库等相关能力 |

| **Mid（中间件）** | `redis`、`nacos`、`etcd`、`mq`、`es` 等 | 中间件管理 |

| **Apm（可观测）** | `metric`、`log`、`trace`、`alarm-event` 等 | 指标 / 日志 / 链路 / 告警 |

| **Ep（效能）** | `dep`、`change`、`notice` 等 | 部署 / 变更 / 通知等 |

**技术栈（与 `pyproject.toml` 一致）**：Python ≥ 3.14、Click、requests、PyYAML、tabulate、colorama；质量工具含 pytest、black、flake8、mypy。

**命令形态**：`infra-cli <资源> <动作> [选项]`；常见全局选项包括 `-e/--env`、`-o/--output`、`--json`、`--timeout` 等（完整列表见下文「命令参考」）。

---

## 第二部分：仓库与源码布局（精简版）

```

infra-cli/

├── pyproject.toml # 包元数据、依赖、入口点 `infra-cli`

├── Makefile # install-dev / test / lint / build / gen-docs 等

├── config.example.yaml # 开发兜底配置模板（勿提交真实凭据）

├── src/infra_cli/

│ ├── cli.py # CLI 入口与命令注册

│ ├── version.py # 版本信息

│ ├── common/ # 配置、输出、错误、客户端工厂等横切能力

│ ├── sre/ # Sre 域

│ ├── mid/ # 中间件域（含 nacos 等）

│ ├── apm/ # 可观测域

│ └── ep/ # 效能域

├── tests/ # 与 src 对应的单测

├── docs/ # 文档（含本文件、CLI 参考等）

└── scripts/ # 如 gen_cli_docs 等脚本

```

具体文件名以仓库当前状态为准；领域目录可能随迭代增减。

---

## 第三部分：开发约定摘录（对应 `AGENTS.md`）

### 配置加载优先级（概念）

| 优先级 | 来源 |

|--------|------|

| 高 | 命令行 `--config` 或环境变量 **`INFRA_CLI_CONFIG`**（路径不存在则报错） |

| 中 | 用户配置 **`~/.infra-cli/config.yaml`** |

| 低 | 开发时仓库内 **`config.example.yaml`**（规则见代码与模板注释；安装为 wheel 后兜底逻辑可能不同） |

### HTTP 客户端（原则）

- 访问公司网关、APM、CMDB、各中间件时，**优先使用** `common` 中提供的 **`get_client` / `get_apm_client` / 各 Session 工厂**，避免在每个命令里重复拼鉴权与重试。

- 具体 host、密钥来自配置与环境变量，**本文档不列举**。

### 命令帮助与输出

- 面向用户的帮助文案一般为**中文**；技术字段名（如 `promql`）可保留英文。

- 列表空结果等场景遵守项目内 skills / 规范（见 `skills/` 与 `AGENTS.md` 原文）。

### 认证与可执行文件路径（要点）

- 日常推荐使用**可编辑安装或正式安装**生成的 **`infra-cli` 可执行文件**路径调用；若使用 `python -m` 方式，可能与部分依赖系统凭据存储的行为不一致（详见 `AGENTS.md`）。

### 常见环境变量名（仅名称，不含取值）

| 变量名 | 用途说明（摘要） |

|--------|------------------|

| `INFRA_CLI_CONFIG` | 显式指定配置文件路径 |

| `INFRA_CLI_ENV` | 默认环境名 |

| `CONFIG_PATH` | SDK 相关配置文件路径（见 `bootstrap` 类逻辑） |

| 私仓发布相关 | 发布到内部 PyPI 时使用账号类变量（**取值由 CI/个人保管，勿入库**） |

### 命名

- **资源**：kebab-case，如 `redis`、`alarm-event`。

- **动作**：动词，如 `list`、`get`、`deploy`。

- **选项**：kebab-case，如 `--app-name`；常用短选项 `-e`（环境）、`-o`（输出）、`-v`（调试）。

### 推荐流程（摘要）

1. 在对应领域目录 `src/infra_cli/<域>/` 增加或修改模块。

2. 在 `cli.py` 中 `import` 并 **`cli.add_command(...)`** 注册。

3. 补充 `tests/` 下对应测试。

4. 运行 `make fmt`、`make lint`、`make test`。

5. 执行 **`make gen-docs`** 更新命令参考文档（见下一节）。

详细步骤、Mock 约定、Click 写法等以 **`docs/CLI命令开发指南.md`** 全文为准。

---

## 第五部分：命令参考文档 `docs/CLI.md`（对应自动生成文档）

- **完整参数、子命令、示例**以 **`docs/CLI.md`** 为准。

- 该文件由 **`scripts/gen_cli_docs.py` 自动生成**，**请勿手改**有自动声明的段落。

- 本地更新命令：

- `make gen-docs` — 生成 / 更新 `docs/CLI.md` 与 HTML

- `make check-docs` — CI 检查与生成内容是否一致

### 全局选项（摘要，与当前生成逻辑一致）

以下适用于「作为全局选项注册」的能力（以实际 `infra-cli --help` 为准）：

- `-e, --env` — 目标环境（可选值以程序定义为准）

- `-o, --output` — `table` / `json` / `yaml`

- `--json` — 等同 `-o json`

- `--yes` — 跳过部分确认

- `-v, --verbose` — 调试日志

- `--no-color` — 关闭彩色

- `--timeout` — 请求超时（秒）

- `--context` — 配置上下文名

- `--config` — 配置文件路径（高优先级）

- `--version` — 打印版本并退出

### 命令总览（领域标签为文档分类，以仓库为准）

仓库中根命令包括（示例，**非穷举**；完整表格见 `docs/CLI.md` 或 `make gen-docs` 后阅读）：

| 根命令 | 文档中的领域标签 |

|--------|------------------|

| `version`、`config`、`auth` 等 | 通用 |

| `cmdb`、`db` 等 | Sre |

| `redis`、`nacos`、`etcd`、`mq`、`es` 等 | Mid |

| `metric`、`log`、`trace`、`alarm-event` 等 | Apm |

| `dep`、`change`、`notice` 等 | Ep |

新增命令后务必重新生成 **`docs/CLI.md`**，避免文档与实现脱节。

---

## 第六部分：与「快速搭建」的关系

环境与安装步骤见 **`docs/快速搭建.md`**。本文档侧重**架构、规范、文档索引**；动手安装请以前者为准。

---

## 第八部分：原始文档索引（需细节时打开）

| 文档 | 用途 |

|------|------|

| `AGENTS.md` | 权威开发约束、错误码、客户端规则全文 |

| `README.md` | 项目总览、目录、配置扩展、发布等（注意不要复制内网 URL 到对外材料） |

| `docs/CLI命令开发指南.md` | 新命令开发全流程与示例 |

| `docs/CLI.md` | 全量命令参数（`make gen-docs` 生成） |

md的架构规划 可以放到ai中 但是要结合实际情况再做检查和调整