needware-cli 1.0.0

package/README.md

@@ -0,0 +1,310 @@
+# Needware CLI
+
+> 一个功能强大的 Node.js 命令行工具
+
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+## ✨ 特性
+
+- 🚀 **模块化命令架构** - 易于扩展和维护
+- 🔌 **第三方 SDK 集成** - 灵活的 SDK 管理系统
+- ⚙️ **灵活的配置管理** - 支持多层配置（默认、用户、环境变量）
+- 🎨 **美观的命令行界面** - 彩色输出和交互式提示
+- 📝 **完善的日志系统** - 多级日志和文件持久化
+- ✅ **完整的错误处理** - 友好的错误提示和解决建议
+- 🧪 **单元测试覆盖** - 高质量代码保证
+
+## 📦 安装
+
+### 全局安装
+
+```bash
+npm install -g needware-cli
+```
+
+### 项目本地安装
+
+```bash
+npm install --save-dev needware-cli
+```
+
+### 使用 npx
+
+```bash
+npx needware-cli <command>
+```
+
+## 🚀 快速开始
+
+### 1. 初始化配置
+
+```bash
+# 交互式初始化
+needware-cli init
+
+# 使用默认配置
+needware-cli init --default
+```
+
+### 2. 配置管理
+
+```bash
+# 查看所有配置
+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 智能助手）
+
+```bash
+# 配置 API Key（必需）
+export ANTHROPIC_API_KEY=your_api_key_here
+
+# 单次对话 - 在当前目录执行任务
+needware-cli agent "创建一个待办事项应用"
+
+# 单次对话 - 指定工作目录
+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
+```
+
+**交互式模式特性**：
+- 🔄 支持多轮对话，AI 记住上下文
+- 💬 可以持续调整需求和代码
+- 🚪 输入 `exit` 或 `quit` 退出对话
+
+查看 [交互式模式详细文档](docs/INTERACTIVE_MODE.md)
+
+### 4. 使用示例命令
+
+```bash
+# 获取数据
+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`
+
+### 配置结构
+
+```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
+  }
+}
+```
+
+### 环境变量
+
+你可以使用环境变量覆盖配置：
+
+```bash
+# 日志级别
+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
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+### 构建项目
+
+```bash
+npm run build
+```
+
+### 运行测试
+
+```bash
+# 运行所有测试
+npm test
+
+# 单元测试
+npm run test:unit
+
+# 集成测试
+npm run test:integration
+
+# 覆盖率报告
+npm run test:coverage
+
+# 监听模式
+npm run test:watch
+```
+
+### 代码检查
+
+```bash
+# 运行 ESLint
+npm run lint
+
+# 自动修复
+npm run lint:fix
+
+# 格式化代码
+npm run format
+```
+
+## 📖 文档
+
+- [架构文档](ARCHITECTURE.md) - 详细的系统架构说明
+- [API 文档](docs/API.md) - API 使用说明
+- [开发指南](docs/DEVELOPMENT.md) - 开发环境配置和贡献指南
+- [Agent 命令指南](docs/AGENT_COMMAND.md) - AI 智能助手详细使用说明
+- [交互式模式文档](docs/INTERACTIVE_MODE.md) - 多轮对话功能详解
+
+## 🧪 测试
+
+项目使用 Jest 进行测试，目标覆盖率为 80%。
+
+```bash
+npm test
+```
+
+## 🤝 贡献
+
+欢迎贡献！请查看 [贡献指南](CONTRIBUTING.md)。
+
+### 提交规范
+
+本项目遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+```
+feat: 新功能
+fix: 修复问题
+docs: 文档更新
+style: 代码格式调整
+refactor: 代码重构
+test: 测试相关
+chore: 构建工具或辅助工具
+```
+
+## 📝 变更日志
+
+查看 [CHANGELOG.md](CHANGELOG.md) 了解版本变更详情。
+
+## 📄 许可证
+
+[MIT](LICENSE) © Needware Team
+
+## 🙏 致谢
+
+感谢以下开源项目：
+
+- [Commander.js](https://github.com/tj/commander.js) - 命令行参数解析
+- [Inquirer.js](https://github.com/SBoudrias/Inquirer.js) - 交互式命令行提示
+- [Chalk](https://github.com/chalk/chalk) - 终端颜色输出
+- [Ora](https://github.com/sindresorhus/ora) - 优雅的终端加载动画
+
+## 📧 联系方式
+
+- 问题反馈: [GitHub Issues](https://github.com/needware/needware-cli/issues)
+- 邮箱: support@needware.com
+
+## 🔗 相关链接
+
+- [官方网站](https://needware.com)
+- [文档中心](https://docs.needware.com)
+- [GitHub](https://github.com/needware/needware-cli)
+- [npm](https://www.npmjs.com/package/needware-cli)
+
+---
+
+**Made with ❤️ by Needware Team**
+

package/SETUP.md

@@ -0,0 +1,315 @@
+# 项目设置说明
+
+## 🎉 项目已成功生成！
+
+根据架构文档，已为您创建了完整的 Needware CLI 项目代码。
+
+## 📋 项目结构
+
+```
+needware-code/
+├── bin/                    # CLI 可执行文件
+├── src/                    # TypeScript 源代码
+│   ├── commands/          # 命令实现
+│   ├── core/              # 核心功能
+│   ├── sdk/               # SDK 集成层
+│   ├── utils/             # 工具函数
+│   └── types/             # 类型定义
+├── tests/                 # 测试文件
+├── config/                # 配置文件
+├── docs/                  # 文档
+└── dist/                  # 构建输出（需要构建后生成）
+```
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+这将安装所有必需的依赖包：
+- TypeScript 和相关工具
+- Commander.js (命令行框架)
+- Inquirer.js (交互式提示)
+- Chalk (彩色输出)
+- Ora (加载动画)
+- Axios (HTTP 客户端)
+- Jest (测试框架)
+- ESLint & Prettier (代码质量工具)
+
+### 2. 构建项目
+
+```bash
+npm run build
+```
+
+这将把 TypeScript 代码编译为 JavaScript，输出到 `dist/` 目录。
+
+### 3. 测试运行
+
+```bash
+# 开发模式（使用 ts-node）
+npm run dev
+
+# 或者链接到全局
+npm link
+needware-cli --help
+```
+
+## 📝 已实现的功能
+
+### ✅ 核心模块
+
+- **CLI 主类** (`src/core/cli.ts`)
+  - 命令注册和管理
+  - 全局选项处理
+  - 错误处理
+
+- **命令基类** (`src/core/command.ts`)
+  - 命令生命周期管理
+  - 统一的接口规范
+  - 验证和错误处理
+
+- **日志系统** (`src/core/logger.ts`)
+  - 多级日志（debug, info, warn, error, success）
+  - 彩色输出
+  - 文件持久化
+
+### ✅ 命令实现
+
+1. **init 命令** (`src/commands/init.ts`)
+   - 交互式配置初始化
+   - 默认配置生成
+   - 配置验证
+
+2. **config 命令** (`src/commands/config.ts`)
+   - 列出所有配置
+   - 获取/设置配置项
+   - 重置配置
+   - 查看配置文件路径
+
+3. **example 命令** (`src/commands/example.ts`)
+   - SDK 调用示例
+   - 数据获取和创建
+   - 健康检查
+
+### ✅ SDK 集成
+
+- **SDK 基类** (`src/sdk/base-sdk.ts`)
+  - 统一的 SDK 接口
+  - 生命周期管理
+  - 健康检查
+
+- **SDK 管理器** (`src/sdk/index.ts`)
+  - SDK 注册和获取
+  - 批量初始化
+  - 健康状态监控
+
+- **示例 SDK** (`src/sdk/example-sdk.ts`)
+  - HTTP 客户端集成
+  - 重试机制
+  - 错误处理
+
+### ✅ 工具函数
+
+- **配置管理** (`src/utils/config.ts`)
+  - 多层配置（默认、用户、环境变量）
+  - 配置读写和合并
+  - 路径解析
+
+- **输入验证** (`src/utils/validator.ts`)
+  - 邮箱、URL、端口验证
+  - 自定义验证器
+  - 类型检查
+
+- **文件操作** (`src/utils/file.ts`)
+  - 文件读写
+  - JSON 处理
+  - 目录管理
+
+### ✅ 类型定义
+
+完整的 TypeScript 类型定义 (`src/types/`)：
+- 命令相关类型
+- 配置相关类型
+- SDK 相关类型
+- 错误类型
+
+### ✅ 测试
+
+- 单元测试示例
+- 集成测试示例
+- Jest 配置
+- 测试覆盖率设置
+
+### ✅ 文档
+
+- `README.md` - 项目说明和使用指南
+- `ARCHITECTURE.md` - 架构设计文档
+- `CHANGELOG.md` - 版本变更记录
+- `CONTRIBUTING.md` - 贡献指南
+- `docs/API.md` - API 文档
+- `docs/DEVELOPMENT.md` - 开发指南
+- `QUICK_START.md` - 快速开始
+
+### ✅ 开发工具
+
+- TypeScript 配置
+- ESLint 配置
+- Prettier 配置
+- Jest 配置
+- Git 忽略文件
+- npm 发布配置
+
+## 🔧 开发命令
+
+```bash
+# 开发模式
+npm run dev
+
+# 构建
+npm run build
+
+# 测试
+npm test
+npm run test:watch
+npm run test:coverage
+
+# 代码检查
+npm run lint
+npm run lint:fix
+
+# 代码格式化
+npm run format
+```
+
+## 📚 使用示例
+
+### 初始化配置
+
+```bash
+# 交互式初始化
+needware-cli init
+
+# 使用默认配置
+needware-cli init --default
+```
+
+### 配置管理
+
+```bash
+# 查看所有配置
+needware-cli config list
+
+# 设置配置
+needware-cli config set sdks.example.apiKey YOUR_KEY
+
+# 获取配置
+needware-cli config get logging.level
+```
+
+### SDK 调用示例
+
+```bash
+# 健康检查
+needware-cli example health
+
+# 获取数据
+needware-cli example fetch 123
+
+# 创建数据
+needware-cli example create '{"name":"test"}'
+```
+
+## 🔍 关键文件说明
+
+| 文件 | 说明 |
+|------|------|
+| `package.json` | 项目配置和依赖 |
+| `tsconfig.json` | TypeScript 配置 |
+| `jest.config.js` | Jest 测试配置 |
+| `.eslintrc.json` | ESLint 代码检查配置 |
+| `.prettierrc` | Prettier 格式化配置 |
+| `src/index.ts` | 主入口文件 |
+| `bin/cli.js` | CLI 可执行文件 |
+| `config/default.json` | 默认配置 |
+
+## 🎯 下一步
+
+1. **安装依赖**
+   ```bash
+   npm install
+   ```
+
+2. **构建项目**
+   ```bash
+   npm run build
+   ```
+
+3. **初始化配置**
+   ```bash
+   npm link
+   needware-cli init
+   ```
+
+4. **开始开发**
+   - 添加自定义命令
+   - 集成更多 SDK
+   - 编写测试
+   - 完善文档
+
+## 📖 相关文档
+
+- [README.md](README.md) - 完整使用说明
+- [ARCHITECTURE.md](ARCHITECTURE.md) - 架构设计详解
+- [QUICK_START.md](QUICK_START.md) - 快速开始指南
+- [docs/API.md](docs/API.md) - API 参考文档
+- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) - 开发指南
+
+## ⚠️ 注意事项
+
+1. 需要 Node.js >= 18.0.0
+2. 首次运行前请先执行 `npm install`
+3. 开发时建议使用 `npm run dev` 而不是直接运行编译后的代码
+4. 修改代码后需要重新构建（`npm run build`）
+5. 测试前确保所有依赖已安装
+
+## 🐛 故障排除
+
+### 构建失败
+
+```bash
+rm -rf dist node_modules
+npm install
+npm run build
+```
+
+### TypeScript 错误
+
+```bash
+# 确保类型定义已安装
+npm install --save-dev @types/node @types/inquirer
+```
+
+### 链接问题
+
+```bash
+npm unlink -g needware-cli
+npm link
+```
+
+## 🎉 开始使用
+
+现在您可以开始使用和开发 Needware CLI 了！
+
+```bash
+npm install
+npm run build
+npm link
+needware-cli init
+```
+
+祝您使用愉快！ 🚀
+

package/bin/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * Needware CLI 可执行文件入口
+ */
+
+'use strict';
+
+// 检查 Node.js 版本
+const nodeVersion = process.versions.node;
+const majorVersion = parseInt(nodeVersion.split('.')[0], 10);
+
+if (majorVersion < 18) {
+  console.error(
+    '\x1b[31m%s\x1b[0m',
+    `Error: Needware CLI requires Node.js 18 or higher. Current version: ${nodeVersion}`
+  );
+  process.exit(1);
+}
+
+// 加载并运行主模块
+async function run() {
+  try {
+    // 尝试加载编译后的代码
+    const indexPath = require.resolve('../dist/index.js');
+    delete require.cache[indexPath];
+    require(indexPath);
+  } catch (error) {
+    // 如果 dist 不存在，尝试使用 ts-node 运行源代码（开发模式）
+    try {
+      require('ts-node/register');
+      require('../src/index.ts');
+    } catch (tsError) {
+      console.error('\x1b[31m%s\x1b[0m', 'Error: Failed to load CLI');
+      console.error(
+        '\x1b[33m%s\x1b[0m',
+        'Please run "npm run build" to build the project first, or install ts-node for development mode.'
+      );
+      console.error('\x1b[90m%s\x1b[0m', error.message);
+      process.exit(1);
+    }
+  }
+}
+
+run().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+

package/config/default.json

@@ -0,0 +1,20 @@
+{
+  "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
+  }
+}
+

package/dist/commands/agent.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Agent 命令 - 使用 Claude Agent SDK 执行智能任务
+ */
+import { Command } from '../core/command';
+import { CommandOptions, CommandResult } from '../types';
+import { Logger } from '../core/logger';
+export declare class AgentCommand extends Command {
+    readonly name = "agent";
+    readonly description = "Execute AI agent tasks using Claude Agent SDK";
+    readonly aliases: string[];
+    constructor(logger: Logger);
+    execute(options: CommandOptions): Promise<CommandResult>;
+    /**
+     * 运行 Agent 查询
+     */
+    private runAgent;
+    /**
+     * 运行交互式 Agent 查询（多轮对话）
+     */
+    private runInteractiveAgent;
+    /**
+     * 创建消息流生成器
+     */
+    private createMessageStream;
+    /**
+     * 处理 Agent 消息
+     */
+    private handleAgentMessage;
+    /**
+     * 获取系统提示词
+     */
+    private getSystemPrompt;
+    /**
+     * 显示帮助信息
+     */
+    private showHelp;
+}
+//# sourceMappingURL=agent.d.ts.map