deepminer-cli 0.1.22 → 0.1.24

package/README.md

@@ -4,14 +4,17 @@ DeepMiner 系统的命令行工具，用于管理认证、配置和 AI 会话。
 
 ## 功能特性
 
-- ✅ **跨平台支持**: macOS、Linux、Windows
-- ✅ **用户认证**: 用户名/密码登录，支持 JWT Token
-- ✅ **自动 Token 管理**: Token 过期时自动刷新（本地 JWT 解析，无需 API 调用）
-- ✅ **空间管理**: 选择和切换工作空间
-- ✅ **配置管理**: 简单的 API 端点配置
-- ✅ **安全存储**: Token 以受限权限存储在本地
-- ✅ **zsh 自动补全**: 自动配置 zsh tab 补全
-- ✅ **文件上传**: 支持上传文件到 OSS，带文件大小验证
+- **跨平台支持**: macOS、Linux、Windows
+- **用户认证**: 用户名/密码登录，支持 JWT Token
+- **自动 Token 管理**: Token 过期时自动刷新（本地 JWT 解析，无需 API 调用）
+- **空间管理**: 查看和切换工作空间
+- **配置管理**: API 端点配置
+- **安全存储**: Token 以受限权限存储在本地
+- **文件上传**: 上传文件到 OSS，带文件大小验证
+- **AI 会话**: 启动 AI 助手会话，支持自定义消息和 claw_param 参数
+- **JSON 输出**: 所有命令支持 `--json` 结构化输出，适合 AI agent 和脚本调用
+- **CLI Schema**: 内置 `schema` 命令输出机器可读的能力描述
+- **zsh 自动补全**: 安装后自动配置
 
 ## 快速安装
 
@@ -22,11 +25,6 @@ npm install -g deepminer-cli
 dm-cli version
 ```
 
-验证安装：
-```bash
-dm-cli --help
-```
-
 ### 方式二：从源码编译
 
 ```bash
@@ -39,22 +37,37 @@ go build -o dm-cli .
 
 ```bash
 # 1. 初始化配置
-dm-cli config init
+dm-cli config init --endpoint https://dm-dev.xmingai.com
+
+# 2. 登录（返回空间列表）
+dm-cli auth login --username user@example.com --password xxx
 
-# 2. 登录
-dm-cli auth login
+# 3. 选择空间
+dm-cli auth switch <space_id>
 
-# 3. 查看状态
+# 4. 查看状态
 dm-cli auth status
 
-# 4. 切换空间
-dm-cli auth switch
+# 5. 启动 AI 会话
+dm-cli agent start-thread --message "你好"
 
-# 5. 登出
+# 6. 上传文件
+dm-cli file upload --file document.pdf
+
+# 7. 登出
 dm-cli auth logout
+```
 
-# 6. 查看版本
-dm-cli version
+### JSON 模式（适合 AI agent / 脚本）
+
+所有命令加 `--json` 输出结构化 JSON：
+
+```bash
+dm-cli auth status --json
+# {"ok": true, "data": {"logged_in": true, "user_id": "...", "current_space": "...", ...}}
+
+dm-cli file upload --file data.xlsx --json
+# {"ok": true, "data": {"file_id": "...", "file_key": "...", ...}}
 ```
 
 ## 命令列表
@@ -62,17 +75,17 @@ dm-cli version
 ### 配置
 
 ```bash
-dm-cli config init    # 初始化配置（设置 API 端点）
-dm-cli config show    # 显示当前配置
+dm-cli config init --endpoint <url>   # 初始化配置（设置 API 端点）
+dm-cli config show                     # 显示当前配置
 ```
 
 ### 认证
 
 ```bash
-dm-cli auth login     # 登录到 DM 系统
-dm-cli auth logout    # 退出登录
-dm-cli auth status    # 显示登录状态
-dm-cli auth switch    # 切换工作空间
+dm-cli auth login --username <用户名> --password <密码>   # 登录（返回空间列表）
+dm-cli auth switch <space_id>                              # 切换工作空间
+dm-cli auth status                                         # 显示登录状态
+dm-cli auth logout                                         # 退出登录
 ```
 
 ### 文件管理
@@ -80,44 +93,55 @@ dm-cli auth switch    # 切换工作空间
 ```bash
 dm-cli file upload --file <路径>                        # 上传文件
 dm-cli file upload --file <路径> --name <文件名>        # 上传文件（自定义名称）
-dm-cli file upload --file <路径> --feature <类型>      # 上传文件（指定功能类型）
-dm-cli file upload --file <路径> --id <ID>             # 上传文件（指定文件 ID）
+dm-cli file upload --file <路径> --feature <类型>       # 上传文件（指定功能类型）
+dm-cli file upload --file <路径> --id <ID>              # 上传文件（指定文件 ID）
 ```
 
 #### 文件大小限制
 
-- 🎬 **视频文件** (mp4): 最大 **500 MB**
-- 🎵 **音频文件** (mp3/wav/aac): 最大 **100 MB**
-- 📄 **其他文件**: 最大 **300 MB**
+| 类型 | 扩展名 | 最大大小 |
+|------|--------|----------|
+| 视频 | mp4 | 500 MB |
+| 音频 | mp3/wav/aac | 100 MB |
+| 其他 | * | 300 MB |
 
-#### 上传示例
+### AI 会话
 
 ```bash
-# 基本上传
-dm-cli file upload --file document.pdf
+dm-cli agent start-thread                                              # 使用默认消息 "你好"
+dm-cli agent start-thread --message <消息>                             # 自定义消息
+dm-cli agent start-thread --message <消息> --claw-param <JSON>         # 完整参数
+```
 
-# 自定义文件名
-dm-cli file upload --file video.mp4 --name my-video.mp4
+#### claw_param 参数说明
 
-# 指定功能类型
-dm-cli file upload --file audio.mp3 --feature thread
+可选的 `--claw-param` 用于指定 DM 系统的渠道和发送者信息：
 
-# 完整参数
-dm-cli file upload --file data.xlsx --feature thread --name data.xlsx --id my-file-id
+```json
+{
+  "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"
+    }
+  ]
+}
 ```
 
-#### 输出说明
+### Schema
 
-```
-✓ 文件上传成功
-文件名: document.pdf
-文件大小: 2.50 MB
-文件类型: pdf
-文件 ID: upload_1774952597926_9acCrbNh
-文件 Key: develop/dm-temp/.../thread/.../file.pdf
-上传 URL: https://...
+```bash
+dm-cli schema             # 输出 CLI Schema（压缩 JSON）
+dm-cli schema --pretty    # 输出 CLI Schema（格式化 JSON）
 ```
 
+Schema 命令输出 dm-cli 的完整能力描述，供 AI 系统或自动化工具解析。
+
 ### 其他
 
 ```bash
@@ -125,6 +149,23 @@ dm-cli version        # 显示版本号
 dm-cli --help         # 显示帮助信息
 ```
 
+## 全局 Flag
+
+| Flag | 说明 |
+|------|------|
+| `--json` | 以 JSON 格式输出结果 |
+| `--help` | 显示帮助信息 |
+
+JSON 模式下成功输出格式：
+```json
+{"ok": true, "data": {...}}
+```
+
+JSON 模式下错误输出格式：
+```json
+{"ok": false, "error": {"type": "auth", "message": "未登陆"}}
+```
+
 ## 文件说明
 
 ### 配置文件：`~/.dm-cli/config.json`
@@ -150,8 +191,8 @@ dm-cli --help         # 显示帮助信息
 
 ## Token 管理工作原理
 
-1. **认证**: 用户输入凭证，获得 `access_token` (JWT) 和 `refresh_token`
-2. **空间选择**: 获取可用空间，用户选择一个
+1. **认证**: 使用 `--username`/`--password` 凭证获得 `access_token` (JWT) 和 `refresh_token`
+2. **空间选择**: 登录返回可用空间列表，使用 `auth switch` 选择
 3. **存储**: Token 和元数据保存在 `~/.dm-cli/token.json`
 4. **自动刷新**: API 调用前自动检查 Token 是否过期，过期则刷新
 5. **401 处理**: 服务器拒绝 Token 时自动尝试刷新并重试
@@ -165,7 +206,8 @@ dm-cli/
 │   ├── auth/              # 认证命令
 │   ├── config/            # 配置命令
 │   ├── agent/             # AI 命令
-│   └── file/              # 文件管理命令
+│   ├── file/              # 文件管理命令
+│   └── schema/            # Schema 输出命令
 ├── internal/
 │   ├── auth/              # 认证模块
 │   ├── client/            # HTTP 客户端
@@ -173,9 +215,11 @@ dm-cli/
 │   ├── cmdutil/           # 命令工具
 │   ├── output/            # 输出处理
 │   └── validate/          # 输入验证
+├── schema/                # CLI Schema 定义（嵌入）
+├── skills/                # AI Agent Skill 定义
 ├── main.go                # 入口点
 ├── go.mod                 # 依赖定义
-└── Makefile              # 构建脚本
+└── Makefile               # 构建脚本
 ```
 
 ## 开发
@@ -187,10 +231,13 @@ dm-cli/
 go build -o dm-cli .
 
 # 初始化配置
-./dm-cli config init
+./dm-cli config init --endpoint https://dm-dev.xmingai.com
 
 # 登录
-./dm-cli auth login
+./dm-cli auth login --username user@example.com --password xxx
+
+# 选择空间
+./dm-cli auth switch <space_id>
 
 # 查看状态
 ./dm-cli auth status
@@ -206,11 +253,12 @@ make build-all
 ## 文档
 
 - [npm 发布指南](./NPM_RELEASE.md) - 项目维护者发布新版本
+- [快速开始](./QUICK_START_FOR_USERS.md) - 用户快速上手
+- [安装指南](./INSTALL.md) - 详细安装说明
 
 ## 安全考虑
 
 - Token 存储在 `~/.dm-cli/` 目录，权限为 0600
-- 密码输入不显示在终端
 - JWT Token 本地解析，只读取 exp 声明（不验证签名）
 - Token 过期时自动刷新
 - Refresh Token 过期后需要重新登录
@@ -225,7 +273,6 @@ dm-cli auth <TAB>     # 显示 auth 子命令
 dm-cli config <TAB>   # 显示 config 子命令
 dm-cli agent <TAB>    # 显示 agent 子命令
 dm-cli file <TAB>     # 显示 file 子命令
-dm-cli file upload <TAB>  # 显示 upload 命令的标志
 ```
 
 ## 许可证

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepminer-cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "DeepMiner CLI - Command-line tool for DM system with cross-platform support, JWT authentication, and workspace management",
   "keywords": [
     "deepminer",

package/scripts/_dm-cli

@@ -18,6 +18,7 @@ _dm_cli() {
       'auth:用户认证'
       'agent:AI 助手相关命令'
       'file:文件管理'
+      'schema:输出 CLI Schema 定义'
       'version:显示版本号'
     )
     _describe 'command' commands