deepminer-cli

v0.2.5

Published

23 days ago

DeepMiner CLI - Command-line tool for DM system with cross-platform support, JWT authentication, and workspace management

0High
0Medium
0Low

lsc-dm-cli

deepminer dm cli command-line authentication jwt api-client

DeepMiner CLI

DeepMiner 系统的命令行工具，用于管理认证、配置和 AI 会话。

功能特性

跨平台支持: macOS、Linux、Windows
AccessKey 鉴权: 通过 AccessKey 进行 API 认证
配置管理: API 端点和 AccessKey 配置
AI 会话: 启动/继续/停止 AI 助手会话，支持自定义消息、文件附件、会话追问和 claw_param 参数
会话结果: 获取会话的最终结果和状态
JSON 输出: 所有命令支持 --json 结构化输出，适合 AI agent 和脚本调用
错误提示: 错误响应包含 hint 字段，提供可操作的修复建议
CLI Schema: 内置 schema 命令输出机器可读的能力描述
zsh 自动补全: 安装后自动配置

快速安装

方式一：使用 npm（推荐）

npm install -g deepminer-cli
dm-cli version

方式二：从源码编译

cd dm-cli
go build -o dm-cli .

快速开始

# 1. 初始化配置
dm-cli config init --accesskey <your_access_key>

# 2. 启动 AI 会话（返回 agent_run_id、thread_id）
dm-cli thread start --message "你好"

# 3. 带文件附件发送
dm-cli thread start --message "请分析这个报告" --file ./report.ppt

# 4. 在已有会话中继续追问
dm-cli thread start --message "继续聊" --thread-id <thread_id>

# 5. 获取会话结果
dm-cli thread result --thread-id <thread_id>

# 6. 查看会话列表
dm-cli thread list

# 7. 查看会话文件列表
dm-cli thread file-list --thread-id <thread_id>

# 8. 停止正在运行的 Agent
dm-cli thread stop --thread-id <thread_id>

# 9. 查看用户打开的 agent
dm-cli agent user-open

# 10. 管理异步任务
dm-cli task info --thread-id <thread_id>
dm-cli task lifecycle --task-id <task_id> --thread-id <thread_id> --action start
dm-cli task files --task-id <task_id> --thread-id <thread_id>
dm-cli task download --task-id <task_id> --thread-id <thread_id> --output ./downloads

JSON 模式（适合 AI agent / 脚本）

所有命令加 --json 输出结构化 JSON：

dm-cli auth status --json
# {"ok": true, "data": {"auth_mode": "accesskey", "access_key": "..."}}

dm-cli thread start --message "分析" --file ./data.xlsx --json
# {"ok": true, "data": {"agent_run_id": "...", "thread_id": "...", ...}}

命令列表

配置

默认 API 地址：https://deepminer.com.cn，无需手动指定。如需连接其他环境，可通过 --endpoint 覆盖。

dm-cli config init --accesskey <key>                     # 初始化配置（使用默认 API 地址）
dm-cli config init --endpoint <url> --accesskey <key>    # 指定自定义 API 端点
dm-cli config init --poll-timeout 30                     # 设置轮询超时为 30 分钟（默认 60）
dm-cli config show                                       # 显示当前配置

认证

dm-cli auth status                                         # 显示鉴权状态

AI 会话

dm-cli thread start --message <消息>                                          # 发送文本消息
dm-cli thread start --message <消息> --file <路径>                            # 附带文件
dm-cli thread start --message <消息> --file <路径1> --file <路径2>            # 附带多个文件
dm-cli thread start --message <消息> --thread-id <会话ID>                     # 在已有会话中继续追问
dm-cli thread start --message <消息> --claw-param <JSON>                      # 附带渠道参数
dm-cli thread start --message <消息> --agent-mode <模式>                      # 指定 agent_mode（默认 auto）
dm-cli thread start --message <消息> --force                                  # 会话运行中强制发送新问题
dm-cli thread list                                                            # 获取所有会话列表
dm-cli thread list --name <关键词>                                            # 按项目名称搜索会话
dm-cli thread file-list --thread-id <会话ID>                                  # 获取会话的文件列表
dm-cli thread stop --thread-id <会话ID>                                       # 停止正在运行的 Agent
dm-cli agent user-open                                                        # 列出用户打开的 agent

异步任务

dm-cli task info --thread-id <会话ID>                                              # 查询会话下所有任务信息
dm-cli task info --thread-id <会话ID> --task-id <任务ID>                           # 查询指定任务信息
dm-cli task lifecycle --task-id <任务ID> --thread-id <会话ID> --action start       # 确认启动任务
dm-cli task lifecycle --task-id <任务ID> --thread-id <会话ID> --action interrupt    # 中断任务
dm-cli task lifecycle --task-id <任务ID> --thread-id <会话ID> --action resume       # 恢复任务
dm-cli task lifecycle --task-id <任务ID> --thread-id <会话ID> --action cancel       # 取消任务
dm-cli task files --task-id <任务ID> --thread-id <会话ID>                          # 列出任务产物文件
dm-cli task files --task-id <任务ID> --thread-id <会话ID> --page 2 --size 20       # 分页查询
dm-cli task download --task-id <任务ID> --thread-id <会话ID>                       # 下载产物文件到当前目录
dm-cli task download --task-id <任务ID> --thread-id <会话ID> --output ./downloads   # 下载到指定目录

文件附件说明

使用 --file 参数附带本地文件，CLI 会自动上传并拼接到消息中。可多次指定以附带多个文件。

文件大小限制：

| 类型 | 扩展名 | 最大大小 | |------|--------|----------| | 视频 | mp4 | 500 MB | | 音频 | mp3/wav/aac | 100 MB | | 其他 | * | 300 MB |

claw_param 参数说明

可选的 --claw-param 用于指定 DM 系统的渠道和发送者信息：

{
  "channel": "dmwork",
  "sender_account_id": "bot_account_id",
  "source_user_id": "user_id",
  "targets": [
    {
      "channel": "dmwork",
      "chat_type": "direct",
      "channel_id": "target_channel_id",
      "sender_bot_token": "bot_token"
    }
  ]
}

会话列表

dm-cli thread list                    # 获取所有会话列表
dm-cli thread list --name <关键词>    # 按项目名称搜索
dm-cli thread list --json             # JSON 格式输出

返回字段说明：

| 字段 | 类型 | 说明 | |------|------|------| | thread_id | string | 会话唯一标识 | | name | string | 项目名称 | | description | string | 项目描述 | | last_message_create_at | string | 最后一条消息的创建时间 (ISO 8601 格式) | | state | string | 会话状态，如 "completed", "ask_human", "failed" 等 | | metadata | object | 会话元数据（包含 agent_keys、agent_mode 等） | | detail_index | integer | 批量任务详情索引（仅批量任务模式） | | detail_status | string | 批量任务详情状态（仅批量任务模式） |

会话文件列表

dm-cli thread file-list --thread-id <会话ID>            # 获取会话的文件列表
dm-cli thread file-list --thread-id <会话ID> --json     # JSON 格式输出

返回字段说明：

| 字段 | 类型 | 说明 | |------|------|------| | file_id | string | 文件唯一标识 | | file_name | string | 文件名称 | | file_size | integer | 文件大小（字节） | | file_type | string | 文件类型 | | created_at | string | 文件创建时间 (ISO 8601 格式) | | url | string | 文件访问地址 |

会话结果

dm-cli thread result --thread-id <会话ID>                                              # 获取会话状态和结果

返回 state（会话状态）和 message_display_to_human（AI 回复内容）。轮询时 state 为 running 表示仍在处理，其他状态（如 ask_human）表示已完成。

Schema

dm-cli schema             # 输出 CLI Schema（压缩 JSON）
dm-cli schema --pretty    # 输出 CLI Schema（格式化 JSON）

Schema 命令输出 dm-cli 的完整能力描述，供 AI 系统或自动化工具解析。

其他

dm-cli version        # 显示版本号
dm-cli --help         # 显示帮助信息

全局 Flag

| Flag | 说明 | |------|------| | --json | 以 JSON 格式输出结果 | | --help | 显示帮助信息 |

JSON 输出格式

成功：

{"ok": true, "data": {...}}

错误（含修复建议）：

{"ok": false, "error": {"type": "auth", "message": "未配置 AccessKey", "hint": "运行 'dm-cli config init --accesskey <key>' 配置"}}

hint 字段提供可操作的修复建议，AI agent 可直接据此自动恢复。

文件说明

配置文件：`~/.dm-cli/config.json`

{
  "api_endpoint": "https://deepminer.com.cn",
  "access_key": "your_access_key",
  "poll_timeout": 60
}

自动更新

dm-cli 每次运行时会自动检查 npm 上的最新版本（每小时最多检查一次），如果发现新版本会自动执行 npm install -g deepminer-cli 更新。

关闭自动更新

在配置文件 ~/.dm-cli/config.json 中设置：

{
  "auto_update": false
}

也可以通过环境变量临时关闭：

export DM_CLI_NO_UPDATE=1

执行 version、--help 等命令时不会触发更新检查。

项目结构

dm-cli/
├── cmd/                    # 命令定义
│   ├── root.go            # 根命令
│   ├── auth/              # 鉴权状态命令
│   ├── config/            # 配置命令
│   ├── agent/             # AI 命令
│   ├── thread/            # 会话命令
│   ├── task/              # 异步任务命令
│   └── schema/            # Schema 输出命令
├── internal/
│   ├── client/            # HTTP 客户端
│   ├── config/            # 配置管理
│   ├── cmdutil/           # 命令工具
│   ├── fileutil/          # 文件上传共享逻辑
│   ├── output/            # 输出处理
│   └── validate/          # 输入验证
├── schema/                # CLI Schema 定义（嵌入）
├── skills/                # AI Agent Skill 定义
├── main.go                # 入口点
├── go.mod                 # 依赖定义
└── Makefile               # 构建脚本

开发

本地编译和测试

# 编译（版本号自动从 git tag 获取）
make build

# 指定版本号编译
make build VERSION=0.3.0

# 初始化配置
./dm-cli config init --accesskey <your_access_key>

# 查看鉴权状态
./dm-cli auth status

跨平台编译

make build-all
# 输出: bin/dm-cli-linux-amd64, bin/dm-cli-darwin-amd64, bin/dm-cli-darwin-arm64, bin/dm-cli-windows-amd64.exe

分支模型与发布流程

项目采用三分支模型，通过 GitLab CI/CD 自动构建和发布到 npm。

分支说明

| 分支 | 用途 | 触发动作 | |------|------|----------| | develop | 日常开发 | 无自动发布 | | test | 测试环境 | 合并后自动发布 beta 版本 | | prod | 生产环境 | 打 v* tag 后自动发布正式版本 |

发布流程

develop (日常开发)
    │
    ▼ merge
  test ──────► CI 自动发布 beta 版 (npm tag: beta)
    │
    ▼ merge
  prod ──────► 打 tag ──► CI 自动发布正式版 (npm tag: latest)

发布 Beta 版本（测试）

合并到 test 分支即可，CI 自动完成构建和发布：

git checkout test
git merge develop
git push

版本号自动生成：{最近tag版本}-beta.{pipeline编号}，如 0.2.0-beta.42
发布到 npm 的 beta dist-tag
测试人员安装：npm install -g deepminer-cli@beta

发布正式版本

合并到 prod 分支并打 tag：

git checkout prod
git merge test
git push
git tag v0.2.1
git push origin v0.2.1

版本号从 tag 提取：v0.2.1 → 0.2.1
发布到 npm 的 latest dist-tag
用户安装/更新：npm install -g deepminer-cli

版本号管理

唯一来源：Git Tag（如 v0.2.1）
构建时通过 LDFLAGS 注入到 Go 二进制
CI 自动同步到 package.json，无需手动维护
本地无 tag 时默认版本号为 dev

CI/CD 配置要求

GitLab CI/CD Variables 中添加 NPM_TOKEN（Settings → CI/CD → Variables，勾选 masked）
确保 test 和 prod 分支已创建
首次使用前打一个初始 tag：git tag v0.2.0 && git push origin v0.2.0

文档

npm 发布指南 - 项目维护者发布新版本
快速开始 - 用户快速上手
安装指南 - 详细安装说明

安全考虑

配置文件存储在 ~/.dm-cli/ 目录，权限为 0600
AccessKey 以明文存储在配置文件中，请确保文件权限安全

zsh 补全

安装后 zsh 补全会自动配置。尝试：

dm-cli <TAB>          # 显示所有命令
dm-cli auth <TAB>     # 显示 auth 子命令
dm-cli config <TAB>   # 显示 config 子命令
dm-cli agent <TAB>    # 显示 agent 子命令
dm-cli thread <TAB>   # 显示 thread 子命令
dm-cli task <TAB>     # 显示 task 子命令

许可证

MIT