Spaces:

cafe3310
/

ling-playground

Running

App Files Files Community

ling-playground / GEMINI.md

cafe3310

feat: Initial clean commit

a9fb7e9 25 days ago

preview code

raw

history blame

12.8 kB

Ling & Ring Playground - 项目与协作文档

[重要] 上下文说明: 本文档定义了 Ling & Ring Playground 项目的具体设计和流程。我们的整体协作模式、沟通风格、以及通用的文档和目录规范，均遵循一套全局 GEMINI.md 核心协作指令。阅读本文档前，建议先了解该全局框架，以获得完整的上下文。

第一部分：元信息与协作流程

Gemini 用例

运行项目

要启动此 Gradio 应用，请遵循以下步骤：

安装依赖: 确保所有必要的库都已安装。
```
uv pip install -r requirements.txt
```
注意: 如果遇到与 SOCKS 代理相关的 ImportError，请额外运行 uv pip install "httpx[socks]"。

启动应用: 在后台静默运行应用。

source .venv/bin/activate && python3 app.py > /dev/null 2>&1 &

验证: 在浏览器中打开 http://127.0.0.1:7860 以确认应用正在运行。

需求开发流程

为确保每个需求的精确实现和追踪，我们遵循以下协作流程：

需求接收 (Requirement Reception):
- 当你提出新需求时，我将首先在 docs/backlog/ 目录下创建一个 Markdown 文件，作为“需求池”的记录。
- 文件名格式为 YYYY-MM-DD-HH-mm-需求简述.md。
- 文件内容将包含：需求描述、创建时间、初始状态 待处理 (Pending)、验证方式（暂空）、验证结果（暂空）。
规划与确认 (Plan & Confirm):
- 当我们决定处理一个需求时，我会基于其文档，提出具体的执行计划。
- 在你确认计划后，我会将该需求文件从 docs/backlog/ 移动到 docs/requirements/ 目录，并将其状态更新为 开发中 (In Progress)。
修订章程 (Revise Charter):
- 我会更新 GEMINI.md 的“第三部分：详细设计”，以反映新功能的设计细节。
执行 (Execute):
- 我将根据确认的计划进行编码实现。
提交验证 (Submit for Verification):
- 完成代码编写后，我会重启应用，并自动刷新你的浏览器以展示最新版本。
- 同时，我将更新需求文件，将状态改为 已完成 (Completed)，并填入“验证方式”供你参考。
确认与关闭 (Confirm & Close):
- 在你完成验证并确认功能符合预期后，我会将需求文件的“验证结果”更新为 已验证 (Verified)，至此该需求流程关闭。

调试与 Bug 修复流程

当功能未按预期工作时，我们将采用以下高效的诊断流程：

问题报告: 你需要向我清晰地描述问题，包括：
- 复现步骤: 你进行了哪些具体操作。
- 预期结果: 你期望看到什么。
- 实际结果: 你实际看到了什么（例如：报错、无响应、界面错乱等）。
启动日志模式: 我会终止在后台静默运行的应用，并以日志模式重新启动它。这能让我观察到应用在运行期间的所有内部活动和潜在错误。
```
# 命令示例
source .venv/bin/activate && python3 app.py > app.log 2>&1 &
```
复现与分析: 我会请你重新执行一遍复现步骤。在你操作完成后，我将立即读取 app.log 文件，分析其中的错误信息和执行轨迹，定位问题的根本原因。
修复与验证:
- 根据日志分析，我会提出具体的修复方案并执行。
- 修复后，我会重启应用（仍处于日志模式），并自动刷新你的浏览器，然后请你再次验证。
- 如果问题依然存在，我们将重复步骤 3 和 4。
流程结束: 在你确认 Bug 已被完全修复后，此调试流程结束。我会终止日志模式的应用，清理日志文件，以标准的静默模式重新启动应用，并为你刷新浏览器。

代码提交与版本管理

在完成一个需求或修复一个 Bug 后，我们将遵循以下流程来提交代码和管理版本：

暂存变更:
- 使用 git add . 暂存所有修改。
编写提交信息 (Commit Message):
- Commit message 应遵循**约定式提交 (Conventional Commits)**规范。
- 格式为 <类型>(<范围>): <描述>，例如：
  - feat(chat): 添加发送按钮
  - fix(models): 修正 Ring 模型流式输出问题
  - docs(workflow): 更新调试与验证流程
- 常用的类型包括 feat, fix, docs, style, refactor, test 等。
创建版本标签 (Git Tag):
- 检查现有版本: 在打标签前，必须先运行 git tag 查看所有历史版本，以确定下一个正确的版本号。
- 确定版本号: 遵循**语义化版本 (Semantic Versioning)**。在 v1.0.0 之前，我们主要递增次版本号（如 v0.4 -> v0.5）。
- 创建附注标签: 使用 git tag -a <版本号> -m "<版本摘要>" 创建一个附注标签，其中摘要应简明扼要地概括该版本的主要变更。例如：
```
git tag -a v0.5 -m "v0.5: Automate browser verification and formalize debugging process"
```
最终确认:
- 提交和打标签后，运行 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 配置加载策略

为兼顾本地开发的便利性、线上部署的安全性与成本效益，项目采用了一种分层配置加载机制：

本地优先 (local.py): 在项目根目录下，可以创建一个 local.py 文件来存放本地开发所需的配置，例如使用内部免费 Provider 的 API Key 和 Endpoint。此文件必须被 .gitignore 忽略，以防止任何敏感信息被提交到版本控制中。
环境变量回退: 当 local.py 文件不存在时（例如在 Hugging Face Spaces 的生产环境中），系统将自动回退，尝试从环境变量中读取所需的配置。这种方式使得 API Key 等敏感信息可以通过平台安全地注入，而无需硬编码在代码中。
模型 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 代码架构

models.py: 存放所有与模型对接和交互的逻辑。
app.py: 作为应用的统一入口，仅保留最精简的组装和启动逻辑。
tab_*.py: 每个标签页（如 tab_chat.py）独立一个文件，负责构建该标签页的UI和处理其特定的后端逻辑。
app.py 调用: 主入口 app.py 通过调用各个 tab_*.py 中的函数来创建和组装完整的应用界面。
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 进行中的任务

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

4.2 待修复的问题

(暂无)