# Ling & Ring Playground - 项目与协作文档 > **[重要] 上下文说明:** 本文档定义了 **Ling & Ring Playground** 项目的具体设计和流程。我们的整体协作模式、沟通风格、以及通用的文档和目录规范，均遵循一套**全局 `GEMINI.md` 核心协作指令**。阅读本文档前，建议先了解该全局框架，以获得完整的上下文。 --- ## 第一部分：元信息与协作流程 --- ## Gemini 用例 ### 运行项目 要启动此 Gradio 应用，请遵循以下步骤： 1. **安装依赖:** 确保所有必要的库都已安装。 ```bash uv pip install -r requirements.txt ``` *注意: 如果遇到与 SOCKS 代理相关的 `ImportError`，请额外运行 `uv pip install "httpx[socks]"`。* 2. **启动应用:** 在后台静默运行应用。 ```bash source .venv/bin/activate && python3 app.py > /dev/null 2>&1 & ``` 3. **验证:** 在浏览器中打开 `http://127.0.0.1:7860` 以确认应用正在运行。 ### 需求开发流程 为确保每个需求的精确实现和追踪，我们遵循以下协作流程： 1. **需求接收 (Requirement Reception):** - 当你提出新需求时，我将首先在 `docs/backlog/` 目录下创建一个 Markdown 文件，作为“需求池”的记录。 - 文件名格式为 `YYYY-MM-DD-HH-mm-需求简述.md`。 - 文件内容将包含：需求描述、创建时间、初始状态 `待处理 (Pending)`、验证方式（暂空）、验证结果（暂空）。 2. **规划与确认 (Plan & Confirm):** - 当我们决定处理一个需求时，我会基于其文档，提出具体的执行计划。 - 在你确认计划后，我会将该需求文件从 `docs/backlog/` **移动**到 `docs/requirements/` 目录，并将其状态更新为 `开发中 (In Progress)`。 3. **修订章程 (Revise Charter):** - 我会更新 `GEMINI.md` 的“第三部分：详细设计”，以反映新功能的设计细节。 4. **执行 (Execute):** - 我将根据确认的计划进行编码实现。 5. **提交验证 (Submit for Verification):** - 完成代码编写后，我会重启应用，并**自动刷新你的浏览器以展示最新版本**。 - 同时，我将更新需求文件，将状态改为 `已完成 (Completed)`，并填入“验证方式”供你参考。 6. **确认与关闭 (Confirm & Close):** - 在你完成验证并确认功能符合预期后，我会将需求文件的“验证结果”更新为 `已验证 (Verified)`，至此该需求流程关闭。 ### 调试与 Bug 修复流程 当功能未按预期工作时，我们将采用以下高效的诊断流程： 1. **问题报告:** 你需要向我清晰地描述问题，包括： - **复现步骤:** 你进行了哪些具体操作。 - **预期结果:** 你期望看到什么。 - **实际结果:** 你实际看到了什么（例如：报错、无响应、界面错乱等）。 2. **启动日志模式:** 我会终止在后台静默运行的应用，并以日志模式重新启动它。这能让我观察到应用在运行期间的所有内部活动和潜在错误。 ```bash # 命令示例 source .venv/bin/activate && python3 app.py > app.log 2>&1 & ``` 3. **复现与分析:** 我会请你重新执行一遍复现步骤。在你操作完成后，我将立即读取 `app.log` 文件，分析其中的错误信息和执行轨迹，定位问题的根本原因。 4. **修复与验证:** - 根据日志分析，我会提出具体的修复方案并执行。 - 修复后，我会重启应用（仍处于日志模式），并**自动刷新你的浏览器**，然后请你再次验证。 - 如果问题依然存在，我们将重复步骤 3 和 4。 5. **流程结束:** 在你确认 Bug 已被完全修复后，此调试流程结束。我会终止日志模式的应用，清理日志文件，**以标准的静默模式重新启动应用，并为你刷新浏览器**。 ### 代码提交与版本管理 在完成一个需求或修复一个 Bug 后，我们将遵循以下流程来提交代码和管理版本： 1. **暂存变更:** - 使用 `git add .` 暂存所有修改。 2. **编写提交信息 (Commit Message):** - Commit message 应遵循**约定式提交 (Conventional Commits)**规范。 - 格式为 `<类型>(<范围>): <描述>`，例如： - `feat(chat): 添加发送按钮` - `fix(models): 修正 Ring 模型流式输出问题` - `docs(workflow): 更新调试与验证流程` - 常用的类型包括 `feat`, `fix`, `docs`, `style`, `refactor`, `test` 等。 3. **创建版本标签 (Git Tag):** - **检查现有版本:** 在打标签前，**必须**先运行 `git tag` 查看所有历史版本，以确定下一个正确的版本号。 - **确定版本号:** 遵循**语义化版本 (Semantic Versioning)**。在 `v1.0.0` 之前，我们主要递增次版本号（如 `v0.4` -> `v0.5`）。 - **创建附注标签:** 使用 `git tag -a <版本号> -m "<版本摘要>"` 创建一个附注标签，其中摘要应简明扼要地概括该版本的主要变更。例如： ```bash git tag -a v0.5 -m "v0.5: Automate browser verification and formalize debugging process" ``` 4. **最终确认:** - 提交和打标签后，运行 `git status` 和 `git tag` 确认工作区干净且新标签已成功创建。 --- ## 第二部分：整体设计 ### 2.1 项目目标 创建一个名为 “Ling & Ring Playground” 的 Hugging Face Space，用于展示两个核心 AI 模型： - **Ling (🧠):** 通用对话模型。 - **Ring (💍):** 推理/代理模型，用于代码生成、网页检索和工作流执行。 ### 2.2 核心设计原则 - **任务导向:** UI 围绕用户任务（聊天、编码等）组织，而非直接暴露模型。 - **品牌明晰:** 在每个功能界面清晰标注“由 Ling/Ring 模型驱动”。 - **无缝体验:** 用户无需手动输入 API Token，认证在后端自动完成。 - **引导优先:** 提供精心设计的示例，确保用户获得高质量的初次体验。 ### 2.3 技术栈与架构 - **前端/UI:** Gradio `gr.Blocks` - **后端:** Python - **安全:** 所有 API 密钥通过 Hugging Face Space Secrets 管理。 ### 2.3.1 配置加载策略 为兼顾本地开发的便利性、线上部署的安全性与成本效益，项目采用了一种分层配置加载机制： 1. **本地优先 (`local.py`):** 在项目根目录下，可以创建一个 `local.py` 文件来存放本地开发所需的配置，例如使用内部免费 Provider 的 API Key 和 Endpoint。此文件**必须**被 `.gitignore` 忽略，以防止任何敏感信息被提交到版本控制中。 2. **环境变量回退:** 当 `local.py` 文件不存在时（例如在 Hugging Face Spaces 的生产环境中），系统将自动回退，尝试从环境变量中读取所需的配置。这种方式使得 API Key 等敏感信息可以通过平台安全地注入，而无需硬编码在代码中。 3. **模型 ID 本地映射:** 为了方便本地开发和调试，系统还支持通过在 `local.py` 文件中定义一个 `get_local_model_id_map` 函数，来实现从在线模型 ID 到本地模型 ID 的映射。这允许开发者在不修改核心代码库的情况下，将模型请求指向本地运行的服务或不同的模型版本。 此策略确保了开发者在本地可以快速迭代，而线上部署则遵循了安全最佳实践。 ### 2.4 项目结构 ``` / ├───.gitignore ├───app.py # 应用主入口 ├───config.py # 配置文件，用于存放 API 密钥等 ├───GEMINI.md # 项目与协作文档（唯一事实来源） ├───models.py # 模型交互逻辑 ├───requirements.txt # Python 依赖 ├───tab_chat.py # “聊天”功能模块 ├───tab_code.py # “代码生成”功能模块 ├───tab_search.py # “网页检索”功能模块 ├───tab_workflow.py # “工作流”功能模块 ├───utils.py # 通用工具函数 └───docs/ ├───backlog/ # 待办需求池 ├───requirements/ # 需求文档（Git 跟踪） └───refs/ # 本地参考资料（Git 忽略） ``` ### 2.5 代码架构 1. **`models.py`**: 存放所有与模型对接和交互的逻辑。 2. **`app.py`**: 作为应用的统一入口，仅保留最精简的组装和启动逻辑。 3. **`tab_*.py`**: 每个标签页（如 `tab_chat.py`）独立一个文件，负责构建该标签页的UI和处理其特定的后端逻辑。 4. **`app.py` 调用**: 主入口 `app.py` 通过调用各个 `tab_*.py` 中的函数来创建和组装完整的应用界面。 5. **`utils.py`**: 存放可被多处复用的纯静态方法、常量或辅助函数。 --- ## 第三部分：详细设计 应用为一个包含页头和四个核心功能标签页的单页应用。 ### Tab 1: 聊天 (Chat) - `tab_chat.py` - **目标:** 提供一个与 Ling 模型进行高质量对话的界面。 - **UI 布局:** - **左侧面板:** `gr.Chatbot` (对话历史), `gr.Textbox` (输入框) 与 `gr.Button` ("发送") 在同一行, `gr.Examples` (示例)。 - **右侧面板:** `gr.Textbox` (System Prompt), `gr.Slider` (温度), `gr.Dropdown` (模型选择)。 - **用户用例:** 1. 用户在输入框中输入问题，按回车提交。 2. Ling 模型的响应以流式方式出现在聊天历史中，且每条回复的开头都会以 `**<模型名称>**` 的形式清晰地标识出当前是哪个模型在回答。 3. 用户可继续多轮对话，或通过右侧面板调整模型行为。 ### Tab 2: 代码生成 (Code Generation) - `tab_code.py` - **目标:** 利用 Ring 模型，根据用户需求生成代码，并提供实时预览。 - **UI 布局:** - **左侧面板:** `gr.Radio` (代码类型), `gr.Radio` (模型选择), `gr.Textbox` (需求输入), `gr.Examples` (预设选项), `gr.Button` (生成)。 - **右侧面板:** `gr.Tabs` - **Tab 1: "实时预览"**: `gr.Button` (全屏预览), `gr.HTML` (`