Question 1

为什么在 Next.js 开发模式并启用 React StrictMode 时，useCopilotAction 的 renderAndWaitForResponse 不渲染任何内容？

Accepted Answer

这是由 `@copilotkit/react-core` 1.53.x 及更早版本中的一个 StrictMode 重新挂载 bug 导致的。Provider 的受保护 effect 会用仅来自 props 的列表覆盖 hook 注册的 `renderToolCalls`，因此在 `next dev` 中 `useHumanInTheLoop` / `renderAndWaitForResponse` 的 UI 会缺失。请升级到 `@copilotkit/react-core` 1.54.0 或更高版本；已确认 1.54.1 可正常工作：`npm install @copilotkit/react-core@^1.54.1`。同时请将相关的 CopilotKit 包（如 `@copilotkitnext/react`）升级到兼容版本。作为临时解决方法，可以在 `next.config.js` 中通过 `reactStrictMode: false` 禁用 StrictMode；生产构建不受影响，因为它们不会双重调用 effect。

Question 2

如何修复在停止 CopilotKit 运行后，/connect 重放时出现的 ZodError "threadId Required, runId Required" 错误？

Accepted Answer

将 CopilotKit 升级到 v1.76.0 或更高版本。停止时生成的 `RUN_FINISHED` 事件现在会包含该次运行的 `threadId` 和 `runId`，因此在 `/connect` 重放期间能够通过 `@ag-ui/core` 的 schema 校验。

```bash
npm install @copilotkit/runtime@^1.76.0
# 将其他 @copilotkit/* 包更新到同一版本
```

如果暂时无法升级，可以重启内存态（in-memory）运行时，以丢弃已存储的无效事件。对于 SQLite 等持久化存储，请从运行历史中删除匹配的 `{"type":"RUN_FINISHED"}` 事件。源代码级别的临时解决方案是修补 `finalizeRunEvents`，使合成的 `RUN_FINISHED` 事件从对应的 `RUN_STARTED` 事件中复制 `threadId` 和 `runId`，而不是仅追加 `{ type: EventType.RUN_FINISHED }`。

Question 3

为什么在 CopilotKit A2UIProvider（@copilotkit/a2ui-renderer）中，dispatchAction 会在 onAction 完成之前就 resolve？

Accepted Answer

这是 `@copilotkit/a2ui-renderer`（v1.71.1）中的一个已知 bug：尽管 `OnActionCallback` 的类型声明为 `(message) => void | Promise<void>`，`A2UIProvider` 在调用 `onActionRef.current(message)` 时却没有返回其结果——无论是在 `MessageProcessor` 的 action 处理器中，还是在 surface 的 `dispatch` 方法中——导致 promise 被丢弃，`dispatchAction` 会立即 resolve。**修复方法：** 修改 `packages/a2ui-renderer/src/react-renderer/core/A2UIProvider.tsx`，在这两处都返回回调的结果：

```tsx
// MessageProcessor action 处理器
processorRef.current = new MessageProcessor([...], (action) => {
  if (onActionRef.current) {
    // ...构建 `message`
    return onActionRef.current(message);
  }
});

// dispatch
dispatch: (message: any) => onActionRef.current?.(message),
```

这对同步处理器来说是安全的。`@a2ui/web_core` 已经会传递该 promise（`SurfaceModel.dispatchAction` 会 await `onAction.emit(...)`，而 `EventEmitter.emit` 会 await 每个监听器），因此只需返回该值即可。**修复前的变通方案：** 直接使用一个独立的 `MessageProcessor`（不经过 `A2UIProvider`），让其 action 处理器返回你的异步 `onAction` promise——这样 `dispatchAction` 就能在处理器完成后正确 resolve。

Question 4

如何修复 LangGraph 中由 `ag_ui` 与 `ag-ui` 状态键不匹配导致的 CopilotKit A2UI 渲染失败问题?

Accepted Answer

LangGraph 可能会将带连字符的 `ag-ui` 状态键规范化为 `ag_ui`，而 CopilotKit 中间件只读取 `state["ag-ui"]`。这会导致找不到 `a2ui_schema` 和 `inject_a2ui_tool`，A2UI 工具不会被注入，组件可能被渲染为未知组件。

解决方法：在每个受影响的节点中，在 CopilotKit/A2UI 逻辑运行之前对状态键进行规范化：

```python
async def chat_node(state):
    if "ag_ui" in state and "ag-ui" not in state:
        state["ag-ui"] = state["ag_ui"]

# 现有的代理逻辑
    response = await model.ainvoke(state["messages"])
    return {"messages": [response]}
```

在子代理或任何读取 A2UI 状态的节点中应用相同的规范化。你可以通过以下方式验证实际的键：

```python
print("ag-ui" in state, "ag_ui" in state)
print(list(state.keys()))
```

受影响的配置包括 CopilotKit 0.1.94+、`ag-ui-langgraph` 0.0.40+ 和 LangGraph 1.1.0+。

Question 5

如何修复 PocketBase 的 'context deadline exceeded' 错误：启动检查能列出一条记录，但在统计所有记录时超时？

Accepted Answer

PocketBase 的 `list()` 方法默认会统计记录总数,即使 `perPage` 设置为 1 也不例外。在 `cvdiag_events` 这样约有 2360 万行的大表上,生成的 `SELECT COUNT(DISTINCT id)` 查询可能会超过 PocketBase 的 30 秒时限并返回 HTTP 400。

通过禁用总数统计来修复存在性检查:

```js
pb.list(collection, {
  perPage: 1,
  skipTotal: true,
});
```

将此应用于两个诊断集合的检查:

- `cvdiag_events`
- `cvdiag_raw_byte_samples`

在报告的预发布环境中,使用 `perPage=1&skipTotal=true` 的只读检查在 112 毫秒内完成。保持现有的健康、身份验证、集合缺失和权限检查不变。无需更改 schema、重试策略或增加超时时间。如果启动探测失败,`buildCvdiagPersistenceWriter()` 会禁用持久化诊断,事件将回退到 stdout,因此应将这条误导性的通用 `cvdiag.pb-writer.write-failed` 日志解读为启动时的读取/探测失败。

CopilotKit

项目简介

README 预览

常见问题 (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter