GPU_GUARD_MONOREPO/docs/superpowers/plans/2026-04-12-netaclaw-agent-skill-migration.md

# NetaClaw Agent/Skill 管理迁移实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 将 Agent 管理、Skill 管理、Agent 对话页面从旧接口迁移到 NetaClaw 运行时，删除旧 agent 模块

**Architecture:** 后端在 NetaClaw 模块新增 Entity（netaclaw_agent, netaclaw_skill）和 Controller（agent CRUD, skill 管理, 会话管理），增强 WS Gateway 支持 agentId。前端 store 从 SSE 改为 WebSocket，所有页面 API 路径统一切到 `/admin/netaclaw/*` 和 `/open/netaclaw/*`。

**Tech Stack:** Midway.js 3.20 + TypeORM + Socket.IO / Vue 3 + Pinia + Element Plus

**Spec:** `docs/superpowers/specs/2026-04-12-netaclaw-agent-skill-migration-design.md`

---

### Task 1: 新建 NetaClaw Agent Entity

**Files:**
- Create: `packages/backend/src/modules/netaclaw/entity/agent.ts`

- [ ] **Step 1: 创建 NetaClawAgentEntity**

```typescript
// packages/backend/src/modules/netaclaw/entity/agent.ts
import { BaseEntity } from '../../base/entity/base.js';
import { Column, Entity, Index } from 'typeorm';

/**
 * NetaClaw Agent 配置
 */
@Entity('netaclaw_agent')
export class NetaClawAgentEntity extends BaseEntity {
  @Column({ comment: '唯一标识', length: 100, unique: true })
  name: string;

  @Column({ comment: '显示名称', length: 200 })
  label: string;

  @Column({ comment: '描述', type: 'text', nullable: true })
  description: string;

  @Column({ comment: '图标', length: 100, nullable: true })
  icon: string;

  @Column({ comment: '系统提示词', type: 'text', nullable: true })
  systemPrompt: string;

  @Column({ type: 'json', comment: '关联Skill名称列表', nullable: true })
  skills: string[];

  @Column({ type: 'json', comment: '模型配置', nullable: true })
  modelConfig: { apiUrl?: string; apiKey?: string; modelId?: string; contextWindow?: number };

  @Column({ type: 'json', comment: 'Agent配置', nullable: true })
  config: Record<string, unknown>;

  @Index()
  @Column({ comment: '状态: 0=草稿 1=已发布', default: 0 })
  status: number;
}
```

- [ ] **Step 2: 启动后端验证表自动创建**

Run: `cd packages/backend && npx midway-bin dev`
Expected: 启动成功，数据库中出现 `netaclaw_agent` 表

- [ ] **Step 3: 用 MCP 工具验证表结构**

用 MySQL MCP 工具执行: `DESCRIBE netaclaw_agent`
Expected: 包含 id, createTime, updateTime, tenantId, name, label, description, icon, systemPrompt, skills, modelConfig, config, status 字段

- [ ] **Step 4: Commit**

```bash
git add packages/backend/src/modules/netaclaw/entity/agent.ts
git commit -m "feat(netaclaw): add NetaClawAgentEntity for agent CRUD management"
```

---

### Task 2: 新建 NetaClaw Skill Entity

**Files:**
- Create: `packages/backend/src/modules/netaclaw/entity/skill.ts`

- [ ] **Step 1: 创建 NetaClawSkillEntity**

```typescript
// packages/backend/src/modules/netaclaw/entity/skill.ts
import { BaseEntity } from '../../base/entity/base.js';
import { Column, Entity, Index } from 'typeorm';

/**
 * NetaClaw Skill 状态管理（配合 SKILL.md 文件使用）
 */
@Entity('netaclaw_skill')
export class NetaClawSkillEntity extends BaseEntity {
  @Column({ comment: 'Skill名称', length: 100, unique: true })
  name: string;

  @Column({ comment: '显示名称', length: 200 })
  label: string;

  @Column({ comment: '描述', type: 'text', nullable: true })
  description: string;

  @Column({ comment: '图标', length: 100, nullable: true })
  icon: string;

  @Column({ comment: '分类', length: 50, nullable: true })
  category: string;

  @Column({ comment: 'Skill类型: compute/llm/multimodal', length: 20, nullable: true })
  skillType: string;

  @Column({ type: 'json', comment: '标签', nullable: true })
  tags: string[];

  @Column({ type: 'json', comment: '配置', nullable: true })
  config: Record<string, unknown>;

  @Index()
  @Column({ comment: '状态: 0=禁用 1=启用', default: 1 })
  status: number;

  @Column({ comment: '版本号', length: 20, nullable: true })
  version: string;
}
```

- [ ] **Step 2: 验证表创建**

启动后端，用 MySQL MCP 工具执行: `DESCRIBE netaclaw_skill`
Expected: 包含所有定义的字段

- [ ] **Step 3: Commit**

```bash
git add packages/backend/src/modules/netaclaw/entity/skill.ts
git commit -m "feat(netaclaw): add NetaClawSkillEntity for skill status management"
```

---

### Task 3: 给 netaclaw_session 表增加 agentId 字段

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/entity/session.ts`

- [ ] **Step 1: 在 NetaClawSessionEntity 中增加 agentId 字段**

在 `agentName` 字段后面添加:

```typescript
  @Column({ comment: 'Agent ID（关联 netaclaw_agent）', nullable: true })
  agentId: number;
```

- [ ] **Step 2: 验证字段添加**

启动后端（synchronize: true 会自动加字段），用 MySQL MCP 工具执行: `DESCRIBE netaclaw_session`
Expected: 出现 agentId 字段

- [ ] **Step 3: Commit**

```bash
git add packages/backend/src/modules/netaclaw/entity/session.ts
git commit -m "feat(netaclaw): add agentId field to session entity"
```

---

### Task 4: 新建 Agent 管理 Controller + Service

**Files:**
- Create: `packages/backend/src/modules/netaclaw/service/agent.ts`
- Create: `packages/backend/src/modules/netaclaw/controller/agent.ts`

- [ ] **Step 1: 创建 AgentService**

```typescript
// packages/backend/src/modules/netaclaw/service/agent.ts
import { Provide, Inject, Scope, ScopeEnum } from '@midwayjs/core';
import { InjectEntityModel } from '@midwayjs/typeorm';
import { Repository, Like } from 'typeorm';
import { NetaClawAgentEntity } from '../entity/agent.js';

@Provide()
@Scope(ScopeEnum.Singleton)
export class NetaClawAgentService {
  @InjectEntityModel(NetaClawAgentEntity)
  agentRepo: Repository<NetaClawAgentEntity>;

  /** 分页查询 */
  async page(params: { page: number; size: number; keyWord?: string }) {
    const { page = 1, size = 20, keyWord } = params;
    const where: any = {};
    if (keyWord) {
      where.label = Like(`%${keyWord}%`);
    }
    const [list, total] = await this.agentRepo.findAndCount({
      where,
      order: { createTime: 'DESC' },
      skip: (page - 1) * size,
      take: size,
    });
    return { list, pagination: { page, size, total } };
  }

  /** 创建 */
  async add(data: Partial<NetaClawAgentEntity>) {
    const entity = this.agentRepo.create(data);
    const saved = await this.agentRepo.save(entity);
    return { id: saved.id };
  }

  /** 更新 */
  async update(data: Partial<NetaClawAgentEntity>) {
    await this.agentRepo.save(data);
  }

  /** 删除 */
  async delete(ids: number[]) {
    await this.agentRepo.delete(ids);
  }

  /** 详情 */
  async info(id: number) {
    return this.agentRepo.findOneBy({ id });
  }

  /** 已发布列表 */
  async publishedList() {
    return this.agentRepo.find({ where: { status: 1 }, order: { createTime: 'DESC' } });
  }
}
```

- [ ] **Step 2: 创建 Agent Controller**

```typescript
// packages/backend/src/modules/netaclaw/controller/agent.ts
import { Provide, Inject, Post, Get, Body, Query, Controller, Logger } from '@midwayjs/core';
import { ILogger } from '@midwayjs/logger';
import { Context } from '@midwayjs/koa';
import { NetaClawAgentService } from '../service/agent.js';

@Provide()
@Controller('/admin/netaclaw/agent')
export class NetaClawAgentAdminController {
  @Inject()
  ctx: Context;

  @Logger()
  logger: ILogger;

  @Inject()
  agentService: NetaClawAgentService;

  @Post('/page')
  async page(@Body() body: { page?: number; size?: number; keyWord?: string }) {
    return { code: 1000, data: await this.agentService.page(body) };
  }

  @Post('/add')
  async add(@Body() body: any) {
    return { code: 1000, data: await this.agentService.add(body) };
  }

  @Post('/update')
  async update(@Body() body: any) {
    await this.agentService.update(body);
    return { code: 1000, message: 'success' };
  }

  @Post('/delete')
  async delete(@Body() body: { ids: number[] }) {
    await this.agentService.delete(body.ids);
    return { code: 1000, message: 'success' };
  }

  @Get('/info')
  async info(@Query('id') id: number) {
    return { code: 1000, data: await this.agentService.info(id) };
  }
}

@Provide()
@Controller('/open/netaclaw/agent')
export class NetaClawAgentOpenController {
  @Inject()
  agentService: NetaClawAgentService;

  @Post('/list')
  async list() {
    return { code: 1000, data: await this.agentService.publishedList() };
  }
}
```

- [ ] **Step 3: 启动后端验证接口**

Run: `cd packages/backend && npx midway-bin dev`
用 curl 测试: `curl -X POST http://localhost:8003/admin/netaclaw/agent/page -H "Content-Type: application/json" -d '{"page":1,"size":10}'`
Expected: 返回 `{"code":1000,"data":{"list":[],"pagination":{"page":1,"size":10,"total":0}}}`

- [ ] **Step 4: Commit**

```bash
git add packages/backend/src/modules/netaclaw/service/agent.ts packages/backend/src/modules/netaclaw/controller/agent.ts
git commit -m "feat(netaclaw): add agent CRUD controller and service"
```

---

### Task 5: 新建 Skill 管理 Controller（合并 SKILL.md + 数据库状态）

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/service/skill_loader.ts`
- Create: `packages/backend/src/modules/netaclaw/controller/skill.ts`

- [ ] **Step 1: 增强 SkillLoaderService，增加数据库状态合并**

在 `packages/backend/src/modules/netaclaw/service/skill_loader.ts` 中：
- 注入 `NetaClawSkillEntity` 的 Repository
- 新增 `getSkillMetas()` 方法：扫描 SKILL.md + 合并数据库 status
- 新增 `setSkillStatus(name, status)` 方法：更新数据库中的启用/禁用状态
- 如果 SKILL.md 存在但数据库无记录，自动创建记录（默认启用）

```typescript
// 在现有 SkillLoaderService 中新增以下导入和方法：
import { InjectEntityModel } from '@midwayjs/typeorm';
import { Repository } from 'typeorm';
import { NetaClawSkillEntity } from '../entity/skill.js';

// 在类中新增：
@InjectEntityModel(NetaClawSkillEntity)
skillRepo: Repository<NetaClawSkillEntity>;

/** 获取所有 Skill 元数据（SKILL.md + 数据库状态合并） */
async getSkillMetas(): Promise<any[]> {
  const fileSkills = this.getAllSkills();
  const dbSkills = await this.skillRepo.find();
  const dbMap = new Map(dbSkills.map(s => [s.name, s]));

  const result = [];
  for (const fs of fileSkills) {
    let dbRecord = dbMap.get(fs.name);
    if (!dbRecord) {
      // 自动创建数据库记录
      dbRecord = await this.skillRepo.save({
        name: fs.name,
        label: fs.name,
        description: fs.description,
        status: 1,
      });
    }
    result.push({
      name: fs.name,
      label: dbRecord.label || fs.name,
      description: fs.description || dbRecord.description,
      icon: dbRecord.icon,
      category: dbRecord.category,
      skillType: dbRecord.skillType,
      tags: dbRecord.tags,
      config: dbRecord.config,
      status: dbRecord.status,
      version: dbRecord.version,
    });
  }
  return result;
}

/** 设置 Skill 启用/禁用状态 */
async setSkillStatus(name: string, status: number): Promise<void> {
  const existing = await this.skillRepo.findOneBy({ name });
  if (existing) {
    await this.skillRepo.update({ name }, { status });
  } else {
    await this.skillRepo.save({ name, label: name, status });
  }
}
```

- [ ] **Step 2: 创建 Skill Controller**

```typescript
// packages/backend/src/modules/netaclaw/controller/skill.ts
import { Provide, Inject, Get, Post, Body, Controller } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';
import { SkillLoaderService } from '../service/skill_loader.js';

@Provide()
@Controller('/admin/netaclaw/skill')
export class NetaClawSkillController {
  @Inject()
  ctx: Context;

  @Inject()
  skillLoader: SkillLoaderService;

  @Get('/metas')
  async metas() {
    return { code: 1000, data: await this.skillLoader.getSkillMetas() };
  }

  @Post('/setStatus')
  async setStatus(@Body() body: { name: string; status: number }) {
    await this.skillLoader.setSkillStatus(body.name, body.status);
    return { code: 1000, message: 'success' };
  }
}
```

- [ ] **Step 3: 验证接口**

用 curl 测试: `curl http://localhost:8003/admin/netaclaw/skill/metas`
Expected: 返回 `{"code":1000,"data":[...]}`（如果 skills/ 目录有 SKILL.md 文件则有数据）

- [ ] **Step 4: Commit**

```bash
git add packages/backend/src/modules/netaclaw/service/skill_loader.ts packages/backend/src/modules/netaclaw/controller/skill.ts
git commit -m "feat(netaclaw): add skill management controller with SKILL.md + DB merge"
```

---

### Task 6: 新建会话管理 Controller

**Files:**
- Create: `packages/backend/src/modules/netaclaw/controller/session.ts`
- Modify: `packages/backend/src/modules/netaclaw/gateway/session.ts`

- [ ] **Step 1: 在 NetaClawSessionService 中新增会话管理方法**

在 `packages/backend/src/modules/netaclaw/gateway/session.ts` 中新增：

```typescript
/** 会话列表 */
async listSessions(userId?: string, agentId?: number): Promise<NetaClawSessionEntity[]> {
  const where: any = { status: 'active' };
  if (userId) where.userId = userId;
  if (agentId) where.agentId = agentId;
  return this.sessionRepo.find({ where, order: { updateTime: 'DESC' } });
}

/** 获取会话消息历史 */
async getMessages(sessionId: string) {
  return this.messageRepo.find({
    where: { sessionId },
    order: { createTime: 'ASC' },
  });
}

/** 删除会话及其消息 */
async deleteSession(sessionId: string): Promise<void> {
  await this.messageRepo.delete({ sessionId });
  await this.sessionRepo.delete({ sessionId });
}

/** 删除用户所有会话 */
async deleteAllSessions(userId?: string): Promise<void> {
  const where: any = {};
  if (userId) where.userId = userId;
  const sessions = await this.sessionRepo.find({ where });
  for (const s of sessions) {
    await this.messageRepo.delete({ sessionId: s.sessionId });
  }
  await this.sessionRepo.delete(where);
}
```

- [ ] **Step 2: 创建 Session Controller**

```typescript
// packages/backend/src/modules/netaclaw/controller/session.ts
import { Provide, Inject, Post, Body, Controller } from '@midwayjs/core';
import { Context } from '@midwayjs/koa';
import { NetaClawSessionService } from '../gateway/session.js';

@Provide()
@Controller('/open/netaclaw/session')
export class NetaClawSessionController {
  @Inject()
  ctx: Context;

  @Inject()
  sessionService: NetaClawSessionService;

  @Post('/list')
  async list(@Body() body: { userId?: string; agentId?: number }) {
    return { code: 1000, data: await this.sessionService.listSessions(body.userId, body.agentId) };
  }

  @Post('/messages')
  async messages(@Body() body: { sessionId: string }) {
    return { code: 1000, data: await this.sessionService.getMessages(body.sessionId) };
  }

  @Post('/delete')
  async delete(@Body() body: { sessionId: string }) {
    await this.sessionService.deleteSession(body.sessionId);
    return { code: 1000, message: 'success' };
  }

  @Post('/deleteAll')
  async deleteAll(@Body() body: { userId?: string }) {
    await this.sessionService.deleteAllSessions(body.userId);
    return { code: 1000, message: 'success' };
  }
}
```

- [ ] **Step 3: 验证接口**

用 curl 测试: `curl -X POST http://localhost:8003/open/netaclaw/session/list -H "Content-Type: application/json" -d '{}'`
Expected: 返回 `{"code":1000,"data":[]}`

- [ ] **Step 4: Commit**

```bash
git add packages/backend/src/modules/netaclaw/controller/session.ts packages/backend/src/modules/netaclaw/gateway/session.ts
git commit -m "feat(netaclaw): add session management controller (list/messages/delete)"
```

---

### Task 7: 增强 WebSocket Gateway 支持 agentId

**Files:**
- Modify: `packages/backend/src/modules/netaclaw/gateway/protocol.ts`
- Modify: `packages/backend/src/modules/netaclaw/gateway/server.ts`

- [ ] **Step 1: 更新协议定义，增加新事件类型**

在 `packages/backend/src/modules/netaclaw/gateway/protocol.ts` 中：

ClientChatMessage 增加 `agentId` 字段：
```typescript
export interface ClientChatMessage {
  type: 'chat';
  sessionId: string;
  content: string;
  agentName?: string;
  agentId?: number;  // 新增：从数据库加载 Agent 配置
}
```

新增服务端事件类型：
```typescript
export interface ServerSkillStartEvent {
  type: 'skill_start';
  sessionId: string;
  name: string;
  label: string;
}

export interface ServerSkillEndEvent {
  type: 'skill_end';
  sessionId: string;
  name: string;
  status: string;
  result?: any;
  tokens?: any;
}

export interface ServerProgressEvent {
  type: 'progress';
  sessionId: string;
  name: string;
  step?: string;
  detail?: string;
  percent?: number;
}

export interface ServerTokenUpdateEvent {
  type: 'token_update';
  sessionId: string;
  input: number;
  output: number;
  total: number;
  apiCalls: number;
}
```

将新类型加入 `ServerEvent` 联合类型。

- [ ] **Step 2: 更新 Gateway 的 handleChat 方法**

在 `packages/backend/src/modules/netaclaw/gateway/server.ts` 中：

1. 注入 `NetaClawAgentService`
2. `handleChat` 方法签名增加 `agentId?: number` 参数
3. 如果有 agentId，从数据库读取 Agent 配置（systemPrompt, modelConfig, skills, config）
4. 用 Agent 的 modelConfig 构建 agentConfig（apiUrl, apiKey, modelId）
5. 用 Agent 的 systemPrompt + skills 构建系统提示
6. 用 Agent 的 config.middleware.maxToolRounds 设置最大工具轮次

关键改动：
```typescript
// 注入
@Inject()
agentService: NetaClawAgentService;

// handleChat 中
private async handleChat(sessionId: string, content: string, agentName?: string, agentId?: number) {
  // ... 现有的会话创建逻辑 ...

  let agentConfig: AgentConfig;
  if (agentId) {
    const agentInfo = await this.agentService.info(agentId);
    if (agentInfo) {
      const mc = agentInfo.modelConfig || {};
      const cfg = (agentInfo.config || {}) as any;
      const skillNames = agentInfo.skills || [];
      const skillPrompt = this.skillLoader.getSkillPrompt(skillNames);
      agentConfig = {
        name: agentInfo.name,
        systemPrompt: (agentInfo.systemPrompt || '') + skillPrompt,
        model: mc.modelId ? `openai:${mc.modelId}` : (process.env.NETACLAW_MODEL ?? 'anthropic:claude-sonnet-4-20250514'),
        apiKey: mc.apiKey || process.env.NETACLAW_API_KEY || '',
        baseUrl: mc.apiUrl,
        maxToolRounds: cfg?.middleware?.maxToolRounds ?? 20,
      };
    }
  }
  // 如果没有 agentId 或找不到 Agent，使用默认配置（现有逻辑）
  if (!agentConfig) {
    agentConfig = { /* 现有默认配置 */ };
  }
  // ... 后续 runAgent 调用不变 ...
}
```

同时更新 `onMessage` 中传递 `msg.agentId`。

- [ ] **Step 3: 验证 WS 连接**

用 WebSocket 客户端工具连接 `ws://localhost:8003/netaclaw`，发送：
```json
{"type":"chat","sessionId":"","content":"你好","agentId":null}
```
Expected: 收到 token/done 事件

- [ ] **Step 4: Commit**

```bash
git add packages/backend/src/modules/netaclaw/gateway/protocol.ts packages/backend/src/modules/netaclaw/gateway/server.ts
git commit -m "feat(netaclaw): enhance WS gateway with agentId support and new event types"
```

---

### Task 8: 前端 — 更新类型定义和 WebSocket 工具

**Files:**
- Modify: `packages/frontend/src/modules/agent/types/index.d.ts`
- Create: `packages/frontend/src/modules/agent/hooks/websocket.ts`

- [ ] **Step 1: 更新类型定义**

在 `packages/frontend/src/modules/agent/types/index.d.ts` 中：

新增 WebSocket 事件类型（替代 SSEEvent）：
```typescript
/**
 * WebSocket 客户端消息
 */
export interface WSClientMessage {
  type: 'chat' | 'ping';
  sessionId?: string;
  content?: string;
  agentId?: number;
}

/**
 * WebSocket 服务端事件
 */
export interface WSServerEvent {
  type: 'token' | 'thinking' | 'tool_call' | 'tool_result' | 'skill_start' | 'skill_end' | 'progress' | 'token_update' | 'done' | 'error' | 'pong';
  sessionId?: string;
  [key: string]: any;
}
```

- [ ] **Step 2: 创建 WebSocket 连接管理 Hook**

```typescript
// packages/frontend/src/modules/agent/hooks/websocket.ts
import { ref, onUnmounted } from 'vue';
import { config } from '/@/config';
import type { WSClientMessage, WSServerEvent } from '../types/index.d';

/**
 * NetaClaw WebSocket 连接管理
 */
export function useNetaClawWS() {
  const connected = ref(false);
  let ws: WebSocket | null = null;
  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
  let reconnectAttempts = 0;
  const MAX_RECONNECT_ATTEMPTS = 10;
  const handlers = new Set<(event: WSServerEvent) => void>();

  function getWsUrl(): string {
    const base = config.baseUrl || `http://localhost:8003`;
    const url = new URL(base);
    const protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
    return `${protocol}//${url.host}/netaclaw`;
  }

  function connect() {
    if (ws?.readyState === WebSocket.OPEN) return;
    try {
      ws = new WebSocket(getWsUrl());
      ws.onopen = () => {
        connected.value = true;
        reconnectAttempts = 0;
        startHeartbeat();
      };
      ws.onmessage = (e) => {
        try {
          const event: WSServerEvent = JSON.parse(e.data);
          if (event.type === 'pong') return;
          handlers.forEach(h => h(event));
        } catch { /* ignore */ }
      };
      ws.onclose = () => {
        connected.value = false;
        stopHeartbeat();
        scheduleReconnect();
      };
      ws.onerror = () => {
        ws?.close();
      };
    } catch { /* ignore */ }
  }

  function send(msg: WSClientMessage) {
    if (ws?.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify(msg));
    }
  }

  function onEvent(handler: (event: WSServerEvent) => void) {
    handlers.add(handler);
    return () => handlers.delete(handler);
  }

  function startHeartbeat() {
    stopHeartbeat();
    heartbeatTimer = setInterval(() => {
      send({ type: 'ping' });
    }, 30000);
  }

  function stopHeartbeat() {
    if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
  }

  function scheduleReconnect() {
    if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) return;
    const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
    reconnectAttempts++;
    reconnectTimer = setTimeout(() => connect(), delay);
  }

  function disconnect() {
    stopHeartbeat();
    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
    reconnectAttempts = MAX_RECONNECT_ATTEMPTS; // 阻止自动重连
    ws?.close();
    ws = null;
    connected.value = false;
  }

  return { connected, connect, disconnect, send, onEvent };
}
```

- [ ] **Step 3: Commit**

```bash
git add packages/frontend/src/modules/agent/types/index.d.ts packages/frontend/src/modules/agent/hooks/websocket.ts
git commit -m "feat(frontend): add WebSocket hook and types for NetaClaw migration"
```

---

### Task 9: 前端 — 改造 Store（SSE → WebSocket）

**Files:**
- Modify: `packages/frontend/src/modules/agent/store/chat.ts`

- [ ] **Step 1: 重写 store，将 SSE 替换为 WebSocket**

核心改动：
1. 导入 `useNetaClawWS` 替代 fetch SSE
2. API 路径从 `/open/agent/*` 改为 `/open/netaclaw/*`（管理接口从 `/admin/agent/*` 改为 `/admin/netaclaw/*`）
3. `sendMessage()` 改为通过 WS 发送 `{type:'chat', sessionId, content, agentId}`
4. 新增 `initWS()` 方法建立 WS 连接并注册事件处理
5. WS 事件处理复用现有的 `handleSSEEvent` 逻辑（重命名为 `handleWSEvent`），映射关系：
   - WS `token` → 追加 content（`event.content`）
   - WS `thinking` → 追加 thinking（`event.content`）
   - WS `tool_call` → 记录（`event.toolName`, `event.args`）
   - WS `skill_start` → 添加 skillProgress
   - WS `skill_end` → 完成 skillProgress
   - WS `progress` → 更新 skillProgress
   - WS `token_update` → 更新 runningTokenUsage
   - WS `done` → 标记完成（`event.sessionId`, `event.usage`）
   - WS `error` → 显示错误（`event.message`）
6. 移除 `checkExecutionStatus()`、`reconnectToExecution()`、`loadContextTokens()` 方法（WS 自动处理）
7. `stopGeneration()` 改为发送 WS 取消消息或直接断开重连
8. 会话管理 API 路径替换：
   - `loadMessages`: `/open/netaclaw/session/messages`
   - `loadSessions`: `/open/netaclaw/session/list`
   - `deleteSession`: `/open/netaclaw/session/delete`
   - `deleteAllSessions`: `/open/netaclaw/session/deleteAll`
   - `loadAgents`: `/open/netaclaw/agent/list`

关键代码结构：
```typescript
const BASE_OPEN = '/open/netaclaw';
const BASE_ADMIN = '/admin/netaclaw';

// WS 实例（store 级别单例）
let wsInstance: ReturnType<typeof useNetaClawWS> | null = null;
let wsCleanup: (() => void) | null = null;

function initWS() {
  if (wsInstance) return;
  wsInstance = useNetaClawWS();
  wsInstance.connect();
  wsCleanup = wsInstance.onEvent(handleWSEvent);
}

async function sendMessage(content: string) {
  if (!content.trim() || loading.value) return;
  initWS();
  // 添加用户消息 + 空助手消息占位（同现有逻辑）
  // ...
  loading.value = true;
  wsInstance.send({
    type: 'chat',
    sessionId: sessionId.value || undefined,
    content: content.trim(),
    agentId: currentAgentId.value || undefined,
  });
}

function handleWSEvent(event: WSServerEvent) {
  if (!loading.value && event.type !== 'done') return;
  const assistantMsg = messages.value[messages.value.length - 1];
  if (!assistantMsg || assistantMsg.role !== 'assistant') return;

  switch (event.type) {
    case 'token':
      assistantMsg.content += event.content;
      _onTokenCbs.forEach(cb => cb());
      break;
    case 'thinking':
      if (!assistantMsg.thinking) assistantMsg.thinking = '';
      assistantMsg.thinking += event.content;
      _onTokenCbs.forEach(cb => cb());
      break;
    case 'done':
      if (event.sessionId) sessionId.value = event.sessionId;
      loading.value = false;
      loadSessions();
      recalcSessionTokens();
      setTimeout(() => { skillProgress.value = []; }, 3000);
      break;
    case 'error':
      assistantMsg.content += `\n\n**错误**: ${event.message}`;
      loading.value = false;
      break;
    // skill_start, skill_end, progress, token_update 同现有逻辑
  }
}
```

- [ ] **Step 2: 验证 Store 编译通过**

Run: `cd packages/frontend && npx vue-tsc --noEmit`
Expected: 无类型错误

- [ ] **Step 3: Commit**

```bash
git add packages/frontend/src/modules/agent/store/chat.ts
git commit -m "feat(frontend): migrate chat store from SSE to WebSocket"
```

---

### Task 10: 前端 — 改造 hooks/chat.ts

**Files:**
- Modify: `packages/frontend/src/modules/agent/hooks/chat.ts`

- [ ] **Step 1: 同步改造 chat hook**

与 store 相同的改造逻辑：
1. API 路径从 `/open/agent/*` 改为 `/open/netaclaw/*`
2. `sendMessage()` 改为通过 WS 发送
3. 事件处理从 SSE 改为 WS
4. 移除 SSE 相关的 fetch/reader/decoder 逻辑

注意：这个 hook 和 store 功能重叠，如果 store 已经覆盖所有场景，可以将 hook 简化为直接调用 store 的方法。

- [ ] **Step 2: Commit**

```bash
git add packages/frontend/src/modules/agent/hooks/chat.ts
git commit -m "feat(frontend): migrate chat hook from SSE to WebSocket"
```

---

### Task 11: 前端 — 改造管理页面 API 路径

**Files:**
- Modify: `packages/frontend/src/modules/agent/views/agent-list.vue`
- Modify: `packages/frontend/src/modules/agent/views/agent-edit.vue`
- Modify: `packages/frontend/src/modules/agent/views/skills.vue`

- [ ] **Step 1: 改造 agent-list.vue**

全局替换 API 路径：
- `/admin/agent/info/page` → `/admin/netaclaw/agent/page`
- `/admin/agent/info/update` → `/admin/netaclaw/agent/update`
- `/admin/agent/info/delete` → `/admin/netaclaw/agent/delete`

- [ ] **Step 2: 改造 agent-edit.vue**

全局替换 API 路径：
- `/admin/agent/info/add` → `/admin/netaclaw/agent/add`
- `/admin/agent/info/update` → `/admin/netaclaw/agent/update`
- `/admin/agent/info/info` → `/admin/netaclaw/agent/info`
- `/admin/agent/skill/metas` → `/admin/netaclaw/skill/metas`

- [ ] **Step 3: 改造 skills.vue**

全局替换 API 路径：
- `/admin/agent/skill/metas` → `/admin/netaclaw/skill/metas`
- `/admin/agent/skill/setStatus` → `/admin/netaclaw/skill/setStatus`

- [ ] **Step 4: Commit**

```bash
git add packages/frontend/src/modules/agent/views/agent-list.vue packages/frontend/src/modules/agent/views/agent-edit.vue packages/frontend/src/modules/agent/views/skills.vue
git commit -m "feat(frontend): migrate agent/skill management pages to netaclaw API paths"
```

---

### Task 12: 前端 — 改造 chat.vue 对话页面

**Files:**
- Modify: `packages/frontend/src/modules/agent/views/chat.vue`

- [ ] **Step 1: 更新 API 路径**

- `/admin/agent/info/info` → `/admin/netaclaw/agent/info`
- `/admin/base/comm/upload` → 保持不变（通用上传接口）

- [ ] **Step 2: 确保 WS 连接在页面加载时建立**

在 `onMounted` 中调用 store 的 `initWS()` 或确保 store 初始化时自动连接。

- [ ] **Step 3: 验证对话功能**

启动前后端，在浏览器中：
1. 打开 Agent 对话页面
2. 发送一条消息
3. 确认收到流式回复（token 逐字输出）
4. 确认会话列表正确更新

- [ ] **Step 4: Commit**

```bash
git add packages/frontend/src/modules/agent/views/chat.vue
git commit -m "feat(frontend): migrate chat page to WebSocket communication"
```

---

### Task 13: 删除旧 Agent 模块代码和数据库表

**Files:**
- Delete: 旧 agent 相关 Entity 文件（如果存在）
- Database: DROP 旧表

- [ ] **Step 1: 查找并删除旧 agent Entity 文件**

搜索 `packages/backend/src/modules/` 下所有引用 `agent_info`、`agent_skill`、`agent_session`、`agent_message` 表名的 Entity 文件，删除它们。

同时搜索是否有旧的 Controller/Service 引用这些 Entity，一并删除。

- [ ] **Step 2: 删除旧数据库表**

用 MySQL MCP 工具执行：
```sql
DROP TABLE IF EXISTS agent_info;
DROP TABLE IF EXISTS agent_skill;
DROP TABLE IF EXISTS agent_session;
DROP TABLE IF EXISTS agent_message;
DROP TABLE IF EXISTS agent_checkpoints;
DROP TABLE IF EXISTS agent_checkpoint_writes;
DROP TABLE IF EXISTS agent_configs;
DROP TABLE IF EXISTS skill_configs;
```

- [ ] **Step 3: 验证后端启动正常**

Run: `cd packages/backend && npx midway-bin dev`
Expected: 启动成功，无报错

- [ ] **Step 4: Commit**

```bash
git add -A
git commit -m "chore: remove old agent module entities and drop legacy database tables"
```

---

### Task 14: 端到端联调验证

**Files:** 无新文件

- [ ] **Step 1: 验证 Agent 管理页面**

1. 打开 Agent 管理页面
2. 创建一个新 Agent（填写名称、描述、模型配置）
3. 编辑 Agent
4. 发布 Agent
5. 删除 Agent

- [ ] **Step 2: 验证 Skill 管理页面**

1. 打开 Skill 管理页面
2. 查看 Skill 列表
3. 启用/禁用 Skill

- [ ] **Step 3: 验证对话页面**

1. 选择一个已发布的 Agent
2. 发送消息，确认 WS 流式回复正常
3. 查看会话列表
4. 切换会话
5. 删除会话

- [ ] **Step 4: 验证数据库**

用 MySQL MCP 工具确认：
- `netaclaw_agent` 表有数据
- `netaclaw_session` 表有新会话
- `netaclaw_message` 表有消息
- 旧 `agent_*` 表已不存在

- [ ] **Step 5: 最终 Commit**

```bash
git add -A
git commit -m "feat(netaclaw): complete agent/skill management migration from old agent module"
```