Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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
+```