zclaw_openfang/docs/archive/NEXT_SESSION.md

ZCLAW 新会话提示词

创建日期: 2026-03-15 目的: 为后续开发会话提供完整上下文

---

项目概述

ZCLAW 是基于 ZCLAW (Rust Agent OS) 的 AI Agent 桌面客户端，使用 Tauri 2.0 + React + TypeScript 开发。

技术栈:

• 前端: React 19 + TypeScript + Zustand + Tailwind CSS
• 桌面: Tauri 2.0 (Rust)
• 后端: ZCLAW Kernel (Rust, 端口 50051)
• 配置: TOML 格式

核心价值: 真实连接 ZCLAW 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 数据，用户看不到真实执行历史

解决方案:

// 移除 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):

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 完全缺失，会话无法持久化

需要添加:

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_zclaw/
├── CLAUDE.md                          # 项目协作规则
├── docs/
│   ├── SYSTEM_ANALYSIS.md             # ⭐ 系统分析报告
│   ├── zclaw-technical-reference.md # ZCLAW 技术参考
│   └── 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 提供商配置
    └── zclaw.default.json          # ⚠️ 待迁移到 TOML

---

API 客户端使用示例

// 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

---

常用命令

# 开发
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. ZCLAW 端口是 50051，不是 4200
5. 配置格式是 TOML，不是 JSON/YAML
6. WebSocket 路径是 /ws

---

验收标准 (Phase 0)

• HandTaskPanel 显示真实任务历史（无 MockTask）
• Workflow 可创建、编辑、删除
• Session 可持久化，刷新后历史保留
• 7 个 Hands 全部有 TOML 配置

---

提示词版本: 2026-03-15