# Matrix CLI

Matrix CLI 是一个功能强大的命令行工具，用于管理 Matrix 生态系统的Skill、Agent、Model等。通过这个工具，您可以轻松搜索、安装、更新、卸载和发布。

## 安装指南

### 全局安装

```bash
npm install -g @matrixopenharmony/matrix-cli
```

### 验证安装

```bash
matrix --version
```

## 快速开始

### 1. 登录

在使用需要认证的功能之前（matrix whoami和matrix skill publish需要鉴权，其他的命令不需要认证登录），您登录执行如下命令：

```bash
matrix login
```

系统会提示您选择登录方式：

- **浏览器登录授权**：自动打开浏览器进行授权登录
- **手动输入私有令牌**：手动输入从 Matrix 平台获取的私有令牌，获取路径：访问[Matrix](https://matrix.openharmony.cn/)并登录，然后跳转到[私有令牌管理](https://matrix.openharmony.cn/#/profile/account/accessToken)获取

### 2. 搜索技能

搜索您需要的技能：

```bash
matrix skill search <关键词>
matrix skill search --tag <tag>     通过标签英文名称搜索技能
matrix skill search --tag <tag> <关键词>    通过标签英文名称搜索技能
```

### 3. 安装技能

安装找到的技能：

```bash
matrix skill install <技能名称>
```

### 4. 查看已安装技能

查看所有已安装的技能：

```bash
matrix skill list
```

## 命令说明

### 全局选项

| 选项                | 描述                                     |
| ------------------- | ---------------------------------------- |
| `-V, -v, --version` | 显示Matrix CLI 版本                      |
| `--workdir <dir>`   | 工作目录（默认：当前目录）               |
| `--dir <dir>`       | 技能目录（相对于工作目录，默认：skills） |
| `-h, --help`        | 显示命令帮助                             |

### 认证命令

#### 登录

```bash
matrix login
```

支持两种登录方式：

**浏览器登录授权**：系统自动生成 client-code，并打开浏览器进行授权登录

**手动输入私有令牌**：手动输入从 Matrix 平台获取的私有令牌

#### 登出

```bash
matrix logout
```

登出并清理所有用户信息（token、authType、clientCode）。

#### 验证身份

```bash
matrix whoami
```

验证当前令牌的有效性并显示用户信息（用户名和账号）。

### 配置管理命令

#### 设置代理

```bash
matrix config set proxy <url>
```

配置 HTTP/HTTPS 代理服务器，支持带认证的代理。

**选项：**

- `--enable` - 启用代理
- `--disable` - 禁用代理
- `--remove` - 移除代理配置
- `--insecure` - 跳过 SSL 证书验证
- `--secure` - 启用 SSL 证书验证（默认）

**代理地址格式：**

- 无认证：`http://host:port`
- 有认证：`http://username:password@host:port`

**特殊字符编码：**

密码中的特殊字符需要 URL 编码：

| 字符 | 编码 |
| ---- | ---- |
| @    | %40  |
| :    | %3A  |
| /    | %2F  |
| ?    | %3F  |
| #    | %23  |
| %    | %25  |

**示例：**

```bash
# 设置代理（无认证）
matrix config set proxy http://proxy.com:8080

# 设置代理（有认证）
matrix config set proxy http://user:password@proxy.com:8080

# 密码包含特殊字符（P@ssword -> P%40ssword）
matrix config set proxy http://user:P%40ssword@proxy.com:8080

# 启用/禁用代理
matrix config set proxy --enable
matrix config set proxy --disable

# 移除代理配置
matrix config set proxy --remove

# SSL 证书验证控制
matrix config set proxy --insecure  # 跳过验证（不安全）
matrix config set proxy --secure    # 启用验证
```

#### 列出配置

```bash
matrix config list
```

列出所有当前配置，包括：

- 代理地址和状态
- SSL 验证状态
- 工作目录
- 技能目录
- 认证状态

### 技能管理命令

#### 搜索技能

```bash
matrix skill search [options] <query...>
```

根据关键字搜索技能，默认显示前 10 条结果。

**选项：**

- `--category-id <id>` - 按分类ID筛选
- `--tag-ids <ids>` - 按标签ID筛选（逗号分隔）
- `-t, --tag <tag>` - 通过标签英文名称搜索技能
- `--format <format>` - 输出格式（json|table），默认为 table
- `--output <file>` - 将结果保存到 JSON 文件
- `--page-size <number>` - 返回结果数量，默认 10

**示例：**

```bash
matrix skill search http
matrix skill search --tag tagEnName
matrix skill search --tag tagEnName api
matrix skill search http --format json
matrix skill search http --page-size 50
matrix skill search http --output results.json
matrix skill search http --format json --output results.json --page-size 100
```

#### 安装技能

```bash
matrix skill install [options] <slugs...>
```

将技能安装到指定目录。

**安装路径规则：**

| 参数组合                         | 安装路径                    |
| -------------------------------- | --------------------------- |
| 无参数                           | `<当前目录>/skills/<slug>`  |
| `--workdir <dir>`                | `<workdir>/<slug>`          |
| `--workdir <dir> --dir <subdir>` | `<workdir>/<subdir>/<slug>` |

**选项：**

- `-f, --force` - 强制覆盖已安装的技能
- `-t, --tag <tag>` - 通过标签批量安装技能

**示例：**

```bash
# 安装单个技能（默认安装到 ./skills/skill-creator）
matrix skill install skill-creator

# 安装到指定目录（安装到 ./my-project/skill-creator）
matrix --workdir ./my-project skill install skill-creator

# 安装到指定子目录（安装到 ./my-project/skills/skill-creator）
matrix --workdir ./my-project --dir skills skill install skill-creator

# 批量安装多个技能（逗号分隔）
matrix skill install skill-creator,file-search,context-fundamentals --force

# 通过标签批量安装（安装该标签下的所有技能）
matrix skill install --tag openharmony --force

# 通过标签批量安装指定技能（只安装该标签下的指定技能）
matrix skill install --tag anthropics skill-creator,file-search

# 强制安装
matrix skill install --force skill-creator
```

#### 更新技能

```bash
matrix skill update [options] [slugs...]
```

更新已安装的技能。如果不指定技能名称，则更新所有已安装的技能。

**选项：**

- `-f, --force` - 强制更新所有安装路径
- `-t, --tag <tag>` - 通过标签批量更新技能

**示例：**

```bash
# 更新单个技能
matrix skill update skill-creator

# 批量更新多个技能（逗号分隔）
matrix skill update skill-creator,file-search --force

# 通过标签批量更新
matrix skill update --tag openharmony --force

# 更新所有已安装技能
matrix skill update --force
```

#### 卸载技能

```bash
matrix skill uninstall [options] <slugs...>
```

从本地卸载技能。

**选项：**

- `-f, --force` - 强制卸载所有安装路径
- `-a, --all` - 卸载所有已安装的技能

**示例：**

```bash
# 卸载单个技能
matrix skill uninstall skill-creator

# 批量卸载多个技能（逗号分隔）
matrix skill uninstall skill-creator,file-search --force

# 强制卸载
matrix skill uninstall --force skill-creator

# 卸载所有已安装的技能（会提示确认）
matrix skill uninstall --all

# 强制卸载所有已安装的技能（不提示确认）
matrix skill uninstall -f --all
```

#### 列出已安装技能

```bash
matrix skill list
```

列出当前已安装的所有技能及其版本信息、安装路径和安装时间。

#### 检查Matrix平台指定技能详情

```bash
matrix skill inspect [options] <enName>
```

获取技能元数据和文件而不安装。

**选项：**

- `--format <format>` - 输出格式（json|table），默认为 table

**示例：**

```bash
matrix skill inspect skill-creator
matrix skill inspect --format json skill-creator
```

**显示信息：**

- ID
- 名称
- 英文名称
- 描述
- 仓库
- 下载量
- 访问量
- 标签

#### 发布技能

```bash
matrix skill publish [options] <path>
```

从文件夹发布技能到 Matrix 技能市场。支持批量发布多个技能。

**示例：**

```bash
# 发布单个技能（指定包含SKILL.md的目录）
matrix skill publish ./my-skill

# 发布技能到指定目录
matrix skill publish ./skills/my-skill

# 批量发布多个技能（指定包含多个技能目录的父目录）
matrix skill publish ./skills-directory
```

**说明：**

- 如果指定目录包含 `SKILL.md` 文件，则发布该技能
- 如果指定目录不包含 `SKILL.md`，则递归查找所有子目录中的 `SKILL.md` 文件
- 支持批量发布多个技能，其中一个失败会打印错误日志并继续下一个
- 发布完成后显示成功和失败的统计信息
- 发布需要登录认证，使用 `matrix login` 命令登录

## 配置文件

Matrix CLI 将配置信息存储在 `~/.matrix/config.json` 文件中，包括：

- `token` - 认证令牌或私有令牌
- `authType` - 认证类型（token 或 secret）
- `clientCode` - 浏览器登录时生成的 client-code
- `workdir` - 工作目录
- `skillsDir` - 技能目录
- `installedSkills` - 已安装技能列表
- `proxy` - 代理配置
  - `url` - 代理地址（加密存储）
  - `enabled` - 是否启用代理
  - `strictSsl` - 是否严格验证 SSL 证书

## 技能目录

安装的技能存储路径取决于参数：

| 参数                             | 存储路径                          |
| -------------------------------- | --------------------------------- |
| 无参数                           | `<当前目录>/skills/<skill-name>`  |
| `--workdir <dir>`                | `<workdir>/<skill-name>`          |
| `--workdir <dir> --dir <subdir>` | `<workdir>/<subdir>/<skill-name>` |

## 多路径管理

Matrix CLI 支持同一技能在多个路径中安装：

```bash
# 安装到指定目录（不加 skills 子目录）
matrix --workdir /projects/project-a skill install skill-creator
# 安装路径: /projects/project-a/skill-creator

# 安装到指定目录的子目录
matrix --workdir /projects/project-b --dir skills skill install skill-creator
  # 安装路径: /projects/project-b/skills/skill-creator

# 查看所有安装
matrix skill list

# 更新特定路径的技能
matrix --workdir /projects/project-a skill update skill-creator

# 强制更新所有路径的技能
matrix skill update --force skill-creator
```

## 代理功能

### 基本使用

Matrix CLI 支持通过代理服务器访问 Matrix 平台：

```bash
# 设置代理
matrix config set proxy http://proxy.example.com:8080

# 查看配置
matrix config list

# 禁用代理（保留配置）
matrix config set proxy --disable

# 重新启用代理
matrix config set proxy --enable

# 移除代理配置
matrix config set proxy --remove
```

### 认证代理

对于需要认证的代理服务器：

```bash
# 格式：http://username:password@host:port
matrix config set proxy http://user:pass@proxy.example.com:8080
```

**重要：** 密码中的特殊字符需要 URL 编码：

```bash
# 密码：P@ss:word
# 编码后：P%40ss%3Aword
matrix config set proxy http://user:P%40ss%3Aword@proxy.example.com:8080
```

### SSL 证书验证

代理模式下的 SSL 验证行为：

- **默认行为**：启用严格 SSL 验证（推荐）
- **企业代理**：某些企业代理可能需要跳过验证

```bash
# 跳过 SSL 验证（不安全，仅用于测试或企业代理）
matrix config set proxy --insecure

# 恢复严格验证
matrix config set proxy --secure
```

### NO_PROXY 环境变量

支持通过 `NO_PROXY` 或 `no_proxy` 环境变量排除特定域名：

```bash
# 排除特定域名
export NO_PROXY=localhost,127.0.0.1,.internal.example.com

# 排除所有域名（禁用代理）
export NO_PROXY=*
```

**匹配规则：**

- `localhost` - 精确匹配
- `.example.com` - 匹配 sub.example.com
- `*.example.com` - 匹配 sub.example.com
- `*` - 匹配所有（禁用代理）

### 安全性说明

- 代理配置使用 AES-256-GCM 加密存储
- 加密密钥基于机器特征（MAC 地址 + 主机名 + 用户名）生成
- 配置文件在不同机器间不可移植
- 认证信息会被自动加密

## 认证机制

### Token 认证

- 请求头：`Cookie='token=${token}'`
- 用于：浏览器登录获取的令牌

### Secret 认证

- 请求头：`x-auth-secret='${secret}'`
- 用于：手动输入的私有令牌
- 用于：`matrix whoami` 和 `matrix skill publish`

## 批量操作

### 批量安装

```bash
# 安装多个技能
matrix skill install skill-creator,file-search,context-fundamentals --force

# 按标签安装
matrix skill install --tag openharmony --force
```

### 批量更新

```bash
# 更新多个技能
matrix skill update skill-creator,file-search --force

# 按标签更新
matrix skill update --tag openharmony --force

# 更新所有技能
matrix skill update --force
```

### 批量卸载

```bash
# 卸载多个技能
matrix skill uninstall skill-creator,file-search --force

# 卸载所有已安装的技能
matrix skill uninstall --all

# 强制卸载所有已安装的技能
matrix skill uninstall -f --all
```

## 开发

### 安装依赖

```bash
npm install
```

### 构建

```bash
npm run build
```

### 开发模式

```bash
npm run dev
```

### 测试

```bash
npm test
```

### 代码检查

```bash
npm run lint
npm run format
```

## 故障排除

### 登录失败

- 确保令牌正确且有效
- 检查网络连接
- 尝试使用 `matrix whoami` 验证令牌

### 安装失败

- 检查是否有足够的磁盘空间
- 确保有目标目录的写入权限
- 查看错误信息以获取更多详情

### 搜索无结果

- 尝试使用不同的关键词
- 检查网络连接
- 确认技能是否存在于市场中

### 认证问题

- Token 认证：确保使用浏览器登录获取的 token
- Secret 认证：确保从 Matrix 平台获取的私有令牌
- 检查令牌是否过期或失效

## 安全性

- Client-code 随机生成（UUID）
- 令牌安全存储在用户目录
- 支持两种认证方式
- 自动清理临时认证信息
- 请求头正确处理不同认证类型

## 贡献

欢迎贡献！请提交 Pull Request 或创建 Issue。

## 许可证

MIT

## 支持

如有问题或建议，请访问 [Matrix 官网](https://matrix.openharmony.cn/)登录，然后在[个人中心](https://matrix.openharmony.cn/#/profile/feedbacks/add)，提出您宝贵的意见。
