Merge pull request 'refactor: 精简agent代码，移除冗余的main入口，添加API文档和note_agent' (#2) from source2md into develop

Reviewed-on: http://192.168.31.46:3000/GuangYu/Agents/pulls/2

README.md

@@ -1,28 +1,26 @@
 # 慧遇 Agent
 
-基于 Google ADK (Agent Development Kit) 构建的智能体项目，支持多智能体协作、多用户会话管理和 REST API 集成。
+慧遇智能体项目，基于 Google ADK (Agent Development Kit) 构建。
 
 ## 项目结构
 
 ```
-├── root_agent/             # 根智能体（小慧）
+workspace/
+├── agents/                  # 所有 Agent 模块
 │   ├── __init__.py
-│   └── agent.py            # 定义 root_agent，包含子智能体引用
+│   └── root_agent/          # Root Agent
-├── note_agent/             # 笔记子智能体
+│       ├── __init__.py
+│       └── agent.py
+├── base/                    # 基础工具类
 │   ├── __init__.py
-│   ├── agent.py            # 定义 root_agent（ADK 要求导出名）
+│   └── agent.py             # HuiYuBaseAgent 基类
-│   └── note_formatter.py   # Markdown 笔记格式化器
+├── common/                  # 公共模块
-├── agent_base/             # Agent 基类
+│   ├── __init__.py          # 环境初始化（.env 加载、日志配置）
-│   ├── __init__.py
+│   ├── logger.py            # 模型调用耗时日志
-│   └── agent_base.py       # HuiYuBaseAgent（防注入 + 日志）
+│   └── prompt_guard.py      # 防提示词注入检测
-├── common/                 # 公共工具
+├── .env                     # 环境变量配置（不提交到 Git）
-│   ├── __init__.py         # 环境初始化（.env 加载、日志配置）
+├── .env.example             # 配置示例（可提交到 Git）
-│   ├── logger.py           # 模型调用耗时日志
+├── .gitignore
-│   └── prompt_guard.py     # 防提示词注入检测
-├── .env                    # 环境变量配置（不提交到 Git）
-├── .env.example            # 配置示例
-├── API_DOC.md              # REST API 接口文档
-├── requirements.txt
 └── README.md
 ```
 
@@ -31,9 +29,16 @@
 - Python >= 3.10
 - pip
 
-## 快速开始
+## 环境搭建
 
-### 1. 安装依赖
+### 1. 克隆项目
+
+```bash
+git clone <your-repo-url>
+cd <project-directory>
+```
+
+### 2. 安装依赖
 
 ```bash
 pip install -r requirements.txt
@@ -42,98 +47,97 @@ pip install -r requirements.txt
 主要依赖：
 - `google-adk` — Google Agent Development Kit
 - `python-dotenv` — 环境变量管理
-- `litellm` — 多模型适配层（对接 MiniMax 等大模型）
+- `litellm` — 多模型适配层
 
-### 2. 配置环境变量
+### 3. 配置环境变量
+
+复制示例配置文件并填入你的 API Key：
 
 ```bash
 cp .env.example .env
 ```
 
-编辑 `.env`：
+编辑 `.env` 文件：
 
 ```env
+# MiniMax API Key（替换为你自己的）
 MINIMAX_API_KEY=your_api_key_here
+
+# MiniMax API 地址
 MINIMAX_API_BASE=https://api.minimaxi.com/v1
+
+# 模型名称
 MINIMAX_MODEL=openai/MiniMax-M2.7
 ```
 
-### 3. 启动服务
+### 4. 启动服务
 
 ```bash
-# Web UI 模式（带聊天界面）
+cd agents
-adk web .
+adk web
-
-# API 服务模式（纯 REST API，适合外部集成）
-adk api_server . --auto_create_session
 ```
 
-启动后访问 `http://127.0.0.1:8000`。
+启动后访问 http://127.0.0.1:8000，在下拉菜单中选择 Agent 即可开始对话。
-
-## 智能体架构
-
-```
-root_agent（小慧）
-├── 通用对话：回答用户问题
-└── 子智能体委派：
-    └── note_agent（笔记助手）
-        ├── generate_text_note — 生成文本笔记
-        └── generate_image_note — 生成图片笔记
-```
-
-当用户请求涉及笔记生成、内容整理时，root_agent 会自动委派给 note_agent 处理。
-
-## API 集成
-
-使用 `adk api_server` 启动后，可通过 REST API 与 Agent 对话：
-
-```bash
-# 启动 API 服务
-adk api_server . --auto_create_session --port 8000
-
-# 发送对话
-curl -X POST http://localhost:8000/run \
-  -H "Content-Type: application/json" \
-  -d '{
-    "app_name": "root_agent",
-    "user_id": "user_001",
-    "session_id": "my_session",
-    "new_message": {"role": "user", "parts": [{"text": "你好"}]}
-  }'
-```
-
-详细的接口文档见 [API_DOC.md](API_DOC.md)，Swagger 文档地址：`http://localhost:8000/docs`
 
 ## 内置能力
 
-所有继承 `HuiYuBaseAgent` 的 Agent 自动获得：
+所有继承 `HuiYuBaseAgent` 的 Agent 自动获得以下能力：
 
 ### 防提示词注入
 
-模型调用前自动检测用户输入中的注入攻击（角色扮演、指令泄露、分隔符注入、越狱尝试等），检测到时拒绝请求。
+在模型调用前自动检测用户输入中的提示词注入攻击，包括：
+- 角色扮演 / 身份覆盖
+- 指令泄露尝试
+- 分隔符注入
+- 越狱尝试
+
+检测到注入时会拒绝请求并返回提示。
 
 ### 模型调用日志
 
-每次模型调用完成后自动记录 Agent 名称、模型版本、调用耗时、Token 用量：
+每次模型调用完成后自动记录：
+- Agent 名称
+- 模型版本
+- 调用耗时
+- Token 使用量（prompt / completion / total）
+
+日志示例：
 
 ```
-2026-04-06 07:54:59 [adk.agent] INFO - 模型调用完成 | agent=huiyu_agent model=MiniMax-M2.7 latency=11.701s prompt_tokens=78 completion_tokens=31 total_tokens=109
+2026-04-06 07:54:59 [adk.agent] INFO - 模型调用完成 | agent=minimax_agent model=MiniMax-M2.7 latency=11.701s prompt_tokens=78 completion_tokens=31 total_tokens=109
 ```
 
 ## 新增 Agent
 
-在项目根目录下创建新的子目录即可：
+在 `agents/` 目录下创建新的子目录即可：
 
 ```
-my_new_agent/
+agents/
-├── __init__.py         # 留空即可
+├── root_agent/
-└── agent.py            # 必须导出名为 root_agent 的变量
+│   ├── __init__.py
+│   └── agent.py
+└── my_new_agent/           # 新增 Agent
+    ├── __init__.py          # 内容同 root_agent/__init__.py
+    └── agent.py
 ```
 
-`agent.py` 示例：
+`__init__.py` 内容（用于设置 Python 路径）：
 
 ```python
-from agent_base.agent_base import HuiYuBaseAgent
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from . import agent
+
+__all__ = ["agent"]
+```
+
+`agent.py` 中继承 `HuiYuBaseAgent`：
+
+```python
+from base.agent import HuiYuBaseAgent
 from google.adk.models.lite_llm import LiteLlm
 import os
 
@@ -143,26 +147,11 @@ model = LiteLlm(
     api_key=os.getenv("MINIMAX_API_KEY"),
 )
 
-root_agent = HuiYuBaseAgent(
+my_agent = HuiYuBaseAgent(
     name="my_agent",
     model=model,
-    description="我的智能体",
     instruction="你是一个专业的助手。",
 )
 ```
 
-> **注意**：ADK 要求每个 agent 目录的 `agent.py` 中必须导出名为 `root_agent` 的变量。
+重启 `adk web` 后，新 Agent 会自动出现在下拉菜单中。
-
-如需作为 root_agent 的子智能体，在 `root_agent/agent.py` 中添加引用：
-
-```python
-from my_new_agent.agent import root_agent as my_new_agent
-
-root_agent = HuiYuBaseAgent(
-    name="huiyu_agent",
-    ...,
-    sub_agents=[my_new_agent],
-)
-```
-
-重启服务后新 Agent 自动生效。

agents/__init__.py

@@ -0,0 +1,10 @@
+"""
+Agent 模块
+
+每个 Agent 是一个独立的子目录，包含 agent.py 和 __init__.py。
+"""
+
+# 导出所有 Agent，供 adk web 服务注册
+from .root_agent import agent as root_agent
+
+__all__ = ["root_agent"]

agents/note_agent/__init__.py

@@ -0,0 +1,8 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from . import agent
+
+__all__ = ["agent"]

agents/note_agent/agent.py

@@ -1,6 +1,6 @@
 import os
 
-from agent_base.agent_base import HuiYuBaseAgent
+from base.agent import HuiYuBaseAgent
 from google.adk.models.lite_llm import LiteLlm
 from .note_formatter import NoteFormatter
 
@@ -75,5 +75,3 @@ note_agent = HuiYuBaseAgent(
     ),
     tools=[generate_text_note, generate_image_note],
 )
-
-root_agent = note_agent

agents/root_agent/__init__.py

@@ -0,0 +1,10 @@
+import sys
+from pathlib import Path
+
+# 将项目根目录加入 sys.path（adk web 从 agents/ 启动）
+# __file__ = agents/root_agent/__init__.py → parent.parent.parent = workspace/
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from . import agent
+
+__all__ = ["agent"]

agents/root_agent/agent.py

@@ -1,9 +1,7 @@
 import os
 
-from agent_base.agent_base import HuiYuBaseAgent
+from base.agent import HuiYuBaseAgent
 from google.adk.models.lite_llm import LiteLlm
-from critical_awareness_agent.agent import critical_awareness_agent
-from note_agent.agent import note_agent
 
 # ============================================================
 # MiniMax 模型配置（从 .env 文件读取）
@@ -28,12 +26,5 @@ root_agent = HuiYuBaseAgent(
     name="huiyu_agent",
     model=model,
     description="一个智能助手，能够回答用户的各种问题。",
-    instruction=(
+    instruction="你是一个乐于助人的中文 AI 助手，你的名字叫小慧，请用中文回答用户的问题，回答要准确、简洁、友好。",
-        "你是一个乐于助人的中文 AI 助手，你的名字叫小慧，请用中文回答用户的问题，回答要准确、简洁、友好。\n\n"
-        "你有一个子助手「笔记助手」（note_agent），当用户需要生成笔记、整理内容、做总结时，"
-        "请将任务委派给 note_agent 处理。"
-        "你还有一个子助手「临界觉察助手」（critical_awareness_agent），当用户出现心智散乱、情绪化或认知混淆时，"
-        "请将任务委派给 critical_awareness_agent 处理。"
-    ),
-    sub_agents=[note_agent, critical_awareness_agent],  # 将 note_agent 和 critical_awareness_agent 作为子 Agent
 )

critical_awareness_agent/__init__.py

@@ -1 +0,0 @@
-# ADK agent_loader 会自动扫描并加载 agent.py

critical_awareness_agent/agent.py

@@ -1,48 +0,0 @@
-import os
-
-
-from google.adk.models.lite_llm import LiteLlm
-from agent_base.agent_base import HuiYuBaseAgent
-
-# ============================================================
-# MiniMax 模型配置（从 .env 文件读取）
-# ============================================================
-MINIMAX_API_KEY = os.getenv("MINIMAX_API_KEY")
-MINIMAX_API_BASE = os.getenv("MINIMAX_API_BASE")
-MINIMAX_MODEL = os.getenv("MINIMAX_MODEL")
-
-# ============================================================
-# 创建 LiteLlm 模型适配器
-# ============================================================
-model = LiteLlm(
-    model=MINIMAX_MODEL,
-    api_base=MINIMAX_API_BASE,
-    api_key=MINIMAX_API_KEY,
-)
-
-# ============================================================
-# 定义 Agent（继承 HuiYuBaseAgent）
-# ============================================================
-critical_awareness_agent = HuiYuBaseAgent(
-    name="critical_awareness_agent",
-    model=model,
-    description="用于处理用户心智散乱、情绪化或认知混淆的专家。它通过‘三界（外中内）’判别法强制用户回归觉知。当用户表达焦虑、愤怒、分心或无法区分事实与观点时，必须调用此工具。",
-    instruction=(
-        """
-        你是一位精通“临界觉察法”的资深导师。你的目标是协助学生通过识别外界、中界、内界的边界，回归当下觉知。
-        
-        判定逻辑：
-        - 外界 (External): 纯粹感官原始数据，无形容词/评价。
-        - 中界 (Middle): 想法、念头、逻辑、评判、语言、对未来的担忧。
-        - 内界 (Internal): 身体生理感受、情绪在身体上的投影（如心跳、紧缩感）。
-        
-        回复规范：
-        1. 必须快速拆解输入内容，给出 [外界/中界/内界] 的结构化分析。
-        2. 语气简洁、敏锐，像手术刀一样切开混沌。
-        3. 引导学生作为“观察者”，清晰的觉知三界都在发生什么。
-        4. 提醒学生回归当下的觉知
-        """
-    )
-)
-
-root_agent = critical_awareness_agent  # 将 critical_awareness_agent 作为 root_agent 导出，供 adk web 注册

note_agent/__init__.py

@@ -1 +0,0 @@
-# ADK agent_loader 会自动扫描并加载 agent.py

root_agent/__init__.py

@@ -1 +0,0 @@
-# ADK agent_loader 会自动扫描并加载 agent.py