# 在终端安装 Astra 并查询 MOI 工作区

Astra 是矩阵起源开源的 AI Agent，运行在你的终端里：你用自然语言说要做什么，它会调用工具一步步完成。在本教程中，Astra 通过 MOI 的命令行工具 moi-cli 访问 MOI。例如你输入“列出所有 MOI 的工作区”，Astra 会运行对应的 moi-cli 命令，再把结果整理给你。

技术上，Astra 属于 Agent Runtime：它负责 Agent 的执行循环，本身不包含模型，使用的模型由 MOI 提供，所以你不需要准备模型 API Key。你也不需要先学会 moi-cli 的命令，用 MOI 账号登录一次即可开始。Astra 在你的电脑上运行命令前，默认会先征得你的同意。

下面五步带你完成安装、登录、第一次对话和两次只读查询。整个流程只读取信息，不会创建、修改或删除任何资源。

{.mo-aside}
文中演示图根据一次实际验证的截图制作，已脱敏；点击图片可在新标签页查看大图。版本号和查询结果以你自己的终端为准。

## 开始前准备

- 一台可以访问 MOI 的 macOS 或 Linux 电脑；
- 可以登录 MOI、且至少能访问一个工作区的账号；
- 一个你愿意用于 Astra 会话的工作目录。首次体验时，建议从独立的项目目录启动，不要直接信任整个用户主目录。

## 1. 安装客户端

在电脑自己的终端运行：

```bash
curl -fsSL https://get.matrixorigin.cn/astra | sh
```

终端出现 `Astra and moi-cli are installed.` 就表示安装完成：

```{figure} ../assets/images/tutorials/astra-cli-install-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: 终端显示 Astra 和 moi-cli 安装完成，账号和设备信息已移除
```

{.mo-aside}
如果随后提示找不到 `astra`，请新开终端，或按安装输出中的 PATH 提示操作；不要重复运行安装命令。

## 2. 登录 MOI 与 Astra

在同一个终端运行：

```bash
astra login
```

命令会打开浏览器。若尚未登录 MOI，先完成 MOI 账号登录。浏览器显示 **You are signed in to Astra** 后，回到终端选择要使用的工作区；以终端显示 **Logged in** 为登录完成标志。

::::{dropdown} 查看浏览器成功页
:class-container: mo-fold
:animate: fade-in

```{figure} ../assets/images/tutorials/astra-cli-sign-in-redacted-v2.png
:figclass: mo-shot
:class: agent-guide-image
:alt: 已脱敏的 Astra 浏览器登录成功页，地址栏已遮盖
```
::::

```{figure} ../assets/images/tutorials/astra-cli-login-terminal-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: 终端完成工作区选择并显示 Logged in，授权链接和工作区信息已脱敏
```

{.mo-aside}
浏览器显示成功时，终端中的工作区选择可能还没结束。不要分享浏览器回调 URL 或终端打印的授权 URL，其中包含本次登录的参数。

## 3. 开始对话

在准备工作的目录中运行：

```bash
astra
```

如果出现目录信任提示，请按是否要启用该目录保存的工作区规则作出选择；图中高亮只是当次验证的选项，不要求你也信任该目录。

::::{dropdown} 查看目录信任提示
:class-container: mo-fold
:animate: fade-in

```{figure} ../assets/images/tutorials/astra-cli-trust-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: Astra 首次启动时询问是否信任当前工作目录，真实路径已脱敏
```
::::

进入对话后输入 `Hi`。收到回复，就说明普通聊天可用：

```{figure} ../assets/images/tutorials/astra-cli-chat-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: Astra 会话中输入 Hi 并收到回复，账号及本机路径已移除
```

## 4. 只读查询 MOI

在同一个 Astra 会话中输入：

```{code-block} text
:class: mo-prompt
列出所有MOI的工作区
```

{.mo-aside}
也可以用英文：`List all MOI workspaces I can access.`

首次调用 MOI 工具时，Astra 可能要求批准 `moi-cli ... workspace list`。先核对它是查询工作区的命令，再选择 **Yes** 执行一次。

::::{dropdown} 查看首次命令批准界面
:class-container: mo-fold
:animate: fade-in

```{figure} ../assets/images/tutorials/astra-cli-approval-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: 首次列出 MOI 工作区时的 moi-cli 命令批准提示
```
::::

随后应看到有权限访问的工作区列表：

```{figure} ../assets/images/tutorials/astra-cli-workspaces-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: 已脱敏的 Astra 工作区查询结果，工作区名称、ID 和所有者信息均已遮盖
```

{.mo-aside}
工作区数量和名称因账号而异。图中名称、ID 和所有者信息已脱敏。

## 5. 查看已选工作区的数据库

在同一个会话中继续提问。本次验证使用的是：

```{code-block} text
:class: mo-prompt
List the databases in my currently selected MOI workspace. Do not change any data.
```

Astra 返回已选工作区的数据库及表名；这次验证得到一个业务数据库和两个系统数据库，未修改数据：

```{figure} ../assets/images/tutorials/astra-cli-databases-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: 已选工作区返回一个业务数据库和两个系统数据库，名称已脱敏
```

:::::{admonition} 已知问题
:class: note

这次验证中，`sql meta-databases` 曾因 `unknown field "next_page_token"` 失败，Astra 随后用只读的 `sql meta-db-tree` 取得结果。这是待修复的兼容性问题，并不表示每次查询都会先失败。如果查询没有恢复成功，请保留错误信息排查，不要把缺失的结果当作空数据库。

::::{dropdown} 查看本次错误及替代查询
:class-container: mo-fold
:animate: fade-in

```{figure} ../assets/images/tutorials/astra-cli-db-fallback-term.png
:figclass: mo-term
:class: agent-guide-image
:alt: 数据库列表命令解码失败后，Astra 改用只读的 meta-db-tree 命令
```
::::
:::::

到这里，你已经完成了从安装到第一次 MOI 只读查询。CSV 导入和修改数据属于后续独立流程。