deepminer-cli 0.1.23 → 0.1.25

package/README.md

@@ -4,15 +4,19 @@ DeepMiner 系统的命令行工具，用于管理认证、配置和 AI 会话。
 
 ## 功能特性
 
-- ✅ **跨平台支持**: macOS、Linux、Windows
-- ✅ **用户认证**: 用户名/密码登录，支持 JWT Token
-- ✅ **自动 Token 管理**: Token 过期时自动刷新（本地 JWT 解析，无需 API 调用）
-- ✅ **空间管理**: 选择和切换工作空间
-- ✅ **配置管理**: 简单的 API 端点配置
-- ✅ **安全存储**: Token 以受限权限存储在本地
-- ✅ **zsh 自动补全**: 自动配置 zsh tab 补全
-- ✅ **文件上传**: 支持上传文件到 OSS，带文件大小验证
-- ✅ **AI 会话**: 启动 AI 助手会话，支持自定义消息和 claw_param 参数
+- **跨平台支持**: macOS、Linux、Windows
+- **用户认证**: 用户名/密码登录，支持 JWT Token
+- **自动 Token 管理**: Token 过期时自动刷新（本地 JWT 解析，无需 API 调用）
+- **空间管理**: 查看和切换工作空间
+- **配置管理**: API 端点配置
+- **安全存储**: Token 以受限权限存储在本地
+- **文件上传**: 上传文件到 OSS，带文件大小验证
+- **AI 会话**: 启动 AI 助手会话，支持自定义消息和 claw_param 参数
+- **JSON 输出**: 所有命令支持 `--json` 结构化输出，适合 AI agent 和脚本调用
+- **错误提示**: 错误响应包含 `hint` 字段，提供可操作的修复建议
+- **Dry Run**: `--dry-run` 预览 HTTP 请求而不实际执行
+- **CLI Schema**: 内置 `schema` 命令输出机器可读的能力描述
+- **zsh 自动补全**: 安装后自动配置
 
 ## 快速安装
 
@@ -23,11 +27,6 @@ npm install -g deepminer-cli
 dm-cli version
 ```
 
-验证安装：
-```bash
-dm-cli --help
-```
-
 ### 方式二：从源码编译
 
 ```bash
@@ -40,25 +39,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. 启动 AI 会话
+# 5. 启动 AI 会话
 dm-cli agent start-thread --message "你好"
 
-# 5. 切换空间
-dm-cli auth switch <space_id>
+# 6. 上传文件
+dm-cli file upload --file document.pdf
 
-# 6. 登出
+# 7. 登出
 dm-cli auth logout
+```
 
-# 7. 查看版本
-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": "...", ...}}
 ```
 
 ## 命令列表
@@ -66,17 +77,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                                         # 退出登录
 ```
 
 ### 文件管理
@@ -84,67 +95,24 @@ 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**
-
-#### 上传示例
-
-```bash
-# 基本上传
-dm-cli file upload --file document.pdf
-
-# 自定义文件名
-dm-cli file upload --file video.mp4 --name my-video.mp4
-
-# 指定功能类型
-dm-cli file upload --file audio.mp3 --feature thread
-
-# 完整参数
-dm-cli file upload --file data.xlsx --feature thread --name data.xlsx --id my-file-id
-```
-
-#### 输出说明
-
-```
-✓ 文件上传成功
-文件名: document.pdf
-文件大小: 2.50 MB
-文件类型: pdf
-文件 ID: upload_1774952597926_9acCrbNh
-文件 Key: develop/dm-temp/.../thread/.../file.pdf
-上传 URL: https://...
-```
+| 类型 | 扩展名 | 最大大小 |
+|------|--------|----------|
+| 视频 | mp4 | 500 MB |
+| 音频 | mp3/wav/aac | 100 MB |
+| 其他 | * | 300 MB |
 
 ### AI 会话
 
 ```bash
-dm-cli agent start-thread                                    # 启动会话（使用默认消息 "你好"）
-dm-cli agent start-thread --message <消息>                   # 启动会话（自定义消息）
-dm-cli agent start-thread --claw-param <JSON>               # 启动会话（指定 claw_param）
-dm-cli agent start-thread --message <消息> --claw-param <JSON>  # 启动会话（完整参数）
-```
-
-#### 会话启动示例
-
-```bash
-# 使用默认消息
-dm-cli agent start-thread
-
-# 自定义消息
-dm-cli agent start-thread --message "分析一下这个数据"
-
-# 指定 claw_param（渠道和发送者信息）
-dm-cli agent start-thread --claw-param '{"channel":"dmwork","sender_account_id":"bot"}'
-
-# 完整参数
-dm-cli agent start-thread --message "你好" --claw-param '{"channel":"dmwork","targets":[...]}'
+dm-cli agent start-thread                                              # 使用默认消息 "你好"
+dm-cli agent start-thread --message <消息>                             # 自定义消息
+dm-cli agent start-thread --message <消息> --claw-param <JSON>         # 完整参数
 ```
 
 #### claw_param 参数说明
@@ -156,7 +124,6 @@ dm-cli agent start-thread --message "你好" --claw-param '{"channel":"dmwork","
   "channel": "dmwork",
   "sender_account_id": "bot_account_id",
   "source_user_id": "user_id",
-  "source_channel_id": "channel_id",
   "targets": [
     {
       "channel": "dmwork",
@@ -168,6 +135,15 @@ dm-cli agent start-thread --message "你好" --claw-param '{"channel":"dmwork","
 }
 ```
 
+### Schema
+
+```bash
+dm-cli schema             # 输出 CLI Schema（压缩 JSON）
+dm-cli schema --pretty    # 输出 CLI Schema（格式化 JSON）
+```
+
+Schema 命令输出 dm-cli 的完整能力描述，供 AI 系统或自动化工具解析。
+
 ### 其他
 
 ```bash
@@ -175,6 +151,51 @@ dm-cli version        # 显示版本号
 dm-cli --help         # 显示帮助信息
 ```
 
+## 全局 Flag
+
+| Flag | 说明 |
+|------|------|
+| `--json` | 以 JSON 格式输出结果 |
+| `--dry-run` | 预览 HTTP 请求而不实际执行 |
+| `--help` | 显示帮助信息 |
+
+### JSON 输出格式
+
+成功：
+```json
+{"ok": true, "data": {...}}
+```
+
+错误（含修复建议）：
+```json
+{"ok": false, "error": {"type": "auth", "message": "未登陆", "hint": "运行 'dm-cli auth login --username <user> --password <pass>' 登录"}}
+```
+
+`hint` 字段提供可操作的修复建议，AI agent 可直接据此自动恢复。
+
+### Dry Run 模式
+
+使用 `--dry-run` 预览请求而不实际执行，适合调试和 AI agent 安全验证：
+
+```bash
+dm-cli --dry-run auth login --username user --password pass
+# [DRY RUN] POST https://api.example.com/api/auth/authentication/login
+# Headers:
+#   Content-Type: application/json
+# Body:
+# {"username": "user", "password": "pass"}
+```
+
+JSON 模式：
+```bash
+dm-cli --dry-run --json agent start-thread --message "你好"
+```
+```json
+{"ok": true, "dry_run": true, "data": {"method": "POST", "url": "...", "headers": {...}, "body": {...}}}
+```
+
+只读命令（`config show`、`auth status`、`version`、`schema`）和纯本地操作（`config init`、`auth logout`）不受 `--dry-run` 影响，正常执行。
+
 ## 文件说明
 
 ### 配置文件：`~/.dm-cli/config.json`
@@ -200,8 +221,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 时自动尝试刷新并重试
@@ -215,7 +236,8 @@ dm-cli/
 │   ├── auth/              # 认证命令
 │   ├── config/            # 配置命令
 │   ├── agent/             # AI 命令
-│   └── file/              # 文件管理命令
+│   ├── file/              # 文件管理命令
+│   └── schema/            # Schema 输出命令
 ├── internal/
 │   ├── auth/              # 认证模块
 │   ├── client/            # HTTP 客户端
@@ -223,9 +245,11 @@ dm-cli/
 │   ├── cmdutil/           # 命令工具
 │   ├── output/            # 输出处理
 │   └── validate/          # 输入验证
+├── schema/                # CLI Schema 定义（嵌入）
+├── skills/                # AI Agent Skill 定义
 ├── main.go                # 入口点
 ├── go.mod                 # 依赖定义
-└── Makefile              # 构建脚本
+└── Makefile               # 构建脚本
 ```
 
 ## 开发
@@ -237,10 +261,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
@@ -256,11 +283,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 过期后需要重新登录
@@ -275,7 +303,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.23",
+  "version": "0.1.25",
   "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