Repository navigation
docs: 补充 --help 与主题适配说明 - #6
Merged
Merged
Conversation
- getting-started.md / user-guide.md / README.md 的运行章节补 命令行参数（-h/--help、--smoke-test）与 PYRAG_LIGHT/PYRAG_DARK 主题覆盖说明 - user-guide.md 的切换模型示例从过时的 google/openai（provider 名 而非配置 key）改为 llm_configurations 的实际 key，并补重载失败 自动回滚的说明（PR #3 落地的契约） Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configuration
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
审阅者指南（小型 PR 默认折叠）审阅者指南本 PR 仅更新三份用户文档，使新增的命令行入口、非交互自检、终端亮暗主题适配及强制覆盖方式与实际行为一致，并修正模型切换示例、补充重载失败自动回滚契约；不涉及代码或配置变更。 文档所述命令行启动模式流程图flowchart TD
Start["uv run main.py"] --> Args{"命令行参数"}
Args -->|"-h / --help"| Help["打印用法并退出"]
Args -->|"--smoke-test"| Smoke["执行非交互启动自检"]
Args -->|"无参数"| Menu["进入交互式主菜单"]
文档所述终端主题选择流程图flowchart TD
Start["程序启动"] --> Override{"强制主题环境变量"}
Override -->|"PYRAG_LIGHT=1"| Light["使用亮色主题"]
Override -->|"PYRAG_DARK=1"| Dark["使用暗色主题"]
Override -->|"未指定"| Detect["检测 COLORFGBG"]
Detect --> Theme["自动选择亮色或暗色主题"]
文件级变更
提示与命令与 Sourcery 互动
自定义你的使用体验访问你的控制面板以：
获取帮助Original review guide in EnglishReviewer's guide (collapsed on small PRs)Reviewer's Guide本 PR 仅更新三份用户文档，使新增的命令行入口、非交互自检、终端亮暗主题适配及强制覆盖方式与实际行为一致，并修正模型切换示例、补充重载失败自动回滚契约；不涉及代码或配置变更。 Flow diagram for documented command-line startup modesflowchart TD
Start["uv run main.py"] --> Args{"命令行参数"}
Args -->|"-h / --help"| Help["打印用法并退出"]
Args -->|"--smoke-test"| Smoke["执行非交互启动自检"]
Args -->|"无参数"| Menu["进入交互式主菜单"]
Flow diagram for documented terminal theme selectionflowchart TD
Start["程序启动"] --> Override{"强制主题环境变量"}
Override -->|"PYRAG_LIGHT=1"| Light["使用亮色主题"]
Override -->|"PYRAG_DARK=1"| Dark["使用暗色主题"]
Override -->|"未指定"| Detect["检测 COLORFGBG"]
Detect --> Theme["自动选择亮色或暗色主题"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
嘿——我发现了 2 个问题
给 AI 智能体的提示
请处理这次代码审查中的评论：
## 各条评论
### 评论 1
<location path="docs/user_guide/user-guide.md" line_range="64" />
<code_context>
* **混合搜索权重**: 当使用“混合检索”时，调整向量和关键词搜索结果的权重。
* **切换模型**:
- * **语言模型 (LLM)**: 动态切换当前对话使用的聊天模型（例如，从 `google` 切换到 `openai`）。切换后，程序会自动重载模型。
+ * **语言模型 (LLM)**: 动态切换当前对话使用的聊天模型（在 `config.toml` 中 `llm_configurations` 里定义的配置项之间切换，例如从 `gpt-5-6-sol` 切到 `deepseek-v4-flash`）。切换后，程序会自动重载模型；重载失败时自动回滚到原模型并提示。
* **重排模型 (Rerank)**: 切换用于精排的 Rerank 模型。
* **查看当前完整配置**: 显示所有当前生效的聊天和模型参数。
</code_context>
<issue_to_address>
**模型示例名称对应的选项缺失**
如果用户按照随附的 `config.toml.example` 中的示例操作，模型菜单会列出 `llm_configurations` 中的键，但示例使用了未定义的 `gpt-5-6-sol`；随附配置中的 OpenAI 键是 `openai`，其模型名称是 `gpt-5.6-sol`。因此，文档中介绍的选项不会出现在菜单中，也无法选择。
请将示例中的 OpenAI 配置键改为 `openai`。
</issue_to_address>
### 评论 2
<location path="README.md" line_range="110" />
<code_context>
uv run main.py
```
+命令行支持 `-h` / `--help`（查看用法）与 `--smoke-test`（非交互自检）；界面配色自动适配终端亮色 / 暗色主题，可用 `PYRAG_LIGHT=1` / `PYRAG_DARK=1` 强制指定。
+
3. 在主菜单中按需执行：
</code_context>
<issue_to_address>
**主题颜色仍有部分未改变**
用户可能会认为，主题覆盖或亮色终端检测会调整整个界面的配色。实际上，主题辅助函数只会更改提示和 questionary 指针的样式；包括启动横幅在内的其他界面颜色仍保持原样。因此，界面的适配范围没有文档所述的那么广。
请缩小文档描述的范围，说明主题适配仅适用于提示和 questionary 指针的样式，而非整个界面。
`docs/user_guide/getting-started.md:84` 和 `docs/user_guide/user-guide.md:9` 也有此问题。
</issue_to_address>Sourcery 评估
等待批准。 请先处理 2 项发现。
阻断性问题：docs/user_guide/user-guide.md:64、README.md:110
Original comment in English
Hey - I've found 2 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="docs/user_guide/user-guide.md" line_range="64" />
<code_context>
* **混合搜索权重**: 当使用“混合检索”时，调整向量和关键词搜索结果的权重。
* **切换模型**:
- * **语言模型 (LLM)**: 动态切换当前对话使用的聊天模型（例如，从 `google` 切换到 `openai`）。切换后，程序会自动重载模型。
+ * **语言模型 (LLM)**: 动态切换当前对话使用的聊天模型（在 `config.toml` 中 `llm_configurations` 里定义的配置项之间切换，例如从 `gpt-5-6-sol` 切到 `deepseek-v4-flash`）。切换后，程序会自动重载模型；重载失败时自动回滚到原模型并提示。
* **重排模型 (Rerank)**: 切换用于精排的 Rerank 模型。
* **查看当前完整配置**: 显示所有当前生效的聊天和模型参数。
</code_context>
<issue_to_address>
**Model example names missing option**
When a user follows the example with the shipped `config.toml.example`, the model menu lists `llm_configurations` keys, but the example uses `gpt-5-6-sol`, which is not defined; the shipped OpenAI key is `openai` and its model name is `gpt-5.6-sol`. The documented option is therefore absent from the menu and cannot be selected.
Change the example’s OpenAI configuration key to `openai`.
</issue_to_address>
### Comment 2
<location path="README.md" line_range="110" />
<code_context>
uv run main.py
```
+命令行支持 `-h` / `--help`（查看用法）与 `--smoke-test`（非交互自检）；界面配色自动适配终端亮色 / 暗色主题，可用 `PYRAG_LIGHT=1` / `PYRAG_DARK=1` 强制指定。
+
3. 在主菜单中按需执行：
</code_context>
<issue_to_address>
**Theme colors remain partly unchanged**
When a user expects a theme override or light-terminal detection to adapt the whole interface, the theme helpers change prompt and questionary pointer styles, but other interface colors, including the startup banner, retain their existing colors. The interface therefore does not adapt as broadly as the documentation promises.
Narrow the documentation to say that theme adaptation applies to prompt and questionary pointer styles, not the whole interface.
Also at `docs/user_guide/getting-started.md:84`, `docs/user_guide/user-guide.md:9`.
</issue_to_address>Sourcery assessment
Approval pending. 2 findings to address first.
Blocking findings: docs/user_guide/user-guide.md:64, README.md:110
- 主题适配范围如实化：只覆盖提示符与选择菜单指针（rich 语义色的 面板/表格本就自适应），不是「整个界面配色」 - 切换模型示例改用 config.toml.example 实际存在的 key（openai/ google-pro）；gpt-5-6-sol 是本机私有配置的 key，用户照文档操作 会在菜单里找不到该选项 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
目的
PR #4/#5 落地的两个用户可见变化没有同步到文档：
main.py的-h/--help与--smoke-test参数、PYRAG_LIGHT/PYRAG_DARK主题覆盖顺带修正
user-guide.md的过时示例：切换模型的google/openai是 provider 名而非llm_configurations的 key（真实 key 形如gpt-5-6-sol），并补上 PR #3 落地的「重载失败自动回滚」契约说明。影响范围
纯文档：
README.md、docs/user_guide/getting-started.md、docs/user_guide/user-guide.md。无代码、无配置影响。🤖 Generated with Claude Code
Sourcery 摘要
更新面向用户的文档，以反映最新的 CLI、主题适配和模型切换行为。
文档：
Original summary in English
Sourcery 摘要
更新用户文档，以反映最新的命令行选项、终端主题适配和模型切换行为。
文档：
Original summary in English
Summary by Sourcery
更新用户文档以反映最新的命令行选项、终端主题适配和模型切换行为。
Documentation: