npm package: @matrixopenharmony/matrix-cli
Description: Matrix CLI - 技能管理命令行工具
Author: matrixopenharmony
Latest version: 0.0.5

# Matrix CLI

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

## 安装指南

### 全局安装

```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 skill search [options] <query...>
```

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

**选项：**

- `--category-id <id>` - 按分类ID筛选
- `--tag-ids <ids>` - 按标签ID筛选（逗号分隔）
- `-t, --tag <tag> ` - 通过标签英文名称搜索技能

**示例：**

```bash
matrix skill search http
matrix skill search --tag tagEnName
matrix skill search --tag tagEnName api
```

#### 安装技能

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

将技能安装到 `<workdir>/<dir>/<slug>` 目录。

**选项：**

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

**示例：**

```bash
# 安装单个技能
matrix 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-directory
```

**说明：**

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

## 配置文件

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

- `token` - 认证令牌或私有令牌
- `authType` - 认证类型（token 或 secret）
- `clientCode` - 浏览器登录时生成的 client-code
- `workdir` - 工作目录
- `skillsDir` - 技能目录
- `installedSkills` - 已安装技能列表

## 技能目录

安装的技能默认存储在 `<workdir>/skills/<skill-name>` 目录下。

## 多路径管理

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

```bash
# 在不同项目中安装同一技能
matrix --workdir /projects/project-a skill install skill-creator
matrix --workdir /projects/project-b skill install skill-creator

# 查看所有安装
matrix skill list

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

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

## 认证机制

### 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)，提出您宝贵的意见。