feat(knowledgebase): add list docs tool- #2

[Hao-Yu-la]

背景

Viking Knowledge MCP Server 当前缺少获取指定知识库文档列表的能力。

本 MR 新增 list_docs 工具，通过游标分页调用 Viking Knowledge Base 的文档列表接口。

主要变更

• 新增只读 MCP 工具 list_docs
• 调用接口：POST /api/knowledge/doc/v2/list
• 支持参数：
  • collection_name：知识库名称，必填
  • limit：单页文档数量，范围为 1–100，默认值为 100
  • next_token：下一页游标，可选
• 使用全局配置的 KNOWLEDGE_BASE_PROJECT
• 复用现有统一请求及鉴权逻辑，同时支持：
  • Viking API Key
  • VolcEngine AK/SK
• 新增 ListDocumentsResult 返回模型
• 保留 Viking 返回的文档扩展字段，例如摘要和 token 数
• 将上游非零状态码转换为 MCP ToolError
• 完善并统一中英文 README：
  • 补充六个工具的调用、参数及返回值示例
  • 补充官方文档链接
  • 对齐中英文文档结构
  • 区分持久安装与 uvx 免安装运行方式

返回结构

list_docs 返回以下字段：

• collection_name
• total_num
• count
• doc_list
• has_more
• next_token

当 next_token 为空时，表示所有文档已经返回完毕。

兼容性

• 本次变更仅新增工具，不影响现有 MCP 工具
• 未修改现有鉴权优先级及配置方式
• list_docs 不暴露 resource_id 和 pipeline_name
• 保持现有 KNOWLEDGE_BASE_PROJECT 全局配置方式

[cuericlee]

Add unit tests at least to cover list_docs

🔴 Blocker（合并前必须）

BL-1 零测试（intent-F2 + nfr-dispatch 一致认定）
新增 list_docs 有 8+ 条可测分支（首屏 / 翻页请求体差异、limit 边界、上游非零 code、空 data、扩展字段透传、failed_code int 型反序列化、total_num null），加上 get_doc 行为修复的回归路径 ——全部无自动化测试（整个子项目无 tests/ 目录）。PR #428 的零测试债务不但未偿还还被放大。
🟠 Major（强烈建议合并前处理）

MJ-1 未声明的现有工具行为变更（intent-F1，沙箱实测验证）
DocumentStatus.failed_code: Optional[str] → Optional[Union[int,str]] 并非 “仅新增工具”——pydantic v2 下旧签名遇上游返回 int 型 failed_code 会抛 ValidationError，导致 get_doc 在部分失败文档场景 “文档存在但获取失败”。此 commit 实为 bug 修复（正确且必要），但与 PR 兼容性声明矛盾 → 需在 PR 描述显式披露 + 补回归用例。

MJ-2 “不暴露 resource_id/pipeline_name” 无代码保证（intent-F3）
DocumentInfo(extra="allow") 递归透传上游全部字段，“不暴露” 仅依赖上游恰好不返回 → 显式 pop 黑名单或契约测试固化。

MJ-3 第 6 次复制 try/except 骨架（maint-F1）
新增代码逐行复制 5 个既有工具的模板（code≠0 检查 / 空 data 检查 / 异常包装）；#428 已证实的 copy-paste bug（server.py:310，get_collection 日志写成 search_knowledge）本 PR 未修复，且新增代码再埋同类风险 → 建议抽 _call_kb(path, params, tool_name) helper 顺带修复。

MJ-4 CHANGELOG / 版本缺失（nfr-dispatch）：新增面向用户的工具但未 bump minor 版本、未加 CHANGELOG（延续 #428 债务）。

[Hao-Yu-la]

已修复

[cuericlee]

/lgtm