proxycast/docs/aiprompts/hooks.md

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

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

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

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

返回值

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

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

相关文档

• components.md - 组件系统
• commands.md - Tauri 命令