needware-cli 1.2.8 → 1.3.0

package/AGENT_COMMAND_SUMMARY.md

@@ -1,364 +0,0 @@
-# Agent 命令实现总结
-
-## 概述
-
-本次开发将 Next.js API 路由中的 Claude Agent SDK 集成代码封装成了 CLI 命令，使得可以通过命令行直接运行 AI Agent 任务。
-
-## 实现内容
-
-### 1. 核心文件
-
-#### 新增文件
-
-| 文件路径 | 说明 |
-|---------|------|
-| `src/commands/agent.ts` | Agent 命令实现（主要逻辑） |
-| `docs/AGENT_COMMAND.md` | Agent 命令详细使用文档 |
-| `docs/AGENT_QUICKSTART.md` | Agent 命令快速入门指南 |
-| `AGENT_COMMAND_SUMMARY.md` | 本文档，变更总结 |
-
-#### 修改文件
-
-| 文件路径 | 修改内容 |
-|---------|---------|
-| `src/commands/index.ts` | 导出 `AgentCommand` 类 |
-| `src/index.ts` | 导入并注册 `AgentCommand` |
-| `src/core/cli.ts` | 为 agent 命令添加参数和选项支持 |
-| `README.md` | 添加 agent 命令使用说明 |
-
-### 2. 编译输出
-
-编译后生成以下文件：
-- `dist/commands/agent.js` - 编译后的 JavaScript 代码
-- `dist/commands/agent.d.ts` - TypeScript 类型定义
-- `dist/commands/agent.js.map` - Source Map
-- `dist/commands/agent.d.ts.map` - 类型定义 Source Map
-
-## 功能特性
-
-### 1. 命令参数
-
-```bash
-needware-cli agent <prompt> [options]
-```
-
-- **必需参数**:
-  - `<prompt>`: AI 任务提示词
-
-- **可选选项**:
-  - `--working-dir <path>`: 指定工作目录（默认：当前目录）
-  - `--additional-dirs <paths>`: 指定额外目录（逗号分隔）
-  - `-V, --verbose`: 详细输出模式
-  - `-q, --quiet`: 静默模式
-
-### 2. 环境变量
-
-- `ANTHROPIC_API_KEY`: **必需** - Anthropic API 密钥
-- `ANTHROPIC_BASE_URL`: 可选 - 自定义 API 端点
-
-### 3. 核心功能
-
-1. **工作目录管理**
-   - 默认使用当前工作目录
-   - 支持通过 `--working-dir` 参数指定
-   - 自动解析为绝对路径
-
-2. **提示词增强**
-   - 自动在用户提示词前添加工作目录上下文
-   - 确保 Agent 在正确的目录中操作
-
-3. **流式输出**
-   - 实时显示 Agent 的执行过程
-   - 支持多种消息类型：
-     - `text`: 文本消息
-     - `tool_use`: 工具使用信息
-     - `tool_result`: 工具执行结果
-     - `thinking`: 思考过程
-     - `error`: 错误信息
-
-4. **系统提示词**
-   - 内置针对 React + Vite + TypeScript + Tailwind CSS 的系统提示
-   - 包含最佳实践和开发规范
-   - 支持中英文交互
-
-5. **错误处理**
-   - API Key 验证
-   - 工作目录验证
-   - 友好的错误提示
-
-## 技术实现
-
-### 1. 代码结构
-
-```typescript
-export class AgentCommand extends Command {
-  readonly name = 'agent';
-  readonly description = 'Execute AI agent tasks using Claude Agent SDK';
-  readonly aliases = ['ag'];
-
-  async execute(options: CommandOptions): Promise<CommandResult> {
-    // 参数解析和验证
-    // 环境变量获取
-    // 工作目录处理
-    // Agent 查询执行
-  }
-
-  private async runAgent(): Promise<CommandResult> {
-    // 提示词增强
-    // SDK 配置
-    // 流式输出处理
-  }
-
-  private handleAgentMessage(message: any): void {
-    // 消息类型处理
-    // 格式化输出
-  }
-
-  private getSystemPrompt(): string {
-    // 返回系统提示词
-  }
-}
-```
-
-### 2. 与 CLI 框架集成
-
-在 `src/core/cli.ts` 中为 agent 命令特殊处理：
-
-```typescript
-if (command.name === 'agent') {
-  commandInstance
-    .argument('<prompt>', 'The task prompt for the AI agent')
-    .option('--working-dir <path>', 'Specify the working directory')
-    .option('--additional-dirs <paths>', 'Specify additional directories (comma-separated)');
-}
-```
-
-### 3. SDK 配置
-
-```typescript
-query({
-  prompt: enhancedPrompt,
-  options: {
-    systemPrompt: this.getSystemPrompt(),
-    settingSources: ['project'],
-    model: 'claude-sonnet-4-5',
-    maxTurns: 30,
-    permissionMode: 'bypassPermissions',
-    cwd: resolvedWorkingDir,
-    additionalDirectories,
-    env: {
-      ANTHROPIC_API_KEY: apiKey,
-      ANTHROPIC_BASE_URL: baseUrl,
-      PATH: process.env.PATH,
-    },
-  },
-})
-```
-
-## 使用示例
-
-### 基本使用
-
-```bash
-# 配置 API Key
-export ANTHROPIC_API_KEY="your_key"
-
-# 在当前目录执行任务
-needware-cli agent "创建一个待办事项应用"
-
-# 指定工作目录
-needware-cli agent "修复样式问题" --working-dir ./my-project
-
-# 指定额外目录
-needware-cli agent "重构代码" --additional-dirs ./shared,./utils
-
-# 详细输出
-needware-cli agent "优化性能" -V
-```
-
-### 实际场景
-
-1. **代码生成**
-   ```bash
-   needware-cli agent "创建一个用户注册表单组件"
-   ```
-
-2. **代码审查**
-   ```bash
-   needware-cli agent "审查这个项目的代码质量"
-   ```
-
-3. **Bug 修复**
-   ```bash
-   needware-cli agent "修复登录表单验证问题"
-   ```
-
-4. **重构**
-   ```bash
-   needware-cli agent "重构 utils 目录，使用 TypeScript"
-   ```
-
-## 测试验证
-
-### 编译测试
-
-```bash
-npm run build
-# ✓ 编译成功，无错误
-```
-
-### 命令测试
-
-```bash
-node bin/cli.js agent --help
-# ✓ 正确显示帮助信息
-```
-
-### 输出示例
-
-```
-🤖 启动 Claude Agent...
-
-工作目录: /Users/user/project
-提示词: 创建应用
-
-✓ Agent 已启动
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-💭 思考中...
-🔧 使用工具: write_file
-✓ 工具执行成功
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-✓ Agent 执行完成
-```
-
-## 文档
-
-### 用户文档
-
-1. **README.md**
-   - 添加 Agent 命令基本说明
-   - 更新命令列表
-   - 添加环境变量说明
-
-2. **docs/AGENT_COMMAND.md**
-   - 完整的使用指南
-   - 参数说明
-   - 示例集合
-   - 故障排除
-   - 最佳实践
-
-3. **docs/AGENT_QUICKSTART.md**
-   - 5 分钟快速入门
-   - 常见场景示例
-   - 问题解决
-
-## 与原始代码的对比
-
-### 原始代码（Next.js API 路由）
-
-```typescript
-// 通过 HTTP POST 接收请求
-export async function POST(request: NextRequest) {
-  const { prompt, workingDirectory, additionalDirectories } = await request.json();
-  
-  // 流式返回 SSE 格式数据
-  return new Response(stream.readable, {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      ...
-    },
-  });
-}
-```
-
-### 新实现（CLI 命令）
-
-```typescript
-// 通过命令行参数接收
-needware-cli agent <prompt> --working-dir <path>
-
-// 直接输出到终端
-console.log(chalk.green('✓ 工具执行成功'));
-```
-
-### 主要差异
-
-| 方面 | 原始代码 | CLI 命令 |
-|------|---------|---------|
-| 输入方式 | HTTP POST JSON | 命令行参数 |
-| 输出格式 | SSE (Server-Sent Events) | 终端彩色输出 |
-| 运行环境 | Next.js 服务器 | Node.js CLI |
-| 交互方式 | 网页/API 客户端 | 命令行终端 |
-| 工作目录 | 通过 POST body 传递 | 通过 CLI 选项传递 |
-
-## 技术栈
-
-- **TypeScript**: 类型安全的代码实现
-- **Commander.js**: CLI 参数解析
-- **Chalk**: 终端彩色输出
-- **Ora**: 加载动画
-- **@anthropic-ai/claude-agent-sdk**: AI Agent 核心功能
-
-## 后续优化建议
-
-### 1. 功能增强
-
-- [ ] 添加配置文件支持（保存常用的工作目录和选项）
-- [ ] 支持交互式提示词输入
-- [ ] 添加历史记录功能
-- [ ] 支持保存/加载会话
-
-### 2. 用户体验
-
-- [ ] 添加进度条显示
-- [ ] 优化消息格式化输出
-- [ ] 添加彩色语法高亮（代码输出）
-- [ ] 支持 Markdown 渲染
-
-### 3. 安全性
-
-- [ ] 添加工作目录白名单
-- [ ] 实现权限确认机制
-- [ ] 添加操作审计日志
-
-### 4. 测试
-
-- [ ] 添加单元测试
-- [ ] 添加集成测试
-- [ ] 添加 E2E 测试
-
-### 5. 文档
-
-- [ ] 添加视频教程
-- [ ] 更多使用示例
-- [ ] FAQ 文档
-
-## 总结
-
-本次开发成功将 Next.js API 路由中的 Claude Agent SDK 集成逻辑封装为 CLI 命令，实现了以下目标：
-
-✅ **功能完整**: 保留了原始代码的所有核心功能  
-✅ **易于使用**: 简洁的命令行界面，清晰的参数说明  
-✅ **文档完善**: 提供了详细的使用文档和快速入门指南  
-✅ **代码质量**: 通过 TypeScript 类型检查和 ESLint 验证  
-✅ **可扩展性**: 遵循项目架构，易于后续功能扩展  
-
-用户现在可以通过简单的命令行操作，在任何项目目录中使用 AI Agent 执行智能任务！
-
-## 相关链接
-
-- [Agent 命令详细文档](docs/AGENT_COMMAND.md)
-- [快速入门指南](docs/AGENT_QUICKSTART.md)
-- [项目架构文档](ARCHITECTURE.md)
-- [主 README](README.md)
-
----
-
-**开发完成时间**: 2025-10-16  
-**版本**: 1.0.0  
-**状态**: ✅ 已完成并测试通过
-

package/CHANGELOG.md

@@ -1,172 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.8] - 2025-10-19
-
-### Fixed
-- 🐛 **容器临时目录修复** - 修改 TMPDIR 环境变量为 `/app`，解决容器环境下临时文件权限问题
-
-## [1.0.0] - 2025-10-16
-
-### Added
-
-#### Core Features
-- ✅ CLI 主类实现 - 命令行程序核心框架
-- ✅ 命令基类 - 统一的命令接口和生命周期管理
-- ✅ 日志系统 - 多级日志和文件持久化支持
-- ✅ 配置管理 - 支持多层配置（默认、用户、环境变量）
-
-#### Commands
-- ✅ `init` 命令 - 交互式初始化项目配置
-- ✅ `config` 命令 - 配置管理（查看/设置/重置）
-- ✅ `example` 命令 - SDK 调用示例
-
-#### SDK Integration
-- ✅ SDK 基类 - 统一的 SDK 接口规范
-- ✅ SDK 管理器 - 集中管理和初始化 SDK
-- ✅ Example SDK - 示例 SDK 实现
-
-#### Utilities
-- ✅ 文件工具 - 文件读写和路径处理
-- ✅ 验证工具 - 输入验证和格式检查
-- ✅ 配置工具 - 配置文件读写和合并
-
-#### Development Tools
-- ✅ TypeScript 支持 - 完整的类型定义
-- ✅ ESLint 配置 - 代码质量检查
-- ✅ Prettier 配置 - 代码格式化
-- ✅ Jest 测试框架 - 单元测试支持
-
-#### Documentation
-- ✅ 架构文档 - 详细的系统设计说明
-- ✅ README - 使用说明和快速开始
-- ✅ 配置示例 - 默认配置文件
-
-### Features
-
-- 🎨 彩色终端输出
-- 🔄 交互式命令行提示
-- 📝 结构化日志记录
-- ⚙️ 灵活的配置系统
-- 🔌 可扩展的 SDK 架构
-- ✅ 完善的错误处理
-- 🚀 模块化设计
-
-### Technical
-
-- Node.js >= 18.0.0 支持
-- TypeScript 5.x
-- Commander.js 用于命令行解析
-- Inquirer.js 用于交互式提示
-- Chalk 用于彩色输出
-- Ora 用于加载动画
-- Axios 用于 HTTP 请求
-
----
-
-## [1.0.5] - 2025-10-19
-
-### Added
-- ✅ **工作目录验证** - 添加 `validateWorkingDirectory()` 函数，在启动 agent 前验证目录是否存在和可访问
-- 📊 **详细错误信息** - agent 执行失败时显示完整的错误堆栈、错误代码和 stdout/stderr 输出
-- 💡 **解决方案提示** - 提供针对常见错误的解决方案建议
-
-### Improved
-- 🎯 **用户体验** - 更友好的错误提示，帮助用户快速定位和解决问题
-- 🔍 **错误诊断** - 增强错误处理，捕获并显示更多上下文信息
-
-### Technical
-- 🛠️ **导入 fs 模块** - 用于文件系统操作和权限检查
-- 🔒 **权限检查** - 使用 `fs.accessSync()` 验证目录的读写权限
-- 📝 **错误对象扩展** - 检查并显示错误对象的 code、stderr、stdout 等属性
-
-## [1.0.4] - 2025-10-19
-
-### Fixed
-- 🐛 **CLI 参数解析修复** - 修复命令行参数（--api-key, --base-url）无法正确传递的问题
-- ✅ **Commander.js 集成** - 正确使用 `commandObject.opts()` 提取命令选项，而不是直接使用 Command 对象
-
-## [1.0.3] - 2025-10-19
-
-### Fixed
-- 🐛 **Agent 命令错误修复** - 修复当未提供 API Key 时的 `Cannot read properties of undefined (reading 'substring')` 错误
-- ✅ **参数验证** - 添加 API Key 和 Base URL 的存在性检查
-- 💬 **错误提示** - 当缺少 API Key 时显示友好的警告信息
-
-## [Unreleased]
-
-### Added
-
-#### Agent Command - Interactive Mode
-- 🔄 **多轮对话支持** - 支持交互式对话模式，可持续与 AI 进行多轮交互
-- 💬 **上下文记忆** - AI 记住对话历史，提供更连贯的回答
-- 🎯 **灵活启动** - 支持带初始提示或直接启动交互模式
-- 📝 **会话管理** - 每个交互会话拥有独立的 session ID
-- 🚪 **优雅退出** - 输入 `exit` 或 `quit` 随时退出对话
-- ⚙️ **扩展配置** - 支持更多轮次（100轮），适应复杂任务
-
-**使用方式：**
-```bash
-# 直接进入交互模式
-needware-cli agent --interactive
-needware-cli agent -i
-
-# 带初始提示启动
-needware-cli agent -i "创建一个待办事项应用"
-```
-
-**文档：**
-- [交互式模式详细文档](docs/INTERACTIVE_MODE.md)
-- [使用示例](INTERACTIVE_EXAMPLE.md)
-
-### Changed
-- 📋 **Agent 命令参数** - `prompt` 参数改为可选，交互模式下不再必需
-- 🔧 **CLI 配置** - 添加 `-i, --interactive` 选项支持
-- 📖 **帮助文档** - 更新帮助信息，包含交互模式说明
-
-### Technical
-- 🛠️ **AsyncGenerator 实现** - 使用异步生成器实现消息流
-- 🔗 **SDK 类型增强** - 引入 `SDKUserMessage` 类型支持
-- 💾 **会话 ID 生成** - 使用 `crypto.randomUUID()` 生成唯一会话标识
-
-### Planned
-
-#### Short-term (1-3 months)
-- [ ] 更多内置命令
-- [ ] 完善测试覆盖
-- [ ] 性能优化
-- [ ] 更多 SDK 集成示例
-
-#### Mid-term (3-6 months)
-- [ ] 插件系统
-- [ ] 多语言支持（i18n）
-- [ ] 自动更新机制
-- [ ] 配置迁移工具
-
-#### Long-term (6-12 months)
-- [ ] 可视化界面
-- [ ] 云端集成
-- [ ] 社区插件市场
-- [ ] 企业级功能
-
----
-
-## Version History
-
-### [1.0.0] - 2025-10-16
-- Initial release
-
----
-
-**Legend:**
-- `Added` for new features
-- `Changed` for changes in existing functionality
-- `Deprecated` for soon-to-be removed features
-- `Removed` for now removed features
-- `Fixed` for any bug fixes
-- `Security` in case of vulnerabilities
-