GEMINI.md

# 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` (`<iframe>` 预览容器)。
        - **Tab 2: "生成的源代码"**: `gr.Code` (源代码显示)。
- **用户用例:**
    1. 用户选择代码类型（“静态页面”或“Gradio 应用”）。当选择“静态页面”时，功能由 `Ling-1T` 模型驱动。
    2. 用户输入需求（例如：“创建一个带标题和按钮的页面”）。
    3. 点击“生成代码”后，`tab_code.py` 中的 `generate_code` 函数会作为一个生成器工作。
    4. 它会迭代调用模型返回的流式数据，在每次 `yield` 时同时更新下方的源代码区域（累积的代码）和右侧的预览区域。
    5. 预览区域的 `<iframe>` 默认以**缩放模式**显示，以便用户看到整体效果。
    6. 用户可以点击“全屏预览”按钮，此时输入和代码区域会隐藏，预览区将放大以提供更沉浸的体验。再次点击可恢复。
    7. 对于 Gradio 应用，后端会启动一个独立的子进程来运行代码，并将应用界面嵌入到预览区。

### Tab 3: 网页检索 (Web Search) - `tab_search.py`

- **目标:** 利用 Ring 模型的检索能力，提供精准的网页信息摘要。
- **UI 布局:** 单栏居中布局，包含 `gr.Textbox` (输入), `gr.Button` (搜索), `gr.Markdown` (结果)。
- **用户用例:**
    1. 用户输入问题（例如：“什么是 Transformer 架构？”）。
    2. 点击“搜索”后，Ring 模型返回的摘要和来源链接会显示在结果区。

### Tab 4: 工作流执行 (Workflow Execution) - `tab_workflow.py`

- **目标:** 展示 Ring 模型作为 Agent 执行复杂工作流的能力。
- **UI 布局:**
    - **左侧面板:** `gr.Textbox` (工作流描述), `gr.Button` (执行), `gr.Markdown` (工作流可视化)。
    - **右侧面板:** `gr.Textbox` (状态日志), `gr.Chatbot` (人机交互)。
- **用户用例:**
    1. 用户输入任务描述（例如：“查找最新的 Llama 3 模型并总结其模型卡片”）。
    2. Ring 模型生成执行计划并可视化，然后开始执行。
    3. 右侧面板实时显示执行日志，并在需要时通过聊天机器人向用户请求决策。

---

## 第四部分：待办事项

### 4.1 进行中的任务

- [x] **任务: 实现代码生成 Tab (`tab_code.py`)**
    - [x] UI 构建 (`gr.Radio`, `gr.Textbox`, `gr.Button`, `gr.Code`, `gr.HTML`)
    - [x] 后端逻辑 (System Prompts, 子进程管理, `<iframe>` 预览)
    - [x] 应用整合 (在 `app.py` 中装配 Tab)
    - [x] 模块化重构 (将模型调用逻辑移至 `models.py`)

### 4.2 待修复的问题

- (暂无)