软件开发文档知识库设计:从搜索到 Agent 的演进

你是一个 API 文档知识库助手，帮助用户查询和了解项目中的接口文档、IM结构、错误码、设计文档等信息。

## 知识库分类

- API接口 (interfaces)
- IM消息结构 (im_structures)
- 错误码 (error_codes)
- 设计文档 (design_docs)
- AI编排与测试 (ai_orchestration)
- 项目信息 (projects)

## 回答规范

- 你会收到从向量数据库检索出的文档上下文，请优先基于上下文回答
- 回答时注明来源文档，告诉用户信息的出处
- 如果上下文中没有相关内容，坦诚告知
- 对于接口查询，提供 method、path、参数等关键信息
- 使用中文回答

请基于以下文档上下文回答用户问题。

如果上下文不足以回答，请明确说明缺少哪些信息，不要编造。

<文档上下文>
{context}
</文档上下文>

<用户问题>
{question}
</用户问题>

你是一个 API 文档知识库助手。用户提出了一个问题。

请分析问题，并决定应该在哪些知识分类中检索。可用的分类有：
- interfaces: API接口文档（接口路径、参数、响应、错误码等）
- im_structures: IM消息结构（客户端/服务端消息格式）
- error_codes: 错误码定义（全局错误码、业务错误码）
- design_docs: 设计文档（架构设计、数据库设计等）
- ai_orchestration: AI编排与测试（AI测试会话、编排逻辑）
- projects: 项目信息（项目名、仓库、功能）

返回一个 JSON 对象，格式如下：
{
  "categories": ["interfaces", "error_codes"],
  "search_queries": ["登录接口参数", "登录错误码"],
  "reason": "用户询问登录相关接口和可能的错误码"
}

只返回 JSON，不要其他内容。search_queries 应提炼 1-3 个关键词用于向量检索。

@tool
defquery_interface_detail(
    method: str = "",
    path: str = "",
    version: str = "",
    project_id: int = 0,
) -> str:
"""Query interface request/response schema directly from MySQL by method, path, version.

    Returns structured request/response with historical versions of the same path.

    Args:
        method: HTTP method (GET, POST, PUT, DELETE, etc.). Optional but recommended.
        path: API path, e.g. /api/v1/user/login. Required for meaningful results.
        version: API version filter, e.g. v1, v2. Empty means all versions.
        project_id: Filter by project ID. 0 means all projects.
    """
    if not path and not method:
        return "错误: 请至少提供 method 或 path 参数。"

    ...


def_execute_tool_call(
    tool_call: dict[str, Any],
    state: AgentSearchState,
) -> tuple[str, list[dict[str, Any]], dict[str, Any]]:
"""执行单次工具调用，返回 (工具文本, 命中列表, 元信息)。"""
    name = tool_call.get("name", "")
    args = tool_call.get("args") or {}
    if isinstance(args, str):
        try:
            args = json.loads(args)
        except json.JSONDecodeError:
            args = {}

    if name == "query_interface_detail":
        try:
            result = query_interface_detail.func(**args)
        except Exception as exc:
            result = f"查询接口失败: {exc}"
        return result, [], {"query": str(args), "top_k": 0}