# React Hooks

## 概述

自定义 Hooks 封装业务逻辑；新代码应优先通过 `src/lib/api/*` 网关与后端通信，而不是直接在 Hook 中散落 `invoke`。

## 目录结构

```
src/hooks/
├── index.ts                # 导出入口
├── useProviderPool.ts      # 凭证池管理
├── useOAuthCredentials.ts  # OAuth 凭证
├── useFlowEvents.ts        # 流量事件
├── useMcpServers.ts        # MCP 服务器
├── useDeepLink.ts          # Deep Link 处理
└── useSound.ts             # 音效管理
```

## 治理约束

- 新的前端能力优先落在 `src/lib/api/*`，再由 Hook 或组件消费。
- 历史 `useTauri.ts` 兼容聚合层已删除，不要重新引入新的“大一统 API Hook”。
- Agent 工作台统一走 `src/components/agent/chat/hooks/index.ts` 暴露的 `useAgentChatUnified`，底层实现委托 `useAsterAgentChat`。
- 历史 `@/hooks/useUnifiedChat` 与 `src/lib/api/unified-chat.ts` 已删除，不要重建 compat Hook / API。

## 核心 Hooks

### useAgentChatUnified / useAsterAgentChat（现役 Agent 对话）

现役 Agent / Codex 工作台事实源：

- `useAgentChatUnified -> useAsterAgentChat -> useAgentContext / useAgentSession / useAgentTools / useAgentStream`
- 命令主链：`agent_runtime_submit_turn -> runtime items(plan / runtime_status / artifact / tool / action) -> action_required -> respond_action`
- 适用场景：Agent 工作台、任务执行、工具审批、timeline 渲染

**相关文件**：

- 统一入口：`src/components/agent/chat/hooks/index.ts`
- Hook 实现：`src/components/agent/chat/hooks/useAsterAgentChat.ts`
- API 封装：`src/lib/api/agentRuntime.ts`

### useProviderPool

```typescript
export function useProviderPool() {
  const [credentials, setCredentials] = useState<Credential[]>([]);
  const [loading, setLoading] = useState(false);

  const refresh = async () => {
    setLoading(true);
    const list = await invoke<Credential[]>("list_credentials");
    setCredentials(list);
    setLoading(false);
  };

  const addCredential = async (provider: string, path: string) => {
    await invoke("add_credential", { provider, filePath: path });
    await refresh();
  };

  const removeCredential = async (id: string) => {
    await invoke("remove_credential", { id });
    await refresh();
  };

  useEffect(() => {
    refresh();
  }, []);

  return { credentials, loading, addCredential, removeCredential, refresh };
}
```

### useFlowEvents

```typescript
export function useFlowEvents() {
  const [records, setRecords] = useState<FlowRecord[]>([]);

  useEffect(() => {
    const unlisten = listen<FlowEvent>("flow-event", (event) => {
      setRecords((prev) => [event.payload.data, ...prev].slice(0, 100));
    });

    return () => {
      unlisten.then((fn) => fn());
    };
  }, []);

  return { records };
}
```

### useDeepLink

```typescript
export function useDeepLink() {
  useEffect(() => {
    const unlisten = listen<string>("deep-link", async (event) => {
      const url = new URL(event.payload);

      if (url.pathname === "/oauth/callback") {
        await handleOAuthCallback(url.searchParams);
      }
    });

    return () => {
      unlisten.then((fn) => fn());
    };
  }, []);
}
```

## Hook 规范

### 命名约定

- 以 `use` 开头
- 描述功能: `useProviderPool`, `useFlowEvents`

### 返回值

```typescript
// 返回对象，包含状态和操作
return {
  // 状态
  data,
  loading,
  error,

  // 操作
  refresh,
  add,
  remove,
};
```

## 相关文档

- [components.md](components.md) - 组件系统
- [commands.md](commands.md) - Tauri 命令