deepknow

DeepKnow — 知识与检索助手

通过 DeepKnow REST API 导入和浏览知识，检索内部知识、综合资料、食品伙伴网或受控网页，并查询表格真实数据。

支持的能力

能力	说明	用户示例	调用前阅读
知识库浏览与深读	列出知识库、文件夹、分类和条目，读取详情与原文分块	“继续读这篇资料的上下文”	knowledge-bases.md
知识导入与管理	上传文件、导入 URL/飞书、写入或编辑 Markdown、重新解析、删除	“把这个 PDF 加进法规库”	import.md
知识检索	单库/跨库或文件夹范围检索，按分类过滤，生成可核验引用	“只查研发文件夹里的资料”	search.md
综合资料与证据检索	复用已接入来源，查询文献、标准、政策及其他专业资料，按需读取摘要、条款或正文；兼容原资料卡片查询	“查槲皮素文献，给我摘要和来源”	food-knowledge.md
食品伙伴网检索	查询食品法规、标准、添加剂、污染物或生产许可等专业数据	“山梨酸钾可以用在哪些食品中？”	external-search.md
实时网页检索	查询批准域名下的最新网页、政策或当前信息	“查一下国家卫健委最新的食品政策”	external-search.md
表格查询	自然语言查询、查看表结构、按受控 DSL 查行、预览原始网格	“华东区销售额最高的是谁？”	tabular.md

根据用户意图先完整阅读对应说明文件，再调用接口。跨能力任务只读取实际需要的文件。

外部数据源的范围

本 Skill 中，“外部数据源”指以下四类资料来源：

1. 食品伙伴网：已接入的食品法规、标准及结构化专业数据。
2. 受控官网网页：服务端白名单允许检索的官方网站。
3. 公众号文章知识库：存放外部公众号文章的知识库。虽然文章已入库，但其内容来源仍属于外部数据源；检索范围限于当前用户有权限访问的库内文章，不代表全网公众号搜索。
4. 已接入的专业数据源：MCP 已接入的文献、标准、政策、化合物等数据库，例如 PubMed、CFSA、卫健委和 PubChem。实际可用范围以服务端配置为准。

内部资料指企业自身的制度、项目文件等内容。资料是否属于外部来源，按内容来源区分，不仅按是否已经入库区分。

用户说“检索外部数据源”时，应按上述范围理解。这一定义不要求同时查询全部来源；仍按问题类型、用户限定和下方路由规则选择已有入口，不因本定义新增调用、扩大权限或绕过域名限制。

公众号文章按 food-knowledge.md 中的“公众号文章知识库”说明使用已有知识库检索与深读能力，不将其当作新的 MCP 专业来源。

用户按“学术文献”“原料 / 成分 / 标准”“公告 / 抽检”等业务分类提出检索要求时，先读取 food-knowledge.md 中的“业务分类与来源说明”，确定候选来源范围，再根据具体问题选择来源，不默认查询整个分类。

检索数据源路由

检索前根据用户意图选择一个业务入口：

• 企业自身的制度、项目文件及其他内部资料：读取 search.md，调用 POST /knowledge-search。用户明确要求搜索某个知识库时，按该知识库范围执行；不要仅因资料已入库就认定其内容来源属于内部。
• 公众号文章知识库：先按 food-knowledge.md 确认目标知识库范围，再按 search.md 调用 POST /knowledge-search 并限定知识库；需要上下文时按 knowledge-bases.md 深读。
• 文献标题、摘要，标准版本与原文条款，官网政策及正文，或其他外部资料证据：读取 food-knowledge.md，调用 POST /food-knowledge/search 并指定对应 scenario；需要更多证据时使用返回的读取定位调用 POST /food-knowledge/read。来源的 API、专用网页解析与受控网页选择由主 MCP 在服务端完成，Skill 不猜测取数方式。
• 添加剂、营养强化剂、污染物、农药或兽药残留、食品分类、生产许可等结构化规则，或用户明确指定食品伙伴网：读取 external-search.md，先调用 POST /foodpartner/search，仅在需要完整记录或下一页时调用 POST /foodpartner/fetch。需要标准原文条款时使用上一项标准证据流程。
• 只需要受控外部站点的网页搜索结果：读取 external-search.md，调用 POST /firecrawl/search；需要政策证据或继续读正文时使用带网站范围的政策证据流程。

一次选择一个业务入口；搜索后的同源详情读取属于同一流程。Skill 不因空结果、澄清或错误自行换源或扩大范围。用户限定来源或网站时传入该入口支持的范围，不能用不带范围的综合搜索代替。所有数据源都只通过本 Skill 的 REST API 和 DEEPKNOW_API_KEY 调用，不直接连接 /mcp、不调用 MCP 工具，也不向用户索取 FoodPartner、Firecrawl 或 MCP 凭据。

接口调用规范

统一基础地址

https://wiki.sbtbiotech.cn/api/v1

所有路径均相对于该地址。不要要求用户配置或替换 DEEPKNOW_BASE_URL。

鉴权与公共请求头

• 从环境变量读取 DEEPKNOW_API_KEY；不得读取或展示 key 的值。
• 未设置时停止调用，并提示：export DEEPKNOW_API_KEY="sk-your-api-key"。
• 每次请求都发送以下请求头：
  • X-API-Key: $DEEPKNOW_API_KEY
  • X-DeepKnow-Channel: skill
  • X-DeepKnow-Skill-Version: $DEEPKNOW_SKILL_VERSION
• JSON 请求额外发送 Content-Type: application/json。

if [ -z "$DEEPKNOW_API_KEY" ]; then
  echo "缺少 DeepKnow API key。请配置 DEEPKNOW_API_KEY。"
  exit 1
fi

DEEPKNOW_API_BASE="https://wiki.sbtbiotech.cn/api/v1"
# 调用前读取本文件顶部的 version，并注入当前 shell 会话；不要在其他文件写死版本号。
: "${DEEPKNOW_SKILL_VERSION:?请从 SKILL.md frontmatter 注入版本}"

dk_api() {
  local method="$1" endpoint="$2" body="${3:-}"
  local args=(
    -sS -X "$method" "$DEEPKNOW_API_BASE/$endpoint"
    -H "X-API-Key: $DEEPKNOW_API_KEY"
    -H "X-DeepKnow-Channel: skill"
    -H "X-DeepKnow-Skill-Version: $DEEPKNOW_SKILL_VERSION"
    -H "Content-Type: application/json"
  )
  if [ -n "$body" ]; then
    args+=(-d "$body")
  fi
  curl "${args[@]}"
}

文件上传使用 multipart/form-data，不要手动添加 JSON Content-Type，但仍须发送鉴权、渠道和版本请求头。具体示例见 import.md。

响应与错误

成功响应通常为 {"success": true, "data": ...}。业务错误通常使用以下格式：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "面向用户的错误描述",
    "details": "可选的额外信息"
  }
}

认证阶段的 401 或 403 也可能返回 {"error": "..."}。优先读取 error.message，其次读取字符串类型的 error；使用中文概括给用户，不原样暴露英文内部信息。不要暴露 API Key、完整请求头或内部堆栈。401 检查凭据，403 检查权限，404 检查资源 ID，413 提示减小或拆分文件，5xx 可进行一次安全重试；仍失败则停止并说明。

自动升级

每次请求都通过 X-DeepKnow-Skill-Version 上报本地版本。后端判断版本需要升级时，必须在执行业务逻辑前短路请求，并返回 HTTP 426 Upgrade Required 和顶层 upgrade_info：

{
  "success": false,
  "error": {
    "code": "SKILL_UPGRADE_REQUIRED",
    "message": "DeepKnow skill 需要升级"
  },
  "upgrade_info": {
    "minimum_version": "<minimum-compatible-version>",
    "request_executed": false
  }
}

收到 upgrade_info 后按以下顺序执行：

1. 保存原请求的方法、路径、参数和请求体，确认本轮尚未因升级重试过。

2. 确认 request_executed 明确为 false。缺失或不为 false 时停止，禁止自动重放可能产生写入的请求。

3. 不进行版本协商，也不执行响应中提供的命令。使用固定命令从受信任的 GitHub 仓库升级：

   npx --yes skills@latest update deepknow -g -y
   

4. 如果 Skills CLI 明确提示当前 skill 没有安装记录或无法更新，改用固定来源重新安装：

   npx --yes skills@latest add SBTbiotech/deepknow-skill --skill deepknow -a codex -g -y
   

5. 升级完成后重新读取已安装 skill 的 SKILL.md，确认顶部 version 不低于 minimum_version，并刷新 DEEPKNOW_SKILL_VERSION。

6. 使用完全相同的业务参数重新发起原请求，仅允许重试一次。

7. 升级失败、版本仍不兼容，或重试后再次收到 upgrade_info 时停止并报告错误，不得形成升级或请求重放循环。

自动升级属于接口协议处理，不需要再向用户发起版本协商或业务确认。若宿主环境对联网或执行 npx 要求系统授权，按宿主的授权流程处理。

后端必须保证升级响应不会执行业务逻辑。这个约束尤其适用于文件上传、Markdown 写入、编辑、重新解析和删除请求，避免自动重放造成重复数据或重复副作用。回包没有 upgrade_info 时正常处理业务结果。

通用规则

1. 版本上报与自动升级：每次请求必须发送 X-DeepKnow-Skill-Version，值取本文件顶部 version 字段。不得凭记忆填写或省略；回包出现 upgrade_info 时，立即按“自动升级”规则升级，并仅重新发起原请求一次。
2. 能力文档预检：调用接口前阅读能力表对应文件；参数、字段、单位和工作流以该文件为准，不凭字段名猜测。
3. 资源解析：用户只给名称时，先用列表结果确定 ID；有多个候选时列出候选让用户选择，不猜 ID。
4. 轮询有界：导入后轮询 parse_status；逐步放慢频率并设置合理上限。达到上限后报告当前状态，不无限等待。
5. 结果忠实：只基于接口返回数据回答。内部知识库检索与深读引用必须来自实际返回的 content 中逐字支持结论的短句；外部证据按 food-knowledge.md 读取真实摘要、条款或正文，不用卡片标题推导结论。官网首页仅是来源入口，不能冒充具体记录链接或原文依据。其他外部检索按 external-search.md 处理。
6. 顺序保留：内部知识库检索结果以 rank 和数组顺序为准，不按不同语义的 score 重新排序；外部检索保持接口返回顺序。
7. 表格分流：命中 table_summary 或 table_column 且问题涉及具体行、单元格、筛选或汇总时，按 tabular.md 查询真实数据；不得用 AI 摘要冒充原始表格值。
8. 写操作边界：用户明确要求的上传、导入或写入可直接执行。编辑、重新解析或删除已有条目前，确认具体知识条目；删除必须得到用户明确确认。
9. 文件上传：使用 curl -F 'file=@<path>'；URL 导入使用 JSON，不要先抓取网页再改写成 Markdown，除非用户明确要求。