agentstudio 0.3.0 → 0.3.1

package/QUICKSTART.md

@@ -0,0 +1,253 @@
+# AgentStudio Docker 快速入门
+
+## 一、构建镜像
+
+```bash
+docker build -t agentstudio:latest .
+```
+
+构建时间：约 3-5 分钟（取决于网络速度）
+镜像大小：约 894MB
+
+## 二、运行应用
+
+### 方式 1：使用 docker-compose（推荐）
+
+```bash
+# 启动
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 停止
+docker-compose down
+```
+
+### 方式 2：使用 docker 命令
+
+```bash
+# 启动容器
+docker run -d \
+  --name agentstudio \
+  -p 4936:4936 \
+  -e ANTHROPIC_API_KEY=your_api_key_here \
+  -v agentstudio_data:/app/data \
+  agentstudio:latest
+
+# 查看日志
+docker logs -f agentstudio
+
+# 停止容器
+docker stop agentstudio
+
+# 启动已停止的容器
+docker start agentstudio
+```
+
+## 三、访问应用
+
+打开浏览器访问：**http://localhost**
+
+- **前端界面**：http://localhost (nginx 服务，端口 80)
+- **API 接口**：http://localhost/api (nginx 代理到后端)
+- **后端直接访问**：http://localhost:4936 (可选)
+- **健康检查**：http://localhost:4936/api/health
+
+## 四、数据持久化说明
+
+### 📊 数据保存位置
+
+所有应用数据（agent 配置、会话历史、项目文件等）都保存在 `/app/data` 目录，通过 Docker Volume 挂载到宿主机。
+
+### ✅ 数据会保留的情况
+
+| 操作 | 数据是否保留 | 说明 |
+|------|-------------|------|
+| `docker stop` | ✅ 保留 | 停止容器，数据完整保留 |
+| `docker start` | ✅ 保留 | 重启容器，数据完整恢复 |
+| `docker restart` | ✅ 保留 | 重启容器，数据完整保留 |
+| `docker-compose down` | ✅ 保留 | 停止并删除容器，但 volume 数据保留 |
+| `docker-compose up` | ✅ 保留 | 重新创建容器，数据自动恢复 |
+| 镜像升级 | ✅ 保留 | 重新构建镜像，volume 数据不受影响 |
+
+### ❌ 数据会丢失的情况
+
+| 操作 | 数据是否丢失 | 如何避免 |
+|------|-------------|---------|
+| `docker rm agentstudio` | ⚠️ 容器数据丢失 | 使用 volume 挂载 |
+| `docker volume rm agentstudio_data` | ❌ 永久删除 | 删除前备份数据 |
+| `docker-compose down -v` | ❌ 永久删除 | 不要使用 `-v` 参数 |
+| `docker system prune -a --volumes` | ❌ 永久删除所有 | 谨慎使用全局清理命令 |
+
+## 五、数据备份与恢复
+
+### 备份数据
+
+```bash
+# 创建备份
+docker run --rm \
+  -v agentstudio_data:/data \
+  -v $(pwd):/backup \
+  ubuntu tar czf /backup/agentstudio-backup-$(date +%Y%m%d).tar.gz -C /data .
+```
+
+### 恢复数据
+
+```bash
+# 从备份恢复
+docker run --rm \
+  -v agentstudio_data:/data \
+  -v $(pwd):/backup \
+  ubuntu tar xzf /backup/agentstudio-backup-20251010.tar.gz -C /data
+```
+
+### 查看 Volume 内容
+
+```bash
+# 列出 volume
+docker volume ls
+
+# 查看 volume 详情
+docker volume inspect agentstudio_data
+
+# 进入容器查看数据
+docker exec -it agentstudio ls -la /app/data
+```
+
+## 六、实际测试示例
+
+### 测试数据持久化
+
+```bash
+# 1. 启动容器
+docker-compose up -d
+
+# 2. 使用应用（创建一些 agents、sessions）
+# 访问 http://localhost:4936
+
+# 3. 停止容器
+docker-compose down
+
+# 4. 再次启动
+docker-compose up -d
+
+# 5. 访问应用，所有数据都还在！
+```
+
+### 升级应用保留数据
+
+```bash
+# 1. 停止旧版本
+docker-compose down
+
+# 2. 拉取最新代码并重新构建
+git pull
+docker build -t agentstudio:latest .
+
+# 3. 启动新版本
+docker-compose up -d
+
+# 4. 数据自动恢复，无需任何额外操作
+```
+
+## 七、环境变量配置
+
+创建 `backend/.env` 文件：
+
+```env
+# AI Provider API Keys (至少配置一个)
+ANTHROPIC_API_KEY=sk-ant-xxx...
+# OPENAI_API_KEY=sk-xxx...
+
+# 服务器配置
+PORT=4936
+NODE_ENV=production
+
+# 自定义 CORS（可选）
+# CORS_ORIGINS=https://yourdomain.com,https://anotherdomain.com
+```
+
+## 八、常见问题
+
+### 1. 如何查看容器是否健康？
+
+```bash
+docker ps
+# 查看 STATUS 列，应该显示 "healthy"
+```
+
+### 2. 端口被占用怎么办？
+
+修改 docker-compose.yml 中的端口映射：
+```yaml
+ports:
+  - "8080:80"      # 前端使用 8080 端口
+  - "5000:4936"    # 后端使用 5000 端口
+```
+
+然后访问 http://localhost:8080
+
+### 3. 如何完全重新开始？
+
+```bash
+# ⚠️ 警告：这会删除所有数据
+docker-compose down -v
+docker rmi agentstudio:latest
+docker build -t agentstudio:latest .
+docker-compose up -d
+```
+
+### 4. 如何查看应用日志？
+
+```bash
+# 实时查看日志
+docker-compose logs -f
+
+# 查看最近 100 行日志
+docker-compose logs --tail=100
+
+# 查看特定时间的日志
+docker-compose logs --since 30m
+```
+
+## 九、生产环境部署建议
+
+1. **使用版本标签**：
+   ```bash
+   docker build -t agentstudio:v1.0.0 .
+   docker tag agentstudio:v1.0.0 agentstudio:latest
+   ```
+
+2. **定期备份数据**：
+   ```bash
+   # 添加到 crontab
+   0 2 * * * /path/to/backup-script.sh
+   ```
+
+3. **配置资源限制**：
+   ```yaml
+   deploy:
+     resources:
+       limits:
+         cpus: '2'
+         memory: 2G
+   ```
+
+4. **启用日志轮转**：
+   ```yaml
+   logging:
+     driver: "json-file"
+     options:
+       max-size: "10m"
+       max-file: "3"
+   ```
+
+## 十、总结
+
+✅ **数据持久化已配置好**：使用 Docker Volume，数据安全可靠
+✅ **前后端一体化**：单个容器，简单易用
+✅ **一键启动**：`docker-compose up -d`
+✅ **数据可备份**：简单的备份恢复机制
+
+开始使用吧！🚀

package/README.md

@@ -1,8 +1,38 @@
 # AgentStudio
 
-AI-powered agent workspace with Claude integration.
+<div align="center">
 
-## Quick Start
+![AgentStudio](./frontend/public/cc-studio.png)
+
+**Agent for Work — Your Local Agent Workspace**
+
+Powered by Claude Agent SDK
+
+[![GPL v3 License](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://opensource.org/licenses/GPL-3.0)
+[![GitHub stars](https://img.shields.io/github/stars/okguitar/agentstudio.svg)](https://github.com/okguitar/agentstudio/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/okguitar/agentstudio.svg)](https://github.com/okguitar/agentstudio/issues)
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+</div>
+
+---
+
+## 📖 Overview
+
+AgentStudio is a **local Agent workspace** running on your computer — a true personal AI assistant. Your data stays completely private, secure, and under your control. It supports scheduled task automation and multi-agent collaboration.
+
+Built on Claude Agent SDK, AgentStudio transforms the CLI experience into a friendly Web interface, making AI agents accessible to everyone, not just developers.
+
+<div align="center">
+
+![Chat Interface](./frontend/public/screenshot-chat.png)
+
+</div>
+
+## 🚀 Quick Start
+
+Install and run with npm:
 
 ```bash
 # Install globally
@@ -10,39 +40,161 @@ npm install -g agentstudio
 
 # Start the server
 agentstudio start
+```
+
+Then open [http://localhost:4936](http://localhost:4936) in your browser.
 
-# Or specify a port
-agentstudio start --port 8080
+**More commands:**
+
+```bash
+agentstudio start --port 8080  # Custom port
+agentstudio install            # Install as system service (auto-start)
+agentstudio upgrade            # Upgrade to latest version
+agentstudio doctor             # Check system status
+agentstudio --help             # Show all commands
 ```
 
-## Commands
+## ✨ Core Features
+
+### 🖥️ Local Agent Workspace
+
+- **Runs on your computer** — A true local workspace
+- **Data stays private** — Nothing uploaded to the cloud
+- **Full control** — Files, code, and conversations remain in your hands
+
+### 🌐 Web-Based Experience
+
+- **Say goodbye to CLI** — Embrace a friendly Web interface
+- **Visual tool execution** — See what your Agent is doing in real-time
+- **Built-in file browser** — View project files alongside conversations
+
+### 🧰 Claude Agent SDK Full Stack
+
+Everything from Claude Code, and more:
+
+| Feature | Description |
+|---------|-------------|
+| **MCP** | One-click import of Claude Code MCP configurations |
+| **Skills** | Reusable code skill library |
+| **Commands** | Custom slash commands for quick actions |
+| **Plugin Ecosystem** | Install agents, commands, skills, and MCP servers |
+| **Project Memory** | Each project has independent memory (CLAUDE.md) |
+| **Subagents** | Configure nested AI agents with specific capabilities |
+| **Multi-Model** | Claude, GLM, DeepSeek, Kimi K2, MiniMax, and more |
+
+### ⏰ Scheduled Tasks
+
+Let your Agent work automatically on a schedule — true AI work automation!
+
+**Example scenarios:**
+- 📊 **Daily progress reports** — Generate project updates every morning at 9am
+- 🔍 **Automated code review** — Check repositories every 2 hours
+- 📝 **Weekly meeting notes** — Summarize and archive every Friday
+- 📈 **Monthly analytics** — Generate business data reports on the 1st
+
+### 🔗 A2A Protocol (Agent-to-Agent)
+
+Build a collaborative network of intelligent agents:
+
+- **Secretary Agent dispatch** — One Agent receives tasks and delegates to project-specific Agents
+- **Local ↔ Remote collaboration** — Agents on your computer communicate with Agents on remote dev machines
+- **Mobile access** — Interact with local Agents from mobile messaging apps (beta)
 
-- `agentstudio start` - Start the full server (frontend + backend)
-- `agentstudio start --api-only` - Start API server only (for CDN frontend mode)
-- `agentstudio start --port <port>` - Specify server port (default: 4936)
-- `agentstudio upgrade` - Upgrade to the latest version
-- `agentstudio --version` - Show version
-- `agentstudio --help` - Show help
+### 🎨 Custom Agents
 
-## Environment Variables
+Create your own specialized Agents without writing code:
 
-Create a `.env` file in your working directory:
+- **PPT creation Agent**
+- **Secretary Agent**
+- **Document writing Agent**
+- **Code review Agent**
+- And any other workflow you need!
 
-```env
-# Required: AI API Key
-ANTHROPIC_API_KEY=your_api_key_here
+## 📊 AgentStudio vs Claude Code
 
-# Optional: Custom port
-PORT=4936
+| Feature | AgentStudio | Claude Code |
+|---------|-------------|-------------|
+| Interface | Web UI | Command Line (CLI) |
+| Target Users | Everyone | Primarily developers |
+| Tool Display | Visual rendering | Plain text |
+| File Browser | ✅ | ❌ |
+| Agent Customization | ✅ | ❌ |
+| Scheduled Tasks | ✅ | ❌ |
+| A2A Protocol | ✅ | ❌ |
+| Mobile Access | Beta | ❌ |
 
-# Optional: Data directory
-DATA_DIR=~/.agentstudio
+Same Claude Agent SDK, friendlier experience.
+
+## 📦 Alternative Installation
+
+### Docker
+
+```bash
+docker build -t agentstudio:latest .
+docker-compose up -d
+```
+
+See [DOCKER.md](DOCKER.md) for details.
+
+### One-Click Install
+
+**macOS/Linux:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/okguitar/agentstudio/main/scripts/install-macos.sh | bash
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://raw.githubusercontent.com/okguitar/agentstudio/main/scripts/windows-install.ps1 | iex
+```
+
+### Development Setup
+
+```bash
+git clone https://github.com/okguitar/agentstudio.git
+cd agentstudio
+pnpm install
+cp backend/.env.example backend/.env
+# Edit backend/.env with your API keys
+pnpm run dev
+```
+
+## 🧪 Development
+
+```bash
+pnpm run dev          # Start development servers
+pnpm run test         # Run tests
+pnpm run type-check   # Type checking
+pnpm run lint         # Linting
+pnpm run build        # Production build
 ```
 
-## Documentation
+## 📦 Tech Stack
+
+**Frontend:** React 19, TypeScript, Vite, TailwindCSS, Zustand, React Query
+
+**Backend:** Node.js, Express, TypeScript, Claude Agent SDK, JWT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+GPL v3 License — see [LICENSE](LICENSE) for details.
+
+## 📮 Support
+
+- 🐛 [Report Issues](https://github.com/okguitar/agentstudio/issues)
+- 💬 [Discussions](https://github.com/okguitar/agentstudio/discussions)
+- 📧 Email: okguitar@gmail.com
+
+---
 
-For full documentation, visit: https://github.com/okguitar/agentstudio
+<div align="center">
 
-## License
+Made with ❤️ by the AgentStudio Team
 
-MIT
+</div>

package/README.zh-CN.md

@@ -0,0 +1,200 @@
+# AgentStudio
+
+<div align="center">
+
+![AgentStudio](./frontend/public/cc-studio.png)
+
+**Agent for Work — 本地的 Agent 工作台**
+
+由 Claude Agent SDK 强力驱动
+
+[![GPL v3 License](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![GitHub stars](https://img.shields.io/github/stars/okguitar/agentstudio.svg)](https://github.com/okguitar/agentstudio/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/okguitar/agentstudio.svg)](https://github.com/okguitar/agentstudio/issues)
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+</div>
+
+---
+
+## 📖 项目简介
+
+AgentStudio 是一个运行在你电脑上的**本地 Agent 工作台** —— 真正意义的私人 AI 助理。你的数据完全私有，安全可控，支持定时任务自动化和多 Agent 协作。
+
+基于 Claude Agent SDK 构建，AgentStudio 将命令行体验转化为友好的 Web 界面，让 AI Agent 不再是开发者的专属，而是每个人都能使用的工作伙伴。
+
+<div align="center">
+
+![聊天界面](./frontend/public/screenshot-chat.png)
+
+</div>
+
+## 🚀 快速开始
+
+使用 npm 安装并运行：
+
+```bash
+# 全局安装
+npm install -g agentstudio
+
+# 启动服务
+agentstudio start
+```
+
+然后在浏览器中打开 [http://localhost:4936](http://localhost:4936) 即可。
+
+**更多命令：**
+
+```bash
+agentstudio start --port 8080  # 自定义端口
+agentstudio install            # 安装为系统服务（开机自启）
+agentstudio upgrade            # 升级到最新版本
+agentstudio doctor             # 检查系统状态
+agentstudio --help             # 显示所有命令
+```
+
+## ✨ 核心特性
+
+### 🖥️ 本地的 Agent 工作台
+
+- **运行在你的电脑上** —— 真正意义的本地工作台
+- **数据完全私有** —— 不上传云端
+- **完全掌控** —— 文件、代码、对话记录都在你的掌控之中
+
+### 🌐 Web 版交互体验
+
+- **告别命令行** —— 拥抱友好的 Web 界面
+- **工具调用可视化** —— 实时看到 Agent 在做什么
+- **内置文件浏览器** —— 对话同时查看项目文件
+
+### 🧰 Claude Agent SDK 全家桶
+
+Claude Code 的所有能力，以及更多：
+
+| 能力 | 说明 |
+|------|------|
+| **MCP** | 一键导入 Claude Code 的 MCP 配置 |
+| **技能系统** | 可复用的代码技能库 |
+| **自定义命令** | 自定义斜杠命令，快速执行操作 |
+| **插件生态** | 安装智能体、命令、技能和 MCP 服务器 |
+| **项目记忆** | 每个项目独立的记忆（CLAUDE.md） |
+| **子 Agent** | 配置嵌套的 AI 智能体 |
+| **多模型支持** | Claude、GLM、DeepSeek、Kimi K2、MiniMax 等 |
+
+### ⏰ 定时任务调度
+
+让 Agent 按计划自动执行 —— 真正实现 AI 工作自动化！
+
+**典型应用场景：**
+- 📊 **每日进度日报** —— 每天早上 9 点，自动生成项目进度日报
+- 🔍 **代码自动审查** —— 每 2 小时检查代码仓库，自动提交审查意见
+- 📝 **周会纪要整理** —— 每周五自动整理本周会议纪要并归档
+- 📈 **月度数据分析** —— 每月 1 号自动生成业务数据分析报告
+
+### 🔗 A2A 协议（Agent 间通信）
+
+让多个 Agent 形成协同工作的网络：
+
+- **秘书 Agent 调度** —— 一个秘书 Agent 统一接收任务，自动调度其他项目 Agent 执行具体工作
+- **本地 ↔ 远程协作** —— 本地电脑与远程开发机上的 Agent 互相通讯，协同完成任务
+- **移动端随时访问** —— 通过移动通讯端与本地 Agent 交互，随时随地工作（内测中）
+
+### 🎨 自定义 Agent
+
+无需编写代码，通过界面配置即可定制专属 Agent：
+
+- **PPT 制作 Agent**
+- **秘书 Agent**
+- **文档写作 Agent**
+- **代码审查 Agent**
+- 以及任何你需要的工作流！
+
+## 📊 AgentStudio vs Claude Code
+
+| 对比维度 | AgentStudio | Claude Code |
+|---------|-------------|-------------|
+| 交互形态 | Web 界面 | 命令行 (CLI) |
+| 目标用户 | 所有人 | 主要开发者 |
+| 工具展示 | 可视化呈现 | 纯文本 |
+| 文件浏览器 | ✅ | ❌ |
+| Agent 定制 | ✅ | ❌ |
+| 定时任务 | ✅ | ❌ |
+| A2A 协议 | ✅ | ❌ |
+| 移动端访问 | 内测中 | ❌ |
+
+同样的 Claude Agent SDK，更友好的使用体验。
+
+## 📦 其他安装方式
+
+### Docker 部署
+
+```bash
+docker build -t agentstudio:latest .
+docker-compose up -d
+```
+
+详见 [DOCKER.md](DOCKER.md)。
+
+### 一键安装
+
+**macOS/Linux：**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/okguitar/agentstudio/main/scripts/install-macos.sh | bash
+```
+
+**Windows（PowerShell）：**
+
+```powershell
+irm https://raw.githubusercontent.com/okguitar/agentstudio/main/scripts/windows-install.ps1 | iex
+```
+
+### 开发环境搭建
+
+```bash
+git clone https://github.com/okguitar/agentstudio.git
+cd agentstudio
+pnpm install
+cp backend/.env.example backend/.env
+# 编辑 backend/.env 添加你的 API 密钥
+pnpm run dev
+```
+
+## 🧪 开发
+
+```bash
+pnpm run dev          # 启动开发服务器
+pnpm run test         # 运行测试
+pnpm run type-check   # 类型检查
+pnpm run lint         # 代码检查
+pnpm run build        # 生产构建
+```
+
+## 📦 技术栈
+
+**前端：** React 19、TypeScript、Vite、TailwindCSS、Zustand、React Query
+
+**后端：** Node.js、Express、TypeScript、Claude Agent SDK、JWT
+
+## 🤝 贡献
+
+欢迎贡献！请随时提交 Pull Request。
+
+## 📄 许可证
+
+GPL v3 许可证 —— 详见 [LICENSE](LICENSE)。
+
+## 📮 支持
+
+- 🐛 [报告问题](https://github.com/okguitar/agentstudio/issues)
+- 💬 [讨论区](https://github.com/okguitar/agentstudio/discussions)
+- 📧 邮箱：okguitar@gmail.com
+
+---
+
+<div align="center">
+
+Made with ❤️ by the AgentStudio Team
+
+</div>