niumagents-cli 0.1.12 → 0.1.13

package/README.md

@@ -1,5 +1,7 @@
 # NiumAgents-CLI
 
+一个基于 AI 的智能代码助手工具，支持多种编程语言的代码生成、项目分析、智能问答等功能。
+
 ## 📦 安装
 
 ### 全局安装
@@ -20,6 +22,8 @@ nium
 
 ### 模型配置
 
+首次启动时，系统会自动创建 `.nium/config.json` 配置文件。
+
 配置示例（`.nium/config.json`）：
 
 ```json
@@ -29,10 +33,10 @@ nium
       "apiKey": "your-api-key-here",
       "baseURL": "https://api.openai.com/v1",
       "model": "gpt-4o",
-      "provider": "openai", // openai(OpenAI兼容) / anthropic
+      "provider": "openai", // openai(OpenAI兼容) / anthropic 
       "maxToken": 128000
     }
-    // 可选配置
+    // 可选：轻量级模型，用于简单任务和上下文压缩
     // "liteModel": {
     //   "apiKey": "your-api-key-here",
     //   "baseURL": "https://api.openai.com/v1",
@@ -44,6 +48,10 @@ nium
 }
 ```
 
+**支持的 provider 类型：**
+- `openai` - OpenAI 及兼容接口（如 DeepSeek, Qwen 等）
+- `anthropic` - Anthropic Claude API
+
 ### 基本工作流程
 
 ```bash
@@ -79,7 +87,7 @@ nium> /clear
 | 命令 | 说明 | 示例 |
 |------|------|------|
 | `/commit` | 使用AI生成commit message并提交 | `/commit` |
-| `/list_tools` | 列出所有可用的工具和代理 | `/list_tools` |
+| `/list_tools` | 列出所有可用的工具（含MCP工具） | `/list_tools` |
 | `/history` | 查看归档的会话历史 | `/history` |
 
 ### 系统命令
@@ -92,18 +100,61 @@ nium> /clear
 ### 命令提示
 
 - 输入 `/` 后可以使用**模糊搜索**来快速找到命令
-- 大多数命令都有简短的别名（如 `/h` = `/help`）
+- 支持命令简写和快速匹配
+
+## 🎯 内置工具和智能体
+
+### 核心工具
+
+#### 思考和规划工具
+- `think(thought)` - 记录思考过程，支持结构化思维和推理
+- `plan(task, subtasks)` - 创建和管理复杂任务计划
+- `todo(action, items)` - 管理待办任务列表，跟踪任务进度
+- `askUser(question, options?)` - 向用户提问并等待响应
+
+#### 文件操作工具
+- `read(path)` - 读取文件内容
+- `write(path, content)` - 写入文件（创建或覆盖）
+- `merge(path, content)` - 智能合并内容到文件（使用三方合并算法，自动解决冲突）
+- `delete(path)` - 删除文件或目录
+- `mkdir(path)` - 创建目录
+- `move(source, destination)` - 移动文件或目录
+- `copy(source, destination)` - 复制文件或目录
+- `searchReplace(pattern, replacement, path)` - 基于正则表达式的查找替换
+- `validate(path)` - 验证文件语法和格式
+
+#### 搜索和检索工具
+- `glob(pattern)` - 通过模式匹配文件（如 `**/*.ts`、`src/**/*.java`）
+- `grep(pattern, path)` - 在文件中搜索内容（支持正则表达式）
+- `search_docs(query, scope?)` - 在项目文档中搜索内容
+- `build_doc_index(paths?)` - 构建项目文档索引
+- `search_file_changes(query?, options?)` - 搜索和查询文件变更历史
+
+#### 项目探索工具
+- `quickProjectScan()` - 快速扫描项目结构并生成文档（15-30秒）
+- `explore(topic, topicEnglish)` - 深度探索项目整体架构、模块关系、设计模式（30-60秒）
+- `moduleExplore(moduleName, moduleEnglish, searchPattern?)` - 深度探索单个模块的内部实现、函数细节（60-120秒）
+- `toolingExplore(topic, topicEnglish)` - 深度探索构建工具和开发流程配置（30-60秒）
 
-## 🎯 子代理系统
+#### 智能辅助工具
+- `smartSuggest(context, options?)` - 基于上下文的智能建议和推荐
 
-子代理是具有特定领域专长的智能体，能够更专业地处理特定类型的任务。
+#### 系统工具
+- `shell(command)` - 执行通用 shell 命令（跨平台）
+- `bash(command)` - 执行 Bash 命令（Linux/macOS）
+- `powershell(command)` - 执行 PowerShell 命令（Windows）
 
+**注意：** `bash` 和 `powershell` 工具会根据运行平台自动启用。
 
-### 自定义子代理
+### MCP 工具（可选）
 
-你可以创建自己的子代理来处理特定任务。
+如果配置了 MCP 服务器，还可以使用额外的工具。通过 `/list_tools` 命令可查看所有可用工具。
 
-#### 创建自定义代理
+### 自定义智能体
+
+你可以创建自己的智能体来处理特定任务。
+
+#### 创建自定义智能体
 
 在 `.nium/agents/` 目录下创建 `.md` 文件：
 
@@ -134,28 +185,28 @@ keywords: 翻译, translate, 中英文, translation
 
 ### .nium 目录结构
 
-`.nium/` 目录包含所有配置文件和会话数据，该目录已添加到 `.gitignore`。
+`.nium/` 目录包含所有配置文件和会话数据，该目录已自动添加到 `.gitignore`。
 
 ```
 .nium/
-├── .env                    # 环境变量配置
-├── config.json             # 全局配置
+├── config.json             # 全局配置（模型、MCP服务器等）
 ├── session.jsonl           # 当前会话数据（用于恢复）
-├── agents/                 # 自定义子代理配置 ⭐
+├── agents/                 # 自定义智能体配置 ⭐
 │   ├── commit-helper.md
 │   ├── translator.md
 │   └── your-agent.md
 ├── archives/               # 历史会话归档
 │   └── session-*.jsonl
-└── project/                # 项目信息
-    └── project.json
+├── project/                # 项目信息缓存
+│   └── project.json
+└── rules.md                # 项目规则文件（可选）
 ```
 
-### 环境变量配置
+### 高级配置
 
-在 `.nium/.env` 文件中可以配置以下环境变量：
+#### 环境变量（可选）
 
-#### 功能开关
+可以通过环境变量或 `.nium/.env` 文件配置：
 
 ```bash
 # 启用上下文隔离模式（推荐）
@@ -164,49 +215,80 @@ USE_LLM_DISCLOSURE=true
 # 启用LLM生成高质量摘要
 USE_LLM_SUMMARY=true
 
+# 启用调试模式
+DEBUG=true
 ```
 
+#### 项目规则文件（可选）
 
-### 项目规则文件（可选）
-
-创建 `.nium/rules.md` 文件来定义项目特定的规则和约定
-
-该文件用于告诉AI助手项目的编码规范、架构约定、开发流程等信息。
-
-## 🛠️ 可用工具
-
-系统提供了丰富的工具集，可通过 `/list_tools` 命令查看完整列表。
-
-### 文件操作工具
-
-- `read(path)` - 读取文件内容
-- `write(path, content)` - 写入文件
-- `merge(path, content)` - 智能合并内容到文件
-- `delete(path)` - 删除文件
-- `mkdir(path)` - 创建目录
-- `searchReplace(pattern, replacement, path)` - 查找替换
-
-### 代码搜索工具
+创建 `.nium/rules.md` 文件来定义项目特定的规则和约定。该文件用于告诉AI助手项目的编码规范、架构约定、开发流程等信息。
 
-- `glob(pattern)` - 通过模式匹配文件
-- `grep(pattern, path)` - 在文件中搜索内容
+**示例 `.nium/rules.md`：**
 
-### Git工具
+```markdown
+# 项目规则
+
+## 代码风格
+- 使用 TypeScript 严格模式
+- 使用 ES6+ 语法
+- 优先使用函数式编程风格
+
+## 命名约定
+- 文件名使用 kebab-case
+- 类名使用 PascalCase
+- 函数和变量使用 camelCase
+
+## 架构约定
+- 遵循单一职责原则
+- 保持模块解耦
+- 使用依赖注入
+```
 
-- `shell(command)` - 执行shell命令（包括git命令）
+### MCP 集成
 
-### 项目分析工具
+支持 Model Context Protocol (MCP)，可以通过MCP服务器扩展更多功能。
 
-- `quickProjectScan()` - 快速扫描项目结构并生成文档
+#### MCP 配置
 
-### 智能体工具
+在 `.nium/config.json` 中配置 MCP 服务器：
 
-- `think(thought)` - 记录思考过程
-- `askUser(question)` - 向用户提问
+```json
+{
+  "models": {
+    "defaultModel": {
+      "apiKey": "your-api-key-here",
+      "baseURL": "https://api.openai.com/v1",
+      "model": "gpt-4o",
+      "provider": "openai",
+      "maxToken": 128000
+    }
+  },
+  "mcpServers": [
+    {
+      "name": "example-http-server",
+      "description": "示例 HTTP MCP 服务器",
+      "transport": "http",
+      "url": "http://localhost:3000",
+      "headers": {
+        "Authorization": "Bearer your-token-here"
+      },
+      "timeout": 30000,
+      "enabled": false
+    }
+  ]
+}
+```
 
-### MCP工具（可选）
+**配置说明：**
+- `name` - 服务器名称（唯一标识）
+- `description` - 服务器描述
+- `transport` - 传输协议（http 或 stdio）
+- `url` - 服务器地址（HTTP 模式）
+- `headers` - 请求头（可选）
+- `timeout` - 超时时间（毫秒）
+- `enabled` - 是否启用
 
-如果配置了MCP服务器，还可以使用额外的工具。详见MCP配置文档。
+配置完成后重新启动，使用 `/list_tools` 命令查看可用的 MCP 工具。
 
 ## 🎨 使用示例
 
@@ -216,66 +298,70 @@ USE_LLM_SUMMARY=true
 nium> 帮我创建一个用户认证模块，包括登录、注册和token验证
 ```
 
-### 示例2：代码审查
+### 示例2：代码分析和重构
 
 ```bash
-nium> 审查 src/api/user.ts 文件，找出潜在问题
+nium> 分析 src/api/user.ts 文件，找出潜在问题并优化代码
 ```
 
-### 示例3：生成commit message
+### 示例3：自动提交代码
 
 ```bash
 # 修改代码后
 nium> /commit
+# AI会自动分析变更，生成合适的commit message并提交
 ```
 
-### 示例4：探索项目
+### 示例4：项目探索
 
 ```bash
-nium> 探索这个项目的结构
+nium> 探索这个项目的结构，告诉我主要的模块和它们的功能
 ```
 
+### 示例5：智能问答
 
-### MCP集成
+```bash
+nium> 这个项目中的用户认证是如何实现的？
+```
 
-支持Model Context Protocol，可以通过MCP服务器扩展更多功能。配置完成后重新启动，通过 /list_tools 命令查看
+## ✨ 核心特性
 
-配置示例（`.nium/config.json`）：
+### 智能上下文管理
 
-```json
-{
-  "models": {
-    "defaultModel": {
-      "apiKey": "your-api-key-here",
-      "baseURL": "https://api.openai.com/v1",
-      "model": "gpt-4o",
-      "provider": "openai", 
-      "maxToken": 128000
-    },
-    "liteModel": {
-      "apiKey": "your-api-key-here",
-      "baseURL": "https://api.openai.com/v1",
-      "model": "gpt-3.5-turbo",
-      "provider": "openai",
-      "maxToken": 16385
-    }
-  },
-  "mcpServers": [
-    {
-      "name": "example-http-server",
-      "description": "Example HTTP MCP server",
-      "transport": "http",
-      "url": "http://localhost:3000",
-      "headers": {
-        "Authorization": "Bearer your-token-here"
-      },
-      "timeout": 30000,
-      "enabled": false
-    }
-  ]
-}
-```
+- **自动上下文压缩** - 使用 LLM 智能压缩历史对话，保持上下文相关性
+- **语义分析** - 自动分析代码语义，提取关键信息
+- **上下文锚点** - 标记重要上下文，避免信息丢失
+- **会话恢复** - 支持中断恢复，保持工作连续性
+- **项目语言缓存** - 自动检测和缓存项目语言，优化后续操作
+
+### 智能文件操作
+
+- **文件变更追踪** - 自动记录所有文件变更，支持历史查询
+- **编码自动检测** - 智能识别文件编码（UTF-8/GBK等）
+
+### 项目分析能力
+
+- **快速扫描** - 快速分析项目结构，生成文档（15-30秒）
+- **深度探索** - 深入分析项目架构、模块关系、设计模式（30-60秒）
+- **模块探索** - 探索单个模块的内部实现和调用链（60-120秒）
+- **依赖分析** - 分析项目依赖关系（支持 Java Maven/Gradle、npm、pip 等）
+- **代码标准检测** - 自动检测项目使用的代码规范和工具
+- **文档搜索** - 基于 FlexSearch 的文档全文检索
+
+### ReAct 智能体架构
+
+基于 ReAct（Reasoning + Acting）模式：
+1. **Thought（思考）** - 结构化思考和推理过程
+2. **Action（行动）** - 执行具体操作和工具调用
+3. **Observation（观察）** - 观察执行结果和反馈
+4. **循环优化** - 根据结果调整策略，持续改进
 
 ## 📝 许可证
 
-MIT License - 详见 [LICENSE](https://github.com/niuma996/niumagents-cli?tab=MIT-1-ov-file) 文件
+MIT License - 详见 [LICENSE](https://github.com/niuma996/niumagents-cli?tab=MIT-1-ov-file) 文件
+
+## 🔗 相关链接
+
+- [GitHub 仓库](https://github.com/niuma996/niumagents-cli)
+- [问题反馈](https://github.com/niuma996/niumagents-cli/issues)
+- [更新日志](https://github.com/niuma996/niumagents-cli/releases)