# @axiom-lattice/react-sdk 中文文档

规范地址：https://npmcn.com/package/%40axiom-lattice/react-sdk/

版本：10\.1\.0
npm 元数据更新时间：2026-11-03T01:45:19.179Z
中文译文更新时间：2026-11-07T16:50:35.078Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40axiom-lattice/react-sdk
原文对照：https://npmcn.com/package/%40axiom-lattice/react-sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：49.5 MB，1349 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.10\.0
- 运行依赖：31 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2025-09-01T12:45:08.291Z
- 最新版本发布：2026-11-03T01:45:19.003Z
- 近 30 天下载量：4412（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：218（近 12 个月 194 个）

## 中文简介

与 Axiom Lattice 代理服务器 API 交互的响应钩

## 安装

```sh
npm install @axiom-lattice/react-sdk
```

也可以使用：`pnpm add @axiom-lattice/react-sdk`、`yarn add @axiom-lattice/react-sdk`、`bun add @axiom-lattice/react-sdk`

## README

# Axiom Lattice 反应 SDK

与 Axiom Lattice 代理服务器 API 交互反应钩.

## 概览

这个软件包提供了将Axiom Lattice客户端SDK包裹起来的回放钩子,使得将代理能力融入到您的回放应用程序中变得容易. 它包括用于管理线程,发送和接收消息的钩子,监测代理状态等.

## 建筑

```mermaid
flowchart TD
    subgraph "Client SDK"
        ClientSDK["@axiom-lattice/client-sdk"]
        Client["Client Class"]
        ClientTypes["Types"]

        ClientSDK --> Client
        ClientSDK --> ClientTypes
    end

    subgraph "React SDK"
        ReactSDK["@axiom-lattice/react-sdk"]

        subgraph "Context"
            Provider["AxiomLatticeProvider"]
            useAxiomLattice["useAxiomLattice()"]
        end

        subgraph "Hooks"
            useThread["useThread()"]
            useChat["useChat()"]
            useAgentState["useAgentState()"]
            useAgentGraph["useAgentGraph()"]
        end

        ReactTypes["Types"]
        Examples["Example Components"]

        ReactSDK --> Provider
        ReactSDK --> useAxiomLattice
        ReactSDK --> useThread
        ReactSDK --> useChat
        ReactSDK --> useAgentState
        ReactSDK --> useAgentGraph
        ReactSDK --> ReactTypes
        ReactSDK --> Examples
    end

    Client --> useAxiomLattice
    useAxiomLattice --> useThread
    useAxiomLattice --> useChat
    useAxiomLattice --> useAgentState
    useAxiomLattice --> useAgentGraph

    subgraph "React Application"
        AppComponent["App Component"]
        ChatComponent["Chat Component"]
        ThreadList["Thread List"]
        StateMonitor["State Monitor"]
    end

    Provider --> AppComponent
    useThread --> ThreadList
    useChat --> ChatComponent
    useAgentState --> StateMonitor
```

## 安装

```bash
npm install @axiom-lattice/react-sdk
# or
yarn add @axiom-lattice/react-sdk
# or
pnpm add @axiom-lattice/react-sdk
```

## 特征

-   所有客户端 SDK 功能的反应钩
-   配置的反应上下文提供者
-   类型脚本支持
-   简化线索和信件的状态管理
-   用 React 状态更新来流化支持
-   专用外部代理 Web App 服务商、可复合部件组件和钩子

## 代理网络应用程序

从单独的入口导入外部出版集成, 并包含其样式表 :

```tsx
import { AgentWebAppProvider, WidgetComposer, WidgetMessageList } from "@axiom-lattice/react-sdk/web-app";
import "@axiom-lattice/react-sdk/web-app/styles.css";

interface PublishedAgentProps { currentUser: { id: string; name?: string } }

export function PublishedAgent({ currentUser }: PublishedAgentProps) {
  return (
    <AgentWebAppProvider
      gatewayUrl="http://localhost:4001"
      webAppId="support-web-app"
      identity={{ mode: "unverified", userId: currentUser.id, displayName: currentUser.name }}
    >
      <main>
        <WidgetMessageList />
        <WidgetComposer />
      </main>
    </AgentWebAppProvider>
  );
}
```

React and React DOM 18+是同级依赖关系. 编组部件使用捆绑的基于 Ant 设计的 UI 依赖性; 对于完整的 Console 聊天体验使用 `AgentChatApp` 从根入. Web App的代理,项目/模型允许列表,功能,外观都是被管理的服务器侧;浏览器道具无法扩展.

**警卫:** 当前 `userId` 以未经验证的浏览器头发送,并且可以冒充。 它只提供逻辑线程分组,而不是认证或安全隔离. 不要公开揭露敏感历史或特权代理人。 使用 [供应商整合移交](https://npmcn.com/package/docs/guides/web-apps/vendor-integration-handoff.md) 跨小组交付和完成 [代理网络应用程序文档](https://npmcn.com/package/docs/guides/web-apps/overview.md) 供参考.

## 使用量

### 提供者设置

首先,用 `AxiomLatticeProvider` 以提供客户端配置:

```tsx
import { AxiomLatticeProvider } from "@axiom-lattice/react-sdk";

function App() {
  return (
    <AxiomLatticeProvider
      config={{
        baseURL: "https://api.example.com",
        apiKey: "your-api-key",
        assistantId: "your-assistant-id",
        transport: "sse",
      }}
    >
      <YourApp />
    </AxiomLatticeProvider>
  );
}
```

### 线索管理

使用 `useThread` 管理线程的钩线 :

```tsx
import { useThread } from "@axiom-lattice/react-sdk";

function ThreadManager() {
  const {
    threads,
    currentThread,
    isLoading,
    error,
    createThread,
    getThread,
    listThreads,
    deleteThread,
    selectThread,
  } = useThread();

  useEffect(() => {
    // Load all threads on component mount
    listThreads();
  }, [listThreads]);

  const handleCreateThread = async () => {
    try {
      const threadId = await createThread();
      console.log(`Created thread: ${threadId}`);
    } catch (error) {
      console.error("Failed to create thread:", error);
    }
  };

  return (
    <div>
      <h2>Threads</h2>
      <button onClick={handleCreateThread} disabled={isLoading}>
        Create New Thread
      </button>

      {error && <div className="error">{error.message}</div>}

      <ul>
        {threads.map((thread) => (
          <li key={thread.id}>
            Thread #{thread.id.substring(0, 8)}
            <button onClick={() => selectThread(thread.id)}>Select</button>
            <button onClick={() => deleteThread(thread.id)}>Delete</button>
          </li>
        ))}
      </ul>

      {currentThread && (
        <div>
          <h3>Current Thread: {currentThread.id.substring(0, 8)}</h3>
        </div>
      )}
    </div>
  );
}
```

### 聊天功能

使用 `useChat` 发送和接收消息的钩钩 :

```tsx
import { useChat } from "@axiom-lattice/react-sdk";

function ChatInterface({ threadId }) {
  const {
    messages,
    streamingMessage,
    isLoading,
    error,
    sendMessage,
    stopStreaming,
    loadMessages,
  } = useChat(threadId, { streaming: true });

  const [inputValue, setInputValue] = useState("");

  const handleSend = async () => {
    if (!inputValue.trim()) return;

    try {
      await sendMessage(inputValue);
      setInputValue("");
    } catch (error) {
      console.error("Failed to send message:", error);
    }
  };

  return (
    <div>
      <div className="messages">
        {messages.map((message) => (
          <div key={message.id} className={`message ${message.role}`}>
            <div className="role">{message.role}</div>
            <div className="content">{message.content}</div>
          </div>
        ))}

        {streamingMessage && (
          <div className="message assistant streaming">
            <div className="role">assistant</div>
            <div className="content">{streamingMessage.content}</div>
          </div>
        )}
      </div>

      {error && <div className="error">{error.message}</div>}

      <div className="input-area">
        <input
          type="text"
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          disabled={isLoading}
          placeholder="Type your message..."
          onKeyDown={(e) => {
            if (e.key === "Enter") {
              handleSend();
            }
          }}
        />
        <button onClick={handleSend} disabled={isLoading}>
          Send
        </button>
        {isLoading && <button onClick={stopStreaming}>Stop</button>}
      </div>
    </div>
  );
}
```

### 国家监测

使用 `useAgentState` 监视代理状态的钩子 :

```tsx
import { useAgentState } from "@axiom-lattice/react-sdk";

function AgentStateMonitor({ threadId }) {
  const { agentState, isLoading, error, startPolling, stopPolling, refresh } =
    useAgentState(threadId, {
      pollingInterval: 3000,
      autoStart: true,
    });

  if (isLoading && !agentState) {
    return <div>Loading agent state...</div>;
  }

  if (error) {
    return <div className="error">Error: {error.message}</div>;
  }

  if (!agentState) {
    return <div>No agent state available</div>;
  }

  return (
    <div>
      <h3>Agent State</h3>
      <button onClick={refresh}>Refresh</button>
      <button onClick={startPolling}>Start Polling</button>
      <button onClick={stopPolling}>Stop Polling</button>

      <div>
        <h4>Messages</h4>
        <pre>{JSON.stringify(agentState.values.messages, null, 2)}</pre>
      </div>

      <div>
        <h4>Tasks</h4>
        <pre>{JSON.stringify(agentState.tasks, null, 2)}</pre>
      </div>
    </div>
  );
}
```

### 代理图形可视化

使用 `useAgentGraph` 抓取和显示代理图的钩子 :

```tsx
import { useAgentGraph } from "@axiom-lattice/react-sdk";

function AgentGraph() {
  const { graphImage, isLoading, error, fetchGraph } = useAgentGraph();

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

  if (isLoading && !graphImage) {
    return <div>Loading graph...</div>;
  }

  if (error) {
    return <div className="error">Error: {error.message}</div>;
  }

  return (
    <div>
      <h3>Agent Graph</h3>
      <button onClick={fetchGraph}>Refresh Graph</button>

      {graphImage && (
        <div className="graph-container">
          <img
            src={`data:image/svg+xml;base64,${graphImage}`}
            alt="Agent Graph"
          />
        </div>
      )}
    </div>
  );
}
```

### 文件浏览器组件

使用 `FileExplorer` 从代理状态显示和探索文件的组件 :

```tsx
import { FileExplorer, useChat } from "@axiom-lattice/react-sdk";

function AgentFiles({ threadId }) {
  // Ensure enableReturnStateWhenStreamCompleted is true to get the agent state
  const { agentState } = useChat(threadId, {
    streaming: true,
    enableReturnStateWhenStreamCompleted: true,
  });

  // Extract files from agent state values
  // Assuming agent returns files in agentState.values.files
  const files = agentState?.values?.files || [];

  return (
    <div style={{ height: "500px" }}>
      <h3>Agent Files</h3>
      <FileExplorer files={files} />
    </div>
  );
}
```

## 完整示例

见 `examples` 一个使用 React SDK 的聊天应用程序的完整示例的目录 .

## API 参考

### 钩子

-   `useThread`: 线索管理
-   `useChat`: 聊天功能
-   `useAgentState`: 代理状态监测
-   `useAgentGraph`: 代理图形可视化

### A. 背景情况

-   `AxiomLatticeProvider`: 客户端的提供者组件
-   `useAxiomLattice`: Hook 访问客户实例

## 捐款

欢迎捐款! 请随意提交拉力请求.

## 常见问题

### @axiom-lattice/react-sdk 是什么？

与 Axiom Lattice 代理服务器 API 交互的响应钩

### 如何安装 @axiom-lattice/react-sdk？

在项目目录运行 npm install @axiom-lattice/react-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @axiom-lattice/react-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @axiom-lattice/react-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @axiom-lattice/react-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.10\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @axiom-lattice/react-sdk 可以商用吗？

@axiom-lattice/react-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @axiom-lattice/react-sdk 的下载量有多少？

根据 npm 官方下载统计，@axiom-lattice/react-sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,412 次，日均约 147 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @axiom-lattice/react-sdk 还在维护吗？

最新版本 10\.1\.0 发布于 2026/11/03（4 天前）；至今共发布 218 个版本，其中过去 12 个月发布了 194 个；首次发布于 2025/09/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。