# 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*