Metadata-Version: 2.4
Name: miaozhi-cli
Version: 0.1.0
Summary: Command-line client for 秒针知识库 (miaozhi-kb), wrapping its token-authorized REST API.
Author: miaozhi-kb
License: Apache License, Version 2.0
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.8
Requires-Dist: requests<3.0.0,>=2.30.0
Requires-Dist: beartype<0.19.0,>=0.18.5

# miaozhi CLI


---

## 一、安装


使用者只需要装好 Python 3.10-3.12，直接从 PyPI 安装：

```bash
pip install miaozhi-cli
miaozhi login
```

安装完成后，命令就是全局的 `miaozhi`。下文示例统一用 `miaozhi ...`。



## 二、配置

配置来源优先级：**环境变量 > `~/.miaozhi/config.json`**。

```bash
# 交互式配置（推荐）
miaozhi login
# 依次输入 Endpoint（如 http://127.0.0.1:9380）和 API Token

# 或者用环境变量（适合 CI/脚本，优先级更高）
export MIAOZHI_ENDPOINT=http://127.0.0.1:9380
export MIAOZHI_TOKEN=<your-api-token>
```

API Token 从秒知 Web 端「API」相关设置页面签发（对应后端 `/new_token` 接口）。

```bash
miaozhi config show              # 查看当前配置（token 只显示前 6 位）
miaozhi config set endpoint http://host:9380
miaozhi config set token <token>
miaozhi config use my-kb         # 设默认知识库，后续命令可省略 --kb
```

---

## 三、命令总览

| 分组 | 命令 | 作用 |
|---|---|---|
| 认证 | `login` | 交互式配置 endpoint + token |
| 配置 | `config show` / `set` / `use` | 查看/修改本地配置、设默认知识库 |
| 知识库 | `kb list` / `create` / `info` / `update` / `delete` / `export` | 知识库的增删查改与元数据导出，支持 `--type doc\|data\|wiki` |
| 检索 | `search` | 检索/问数，支持 `--type doc\|data\|wiki` |
| 问答 | `ask` | 走完整 RAG 流程，返回大模型生成的答案（仅 doc） |
| 摄取 | `ingest add` / `status` / `update` / `cancel` | 上传文档、查看解析进度、替换文档、取消解析（仅 doc） |
| 知识图谱 | `graph generate` / `stats` / `entity` / `relation` / `export` | 生成图谱、查看状态、查实体/关系、导出（仅 doc） |
| 体验 | `completion` | 生成 bash/zsh/fish 自动补全脚本 |

`--format table|json` 在大部分列表类命令上都可用，`json` 便于配合 `jq` 做管道处理。

---

## 四、知识库管理（`kb`）

支持三种知识库类型：`doc`（文档知识库，默认）/ `data`（数据知识库）/ `wiki`（Wiki 知识库）。

```bash
miaozhi kb list [--type doc|data|wiki] [--format table|json]   # --type 默认 doc
miaozhi kb create --name my-kb [--desc "描述"]                  # doc（默认）
miaozhi kb create --type data --name my-data-kb \
  --db-type mysql --db-host 10.0.0.1 --db-port 3306 \
  --db-name mydb --db-user root --db-password secret          # data，一次性把连接信息也配好
miaozhi kb create --type wiki --name my-wiki --space-type personal

miaozhi kb info my-kb                        # 不传 --type 会自动按 doc→data→wiki 依次探测
miaozhi kb update my-kb --desc "新描述"        # doc；data 用 --db-*，wiki 用 --llm-id/--embd-id
miaozhi kb delete my-kb [--yes]               # 不加 --yes 会二次确认
miaozhi kb export my-kb [--output kb.json]    # 不加 --output 打印到 stdout
```

`info`/`update`/`delete`/`export` 按名字操作单个知识库时，**不传 `--type` 会自动依次尝试 doc→data→
wiki**，找到哪个类型就用哪个；如果知道类型，加 `--type` 可以跳过探测、避免同名歧义。`list`/`create`
因为必须先知道类型才能操作，`--type` 固定默认 `doc`。

不同类型输出的字段不一样（doc 是文档数/chunk 数，data 是数据库连接信息，wiki 是 space_type/owner），
这是三种知识库本身模型不同决定的，不是 bug。

---

## 五、检索与问答（`search` / `ask`）

`search` 支持三种知识库类型，语义完全不同：

```bash
# --type doc（默认）：chunk 语义检索，返回命中片段 + 相似度分数
miaozhi search "如何配置广告监测" --kb my-kb --top 5
miaozhi search "API 接入文档" --kb my-kb --format json | jq '.[].similarity'

# --type data：自然语言问数，转成 SQL 执行，返回 SQL + 结果表格
miaozhi search "上个月总共有多少条活动数据" --kb my-data-kb --type data
miaozhi search "..." --kb my-data-kb --type data --format json   # 原样输出 {sql, columns, rows, row_count, error}

# --type wiki：Wiki 页面检索，返回命中页面标题 + 相似度分数
miaozhi search "霸王茶姬" --kb my-wiki --type wiki --top 5
```

`ask` 目前只支持文档知识库（doc），走完整 RAG 流程（检索 + 大模型生成答案）：

```bash
miaozhi ask "广告归因的准确率是多少？" --kb my-kb
miaozhi ask "如何接入 SDK？" --kb my-kb --with-sources   # 带引用来源
miaozhi ask "Q3 的 DAU 数据" --kb my-kb --format json
```

`--kb` 都可以省略，前提是用 `miaozhi config use <kb>` 设过默认知识库。

`ask` 首次对某个知识库提问时，会自动创建一个名为 `miaozhi-cli-<kb名>` 的 chat 助手并复用；每次调用都是
新开一轮对话（one-shot，不带多轮上下文记忆）。

---

## 六、摄取文档（`ingest`）

目前只支持文档知识库（doc）。数据知识库是连数据库/建表，Wiki 知识库是页面/数据源，摄取语义完全不同，
还没有对应的 CLI 命令。

```bash
miaozhi ingest add --kb my-kb --file ./report.pdf        # 上传并排队解析
miaozhi ingest status --kb my-kb                          # 查看解析进度（含文档 id）
miaozhi ingest update --kb my-kb --file ./report-v2.pdf   # 按文件名替换旧文档，重新解析
miaozhi ingest cancel --kb my-kb --doc-id <id>            # 按 id 取消解析（可重复传多个 --doc-id）
miaozhi ingest cancel --kb my-kb --name report.pdf        # 或者按文件名取消
```

---

## 七、知识图谱（`graph`）

```bash
miaozhi graph generate --kb my-kb                          # 触发图谱生成（需要知识库已开启 GraphRAG）
miaozhi graph stats --kb my-kb                              # 生成状态 + 覆盖度统计
miaozhi graph entity "广告监测" --kb my-kb                   # 查某个实体的类型/描述/关系/引用来源
miaozhi graph relation --kb my-kb --source "广告监测" --target "数据报表"   # 查两个实体间的关系
miaozhi graph export --kb my-kb [--output graph.json]       # 导出完整图谱（nodes/edges + mind map）
```

---

## 八、Shell 自动补全（`completion`）

```bash
eval "$(miaozhi completion bash)"    # 加到 ~/.bashrc
eval "$(miaozhi completion zsh)"     # 加到 ~/.zshrc
miaozhi completion fish > ~/.config/fish/completions/miaozhi.fish
```

---

## 九、退出码

- `0` 成功
- `1` 一般错误（参数错误、资源不存在等）
- `2` 未配置 endpoint/token
- `3` 网络错误（请求异常）

---

## 十、已知限制


- `graph` 命令依赖的后端接口（`api/apps/sdk/graph_sdk.py`）是新增文件，路由只在服务进程**启动时**扫描
  注册一次——如果你的秒知服务是在这个文件加进去之前启动的，需要重启一次服务进程才能让这组命令生效。
- `graph generate`/`graph stats` 等命令要求对应知识库已经在 Web 端开启过 GraphRAG（`parser_config`
  里的 `graphrag.use_graphrag`），否则会报"GraphRAG is not enabled"或返回 `disabled` 状态。
- `ask`/`ingest`/`graph` 只支持文档知识库（doc），不支持 data/wiki——问答走的是另一套
  assistant 体系，摄取/图谱的语义在数据知识库和 Wiki 知识库上完全不一样（数据知识库是连表不是解析
  文档，Wiki 是页面不是文档），没有直接对应的操作可以照搬。
- `kb create --type data` 时，如果传了 `--db-*` 连接信息：后端创建接口本身只接受 `name`/`description`，
  CLI 是先建好 kb 再紧接着调一次更新把连接信息写进去（两次请求，对使用者表现为一个命令）。中途如果第二
  步失败（比如连接信息校验不过），knowledge base 本身已经建好了，需要手动 `kb update --type data` 补上
  或者 `kb delete --type data` 删掉重来。
- data 类型的 `search` 本质是"自然语言生成 SQL 再执行"，如果目标数据库连不上（网络/账号密码问题），
  会正常返回生成好的 SQL 和执行报错，不是 CLI 的 bug——这个我在真实环境里遇到过一次并确认过是数据库
  连接问题。
