citrus-code 0.1.0__tar.gz → 0.1.1__tar.gz

{citrus_code-0.1.0 → citrus_code-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: citrus-code
-Version: 0.1.0
+Version: 0.1.1
 Summary: A small Python coding agent inspired by pi, built as a learning project.
 Keywords: coding-agent,agent,cli,learning,deepseek
 License-Expression: MIT
@@ -20,6 +20,10 @@ Project-URL: Issues, https://github.com/big-orange947/citrus-code/issues
 Project-URL: Documentation, https://github.com/big-orange947/citrus-code#readme
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/big-orange947/citrus-code/main/assets/citrus-banner.svg" alt="Citrus Code：绿叶像素橘子，参考 pi 的 Python coding agent" width="960">
+</p>
+
 # Citrus Code
 
 **参考 pi 的核心设计，带初学者用 Python 一步步实现一个精简的 coding agent。**
@@ -49,6 +53,16 @@ Description-Content-Type: text/markdown
 
 本项目是学习实现，并非 pi 的官方 Python 移植版，也不承诺与其接口和功能完全一致。
 
+## 终端界面与项目标识
+
+Citrus Code 使用自己的绿叶像素橘子作为项目标识，README 和终端欢迎页采用同一角色与配色。
+可复用的透明背景图标位于 [assets/citrus-logo.svg](https://github.com/big-orange947/citrus-code/blob/main/assets/citrus-logo.svg)，页首横幅位于
+[assets/citrus-banner.svg](https://github.com/big-orange947/citrus-code/blob/main/assets/citrus-banner.svg)。终端角色直接由字符块绘制，运行时无需加载图片。
+
+CLI 提供居中的像素欢迎页、随输入内容增高的输入栏、闪烁块状光标，以及输入 `/` 时展开的命令列表。
+任务运行中显示旋转指示，助手回复支持 Markdown 和代码高亮，工具执行结果以卡片呈现。
+欢迎页使用独立终端屏幕，首次发送任务或命令后返回普通终端对话；最近的缩放重绘调整仍待实际交互确认。
+
 ## 当前进度
 
 | 模块 | 当前能力 |
@@ -56,7 +70,7 @@ Description-Content-Type: text/markdown
 | 消息类型 | 系统、用户、助手、工具结果消息；文字块、图片块与工具调用块 |
 | Provider 接口 | 统一模型信息和异步事件流，提供注册与查找 |
 | FakeProvider | 使用预设文字模拟流式响应，便于理解异步生成器 |
-| DeepSeek 接入 | HTTP 请求、SSE 读取、非思考模式、Flash 图片输入、用量统计和错误事件 |
+| DeepSeek 接入 | HTTP 请求、SSE 读取、非思考模式、Flash 图片输入、临时错误退避重试、用量统计和错误事件 |
 | 工具调用解析 | 按索引拼接多个工具调用的参数，转换成统一工具事件 |
 | 生成截断处理 | 默认输出上限 32,768 tokens；回复被截断时不执行该回复中的工具调用 |
 | 完整回答接口 | `complete()` 消费事件流并返回最终助手消息 |
@@ -66,22 +80,25 @@ Description-Content-Type: text/markdown
 | coding 工具 | read、write、edit、bash、powershell、grep、find、ls |
 | 输出控制 | read/命令输出按 2000 行或 50KB 截断；搜索工具提供数量和字节限制 |
 | 工具运行器 | 按名称查找工具，将执行结果或异常转换成工具结果消息 |
+| 工具执行操作 | 文件、命令和搜索后端可替换；默认本机执行，尚未接入沙箱 |
 | 会话存储 | JSONL 追加保存、加载校验、消息树与分支选择、当前分支上下文重建 |
 | CodingSession | 按事件保存消息、安全切换分支、取消与排队消息入口 |
 | CLI | 交互与单次任务、流式输出、运行中追加消息、会话恢复、末尾缺失工具结果修复 |
-| 终端展示 | 原创字符 π 标识、欢迎面板、多行输入、状态栏、Markdown 流式预览、代码高亮和工具结果卡片 |
+| 终端展示 | 原创像素块柑橘标识、简洁欢迎面板、横线输入栏与块状光标、命令提示列表、运行动画、Markdown 流式预览和工具结果卡片 |
 | 项目指令 | 启动时读取工作目录下的 AGENTS.md，通过模型前 Hook 组装当前请求 |
 | 上下文压缩 | 估计达到 600,000 tokens 时生成摘要，保留当前要求及近期完整交互，保存压缩记录 |
 
 工具名称、主要参数和默认组合参考 pi。实现细节、系统程序依赖、图片能力和取消处理的边界见 [工具说明](https://github.com/big-orange947/citrus-code/blob/main/docs/tools.md)。
 
+可替换执行操作的接口与使用方式见 [工具后端说明](https://github.com/big-orange947/citrus-code/blob/main/docs/tool-operations.md)，从 `0.1.1` 起提供。
+
 会话存储的接口、文件格式和恢复边界见 [会话说明](https://github.com/big-orange947/citrus-code/blob/main/docs/sessions.md)。带自动保存的任务通过 `CodingSession.prompt()` 运行。命令入口见 [CLI 使用说明](https://github.com/big-orange947/citrus-code/blob/main/docs/cli.md)。
 
 自动压缩策略与失败边界见 [上下文压缩说明](https://github.com/big-orange947/citrus-code/blob/main/docs/compaction.md)。当前固定假设模型支持 1,000,000 tokens；估计达到 60% 时压缩。摘要调用会消耗模型额度。
 
 ## 快速开始
 
-当前版本从源码安装，需要 Python 3.12 或更新版本，以及 [uv](https://docs.astral.sh/uv/)。
+要体验仓库中的最新功能，可以从源码安装，需要 Python 3.12 或更新版本，以及 [uv](https://docs.astral.sh/uv/)。
 先克隆仓库并安装锁定的依赖：
 
 ```powershell
@@ -106,7 +123,7 @@ uv run citrus --cwd "D:\project\your-project"
 
 ## 安装发行版
 
-需要 Python 3.12 或更新版本。以下命令安装已经发布到 PyPI 的版本；首次发布前请使用上方的源码安装方式。安装包名为 `citrus-code`，启动命令为 `citrus`。
+需要 Python 3.12 或更新版本。以下命令从 PyPI 安装最新发行版。`0.1.1` 加入了新版界面、模型请求自动重试和可替换工具后端。安装包名为 `citrus-code`，启动命令为 `citrus`。
 
 使用 uv 安装：
 
@@ -123,6 +140,16 @@ pipx install citrus-code
 python -m pip install citrus-code
 ```
 
+已有安装可按自己的安装方式升级：
+
+```powershell
+uv tool upgrade citrus-code
+# 或
+pipx upgrade citrus-code
+# 或
+python -m pip install --upgrade citrus-code
+```
+
 在 PowerShell 中配置自己的模型密钥并启动：
 
 ```powershell
@@ -157,6 +184,8 @@ uv run citrus --resume
 
 输入框中 Enter 发送，Alt+Enter 或 Ctrl+J 换行，Tab 补全命令。助手回答支持 Markdown；较长的工具结果默认只展示预览，使用 `--verbose` 启动可查看完整工具返回。升级依赖前先退出正在运行的旧 CLI，避免 Windows 锁住启动程序。
 
+输入 `/` 自动展开带说明的命令列表。输入区使用上下横线和闪烁块状光标，运行时持续显示旋转指示。模型临时断流、超时和部分 HTTP 错误最多自动重试 3 次，默认等待 2、4、8 秒；失败尝试的临时回复清除，已完成的工具结果保留，重试等待可用 Ctrl+C 取消。
+
 | 操作 | 命令或按键 |
 | --- | --- |
 | 查看帮助 | `/help` |
@@ -219,6 +248,7 @@ citrus --cwd "D:\project\poirot" --resume latest --max-output-tokens 65536
 
 ```text
 citrus-code/
+├── assets/                       # 像素橘子图标与 README 品牌横幅
 ├── src/citrus_code/
 │   ├── config.py                 # 从环境变量加载连接配置
 │   ├── __main__.py               # python -m citrus_code 入口
@@ -263,6 +293,8 @@ citrus-code/
 │       │   └── recovery.py       # 为缺失结果补充执行状态未知记录
 │       └── tools/                # 具体 coding 工具
 │           ├── factory.py        # 默认、只读和全部工具组合
+│           ├── operations.py     # 文件、命令与搜索的接口
+│           ├── local_files.py / local_shell.py / local_search.py
 │           ├── read.py / write.py
 │           ├── edit.py / edit_text.py
 │           ├── bash.py / powershell.py / shell.py
@@ -375,8 +407,9 @@ Windows 上如需使用 PowerShell，可添加 `--shell powershell`。上述示
 | 10 | `coding/tools/` | `coding_tools.py`、`coding_agent.py` | pi 风格工具、精确修改和输出控制 |
 | 11 | `coding/session/` | `session_storage.py` | 消息树、追加存储、加载与分支恢复 |
 | 12 | `coding/coding_session.py`、`coding/history.py`、`cli/` | `uv run citrus --fake` | 按事件保存、取消、消息队列与终端交互 |
-| 13 | `coding/project_context.py`、`coding/context_hooks.py`、`cli/prompts.py` | CLI 启动时显示项目指令来源 | 项目约定、系统提示组装与历史消息的区别 |
+| 13 | `coding/project_context.py`、`coding/context_hooks.py`、`cli/prompts.py` | 在工作目录中添加 AGENTS.md 后启动 CLI | 项目约定、系统提示组装与历史消息的区别 |
 | 14 | `coding/compaction/`、`coding/session/projection.py`、`agent/context.py` | 见上下文压缩说明 | 安全边界、完整工具交互、摘要与原始历史的区别 |
+| 15 | `coding/tools/operations.py`、`local_*.py`、`factory.py` | `tool_operations.py` | 工具定义与执行环境分离、Protocol 和可替换实现 |
 
 上表中的源码路径以 `src/citrus_code/` 为基准，示例路径以 `examples/` 为基准。早期原型位于 `examples/prototype/`，仅保留作学习对照，不作为当前版本入口。
 
@@ -389,6 +422,8 @@ Windows 上如需使用 PowerShell，可添加 `--shell powershell`。上述示
 - [x] Hooks：模型调用前后、工具执行前后的扩展点。
 - [x] 写入、精确编辑、搜索和命令执行工具。
 - [x] 工具输出截断与命令超时处理。
+- [x] 文件、命令和搜索的可替换执行操作接口。
+- [ ] 容器或其他隔离环境的执行适配器。
 - [x] Agent 主动取消与嵌套事件流关闭。
 - [ ] 工具增量事件。
 - [x] 第一版 CLI 交互与终端流式展示代码。

{citrus_code-0.1.0 → citrus_code-0.1.1}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/big-orange947/citrus-code/main/assets/citrus-banner.svg" alt="Citrus Code：绿叶像素橘子，参考 pi 的 Python coding agent" width="960">
+</p>
+
 # Citrus Code
 
 **参考 pi 的核心设计，带初学者用 Python 一步步实现一个精简的 coding agent。**
@@ -27,6 +31,16 @@
 
 本项目是学习实现，并非 pi 的官方 Python 移植版，也不承诺与其接口和功能完全一致。
 
+## 终端界面与项目标识
+
+Citrus Code 使用自己的绿叶像素橘子作为项目标识，README 和终端欢迎页采用同一角色与配色。
+可复用的透明背景图标位于 [assets/citrus-logo.svg](https://github.com/big-orange947/citrus-code/blob/main/assets/citrus-logo.svg)，页首横幅位于
+[assets/citrus-banner.svg](https://github.com/big-orange947/citrus-code/blob/main/assets/citrus-banner.svg)。终端角色直接由字符块绘制，运行时无需加载图片。
+
+CLI 提供居中的像素欢迎页、随输入内容增高的输入栏、闪烁块状光标，以及输入 `/` 时展开的命令列表。
+任务运行中显示旋转指示，助手回复支持 Markdown 和代码高亮，工具执行结果以卡片呈现。
+欢迎页使用独立终端屏幕，首次发送任务或命令后返回普通终端对话；最近的缩放重绘调整仍待实际交互确认。
+
 ## 当前进度
 
 | 模块 | 当前能力 |
@@ -34,7 +48,7 @@
 | 消息类型 | 系统、用户、助手、工具结果消息；文字块、图片块与工具调用块 |
 | Provider 接口 | 统一模型信息和异步事件流，提供注册与查找 |
 | FakeProvider | 使用预设文字模拟流式响应，便于理解异步生成器 |
-| DeepSeek 接入 | HTTP 请求、SSE 读取、非思考模式、Flash 图片输入、用量统计和错误事件 |
+| DeepSeek 接入 | HTTP 请求、SSE 读取、非思考模式、Flash 图片输入、临时错误退避重试、用量统计和错误事件 |
 | 工具调用解析 | 按索引拼接多个工具调用的参数，转换成统一工具事件 |
 | 生成截断处理 | 默认输出上限 32,768 tokens；回复被截断时不执行该回复中的工具调用 |
 | 完整回答接口 | `complete()` 消费事件流并返回最终助手消息 |
@@ -44,22 +58,25 @@
 | coding 工具 | read、write、edit、bash、powershell、grep、find、ls |
 | 输出控制 | read/命令输出按 2000 行或 50KB 截断；搜索工具提供数量和字节限制 |
 | 工具运行器 | 按名称查找工具，将执行结果或异常转换成工具结果消息 |
+| 工具执行操作 | 文件、命令和搜索后端可替换；默认本机执行，尚未接入沙箱 |
 | 会话存储 | JSONL 追加保存、加载校验、消息树与分支选择、当前分支上下文重建 |
 | CodingSession | 按事件保存消息、安全切换分支、取消与排队消息入口 |
 | CLI | 交互与单次任务、流式输出、运行中追加消息、会话恢复、末尾缺失工具结果修复 |
-| 终端展示 | 原创字符 π 标识、欢迎面板、多行输入、状态栏、Markdown 流式预览、代码高亮和工具结果卡片 |
+| 终端展示 | 原创像素块柑橘标识、简洁欢迎面板、横线输入栏与块状光标、命令提示列表、运行动画、Markdown 流式预览和工具结果卡片 |
 | 项目指令 | 启动时读取工作目录下的 AGENTS.md，通过模型前 Hook 组装当前请求 |
 | 上下文压缩 | 估计达到 600,000 tokens 时生成摘要，保留当前要求及近期完整交互，保存压缩记录 |
 
 工具名称、主要参数和默认组合参考 pi。实现细节、系统程序依赖、图片能力和取消处理的边界见 [工具说明](https://github.com/big-orange947/citrus-code/blob/main/docs/tools.md)。
 
+可替换执行操作的接口与使用方式见 [工具后端说明](https://github.com/big-orange947/citrus-code/blob/main/docs/tool-operations.md)，从 `0.1.1` 起提供。
+
 会话存储的接口、文件格式和恢复边界见 [会话说明](https://github.com/big-orange947/citrus-code/blob/main/docs/sessions.md)。带自动保存的任务通过 `CodingSession.prompt()` 运行。命令入口见 [CLI 使用说明](https://github.com/big-orange947/citrus-code/blob/main/docs/cli.md)。
 
 自动压缩策略与失败边界见 [上下文压缩说明](https://github.com/big-orange947/citrus-code/blob/main/docs/compaction.md)。当前固定假设模型支持 1,000,000 tokens；估计达到 60% 时压缩。摘要调用会消耗模型额度。
 
 ## 快速开始
 
-当前版本从源码安装，需要 Python 3.12 或更新版本，以及 [uv](https://docs.astral.sh/uv/)。
+要体验仓库中的最新功能，可以从源码安装，需要 Python 3.12 或更新版本，以及 [uv](https://docs.astral.sh/uv/)。
 先克隆仓库并安装锁定的依赖：
 
 ```powershell
@@ -84,7 +101,7 @@ uv run citrus --cwd "D:\project\your-project"
 
 ## 安装发行版
 
-需要 Python 3.12 或更新版本。以下命令安装已经发布到 PyPI 的版本；首次发布前请使用上方的源码安装方式。安装包名为 `citrus-code`，启动命令为 `citrus`。
+需要 Python 3.12 或更新版本。以下命令从 PyPI 安装最新发行版。`0.1.1` 加入了新版界面、模型请求自动重试和可替换工具后端。安装包名为 `citrus-code`，启动命令为 `citrus`。
 
 使用 uv 安装：
 
@@ -101,6 +118,16 @@ pipx install citrus-code
 python -m pip install citrus-code
 ```
 
+已有安装可按自己的安装方式升级：
+
+```powershell
+uv tool upgrade citrus-code
+# 或
+pipx upgrade citrus-code
+# 或
+python -m pip install --upgrade citrus-code
+```
+
 在 PowerShell 中配置自己的模型密钥并启动：
 
 ```powershell
@@ -135,6 +162,8 @@ uv run citrus --resume
 
 输入框中 Enter 发送，Alt+Enter 或 Ctrl+J 换行，Tab 补全命令。助手回答支持 Markdown；较长的工具结果默认只展示预览，使用 `--verbose` 启动可查看完整工具返回。升级依赖前先退出正在运行的旧 CLI，避免 Windows 锁住启动程序。
 
+输入 `/` 自动展开带说明的命令列表。输入区使用上下横线和闪烁块状光标，运行时持续显示旋转指示。模型临时断流、超时和部分 HTTP 错误最多自动重试 3 次，默认等待 2、4、8 秒；失败尝试的临时回复清除，已完成的工具结果保留，重试等待可用 Ctrl+C 取消。
+
 | 操作 | 命令或按键 |
 | --- | --- |
 | 查看帮助 | `/help` |
@@ -197,6 +226,7 @@ citrus --cwd "D:\project\poirot" --resume latest --max-output-tokens 65536
 
 ```text
 citrus-code/
+├── assets/                       # 像素橘子图标与 README 品牌横幅
 ├── src/citrus_code/
 │   ├── config.py                 # 从环境变量加载连接配置
 │   ├── __main__.py               # python -m citrus_code 入口
@@ -241,6 +271,8 @@ citrus-code/
 │       │   └── recovery.py       # 为缺失结果补充执行状态未知记录
 │       └── tools/                # 具体 coding 工具
 │           ├── factory.py        # 默认、只读和全部工具组合
+│           ├── operations.py     # 文件、命令与搜索的接口
+│           ├── local_files.py / local_shell.py / local_search.py
 │           ├── read.py / write.py
 │           ├── edit.py / edit_text.py
 │           ├── bash.py / powershell.py / shell.py
@@ -353,8 +385,9 @@ Windows 上如需使用 PowerShell，可添加 `--shell powershell`。上述示
 | 10 | `coding/tools/` | `coding_tools.py`、`coding_agent.py` | pi 风格工具、精确修改和输出控制 |
 | 11 | `coding/session/` | `session_storage.py` | 消息树、追加存储、加载与分支恢复 |
 | 12 | `coding/coding_session.py`、`coding/history.py`、`cli/` | `uv run citrus --fake` | 按事件保存、取消、消息队列与终端交互 |
-| 13 | `coding/project_context.py`、`coding/context_hooks.py`、`cli/prompts.py` | CLI 启动时显示项目指令来源 | 项目约定、系统提示组装与历史消息的区别 |
+| 13 | `coding/project_context.py`、`coding/context_hooks.py`、`cli/prompts.py` | 在工作目录中添加 AGENTS.md 后启动 CLI | 项目约定、系统提示组装与历史消息的区别 |
 | 14 | `coding/compaction/`、`coding/session/projection.py`、`agent/context.py` | 见上下文压缩说明 | 安全边界、完整工具交互、摘要与原始历史的区别 |
+| 15 | `coding/tools/operations.py`、`local_*.py`、`factory.py` | `tool_operations.py` | 工具定义与执行环境分离、Protocol 和可替换实现 |
 
 上表中的源码路径以 `src/citrus_code/` 为基准，示例路径以 `examples/` 为基准。早期原型位于 `examples/prototype/`，仅保留作学习对照，不作为当前版本入口。
 
@@ -367,6 +400,8 @@ Windows 上如需使用 PowerShell，可添加 `--shell powershell`。上述示
 - [x] Hooks：模型调用前后、工具执行前后的扩展点。
 - [x] 写入、精确编辑、搜索和命令执行工具。
 - [x] 工具输出截断与命令超时处理。
+- [x] 文件、命令和搜索的可替换执行操作接口。
+- [ ] 容器或其他隔离环境的执行适配器。
 - [x] Agent 主动取消与嵌套事件流关闭。
 - [ ] 工具增量事件。
 - [x] 第一版 CLI 交互与终端流式展示代码。

{citrus_code-0.1.0 → citrus_code-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "citrus-code"
-version = "0.1.0"
+version = "0.1.1"
 description = "A small Python coding agent inspired by pi, built as a learning project."
 readme = "README.md"
 license = "MIT"

{citrus_code-0.1.0 → citrus_code-0.1.1}/src/citrus_code/ai/events.py

@@ -62,6 +62,18 @@ class ErrorEvent(BaseModel):
     type: Literal["error"] = "error"
     reason: Literal["error", "aborted"]
     error: AssistantMessage
+    retryable: bool = False
+    retry_after_seconds: float | None = Field(default=None, ge=0)
+
+
+class RetryEvent(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["retry"] = "retry"
+    attempt: int = Field(ge=1)
+    max_retries: int = Field(ge=1)
+    delay_seconds: float = Field(ge=0)
+    error_message: str
 
 
 AssistantMessageEvent = Annotated[
@@ -73,6 +85,7 @@ AssistantMessageEvent = Annotated[
     | ToolCallDeltaEvent
     | ToolCallEndEvent
     | DoneEvent
+    | RetryEvent
     | ErrorEvent,
     Field(discriminator="type"),
-]
+]

{citrus_code-0.1.0 → citrus_code-0.1.1}/src/citrus_code/ai/providers/chat_completions.py

@@ -44,6 +44,10 @@ from .tool_call_buffer import ToolCallBuffer
 from .chat_stream_types import ChatStreamChunk
 
 
+class IncompleteStreamError(RuntimeError):
+    """The response ended before its required completion markers arrived."""
+
+
 def to_text(content: str | Iterable[TextContent | ImageContent]) -> str:
     if isinstance(content, str):
         return content
@@ -271,14 +275,14 @@ async def stream_chat_data(
 
                 data_lines.append(value)
 
-        raise RuntimeError(
+        raise IncompleteStreamError(
             "The chat stream ended without a [DONE] marker"
         )
 
 async def stream_assistant_events(
     model: ModelSpec,
     data_stream: AsyncIterator[str],
-) -> AsyncIterator[AssistantMessageEvent]:
+) -> AsyncGenerator[AssistantMessageEvent, None]:
     message = AssistantMessage(
         content=[],
         api=model.api,
@@ -399,7 +403,7 @@ async def stream_assistant_events(
                     finish_reason = choice.finish_reason
 
         if finish_reason is None:
-            raise RuntimeError(
+            raise IncompleteStreamError(
                 "The response ended without a finish reason"
             )
 
@@ -478,8 +482,26 @@ async def stream_assistant_events(
 
     except Exception as exc:
         message.stop_reason = "error"
+        retryable = isinstance(exc, (
+            httpx.TimeoutException, httpx.NetworkError,
+            httpx.RemoteProtocolError, IncompleteStreamError,
+        ))
+        retry_after: float | None = None
+        if isinstance(exc, httpx.HTTPStatusError):
+            retryable = exc.response.status_code in (408, 429, 500, 502, 503, 504)
+            header = exc.response.headers.get("Retry-After", "").strip()
+            if header.isascii() and header.isdigit():
+                retry_after = min(30.0, float(header))
         detail = str(exc).strip()
-        if isinstance(exc, httpx.ReadTimeout):
+        if isinstance(exc, (httpx.RemoteProtocolError, IncompleteStreamError)):
+            detail = (
+                "模型接口的流式响应未完整接收，连接就已中断。"
+                "可能与服务端、代理或网络有关，不能仅凭此错误确定具体来源。"
+                "此前已完成的工具操作不受影响；本条未完整回复中的工具调用未执行。"
+                "可以继续当前会话，先检查实际文件状态，再接着完成任务。"
+                f" 原始错误：{detail or '服务端响应传输不完整。'}"
+            )
+        elif isinstance(exc, httpx.ReadTimeout):
             detail = (
                 "等待模型响应数据超时（ReadTimeout）。"
                 "这是模型接口读取超时，不代表上一条工具命令失败。"
@@ -496,6 +518,8 @@ async def stream_assistant_events(
         yield ErrorEvent(
             reason="error",
             error=message,
+            retryable=retryable,
+            retry_after_seconds=retry_after,
         )
 
     finally:

{citrus_code-0.1.0 → citrus_code-0.1.1}/src/citrus_code/ai/providers/deepseek.py

@@ -4,6 +4,7 @@ import httpx
 from pydantic import SecretStr
 
 from ..events import AssistantMessageEvent
+from ..retry import stream_with_retries
 from ..types import (
     ImageContent, Message, ModelContext, ModelOptions, ModelSpec,
     TextContent, ToolResultMessage, UserMessage,
@@ -91,14 +92,11 @@ class DeepSeekProvider:
 
         body["thinking"] = {"type": "disabled"}
 
-        data_stream = stream_chat_data(
-            client=self._client,
-            model=model,
-            api_key=self._api_key,
-            body=body,
-        )
-
-        return stream_assistant_events(
-            model=model,
-            data_stream=data_stream,
+        return stream_with_retries(
+            lambda: stream_assistant_events(
+                model=model,
+                data_stream=stream_chat_data(
+                    client=self._client, model=model, api_key=self._api_key, body=body,
+                ),
+            ),
         )

citrus_code-0.1.1/src/citrus_code/ai/retry.py

@@ -0,0 +1,42 @@
+"""Retry an uncommitted model response; tool execution stays outside this layer."""
+
+import asyncio
+from collections.abc import AsyncGenerator, Callable
+from contextlib import aclosing
+
+from .events import AssistantMessageEvent, DoneEvent, ErrorEvent, RetryEvent
+
+
+async def stream_with_retries(
+    create_stream: Callable[[], AsyncGenerator[AssistantMessageEvent, None]],
+    *,
+    max_retries: int = 3,
+) -> AsyncGenerator[AssistantMessageEvent, None]:
+    if max_retries < 0:
+        raise ValueError("max_retries must not be negative")
+    for attempt in range(max_retries + 1):
+        failure: ErrorEvent | None = None
+        async with aclosing(create_stream()) as stream:
+            async for event in stream:
+                if isinstance(event, ErrorEvent):
+                    failure = event
+                    break
+                yield event
+                if isinstance(event, DoneEvent):
+                    return
+
+        if failure is None:
+            raise RuntimeError("The model stream ended without a terminal event")
+        if not failure.retryable or failure.reason != "error" or attempt == max_retries:
+            yield failure
+            return
+
+        delay = min(30.0, max(2.0 ** (attempt + 1), failure.retry_after_seconds or 0.0))
+        yield RetryEvent(
+            attempt=attempt + 1,
+            max_retries=max_retries,
+            delay_seconds=delay,
+            error_message=failure.error.error_message or "模型请求暂时失败",
+        )
+        # Cancellation propagates, including while waiting between attempts.
+        await asyncio.sleep(delay)

citrus_code-0.1.1/src/citrus_code/cli/commands.py

@@ -0,0 +1,59 @@
+"""Slash command descriptions shared by help and input completion."""
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from prompt_toolkit.completion import Completer, CompleteEvent, Completion
+from prompt_toolkit.document import Document
+
+
+@dataclass(frozen=True)
+class Command:
+    name: str
+    description: str
+    argument: str = ""
+
+    @property
+    def usage(self) -> str:
+        return f"{self.name} {self.argument}" if self.argument else self.name
+
+
+COMMANDS = (
+    Command("/help", "显示帮助"),
+    Command("/status", "查看运行状态、模型和消息队列"),
+    Command("/history", "显示当前分支的对话"),
+    Command("/tree", "列出会话节点与当前分支"),
+    Command("/checkout", "空闲且无排队消息时切换分支，支持唯一 ID 前缀", "<节点ID>"),
+    Command("/steer", "向正在运行的 Agent 追加引导消息", "<消息>"),
+    Command("/follow", "排队，等待 Agent 正常完成后处理", "<消息>"),
+    Command("/clear-queue", "清空尚未接纳的排队消息"),
+    Command("/recover", "空闲且无排队消息时补齐缺失的工具结果"),
+    Command("/abort", "取消当前任务，等待收尾"),
+    Command("/quit", "取消当前任务并退出"),
+    Command("/exit", "退出，等同于 /quit"),
+)
+
+
+def is_command_input(document: Document) -> bool:
+    return (
+        document.text.startswith("/")
+        and document.cursor_position == len(document.text)
+        and not any(character.isspace() for character in document.text)
+    )
+
+
+class SlashCommandCompleter(Completer):
+    def get_completions(
+        self, document: Document, complete_event: CompleteEvent,
+    ) -> Iterable[Completion]:
+        if not is_command_input(document):
+            return
+        prefix = document.text
+        for command in COMMANDS:
+            if command.name.startswith(prefix):
+                yield Completion(
+                    command.name,
+                    start_position=-len(prefix),
+                    display=command.usage,
+                    display_meta=command.description,
+                )

{citrus_code-0.1.0 → citrus_code-0.1.1}/src/citrus_code/cli/main.py

@@ -218,7 +218,8 @@ async def run_application(options: Options) -> int:
             raise ValueError("恢复时必须使用会话记录的模型，当前尚未提供模型切换入口")
         tools = create_tools(cwd, settings.tools)
         system_prompt = build_system_prompt(
-            cwd, settings.tools, context_files, supports_images=model.supports_images,
+            cwd, settings.tools, context_files,
+            model_id=model.id, supports_images=model.supports_images,
         )
         if options.resume is None:
             manager.save(path)
@@ -233,7 +234,7 @@ async def run_application(options: Options) -> int:
             max_turns=options.max_turns,
         )
         console.welcome(
-            cwd, model, settings.tools, path, [item.path for item in context_files],
+            cwd, model,
             fake=fake, resumed=options.resume is not None, interactive=options.prompt is None,
         )
         if recovered:

citrus_code-0.1.1/src/citrus_code/cli/output.py

@@ -0,0 +1,41 @@
+"""Flush Rich transcript output while the prompt renderer is suspended."""
+
+import asyncio
+from io import StringIO
+from typing import TextIO
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.application import run_in_terminal
+
+
+class TerminalOutput(StringIO):
+    def __init__(self, original: TextIO, prompt: PromptSession[str]) -> None:
+        super().__init__()
+        self.original = original
+        self.prompt = prompt
+        self._drain_lock = asyncio.Lock()
+
+    @property
+    def encoding(self) -> str:
+        return self.original.encoding or "utf-8"
+
+    def isatty(self) -> bool:
+        return self.original.isatty()
+
+    # Keep StringIO.fileno unsupported: Rich must not bypass the buffer via
+    # the Windows console handle while prompt_toolkit is drawing the input.
+    async def drain(self) -> None:
+        async with self._drain_lock:
+            text = self.getvalue()
+            if not text:
+                return
+            self.seek(0)
+            self.truncate(0)
+
+            def write() -> None:
+                output = self.prompt.app.output
+                output.enable_autowrap()
+                output.write_raw(text)
+                output.flush()
+
+            await run_in_terminal(write)