0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
234 lines
6.0 KiB
Markdown
234 lines
6.0 KiB
Markdown
# 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 数据，用户看不到真实执行历史
|
||
|
||
**解决方案**:
|
||
```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_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 客户端使用示例
|
||
|
||
```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. **ZCLAW 端口是 50051，不是 4200**
|
||
5. **配置格式是 TOML，不是 JSON/YAML**
|
||
6. **WebSocket 路径是 `/ws`**
|
||
|
||
---
|
||
|
||
## 验收标准 (Phase 0)
|
||
|
||
- [ ] HandTaskPanel 显示真实任务历史（无 MockTask）
|
||
- [ ] Workflow 可创建、编辑、删除
|
||
- [ ] Session 可持久化，刷新后历史保留
|
||
- [ ] 7 个 Hands 全部有 TOML 配置
|
||
|
||
---
|
||
|
||
*提示词版本: 2026-03-15*
|