BUG：Web UI 智能体发现机制显示非智能体目录（继承自 Google ADK）

[xyl-muse]

描述 Bug:

VeADK 继承了 Google ADK 的 Web UI 智能体发现机制，该机制会在智能体选择下拉列表中显示所有子目录，包括非智能体目录（如 tools/、schemas/、tests/ 等），导致用户界面混乱和不良的开发体验。

复现步骤:

1. 创建一个典型的 VeADK 多智能体项目结构：

xsoc_agent/
├── agent.py            # 根智能体
├── __init__.py
├── flows/              # ✅ 有效智能体 (SecurityEventOrchestrator)
│   ├── __init__.py
│   └── security_event_flow.py
├── agents/             # ❌ 非智能体 (子智能体代码)
├── tools/              # ❌ 非智能体 (工具模块)
├── schemas/            # ❌ 非智能体 (Pydantic模型)
└── tests/              # ❌ 非智能体 (单元测试)

2. 运行 veadk web
3. 打开浏览器访问 http://127.0.0.1:8000/
4. 观察智能体选择下拉列表显示：agents, flows, schemas, tests, tools
5. 尝试选择 agents 或 tools 等目录 → 出现加载错误

期望行为:

下拉列表应仅显示包含有效智能体定义的目录（本例中应只显示 flows）。

实际行为:

Web UI 显示了所有子目录，选择非智能体目录时出现错误：

ValueError: No root_agent found for 'tools'.

环境详情:

• VeADK 版本: 0.5.29
• Google ADK 版本: 1.29.0
• 操作系统: Windows 10 / Linux / macOS
• Python 版本: 3.10+

模型信息:

• 是否使用 LiteLLM: N/A
• 使用的模型: N/A（问题出在智能体发现机制，与模型无关）

---

🟡 可选信息

回归测试:

这不是回归问题，而是从依赖的上游项目（Google ADK）继承的设计问题。相关 Issue：Google ADK Duplicate of #3429。

日志:

无后端错误日志。问题在于 /list-apps API 返回了所有目录名。

截图 / 视频:

Web UI 下拉列表中混入了非智能体目录，造成用户困惑。

补充背景:

VeADK 与 Google ADK 的依赖关系:

veadk-python (0.5.29)
    ↓ 依赖于
google-adk (>=1.19.0)
    ↓ 调用
google.adk.cli.cli_tools_click.cli_web()

VeADK 的 cli_web.py 实现:

from google.adk.cli.cli_tools_click import cli_web

# VeADK 对 AdkWebServer 进行了一些 patch
# 但没有修改 list_apps 的行为
cli_web.main(args=extra_args, standalone_mode=False)

根本原因:

1. Google ADK 的 /list-apps 端点默认 detailed=False
2. 预编译的 Angular 前端硬编码了 API 调用，未传递 ?detailed=true
3. VeADK 完全委托给 Google ADK，没有覆盖或 patch 这个行为

对国内开发者的影响:

VeADK 主要面向国内市场，用户构建企业级多智能体系统时面临：

• 界面混乱: 看到 6+ 个选项，但只有 1-2 个有效
• 开发体验差: 需要反复尝试才能找到有效智能体
• 生产部署问题: 无效的智能体名称出现在部署场景中

建议解决方案:

方案 1: 等待 Google ADK 修复

跟踪 Google ADK 进展，等待上游修复后更新依赖。

优点：

• 无需修改代码
• 受益于整个 Google ADK 生态系统
• 保持与上游对齐

缺点：

• 依赖 Google ADK 发布时间线
• 期间用户仍会遇到此问题

方案 2: 在 VeADK 层面临时 Patch

在 veadk/cli/cli_web.py 中添加 monkey patch 强制使用 detailed 模式。

优点：

• VeADK 用户立即受益
• 不依赖上游时间线

缺点：

• 增加维护负担
• 可能与未来 Google ADK 版本产生兼容性问题
• Monkey patch 不够优雅

方案 3: 文档说明

在 VeADK 文档中说明当前行为和临时解决方案。

最小复现代码:

# 创建测试项目结构
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as tmp:
    # 创建有效智能体
    (Path(tmp) / "flows").mkdir()
    (Path(tmp) / "flows" / "__init__.py").write_text(
        "from veadk import Agent\n"
        "root_agent = Agent(name='test', model='gemini-2.0-flash-exp')"
    )
    
    # 创建非智能体目录
    (Path(tmp) / "tools").mkdir()
    (Path(tmp) / "schemas").mkdir()
    
    # 运行 veadk web tmp
    # 下拉列表会显示: flows, schemas, tools
    # 但只有 flows 可用

问题发生频率:

• 总是 (100%)