docs: add next session prompt for continuing development
Create comprehensive onboarding document for new sessions: - Project overview (OpenFang + Tauri + React) - Current status (API 60%, UI 80%, Hands 43%) - Phase 0 tasks with code examples: - HandTaskPanel real task history - 4 missing Hands TOML configs - Workflow editor implementation - Session management API - Key file locations - API client usage examples - Common commands - Acceptance criteria Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
233
docs/NEXT_SESSION.md
Normal file
233
docs/NEXT_SESSION.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# ZCLAW 新会话提示词
|
||||
|
||||
**创建日期**: 2026-03-15
|
||||
**目的**: 为后续开发会话提供完整上下文
|
||||
|
||||
---
|
||||
|
||||
## 项目概述
|
||||
|
||||
ZCLAW 是基于 **OpenFang** (Rust Agent OS) 的 AI Agent 桌面客户端，使用 Tauri 2.0 + React + TypeScript 开发。
|
||||
|
||||
**技术栈**:
|
||||
- 前端: React 19 + TypeScript + Zustand + Tailwind CSS
|
||||
- 桌面: Tauri 2.0 (Rust)
|
||||
- 后端: OpenFang Kernel (Rust, 端口 50051)
|
||||
- 配置: TOML 格式
|
||||
|
||||
**核心价值**: 真实连接 OpenFang Kernel，驱动 Agents / Skills / Hands / Workflows
|
||||
|
||||
---
|
||||
|
||||
## 当前状态
|
||||
|
||||
```
|
||||
API 覆盖率: 60% (37/62 端点)
|
||||
UI 完成度: 80% (20/25 组件)
|
||||
Hands 配置: 43% (3/7 有 TOML)
|
||||
Skills 定义: 7% (4/60+ 潜在)
|
||||
整体对齐度: 80%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 待完成任务 (Phase 0 - P0 优先级)
|
||||
|
||||
### 1. HandTaskPanel 真实任务历史
|
||||
|
||||
**文件**: `desktop/src/components/HandTaskPanel.tsx`
|
||||
|
||||
**问题**: 当前使用硬编码 MockTask 数据，用户看不到真实执行历史
|
||||
|
||||
**解决方案**:
|
||||
```typescript
|
||||
// 移除 MockTask 接口和硬编码数据
|
||||
// 添加 API 调用获取真实任务历史
|
||||
const { data: tasks } = useQuery(['hand-runs', handName],
|
||||
() => gatewayClient.listHandRuns(handName)
|
||||
);
|
||||
```
|
||||
|
||||
**相关 API**: `/api/hands/:name/runs` (已实现)
|
||||
|
||||
### 2. 补充 4 个 Hands TOML 配置
|
||||
|
||||
**目录**: `hands/`
|
||||
|
||||
**已有**: `researcher.HAND.toml`, `browser.HAND.toml`, `lead.HAND.toml`
|
||||
|
||||
**缺失**:
|
||||
- `clip.HAND.toml` - 视频处理
|
||||
- `collector.HAND.toml` - 数据收集
|
||||
- `predictor.HAND.toml` - 预测分析
|
||||
- `twitter.HAND.toml` - Twitter 自动化
|
||||
|
||||
**参考格式** (researcher.HAND.toml):
|
||||
```toml
|
||||
name = "researcher"
|
||||
type = "research"
|
||||
description = "深度研究自主能力包"
|
||||
requires_approval = false
|
||||
timeout_seconds = 300
|
||||
|
||||
[agent]
|
||||
provider = "openai"
|
||||
model = "gpt-4"
|
||||
|
||||
[[tools]]
|
||||
name = "web_search"
|
||||
```
|
||||
|
||||
### 3. Workflow 编辑器实现
|
||||
|
||||
**文件**: `desktop/src/components/WorkflowEditor.tsx` (新建)
|
||||
|
||||
**当前问题**: WorkflowList.tsx 中编辑/删除/新建都是 alert() placeholder
|
||||
|
||||
**需要实现**:
|
||||
- 创建 Workflow 弹窗
|
||||
- 编辑 Workflow 步骤
|
||||
- 删除确认对话框
|
||||
- 调用 API: `POST /api/workflows`, `PUT /api/workflows/:id`, `DELETE /api/workflows/:id`
|
||||
|
||||
### 4. Session 管理实现
|
||||
|
||||
**文件**: `desktop/src/store/gatewayStore.ts`
|
||||
|
||||
**问题**: Session API 完全缺失，会话无法持久化
|
||||
|
||||
**需要添加**:
|
||||
```typescript
|
||||
loadSessions: async () => {
|
||||
const sessions = await client.listSessions();
|
||||
set({ sessions });
|
||||
},
|
||||
|
||||
createSession: async (agentId: string) => {
|
||||
const session = await client.createSession({ agentId });
|
||||
return session;
|
||||
},
|
||||
|
||||
getSessionMessages: async (sessionId: string) => {
|
||||
const messages = await client.getSessionMessages(sessionId);
|
||||
return messages;
|
||||
},
|
||||
```
|
||||
|
||||
**相关 API**:
|
||||
- `GET /api/sessions`
|
||||
- `POST /api/sessions`
|
||||
- `GET /api/sessions/:id`
|
||||
- `DELETE /api/sessions/:id`
|
||||
- `GET /api/sessions/:id/messages`
|
||||
|
||||
---
|
||||
|
||||
## 关键文件位置
|
||||
|
||||
```
|
||||
ZClaw_openfang/
|
||||
├── CLAUDE.md # 项目协作规则
|
||||
├── docs/
|
||||
│ ├── SYSTEM_ANALYSIS.md # ⭐ 系统分析报告
|
||||
│ ├── openfang-technical-reference.md # OpenFang 技术参考
|
||||
│ └── knowledge-base/ # 知识库
|
||||
│ ├── feature-checklist.md # 功能验证清单
|
||||
│ └── hands-integration-lessons.md
|
||||
├── desktop/
|
||||
│ ├── src/
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── HandList.tsx # Hands 列表
|
||||
│ │ │ ├── HandTaskPanel.tsx # ⚠️ 使用 Mock 数据
|
||||
│ │ │ ├── WorkflowList.tsx # ⚠️ 编辑器是 placeholder
|
||||
│ │ │ └── Settings/ # 设置页面
|
||||
│ │ ├── store/
|
||||
│ │ │ ├── gatewayStore.ts # Gateway 状态管理
|
||||
│ │ │ └── chatStore.ts # 聊天状态管理
|
||||
│ │ ├── lib/
|
||||
│ │ │ ├── gateway-client.ts # API 客户端
|
||||
│ │ │ └── gateway-config.ts # 配置管理
|
||||
│ │ └── types/
|
||||
│ │ └── hands.ts # Hands 类型定义
|
||||
│ └── src-tauri/ # Tauri Rust 后端
|
||||
├── hands/ # ⚠️ 缺 4 个 TOML
|
||||
│ ├── researcher.HAND.toml
|
||||
│ ├── browser.HAND.toml
|
||||
│ └── lead.HAND.toml
|
||||
├── skills/ # 技能定义
|
||||
│ ├── chinese-writing/SKILL.md
|
||||
│ ├── feishu-docs/SKILL.md
|
||||
│ ├── code-review/SKILL.md
|
||||
│ └── translation/SKILL.md
|
||||
└── config/
|
||||
├── chinese-providers.toml # LLM 提供商配置
|
||||
└── openclaw.default.json # ⚠️ 待迁移到 TOML
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API 客户端使用示例
|
||||
|
||||
```typescript
|
||||
// gateway-client.ts 中已实现的方法
|
||||
const client = getGatewayClient();
|
||||
|
||||
// Hands 相关
|
||||
await client.listHands();
|
||||
await client.getHand('researcher');
|
||||
await client.triggerHand('researcher', { query: '...' });
|
||||
await client.listHandRuns('researcher'); // ⭐ HandTaskPanel 需要
|
||||
|
||||
// Workflows 相关
|
||||
await client.listWorkflows();
|
||||
await client.executeWorkflow('workflow-id');
|
||||
// ⚠️ createWorkflow, updateWorkflow, deleteWorkflow 未实现
|
||||
|
||||
// Session 相关
|
||||
// ⚠️ 全部未实现: listSessions, createSession, getSessionMessages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 开发
|
||||
cd desktop && pnpm dev
|
||||
|
||||
# Tauri 开发
|
||||
cd desktop && pnpm tauri:dev
|
||||
|
||||
# 测试
|
||||
pnpm vitest run tests/desktop/
|
||||
|
||||
# 类型检查
|
||||
pnpm tsc --noEmit
|
||||
|
||||
# 构建
|
||||
cd desktop && pnpm tauri:build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **所有 UI 文本必须中文**
|
||||
2. **使用 Zustand 管理状态，不要在组件内直接调用 API**
|
||||
3. **类型定义放在 `desktop/src/types/` 目录**
|
||||
4. **OpenFang 端口是 50051，不是 4200**
|
||||
5. **配置格式是 TOML，不是 JSON/YAML**
|
||||
6. **WebSocket 路径是 `/ws`**
|
||||
|
||||
---
|
||||
|
||||
## 验收标准 (Phase 0)
|
||||
|
||||
- [ ] HandTaskPanel 显示真实任务历史（无 MockTask）
|
||||
- [ ] Workflow 可创建、编辑、删除
|
||||
- [ ] Session 可持久化，刷新后历史保留
|
||||
- [ ] 7 个 Hands 全部有 TOML 配置
|
||||
|
||||
---
|
||||
|
||||
*提示词版本: 2026-03-15*
|
||||
Reference in New Issue
Block a user