person

# ZeptoClaw 企业级 Web UI 开发指南

> 本文档提供阶段性开发的详细指导，每个阶段都可以作为独立的开发任务。

## 项目概述

基于 zeptoclaw 开源项目进行二次开发，打造企业级个人 AI 助手 Web UI。

**核心特性：**
- React 19+ TypeScript 前端
- 多模型提供商配置（GPT、DeepSeek、Kimi、GLM）
- Web 对话界面（支持流式响应）
- Skills 热插拔管理
- 多租户数据隔离
- 简单认证（默认 admin 账号）

**技术栈：**
- 后端：Rust + Axum + WebSocket
- 前端：React 19 + TypeScript + Vite + Tailwind CSS
- 认证：JWT + bcrypt
- 数据存储：文件系统（JSON）

---

## 开发原则

1. **最小侵入性**：95% 扩展，5% 修改现有代码
2. **模块化设计**：新功能在独立模块中实现
3. **向后兼容**：保持与上游 zeptoclaw 的兼容性
4. **测试驱动**：每个阶段完成后运行测试
5. **渐进式交付**：每个阶段都可以独立验证

---

## 阶段 0：准备工作（开始前必读）

### 📋 Prompt 模板

```
我正在基于 zeptoclaw 项目开发企业级 Web UI。

项目背景：
- 这是阶段 0 的准备工作
- 需要创建 GitHub Issue 并设置开发环境
- 参考文档：ENTERPRISE_UI_DEVELOPMENT_GUIDE.md

请帮我：
1. 检查当前 zeptoclaw 项目的开放 Issue
2. 为企业级 Web UI 功能创建新的 GitHub Issue
3. 验证开发环境（Rust、Node.js、cargo、npm）
4. 确认 panel feature 是否已启用
5. 运行现有测试确保基线正常

遵循 AGENTS.md 中的规范。
```

### ✅ 验收标准

- [ ] GitHub Issue 已创建（标签：feat, area:api, P1）
- [ ] 开发环境验证通过
- [ ] `cargo test` 全部通过
- [ ] `cargo clippy -- -D warnings` 无警告
- [ ] `cargo fmt -- --check` 格式正确

### 📝 输出物

- GitHub Issue URL
- 环境验证报告

---

## 阶段 1：用户上下文隔离层（后端基础）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 1：用户上下文隔离层。

任务目标：
实现多租户数据隔离的核心基础设施，确保不同用户的数据完全隔离。

具体要求：
1. 创建 src/api/user_context.rs 文件
2. 实现 UserContext 结构体，包含：
   - user_id: String
   - config_dir: PathBuf (.zeptoclaw/users/{user_id}/)
   - session_dir: PathBuf
   - skills_dir: PathBuf
3. 实现 UserContextManager，提供：
   - get_or_create_context(user_id) -> UserContext
   - ensure_user_directories(user_id) -> Result<()>
   - validate_user_ownership(user_id, resource_path) -> bool
4. 在 src/config/types.rs 中添加用户配置字段：
   - users_base_dir: PathBuf (默认 ~/.zeptoclaw/users)
   - enable_multi_tenant: bool (默认 true)
5. 更新 src/api/mod.rs 导出新模块

技术要求：
- 使用 Arc<RwLock<HashMap<String, UserContext>>> 缓存用户上下文
- 目录创建使用 tokio::fs::create_dir_all
- 路径验证防止目录遍历攻击
- 添加完整的单元测试（至少 5 个测试用例）

遵循 AGENTS.md 规范：
- 不使用 unwrap()，使用 ? 或 Result
- 添加 tracing 日志
- 运行 cargo fmt 和 cargo clippy
```

### ✅ 验收标准

- [ ] src/api/user_context.rs 创建完成
- [ ] UserContext 和 UserContextManager 实现
- [ ] 配置字段添加到 src/config/types.rs
- [ ] 单元测试覆盖率 > 80%
- [ ] cargo test 通过
- [ ] cargo clippy 无警告
- [ ] 目录隔离验证通过

### 📝 输出物

- src/api/user_context.rs
- 更新的 src/config/types.rs
- 测试报告

### 🔍 验证命令

```bash
cargo test user_context
cargo clippy --package zeptoclaw --lib -- -D warnings
```

---

## 阶段 2：Provider 配置 API（后端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 2：Provider 配置 API。

任务目标：
实现用户级别的 LLM Provider 配置管理 REST API。

具体要求：
1. 创建 src/api/routes/providers.rs 文件
2. 实现以下 API 端点：
   - GET /api/providers - 列出所有支持的 providers
   - GET /api/providers/configured - 获取当前用户已配置的 providers
   - POST /api/providers/{name}/configure - 配置 provider API key
   - PUT /api/providers/{name}/update - 更新 provider 配置
   - DELETE /api/providers/{name} - 删除 provider 配置
   - GET /api/providers/{name}/status - 检查 provider 状态

3. 数据结构：
   - ProviderInfo { name, display_name, supported_models, configured }
   - ProviderConfig { api_key, model, api_base?, max_tokens?, temperature? }
   - ConfigureRequest { api_key, model?, api_base? }

4. 功能实现：
   - API key 使用 AES-256 加密存储（复用 src/security/encryption.rs）
   - 配置保存到 .zeptoclaw/users/{user_id}/providers.json
   - 支持的 providers: openai, anthropic, deepseek, moonshot, zhipu
   - API key 格式验证（正则表达式）
   - 配置更新后触发 EventBus 事件

5. 在 src/api/server.rs 中注册路由

技术要求：
- 使用 axum::extract::State 获取 AppState
- 使用 axum::extract::Path 获取路径参数
- 使用 axum::Json 处理 JSON 请求/响应
- 错误处理返回标准 JSON 格式 { error: string, code: string }
- 添加请求日志（tracing::info）
- 编写集成测试

遵循 AGENTS.md 规范。
```

### ✅ 验收标准

- [ ] src/api/routes/providers.rs 创建完成
- [ ] 6 个 API 端点实现
- [ ] API key 加密存储
- [ ] 配置文件持久化
- [ ] 路由注册到 server.rs
- [ ] 集成测试通过
- [ ] API 文档注释完整

### 📝 输出物

- src/api/routes/providers.rs
- 更新的 src/api/server.rs
- 测试用例

### 🔍 验证命令

```bash
cargo test routes::providers
cargo run --features panel -- panel &
curl -H "Authorization: Bearer test-token" http://localhost:9091/api/providers
```

---

## 阶段 3：对话 API（后端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 3：对话 API。

任务目标：
实现 Web 对话接口，支持流式响应和会话管理。

具体要求：
1. 创建 src/api/routes/chat.rs 文件
2. 实现以下 API 端点：
   - POST /api/chat/send - 发送消息（支持流式和非流式）
   - GET /api/chat/conversations - 获取用户的对话列表
   - GET /api/chat/conversations/{id} - 获取对话详情
   - POST /api/chat/conversations/new - 创建新对话
   - DELETE /api/chat/conversations/{id} - 删除对话
   - PUT /api/chat/conversations/{id}/model - 切换模型

3. 数据结构：
   - SendMessageRequest { conversation_id?, message, model?, stream? }
   - SendMessageResponse { conversation_id, message_id, content, done }
   - Conversation { id, title, model, created_at, updated_at, message_count }
   - Message { id, role, content, timestamp, tool_calls? }

4. 流式响应实现：
   - 使用 Server-Sent Events (SSE)
   - 返回 Content-Type: text/event-stream
   - 每个 token 作为一个 event 发送
   - 格式：data: {"type":"token","content":"..."}\n\n
   - 结束时发送：data: {"type":"done"}\n\n

5. 会话管理：
   - 复用现有的 SessionManager (src/session/mod.rs)
   - 每个用户的会话隔离存储
   - 自动生成对话标题（基于首条消息）
   - 支持对话历史持久化

6. Agent 集成：
   - 使用 src/cli/common.rs 中的 create_agent() 创建 agent
   - 根据用户配置的 provider 初始化 LLMProvider
   - 支持工具调用（tool_calls）
   - 错误处理和超时控制

技术要求：
- 流式响应使用 axum::response::sse::Event
- 使用 tokio::sync::mpsc 传递流式数据
- 添加请求超时（300 秒）
- 并发控制（每用户最多 3 个并发请求）
- 完整的错误处理和日志

遵循 AGENTS.md 规范。
```

### ✅ 验收标准

- [ ] src/api/routes/chat.rs 创建完成
- [ ] 6 个 API 端点实现
- [ ] SSE 流式响应工作正常
- [ ] 会话隔离验证通过
- [ ] Agent 集成测试通过
- [ ] 并发控制生效
- [ ] 错误处理完善

### 📝 输出物

- src/api/routes/chat.rs
- 更新的 src/api/server.rs
- 集成测试用例

### 🔍 验证命令

```bash
cargo test routes::chat
# 测试流式响应
curl -N -H "Authorization: Bearer test-token" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello","stream":true}' \
  http://localhost:9091/api/chat/send
```

---

## 阶段 4：Skills 管理 API（后端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 4：Skills 管理 API。

任务目标：
实现用户级别的 Skills 热插拔管理 API。

具体要求：
1. 创建 src/api/routes/skills.rs 文件
2. 实现以下 API 端点：
   - GET /api/skills - 列出所有可用的 skills
   - GET /api/skills/enabled - 获取当前用户已启用的 skills
   - POST /api/skills/{name}/enable - 启用 skill
   - POST /api/skills/{name}/disable - 禁用 skill
   - GET /api/skills/{name} - 获取 skill 详情
   - PUT /api/skills/{name}/config - 更新 skill 配置（环境变量）

3. 数据结构：
   - SkillInfo { name, description, version, enabled, required_env_vars }
   - SkillConfig { env_vars: HashMap<String, String> }
   - EnableSkillRequest { env_vars?: HashMap<String, String> }

4. 功能实现：
   - 复用现有的 skills 模块 (src/skills/)
   - 从 workspace skills 目录发现 skills
   - 用户级别的 skills 启用状态存储
   - 配置保存到 .zeptoclaw/users/{user_id}/skills.json
   - 支持热加载（不重启进程）
   - 环境变量验证和加密存储

5. Skills 状态管理：
   - 使用 Arc<RwLock<HashMap<String, SkillRegistry>>> 缓存
   - 每个用户独立的 skill 注册表
   - 启用/禁用时触发 EventBus 事件
   - 失败时回滚状态

6. 在 src/api/server.rs 中注册路由

技术要求：
- 集成现有的 SkillLoader (src/skills/loader.rs)
- 使用 SkillRegistry (src/skills/registry.rs)
- 环境变量加密存储（复用 encryption.rs）
- 添加 skill 兼容性检查
- 完整的错误处理（skill 加载失败、缺少环境变量等）

遵循 AGENTS.md 规范。
```

### ✅ 验收标准

- [ ] src/api/routes/skills.rs 创建完成
- [ ] 6 个 API 端点实现
- [ ] Skills 发现功能正常
- [ ] 热加载验证通过
- [ ] 用户隔离验证通过
- [ ] 环境变量加密存储
- [ ] 错误处理完善

### 📝 输出物

- src/api/routes/skills.rs
- 更新的 src/api/server.rs
- 测试用例

### 🔍 验证命令

```bash
cargo test routes::skills
curl -H "Authorization: Bearer test-token" \
  http://localhost:9091/api/skills
curl -X POST -H "Authorization: Bearer test-token" \
  -H "Content-Type: application/json" \
  -d '{"env_vars":{"API_KEY":"test"}}' \
  http://localhost:9091/api/skills/github/enable
```

---

## 阶段 5：用户管理 API（后端，可选）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 5：用户管理 API（可选）。

任务目标：
实现基础的用户管理功能，为未来扩展做准备。

具体要求：
1. 创建 src/api/routes/users.rs 文件
2. 实现以下 API 端点：
   - GET /api/users/me - 获取当前用户信息
   - PUT /api/users/me - 更新用户信息
   - PUT /api/users/me/password - 修改密码
   - GET /api/users/me/preferences - 获取用户偏好设置
   - PUT /api/users/me/preferences - 更新用户偏好设置

3. 数据结构：
   - UserInfo { id, username, email?, created_at, last_login }
   - UserPreferences { theme, language, default_model, notifications }
   - UpdatePasswordRequest { old_password, new_password }

4. 功能实现：
   - 用户信息存储在 .zeptoclaw/users/{user_id}/profile.json
   - 偏好设置存储在 .zeptoclaw/users/{user_id}/preferences.json
   - 密码修改需要验证旧密码
   - 新密码使用 bcrypt 哈希（work factor 12）

5. 在 src/api/server.rs 中注册路由

技术要求：
- 复用现有的 bcrypt 依赖
- 添加密码强度验证（最少 8 字符）
- 偏好设置支持默认值
- 完整的单元测试

注意：此阶段为可选，可以先跳过，在前端基础完成后再实现。

遵循 AGENTS.md 规范。
```

### ✅ 验收标准

- [ ] src/api/routes/users.rs 创建完成
- [ ] 5 个 API 端点实现
- [ ] 密码修改功能正常
- [ ] 偏好设置持久化
- [ ] 单元测试通过

### 📝 输出物

- src/api/routes/users.rs
- 更新的 src/api/server.rs
- 测试用例

### 🔍 验证命令

```bash
cargo test routes::users
curl -H "Authorization: Bearer test-token" \
  http://localhost:9091/api/users/me
```

---

## 阶段 6：React 前端项目搭建

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 6：React 前端项目搭建。

任务目标：
创建 React 19 + TypeScript + Vite 前端项目基础架构。

具体要求：
1. 在项目根目录创建 panel-ui/ 目录
2. 使用 Vite 初始化 React + TypeScript 项目：
   npm create vite@latest panel-ui -- --template react-ts

3. 安装依赖：
   - React 19
   - React Router v6
   - Tailwind CSS
   - Axios（HTTP 客户端）
   - Zustand（状态管理）
   - React Markdown（消息渲染）
   - date-fns（日期格式化）

4. 配置 Tailwind CSS：
   - 安装 tailwindcss, postcss, autoprefixer
   - 创建 tailwind.config.js
   - 配置 content 路径
   - 添加自定义主题色

5. 项目结构：
   panel-ui/
   ├── src/
   │   ├── api/           # API 客户端
   │   ├── components/    # 可复用组件
   │   ├── pages/         # 页面组件
   │   ├── hooks/         # 自定义 hooks
   │   ├── stores/        # Zustand stores
   │   ├── types/         # TypeScript 类型
   │   ├── utils/         # 工具函数
   │   ├── App.tsx
   │   ├── main.tsx
   │   └── index.css
   ├── public/
   ├── index.html
   ├── package.json
   ├── tsconfig.json
   ├── vite.config.ts
   └── tailwind.config.js

6. 配置 vite.config.ts：
   - 设置 proxy 代理到后端 API (http://localhost:9091)
   - 配置开发服务器端口 (5173)
   - 配置构建输出目录 (../panel/dist)

7. 创建基础文件：
   - src/api/client.ts - Axios 实例配置
   - src/types/index.ts - 通用类型定义
   - src/utils/storage.ts - localStorage 封装
   - src/App.tsx - 根组件和路由配置

技术要求：
- 使用 TypeScript strict 模式
- 配置 ESLint 和 Prettier
- 添加 .env.example 文件
- 创建 README.md 说明开发流程

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] panel-ui/ 目录创建完成
- [ ] 依赖安装成功
- [ ] Tailwind CSS 配置正确
- [ ] 项目结构符合规范
- [ ] Vite 开发服务器启动正常
- [ ] TypeScript 编译无错误
- [ ] ESLint 检查通过

### 📝 输出物

- panel-ui/ 完整项目结构
- package.json
- vite.config.ts
- tailwind.config.js
- README.md

### 🔍 验证命令

```bash
cd panel-ui
npm install
npm run dev
npm run build
npm run lint
```

---

## 阶段 7：认证和路由（前端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 7：认证和路由。

任务目标：
实现登录认证流程和前端路由保护。

具体要求：
1. 创建认证相关文件：
   - src/stores/authStore.ts - 认证状态管理
   - src/api/auth.ts - 认证 API 调用
   - src/hooks/useAuth.ts - 认证 hook
   - src/components/ProtectedRoute.tsx - 路由保护组件

2. authStore 实现（Zustand）：
   - 状态：token, user, isAuthenticated, isLoading
   - 方法：login(username, password), logout(), checkAuth()
   - 持久化：localStorage 存储 token

3. API 客户端配置（src/api/client.ts）：
   - Axios 拦截器添加 Authorization header
   - 401 响应自动跳转登录
   - 请求/响应日志（开发环境）

4. 创建页面组件：
   - src/pages/Login.tsx - 登录页面
   - src/pages/Dashboard.tsx - 仪表盘（占位）
   - src/pages/NotFound.tsx - 404 页面

5. 路由配置（src/App.tsx）：
   - / - 重定向到 /dashboard 或 /login
   - /login - 登录页面（公开）
   - /dashboard - 仪表盘（受保护）
   - /chat - 对话页面（受保护，占位）
   - /providers - Provider 配置（受保护，占位）
   - /skills - Skills 管理（受保护，占位）
   - * - 404 页面

6. Login 页面设计：
   - 简洁的居中表单
   - 用户名和密码输入框
   - 记住我选项（可选）
   - 登录按钮（loading 状态）
   - 错误提示
   - 使用 Tailwind CSS 样式

技术要求：
- 使用 React Router v6 的 Navigate 组件
- 表单验证（非空检查）
- 错误处理和用户反馈
- 响应式设计
- 无障碍支持（ARIA 标签）

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] 认证 store 实现完成
- [ ] API 客户端拦截器配置
- [ ] 登录页面 UI 完成
- [ ] 路由保护生效
- [ ] Token 持久化正常
- [ ] 401 自动跳转登录
- [ ] 响应式设计验证

### 📝 输出物

- src/stores/authStore.ts
- src/api/auth.ts
- src/pages/Login.tsx
- src/components/ProtectedRoute.tsx
- 更新的 src/App.tsx

### 🔍 验证命令

```bash
cd panel-ui
npm run dev
# 浏览器访问 http://localhost:5173
# 测试登录流程
```

---

## 阶段 8：Provider 配置页面（前端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 8：Provider 配置页面。

任务目标：
实现 LLM Provider 配置管理界面。

具体要求：
1. 创建相关文件：
   - src/api/providers.ts - Provider API 调用
   - src/stores/providerStore.ts - Provider 状态管理
   - src/pages/Providers.tsx - Provider 配置页面
   - src/components/ProviderCard.tsx - Provider 卡片组件
   - src/components/ProviderConfigModal.tsx - 配置弹窗

2. providerStore 实现：
   - 状态：providers, configuredProviders, loading, error
   - 方法：fetchProviders(), configureProvider(), deleteProvider()

3. Providers 页面布局：
   - 页面标题和说明
   - Provider 卡片网格（2-3 列）
   - 每个卡片显示：
     * Provider 名称和图标
     * 配置状态（已配置/未配置）
     * 支持的模型列表
     * 配置/编辑按钮

4. ProviderCard 组件：
   - 卡片样式（Tailwind CSS）
   - 状态指示器（绿色/灰色圆点）
   - 悬停效果
   - 点击打开配置弹窗

5. ProviderConfigModal 组件：
   - 模态对话框（使用 Headless UI 或自定义）
   - 表单字段：
     * API Key（密码输入框）
     * 默认模型（下拉选择）
     * API Base URL（可选，高级选项）
   - 保存和取消按钮
   - 表单验证
   - 加载和错误状态

6. 支持的 Providers：
   - OpenAI (GPT)
   - Anthropic (Claude)
   - DeepSeek
   - Moonshot (Kimi)
   - Zhipu (GLM)

技术要求：
- 使用 React Hook Form 处理表单
- API Key 输入框显示/隐藏切换
- 配置成功后显示 toast 通知
- 错误处理和用户反馈
- 响应式设计
- 加载骨架屏

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] Provider 列表展示正常
- [ ] 配置弹窗功能完整
- [ ] API 调用成功
- [ ] 表单验证生效
- [ ] 错误处理完善
- [ ] 响应式设计验证
- [ ] 用户体验流畅

### 📝 输出物

- src/api/providers.ts
- src/stores/providerStore.ts
- src/pages/Providers.tsx
- src/components/ProviderCard.tsx
- src/components/ProviderConfigModal.tsx

### 🔍 验证命令

```bash
cd panel-ui
npm run dev
# 访问 /providers 页面
# 测试配置流程
```

---

## 阶段 9：对话界面（前端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 9：对话界面。

任务目标：
实现完整的 Web 对话界面，支持流式响应和会话管理。

具体要求：
1. 创建相关文件：
   - src/api/chat.ts - 对话 API 调用（含 SSE）
   - src/stores/chatStore.ts - 对话状态管理
   - src/pages/Chat.tsx - 对话主页面
   - src/components/ConversationList.tsx - 会话列表
   - src/components/MessageList.tsx - 消息列表
   - src/components/MessageInput.tsx - 消息输入框
   - src/components/MessageBubble.tsx - 消息气泡
   - src/components/ModelSelector.tsx - 模型选择器

2. chatStore 实现：
   - 状态：conversations, currentConversation, messages, isStreaming
   - 方法：
     * fetchConversations()
     * createConversation()
     * selectConversation(id)
     * sendMessage(message, stream)
     * deleteConversation(id)

3. Chat 页面布局（三栏）：
   - 左侧：会话列表（可折叠）
   - 中间：消息列表 + 输入框
   - 右侧：设置面板（可选，可折叠）

4. ConversationList 组件：
   - 新建对话按钮
   - 会话列表（滚动）
   - 每个会话显示：标题、最后消息时间、消息数
   - 当前会话高亮
   - 删除按钮（悬停显示）

5. MessageList 组件：
   - 自动滚动到底部
   - 消息分组（按日期）
   - 加载历史消息（分页）
   - 空状态提示

6. MessageBubble 组件：
   - 用户消息（右对齐，蓝色背景）
   - AI 消息（左对齐，灰色背景）
   - Markdown 渲染（react-markdown）
   - 代码高亮（syntax highlighting）
   - 复制按钮
   - 时间戳

7. MessageInput 组件：
   - 多行文本输入框（自动扩展）
   - 发送按钮
   - Shift+Enter 换行，Enter 发送
   - 输入中状态
   - 字符计数（可选）

8. ModelSelector 组件：
   - 下拉选择当前模型
   - 显示已配置的 providers 和模型
   - 切换模型后提示

9. 流式响应处理：
   - 使用 EventSource 或 fetch + ReadableStream
   - 逐 token 更新 UI
   - 打字机效果（可选）
   - 流式错误处理

技术要求：
- 使用 react-markdown 渲染 Markdown
- 使用 prismjs 或 highlight.js 代码高亮
- 虚拟滚动优化长列表（可选）
- 响应式设计（移动端适配）
- 键盘快捷键支持
- 无障碍支持

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] 对话界面布局完成
- [ ] 会话列表功能正常
- [ ] 消息发送和接收正常
- [ ] 流式响应显示正确
- [ ] Markdown 渲染正常
- [ ] 模型切换功能正常
- [ ] 响应式设计验证
- [ ] 用户体验流畅

### 📝 输出物

- src/api/chat.ts
- src/stores/chatStore.ts
- src/pages/Chat.tsx
- 6 个对话相关组件

### 🔍 验证命令

```bash
cd panel-ui
npm run dev
# 访问 /chat 页面
# 测试发送消息和流式响应
```

---

## 阶段 10：Skills 管理页面（前端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 10：Skills 管理页面。

任务目标：
实现 Skills 热插拔管理界面。

具体要求：
1. 创建相关文件：
   - src/api/skills.ts - Skills API 调用
   - src/stores/skillStore.ts - Skills 状态管理
   - src/pages/Skills.tsx - Skills 管理页面
   - src/components/SkillCard.tsx - Skill 卡片组件
   - src/components/SkillDetailModal.tsx - Skill 详情弹窗
   - src/components/SkillConfigModal.tsx - Skill 配置弹窗

2. skillStore 实现：
   - 状态：skills, enabledSkills, loading, error
   - 方法：
     * fetchSkills()
     * fetchEnabledSkills()
     * enableSkill(name, config)
     * disableSkill(name)
     * updateSkillConfig(name, config)

3. Skills 页面布局：
   - 页面标题和说明
   - 筛选器（全部/已启用/未启用）
   - 搜索框
   - Skills 卡片网格（2-3 列）

4. SkillCard 组件：
   - Skill 名称和图标
   - 简短描述
   - 版本号
   - 启用状态开关（toggle）
   - 查看详情按钮
   - 配置按钮（已启用时显示）

5. SkillDetailModal 组件：
   - 模态对话框
   - 显示完整信息：
     * 名称、版本、作者
     * 详细描述
     * 所需环境变量列表
     * 依赖项（如果有）
   - 启用/禁用按钮
   - 关闭按钮

6. SkillConfigModal 组件：
   - 环境变量配置表单
   - 动态生成输入框（基于 required_env_vars）
   - 敏感信息输入框（密码类型）
   - 验证必填字段
   - 保存和取消按钮

7. 功能实现：
   - 启用 skill 时检查环境变量
   - 禁用 skill 时确认对话框
   - 实时更新启用状态
   - 错误处理和用户反馈
   - 加载状态显示

技术要求：
- 使用 React Hook Form 处理配置表单
- Toggle 开关使用 Headless UI Switch
- 搜索和筛选本地实现（前端过滤）
- 响应式设计
- 空状态提示
- 加载骨架屏

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] Skills 列表展示正常
- [ ] 启用/禁用功能正常
- [ ] 配置弹窗功能完整
- [ ] 搜索和筛选生效
- [ ] 错误处理完善
- [ ] 响应式设计验证
- [ ] 用户体验流畅

### 📝 输出物

- src/api/skills.ts
- src/stores/skillStore.ts
- src/pages/Skills.tsx
- 3 个 Skills 相关组件

### 🔍 验证命令

```bash
cd panel-ui
npm run dev
# 访问 /skills 页面
# 测试启用/禁用流程
```

---

## 阶段 11：导航和布局（前端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 11：导航和布局。

任务目标：
实现统一的导航栏和页面布局组件。

具体要求：
1. 创建相关文件：
   - src/components/Layout.tsx - 主布局组件
   - src/components/Sidebar.tsx - 侧边栏导航
   - src/components/Header.tsx - 顶部导航栏
   - src/components/UserMenu.tsx - 用户菜单
   - src/components/Breadcrumb.tsx - 面包屑导航

2. Layout 组件：
   - 全屏布局（flex）
   - 左侧：Sidebar（固定宽度，可折叠）
   - 右侧：Header + 内容区域
   - 响应式：移动端 Sidebar 变为抽屉

3. Sidebar 组件：
   - Logo 和应用名称
   - 导航菜单项：
     * Dashboard（仪表盘）
     * Chat（对话）
     * Providers（模型配置）
     * Skills（技能管理）
     * Settings（设置，可选）
   - 当前路由高亮
   - 图标 + 文字
   - 折叠按钮（仅显示图标）

4. Header 组件：
   - 面包屑导航
   - 搜索框（可选）
   - 通知图标（可选）
   - 用户菜单

5. UserMenu 组件：
   - 用户头像/名称
   - 下拉菜单：
     * 个人设置
     * 退出登录
   - 使用 Headless UI Menu

6. Breadcrumb 组件：
   - 根据当前路由生成面包屑
   - 可点击导航
   - 分隔符

7. 样式设计：
   - 使用 Tailwind CSS
   - 深色/浅色主题支持（可选）
   - 平滑过渡动画
   - 悬停效果

技术要求：
- 使用 React Router 的 useLocation 获取当前路由
- 使用 Headless UI 的 Menu 和 Disclosure
- 响应式设计（移动端适配）
- 无障碍支持（键盘导航）
- 图标使用 Heroicons 或 Lucide React

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] Layout 组件实现完成
- [ ] Sidebar 导航功能正常
- [ ] Header 组件显示正确
- [ ] 用户菜单功能正常
- [ ] 面包屑导航生效
- [ ] 响应式设计验证
- [ ] 主题切换正常（如果实现）

### 📝 输出物

- src/components/Layout.tsx
- src/components/Sidebar.tsx
- src/components/Header.tsx
- src/components/UserMenu.tsx
- src/components/Breadcrumb.tsx

### 🔍 验证命令

```bash
cd panel-ui
npm run dev
# 测试导航和布局
# 测试响应式（调整浏览器窗口）
```

---

## 阶段 12：仪表盘页面（前端）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 12：仪表盘页面。

任务目标：
实现系统概览仪表盘，展示关键指标和快速操作。

具体要求：
1. 创建相关文件：
   - src/api/dashboard.ts - 仪表盘 API 调用
   - src/pages/Dashboard.tsx - 仪表盘页面
   - src/components/StatCard.tsx - 统计卡片组件
   - src/components/RecentConversations.tsx - 最近对话列表
   - src/components/QuickActions.tsx - 快速操作面板

2. Dashboard 页面布局：
   - 欢迎信息（用户名 + 时间）
   - 统计卡片行（4 个卡片）
   - 最近对话列表
   - 快速操作面板
   - 系统状态（可选）

3. 统计卡片（StatCard）：
   - 总对话数
   - 今日消息数
   - 已启用 Skills 数
   - 已配置 Providers 数
   - 图标 + 数字 + 标题
   - 趋势指示器（可选）

4. RecentConversations 组件：
   - 显示最近 5 条对话
   - 每条显示：标题、时间、消息数
   - 点击跳转到对话页面
   - 查看全部按钮

5. QuickActions 组件：
   - 新建对话按钮
   - 配置 Provider 按钮
   - 启用 Skill 按钮
   - 查看文档按钮（可选）

6. 数据获取：
   - 从后端 API 获取统计数据
   - 从 chatStore 获取最近对话
   - 从 providerStore 获取配置状态
   - 从 skillStore 获取启用状态

7. 样式设计：
   - 卡片式布局
   - 网格系统（响应式）
   - 渐变背景（可选）
   - 加载骨架屏

技术要求：
- 使用 SWR 或 React Query 缓存数据（可选）
- 数据刷新机制（手动或自动）
- 错误状态处理
- 空状态提示
- 响应式设计

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] Dashboard 页面布局完成
- [ ] 统计卡片显示正确
- [ ] 最近对话列表正常
- [ ] 快速操作功能正常
- [ ] 数据获取和刷新正常
- [ ] 响应式设计验证
- [ ] 加载和错误状态处理

### 📝 输出物

- src/api/dashboard.ts
- src/pages/Dashboard.tsx
- src/components/StatCard.tsx
- src/components/RecentConversations.tsx
- src/components/QuickActions.tsx

### 🔍 验证命令

```bash
cd panel-ui
npm run dev
# 访问 /dashboard 页面
# 验证数据显示
```

---

## 阶段 13：集成测试和优化

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 13：集成测试和优化。

任务目标：
完成端到端集成测试，优化性能和用户体验。

具体要求：
1. 后端集成测试：
   - 创建 tests/api_integration.rs
   - 测试所有 API 端点
   - 测试用户隔离
   - 测试并发请求
   - 测试错误场景

2. 前端测试：
   - 安装 Vitest 和 Testing Library
   - 创建 src/__tests__/ 目录
   - 单元测试关键组件
   - 集成测试主要流程
   - E2E 测试（可选，使用 Playwright）

3. 性能优化：
   - 前端代码分割（React.lazy）
   - 图片优化和懒加载
   - API 响应缓存
   - 虚拟滚动（长列表）
   - Bundle 大小分析

4. 用户体验优化：
   - 加载状态优化
   - 错误提示优化
   - 空状态设计
   - 骨架屏优化
   - 动画和过渡效果

5. 安全加固：
   - XSS 防护验证
   - CSRF token 验证
   - API rate limiting 测试
   - 输入验证和清理
   - 敏感数据处理审查

6. 文档完善：
   - 更新 README.md
   - 添加 API 文档
   - 添加部署文档
   - 添加开发指南
   - 添加故障排查指南

7. 构建和部署：
   - 配置生产构建
   - 环境变量管理
   - Docker 镜像（可选）
   - CI/CD 配置（可选）

技术要求：
- 测试覆盖率 > 70%
- Lighthouse 性能分数 > 90
- 无 console 错误和警告
- 通过无障碍检查
- 浏览器兼容性测试

遵循 AGENTS.md 规范。
```

### ✅ 验收标准

- [ ] 后端集成测试通过
- [ ] 前端测试覆盖率达标
- [ ] 性能优化完成
- [ ] 用户体验优化完成
- [ ] 安全审查通过
- [ ] 文档完善
- [ ] 生产构建成功

### 📝 输出物

- tests/api_integration.rs
- src/__tests__/ 测试文件
- 优化后的代码
- 完整文档
- 部署配置

### 🔍 验证命令

```bash
# 后端测试
cargo test --test api_integration
cargo clippy -- -D warnings
cargo fmt -- --check

# 前端测试
cd panel-ui
npm run test
npm run build
npm run preview

# 性能分析
npm run build -- --analyze
```

---

## 阶段 14：部署和上线

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 14：部署和上线。

任务目标：
完成生产环境部署配置和上线准备。

具体要求：
1. 生产构建配置：
   - 优化 Rust release 构建
   - 优化前端生产构建
   - 配置环境变量
   - 配置日志级别

2. 部署文档：
   - 创建 docs/DEPLOYMENT.md
   - 系统要求说明
   - 安装步骤
   - 配置说明
   - 启动和停止命令
   - 故障排查

3. Docker 部署（可选）：
   - 创建 Dockerfile.enterprise
   - 多阶段构建
   - Docker Compose 配置
   - 数据卷配置
   - 网络配置

4. 系统服务配置：
   - systemd service 文件
   - 自动启动配置
   - 日志轮转配置
   - 监控配置（可选）

5. 备份和恢复：
   - 数据备份脚本
   - 配置备份
   - 恢复流程文档

6. 安全配置：
   - HTTPS 配置说明
   - 防火墙规则
   - 反向代理配置（Nginx/Caddy）
   - 安全最佳实践

7. 监控和日志：
   - 日志收集配置
   - 性能监控（可选）
   - 告警配置（可选）
   - 健康检查端点

8. 用户手册：
   - 创建 docs/USER_GUIDE.md
   - 功能说明
   - 使用教程
   - 常见问题
   - 截图和示例

技术要求：
- 生产环境测试
- 性能压测
- 安全扫描
- 文档完整性检查

遵循 AGENTS.md 规范。
```

### ✅ 验收标准

- [ ] 生产构建配置完成
- [ ] 部署文档完整
- [ ] Docker 配置正常（如果实现）
- [ ] 系统服务配置正确
- [ ] 备份恢复流程验证
- [ ] 安全配置完成
- [ ] 用户手册完整
- [ ] 生产环境测试通过

### 📝 输出物

- docs/DEPLOYMENT.md
- docs/USER_GUIDE.md
- Dockerfile.enterprise（可选）
- docker-compose.yml（可选）
- systemd service 文件
- 部署脚本

### 🔍 验证命令

```bash
# 生产构建
cargo build --release --features panel
cd panel-ui && npm run build

# Docker 构建（如果实现）
docker build -f Dockerfile.enterprise -t zeptoclaw-enterprise .
docker-compose up -d

# 健康检查
curl http://localhost:9091/api/health
```

---

## 附录 A：技术栈详细说明

### 后端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Rust | 2021 edition | 核心语言 |
| Axum | 0.8+ | Web 框架 |
| Tokio | 1.35+ | 异步运行时 |
| Tower-HTTP | 0.6+ | HTTP 中间件 |
| Serde | 1.0+ | 序列化/反序列化 |
| JWT | 9+ | Token 认证 |
| bcrypt | 0.17+ | 密码哈希 |
| chacha20poly1305 | 0.10+ | 数据加密 |

### 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| React | 19+ | UI 框架 |
| TypeScript | 5+ | 类型系统 |
| Vite | 5+ | 构建工具 |
| React Router | 6+ | 路由管理 |
| Zustand | 4+ | 状态管理 |
| Tailwind CSS | 3+ | 样式框架 |
| Axios | 1+ | HTTP 客户端 |
| React Markdown | 9+ | Markdown 渲染 |
| Headless UI | 2+ | 无样式组件 |

---

## 附录 B：API 端点清单

### 认证 API
- `POST /api/auth/login` - 用户登录
- `GET /api/csrf-token` - 获取 CSRF token

### Provider API
- `GET /api/providers` - 列出所有 providers
- `GET /api/providers/configured` - 获取已配置的 providers
- `POST /api/providers/{name}/configure` - 配置 provider
- `PUT /api/providers/{name}/update` - 更新配置
- `DELETE /api/providers/{name}` - 删除配置
- `GET /api/providers/{name}/status` - 检查状态

### 对话 API
- `POST /api/chat/send` - 发送消息
- `GET /api/chat/conversations` - 获取对话列表
- `GET /api/chat/conversations/{id}` - 获取对话详情
- `POST /api/chat/conversations/new` - 创建新对话
- `DELETE /api/chat/conversations/{id}` - 删除对话
- `PUT /api/chat/conversations/{id}/model` - 切换模型

### Skills API
- `GET /api/skills` - 列出所有 skills
- `GET /api/skills/enabled` - 获取已启用的 skills
- `POST /api/skills/{name}/enable` - 启用 skill
- `POST /api/skills/{name}/disable` - 禁用 skill
- `GET /api/skills/{name}` - 获取 skill 详情
- `PUT /api/skills/{name}/config` - 更新配置

### 用户 API（可选）
- `GET /api/users/me` - 获取当前用户
- `PUT /api/users/me` - 更新用户信息
- `PUT /api/users/me/password` - 修改密码
- `GET /api/users/me/preferences` - 获取偏好设置
- `PUT /api/users/me/preferences` - 更新偏好设置

### 系统 API
- `GET /api/health` - 健康检查
- `GET /api/metrics` - 系统指标

---

## 附录 C：数据模型定义

### 后端数据模型（Rust）

```rust
// User Context
pub struct UserContext {
    pub user_id: String,
    pub config_dir: PathBuf,
    pub session_dir: PathBuf,
    pub skills_dir: PathBuf,
}

// Provider Configuration
pub struct ProviderConfig {
    pub api_key: String,  // 加密存储
    pub model: Option<String>,
    pub api_base: Option<String>,
    pub max_tokens: Option<u32>,
    pub temperature: Option<f32>,
}

// Conversation
pub struct Conversation {
    pub id: String,
    pub user_id: String,
    pub title: String,
    pub model: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub message_count: usize,
}

// Message
pub struct Message {
    pub id: String,
    pub conversation_id: String,
    pub role: MessageRole,  // User | Assistant
    pub content: String,
    pub timestamp: DateTime<Utc>,
    pub tool_calls: Option<Vec<ToolCall>>,
}

// Skill Info
pub struct SkillInfo {
    pub name: String,
    pub description: String,
    pub version: String,
    pub enabled: bool,
    pub required_env_vars: Vec<String>,
}
```

### 前端数据模型（TypeScript）

```typescript
// Auth
interface User {
  id: string;
  username: string;
  email?: string;
}

interface AuthState {
  token: string | null;
  user: User | null;
  isAuthenticated: boolean;
}

// Provider
interface ProviderInfo {
  name: string;
  displayName: string;
  supportedModels: string[];
  configured: boolean;
}

interface ProviderConfig {
  apiKey: string;
  model?: string;
  apiBase?: string;
}

// Chat
interface Conversation {
  id: string;
  title: string;
  model: string;
  createdAt: string;
  updatedAt: string;
  messageCount: number;
}

interface Message {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: string;
  toolCalls?: ToolCall[];
}

interface SendMessageRequest {
  conversationId?: string;
  message: string;
  model?: string;
  stream?: boolean;
}

// Skill
interface SkillInfo {
  name: string;
  description: string;
  version: string;
  enabled: boolean;
  requiredEnvVars: string[];
}

interface SkillConfig {
  envVars: Record<string, string>;
}
```

---

## 附录 D：目录结构规划

### 完整项目结构

```
zeptoclaw/
├── src/
│   ├── api/
│   │   ├── routes/
│   │   │   ├── auth.rs
│   │   │   ├── providers.rs      # 新增
│   │   │   ├── chat.rs            # 新增
│   │   │   ├── skills.rs          # 新增
│   │   │   ├── users.rs           # 新增（可选）
│   │   │   ├── channels.rs
│   │   │   ├── cron.rs
│   │   │   ├── health.rs
│   │   │   ├── metrics.rs
│   │   │   ├── routines.rs
│   │   │   ├── sessions.rs
│   │   │   ├── tasks.rs
│   │   │   └── ws.rs
│   │   ├── auth.rs
│   │   ├── config.rs
│   │   ├── events.rs
│   │   ├── middleware.rs
│   │   ├── mod.rs
│   │   ├── server.rs
│   │   ├── tasks.rs
│   │   └── user_context.rs        # 新增
│   ├── [其他现有模块...]
│   └── main.rs
├── panel-ui/                       # 新增前端项目
│   ├── src/
│   │   ├── api/
│   │   │   ├── client.ts
│   │   │   ├── auth.ts
│   │   │   ├── providers.ts
│   │   │   ├── chat.ts
│   │   │   ├── skills.ts
│   │   │   ├── users.ts
│   │   │   └── dashboard.ts
│   │   ├── components/
│   │   │   ├── Layout.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   ├── Header.tsx
│   │   │   ├── UserMenu.tsx
│   │   │   ├── Breadcrumb.tsx
│   │   │   ├── ProtectedRoute.tsx
│   │   │   ├── ProviderCard.tsx
│   │   │   ├── ProviderConfigModal.tsx
│   │   │   ├── ConversationList.tsx
│   │   │   ├── MessageList.tsx
│   │   │   ├── MessageBubble.tsx
│   │   │   ├── MessageInput.tsx
│   │   │   ├── ModelSelector.tsx
│   │   │   ├── SkillCard.tsx
│   │   │   ├── SkillDetailModal.tsx
│   │   │   ├── SkillConfigModal.tsx
│   │   │   ├── StatCard.tsx
│   │   │   ├── RecentConversations.tsx
│   │   │   └── QuickActions.tsx
│   │   ├── hooks/
│   │   │   ├── useAuth.ts
│   │   │   └── useWebSocket.ts
│   │   ├── pages/
│   │   │   ├── Login.tsx
│   │   │   ├── Dashboard.tsx
│   │   │   ├── Chat.tsx
│   │   │   ├── Providers.tsx
│   │   │   ├── Skills.tsx
│   │   │   └── NotFound.tsx
│   │   ├── stores/
│   │   │   ├── authStore.ts
│   │   │   ├── providerStore.ts
│   │   │   ├── chatStore.ts
│   │   │   └── skillStore.ts
│   │   ├── types/
│   │   │   └── index.ts
│   │   ├── utils/
│   │   │   ├── storage.ts
│   │   │   └── format.ts
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   └── index.css
│   ├── public/
│   ├── index.html
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   ├── postcss.config.js
│   └── README.md
├── tests/
│   ├── api_integration.rs          # 新增
│   └── [其他测试文件...]
├── docs/
│   ├── DEPLOYMENT.md               # 新增
│   └── USER_GUIDE.md               # 新增
├── .zeptoclaw/
│   └── users/                      # 新增用户数据目录
│       └── {user_id}/
│           ├── config.json
│           ├── providers.json
│           ├── skills.json
│           ├── profile.json
│           ├── preferences.json
│           └── conversations/
├── Cargo.toml
├── ENTERPRISE_UI_DEVELOPMENT_GUIDE.md  # 本文档
└── README.md
```

---

## 附录 E：常见问题和解决方案

### Q1: 如何处理与上游 zeptoclaw 的代码冲突？

**A:** 使用 Git rebase 策略：
```bash
# 定期同步上游
git fetch upstream
git rebase upstream/main

# 如果有冲突，解决后继续
git add .
git rebase --continue
```

大部分冲突会出现在：
- `src/api/server.rs` - 路由注册部分
- `src/config/types.rs` - 配置字段部分
- `Cargo.toml` - 依赖版本

### Q2: 如何确保多租户数据隔离？

**A:** 三层防护：
1. **路径隔离**：所有用户数据存储在 `.zeptoclaw/users/{user_id}/`
2. **API 层验证**：每个请求验证 token 中的 user_id
3. **文件系统权限**：使用 `validate_user_ownership()` 检查路径

### Q3: 如何处理流式响应？

**A:** 使用 Server-Sent Events (SSE)：
```rust
// 后端
use axum::response::sse::{Event, Sse};
use futures::stream::Stream;

async fn stream_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> {
    let stream = /* 创建流 */;
    Sse::new(stream)
}
```

```typescript
// 前端
const eventSource = new EventSource('/api/chat/send');
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // 处理数据
};
```

### Q4: 如何优化前端性能？

**A:** 关键优化点：
1. **代码分割**：使用 React.lazy() 懒加载页面
2. **虚拟滚动**：长列表使用 react-window
3. **缓存**：使用 SWR 或 React Query
4. **图片优化**：懒加载和 WebP 格式
5. **Bundle 分析**：使用 vite-plugin-visualizer

### Q5: 如何处理 API 认证？

**A:** 使用 Axios 拦截器：
```typescript
axios.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

axios.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // 跳转到登录页
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);
```

### Q6: 如何测试 API 端点？

**A:** 使用 curl 或 Postman：
```bash
# 登录获取 token
TOKEN=$(curl -X POST http://localhost:9091/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' \
  | jq -r '.token')

# 使用 token 调用 API
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:9091/api/providers
```

### Q7: 如何调试 Rust 后端？

**A:** 使用 tracing 日志：
```rust
// 启用详细日志
RUST_LOG=debug cargo run --features panel

// 在代码中添加日志
tracing::debug!("User context: {:?}", user_context);
tracing::info!("API request: {} {}", method, path);
tracing::error!("Failed to load skill: {}", error);
```

### Q8: 如何处理环境变量？

**A:** 使用 .env 文件：
```bash
# .env.example
ZEPTOCLAW_PANEL_ENABLED=true
ZEPTOCLAW_PANEL_PORT=9092
ZEPTOCLAW_PANEL_API_PORT=9091
ZEPTOCLAW_PANEL_BIND=127.0.0.1
ZEPTOCLAW_MASTER_KEY=your-32-byte-hex-key
```

前端使用 Vite 环境变量：
```typescript
// vite.config.ts
export default defineConfig({
  define: {
    'import.meta.env.VITE_API_URL': JSON.stringify(
      process.env.VITE_API_URL || 'http://localhost:9091'
    ),
  },
});
```

---

## 附录 F：开发工作流建议

### 日常开发流程

```bash
# 1. 启动后端（终端 1）
cd zeptoclaw
cargo run --features panel

# 2. 启动前端（终端 2）
cd panel-ui
npm run dev

# 3. 访问应用
# 前端：http://localhost:5173
# 后端 API：http://localhost:9091
```

### Git 工作流

```bash
# 1. 创建功能分支
git checkout -b feature/enterprise-ui-stage-1

# 2. 开发和提交
git add .
git commit -m "feat: implement user context isolation layer"

# 3. 推送到远程
git push origin feature/enterprise-ui-stage-1

# 4. 创建 Pull Request（如果需要）
gh pr create --title "feat: Enterprise UI Stage 1" --body "Implements user context isolation"

# 5. 合并后删除分支
git checkout main
git pull
git branch -d feature/enterprise-ui-stage-1
```

### 代码审查清单

**后端代码审查：**
- [ ] 遵循 AGENTS.md 规范
- [ ] 无 `unwrap()` 或 `expect()` 在生产路径
- [ ] 添加了 tracing 日志
- [ ] 错误处理完善
- [ ] 单元测试覆盖
- [ ] `cargo fmt` 和 `cargo clippy` 通过
- [ ] 文档注释完整

**前端代码审查：**
- [ ] TypeScript 类型定义完整
- [ ] 组件职责单一
- [ ] 错误边界处理
- [ ] 加载和空状态
- [ ] 响应式设计
- [ ] 无障碍支持
- [ ] ESLint 检查通过

### 调试技巧

**后端调试：**
```bash
# 详细日志
RUST_LOG=debug cargo run --features panel

# 特定模块日志
RUST_LOG=zeptoclaw::api=debug cargo run --features panel

# 使用 rust-gdb 调试
rust-gdb target/debug/zeptoclaw
```

**前端调试：**
```bash
# 开发模式（自动刷新）
npm run dev

# 生产构建预览
npm run build
npm run preview

# 类型检查
npm run type-check

# 查看 bundle 大小
npm run build -- --analyze
```

### 性能分析

**后端性能：**
```bash
# 使用 cargo-flamegraph
cargo install flamegraph
cargo flamegraph --features panel

# 使用 criterion 基准测试
cargo bench
```

**前端性能：**
```bash
# Lighthouse 分析
npm run build
npx lighthouse http://localhost:5173 --view

# Bundle 分析
npm run build -- --analyze
```

---

## 附录 G：快速参考

### 阶段概览

| 阶段 | 名称 | 工作量 | 依赖 | 输出 |
|------|------|--------|------|------|
| 0 | 准备工作 | 0.5 天 | - | GitHub Issue, 环境验证 |
| 1 | 用户上下文隔离层 | 2-3 天 | 0 | user_context.rs |
| 2 | Provider 配置 API | 2-3 天 | 1 | routes/providers.rs |
| 3 | 对话 API | 3-4 天 | 1 | routes/chat.rs |
| 4 | Skills 管理 API | 2-3 天 | 1 | routes/skills.rs |
| 5 | 用户管理 API（可选） | 2-3 天 | 1 | routes/users.rs |
| 6 | React 项目搭建 | 2-3 天 | - | panel-ui/ |
| 7 | 认证和路由 | 2-3 天 | 6 | Login, ProtectedRoute |
| 8 | Provider 配置页面 | 3-4 天 | 6,7 | Providers.tsx |
| 9 | 对话界面 | 4-5 天 | 6,7 | Chat.tsx |
| 10 | Skills 管理页面 | 3-4 天 | 6,7 | Skills.tsx |
| 11 | 导航和布局 | 2-3 天 | 6,7 | Layout.tsx |
| 12 | 仪表盘页面 | 2-3 天 | 6,7 | Dashboard.tsx |
| 13 | 集成测试和优化 | 3-4 天 | 1-12 | 测试套件 |
| 14 | 部署和上线 | 2-3 天 | 1-13 | 部署文档 |

**总计：约 4-6 周（单人）或 3-4 周（双人）**

### 关键命令速查

```bash
# 后端开发
cargo run --features panel              # 启动后端
cargo test                              # 运行测试
cargo clippy -- -D warnings             # 代码检查
cargo fmt                               # 格式化代码

# 前端开发
cd panel-ui
npm install                             # 安装依赖
npm run dev                             # 启动开发服务器
npm run build                           # 生产构建
npm run lint                            # 代码检查
npm run test                            # 运行测试

# Git 工作流
git checkout -b feature/stage-N         # 创建分支
git add . && git commit -m "feat: ..."  # 提交
git push origin feature/stage-N         # 推送
gh pr create                            # 创建 PR

# 测试 API
curl -X POST http://localhost:9091/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
```

### 重要文件清单

**必须修改的文件（最小化）：**
- `src/api/server.rs` - 添加路由注册
- `src/api/mod.rs` - 导出新模块
- `src/config/types.rs` - 添加配置字段
- `Cargo.toml` - 确保 panel feature

**新增的核心文件：**
- `src/api/user_context.rs` - 用户隔离层
- `src/api/routes/providers.rs` - Provider API
- `src/api/routes/chat.rs` - 对话 API
- `src/api/routes/skills.rs` - Skills API
- `panel-ui/` - 完整前端项目

### 配置示例

**.env 文件：**
```bash
ZEPTOCLAW_PANEL_ENABLED=true
ZEPTOCLAW_PANEL_PORT=9092
ZEPTOCLAW_PANEL_API_PORT=9091
ZEPTOCLAW_PANEL_BIND=127.0.0.1
ZEPTOCLAW_MASTER_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
RUST_LOG=info
```

**panel-ui/.env：**
```bash
VITE_API_URL=http://localhost:9091
VITE_WS_URL=ws://localhost:9091
```

### 故障排查

**问题：后端编译失败**
```bash
# 清理并重新构建
cargo clean
cargo build --features panel
```

**问题：前端无法连接后端**
```bash
# 检查 CORS 配置
# 检查 vite.config.ts 中的 proxy 配置
# 检查后端是否启动在正确端口
```

**问题：认证失败**
```bash
# 检查 token 是否正确存储
# 检查 Authorization header 格式
# 检查后端日志
RUST_LOG=debug cargo run --features panel
```

---

## 总结

本开发指南提供了完整的阶段性开发路线图，每个阶段都包含：
- 详细的 Prompt 模板（可直接使用）
- 明确的验收标准
- 具体的输出物
- 验证命令

**使用建议：**
1. 按顺序完成每个阶段
2. 每个阶段完成后运行验证命令
3. 遇到问题参考附录 E（常见问题）
4. 保持与上游 zeptoclaw 的定期同步

**关键原则：**
- 最小侵入性（95% 扩展，5% 修改）
- 模块化设计
- 完整的测试覆盖
- 详细的文档

祝开发顺利！🚀

---

**文档版本：** v1.0  
**最后更新：** 2026-02-28  
**维护者：** ZeptoClaw Enterprise UI Team

## 阶段 15：Cron 定时任务管理页面（前端补充）

### 📋 Prompt 模板

```
我正在开发 zeptoclaw 企业级 Web UI 的阶段 15：Cron 定时任务管理页面。

任务目标：
实现 Cron 定时任务的 Web 管理界面，支持创建、编辑、删除和触发定时任务。

具体要求：
1. 创建相关文件：
   - src/api/cron.ts - Cron API 调用
   - src/stores/cronStore.ts - Cron 状态管理
   - src/pages/Cron.tsx - Cron 管理页面
   - src/components/CronJobCard.tsx - Cron 任务卡片
   - src/components/CronJobModal.tsx - 创建/编辑弹窗
   - src/components/CronExpressionBuilder.tsx - Cron 表达式构建器

2. cronStore 实现：
   - 状态：jobs, loading, error
   - 方法：
     * fetchJobs()
     * createJob(job)
     * updateJob(id, job)
     * deleteJob(id)
     * triggerJob(id)

3. Cron 页面布局：
   - 页面标题和说明
   - 新建任务按钮
   - 任务列表（表格或卡片）
   - 筛选器（全部/启用/禁用）

4. CronJobCard 组件：
   - 任务名称和描述
   - Cron 表达式（人类可读格式）
   - 下次执行时间
   - 启用/禁用开关
   - 立即触发按钮
   - 编辑和删除按钮

5. CronJobModal 组件：
   - 任务名称输入
   - 消息内容输入
   - Cron 表达式输入（带验证）
   - 或使用 CronExpressionBuilder
   - 目标 channel 选择
   - 目标 chat_id 输入
   - 一次性任务选项（指定时间）
   - 保存和取消按钮

6. CronExpressionBuilder 组件：
   - 可视化 cron 表达式构建器
   - 预设选项（每天、每周、每月等）
   - 自定义选项（分钟、小时、日、月、周）
   - 实时预览下次执行时间
   - 表达式验证

7. 功能实现：
   - 复用现有的 Cron API（已存在于 src/api/routes/cron.rs）
   - 支持 cron 表达式和一次性任务（At）
   - 任务执行历史（可选）
   - 错误处理和用户反馈

8. 在 Sidebar 中添加 Cron 菜单项

技术要求：
- 使用 cronstrue 库将 cron 表达式转换为人类可读格式
- 使用 cron-parser 验证 cron 表达式
- 使用 date-fns 格式化时间
- 响应式设计
- 完整的错误处理

遵循前端最佳实践。
```

### ✅ 验收标准

- [ ] Cron 任务列表展示正常
- [ ] 创建/编辑任务功能正常
- [ ] Cron 表达式构建器可用
- [ ] 立即触发功能正常
- [ ] 启用/禁用功能正常
- [ ] 删除任务功能正常
- [ ] 响应式设计验证

### 📝 输出物

- src/api/cron.ts
- src/stores/cronStore.ts
- src/pages/Cron.tsx
- 3 个 Cron 相关组件
- 更新的 Sidebar.tsx

### 🔍 验证命令

```bash
cd panel-ui
npm install cronstrue cron-parser
npm run dev
# 访问 /cron 页面
# 测试创建和触发任务
```

---


技术	版本	用途
Rust	2021 edition	核心语言
Axum	0.8+	Web 框架
Tokio	1.35+	异步运行时
Tower-HTTP	0.6+	HTTP 中间件
Serde	1.0+	序列化/反序列化
JWT	9+	Token 认证
bcrypt	0.17+	密码哈希
chacha20poly1305	0.10+	数据加密

技术	版本	用途
React	19+	UI 框架
TypeScript	5+	类型系统
Vite	5+	构建工具
React Router	6+	路由管理
Zustand	4+	状态管理
Tailwind CSS	3+	样式框架
Axios	1+	HTTP 客户端
React Markdown	9+	Markdown 渲染
Headless UI	2+	无样式组件

阶段	名称	工作量	依赖	输出
0	准备工作	0.5 天	-	GitHub Issue, 环境验证
1	用户上下文隔离层	2-3 天	0	user_context.rs
2	Provider 配置 API	2-3 天	1	routes/providers.rs
3	对话 API	3-4 天	1	routes/chat.rs
4	Skills 管理 API	2-3 天	1	routes/skills.rs
5	用户管理 API（可选）	2-3 天	1	routes/users.rs
6	React 项目搭建	2-3 天	-	panel-ui/
7	认证和路由	2-3 天	6	Login, ProtectedRoute
8	Provider 配置页面	3-4 天	6,7	Providers.tsx
9	对话界面	4-5 天	6,7	Chat.tsx
10	Skills 管理页面	3-4 天	6,7	Skills.tsx
11	导航和布局	2-3 天	6,7	Layout.tsx
12	仪表盘页面	2-3 天	6,7	Dashboard.tsx
13	集成测试和优化	3-4 天	1-12	测试套件
14	部署和上线	2-3 天	1-13	部署文档

person #1

Description

ZeptoClaw 企业级 Web UI 开发指南

项目概述

开发原则

阶段 0：准备工作（开始前必读）

📋 Prompt 模板

✅ 验收标准

📝 输出物

阶段 1：用户上下文隔离层（后端基础）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 2：Provider 配置 API（后端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 3：对话 API（后端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 4：Skills 管理 API（后端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 5：用户管理 API（后端，可选）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 6：React 前端项目搭建

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 7：认证和路由（前端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 8：Provider 配置页面（前端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 9：对话界面（前端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 10：Skills 管理页面（前端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 11：导航和布局（前端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 12：仪表盘页面（前端）

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 13：集成测试和优化

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

阶段 14：部署和上线

📋 Prompt 模板

✅ 验收标准

📝 输出物

🔍 验证命令

附录 A：技术栈详细说明