needware-cli

v1.5.15

Published

4 days ago

一个功能强大的 Node.js 命令行工具

0High
0Medium
0Low

sparrow666

cli command-line nodejs typescript sdk

Needware CLI

一个功能强大的 Node.js 命令行工具

✨ 特性

🚀 模块化命令架构 - 易于扩展和维护
🤖 AI 智能助手 - 集成 Claude Agent SDK，支持多种 prompt 格式 ⭐ 增强
- 文本字符串、文件路径、JSON 对象/数组
- 多模态消息支持（文本 + 图片） 🆕
- 消息历史和会话管理
- 交互式多轮对话
🔌 第三方 SDK 集成 - 灵活的 SDK 管理系统
⚙️ 灵活的配置管理 - 支持多层配置（默认、用户、环境变量）
🎨 美观的命令行界面 - 彩色输出和交互式提示
📝 完善的日志系统 - 多级日志和文件持久化
✅ 完整的错误处理 - 友好的错误提示和解决建议
🧪 单元测试覆盖 - 高质量代码保证

📦 安装

一键安装（推荐）

使用以下命令快速安装：

curl -fsSL https://raw.githubusercontent.com/needware/needware-cli/main/install.sh | sh

或使用 wget：

wget -qO- https://raw.githubusercontent.com/needware/needware-cli/main/install.sh | sh

安装脚本会自动：

✓ 检查系统要求（Node.js >= 18.0.0）
✓ 提供安装方式选择（npm 或源码）
✓ 自动构建和配置
✓ 可选初始化配置

全局安装

npm install -g needware-cli

项目本地安装

npm install --save-dev needware-cli

使用 npx

npx needware-cli <command>

查看完整安装指南了解更多安装方式和故障排查。

🚀 快速开始

1. 初始化配置

# 交互式初始化
needware-cli init

# 使用默认配置
needware-cli init --default

2. 配置管理

# 查看所有配置
needware-cli config list

# 获取配置项
needware-cli config get logging.level

# 设置配置项
needware-cli config set logging.level debug

# 设置 API Key
needware-cli config set sdks.example.apiKey YOUR_API_KEY

# 重置配置
needware-cli config reset

# 查看配置文件路径
needware-cli config path

3. 使用 Agent 命令（AI 智能助手）

# 配置 API Key（必需）
export ANTHROPIC_API_KEY=your_api_key_here

# 1. 简单文本 prompt（最常用）
needware-cli agent "创建一个待办事项应用"

# 2. 从文件读取 prompt
needware-cli agent ./requirements.txt
needware-cli agent ./prompts/feature.md

# 3. 使用 JSON 格式的消息
needware-cli agent '{"role":"user","content":"修复登录页面"}'

# 4. 使用消息历史（多轮对话上下文）
needware-cli agent ./conversation.json

# 5. 使用带元数据的 JSON（包含 sessionId）
needware-cli agent '{"prompt":"添加功能","sessionId":"my-session"}'

# 单次对话 - 指定工作目录
needware-cli agent "修复登录页面的样式问题" --working-dir ./my-project

# 多轮对话 - 交互式模式（推荐用于复杂任务）
needware-cli agent --interactive
# 或使用简写
needware-cli agent -i

# 多轮对话 - 带初始提示
needware-cli agent -i "创建一个待办事项应用"

# 指定额外目录
needware-cli agent "优化性能" --additional-dirs ./shared,./utils

# 使用数据库配置（如 Supabase）🆕
needware-cli agent "创建待办事项" --db-config '{"hasSelectedProject":true,"projectId":"your-project-id","publishableKey":"your-key","url":"https://your-project.supabase.co"}'

# 从文件读取数据库配置
needware-cli agent "创建待办事项" --db-config "$(cat db-config.json)"

Prompt 输入格式（自动识别） ⭐ 新增：

📝 文本字符串 - 直接提供文本: "创建组件"
📄 文件路径 - 从文件读取 (.txt, .md, .json): ./prompt.txt
🔤 JSON 对象 - 单个消息: '{"role":"user","content":"..."}'
📚 JSON 数组 - 消息历史: '[{"role":"user",...}]'
🔧 带元数据 - 包含配置: '{"prompt":"...","sessionId":"..."}'
🖼️ 多模态消息 - 文本 + 图片: '{"user":{"content":[{"type":"text",...},{"type":"image",...}]}}' 🆕
💡 智能检测 - 无需额外参数，系统自动识别所有格式

多模态消息示例 🆕：

# 从图片生成代码
needware-cli agent '{
  "user": {
    "content": [
      {"type": "text", "text": "根据这张图片一比一还原应用"},
      {"type": "image", "source": {"type": "url", "media_type": "image/png", "url": "https://example.com/design.png"}}
    ]
  }
}' --api-key YOUR_API_KEY

# 从文件读取多模态消息
needware-cli agent examples/multimodal-message-example.json --api-key YOUR_API_KEY

图片转换功能 🆕： needware-cli 现在提供了强大的图片转换功能，支持本地文件和远程URL：

🔥 自动转换 - 使用 URL 图片时自动转换为 base64：

# 直接使用图片 URL，系统自动下载并转换为 base64
needware-cli agent '{
  "user": {
    "content": [
      {"type": "text", "text": "分析这张图片"},
      {"type": "image", "source": {"type": "url", "url": "https://example.com/photo.jpg"}}
    ]
  }
}'

📦 手动转换 API：

import {
  convertImageToBase64,           // 转换本地图片
  convertRemoteImageToBase64,     // 转换远程URL图片
  convertImageToBase64Smart,      // 智能检测并转换
  isImageFile
} from 'needware-cli/utils/prompt-parser';

// 转换本地图片
const local = await convertImageToBase64('./photo.jpg');

// 转换远程图片
const remote = await convertRemoteImageToBase64('https://example.com/photo.jpg');

// 智能转换（自动检测本地或远程）
const smart = await convertImageToBase64Smart('./photo.jpg');
// 或
const smart2 = await convertImageToBase64Smart('https://example.com/photo.jpg');

// 返回格式：
// {
//   "type": "image",
//   "source": {
//     "type": "base64",
//     "media_type": "image/jpeg",
//     "data": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
//   }
// }

支持的图片格式：JPEG, PNG, GIF, WebP
支持的图片源：本地文件、远程URL（HTTP/HTTPS）

详细文档：

交互式模式特性：

🔄 支持多轮对话，AI 记住上下文
💬 可以持续调整需求和代码
🚪 输入 exit 或 quit 退出对话

查看文档：

4. 使用示例命令

# 获取数据
needware-cli example fetch 123

# 创建数据
needware-cli example create '{"name":"test"}'

# 健康检查
needware-cli example health

📚 命令列表

| 命令 | 别名 | 描述 | 示例 | |------|------|------|------| | init | i | 初始化项目配置 | needware-cli init | | config | cfg | 配置管理 | needware-cli config list | | agent | ag | AI 智能助手 | needware-cli agent "创建应用" | | example | ex | 示例命令 | needware-cli example health |

🔧 全局选项

| 选项 | 简写 | 描述 | 默认值 | |------|------|------|--------| | --verbose | -V | 详细输出模式 | false | | --quiet | -q | 静默模式 | false | | --config <path> | -c | 指定配置文件路径 | ~/.needware/config.json | | --version | -v | 显示版本信息 | - | | --help | -h | 显示帮助信息 | - |

⚙️ 配置

配置文件位置

默认配置文件位于 ~/.needware/config.json

配置结构

{
  "version": "1.0.0",
  "logging": {
    "level": "info",
    "file": "~/.needware/logs/cli.log"
  },
  "sdks": {
    "example": {
      "apiKey": "",
      "endpoint": "https://api.example.com",
      "timeout": 30000,
      "retries": 3
    }
  },
  "preferences": {
    "colorOutput": true,
    "interactive": true
  }
}

环境变量

你可以使用环境变量覆盖配置：

# 日志级别
export NEEDWARE_LOG_LEVEL=debug

# API 配置
export NEEDWARE_API_KEY=your-api-key
export NEEDWARE_ENDPOINT=https://api.example.com

# Anthropic API 配置（Agent 命令需要）
export ANTHROPIC_API_KEY=your_anthropic_api_key
export ANTHROPIC_BASE_URL=https://api.anthropic.com  # 可选

# 偏好设置
export NEEDWARE_COLOR_OUTPUT=true
export NEEDWARE_INTERACTIVE=true

🛠️ 开发

环境要求

Node.js >= 18.0.0
npm >= 8.0.0

安装依赖

npm install

开发模式

npm run dev

构建项目

npm run build

运行测试

# 运行所有测试
npm test

# 单元测试
npm run test:unit

# 集成测试
npm run test:integration

# 覆盖率报告
npm run test:coverage

# 监听模式
npm run test:watch

代码检查

# 运行 ESLint
npm run lint

# 自动修复
npm run lint:fix

# 格式化代码
npm run format

📖 文档

快速开始

安装指南 - 完整的安装说明
快速开始 - 快速上手指南

Agent 命令（AI 智能助手）

Agent 命令指南 - AI 智能助手详细使用说明
Prompt 类型文档 - 多种 prompt 格式使用指南 ⭐ 新增
数据库配置指南 - 数据库配置使用说明 🆕
交互式模式文档 - 多轮对话功能详解

开发与架构

架构文档 - 详细的系统架构说明
API 文档 - API 使用说明
开发指南 - 开发环境配置和贡献指南
贡献指南 - 如何参与项目开发

故障排查

故障排查指南 - 常见问题和解决方案
容器环境配置 - Docker/Kubernetes 等容器环境使用指南
容器快速修复 - 容器权限问题快速解决方案 ⚡

示例

示例目录 - 各种使用示例
Prompt 示例 - 不同格式的 prompt 示例文件

🧪 测试

项目使用 Jest 进行测试，目标覆盖率为 80%。

npm test

🤝 贡献

欢迎贡献！请查看贡献指南。

提交规范

本项目遵循 Conventional Commits 规范：

feat: 新功能
fix: 修复问题
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建工具或辅助工具

📝 变更日志

查看 CHANGELOG.md 了解版本变更详情。

📄 许可证

🙏 致谢

感谢以下开源项目：

Commander.js - 命令行参数解析
Inquirer.js - 交互式命令行提示
Chalk - 终端颜色输出
Ora - 优雅的终端加载动画

📧 联系方式

问题反馈: GitHub Issues
邮箱: [email protected]

🔗 相关链接

Made with ❤️ by Needware Team