@ian2018cs/agenthub 0.1.55 → 0.1.56

package/README.md

@@ -1,330 +1,277 @@
 <div align="center">
   <img src="public/logo.svg" alt="AgentHub" width="64" height="64">
   <h1>AgentHub</h1>
+  <p>基于 Web 的 AI Agent 管理平台，支持桌面与移动端</p>
 </div>
 
-A desktop and mobile Web UI for AI Agents. You can use it locally or remotely to manage your AI agent sessions and interact with them from everywhere (mobile or desktop). This gives you a proper interface that works everywhere. 
-
-## Screenshots
+---
 
-<div align="center">
-  
-<table>
-<tr>
-<td align="center">
-<h3>Desktop View</h3>
-<img src="public/screenshots/desktop-main.png" alt="Desktop Interface" width="400">
-<br>
-<em>Main interface showing project overview and chat</em>
-</td>
-<td align="center">
-<h3>Mobile Experience</h3>
-<img src="public/screenshots/mobile-chat.png" alt="Mobile Interface" width="250">
-<br>
-<em>Responsive mobile design with touch navigation</em>
-</td>
-</tr>
-</table>
+## 简介
 
+AgentHub 是一个全功能的 AI Agent Web UI，可本地或远程部署，让你随时随地（手机、电脑）管理和使用 AI Agent 会话。支持 Claude、Gemini、Codex 多种 AI 引擎，并提供飞书 IM 集成、多用户管理、工具安全守卫等企业级特性。
 
+## 功能特性
 
-</div>
+### 核心对话
+- **Claude Agent 对话** — 基于 `@anthropic-ai/claude-agent-sdk`，支持流式响应、工具调用、会话续接
+- **Gemini Shell** — node-pty 驱动 Gemini CLI，xterm.js 渲染真实终端体验
+- **Codex Shell** — node-pty 驱动 Codex CLI，xterm.js 渲染，独立会话隔离
+- **WebSocket 实时通信** — 前后端通过 WebSocket 双向通信，响应实时推送
 
-## Features
+### 项目与文件管理
+- **项目管理** — 自动发现 Agent 会话，按项目分组，支持重命名、删除
+- **文件浏览器** — 交互式文件树，支持展开/折叠导航
+- **代码编辑器** — CodeMirror 6 驱动，多语言语法高亮、实时编辑保存
+- **MCP 服务器支持** — 通过 UI 添加、管理自定义 MCP 服务器，自动同步到 Codex
 
-- **Responsive Design** - Works seamlessly across desktop, tablet, and mobile
-- **Interactive Chat Interface** - Built-in chat interface for seamless communication with AI agents
-- **Integrated Shell Terminal** - Direct access to AI agents through built-in shell functionality
-- **File Explorer** - Interactive file tree with syntax highlighting and live editing
-- **Session Management** - Resume conversations, manage multiple sessions, and track history
-- **MCP Server Support** - Add your own MCP servers through the UI
-- **Model Compatibility** - Works with various AI models 
+### 多用户与权限
+- **多用户系统** — 注册/登录，JWT 认证，每用户数据完全隔离（独立 UUID 目录）
+- **三级角色** — `super_admin`（首个注册用户）、`admin`（受限管理员）、`user`（普通用户）
+- **限额管理** — 按用户设置每日使用限额，管理员面板实时查看用量
+- **邮箱域名白名单** — 限制注册邮箱域名范围
 
+### 飞书 IM 集成
+- **WebSocket 长连接** — 通过 `@larksuiteoapi/node-sdk` 接收飞书消息
+- **单聊对话** — 在飞书直接与 AI Agent 对话
+- **工具审批卡片** — Agent 执行危险操作时，飞书推送审批卡片
+- **语音转文字** — 支持语音消息（需配置 ffmpeg + Whisper）
+- **文件/图片发送** — Agent 可将生成文件自动发送到飞书聊天
 
-## Quick Start
+### 安全
+- **工具安全守卫（Tool Guard）** — 双层检测：正则规则快速拦截 + LLM 兜底审查
+- **路径隔离** — 阻止访问用户目录之外的文件系统路径
+- **危险命令拦截** — 阻止 rm -rf、系统文件修改、全局包安装等高危操作
 
-### Prerequisites
+### Agent 商店
+- **系统 Agent 仓库** — 发布、安装、管理预置 Agent
+- **版本管理** — 支持 Agent 版本控制与更新
+- **管理员审核** — Agent 提交需管理员审核后才能上架
 
-- [Node.js](https://nodejs.org/) v20 or higher
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured
+### 其他
+- **图片持久化** — 聊天图片 SHA-256 去重存储，30 天自动清理
+- **计费统计** — 按模型精确计算 token 用量和费用
+- **响应式设计** — 桌面、平板、手机全端适配，支持添加到主屏幕
 
-### One-click Operation (Recommended)
+---
 
-No installation required, direct operation:
+## 快速开始
 
-```bash
-npx agenthub
-```
+### 环境要求
 
-The server will start and be accessible at `http://localhost:3001` (or your configured PORT).
+- [Node.js](https://nodejs.org/) v20 或更高版本
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) 已安装并配置
 
-**To restart**: Simply run the same `npx` command again after stopping the server
-### Global Installation (For Regular Use)
+### 一键运行（推荐）
 
-For frequent use, install globally once:
+无需安装，直接运行：
 
 ```bash
-npm install -g agenthub
+npx agenthub
 ```
 
-Then start with a simple command:
+服务启动后访问 `http://localhost:3001`（或你配置的端口）。
+
+### 全局安装
 
 ```bash
+npm install -g agenthub
 agenthub
 ```
 
+更新到最新版本：
 
-**To restart**: Stop with Ctrl+C and run `claude-code-ui` again.
-
-**To update**:
 ```bash
 agenthub update
 ```
 
-### CLI Usage
+### CLI 命令
 
-After global installation, you have access to `agenthub` command:
+| 命令 / 选项 | 简写 | 说明 |
+|------------|------|------|
+| `agenthub` | | 启动服务（默认） |
+| `agenthub start` | | 显式启动服务 |
+| `agenthub status` | | 显示配置和数据目录信息 |
+| `agenthub update` | | 更新到最新版本 |
+| `agenthub help` | | 显示帮助信息 |
+| `agenthub version` | | 显示版本信息 |
+| `--port <port>` | `-p` | 指定端口（默认：3001） |
+| `--database-path <path>` | | 指定数据库存储路径 |
 
-| Command / Option | Short | Description |
-|------------------|-------|-------------|
-| `agenthub` | | Start the server (default) |
-| `agenthub start` | | Start the server explicitly |
-| `agenthub status` | | Show configuration and data locations |
-| `agenthub update` | | Update to the latest version |
-| `agenthub help` | | Show help information |
-| `agenthub version` | | Show version information |
-| `--port <port>` | `-p` | Set server port (default: 3001) |
-| `--database-path <path>` | | Set custom database location |
+示例：
 
-**Examples:**
 ```bash
-agenthub                          # Start with defaults
-agenthub -p 8080              # Start on custom port
-agenthub status                   # Show current configuration
+agenthub -p 8080          # 在 8080 端口启动
+agenthub status           # 查看当前配置
 ```
 
-### Run as Background Service (Recommended for Production)
-
-For production use, run AgentHub as a background service using PM2 (Process Manager 2):
+### 后台服务（生产环境推荐）
 
-#### Install PM2
+使用 PM2 作为进程管理器：
 
 ```bash
 npm install -g pm2
-```
-
-#### Start as Background Service
 
-```bash
-# Start the server in background
+# 启动后台服务
 pm2 start agenthub --name "agenthub"
 
-# Or using the shorter alias
-pm2 start agenthub --name "agenthub"
-
-# Start on a custom port
+# 在指定端口启动
 pm2 start agenthub --name "agenthub" -- --port 8080
-```
-
 
-#### Auto-Start on System Boot
-
-To make AgentHub start automatically when your system boots:
-
-```bash
-# Generate startup script for your platform
+# 开机自启
 pm2 startup
-
-# Save current process list
 pm2 save
 ```
 
+---
 
-### Local Development Installation
+## 本地开发
 
-1. **Clone the repository:**
 ```bash
-git clone https://github.com/IAn2018cs/claudecodeui.git
-cd claudecodeui
-```
+# 克隆仓库
+git clone git@git.amberweather.com:share/agenthub.git
+cd agenthub
 
-2. **Install dependencies:**
-```bash
+# 安装依赖
 npm install
-```
 
-3. **Configure environment:**
-```bash
+# 配置环境变量
 cp .env.example .env
-# Edit .env with your preferred settings
-```
+# 编辑 .env 填写所需配置
 
-4. **Start the application:**
-```bash
-# Development mode (with hot reload)
+# 开发模式（React 热重载 + Node 服务器）
 npm run dev
-
 ```
-The application will start at the port you specified in your .env
-
-5. **Open your browser:**
-   - Development: `http://localhost:3001`
 
-## Security & Tools Configuration
+其他开发命令：
 
-**🔒 Important Notice**: All agent tools are **disabled by default**. This prevents potentially harmful operations from running automatically.
+```bash
+npm run build    # 生产构建
+npm run start    # 构建 + 启动服务器
+npm run server   # 仅启动 Node 服务器
+npm run client   # 仅启动 Vite dev 服务器
+```
 
-### Enabling Tools
+---
 
-To use full functionality, you'll need to manually enable tools:
+## 环境变量配置
 
-1. **Open Tools Settings** - Click the gear icon in the sidebar
-3. **Enable Selectively** - Turn on only the tools you need
-4. **Apply Settings** - Your preferences are saved locally
+在 `.env` 文件中配置以下变量：
 
-<div align="center">
+### 基础配置
 
-![Tools Settings Modal](public/screenshots/tools-modal.png)
-*Tools Settings interface - enable only what you need*
+| 变量 | 说明 |
+|------|------|
+| `PORT` | 服务端口，默认 `3001` |
+| `JWT_SECRET` | JWT 签名密钥（必填） |
+| `ANTHROPIC_API_KEY` | Anthropic API Key |
 
-</div>
+### 飞书集成（可选）
 
-**Recommended approach**: Start with basic tools enabled and add more as needed. You can always adjust these settings later.
+| 变量 | 说明 |
+|------|------|
+| `FEISHU_APP_ID` | 飞书应用 App ID |
+| `FEISHU_APP_SECRET` | 飞书应用 App Secret |
+| `FEISHU_MENU_KEY_MAP` | JSON 格式，event_key → 斜杠命令映射 |
+| `FEISHU_CARD_*_ID` | 各类消息卡片模板 ID |
 
-## Usage Guide
+设置 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 即可自动启用飞书集成。
 
-### Core Features
+### 语音转文字（可选，需飞书集成）
 
-#### Project Management
-It automatically discovers agent sessions and groups them together into projects
-session counts
-- **Project Actions** - Rename, delete, and organize projects
-- **Smart Navigation** - Quick access to recent projects and sessions
-- **MCP support** - Add your own MCP servers through the UI
+| 变量 | 说明 |
+|------|------|
+| `WHISPER_*` | Whisper 语音识别相关配置 |
 
-#### Chat Interface
-- **Use responsive chat or CLI** - You can either use the adapted chat interface or use the shell button to connect to CLI.
-- **Real-time Communication** - Stream responses from AI agents with WebSocket connection
-- **Session Management** - Resume previous conversations or start fresh sessions
-- **Message History** - Complete conversation history with timestamps and metadata
-- **Multi-format Support** - Text, code blocks, and file references
+### 工具安全守卫（可选）
 
-#### File Explorer & Editor
-- **Interactive File Tree** - Browse project structure with expand/collapse navigation
-- **Live File Editing** - Read, modify, and save files directly in the interface
-- **Syntax Highlighting** - Support for multiple programming languages
-- **File Operations** - Create, rename, delete files and directories
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `TOOL_GUARD_ENABLED` | 总开关 | `false` |
+| `TOOL_GUARD_LLM_ENABLED` | LLM 审查开关 | `false` |
+| `TOOL_GUARD_LLM_MODEL` | LLM 审查模型 | `gemini-3.1-flash-lite-preview` |
+| `TOOL_GUARD_LLM_TIMEOUT_MS` | LLM 超时时间（毫秒） | `5000` |
+| `TOOL_GUARD_VERBOSE` | 详细日志 | `false` |
 
-#### Session Management
-- **Session Persistence** - All conversations automatically saved
-- **Session Organization** - Group sessions by project and timestamp
-- **Session Actions** - Rename, delete, and export conversation history
-- **Cross-device Sync** - Access sessions from any device
+### LLM 通用配置（Tool Guard LLM 审查用）
 
-### Mobile App
-- **Responsive Design** - Optimized for all screen sizes
-- **Touch-friendly Interface** - Swipe gestures and touch navigation
-- **Mobile Navigation** - Bottom tab bar for easy thumb navigation
-- **Adaptive Layout** - Collapsible sidebar and smart content prioritization
-- **Add shortcut to Home Screen** - Add a shortcut to your home screen and the app will behave like a PWA
+| 变量 | 说明 |
+|------|------|
+| `OPENAI_API_KEY` | OpenAI 兼容 API Key |
+| `OPENAI_BASE_URL` | OpenAI 兼容 API Base URL |
 
-## Architecture
+---
 
-### System Overview
+## 架构概览
 
 ```
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│   Frontend      │    │   Backend       │    │  Agent     │
-│   (React/Vite)  │◄──►│ (Express/WS)    │◄──►│  Integration    │
-│                 │    │                 │    │                │
-└─────────────────┘    └─────────────────┘    └─────────────────┘
+┌──────────────────────┐    ┌──────────────────────┐    ┌──────────────────────┐
+│  前端 (React + Vite)  │◄──►│  后端 (Express + WS)  │◄──►│  AI 引擎集成          │
+│                      │    │                      │    │  Claude / Gemini     │
+│  - ChatInterface     │    │  - claude-sdk.js     │    │  / Codex             │
+│  - GeminiShell       │    │  - WebSocket 路由     │    │                      │
+│  - CodexShell        │    │  - REST API          │    └──────────────────────┘
+│  - CodeEditor        │    │  - SQLite (DB)       │
+│  - AdminPanel        │    │  - Tool Guard        │    ┌──────────────────────┐
+└──────────────────────┘    │  - 飞书 IM 服务       │◄──►│  飞书 IM              │
+                            └──────────────────────┘    │  (长连接 WS)          │
+                                                        └──────────────────────┘
 ```
 
-### Backend (Node.js + Express)
-- **Express Server** - RESTful API with static file serving
-- **WebSocket Server** - Communication for chats and project refresh
-- **Agent Integration** - Process spawning and management
-- **File System API** - Exposing file browser for projects
+### 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 前端框架 | React 18 + Vite 7 |
+| 样式 | Tailwind CSS 3.4 |
+| 代码编辑器 | CodeMirror 6 |
+| 终端 | xterm.js |
+| 后端框架 | Node.js 20+ + Express 4 |
+| 实时通信 | WebSocket (`ws`) |
+| 数据库 | better-sqlite3 |
+| 终端进程 | node-pty |
+| AI SDK | `@anthropic-ai/claude-agent-sdk` |
+| 飞书 SDK | `@larksuiteoapi/node-sdk` |
 
-### Frontend (React + Vite)
-- **React 18** - Modern component architecture with hooks
-- **CodeMirror** - Advanced code editor with syntax highlighting
-
-
-
-
-
-### Contributing
-
-We welcome contributions! Please follow these guidelines:
-
-#### Getting Started
-1. **Fork** the repository
-2. **Clone** your fork: `git clone <your-fork-url>`
-3. **Install** dependencies: `npm install`
-4. **Create** a feature branch: `git checkout -b feature/amazing-feature`
-
-#### Development Process
-1. **Make your changes** following the existing code style
-2. **Test thoroughly** - ensure all features work correctly
-3. **Run quality checks**: `npm run lint && npm run format`
-4. **Commit** with descriptive messages following [Conventional Commits](https://conventionalcommits.org/)
-5. **Push** to your branch: `git push origin feature/amazing-feature`
-6. **Submit** a Pull Request with:
-   - Clear description of changes
-   - Screenshots for UI changes
-   - Test results if applicable
-
-#### What to Contribute
-- **Bug fixes** - Help us improve stability
-- **New features** - Enhance functionality (discuss in issues first)
-- **Documentation** - Improve guides and API docs
-- **UI/UX improvements** - Better user experience
-- **Performance optimizations** - Make it faster
-
-## Troubleshooting
+---
 
-### Common Issues & Solutions
+## 工具设置
 
+> **注意**：所有 Agent 工具默认关闭，防止自动执行高风险操作。
 
-#### "No projects found"
-**Problem**: The UI shows no projects or empty project list
-**Solutions**:
-- Ensure you have initialized at least one project
-- Verify `~/.claude/projects/` directory exists and has proper permissions
+开启工具步骤：
+1. 点击侧边栏齿轮图标打开设置
+2. 进入"工具设置"
+3. 按需开启所需工具
+4. 设置会自动保存
 
-#### File Explorer Issues
-**Problem**: Files not loading, permission errors, empty directories
-**Solutions**:
-- Check project directory permissions (`ls -la` in terminal)
-- Verify the project path exists and is accessible
-- Review server console logs for detailed error messages
-- Ensure you're not trying to access system directories outside project scope
+建议从基础工具开始，按需逐步开启。
 
+---
 
-## License
+## 常见问题
 
-GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
+**无项目显示**
+- 确认至少初始化了一个项目
+- 检查 `~/.claude/projects/` 目录是否存在且有读取权限
 
-This project is open source and free to use, modify, and distribute under the GPL v3 license.
+**文件浏览器无法加载**
+- 检查项目目录权限（`ls -la`）
+- 确认项目路径存在且可访问
+- 查看服务器控制台日志获取详细错误信息
 
-## Acknowledgments
+**飞书集成不工作**
+- 确认 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 已正确设置
+- 检查飞书应用是否已开启事件订阅
+- 确认机器人已被添加到对应群/单聊
 
-### Built With
-- **[React](https://react.dev/)** - User interface library
-- **[Vite](https://vitejs.dev/)** - Fast build tool and dev server
-- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework
-- **[CodeMirror](https://codemirror.net/)** - Advanced code editor
+---
 
-## Support & Community
+## 许可证
 
-### Stay Updated
-- **Star** this repository to show support
-- **Watch** for updates and new releases
-- **Follow** the project for announcements
+MIT License — 详见 [LICENSE](LICENSE) 文件。
 
 ---
 
 <div align="center">
-  <strong>Made with care for the AI community.</strong>
+  <strong>为 AI 开发者打造的一站式 Agent 管理平台</strong>
 </div>