SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdeepknow

deepknow

General & other

View repository

Updated 10-16 16:28

About this skill

DeepKnow — Knowledge and Retrieval Assistant

Import and browse knowledge through the DeepKnow REST API, retrieve internal knowledge, comprehensive materials, Food Partner Network, or controlled web pages, and query real table data.

Supported Capabilities

Capability Description User Example Read Before Calling
Knowledge base browsing and deep reading List knowledge bases, folders, categories, and entries; read details and original text chunks "Continue reading the context of this material" knowledge-bases.md
Knowledge import and management Upload files, import URLs/Feishu, write or edit Markdown, re-parse, delete "Add this PDF to the regulations library" import.md
Knowledge retrieval Single-base/cross-base or folder-scoped retrieval, filter by category, generate verifiable citations "Only search materials in the R&D folder" search.md
Comprehensive material retrieval Aggregate professional sources, official websites, and authorized official account materials; return material cards and links "Look up materials related to quercetin" food-knowledge.md
Food Partner Network retrieval Query professional data such as food regulations, standards, additives, contaminants, or production licenses "In which foods can potassium sorbate be used?" external-search.md
Real-time web retrieval Query the latest web pages, policies, or current information under approved domains "Check the latest food policy from the National Health Commission" external-search.md
Table query Natural language query, view table structure, query rows by controlled DSL, preview original grid "Who has the highest sales in East China?" tabular.md

Based on user intent, first read the corresponding documentation file in full, then call the interface. For cross-capability tasks, read only the files actually needed.

Retrieval Data Source Routing

Before retrieval, choose one business entry point based on user intent:

  • Enterprise internal policies, project materials, or other already-ingested content: read search.md, call POST /knowledge-search。
  • Cross-source search for research, regulations, or related materials on a certain topic, without limiting to a single source: read food-knowledge.md, call POST /food-knowledge/search。
  • Professional data such as food standards, regulations, additives, nutrient supplements, contaminants, pesticide or veterinary drug residues, food classification, production licenses: read external-search.md, first call POST /foodpartner/search, and call only when complete records or the next page are needed POST /foodpartner/fetch。
  • Latest web pages, real-time policies, or current information from controlled external sites are needed: read external-search.md, call POST /firecrawl/search。

Choose one business entry point at a time. Comprehensive search can aggregate multiple sources on the backend, and the web interface can execute the existing server-side fallback; the Skill does not switch entry points or append multi-source queries on its own due to empty results, clarification, or errors. When the user limits the source, use the corresponding entry point and do not substitute comprehensive search that cannot limit the source; if the intent cannot be uniquely determined, first ask the user to confirm. All data sources are called only through this Skill's REST API and DEEPKNOW_API_KEY , without directly connecting to /mcp, without calling MCP tools, and without requesting FoodPartner, Firecrawl, or MCP credentials from the user.

API Invocation Specification

Unified Base URL

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

All paths are relative to this address. Do not require users to configure or replace DEEPKNOW_BASE_URL。

Authentication and Common Request Headers

  • Read from the environment variable DEEPKNOW_API_KEY; do not read or display the value of the key.
  • If not set, stop the invocation and prompt:export DEEPKNOW_API_KEY="sk-your-api-key"。
  • Send the following request headers with every request:
    • X-API-Key: $DEEPKNOW_API_KEY
    • X-DeepKnow-Channel: skill
    • X-DeepKnow-Skill-Version: $DEEPKNOW_SKILL_VERSION
  • For JSON requests, additionally send 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[@]}"
}

File uploads use multipart/form-data, do not manually add the JSON Content-Type, but you must still send the authentication, channel, and version request headers. For specific examples, see import.md。

Responses and Errors

Successful responses are usually {"success": true, "data": ...}. Business errors usually use the following format:

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

During the authentication stage, 401 or 403 may also return {"error": "..."}. Prefer reading error.message, then read the string-type error; summarize for the user in Chinese, and do not expose English internal information verbatim. Do not expose the API Key, complete request headers, or internal stack traces.401 Check credentials,403 check permissions,404 check the resource ID,413 prompt to reduce or split the file,5xx you may perform one safe retry; if it still fails, stop and explain.

Automatic Upgrade

Report the local version via X-DeepKnow-Skill-Version with every request. When the backend determines that the version needs to be upgraded, it must short-circuit the request before executing business logic and return HTTP 426 Upgrade Required and top-level upgrade_info：

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

After receiving upgrade_info , execute in the following order:

  1. Save the original request's method, path, parameters, and request body, and confirm that this round has not already been retried due to an upgrade.

  2. Confirm that request_executed is explicitly false. If missing or not false , stop; do not automatically replay requests that may produce writes.

  3. Do not perform version negotiation, and do not execute commands provided in the response. Use a fixed command to upgrade from a trusted GitHub repository:

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

  4. If the Skills CLI explicitly indicates that the current skill has no installation record or cannot be updated, switch to a fixed source to reinstall:

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

  5. After the upgrade is complete, re-read the installed skill's SKILL.md, confirm that the top version is not lower than minimum_version, and refresh DEEPKNOW_SKILL_VERSION。

  6. Re-initiate the original request using exactly the same business parameters; only one retry is allowed.

  7. If the upgrade fails, the version is still incompatible, or upgrade_info is received again after the retry, stop and report the error; do not form an upgrade or request replay loop.

Automatic upgrade is API protocol handling and does not require initiating version negotiation or business confirmation with the user. If the host environment requires system authorization for network access or executing npx , handle it according to the host's authorization process.

The backend must ensure that upgrade responses do not execute business logic. This constraint especially applies to file upload, Markdown write, edit, re-parse, and delete requests, to avoid duplicate data or duplicate side effects caused by automatic replay. If the response does not contain upgrade_info , process the business result normally.

General Rules

  1. Version Reporting and Automatic Upgrade: Every request must send X-DeepKnow-Skill-Version, with the value taken from the version field at the top of this file. Do not fill it in from memory or omit it; when the response contains upgrade_info , immediately upgrade according to the "Automatic Upgrade" rules, and re-initiate the original request only once.
  2. Capability document pre-check: Before calling an interface, read the corresponding file in the capability table; parameters, fields, units, and workflows are governed by that file—do not guess based on field names.
  3. Resource resolution: When the user provides only a name, first use the list results to determine the ID; when there are multiple candidates, list the candidates for the user to choose—do not guess the ID.
  4. Bounded polling: After import, poll parse_status; gradually slow down the frequency and set a reasonable upper limit. After reaching the limit, report the current status—do not wait indefinitely.
  5. Faithful results: Answer only based on data returned by the interface. Internal knowledge base retrieval and deep reading citations must come from the actually returned content short sentences that verbatim support the conclusion; treat synthesized materials according to food-knowledge.md, and other external retrieval according to external-search.md for evidence and citations.
  6. Preserve order: Internal knowledge base retrieval results are governed by rank and the array order—do not reorder by score of different semantics; external retrieval preserves the order returned by the interface.
  7. Table routing: When table_summary or table_column is hit and the question involves specific rows, cells, filtering, or aggregation, query real data according to tabular.md ; do not use AI summaries to impersonate original table values.
  8. Write operation boundaries: Uploads, imports, or writes explicitly requested by the user can be executed directly. Before editing, reparsing, or deleting an existing entry, confirm the specific knowledge entry; deletion must receive explicit user confirmation.
  9. File upload: Use curl -F 'file=@<path>'; for URL import, use JSON—do not first scrape the webpage and then rewrite it as Markdown unless the user explicitly requests it.