WinNexO CLI

WinNexO CLI 是 WinNexO SaaS 平台的命令行界面工具，让您能够通过终端与 WinNexO AI 服务进行交互。

✨ 特性

• 💬 智能对话: 通过命令行与 WinNexO AI 进行自然语言对话
• 📖 帮助文档: 内置详细的使用说明和示例
• 🌐 联网搜索: 支持启用网络搜索增强 AI 响应
• 🎯 上下文管理: 通过对话 ID 维护多轮对话上下文
• 📊 业务对象绑定: 支持关联业务对象（customer, contact, scene 等）
• 🖱️ 交互式选择: REPL模式支持方向键导航选择对象类型和实例
• 🔍 对象类型查询: 列出所有可用的业务对象类型
• 🛠️ 技能管理: 查看指定对象类型的 AI 技能列表
• 📋 实例查询: 查看对象实例列表（支持分页）
• ⚡ 流式响应: 实时流式输出 AI 响应内容
• 🎨 彩色终端: 友好的彩色终端输出
• 🔧 灵活配置: 简单的 JSON 配置文件

📦 安装

前置要求

• Node.js >= 18.0.0
• npm >= 6.0.0

从源码安装

# 克隆仓库
git clone git@xxxxxxxxx/winnexo-cli.git
cd winnexo-cli

# 安装依赖
npm install

# 构建项目
npm run build

# 全局安装
npm link

⚙️ 配置

创建配置文件 ~/.winnexo/config.json:

{
  "apiEndpoint": "http://xx.xx.xx.xx:7001",
  "authToken": "your-auth-token-here"
}

配置字段说明

| 字段 | 类型 | 必需 | 说明 | |-----|------|------|------| | apiEndpoint | string | ✅ | WinNexO API 端点 URL | | authToken | string | ✅ | 认证令牌 |

🚀 快速开始

第一步：创建配置文件

mkdir -p ~/.winnexo
cat > ~/.winnexo/config.json << EOF
{
  "apiEndpoint": "http://xx.xx.xx.xx:7001",
  "authToken": "your_token_here"
}
EOF

第二步：查看可用对象类型

winnexo object-types

第三步：查看对象实例（获取 Object ID）

winnexo object-ids --object-type customer

第四步：开始对话

winnexo chat "你好，帮我分析一下" --object-type customer --object-id C12345

📝 命令列表

1. REPL 模式（交互式会话）

描述: 启动持久化的交互式对话会话

winnexo

全局选项:

winnexo \
  --conversation-id <id> \           # 会话ID
  --model <model> \                   # 模型名称（默认: qwen-plus-latest）
  --temperature <value> \             # 温度参数 0-1（默认: 0.7）
  --web-search                        # 启用联网搜索

REPL内置命令:

• /help - 显示可用命令
• /exit 或 /quit - 退出REPL
• /clear - 清空对话历史
• /status - 显示会话信息
• /object-types - 交互式选择业务对象类型（使用 ↑↓ 方向键导航）
• /object-ids - 交互式选择业务对象实例（需先设置对象类型）

基本示例:

# 基本 REPL 模式
winnexo

# 带参数的 REPL 模式
winnexo --model qwen-turbo --temperature 0.5 --web-search

REPL工作流程示例:

winnexo

# 1. 选择对象类型
> /object-types
Select an option (use ↑/↓ keys, press Enter to confirm):

> customer - 客户
  contact - 联系人
  scene - 场景

✓ 已设置对象类型: 客户

# 2. 选择对象实例
> /object-ids
Select an option (use ↑/↓ keys, press Enter to confirm):

> C12345 - 阿里巴巴集团
  C12346 - 腾讯科技
  C12347 - 字节跳动

✓ 已设置对象 ID: 阿里巴巴集团

# 3. 开始对话（自动使用已选择的对象）
> 帮我分析一下这个客户
[AI响应...]

2. help - 帮助文档

描述: 显示完整的帮助信息

winnexo help

3. chat - AI 对话命令 ⚠️

描述: 发送单条消息给 WinNexO AI 并获取响应

winnexo chat <message> --object-type <type> --object-id <id> [options]

必需参数 ⚠️:

• --object-type <type>: 业务对象类型（customer, contact, scene 等）【必填】
• --object-id <id>: 对象 ID 【必填】

可选参数:

• -p, --print: 打印模式（收集完整响应后一次性打印）
• --conversation-id <id>: 会话 ID（用于上下文关联）
• --web-search: 启用联网搜索
• --model <model>: 模型名称（默认: qwen-plus-latest）
• --temperature <value>: 温度 0-1（默认: 0.7）

输出模式:

1. 交互模式（默认）: 实时流式输出，AI 生成时即时显示
2. 打印模式（-p/--print）: 收集完整响应后一次性打印

示例:

# 基本对话（交互模式）
winnexo chat "你好" --object-type customer --object-id C12345

# 打印模式
winnexo chat "帮我分析一下" --object-type customer --object-id C12345 -p

# 带联网搜索
winnexo chat "最新的AI新闻" --object-type customer --object-id C12345 --web-search

# 带会话上下文
winnexo chat "继续上面的话题" \
  --object-type customer \
  --object-id C12345 \
  --conversation-id abc123

# 自定义模型和温度
winnexo chat "写一首诗" \
  --object-type customer \
  --object-id C12345 \
  --model qwen-turbo \
  --temperature 0.9

❌ 错误示例:

# 缺少 --object-type
winnexo chat "你好" --object-id C12345
# 输出: error: required option '--object-type <type>' not specified

# 缺少 --object-id
winnexo chat "你好" --object-type customer
# 输出: error: required option '--object-id <id>' not specified

# 两个都缺少
winnexo chat "你好"
# 输出: error: required option '--object-type <type>' not specified

4. object-types - 查看业务对象类型

描述: 列出所有可用的业务对象类型

winnexo object-types

输出: 以表格形式显示所有对象类型

| Code | Display Name | Object Type | Actions | |------|--------------|-------------|---------| | customer | 客户 | customer | view, edit, delete | | contact | 联系人 | contact | view, edit | | scene | 场景 | scene | view, execute |

示例:

winnexo object-types

5. skills - 查看技能列表

描述: 列出指定对象类型可用的 AI 技能

winnexo skills --object-type <type>

必需参数:

• --object-type <type>: 业务对象类型

输出: 以表格形式显示技能列表

| Code | Name | Status | Bound | |------|------|--------|-------| | skill_001 | 客户分析 | active | yes | | skill_002 | 需求预测 | active | no |

示例:

# 查看客户对象的技能
winnexo skills --object-type customer

# 查看联系人对象的技能
winnexo skills --object-type contact

6. object-ids - 查看对象实例列表

描述: 列出指定对象类型的实例，支持分页

winnexo object-ids --object-type <type> [options]

必需参数:

• --object-type <type>: 业务对象类型

可选参数:

• --page <num>: 页码（从 1 开始，默认: 1）
• --page-size <size>: 每页数量（1-100，默认: 20）

输出: 以表格形式显示对象实例列表（包含 Object ID）

示例:

# 查看第一页（默认20条）
winnexo object-ids --object-type customer

# 指定页码
winnexo object-ids --object-type customer --page 2

# 自定义每页数量
winnexo object-ids --object-type customer --page-size 50

# 查看第3页，每页10条
winnexo object-ids --object-type contact --page 3 --page-size 10

⚠️ 重要提示

1. chat 命令必须提供两个参数:

   • --object-type 和 --object-id 缺一不可
   • 不提供会报错: error: required option '--object-type <type>' not specified

2. 获取 Object ID 的方法:

   • 使用 winnexo object-ids --object-type <type> 命令查看

3. REPL 模式 vs chat 命令:

   • REPL 模式: 适合多轮对话，支持交互式选择对象（/object-types、/object-ids），无需每次输入
   • chat 命令: 适合单次对话或脚本调用，需要明确指定所有参数（--object-type、--object-id）

🔧 开发

项目结构

winnexo-cli/
├── src/
│   ├── api/          # API 客户端
│   ├── commands/     # 命令实现
│   ├── config/       # 配置管理
│   ├── errors/       # 错误类
│   ├── utils/        # 工具函数
│   └── index.ts      # CLI 入口
├── tests/
│   ├── unit/         # 单元测试
│   ├── integration/  # 集成测试
│   └── e2e/          # 端到端测试
└── specs/            # 功能规范

开发命令

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 运行测试
npm test

# 运行测试（监听模式）
npm run test:watch

# 测试覆盖率
npm run test:coverage

# 代码检查
npm run lint

# 代码格式化
npm run format

测试

项目采用 Test-Driven Development (TDD) 开发模式：

# 运行所有测试
npm test

# 运行单元测试
npm test -- tests/unit

# 运行集成测试
npm test -- tests/integration

# 运行 E2E 测试
npm test -- tests/e2e

# 生成覆盖率报告
npm run test:coverage

🐛 错误处理

CLI 使用标准的 Unix 退出码：

| 退出码 | 说明 | |-------|------| | 0 | 成功 | | 1 | 一般错误（API 错误、限流等） | | 2 | 无效参数 | | 3 | 认证错误 (401/403) | | 4 | 网络错误（连接失败、超时） |

📄 许可证

MIT

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

🙏 致谢

• Commander.js - CLI 框架
• chalk - 终端样式
• eventsource-parser - SSE 解析