From b1c4b07759097d297a32e0502b1442ab57bba2da Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Wed, 22 Jul 2026 08:53:07 +0800
Subject: [PATCH 01/12] Add files via upload

---
 .env.example |   7 +
 .gitignore   |  34 +++--
 README.md    | 406 ++++++++++++++++++++++-----------------------------
 start.bat    |  36 +++++
 4 files changed, 241 insertions(+), 242 deletions(-)
 create mode 100644 .env.example
 create mode 100644 start.bat

diff --git a/.env.example b/.env.example
new file mode 100644
index 00000000..9312ed80
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,7 @@
+# Hy3 API 配置
+# 从腾讯云控制台获取 API 密钥：
+# https://console.cloud.tencent.com/hunyuan
+
+HY3_API_KEY=在此填写你的 API 密钥
+HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
+HY3_MODEL=hunyuan-hy3-295b-a21b
diff --git a/.gitignore b/.gitignore
index 56137961..6f9bb002 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,10 +1,24 @@
-.cache/
-.huggingface/
-.modelscope/
-.ms*
-*.swp
-*.log
-.DS_Store
-Thumbs.db
-__pycache__/
-*.pyc
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Environment
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Uploaded files
+uploads/
diff --git a/README.md b/README.md
index d118cf0f..09b2308b 100644
--- a/README.md
+++ b/README.md
@@ -1,232 +1,174 @@
-<p align="left">
-    <a href="README_CN.md">中文</a>&nbsp;｜&nbsp;English
-</p>
-<br>
-
-<p align="center">
- <img src="assets/logo-en.png" width="400"/> <br>
-</p>
-
-<div align="center" style="line-height: 1;">
-
-
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](#license)
-&nbsp;&nbsp;
-[![HuggingFace](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Tencent%20Hy-ffc107?color=ffc107&logoColor=white)](https://huggingface.co/tencent/Hy3)
-&nbsp;&nbsp;
-[![ModelScope](https://img.shields.io/badge/ModelScope-Tencent%20Hy-624aff)](https://modelscope.cn/models/Tencent-Hunyuan/Hy3)
-&nbsp;&nbsp;
-[![cnb.cool](https://img.shields.io/badge/cnb.cool-Tencent%20Hy-blue?logoColor=white)](https://cnb.cool/ai-models/tencent/Hy3)
-&nbsp;&nbsp;
-[![GitCode](https://img.shields.io/badge/GitCode-Tencent%20Hy-red?logoColor=white)](https://ai.gitcode.com/tencent_hunyuan/Hy3)
-
-</div>
-
-<p align="center">
-    🖥️&nbsp;<a href="https://aistudio.tencent.com/"><b>Official Website</b></a>&nbsp;&nbsp;|&nbsp;&nbsp;
-    💬&nbsp;<a href="https://github.com/Tencent-Hunyuan/Hy3"><b>GitHub</b></a></p>
-
----
-
-## Table of Contents
-
-- [Model Introduction](#model-introduction)
-- [Stronger Agent Capabilities](#stronger-agent-capabilities)
-- [More Reliable Product Experiences](#more-reliable-product-experiences)
-- [Benchmark Appendix](#benchmark-appendix)
-- [News](#news)
-- [Model Links](#model-links)
-- [Quickstart](#quickstart)
-- [Deployment](#deployment)
-  - [vLLM](#vllm)
-  - [SGLang](#sglang)
-- [Finetuning](#finetuning)
-- [RL Post-training](#rl-post-training)
-- [Quantization](#quantization)
-- [License](#license)
-- [Contact Us](#contact-us)
-
----
-
-## Model Introduction
-
-**Hy3** is a 295B-parameter Mixture-of-Experts (MoE) model with 21B active parameters and 3.8B MTP layer parameters, developed by the Tencent Hy Team. Following the Hy3 Preview launch in late April, we gathered feedback from 50+ products and scaled up post-training with higher quality data. Today, we introduce Hy3, which outperforms similar-size models and rivals flagship open-source models with 2-5x parameters. It also shows significant gains in utility across various products and productivity tasks.
-
-
-| Property | Value |
-|:---|:---|
-| Architecture | Mixture-of-Experts (MoE) |
-| Total Parameters | 295B |
-| Activated Parameters | 21B |
-| MTP Layer Parameters | 3.8B |
-| Number of Layers (excluding MTP layer) | 80 |
-| Number of MTP Layers | 1 |
-| Attention Heads | 64 (GQA, 8 KV heads, head dim 128) |
-| Hidden Size | 4096 |
-| Intermediate Size | 13312 |
-| Context Length | 256K |
-| Vocabulary Size | 120832 |
-| Number of Experts | 192 experts, top-8 activated |
-| Supported Precisions | BF16 |
-
-## Stronger Agent Capabilities
-
-Building on Hy3 Preview, we further improved the quality and diversity of post-training data while scaling up RL training. Hy3 shows solid gains across reasoning, agentic, and long-context tasks, competitive with much larger flagship models.
-
-<p align="center">
-  <img src="assets/benchmark.png" width="100%"/>
-</p>
-
-In productivity scenarios such as coding, office work, financial modeling, frontend design, and game development, Hy3 has made remarkable progress and can now serve as a reliable, cost-effective model option.
-
-We don't think public benchmark scores tell the full story. So we ran a blind evaluation with 270 experts using tasks from their work, and Hy3 scored 2.67/4, outperforming GLM-5.1 at 2.51/4. The advantage was most substantial in frontend development, data & storage, and CI/CD tasks.
-
-## More Reliable Product Experiences
-
-Model usefulness is not fully captured by benchmarks. Based on extensive product feedback, we identified and fixed the following issues, receiving consistently positive feedback from product teams.
-
-**Stability of tool calls and output formats**: We fixed multiple baseline reliability issues, bringing the model to production-grade standards across tool configurations and output constraints. Tool-call error recovery and overall efficiency improved. Hy3 also generalizes across different agent scaffoldings. On SWE-Bench Verified, accuracy variance across scaffoldings like CodeBuddy, Cline, and KiloCode remains within 4%.
-
-**Knowledge and anti-hallucination**: Guided by the ideal of "answer when grounded, state when evidence is missing, do not conflate sources or fabricate data," we implemented fine-grained data cleaning and training constraints. In internal evaluations based on real-world scenarios, Hy3's hallucination rate dropped from 12.5% to 5.4%, and commonsense error rates fell from 25.4% to 12.7%. These improvements materially reduce fact conflation, fabrication, and logical contradiction.
-
-**Complex context retention and multi-turn intent tracking**: Through joint optimization of SFT and RL, Hy3 improved on operational pain points like coreference resolution, ellipsis recovery, and multi-turn constraint inheritance. On internal comprehensive multi-turn tests, the issue rate dropped from 17.4% to 7.9%. Hy3 also improved markedly on long-dialogue evals like MRCR. Its outputs are more concise while ensuring complex intents do not decay or drift over long-horizon interactions.
-
-## Benchmark Appendix
-
-<p align="center">
-  <img src="assets/benchmark-appendix.png" width="100%"/>
-</p>
-
-## News
-
-
-* 🔥 We open-source **Hy3** and **Hy3-FP8** model weights on [Hugging Face](https://huggingface.co/tencent/Hy3), [ModelScope](https://modelscope.cn/models/Tencent-Hunyuan/Hy3), [GitCode](https://ai.gitcode.com/tencent_hunyuan/Hy3), and [CNB](https://cnb.cool/ai-models/tencent/Hy3).
-
-## Model Links
-
-
-| Model Name | Description | Hugging Face | ModelScope | GitCode | CNB |
-|:---|:---|:---:|:---:|:---:|:---:|
-| Hy3 | Instruct model | 🤗 [Model](https://huggingface.co/tencent/Hy3) | [Model](https://modelscope.cn/models/Tencent-Hunyuan/Hy3) | [Model](https://ai.gitcode.com/tencent_hunyuan/Hy3) | [Model](https://cnb.cool/ai-models/tencent/Hy3) |
-| Hy3-FP8 | FP8 quantized instruct model | 🤗 [Model](https://huggingface.co/tencent/Hy3-FP8) | [Model](https://modelscope.cn/models/Tencent-Hunyuan/Hy3-FP8) | [Model](https://ai.gitcode.com/tencent_hunyuan/Hy3-FP8) | [Model](https://cnb.cool/ai-models/tencent/Hy3-FP8) |
-
-## Quickstart
-
-Deploy Hy3 with [vLLM](#vllm) or [SGLang](#sglang) first, then call the OpenAI-compatible API:
-
-```python
-from openai import OpenAI
-
-client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="EMPTY")
-
-response = client.chat.completions.create(
-    model="hy3",
-    messages=[
-        {"role": "user", "content": "Hello! Can you briefly introduce yourself?"},
-    ],
-    temperature=0.9,
-    top_p=1.0,
-    # reasoning_effort: "no_think" (default, direct response), "low", "high" (deep chain-of-thought)
-    extra_body={"chat_template_kwargs": {"reasoning_effort": "no_think"}},
-)
-print(response.choices[0].message.content)
-```
-
-> **Recommended parameters**: `temperature=0.9`, `top_p=1.0`.
->
-> **Reasoning mode**: Set `reasoning_effort` to `"high"` for complex tasks (math, coding, reasoning) or `"no_think"` for direct responses.
-
-See the [Deployment](#deployment) section below for how to start the API server.
-
-## Deployment
-
-Hy3 has 295B parameters in total. To serve it on 8 GPUs, we recommend using H20-3e or other GPUs with larger memory capacity.
-
-For production serving, we recommend using vLLM or SGLang, both of which provide dedicated recipes for Hy3:
-
-- [vLLM](https://github.com/vllm-project/vllm) - see [vLLM recipes](https://recipes.vllm.ai/tencent/Hy3)
-
-- [SGLang](https://docs.sglang.io/) - see [SGLang cookbook](https://lmsysorg.mintlify.app/cookbook/autoregressive/Tencent/Hy3)
-
-### vLLM
-
-Build vLLM from source:
-```bash
-uv venv --python 3.12 --seed --managed-python
-source .venv/bin/activate
-git clone https://github.com/vllm-project/vllm.git
-cd vllm
-uv pip install --editable . --torch-backend=auto
-```
-
-Start the vLLM server with MTP enabled:
-
-```bash
-# Switch to trtllm backend to work-around mnnvl workspace size issue.
-export VLLM_FLASHINFER_ALLREDUCE_BACKEND=trtllm
-vllm serve tencent/Hy3 \
-  --tensor-parallel-size 8 \
-  --speculative-config.method mtp \
-  --speculative-config.num_speculative_tokens 2 \
-  --tool-call-parser hy_v3 \
-  --reasoning-parser hy_v3 \
-  --enable-auto-tool-choice \
-  --port 8000 \
-  --served-model-name hy3
-```
-
-### SGLang
-
-Build SGLang from source:
-```bash
-git clone https://github.com/sgl-project/sglang
-cd sglang
-pip3 install pip --upgrade
-pip3 install "transformers>=5.6.0"
-pip3 install -e "python"
-```
-
-Launch SGLang server with MTP enabled:
-
-```bash
-python3 -m sglang.launch_server \
-  --model tencent/Hy3 \
-  --tp-size 8 \
-  --tool-call-parser hunyuan \
-  --reasoning-parser hunyuan \
-  --speculative-num-steps 2 \
-  --speculative-eagle-topk 1 \
-  --speculative-num-draft-tokens 3 \
-  --speculative-algorithm EAGLE \
-  --port 8000 \
-  --served-model-name hy3
-```
-
-## Finetuning
-
-Hy3 provides a complete model finetuning pipeline. For detailed documentation, please refer to: [Finetuning Guide](./finetune/README.md)
-
-## RL Post-training
-
-Hy3 supports GRPO reinforcement learning training with [verl](https://github.com/volcengine/verl), training on Megatron-LM (model conversion via NVIDIA Megatron-Bridge) with vLLM rollout. For detailed documentation, please refer to: [RL Training Guide](./rl/README.md)
-
-## Quantization
-
-We provide [AngelSlim](https://github.com/tencent/AngelSlim), a more accessible, comprehensive, and efficient toolkit for large model compression. AngelSlim supports a comprehensive suite of compression tools for large-scale multimodal models, including common quantization algorithms, low-bit quantization, and speculative sampling.
-
-## License
-
-
-Hy3 is released under the **Apache License 2.0**. See [LICENSE](./LICENSE) for details.
-
-## Contact Us
-
-If you would like to leave a message for our R&D and product teams, welcome to contact us. You can also reach us via email:
-
-📧 **hunyuan_opensource@tencent.com**
-
----
-
-<p align="center">
-  <i>Hy3 is developed by the Tencent Hy Team.</i>
-</p>
+# Hy3 研究助手
+
+> 基于 **腾讯混元 Hy3**（295B MoE 模型）的端到端研究助手应用。
+>
+> 🏷️ 腾讯犀牛鸟开源人才培养计划 2026 · Issue [#4](https://github.com/Tencent-Hunyuan/Hy3/issues/4)
+
+---
+
+## 项目概述
+
+Hy3 研究助手是一个全栈 Web 应用，展示了 **Hy3 在实际场景中的强大能力**：
+
+| 功能 | 描述 | Hy3 扮演的角色 |
+|------|------|---------------|
+| 🔬 **深度研究** | 规划 → 搜索 → 长文报告（带引用来源） | 规划智能体、信息综合、报告撰写 |
+| 💻 **代码分析** | Bug 检测、性能优化、代码解释 | 代码理解、逻辑分析、重构建议 |
+| 📄 **文档问答** | 多文档上传与智能问答 | 阅读理解、基于证据的回答 |
+
+所有 LLM 能力**完全通过 Hy3 API 实现**——无需训练、微调或本地推理。
+
+---
+
+## 演示流程
+
+### 演示一：「MoE 架构效率」深度研究
+
+1. 输入主题：「MoE 架构对 LLM 推理效率的影响」
+2. Hy3 生成包含 4 个关键问题和搜索查询的研究计划
+3. 系统执行网页搜索并收集来源
+4. Hy3 撰写带有引用标注（[来源 1], [来源 2], ...）的全面报告
+5. 生成中英文双语执行摘要
+
+### 演示二：技术论文多文档问答
+
+1. 上传 2-3 个技术 PDF/TXT 文件
+2. 提问：「比较这些文档中描述的方法，关键区别是什么？」
+3. Hy3 读取所有文档并提供跨文档的综合分析
+
+---
+
+## 架构
+
+```
+hy3-research-assistant/
+├── backend/
+│   ├── main.py            # FastAPI 服务器（6 个 API 端点）
+│   ├── hy3_client.py      # Hy3 API 客户端（OpenAI 兼容）
+│   ├── tools.py            # 网页搜索、文件解析工具
+│   └── requirements.txt   # Python 依赖
+├── frontend/
+│   └── index.html          # 现代化单页应用（纯 HTML/CSS/JS）
+├── .env.example            # 环境变量模板
+└── README.md               # 项目文档
+```
+
+**技术栈：**
+- **后端**：Python 3.10+ · FastAPI · OpenAI SDK（Hy3 兼容）
+- **前端**：纯 HTML5/CSS3/JavaScript（零依赖）
+- **大模型**：腾讯混元 Hy3（295B MoE，21B 活跃参数）
+- **搜索**：DuckDuckGo（无需 API 密钥）
+- **文件解析**：PyPDF2、python-docx
+
+---
+
+## 快速开始
+
+### 前提条件
+
+- Python 3.10+
+- 从 [腾讯云控制台](https://console.cloud.tencent.com/hunyuan) 获取 Hy3 API 密钥
+
+### 安装运行
+
+```bash
+# 1. 进入项目目录
+cd hy3-research-assistant
+
+# 2. 设置 Hy3 API 密钥
+export HY3_API_KEY="你的 API 密钥"
+
+# Windows 系统使用:
+set HY3_API_KEY=你的 API 密钥
+
+# 3. 安装依赖
+cd backend
+pip install -r requirements.txt
+
+# 4. 启动服务器
+python main.py
+```
+
+在浏览器中访问 http://localhost:8000 即可使用。
+
+### API 端点
+
+| 方法 | 端点 | 描述 |
+|------|------|------|
+| `GET` | `/api/health` | 健康检查 |
+| `POST` | `/api/research` | 深度研究（完整版） |
+| `POST` | `/api/research/stream` | 深度研究（流式 SSE） |
+| `POST` | `/api/analyze-code` | 代码分析 |
+| `POST` | `/api/upload-documents` | 上传文档 |
+| `POST` | `/api/qa` | 文档问答 |
+
+---
+
+## Hy3 API 配置
+
+Hy3 提供了 **OpenAI 兼容的 API**。本项目使用标准的 `openai` Python SDK 配合 Hy3 的接口地址：
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="你的 Hy3 API 密钥",
+    base_url="https://api.hunyuan.cloud.tencent.com/v1",
+)
+
+response = client.chat.completions.create(
+    model="hunyuan-hy3-295b-a21b",
+    messages=[{"role": "user", "content": "你好！"}],
+)
+```
+
+环境变量说明：
+- `HY3_API_KEY` — 腾讯云 API 密钥 **（必填）**
+- `HY3_BASE_URL` — API 基础地址（默认：`https://api.hunyuan.cloud.tencent.com/v1`）
+- `HY3_MODEL` — 模型名称（默认：`hunyuan-hy3-295b-a21b`）
+
+---
+
+## 开发说明
+
+### CodeBuddy 协作
+
+本项目使用 **CodeBuddy** 作为主要开发环境。以下是由 CodeBuddy 生成或大幅协助完成的代码模块：
+
+| 文件 | CodeBuddy 贡献 |
+|------|---------------|
+| `backend/hy3_client.py` | 完整文件 — Hy3 API 客户端封装，含流式支持 |
+| `backend/tools.py` | 完整文件 — 网页搜索爬虫、多格式文件解析器 |
+| `backend/main.py` | 完整文件 — FastAPI 服务器及所有端点（含流式） |
+| `frontend/index.html` | 完整文件 — 单页应用（暗色主题、SSE 流式、Markdown 渲染） |
+| `README.md` | 完整文件 — 项目文档和配置指南 |
+
+开发者的主要工作：
+- 设计应用架构
+- 选择技术栈
+- 配置 Hy3 API 凭证
+- 测试和迭代提示词工程
+- 制作演示录屏
+
+### 提示词工程
+
+系统使用精心设计的提示词来最大化 Hy3 的能力：
+
+1. **研究规划器**：结构化 JSON 输出，用于制定研究计划
+2. **研究报告撰写器**：学术风格的写作，带来源引用
+3. **代码分析器**：领域专用分析（Bug 检测/优化/解释）
+4. **文档问答器**：基于证据的回答，支持段落引用
+
+---
+
+## 许可证
+
+MIT License — 模型许可参见 [Hy3 仓库](https://github.com/Tencent-Hunyuan/Hy3)
+
+---
+
+## 致谢
+
+- [腾讯混元 Hy3](https://github.com/Tencent-Hunyuan/Hy3) — 驱动本应用的 295B MoE 模型
+- 腾讯犀牛鸟开源人才培养计划 2026
+- 使用 [CodeBuddy](https://www.codebuddy.ai/) 构建
diff --git a/start.bat b/start.bat
new file mode 100644
index 00000000..e2b8e339
--- /dev/null
+++ b/start.bat
@@ -0,0 +1,36 @@
+@echo off
+echo ============================================
+echo     Hy3 研究助手 - 一键启动脚本
+echo ============================================
+echo.
+
+REM 检查 Python
+python --version >nul 2>&1
+if errorlevel 1 (
+    echo [错误] 未检测到 Python，请先安装 Python 并添加到 PATH 环境变量。
+    pause
+    exit /b 1
+)
+
+REM 检查 API 密钥
+if "%HY3_API_KEY%"=="" (
+    echo [警告] 未设置 HY3_API_KEY 环境变量。
+    echo 请在运行前设置 API 密钥：
+    echo   set HY3_API_KEY=你的 API 密钥
+    echo.
+)
+
+REM 安装依赖
+echo [1/2] 正在安装 Python 依赖...
+cd /d "%~dp0backend"
+pip install -r requirements.txt -q
+
+REM 启动服务器
+echo [2/2] 正在启动服务器...
+echo.
+echo 服务器将在以下地址启动: http://localhost:8000
+echo 按 Ctrl+C 停止服务器。
+echo.
+python main.py
+
+pause

From 2576f86590a1baf3685274eec232bce47f8a3bc9 Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Wed, 22 Jul 2026 09:01:02 +0800
Subject: [PATCH 02/12] Add files via upload

---
 .env.example |  16 +++--
 .gitignore   |  15 +---
 README.md    | 200 ++++++++++++++++++++-------------------------------
 start.bat    |  38 ++++------
 4 files changed, 105 insertions(+), 164 deletions(-)

diff --git a/.env.example b/.env.example
index 9312ed80..773cbc1c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,7 +1,11 @@
-# Hy3 API 配置
-# 从腾讯云控制台获取 API 密钥：
-# https://console.cloud.tencent.com/hunyuan
+# Hy3 API 密钥（必填）
+HY3_API_KEY=你的API密钥
 
-HY3_API_KEY=在此填写你的 API 密钥
-HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
-HY3_MODEL=hunyuan-hy3-295b-a21b
+# API 端点（选填，默认混元云端）
+# HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
+
+# 模型名称（选填，默认 hunyuan-pro）
+# HY3_MODEL=hunyuan-pro
+
+# 服务端口（选填，默认 8000）
+# PORT=8000
diff --git a/.gitignore b/.gitignore
index 6f9bb002..08937d87 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,24 +1,15 @@
-# Python
 __pycache__/
-*.py[cod]
+*.pyc
+*.pyo
+.env
 *.egg-info/
 dist/
 build/
 .venv/
 venv/
-
-# Environment
-.env
-
-# IDE
 .idea/
 .vscode/
 *.swp
 *.swo
-
-# OS
 .DS_Store
 Thumbs.db
-
-# Uploaded files
-uploads/
diff --git a/README.md b/README.md
index 09b2308b..2c731e5e 100644
--- a/README.md
+++ b/README.md
@@ -1,174 +1,128 @@
 # Hy3 研究助手
 
-> 基于 **腾讯混元 Hy3**（295B MoE 模型）的端到端研究助手应用。
->
-> 🏷️ 腾讯犀牛鸟开源人才培养计划 2026 · Issue [#4](https://github.com/Tencent-Hunyuan/Hy3/issues/4)
+基于腾讯混元 Hy3 大模型的智能研究助手，提供**深度研究**、**代码分析**、**文档问答**三大核心功能。
 
----
+## 项目简介
 
-## 项目概述
+本项目是腾讯犀牛鸟实战计划 [Issue #4](https://github.com/Tencent-Hunyuan/Hy3/issues/4) 的完整实现。所有智能任务（研究规划、报告生成、代码分析、文档问答）均通过调用 **Hy3 API**（OpenAI 兼容接口）完成，不涉及模型训练、微调或本地推理。
 
-Hy3 研究助手是一个全栈 Web 应用，展示了 **Hy3 在实际场景中的强大能力**：
+### Hy3 在项目中的角色
 
-| 功能 | 描述 | Hy3 扮演的角色 |
-|------|------|---------------|
-| 🔬 **深度研究** | 规划 → 搜索 → 长文报告（带引用来源） | 规划智能体、信息综合、报告撰写 |
-| 💻 **代码分析** | Bug 检测、性能优化、代码解释 | 代码理解、逻辑分析、重构建议 |
-| 📄 **文档问答** | 多文档上传与智能问答 | 阅读理解、基于证据的回答 |
+| 功能模块 | Hy3 的角色 |
+|---------|-----------|
+| 深度研究 | 研究计划制定 → 搜索关键词生成 → 长文报告撰写 → 执行摘要提炼 |
+| 代码分析 | 代码理解、Bug 检测、性能优化建议、安全审计、质量评分 |
+| 文档问答 | 多文档阅读理解、证据驱动的精准问答 |
 
-所有 LLM 能力**完全通过 Hy3 API 实现**——无需训练、微调或本地推理。
-
----
-
-## 演示流程
-
-### 演示一：「MoE 架构效率」深度研究
-
-1. 输入主题：「MoE 架构对 LLM 推理效率的影响」
-2. Hy3 生成包含 4 个关键问题和搜索查询的研究计划
-3. 系统执行网页搜索并收集来源
-4. Hy3 撰写带有引用标注（[来源 1], [来源 2], ...）的全面报告
-5. 生成中英文双语执行摘要
-
-### 演示二：技术论文多文档问答
-
-1. 上传 2-3 个技术 PDF/TXT 文件
-2. 提问：「比较这些文档中描述的方法，关键区别是什么？」
-3. Hy3 读取所有文档并提供跨文档的综合分析
-
----
-
-## 架构
+## 项目结构
 
 ```
 hy3-research-assistant/
 ├── backend/
-│   ├── main.py            # FastAPI 服务器（6 个 API 端点）
-│   ├── hy3_client.py      # Hy3 API 客户端（OpenAI 兼容）
-│   ├── tools.py            # 网页搜索、文件解析工具
+│   ├── main.py            # FastAPI 服务器（6 个 API 端点，全部支持 SSE 流式输出）
+│   ├── hy3_client.py      # Hy3 API 客户端封装（OpenAI 兼容接口）
+│   ├── tools.py            # 工具函数（网页搜索、PDF/DOCX/代码文件解析）
 │   └── requirements.txt   # Python 依赖
 ├── frontend/
-│   └── index.html          # 现代化单页应用（纯 HTML/CSS/JS）
-├── .env.example            # 环境变量模板
-└── README.md               # 项目文档
+│   └── index.html          # 现代化 Web 前端（暗色主题、流式渲染、Markdown 展示）
+├── .env.example            # 环境变量配置模板
+├── .gitignore
+├── start.bat               # Windows 一键启动脚本
+└── README.md
 ```
 
-**技术栈：**
-- **后端**：Python 3.10+ · FastAPI · OpenAI SDK（Hy3 兼容）
-- **前端**：纯 HTML5/CSS3/JavaScript（零依赖）
-- **大模型**：腾讯混元 Hy3（295B MoE，21B 活跃参数）
-- **搜索**：DuckDuckGo（无需 API 密钥）
-- **文件解析**：PyPDF2、python-docx
-
----
-
 ## 快速开始
 
-### 前提条件
+### 环境要求
 
-- Python 3.10+
-- 从 [腾讯云控制台](https://console.cloud.tencent.com/hunyuan) 获取 Hy3 API 密钥
+- Python 3.9+
+- 有效的 Hy3 API Key
 
-### 安装运行
+### 安装与启动
 
 ```bash
-# 1. 进入项目目录
+# 1. 克隆项目
 cd hy3-research-assistant
 
-# 2. 设置 Hy3 API 密钥
-export HY3_API_KEY="你的 API 密钥"
-
-# Windows 系统使用:
-set HY3_API_KEY=你的 API 密钥
+# 2. 配置 API 密钥
+# Windows
+set HY3_API_KEY=你的API密钥
+# 或复制 .env.example 为 .env 并填入密钥
 
 # 3. 安装依赖
 cd backend
 pip install -r requirements.txt
 
-# 4. 启动服务器
+# 4. 启动服务
 python main.py
+# 服务运行在 http://localhost:8000
 ```
 
-在浏览器中访问 http://localhost:8000 即可使用。
+打开浏览器访问 `http://localhost:8000` 即可使用。
 
-### API 端点
+### 可选环境变量
 
-| 方法 | 端点 | 描述 |
-|------|------|------|
-| `GET` | `/api/health` | 健康检查 |
-| `POST` | `/api/research` | 深度研究（完整版） |
-| `POST` | `/api/research/stream` | 深度研究（流式 SSE） |
-| `POST` | `/api/analyze-code` | 代码分析 |
-| `POST` | `/api/upload-documents` | 上传文档 |
-| `POST` | `/api/qa` | 文档问答 |
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `HY3_API_KEY` | Hy3 API 密钥（必填） | - |
+| `HY3_BASE_URL` | API 端点地址 | `https://api.hunyuan.cloud.tencent.com/v1` |
+| `HY3_MODEL` | 模型名称 | `hunyuan-pro` |
+| `PORT` | 服务端口 | `8000` |
 
----
+## 三大功能
 
-## Hy3 API 配置
+### 🔬 深度研究 (Deep Research)
 
-Hy3 提供了 **OpenAI 兼容的 API**。本项目使用标准的 `openai` Python SDK 配合 Hy3 的接口地址：
+输入研究主题，Hy3 将自动完成：
 
-```python
-from openai import OpenAI
+1. **研究规划** — 将主题拆解为子问题，生成搜索关键词
+2. **资料搜索** — 自动搜索相关网页资料
+3. **报告撰写** — 基于搜索结果生成 1500-3000 字专业研究报告
+4. **执行摘要** — 提炼核心发现的简明摘要
 
-client = OpenAI(
-    api_key="你的 Hy3 API 密钥",
-    base_url="https://api.hunyuan.cloud.tencent.com/v1",
-)
-
-response = client.chat.completions.create(
-    model="hunyuan-hy3-295b-a21b",
-    messages=[{"role": "user", "content": "你好！"}],
-)
-```
+### 💻 代码分析 (Code Analysis)
 
-环境变量说明：
-- `HY3_API_KEY` — 腾讯云 API 密钥 **（必填）**
-- `HY3_BASE_URL` — API 基础地址（默认：`https://api.hunyuan.cloud.tencent.com/v1`）
-- `HY3_MODEL` — 模型名称（默认：`hunyuan-hy3-295b-a21b`）
+粘贴代码或上传代码文件，Hy3 将提供：
 
----
+- 代码概览与核心功能解读
+- 执行逻辑与关键流程分析
+- 潜在 Bug、性能隐患、安全问题诊断
+- 具体优化建议与最佳实践
+- 1-10 分代码质量评分
 
-## 开发说明
+### 📚 文档问答 (Document Q&A)
 
-### CodeBuddy 协作
+上传多个文档（支持 PDF、DOCX、TXT、代码文件等），向 Hy3 提问：
 
-本项目使用 **CodeBuddy** 作为主要开发环境。以下是由 CodeBuddy 生成或大幅协助完成的代码模块：
+- 基于文档内容精准回答
+- 引用原始段落作为证据
+- 明确标注信息缺失情况
 
-| 文件 | CodeBuddy 贡献 |
-|------|---------------|
-| `backend/hy3_client.py` | 完整文件 — Hy3 API 客户端封装，含流式支持 |
-| `backend/tools.py` | 完整文件 — 网页搜索爬虫、多格式文件解析器 |
-| `backend/main.py` | 完整文件 — FastAPI 服务器及所有端点（含流式） |
-| `frontend/index.html` | 完整文件 — 单页应用（暗色主题、SSE 流式、Markdown 渲染） |
-| `README.md` | 完整文件 — 项目文档和配置指南 |
+## API 端点
 
-开发者的主要工作：
-- 设计应用架构
-- 选择技术栈
-- 配置 Hy3 API 凭证
-- 测试和迭代提示词工程
-- 制作演示录屏
-
-### 提示词工程
-
-系统使用精心设计的提示词来最大化 Hy3 的能力：
-
-1. **研究规划器**：结构化 JSON 输出，用于制定研究计划
-2. **研究报告撰写器**：学术风格的写作，带来源引用
-3. **代码分析器**：领域专用分析（Bug 检测/优化/解释）
-4. **文档问答器**：基于证据的回答，支持段落引用
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/` | GET | 前端页面 |
+| `/health` | GET | 服务健康检查 |
+| `/api/research` | POST | 深度研究（流式） |
+| `/api/analyze-code` | POST | 粘贴代码分析（流式） |
+| `/api/analyze-code-file` | POST | 上传代码文件分析（流式） |
+| `/api/qa-documents` | POST | 多文档问答（流式） |
 
----
+所有智能端点均使用 Server-Sent Events (SSE) 实现流式输出，支持前端实时渲染。
 
-## 许可证
+## 技术栈
 
-MIT License — 模型许可参见 [Hy3 仓库](https://github.com/Tencent-Hunyuan/Hy3)
+- **后端**: FastAPI + OpenAI SDK + Uvicorn
+- **前端**: 原生 HTML/CSS/JS + marked.js（Markdown 渲染）
+- **模型**: 腾讯混元 Hy3（通过 OpenAI 兼容接口调用）
+- **工具**: DuckDuckGo 网页搜索、PyPDF2、python-docx
 
----
+## CodeBuddy 协作说明
 
-## 致谢
+本项目借助 CodeBuddy AI 编程助手完成：
 
-- [腾讯混元 Hy3](https://github.com/Tencent-Hunyuan/Hy3) — 驱动本应用的 295B MoE 模型
-- 腾讯犀牛鸟开源人才培养计划 2026
-- 使用 [CodeBuddy](https://www.codebuddy.ai/) 构建
+- **协同设计**：AI 参与整体架构规划、功能模块拆解、前后端交互设计
+- **代码生成**：AI 编写了 `backend/main.py`（服务器和所有提示词工程）、`backend/hy3_client.py`（API 客户端封装）、`backend/tools.py`（搜索和文件解析）、`frontend/index.html`（完整前端界面）
+- **文档撰写**：AI 生成了 README、配置模板、启动脚本
+- **代码审查与打磨**：AI 辅助进行了语法检查、中英文翻译、结构优化
diff --git a/start.bat b/start.bat
index e2b8e339..faaecbfc 100644
--- a/start.bat
+++ b/start.bat
@@ -1,36 +1,28 @@
 @echo off
-echo ============================================
-echo     Hy3 研究助手 - 一键启动脚本
-echo ============================================
+chcp 65001 >nul
+echo ========================================
+echo   Hy3 研究助手 一键启动
+echo ========================================
 echo.
 
-REM 检查 Python
-python --version >nul 2>&1
-if errorlevel 1 (
-    echo [错误] 未检测到 Python，请先安装 Python 并添加到 PATH 环境变量。
-    pause
-    exit /b 1
-)
-
-REM 检查 API 密钥
+REM 检查 API Key
 if "%HY3_API_KEY%"=="" (
-    echo [警告] 未设置 HY3_API_KEY 环境变量。
-    echo 请在运行前设置 API 密钥：
-    echo   set HY3_API_KEY=你的 API 密钥
+    echo [警告] 未设置 HY3_API_KEY 环境变量
+    echo 请先执行: set HY3_API_KEY=你的API密钥
     echo.
+    pause
+    exit /b 1
 )
 
-REM 安装依赖
-echo [1/2] 正在安装 Python 依赖...
+echo [信息] API Key 已配置
+echo [信息] 正在安装依赖...
 cd /d "%~dp0backend"
 pip install -r requirements.txt -q
-
-REM 启动服务器
-echo [2/2] 正在启动服务器...
 echo.
-echo 服务器将在以下地址启动: http://localhost:8000
-echo 按 Ctrl+C 停止服务器。
+
+echo [信息] 启动服务...
+echo 前端页面: http://localhost:8000
+echo 按 Ctrl+C 停止服务
 echo.
 python main.py
-
 pause

From 6040f7c80ab9796f98356bf299144a2333b928bb Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Wed, 22 Jul 2026 09:26:42 +0800
Subject: [PATCH 03/12] Add files via upload


From e9efa63c3388c120a7e812013ffa704a5232d623 Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Thu, 23 Jul 2026 20:15:54 +0800
Subject: [PATCH 04/12] Add files via upload

---
 .env.example     |  13 +--
 .gitignore       |  10 +-
 README.md        | 268 +++++++++++++++++++++++++++++++++--------------
 requirements.txt |   3 +
 setup.bat        |  54 ++++++++++
 setup.sh         |  43 ++++++++
 6 files changed, 293 insertions(+), 98 deletions(-)
 create mode 100644 requirements.txt
 create mode 100644 setup.bat
 create mode 100644 setup.sh

diff --git a/.env.example b/.env.example
index 773cbc1c..d098a0d8 100644
--- a/.env.example
+++ b/.env.example
@@ -1,11 +1,4 @@
-# Hy3 API 密钥（必填）
+# Hy3 API 配置
 HY3_API_KEY=你的API密钥
-
-# API 端点（选填，默认混元云端）
-# HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
-
-# 模型名称（选填，默认 hunyuan-pro）
-# HY3_MODEL=hunyuan-pro
-
-# 服务端口（选填，默认 8000）
-# PORT=8000
+HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
+HY3_MODEL=hunyuan-pro
diff --git a/.gitignore b/.gitignore
index 08937d87..44113458 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,14 +2,8 @@ __pycache__/
 *.pyc
 *.pyo
 .env
+.venv/
+venv/
 *.egg-info/
 dist/
 build/
-.venv/
-venv/
-.idea/
-.vscode/
-*.swp
-*.swo
-.DS_Store
-Thumbs.db
diff --git a/README.md b/README.md
index 2c731e5e..4b397e19 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,50 @@
-# Hy3 研究助手
+# Hy3 MCP Server
 
-基于腾讯混元 Hy3 大模型的智能研究助手，提供**深度研究**、**代码分析**、**文档问答**三大核心功能。
+基于 **MCP (Model Context Protocol)** 协议，封装**腾讯混元 Hy3** 大模型能力的智能工具集。
+
+可一键安装、即插即用到任何支持 MCP 的 AI 客户端（CodeBuddy / WorkBuddy / Cursor / Cline / Claude Desktop 等）。
+
+---
 
 ## 项目简介
 
-本项目是腾讯犀牛鸟实战计划 [Issue #4](https://github.com/Tencent-Hunyuan/Hy3/issues/4) 的完整实现。所有智能任务（研究规划、报告生成、代码分析、文档问答）均通过调用 **Hy3 API**（OpenAI 兼容接口）完成，不涉及模型训练、微调或本地推理。
+本项目是**腾讯犀牛鸟实战计划 [Issue #3](https://github.com/Tencent-Hunyuan/Hy3/issues/3)** 的完整实现。通过 MCP 协议将 Hy3 大模型的能力暴露为标准化工具（Tools），让支持 MCP 的 AI 客户端可以直接调用 Hy3 完成深度研究、代码评审、文档问答、数据分析等任务。
+
+### Hy3 在本项目中的角色
 
-### Hy3 在项目中的角色
+所有工具的**核心推理、分析、生成能力**均由 Hy3 API 提供：
 
-| 功能模块 | Hy3 的角色 |
-|---------|-----------|
-| 深度研究 | 研究计划制定 → 搜索关键词生成 → 长文报告撰写 → 执行摘要提炼 |
-| 代码分析 | 代码理解、Bug 检测、性能优化建议、安全审计、质量评分 |
-| 文档问答 | 多文档阅读理解、证据驱动的精准问答 |
+| 工具 | Hy3 的角色 |
+|------|-----------|
+| `hy3_research` | 搜索资料整合 → 报告规划 → 长文撰写 → 执行摘要提炼 |
+| `hy3_code_review` | 代码理解 → Bug 检测 → 性能分析 → 安全审计 → 优化建议 |
+| `hy3_doc_qa` | 文档阅读理解 → 证据驱动的精准问答 |
+| `hy3_data_analyze` | 数据模式识别 → 趋势分析 → 洞察生成 → 行动建议 |
+| `hy3_chat` | 自由对话、创意写作、翻译、解释等通用场景 |
+
+---
 
 ## 项目结构
 
 ```
-hy3-research-assistant/
-├── backend/
-│   ├── main.py            # FastAPI 服务器（6 个 API 端点，全部支持 SSE 流式输出）
-│   ├── hy3_client.py      # Hy3 API 客户端封装（OpenAI 兼容接口）
-│   ├── tools.py            # 工具函数（网页搜索、PDF/DOCX/代码文件解析）
-│   └── requirements.txt   # Python 依赖
-├── frontend/
-│   └── index.html          # 现代化 Web 前端（暗色主题、流式渲染、Markdown 展示）
-├── .env.example            # 环境变量配置模板
-├── .gitignore
-├── start.bat               # Windows 一键启动脚本
-└── README.md
+hy3-mcp-server/
+├── src/
+│   ├── server.py          # MCP Server 主程序（5 个 Tool）
+│   ├── hy3_client.py      # Hy3 API 客户端（OpenAI 兼容封装）
+│   └── __init__.py
+├── configs/
+│   ├── codebuddy-mcp.json # CodeBuddy / WorkBuddy 配置示例
+│   ├── cursor-mcp.json    # Cursor 配置示例
+│   ├── claude-mcp.json    # Claude Desktop 配置示例
+│   └── cline-mcp.json     # Cline 配置示例
+├── requirements.txt        # Python 依赖
+├── setup.bat               # Windows 一键安装脚本
+├── setup.sh                # Linux/macOS 一键安装脚本
+└── README.md               # 本文档
 ```
 
+---
+
 ## 快速开始
 
 ### 环境要求
@@ -38,91 +52,185 @@ hy3-research-assistant/
 - Python 3.9+
 - 有效的 Hy3 API Key
 
-### 安装与启动
-
-```bash
-# 1. 克隆项目
-cd hy3-research-assistant
+### 一键安装
 
-# 2. 配置 API 密钥
-# Windows
+**Windows：**
+```batch
+cd hy3-mcp-server
 set HY3_API_KEY=你的API密钥
-# 或复制 .env.example 为 .env 并填入密钥
+setup.bat
+```
+
+**Linux / macOS：**
+```bash
+cd hy3-mcp-server
+export HY3_API_KEY=你的API密钥
+bash setup.sh
+```
 
-# 3. 安装依赖
-cd backend
+或手动安装：
+```bash
 pip install -r requirements.txt
+```
 
-# 4. 启动服务
-python main.py
-# 服务运行在 http://localhost:8000
+---
+
+## 在 AI 客户端中配置
+
+### 1. CodeBuddy / WorkBuddy
+
+将以下配置添加到 CodeBuddy 的 MCP 设置中：
+
+```json
+{
+  "mcpServers": {
+    "hy3-assistant": {
+      "type": "stdio",
+      "command": "python",
+      "args": ["src/server.py"],
+      "cwd": "你的hy3-mcp-server项目路径",
+      "env": {
+        "HY3_API_KEY": "你的API密钥",
+        "HY3_MODEL": "hunyuan-pro"
+      }
+    }
+  }
+}
 ```
 
-打开浏览器访问 `http://localhost:8000` 即可使用。
+配置完成后，在 CodeBuddy 对话中即可直接调用 Hy3 工具，例如：
+> "请用 hy3_research 帮我研究一下大模型在医疗领域的应用"
+
+### 2. Cursor
+
+将 `configs/cursor-mcp.json` 的内容复制到 `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局级）。
+
+### 3. Claude Desktop
+
+将 `configs/claude-mcp.json` 的内容添加到 Claude Desktop 的配置文件中：
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### 4. Cline (VS Code 插件)
 
-### 可选环境变量
+将 `configs/cline-mcp.json` 的内容添加到 Cline 的 MCP 设置中。
 
-| 变量名 | 说明 | 默认值 |
-|--------|------|--------|
-| `HY3_API_KEY` | Hy3 API 密钥（必填） | - |
-| `HY3_BASE_URL` | API 端点地址 | `https://api.hunyuan.cloud.tencent.com/v1` |
-| `HY3_MODEL` | 模型名称 | `hunyuan-pro` |
-| `PORT` | 服务端口 | `8000` |
+---
 
-## 三大功能
+## 工具说明
 
-### 🔬 深度研究 (Deep Research)
+### 🔬 hy3_research — 深度研究助手
 
-输入研究主题，Hy3 将自动完成：
+自动搜索网络资料，由 Hy3 大模型分析并生成结构化研究报告。
 
-1. **研究规划** — 将主题拆解为子问题，生成搜索关键词
-2. **资料搜索** — 自动搜索相关网页资料
-3. **报告撰写** — 基于搜索结果生成 1500-3000 字专业研究报告
-4. **执行摘要** — 提炼核心发现的简明摘要
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `topic` | string | ✅ | 研究主题 |
+| `depth` | string | ❌ | 研究深度：`"detailed"`(默认) 或 `"brief"` |
 
-### 💻 代码分析 (Code Analysis)
+**示例调用：**
+```
+请用 hy3_research 研究"新能源汽车电池回收技术的现状与挑战"，depth=detailed
+```
 
-粘贴代码或上传代码文件，Hy3 将提供：
+### 💻 hy3_code_review — 代码评审助手
 
-- 代码概览与核心功能解读
-- 执行逻辑与关键流程分析
-- 潜在 Bug、性能隐患、安全问题诊断
-- 具体优化建议与最佳实践
-- 1-10 分代码质量评分
+对代码进行多维度审查：Bug 检测、性能分析、安全审计、优化建议。
 
-### 📚 文档问答 (Document Q&A)
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `code` | string | ✅ | 需审查的完整代码 |
+| `language` | string | ❌ | 编程语言，默认 `"auto"` |
+| `review_focus` | string | ❌ | 审查重点：`"comprehensive"`(默认)、`"security"`、`"performance"`、`"bugs"` |
 
-上传多个文档（支持 PDF、DOCX、TXT、代码文件等），向 Hy3 提问：
+**示例调用：**
+```
+请用 hy3_code_review 审查以下代码，重点关注安全问题：
+[贴入代码]
+```
 
-- 基于文档内容精准回答
-- 引用原始段落作为证据
-- 明确标注信息缺失情况
+### 📚 hy3_doc_qa — 文档问答助手
 
-## API 端点
+读取本地文档，由 Hy3 基于文档内容精准回答。
 
-| 端点 | 方法 | 说明 |
-|------|------|------|
-| `/` | GET | 前端页面 |
-| `/health` | GET | 服务健康检查 |
-| `/api/research` | POST | 深度研究（流式） |
-| `/api/analyze-code` | POST | 粘贴代码分析（流式） |
-| `/api/analyze-code-file` | POST | 上传代码文件分析（流式） |
-| `/api/qa-documents` | POST | 多文档问答（流式） |
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_path` | string | ✅ | 文档的本地路径 |
+| `question` | string | ✅ | 你想问的问题 |
 
-所有智能端点均使用 Server-Sent Events (SSE) 实现流式输出，支持前端实时渲染。
+支持格式：`.txt` `.md` `.py` `.js` `.ts` `.json` `.csv` `.html` `.css` `.yaml`
 
-## 技术栈
+**示例调用：**
+```
+请用 hy3_doc_qa 读取 /path/to/report.md，回答"报告中有哪些关键数据指标？"
+```
+
+### 📊 hy3_data_analyze — 数据分析助手
+
+读取 CSV 或 JSON 数据，由 Hy3 进行深度分析和洞察输出。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_path` | string | ✅ | 数据文件路径（.csv/.json） |
+| `analysis_goal` | string | ❌ | 分析目标，默认 `"全面分析"` |
+
+**示例调用：**
+```
+请用 hy3_data_analyze 分析 /path/to/sales.csv，"分析各季度的销售趋势并找出异常数据"
+```
+
+### 💬 hy3_chat — 通用对话助手
+
+与 Hy3 自由对话，适用于其他工具未覆盖的灵活场景。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `message` | string | ✅ | 你想说的话或问题 |
+| `system_prompt` | string | ❌ | 设定 AI 角色与行为 |
+
+---
+
+## 技术细节
+
+- **MCP 协议**: 使用 Python FastMCP 框架，遵循标准 stdio 传输模式
+- **Hy3 调用**: 通过 OpenAI 兼容接口，支持 `HY3_API_KEY`、`HY3_BASE_URL`、`HY3_MODEL` 环境变量
+- **数据源**: DuckDuckGo 网页搜索（无需额外 API Key）、本地文件读取
+- **安全**: API Key 仅通过环境变量传入，代码中无硬编码
+
+---
+
+## 环境变量
+
+| 变量名 | 必填 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `HY3_API_KEY` | ✅ | - | Hy3 API 密钥 |
+| `HY3_BASE_URL` | ❌ | `https://api.hunyuan.cloud.tencent.com/v1` | API 端点 |
+| `HY3_MODEL` | ❌ | `hunyuan-pro` | 模型名称 |
+
+---
+
+## 手动测试
+
+启动 MCP Server 进行本地验证：
+```bash
+cd src
+export HY3_API_KEY=你的API密钥
+python server.py
+```
+
+或使用 MCP Inspector 调试：
+```bash
+npx @modelcontextprotocol/inspector python src/server.py
+```
 
-- **后端**: FastAPI + OpenAI SDK + Uvicorn
-- **前端**: 原生 HTML/CSS/JS + marked.js（Markdown 渲染）
-- **模型**: 腾讯混元 Hy3（通过 OpenAI 兼容接口调用）
-- **工具**: DuckDuckGo 网页搜索、PyPDF2、python-docx
+---
 
 ## CodeBuddy 协作说明
 
 本项目借助 CodeBuddy AI 编程助手完成：
 
-- **协同设计**：AI 参与整体架构规划、功能模块拆解、前后端交互设计
-- **代码生成**：AI 编写了 `backend/main.py`（服务器和所有提示词工程）、`backend/hy3_client.py`（API 客户端封装）、`backend/tools.py`（搜索和文件解析）、`frontend/index.html`（完整前端界面）
-- **文档撰写**：AI 生成了 README、配置模板、启动脚本
-- **代码审查与打磨**：AI 辅助进行了语法检查、中英文翻译、结构优化
+- **架构设计**: AI 参与 MCP Server 整体架构、工具拆解和接口设计
+- **代码生成**: AI 编写了 `server.py`（5 个 MCP Tool + Hy3 调用逻辑）、`hy3_client.py`（API 客户端封装）
+- **多客户端适配**: AI 生成了 CodeBuddy、Cursor、Claude Desktop、Cline 四种客户端的配置示例
+- **文档撰写**: AI 编写了 README、安装脚本、配置说明
+- **代码审查**: AI 辅助进行了语法验证和结构优化
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 00000000..a5c3e52b
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,3 @@
+fastmcp>=2.0.0
+openai>=1.50.0
+httpx>=0.28.0
diff --git a/setup.bat b/setup.bat
new file mode 100644
index 00000000..1c7be735
--- /dev/null
+++ b/setup.bat
@@ -0,0 +1,54 @@
+@echo off
+chcp 65001 >nul
+echo ==============================================
+echo   Hy3 MCP Server - 一键安装脚本
+echo ==============================================
+echo.
+
+REM 检查 Python
+python --version >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [错误] 未检测到 Python，请先安装 Python 3.9+
+    pause
+    exit /b 1
+)
+
+echo [信息] Python 已检测到
+echo.
+
+REM 检查 API Key
+if "%HY3_API_KEY%"=="" (
+    echo [警告] 未设置 HY3_API_KEY 环境变量
+    echo.
+    echo 请先设置 API Key：
+    echo   set HY3_API_KEY=你的API密钥
+    echo.
+    echo 或创建 .env 文件并添加：
+    echo   HY3_API_KEY=你的API密钥
+    echo.
+)
+
+REM 安装依赖
+echo [信息] 正在安装依赖...
+cd /d "%~dp0"
+pip install -r requirements.txt -q
+echo.
+
+REM 验证安装
+echo [信息] 正在验证安装...
+python -c "from fastmcp import FastMCP; print('  [OK] FastMCP')" 2>nul
+python -c "from openai import OpenAI; print('  [OK] OpenAI SDK')" 2>nul
+python -c "import httpx; print('  [OK] httpx')" 2>nul
+echo.
+
+echo [信息] 安装完成！
+echo.
+echo 启动方式（在 CodeBuddy 中配置 MCP）：
+echo   将 configs/codebuddy-mcp.json 中的配置添加到 CodeBuddy 的 MCP 设置中。
+echo.
+echo 或手动测试：
+echo   cd src
+echo   set HY3_API_KEY=你的API密钥
+echo   python server.py
+echo.
+pause
diff --git a/setup.sh b/setup.sh
new file mode 100644
index 00000000..26eb7e8f
--- /dev/null
+++ b/setup.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+echo "=============================================="
+echo "  Hy3 MCP Server - 一键安装脚本"
+echo "=============================================="
+echo ""
+
+# 检查 Python
+if ! command -v python3 &> /dev/null; then
+    echo "[错误] 未检测到 Python，请先安装 Python 3.9+"
+    exit 1
+fi
+
+echo "[信息] Python 已检测到"
+
+# 检查 API Key
+if [ -z "$HY3_API_KEY" ]; then
+    echo "[警告] 未设置 HY3_API_KEY 环境变量"
+    echo ""
+    echo "请先设置 API Key："
+    echo "  export HY3_API_KEY=你的API密钥"
+    echo ""
+fi
+
+# 安装依赖
+echo "[信息] 正在安装依赖..."
+cd "$(dirname "$0")"
+pip3 install -r requirements.txt -q
+echo ""
+
+# 验证
+echo "[信息] 正在验证安装..."
+python3 -c "from fastmcp import FastMCP; print('  [OK] FastMCP')"
+python3 -c "from openai import OpenAI; print('  [OK] OpenAI SDK')"
+python3 -c "import httpx; print('  [OK] httpx')"
+echo ""
+
+echo "[信息] 安装完成！"
+echo ""
+echo "启动方式（手动测试）："
+echo "  cd src"
+echo "  export HY3_API_KEY=你的API密钥"
+echo "  python3 server.py"
+echo ""

From ebebd68b1af797c0727a8dd7e68dd92808a0a3c1 Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Thu, 23 Jul 2026 20:18:04 +0800
Subject: [PATCH 05/12] Add files via upload


From c4d3b10b512da228f23b5f8591c4a3d5712db68e Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Thu, 23 Jul 2026 21:13:42 +0800
Subject: [PATCH 06/12] Add files via upload


From 1d01d6f1a9fb61a869dbf1fa575c5f4e72da022a Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Thu, 23 Jul 2026 21:35:27 +0800
Subject: [PATCH 07/12] =?UTF-8?q?=E5=9F=BA=E4=BA=8EMCP=20=E5=8D=8F?=
 =?UTF-8?q?=E8=AE=AE=EF=BC=8C=E5=B0=81=E8=A3=85=E8=85=BE=E8=AE=AF=E6=B7=B7?=
 =?UTF-8?q?=E5=85=83=20Hy3=E5=A4=A7=E6=A8=A1=E5=9E=8B=E8=83=BD=E5=8A=9B?=
 =?UTF-8?q?=E7=9A=84=E6=99=BA=E8=83=BD=E5=B7=A5=E5=85=B7=E9=9B=86=20?=
 =?UTF-8?q?=E5=8F=AF=E4=B8=80=E9=94=AE=E5=AE=89=E8=A3=85=E3=80=81=E5=8D=B3?=
 =?UTF-8?q?=E6=8F=92=E5=8D=B3=E7=94=A8=E5=88=B0=E4=BB=BB=E4=BD=95=E6=94=AF?=
 =?UTF-8?q?=E6=8C=81=20MCP=20=E7=9A=84=20AI=20=E5=AE=A2=E6=88=B7=E7=AB=AF?=
 =?UTF-8?q?=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

通过 MCP 协议将 Hy3 大模型的能力暴露为标准化工具（Tools），让支持 MCP 的 AI 客户端可以直接调用 Hy3 完成深度研究、代码评审、文档问答、数据分析等任务。

From 4fd0111bf38227e9bf5e6f811f4ae1d29af28a12 Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Thu, 23 Jul 2026 21:39:32 +0800
Subject: [PATCH 08/12] =?UTF-8?q?=E5=9F=BA=E4=BA=8E=20MCP=20=E5=8D=8F?=
 =?UTF-8?q?=E8=AE=AE=EF=BC=8C=E5=B0=81=E8=A3=85=E8=85=BE=E8=AE=AF=E6=B7=B7?=
 =?UTF-8?q?=E5=85=83=20Hy3=E5=A4=A7=E6=A8=A1=E5=9E=8B=E8=83=BD=E5=8A=9B?=
 =?UTF-8?q?=E7=9A=84=E6=99=BA=E8=83=BD=E5=B7=A5=E5=85=B7=E9=9B=86=E5=8F=AF?=
 =?UTF-8?q?=E4=B8=80=E9=94=AE=E5=AE=89=E8=A3=85=E3=80=81=E5=8D=B3=E6=8F=92?=
 =?UTF-8?q?=E5=8D=B3=E7=94=A8=E5=88=B0=E4=BB=BB=E4=BD=95=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=20MCP=20=E7=9A=84=20AI=20=E5=AE=A2=E6=88=B7=E7=AB=AF=EF=BC=88C?=
 =?UTF-8?q?odeBuddy=20/=20WorkBuddy=20/=20Cursor=20/=20Cline=20/=20Claude?=
 =?UTF-8?q?=20Desktop=20=E7=AD=89=EF=BC=89=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

所有工具的**核心推理、分析、生成能力**均由 Hy3 API 提供：

| 工具 | Hy3 的角色 |
|------|-----------|
| `hy3_research` | 搜索资料整合 → 报告规划 → 长文撰写 → 执行摘要提炼 |
| `hy3_code_review` | 代码理解 → Bug 检测 → 性能分析 → 安全审计 → 优化建议 |
| `hy3_doc_qa` | 文档阅读理解 → 证据驱动的精准问答 |
| `hy3_data_analyze` | 数据模式识别 → 趋势分析 → 洞察生成 → 行动建议 |
| `hy3_chat` | 自由对话、创意写作、翻译、解释等通用场景 |

---

From fbd49178d3cf2d383a490c08de2e6c54ea4181eb Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Fri, 24 Jul 2026 11:15:01 +0800
Subject: [PATCH 09/12] =?UTF-8?q?MCP=E8=A1=A5=E5=85=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🔬 hy3_research — 深度研究助手
自动搜索网络资料，由 Hy3 大模型分析并生成结构化研究报告。

参数	类型	必填	说明
topic	string	✅	研究主题
depth	string	❌	研究深度："detailed"(默认) 或 "brief"
示例调用：

请用 hy3_research 研究"新能源汽车电池回收技术的现状与挑战"，depth=detailed
💻 hy3_code_review — 代码评审助手
对代码进行多维度审查：Bug 检测、性能分析、安全审计、优化建议。

参数	类型	必填	说明
code	string	✅	需审查的完整代码
language	string	❌	编程语言，默认 "auto"
review_focus	string	❌	审查重点："comprehensive"(默认)、"security"、"performance"、"bugs"
示例调用：

请用 hy3_code_review 审查以下代码，重点关注安全问题：
[贴入代码]
📚 hy3_doc_qa — 文档问答助手
读取本地文档，由 Hy3 基于文档内容精准回答。

参数	类型	必填	说明
file_path	string	✅	文档的本地路径
question	string	✅	你想问的问题
支持格式：.txt .md .py .js .ts .json .csv .html .css .yaml

示例调用：

请用 hy3_doc_qa 读取 /path/to/report.md，回答"报告中有哪些关键数据指标？"
📊 hy3_data_analyze — 数据分析助手
读取 CSV 或 JSON 数据，由 Hy3 进行深度分析和洞察输出。

参数	类型	必填	说明
file_path	string	✅	数据文件路径（.csv/.json）
analysis_goal	string	❌	分析目标，默认 "全面分析"
示例调用：

请用 hy3_data_analyze 分析 /path/to/sales.csv，"分析各季度的销售趋势并找出异常数据"
💬 hy3_chat — 通用对话助手
与 Hy3 自由对话，适用于其他工具未覆盖的灵活场景。

参数	类型	必填	说明
message	string	✅	你想说的话或问题
system_prompt	string	❌	设定 AI 角色与行为
技术细节
MCP 协议: 使用 Python FastMCP 框架，遵循标准 stdio 传输模式
Hy3 调用: 通过 OpenAI 兼容接口，支持 HY3_API_KEY、HY3_BASE_URL、HY3_MODEL 环境变量
数据源: DuckDuckGo 网页搜索（无需额外 API Key）、本地文件读取
安全: API Key 仅通过环境变量传入，代码中无硬编码
环境变量
变量名	必填	默认值	说明
HY3_API_KEY	✅	-	Hy3 API 密钥
HY3_BASE_URL	❌	https://api.hunyuan.cloud.tencent.com/v1	API 端点
HY3_MODEL	❌	hunyuan-pro	模型名称
手动测试
---
 .env.example     | 13 ++++++++++---
 requirements.txt |  1 +
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index d098a0d8..484e91e7 100644
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,11 @@
-# Hy3 API 配置
+# Hy3 MCP Server 配置文件
+# 复制此文件为 .env 并填入你的密钥
+
+# 必填：Hy3 API 密钥
 HY3_API_KEY=你的API密钥
-HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
-HY3_MODEL=hunyuan-pro
+
+# 可选：API 端点（默认值如下）
+# HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
+
+# 可选：模型名称（默认 hunyuan-pro）
+# HY3_MODEL=hunyuan-pro
diff --git a/requirements.txt b/requirements.txt
index a5c3e52b..b4fa0528 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,4 @@
 fastmcp>=2.0.0
 openai>=1.50.0
 httpx>=0.28.0
+python-dotenv>=1.0.0

From 212c0ddebf1720bb3f9680f2dddde51d3df4e5a4 Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Fri, 24 Jul 2026 11:19:36 +0800
Subject: [PATCH 10/12] =?UTF-8?q?MCP=E8=A1=A5=E5=85=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🔬 hy3_research — 深度研究助手
自动搜索网络资料，由 Hy3 大模型分析并生成结构化研究报告。

参数	类型	必填	说明
topic	string	✅	研究主题
depth	string	❌	研究深度："detailed"(默认) 或 "brief"
示例调用：

请用 hy3_research 研究"新能源汽车电池回收技术的现状与挑战"，depth=detailed
💻 hy3_code_review — 代码评审助手
对代码进行多维度审查：Bug 检测、性能分析、安全审计、优化建议。

参数	类型	必填	说明
code	string	✅	需审查的完整代码
language	string	❌	编程语言，默认 "auto"
review_focus	string	❌	审查重点："comprehensive"(默认)、"security"、"performance"、"bugs"
示例调用：

请用 hy3_code_review 审查以下代码，重点关注安全问题：
[贴入代码]
📚 hy3_doc_qa — 文档问答助手
读取本地文档，由 Hy3 基于文档内容精准回答。

参数	类型	必填	说明
file_path	string	✅	文档的本地路径
question	string	✅	你想问的问题
支持格式：.txt .md .py .js .ts .json .csv .html .css .yaml

示例调用：

请用 hy3_doc_qa 读取 /path/to/report.md，回答"报告中有哪些关键数据指标？"
📊 hy3_data_analyze — 数据分析助手
读取 CSV 或 JSON 数据，由 Hy3 进行深度分析和洞察输出。

参数	类型	必填	说明
file_path	string	✅	数据文件路径（.csv/.json）
analysis_goal	string	❌	分析目标，默认 "全面分析"
示例调用：

请用 hy3_data_analyze 分析 /path/to/sales.csv，"分析各季度的销售趋势并找出异常数据"
💬 hy3_chat — 通用对话助手
与 Hy3 自由对话，适用于其他工具未覆盖的灵活场景。

参数	类型	必填	说明
message	string	✅	你想说的话或问题
system_prompt	string	❌	设定 AI 角色与行为
技术细节
MCP 协议: 使用 Python FastMCP 框架，遵循标准 stdio 传输模式
Hy3 调用: 通过 OpenAI 兼容接口，支持 HY3_API_KEY、HY3_BASE_URL、HY3_MODEL 环境变量
数据源: DuckDuckGo 网页搜索（无需额外 API Key）、本地文件读取
安全: API Key 仅通过环境变量传入，代码中无硬编码
环境变量
变量名	必填	默认值	说明
HY3_API_KEY	✅	-	Hy3 API 密钥
HY3_BASE_URL	❌	https://api.hunyuan.cloud.tencent.com/v1	API 端点
HY3_MODEL	❌	hunyuan-pro	模型名称
手动测试

From 42e5b2c96812f01b55295a25d57b705152c9473a Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Fri, 24 Jul 2026 14:43:39 +0800
Subject: [PATCH 11/12] =?UTF-8?q?Hy3=E7=A0=94=E7=A9=B6=E5=8A=A9=E6=89=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

三大功能
🔬 深度研究 (Deep Research)
输入研究主题，Hy3 将自动完成：

研究规划 — 将主题拆解为子问题，生成搜索关键词
资料搜索 — 自动搜索相关网页资料
报告撰写 — 基于搜索结果生成 1500-3000 字专业研究报告
执行摘要 — 提炼核心发现的简明摘要
💻 代码分析 (Code Analysis)
粘贴代码或上传代码文件，Hy3 将提供：

代码概览与核心功能解读
执行逻辑与关键流程分析
潜在 Bug、性能隐患、安全问题诊断
具体优化建议与最佳实践
1-10 分代码质量评分
📚 文档问答 (Document Q&A)
上传多个文档（支持 PDF、DOCX、TXT、代码文件等），向 Hy3 提问：

基于文档内容精准回答
引用原始段落作为证据
明确标注信息缺失情况
---
 .env.example |  19 ++--
 .gitignore   |  10 +-
 README.md    | 268 +++++++++++++++------------------------------------
 start.bat    |  36 +++++--
 4 files changed, 127 insertions(+), 206 deletions(-)

diff --git a/.env.example b/.env.example
index 484e91e7..7c322ec1 100644
--- a/.env.example
+++ b/.env.example
@@ -1,11 +1,14 @@
-# Hy3 MCP Server 配置文件
-# 复制此文件为 .env 并填入你的密钥
+# Hy3 Research Assistant 配置文件
+# 复制此文件为 .env 并填写你的 API 密钥
 
-# 必填：Hy3 API 密钥
-HY3_API_KEY=你的API密钥
+# 腾讯混元大模型 API Key（必填）
+HY3_API_KEY=your-api-key-here
 
-# 可选：API 端点（默认值如下）
-# HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
+# Hy3 API 端点（可选，默认为腾讯云）
+HY3_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1
 
-# 可选：模型名称（默认 hunyuan-pro）
-# HY3_MODEL=hunyuan-pro
+# 使用的模型名称（可选，默认 hunyuan-pro）
+HY3_MODEL=hunyuan-pro
+
+# 服务器端口（可选，默认 8000）
+PORT=8000
diff --git a/.gitignore b/.gitignore
index 44113458..08937d87 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,8 +2,14 @@ __pycache__/
 *.pyc
 *.pyo
 .env
-.venv/
-venv/
 *.egg-info/
 dist/
 build/
+.venv/
+venv/
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
diff --git a/README.md b/README.md
index 4b397e19..2c731e5e 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,36 @@
-# Hy3 MCP Server
+# Hy3 研究助手
 
-基于 **MCP (Model Context Protocol)** 协议，封装**腾讯混元 Hy3** 大模型能力的智能工具集。
-
-可一键安装、即插即用到任何支持 MCP 的 AI 客户端（CodeBuddy / WorkBuddy / Cursor / Cline / Claude Desktop 等）。
-
----
+基于腾讯混元 Hy3 大模型的智能研究助手，提供**深度研究**、**代码分析**、**文档问答**三大核心功能。
 
 ## 项目简介
 
-本项目是**腾讯犀牛鸟实战计划 [Issue #3](https://github.com/Tencent-Hunyuan/Hy3/issues/3)** 的完整实现。通过 MCP 协议将 Hy3 大模型的能力暴露为标准化工具（Tools），让支持 MCP 的 AI 客户端可以直接调用 Hy3 完成深度研究、代码评审、文档问答、数据分析等任务。
-
-### Hy3 在本项目中的角色
+本项目是腾讯犀牛鸟实战计划 [Issue #4](https://github.com/Tencent-Hunyuan/Hy3/issues/4) 的完整实现。所有智能任务（研究规划、报告生成、代码分析、文档问答）均通过调用 **Hy3 API**（OpenAI 兼容接口）完成，不涉及模型训练、微调或本地推理。
 
-所有工具的**核心推理、分析、生成能力**均由 Hy3 API 提供：
+### Hy3 在项目中的角色
 
-| 工具 | Hy3 的角色 |
-|------|-----------|
-| `hy3_research` | 搜索资料整合 → 报告规划 → 长文撰写 → 执行摘要提炼 |
-| `hy3_code_review` | 代码理解 → Bug 检测 → 性能分析 → 安全审计 → 优化建议 |
-| `hy3_doc_qa` | 文档阅读理解 → 证据驱动的精准问答 |
-| `hy3_data_analyze` | 数据模式识别 → 趋势分析 → 洞察生成 → 行动建议 |
-| `hy3_chat` | 自由对话、创意写作、翻译、解释等通用场景 |
-
----
+| 功能模块 | Hy3 的角色 |
+|---------|-----------|
+| 深度研究 | 研究计划制定 → 搜索关键词生成 → 长文报告撰写 → 执行摘要提炼 |
+| 代码分析 | 代码理解、Bug 检测、性能优化建议、安全审计、质量评分 |
+| 文档问答 | 多文档阅读理解、证据驱动的精准问答 |
 
 ## 项目结构
 
 ```
-hy3-mcp-server/
-├── src/
-│   ├── server.py          # MCP Server 主程序（5 个 Tool）
-│   ├── hy3_client.py      # Hy3 API 客户端（OpenAI 兼容封装）
-│   └── __init__.py
-├── configs/
-│   ├── codebuddy-mcp.json # CodeBuddy / WorkBuddy 配置示例
-│   ├── cursor-mcp.json    # Cursor 配置示例
-│   ├── claude-mcp.json    # Claude Desktop 配置示例
-│   └── cline-mcp.json     # Cline 配置示例
-├── requirements.txt        # Python 依赖
-├── setup.bat               # Windows 一键安装脚本
-├── setup.sh                # Linux/macOS 一键安装脚本
-└── README.md               # 本文档
+hy3-research-assistant/
+├── backend/
+│   ├── main.py            # FastAPI 服务器（6 个 API 端点，全部支持 SSE 流式输出）
+│   ├── hy3_client.py      # Hy3 API 客户端封装（OpenAI 兼容接口）
+│   ├── tools.py            # 工具函数（网页搜索、PDF/DOCX/代码文件解析）
+│   └── requirements.txt   # Python 依赖
+├── frontend/
+│   └── index.html          # 现代化 Web 前端（暗色主题、流式渲染、Markdown 展示）
+├── .env.example            # 环境变量配置模板
+├── .gitignore
+├── start.bat               # Windows 一键启动脚本
+└── README.md
 ```
 
----
-
 ## 快速开始
 
 ### 环境要求
@@ -52,185 +38,91 @@ hy3-mcp-server/
 - Python 3.9+
 - 有效的 Hy3 API Key
 
-### 一键安装
-
-**Windows：**
-```batch
-cd hy3-mcp-server
-set HY3_API_KEY=你的API密钥
-setup.bat
-```
-
-**Linux / macOS：**
-```bash
-cd hy3-mcp-server
-export HY3_API_KEY=你的API密钥
-bash setup.sh
-```
+### 安装与启动
 
-或手动安装：
 ```bash
-pip install -r requirements.txt
-```
-
----
-
-## 在 AI 客户端中配置
-
-### 1. CodeBuddy / WorkBuddy
-
-将以下配置添加到 CodeBuddy 的 MCP 设置中：
-
-```json
-{
-  "mcpServers": {
-    "hy3-assistant": {
-      "type": "stdio",
-      "command": "python",
-      "args": ["src/server.py"],
-      "cwd": "你的hy3-mcp-server项目路径",
-      "env": {
-        "HY3_API_KEY": "你的API密钥",
-        "HY3_MODEL": "hunyuan-pro"
-      }
-    }
-  }
-}
-```
-
-配置完成后，在 CodeBuddy 对话中即可直接调用 Hy3 工具，例如：
-> "请用 hy3_research 帮我研究一下大模型在医疗领域的应用"
-
-### 2. Cursor
-
-将 `configs/cursor-mcp.json` 的内容复制到 `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局级）。
-
-### 3. Claude Desktop
-
-将 `configs/claude-mcp.json` 的内容添加到 Claude Desktop 的配置文件中：
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-### 4. Cline (VS Code 插件)
-
-将 `configs/cline-mcp.json` 的内容添加到 Cline 的 MCP 设置中。
-
----
-
-## 工具说明
+# 1. 克隆项目
+cd hy3-research-assistant
 
-### 🔬 hy3_research — 深度研究助手
-
-自动搜索网络资料，由 Hy3 大模型分析并生成结构化研究报告。
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `topic` | string | ✅ | 研究主题 |
-| `depth` | string | ❌ | 研究深度：`"detailed"`(默认) 或 `"brief"` |
-
-**示例调用：**
-```
-请用 hy3_research 研究"新能源汽车电池回收技术的现状与挑战"，depth=detailed
-```
-
-### 💻 hy3_code_review — 代码评审助手
-
-对代码进行多维度审查：Bug 检测、性能分析、安全审计、优化建议。
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `code` | string | ✅ | 需审查的完整代码 |
-| `language` | string | ❌ | 编程语言，默认 `"auto"` |
-| `review_focus` | string | ❌ | 审查重点：`"comprehensive"`(默认)、`"security"`、`"performance"`、`"bugs"` |
-
-**示例调用：**
-```
-请用 hy3_code_review 审查以下代码，重点关注安全问题：
-[贴入代码]
-```
-
-### 📚 hy3_doc_qa — 文档问答助手
-
-读取本地文档，由 Hy3 基于文档内容精准回答。
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `file_path` | string | ✅ | 文档的本地路径 |
-| `question` | string | ✅ | 你想问的问题 |
+# 2. 配置 API 密钥
+# Windows
+set HY3_API_KEY=你的API密钥
+# 或复制 .env.example 为 .env 并填入密钥
 
-支持格式：`.txt` `.md` `.py` `.js` `.ts` `.json` `.csv` `.html` `.css` `.yaml`
+# 3. 安装依赖
+cd backend
+pip install -r requirements.txt
 
-**示例调用：**
-```
-请用 hy3_doc_qa 读取 /path/to/report.md，回答"报告中有哪些关键数据指标？"
+# 4. 启动服务
+python main.py
+# 服务运行在 http://localhost:8000
 ```
 
-### 📊 hy3_data_analyze — 数据分析助手
+打开浏览器访问 `http://localhost:8000` 即可使用。
 
-读取 CSV 或 JSON 数据，由 Hy3 进行深度分析和洞察输出。
+### 可选环境变量
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `file_path` | string | ✅ | 数据文件路径（.csv/.json） |
-| `analysis_goal` | string | ❌ | 分析目标，默认 `"全面分析"` |
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `HY3_API_KEY` | Hy3 API 密钥（必填） | - |
+| `HY3_BASE_URL` | API 端点地址 | `https://api.hunyuan.cloud.tencent.com/v1` |
+| `HY3_MODEL` | 模型名称 | `hunyuan-pro` |
+| `PORT` | 服务端口 | `8000` |
 
-**示例调用：**
-```
-请用 hy3_data_analyze 分析 /path/to/sales.csv，"分析各季度的销售趋势并找出异常数据"
-```
+## 三大功能
 
-### 💬 hy3_chat — 通用对话助手
+### 🔬 深度研究 (Deep Research)
 
-与 Hy3 自由对话，适用于其他工具未覆盖的灵活场景。
+输入研究主题，Hy3 将自动完成：
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `message` | string | ✅ | 你想说的话或问题 |
-| `system_prompt` | string | ❌ | 设定 AI 角色与行为 |
+1. **研究规划** — 将主题拆解为子问题，生成搜索关键词
+2. **资料搜索** — 自动搜索相关网页资料
+3. **报告撰写** — 基于搜索结果生成 1500-3000 字专业研究报告
+4. **执行摘要** — 提炼核心发现的简明摘要
 
----
+### 💻 代码分析 (Code Analysis)
 
-## 技术细节
+粘贴代码或上传代码文件，Hy3 将提供：
 
-- **MCP 协议**: 使用 Python FastMCP 框架，遵循标准 stdio 传输模式
-- **Hy3 调用**: 通过 OpenAI 兼容接口，支持 `HY3_API_KEY`、`HY3_BASE_URL`、`HY3_MODEL` 环境变量
-- **数据源**: DuckDuckGo 网页搜索（无需额外 API Key）、本地文件读取
-- **安全**: API Key 仅通过环境变量传入，代码中无硬编码
+- 代码概览与核心功能解读
+- 执行逻辑与关键流程分析
+- 潜在 Bug、性能隐患、安全问题诊断
+- 具体优化建议与最佳实践
+- 1-10 分代码质量评分
 
----
+### 📚 文档问答 (Document Q&A)
 
-## 环境变量
+上传多个文档（支持 PDF、DOCX、TXT、代码文件等），向 Hy3 提问：
 
-| 变量名 | 必填 | 默认值 | 说明 |
-|--------|------|--------|------|
-| `HY3_API_KEY` | ✅ | - | Hy3 API 密钥 |
-| `HY3_BASE_URL` | ❌ | `https://api.hunyuan.cloud.tencent.com/v1` | API 端点 |
-| `HY3_MODEL` | ❌ | `hunyuan-pro` | 模型名称 |
+- 基于文档内容精准回答
+- 引用原始段落作为证据
+- 明确标注信息缺失情况
 
----
+## API 端点
 
-## 手动测试
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/` | GET | 前端页面 |
+| `/health` | GET | 服务健康检查 |
+| `/api/research` | POST | 深度研究（流式） |
+| `/api/analyze-code` | POST | 粘贴代码分析（流式） |
+| `/api/analyze-code-file` | POST | 上传代码文件分析（流式） |
+| `/api/qa-documents` | POST | 多文档问答（流式） |
 
-启动 MCP Server 进行本地验证：
-```bash
-cd src
-export HY3_API_KEY=你的API密钥
-python server.py
-```
+所有智能端点均使用 Server-Sent Events (SSE) 实现流式输出，支持前端实时渲染。
 
-或使用 MCP Inspector 调试：
-```bash
-npx @modelcontextprotocol/inspector python src/server.py
-```
+## 技术栈
 
----
+- **后端**: FastAPI + OpenAI SDK + Uvicorn
+- **前端**: 原生 HTML/CSS/JS + marked.js（Markdown 渲染）
+- **模型**: 腾讯混元 Hy3（通过 OpenAI 兼容接口调用）
+- **工具**: DuckDuckGo 网页搜索、PyPDF2、python-docx
 
 ## CodeBuddy 协作说明
 
 本项目借助 CodeBuddy AI 编程助手完成：
 
-- **架构设计**: AI 参与 MCP Server 整体架构、工具拆解和接口设计
-- **代码生成**: AI 编写了 `server.py`（5 个 MCP Tool + Hy3 调用逻辑）、`hy3_client.py`（API 客户端封装）
-- **多客户端适配**: AI 生成了 CodeBuddy、Cursor、Claude Desktop、Cline 四种客户端的配置示例
-- **文档撰写**: AI 编写了 README、安装脚本、配置说明
-- **代码审查**: AI 辅助进行了语法验证和结构优化
+- **协同设计**：AI 参与整体架构规划、功能模块拆解、前后端交互设计
+- **代码生成**：AI 编写了 `backend/main.py`（服务器和所有提示词工程）、`backend/hy3_client.py`（API 客户端封装）、`backend/tools.py`（搜索和文件解析）、`frontend/index.html`（完整前端界面）
+- **文档撰写**：AI 生成了 README、配置模板、启动脚本
+- **代码审查与打磨**：AI 辅助进行了语法检查、中英文翻译、结构优化
diff --git a/start.bat b/start.bat
index faaecbfc..dd2ddea9 100644
--- a/start.bat
+++ b/start.bat
@@ -5,24 +5,44 @@ echo   Hy3 研究助手 一键启动
 echo ========================================
 echo.
 
+cd /d "%~dp0"
+
+REM 优先从 .env 文件加载 HY3_API_KEY
+if exist ".env" (
+    for /f "tokens=1,2 delims==" %%a in (.env) do (
+        if "%%a"=="HY3_API_KEY" set HY3_API_KEY=%%b
+    )
+)
+
 REM 检查 API Key
 if "%HY3_API_KEY%"=="" (
-    echo [警告] 未设置 HY3_API_KEY 环境变量
-    echo 请先执行: set HY3_API_KEY=你的API密钥
+    echo [错误] 未检测到 HY3_API_KEY
+    echo.
+    echo 请按以下方式配置：
+    echo   1. 复制 .env.example 为 .env，填写你的 API Key
+    echo   2. 或执行: set HY3_API_KEY=你的API密钥
     echo.
     pause
     exit /b 1
 )
 
 echo [信息] API Key 已配置
-echo [信息] 正在安装依赖...
+echo [信息] 正在检查依赖...
 cd /d "%~dp0backend"
-pip install -r requirements.txt -q
-echo.
 
-echo [信息] 启动服务...
-echo 前端页面: http://localhost:8000
-echo 按 Ctrl+C 停止服务
+REM 检查并安装依赖
+pip install -r requirements.txt -q 2>nul
+if errorlevel 1 (
+    echo [警告] 依赖安装可能存在问题，尝试继续...
+)
+
+echo.
+echo [信息] 启动 Hy3 研究助手服务...
+echo ========================================
+echo   前端页面: http://localhost:8000
+echo   API 文档: http://localhost:8000/docs
+echo   按 Ctrl+C 停止服务
+echo ========================================
 echo.
 python main.py
 pause

From 8e12e48fe28579051752e359f5a4e417a55153d4 Mon Sep 17 00:00:00 2001
From: tsy712 <3603013478@qq.com>
Date: Fri, 24 Jul 2026 15:07:55 +0800
Subject: [PATCH 12/12] =?UTF-8?q?Hy3=E7=A0=94=E7=A9=B6=E5=8A=A9=E6=89=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

本项目是腾讯犀牛鸟实战计划 [Issue #4](https://github.com/Tencent-Hunyuan/Hy3/issues/4) 的完整实现。所有智能任务（研究规划、报告生成、代码分析、文档问答）均通过调用 **Hy3 API**（OpenAI 兼容接口）完成，不涉及模型训练、微调或本地推理。
三大功能

### 🔬 深度研究 (Deep Research)

输入研究主题，Hy3 将自动完成：

1. **研究规划** — 将主题拆解为子问题，生成搜索关键词
2. **资料搜索** — 自动搜索相关网页资料
3. **报告撰写** — 基于搜索结果生成 1500-3000 字专业研究报告
4. **执行摘要** — 提炼核心发现的简明摘要

### 💻 代码分析 (Code Analysis)

粘贴代码或上传代码文件，Hy3 将提供：

- 代码概览与核心功能解读
- 执行逻辑与关键流程分析
- 潜在 Bug、性能隐患、安全问题诊断
- 具体优化建议与最佳实践
- 1-10 分代码质量评分

### 📚 文档问答 (Document Q&A)

上传多个文档（支持 PDF、DOCX、TXT、代码文件等），向 Hy3 提问：

- 基于文档内容精准回答
- 引用原始段落作为证据
- 明确标注信息缺失情况