From 1f9b6553fcf91aaa79224384fdb4d4002181703d Mon Sep 17 00:00:00 2001 From: iven Date: Sun, 15 Mar 2026 00:19:35 +0800 Subject: [PATCH] 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 --- docs/NEXT_SESSION.md | 233 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 docs/NEXT_SESSION.md diff --git a/docs/NEXT_SESSION.md b/docs/NEXT_SESSION.md new file mode 100644 index 0000000..b30f5b2 --- /dev/null +++ b/docs/NEXT_SESSION.md @@ -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*