CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
docs(zh-Hans): sync recipe docs — add 运行示例 sections and resumable-tasks fix
xf gongb0eb5cc1bdcd
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/ask-user-form.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/ask-user-form.mdindex a9d299b..71b1f88 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/ask-user-form.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/ask-user-form.md@@ -180,3 +180,17 @@ async def main():asyncio.run(main())```++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/ask_user_form.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/ask_user_form.py)。+Host 循环以编程方式回答所有问题,无需接入真实 UI 即可观察完整的交互过程。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/ask_user_form.py+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/multi-provider-failover.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/multi-provider-failover.mdindex f4c72c2..7d9717f 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/multi-provider-failover.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/multi-provider-failover.md@@ -253,3 +253,17 @@ class CircuitBreaker:- [Providers / Anthropic](../guides/providers/anthropic) 和[OpenAI](../guides/providers/openai) —— provider 专属细节。- [编写自定义 Provider](../guides/providers/custom) —— 本封装器使用的同一 Protocol。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/multi_provider_failover.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/multi_provider_failover.py)。+示例故意使用错误的主 provider key 触发故障转移,再通过备用 provider 正确返回结果。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/multi_provider_failover.py+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/persistent-chat.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/persistent-chat.mdindex 5b10dce..06a3c86 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/persistent-chat.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/persistent-chat.md@@ -168,3 +168,19 @@ Postgres 适合多实例服务或大量并发用户 ——- [多轮对话](../guides/agents/multi-turn) —— `steer`、`follow_up`、`resume`。- [SQLite Checkpointing](../guides/checkpointing/sqlite) —— 后端详细说明。- [可恢复长任务](./resumable-tasks) —— 当崩溃发生在工具执行中途,而非轮次之间时。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/persistent_chat.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/persistent_chat.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync --extra sqlite++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/persistent_chat.py alice+# Ctrl-D 退出后重新运行 —— 历史记录会恢复。+uv run python examples/persistent_chat.py bob+# 不同的 thread_id → 全新对话。+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/postgres-fastapi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/postgres-fastapi.mdindex 4bcf6a5..abb3069 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/postgres-fastapi.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/postgres-fastapi.md@@ -246,3 +246,24 @@ curl -N -X POST http://localhost:8000/chat/conv1/messages \- [Postgres Checkpointing](../guides/checkpointing/postgres) —— 后端深度说明。- [持久化聊天](./persistent-chat) —— 使用 SQLite 的相同流程。- [多 Provider 故障转移](./multi-provider-failover) —— 与本服务结合以提升弹性。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/postgres_fastapi.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/postgres_fastapi.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync --extra postgres++export DATABASE_URL=postgresql://user:pass@localhost/cubepi+export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]++uv run --with fastapi --with "uvicorn[standard]" --with sse-starlette \+ uvicorn examples.postgres_fastapi:app --reload --port 8000++# 用 curl 测试:+curl -N -X POST http://localhost:8000/chat/conv1/messages \+ -H "content-type: application/json" \+ -d '{"text":"hi"}'+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/resumable-tasks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/resumable-tasks.mdindex 63031e5..35391ac 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/resumable-tasks.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/resumable-tasks.md@@ -121,6 +121,16 @@ async def main(thread_id: str, initial_prompt: str | None):# resume 从最后一条持久化消息继续:# ToolResultMessage / UserMessage → 重新调用模型# 没有排队 steer/follow_up 的 AssistantMessage → 抛出异常+ last = agent.state.messages[-1]+ if type(last).__name__ == "AssistantMessage":+ from cubepi.providers.base import ToolCall+ has_pending_tools = any(isinstance(c, ToolCall) for c in last.content)+ if not has_pending_tools:+ # 任务已正常完成,无待执行的工具调用。+ # 实际应用中可在此处提示用户输入下一条消息。+ print("上次运行已完成,无需恢复。")+ return+ # 存在未执行的工具调用 —— 交由 resume() 继续执行。await agent.resume()@@ -203,3 +213,21 @@ CubePi 不提供"持久化部分工具结果"的 API。预期的模式是:将—— 完整语义。- [持久化聊天](./persistent-chat) —— 更简单的可重启场景。- [SQLite Checkpointing](../guides/checkpointing/sqlite) —— 持久化内容与时机。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/resumable_tasks.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/resumable_tasks.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync --extra sqlite++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]++# 启动任务(可用 Ctrl-C 中途终止以测试恢复能力):+uv run python examples/resumable_tasks.py job-1 start++# 从中断处恢复 —— 已完成的条目会被跳过:+uv run python examples/resumable_tasks.py job-1+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/sandbox-confirm.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/sandbox-confirm.mdindex 0071388..3d1ff4d 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/sandbox-confirm.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/sandbox-confirm.md@@ -135,3 +135,17 @@ await agent.abort_pending(reason="user closed tab")这会干净地关闭对话:为所有未解决的 tool call 追加合成的 deny tool_result,持久化一个终止性的 `AssistantMessage(stop_reason="aborted")`,并触发`AgentAbortedEvent`。下一次 `agent.prompt(...)` 重新开始。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/sandbox_confirm.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/sandbox_confirm.py)。+示例接入了一个模拟的 bash 工具和一个策略函数:读操作自动允许、危险写操作硬拒绝、其他操作由 host 循环自动确认。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/sandbox_confirm.py+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/weather-agent.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/weather-agent.mdindex 5649106..95f69af 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/weather-agent.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/recipes/weather-agent.md@@ -146,3 +146,16 @@ Tokyo is currently 18°C with a wind speed of 12 km/h. São Paulo is 25°C with- [构建你的第一个 Agent](../guides/agents/first-agent) —— 使用硬编码工具的相同模式。- [工具使用与并行执行](../guides/agents/tool-use) —— 更多关于并行工具调用的内容。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/weather_agent.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/weather_agent.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run --with httpx python examples/weather_agent.py+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/ask-user-form.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/ask-user-form.mdindex a9d299b..71b1f88 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/ask-user-form.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/ask-user-form.md@@ -180,3 +180,17 @@ async def main():asyncio.run(main())```++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/ask_user_form.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/ask_user_form.py)。+Host 循环以编程方式回答所有问题,无需接入真实 UI 即可观察完整的交互过程。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/ask_user_form.py+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/multi-provider-failover.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/multi-provider-failover.mdindex 65357ee..c493239 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/multi-provider-failover.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/multi-provider-failover.md@@ -253,3 +253,17 @@ class CircuitBreaker:- [Providers / Anthropic](../guides/providers/anthropic) 和[OpenAI](../guides/providers/openai) —— provider 专属细节。- [编写自定义 Provider](../guides/providers/custom) —— 本封装器使用的同一 Protocol。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/multi_provider_failover.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/multi_provider_failover.py)。+示例故意使用错误的主 provider key 触发故障转移,再通过备用 provider 正确返回结果。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/multi_provider_failover.py+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/persistent-chat.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/persistent-chat.mdindex fd1b568..085664e 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/persistent-chat.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/persistent-chat.md@@ -168,3 +168,19 @@ Postgres 适合多实例服务或大量并发用户 ——- [多轮对话](../guides/agents/multi-turn) —— `steer`、`follow_up`、`resume`。- [SQLite Checkpointing](../guides/checkpointing/sqlite) —— 后端详细说明。- [可恢复长任务](./resumable-tasks) —— 当崩溃发生在工具执行中途,而非轮次之间时。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/persistent_chat.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/persistent_chat.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync --extra sqlite++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/persistent_chat.py alice+# Ctrl-D 退出后重新运行 —— 历史记录会恢复。+uv run python examples/persistent_chat.py bob+# 不同的 thread_id → 全新对话。+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/postgres-fastapi.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/postgres-fastapi.mdindex 0b6a8d1..dd9b73d 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/postgres-fastapi.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/postgres-fastapi.md@@ -246,3 +246,24 @@ curl -N -X POST http://localhost:8000/chat/conv1/messages \- [Postgres Checkpointing](../guides/checkpointing/postgres) —— 后端深度说明。- [持久化聊天](./persistent-chat) —— 使用 SQLite 的相同流程。- [多 Provider 故障转移](./multi-provider-failover) —— 与本服务结合以提升弹性。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/postgres_fastapi.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/postgres_fastapi.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync --extra postgres++export DATABASE_URL=postgresql://user:pass@localhost/cubepi+export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]++uv run --with fastapi --with "uvicorn[standard]" --with sse-starlette \+ uvicorn examples.postgres_fastapi:app --reload --port 8000++# 用 curl 测试:+curl -N -X POST http://localhost:8000/chat/conv1/messages \+ -H "content-type: application/json" \+ -d '{"text":"hi"}'+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/resumable-tasks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/resumable-tasks.mdindex f6b398b..ac43710 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/resumable-tasks.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/resumable-tasks.md@@ -121,6 +121,16 @@ async def main(thread_id: str, initial_prompt: str | None):# resume 从最后一条持久化消息继续:# ToolResultMessage / UserMessage → 重新调用模型# 没有排队 steer/follow_up 的 AssistantMessage → 抛出异常+ last = agent.state.messages[-1]+ if type(last).__name__ == "AssistantMessage":+ from cubepi.providers.base import ToolCall+ has_pending_tools = any(isinstance(c, ToolCall) for c in last.content)+ if not has_pending_tools:+ # 任务已正常完成,无待执行的工具调用。+ # 实际应用中可在此处提示用户输入下一条消息。+ print("上次运行已完成,无需恢复。")+ return+ # 存在未执行的工具调用 —— 交由 resume() 继续执行。await agent.resume()@@ -203,3 +213,21 @@ CubePi 不提供"持久化部分工具结果"的 API。预期的模式是:将—— 完整语义。- [持久化聊天](./persistent-chat) —— 更简单的可重启场景。- [SQLite Checkpointing](../guides/checkpointing/sqlite) —— 持久化内容与时机。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/resumable_tasks.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/resumable_tasks.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync --extra sqlite++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]++# 启动任务(可用 Ctrl-C 中途终止以测试恢复能力):+uv run python examples/resumable_tasks.py job-1 start++# 从中断处恢复 —— 已完成的条目会被跳过:+uv run python examples/resumable_tasks.py job-1+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/sandbox-confirm.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/sandbox-confirm.mdindex 0071388..3d1ff4d 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/sandbox-confirm.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/sandbox-confirm.md@@ -135,3 +135,17 @@ await agent.abort_pending(reason="user closed tab")这会干净地关闭对话:为所有未解决的 tool call 追加合成的 deny tool_result,持久化一个终止性的 `AssistantMessage(stop_reason="aborted")`,并触发`AgentAbortedEvent`。下一次 `agent.prompt(...)` 重新开始。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/sandbox_confirm.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/sandbox_confirm.py)。+示例接入了一个模拟的 bash 工具和一个策略函数:读操作自动允许、危险写操作硬拒绝、其他操作由 host 循环自动确认。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run python examples/sandbox_confirm.py+```diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/weather-agent.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/weather-agent.mdindex e529511..9570791 100644--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/weather-agent.md+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.8/recipes/weather-agent.md@@ -146,3 +146,16 @@ Tokyo is currently 18°C with a wind speed of 12 km/h. São Paulo is 25°C with- [构建你的第一个 Agent](../guides/agents/first-agent) —— 使用硬编码工具的相同模式。- [工具使用与并行执行](../guides/agents/tool-use) —— 更多关于并行工具调用的内容。++## 运行示例++仓库中有一份完整可运行的代码,位于+[`examples/weather_agent.py`](https://github.com/cubeplexai/cubepi/blob/main/examples/weather_agent.py)。++```bash+git clone https://github.com/cubeplexai/cubepi && cd cubepi+uv sync++export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY [+ OPENAI_BASE_URL]+uv run --with httpx python examples/weather_agent.py+```