xiaozhou-chat 1.0.0 → 1.0.1-0.1

package/README.md

@@ -1,28 +1,124 @@
-# my-newapi-chat
+# xiaozhou-chat
 
-CLI chatbot based on NewAPI.
+CLI chatbot based on NewAPI with advanced features like Project Context, Multi-Profiles, and AI Tools.
+基于 NewAPI 的高级命令行聊天工具，支持项目上下文感知、多环境配置及 AI 自动化工具。
 
-## 安装
-npm i -g my-newapi-chat
+---
 
-## 配置
-export NEWAPI_API_KEY="你的Key"
+## ✨ 特性 (Features)
 
-可选：
-export NEWAPI_BASE_URL="https://api.newapi.pro/v1"
-export NEWAPI_MODEL="gpt-3.5-turbo"
+- **🤖 多模型/多环境管理**：支持通过 `/profile` (或 `/切换模型`) 快速切换不同的 API Key 和模型配置。
+- **📂 项目感知**：通过 `/scan` 自动扫描项目结构、读取 `package.json` 和 `README.md` (智能大文件摘要)，让 AI 理解你的项目。
+- **🛠️ AI 编程助手**：内置文件读写 (`read_file`, `write_file`) 和命令执行 (`run_command`) 工具，AI 可以帮你重构代码、运行测试。
+- **🛡️ 安全机制**：`write_file` 覆盖文件前自动创建 `.bak` 备份；敏感文件自动排除；网络请求失败自动指数退避重试。
+- **🚀 效率工具**：`/commit` 自动分析代码变更并生成 Git Commit Message；`/token` 实时监控上下文消耗。
+- **🎨 交互优化**：
+  - **Ctrl+C 中断**：生成过程中按 `Ctrl+C` 仅中断当前输出，不退出程序。
+  - **Markdown 渲染**：终端内完美渲染 Markdown（代码高亮、表格、粗体等）。
+  - **Esc 快捷键**：按 `Esc` 清除当前输入，空行时按 `Esc` 退出程序。
+- **⚙️ 灵活配置**：支持全局配置及项目级配置文件 (`.newapi-chat-config.json`)，可随项目隔离环境。
+- **🔌 MCP 支持**：集成 Model Context Protocol，可连接外部 MCP Server 扩展能力。
 
-## 使用
-newapi-chat
+---
 
-## CLI 参数
-newapi-chat --model gpt-4 --base-url https://api.newapi.pro/v1
+## 📦 安装与使用 (Installation & Usage)
 
-## 历史记录
-默认保存在：
-~/.newapi-chat-history.json
+### 方式一：在当前项目中使用 (推荐)
+无需全局安装，直接在你的项目中添加并初始化配置：
 
-## Windows 打包
-npm i -g pkg
-npm run build:win
-dist/newapi-chat.exe
+1. **安装依赖**
+   ```bash
+   npm install xiaozhou-chat
+   ```
+
+2. **初始化配置** (自动在当前目录生成配置文件)
+   ```bash
+   npx xiaozhou-chat init
+   ```
+
+3. **启动聊天**
+   ```bash
+   npx xiaozhou-chat
+   ```
+
+### 方式二：全局安装
+如果你希望在任何目录下都能使用：
+
+```bash
+npm i -g xiaozhou-chat
+xiaozhou-chat
+```
+
+---
+
+## 💬 常用命令 (Commands)
+
+在对话中输入 `/` 开头的命令即可触发功能。支持中文别名。
+
+### 🔧 配置管理
+| 命令 | 中文别名 | 说明 |
+|---|---|---|
+| `/init` | `/初始化配置` | (交互式) 在当前目录生成 `.newapi-chat-config.json` |
+| `/config` | `/配置` | 查看或修改当前配置 (如 `/config set model gpt-4`) |
+| `/profile` | `/切换模型` | 管理多套配置 (详情见下文) |
+| `/system` | - | 设置系统提示词 (System Prompt) |
+
+### 🧠 上下文与文件
+| 命令 | 中文别名 | 说明 |
+|---|---|---|
+| `/scan` | `/当前项目结构` | 扫描当前目录结构并加载关键文件到上下文 |
+| `/load <file>` | - | 加载指定文件内容给 AI (支持大文件行号选择) |
+| `/save <file>` | - | 将 AI 回复中的代码块保存为本地文件 |
+| `/paste` | - | 进入多行粘贴模式 (避免回车直接发送) |
+
+### 🛠️ 工具与扩展
+| 命令 | 说明 |
+|---|---|
+| `/commit` | 自动执行 `git add -A` 并利用 AI 生成提交信息 |
+| `/token` | 查看当前会话 Token 估算与预警 |
+| `/compress` | 智能压缩对话历史，节省 Token |
+| `/mcp` | 管理 MCP 服务器连接 (如连接外部数据库工具) |
+| `/clear` | 清空当前对话历史 (保留 System Prompt) |
+| `/history` | 查看历史记录 (支持 Markdown 渲染) |
+| `/export` | 导出对话记录为 Markdown |
+
+---
+
+## ⚙️ 配置文件 (Configuration)
+
+工具会按以下优先级读取配置：
+1. **项目级配置**：`./.newapi-chat-config.json` (推荐，由 `init` 生成)
+2. **用户级配置**：`~/.newapi-chat-config.json`
+
+**配置文件示例 (`.newapi-chat-config.json`)：**
+```json
+{
+  "apiKey": "sk-xxxx",
+  "baseUrl": "https://api.newapi.pro/v1",
+  "model": "claude-3-5-sonnet",
+  "profiles": {
+    "default": { "model": "claude-3-5-sonnet" },
+    "gpt4": { "model": "gpt-4", "apiKey": "sk-special..." }
+  }
+}
+```
+
+> **注意**：建议将 `.newapi-chat-config.json` 添加到 `.gitignore` 中，防止 API Key 泄露。
+
+---
+
+## 🛠️ 本地开发 (Development)
+
+### 依赖安装
+```bash
+npm install
+```
+
+### 构建与打包
+- **Windows**: `npm run build:win` -> `dist/newapi-chat.exe`
+- **macOS**: `npm run build:mac` -> `dist/xiaozhou-chat`
+
+---
+
+## 📄 许可证
+MIT