最佳实践

文档组织

保持 Markdown 目录清晰，按主题拆分章节
标题层级规范（#→##→###）有助于分块质量
每个页面聚焦单主题，避免超长“杂糅页”

知识库检索质量

提问建议使用自然语言完整句
给 keyword 增加领域词（如“部署;鉴权;MCP”）
top_k 从 3~5 开始，再按召回质量调整

MCP 工具设计

工具名使用明确动词语义（如 query_knowledge_base）
description 用英文写清调用场景
inputSchema 使用 required、enum 约束输入
返回内容尽量使用 Markdown，便于模型消费

线上稳定性

给外部 API 调用设置超时与重试
对错误码做统一映射，避免前端只看到“unknown error”
记录请求链路日志（请求ID、耗时、响应码）

安全与鉴权

不在前端暴露 CNB_TOKEN
优先使用平台注入环境变量
对外接口加 CORS 白名单和方法限制

迭代策略

先做最小可用：单工具检索
观察用户问答日志，补高频工具
最后再做 UI 细节和高级特性