knowledge-and-ocr
Operate Yuxi knowledge-base, retrieval, document parsing, OCR, graph, mindmap, and knowledge evaluation workflows safely.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- knowledge-and-ocr
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Operate Yuxi knowledge-base, retrieval, document parsing, OCR, graph, mindmap, and knowledge evaluation workflows safely.
- disable-model-invocation
- true
02 资源文件 3
- 参考文档references/knowledge-workflows.md15.7 KB
- 参考文档references/ocr-engine-matrix.md9.7 KB
- 参考文档references/troubleshooting.md12.3 KB
03 SKILL.md 正文
Yuxi knowledge and OCR operating guide
Load this sub-skill when the task touches Yuxi knowledge bases, RAG retrieval, document upload/parse/chunk/index flows, OCR configuration, graph/mindmap features, knowledge evaluation, KB agent tools, or read_file OCR fallback behavior.
Owned capabilities
- Knowledge-base types: Milvus document KBs, Dify Dataset read-only retrieval connectors, and Notion Data Source read-only retrieval connectors.
- Document lifecycle: upload/import/fetch, file records, parsing to Markdown, chunking/indexing, re-indexing, file search/open/find/download, previews, and image proxy handling.
- Retrieval: vector, keyword/BM25, hybrid, reranker, file-name scoped search, and optional graph-enhanced retrieval for Milvus KBs.
- OCR: default engine resolution, per-file engine selection, config/health endpoints, local/service/cloud engines, and agent
ocr_parse_filefallback. - Knowledge structure: mindmap generation/diff/incremental update, generated sample questions, Milvus knowledge graph build/query/reset/reconcile.
- Evaluation: JSONL benchmark upload, LLM-generated benchmarks, RAG evaluation runs, result inspection, and metrics interpretation.
Use sibling sub-skills instead for deployment startup details, CLI command syntax, agent runtime internals unrelated to KB data, or general repo development workflow.
Safety gates before acting
- Classify the runtime need. Parser facade and metadata checks are CPU-safe; real KB ingestion/retrieval requires running services such as API, Postgres, Redis/task workers, MinIO, and Milvus. Graph build also needs Neo4j and a configured LLM provider. Some OCR engines require GPU services or cloud credentials.
- Do not assume credentials. Dify, Notion, MinerU Official, DeepSeek OCR, PaddleOCR API, rerankers, embeddings, and LLM-based graph/evaluation features may call external services. Confirm credentials and side effects before running them.
- Respect file boundaries. Knowledge files should enter via Yuxi upload/import/fetch APIs and be stored in MinIO before document record creation. Agent OCR fallback only accepts sandbox virtual paths under user-data
workspace,uploads, oroutputsand writes Markdown underoutputs/ocr. - Do not treat read-only connectors as Milvus. Dify and Notion are normal KB types for retrieval, but public document upload/open/find/download workflows are gated to document-supporting KBs; expect read-only connectors to reject file operations.
- Keep secrets out of logs and artifacts. Config APIs intentionally redact sensitive values; never print tokens or API keys while debugging.
First routing question
Choose the narrow workflow before touching code or services:
- Create/query/manage a KB: use references/knowledge-workflows.md.
- OCR or parser issue: use references/ocr-engine-matrix.md first, then references/troubleshooting.md.
- Agent KB tools: use references/knowledge-workflows.md.
- Graph or mindmap: use references/knowledge-workflows.md.
- Knowledge evaluation: use references/knowledge-workflows.md.
- Unknown failure: use references/troubleshooting.md and classify by KB type, file status, OCR engine, service dependency, and credential requirement.
Safe entry points
Prefer these entry points because they preserve Yuxi's permission, config, storage, and task semantics:
- Web/API routes under
/api/knowledge/*,/api/system/ocr/*,/api/system/config*,/api/system/config/options*,/api/evaluation/*, and/api/graph/*. - Python service/facade calls:
yuxi.knowledge.runtime.knowledge_base,yuxi.services.ocr_service.parse_document,yuxi.services.ocr_service.get_ocr_options,yuxi.services.ocr_service.check_all_ocr_health, andyuxi.knowledge.graphs.milvus_graph_service.MilvusGraphService. - Agent tools made available by the built-in
knowledge-baseskill dependency:list_kbs,get_mindmap,query_kb,search_file,open_kb_document,find_kb_document, anddownload_kb_file. - Agent built-in OCR helper:
ocr_parse_filefor sandbox PDF/Office/image to Markdown conversion.
Avoid calling low-level parser functions directly unless the task is specifically parser internals. The business entry point is parse_document; low-level PDF/image parsers expect an already resolved ocr_engine and can bypass DB/environment fallback if called incorrectly.
Verification candidates
- CPU-safe native candidate:
pytest backend/test/unit/knowledge/test_parser_facade.py— proves parser registry metadata, engine selection, parser facade, credential-safe cache keys, and common document conversion behavior. - Service-required candidate:
pytest backend/test/e2e/test_ocr_config_center_e2e.py— proves configured default OCR drives real temporary attachment parsing when API services and MinIO are available. - Service/model-required candidate:
pytest backend/test/e2e/test_read_file_multimodal_e2e.py— proves imageread_fileand non-vision OCR fallback only when model/OCR prerequisites are configured.
Run service-required candidates only after the deployment sub-skill's runtime checks pass and the needed credentials/providers are approved.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.