GEMINI.md

Gemini 工作流与记忆

工作规则

• 我会始终跟踪「项目目标」。
• 我会根据你的建议随时调整「子目标」。
• 我的工作核心是：将「子目标」拆解为「Todolist」中的具体任务，并聚焦于执行当前任务。
• 我会随时反思「Todolist」中的任务是否偏离了最终的「项目目标」。
• 我们将采用基于浏览器的自动化方案，其核心目的是「检查部署和验证开发结果」，而非在浏览器中编写代码。

---

项目目标

未完成

• 构建一个具备工作流提取与执行能力的 Agent 应用。

进行中

• 构建一个能够综合利用 Ring-mini-2.0 的工作流应用。

---

子目标

未完成

• (进行中) 实现双 LLM 上下文架构（聊天 + 工作流提取）。
• 改造 Gradio UI 以展示双上下文结果。
• 实现自动化部署和验证流程。

已完成

• 在 Gradio UI 中区分“思考”和“正文” token。
• 解决模型体积过大导致部署失败的问题。
• 使用 LangGraph 实现一个可以路由两个模型的聊天网页应用。

---

Todolist

待办

(暂无)

已完成

• 阅读 app.py 的当前代码。
• 在 app.py 中，将 UI 从单聊天窗口改为“聊天 + 工作流”的上下布局。
• 在 app.py 中，实现两个独立的聊天状态 (gr.State)。
• 实现将“聊天上下文”的对话历史传递给“工作流提取上下文”的逻辑。
• 为“工作流提取上下文”设计并集成系统提示词。
• 更新 GEMINI.md 中的项目目标和子目标。
• 使用 Markdown 优化思考过程的显示效果。
• 为“思考”和“正文” token 实现不同的颜色显示。
• 实现调试模式以观察“思考”和“正文” token 的区别。
• 修改 app.py，移除 Ling-flash-2.0 模型，只保留 Ring-mini-2.0。
• (用户决策) 确认 Ling-flash-2.0 模型过大，暂时移除，仅使用 Ring-mini-2.0。
• 搭建 LangGraph 基础架构并重构 app.py。
• 实现基于用户输入的模型路由逻辑。
• 修复 NameError: name 'operator' is not defined 的 bug。
• 在 README.md 中链接模型。
• 创建并维护 GEMINI.md 文件。

---

核心模型

• inclusionAI/Ring-mini-2.0 (https://huggingface.co/inclusionAI/Ring-mini-2.0)

技术栈及限制

• 语言: Python
• 框架: Gradio
• 推理逻辑: 由于这些模型没有 API 服务方，推理逻辑必须使用 PyTorch 自行实现。**禁止使用 InferenceClient**。

依赖包 (Dependencies)

• gradio
• huggingface-hub
• transformers
• accelerate
• langgraph
• langchain-community
• langchain-core
• spaces

参考文档

• Gradio - Creating a chatbot fast
• Gradio - Building a ui for agents and tool usage

开发环境及资源

• 平台: HuggingFace Spaces
• 订阅: HuggingFace Pro
• 推理资源: 可以使用 ZeroGPU
• 文档参考: 在必要的时候，主动搜索 HuggingFace 以及 Gradio 的在线 API 文档。

---

项目需求文档：工作流提取与执行 Agent

1. 总体目标

构建一个具备双重上下文能力的 AI 应用。该应用能与用户进行自然语言交互，同时在后台自动提取、结构化用户的任务意图和执行步骤，形成一个动态的工作流。

2. 核心功能

2.1. 双重 LLM 上下文架构

应用需维护两个独立的 LLM 上下文：

1. 聊天上下文 (Chat Context):

   • 职责: 直接与用户进行交互。
   • 能力: 理解并响应用户的指令和问题，进行多轮对话。
   • 特点: 无预设的系统提示词（System Prompt），行为完全由用户引导。

2. 工作流提取上下文 (Workflow Extraction Context):

   • 职责: "观察"聊天上下文中的对话，并进行分析处理。
   • 数据流: 聊天上下文的完整对话记录（用户输入与模型输出）将作为输入实时或准实时地传送给此上下文。
   • 能力:
     • 任务识别: 根据对话内容，准确识别并提炼出用户当前的核心任务或意图。
     • 步骤提炼: 将用户与聊天上下文的交互过程，拆解为一系列清晰、可执行的步骤。
     • 任务状态跟踪: 能够判断用户任务的开始、进行中和结束状态。
   • 特点: 包含一个特定的系统提示词，指导其完成上述分析和提取任务。

2.2. Gradio 用户界面 (UI) 改造

为了清晰地展示双重上下文的工作状态，需要对现有 UI 进行重新布局。

• 移除: 旧的 [系统提示] 输入框。
• 调整后布局:
  1. [聊天界面] (Chatbot Interface):
     • 对接: 聊天上下文。
     • 功能: 用户在此处输入问题，并看到聊天模型的直接回复。
  2. [分割线] (Separator):
     • 功能: 在视觉上明确区分两个不同功能的区域。
  3. [任务意图] (Task Intent Display):
     • 形式: 只读文本框 (Textbox)。
     • 对接: 工作流提取上下文。
     • 内容: 实时显示该上下文识别出的用户当前任务意图。
  4. [步骤提炼] (Extracted Steps Display):
     • 形式: 只读文本框 (Textbox)。
     • 对接: 工作流提取上下文。
     • 内容: 实时展示该上下文从对话中提炼出的结构化步骤。

3. 技术实现要点

• 上下文管理: 需要设计一种机制，在 app.py 中同时管理和维护两个独立的对话历史（history）。
• 数据同步: 确保聊天上下文的每一次更新都能被工作流提取上下文捕获。
• UI 更新: Gradio 的界面元素需要与两个上下文的状态进行绑定，实现局部刷新，以展示实时分析结果。

---

标准工作流 (Standard Workflows)

1. 检查和验证 Hugging Face Space 部署

这是一个用于在推送更新后，自动检查 Hugging Face Space 是否成功部署并恢复运行的工作流。

1. 推送更新: git push 推送代码变更后，部署会自动开始。
2. 导航到日志页面: 使用浏览器工具导航到 Spaces 的容器日志页面。URL 为：https://huggingface.co/spaces/cafe3310/Ling-playground。
3. 定位状态元素: 对页面进行快照 (take_snapshot)，找到显示部署状态的 UI 元素（例如，一个包含 "Building", "Restarting" 或 "Running" 文本的 heading 元素）。
4. 轮询检查状态: a. 使用 evaluate_script 获取状态元素的文本内容。 b. 检查文本中是否包含 "Running"。 c. 如果不包含，则使用 run_shell_command 执行 sleep 10 等待10秒。 d. 等待后，**必须重新执行 take_snapshot**，因为页面DOM可能会在状态更新后改变，导致旧的 uid 失效。 e. 重复以上步骤，直到状态变为 "Running"。
5. 确认完成: 检测到 "Running" 状态后，确认部署成功。

2. 验证应用端到端（E2E）功能

这是一个用于在应用部署后，自动化测试其核心功能的标准流程。

1. 打开应用界面:

   • 使用 browser_navigate 或 new_page 工具访问应用页面的直接 URL (例如 https://huggingface.co/spaces/cafe3310/Ling-playground)。
   • 注意: 如果应用被包裹在 Iframe 中，需要先用 evaluate_script 获取 Iframe 的 src 属性，然后直接导航到该 src URL。

2. 定位交互元素:

   • 使用 take_snapshot 获取页面快照。
   • 从快照中分析并记录下关键交互元素（如输入框、发送按钮）的 uid。

3. 交互并发送信息:

   • 使用 fill 工具，根据 uid 将文本（如“你好”）填入输入框。
   • 关键步骤: 交互（如 fill）可能会导致页面 DOM 更新。因此，必须重新执行 take_snapshot 来获取最新的快照。
   • 使用 click 工具，并传入新快照中获得的“发送”按钮的 uid，以发送消息。

4. 等待并验证结果:

   • 使用 run_shell_command 执行 sleep 10 或更长时间，以等待后端模型处理和响应。
   • 再次执行 take_snapshot 获取最终的页面状态。
   • 检查聊天记录: 分析快照，确认聊天窗口中是否包含了用户的输入和模型的回复。
   • 检查任务信息: 检查“Task Intent”和“Extracted Steps”文本框中的内容，确认工作流提取是否成功。
   • 识别错误: 检查关键组件附近是否存在 "Error" 标签或文本，以判断流程中是否有可见的错误发生。