union_kb_ingest 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# 离线知识库文件生成工具
+
+这个目录是离线辅助工具，不参与线上应用运行。
+
+目标：
+
+1. 批量读取 PDF、Word、Markdown、TXT 文档。
+2. 通过 Docling slim 的离线文本解析能力生成统一 Markdown 中间格式。
+3. 按章节、场景、规则、指标等粒度切割。
+4. 可选调用大模型，把内容整理为项目知识库规范要求的 Markdown 文件。
+5. 默认生成 `status: draft` 草稿，不进入现有 RAG 检索。
+
+启用大模型时，工具会把 `prompts/联合运维知识库建立规范.md` 作为格式和质量约束放入提示词，要求模型依据原文语义判断业务场景、模块、角色、标签和风险等级。代码中的启发式生成只作为未启用大模型或调用失败时的兜底，不使用预设业务关键词去指导大模型输出。
+
+## 安装可选依赖
+
+不建议把这些依赖加入项目根 `requirements.txt`。离线机器单独安装即可：
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+解析层不使用 OCR，不加载本地视觉/版面模型，也不访问远程模型服务：
+
+- PDF：使用 `docling-parse` 抽取 PDF 内嵌文本和文本行顺序；扫描件或图片型 PDF 不会识别。
+- DOCX：使用 Docling 的 Word 后端转为 Markdown。
+- 旧版 `.doc`：通过 LibreOffice `soffice` 转为 `.docx` 后再解析；不使用 OCR。
+- Markdown / TXT：作为已文本化材料直接读取。
+
+不要安装 `docling` 或 `docling-slim[standard]`，它们会引入 OCR、版面/表格模型、Torch/ONNXRuntime 等重依赖，并可能在运行时下载模型。内网机器建议为离线工具单独准备 Python 3.10+ 环境。
+
+## 基本用法
+
+把文件放入：
+
+```text
+input/
+```
+
+生成草稿：
+
+```bash
+python ingest.py draft
+```
+
+如果 `drafts/` 中已有草稿文件，命令会先询问是否覆盖。选择 `y` 后会清空 `drafts/`、`approved/` 和 `result/` 中已有生成文件，再重新生成；选择其他内容会直接退出，避免多次生成结果相互影响。
+
+只解析为中间 Markdown：
+
+```bash
+python ingest.py parse
+```
+
+校验草稿：
+
+```bash
+python ingest.py validate
+```
+
+审核后复制到知识库：
+
+```bash
+python ingest.py promote
+```
+
+默认目录为 `input/`、`parsed/`、`drafts/`、`approved/` 和 `result/`。只有需要处理其他目录时，才使用 `--input`、`--output` 或 `--result-dir` 覆盖。
+
+## 大模型配置
+
+默认不强制调用大模型，会使用启发式模板生成 `draft` 文件。
+
+如果要启用大模型整理，修改 `config/config.yaml`：
+
+```yaml
+llm:
+  enabled: true
+  base_url: "https://your-model-endpoint"
+  api_key: "your-api-key"
+  model: "your-model"
+  timeout_seconds: 120
+  max_tokens: 4096
+  temperature: 0.1
+```
+
+也可以继续使用环境变量覆盖配置文件：
+
+```bash
+export KB_LLM_ENABLED=true
+export KB_LLM_BASE_URL="https://your-model-endpoint"
+export KB_LLM_API_KEY="your-api-key"
+export KB_LLM_MODEL="your-model"
+```
+
+`base_url` 必须填写完整的大模型调用地址，工具不会自动拼接任何路径。工具不 import 项目 `src` 代码。
+
+## 与线上项目的关系
+
+这个工具只产出符合规范的 `*.md` 文件。确认无误后，人工把 `status: draft` 改为 `active`，再放入 `result/`，后续由线上知识库加载流程处理。
+
+建议线上打包时排除整个 `tools/kb_ingest` 目录。

package/app_config.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict
+
+import yaml
+
+
+CURRENT_DIR = Path(__file__).resolve().parent
+DEFAULT_CONFIG_PATH = CURRENT_DIR / "config" / "config.yaml"
+
+
+@dataclass(frozen=True)
+class LlmConfig:
+    enabled: bool = False
+    base_url: str = ""
+    api_key: str = ""
+    model: str = ""
+    timeout_seconds: int = 120
+    max_tokens: int = 4096
+    temperature: float = 0.1
+
+
+@lru_cache(maxsize=1)
+def get_llm_config() -> LlmConfig:
+    raw = _read_config().get("llm", {})
+    if not isinstance(raw, dict):
+        raw = {}
+
+    return LlmConfig(
+        enabled=_env_bool("KB_LLM_ENABLED", _as_bool(raw.get("enabled"), False)),
+        base_url=os.environ.get("KB_LLM_BASE_URL", str(raw.get("base_url") or "")),
+        api_key=os.environ.get("KB_LLM_API_KEY", str(raw.get("api_key") or "")),
+        model=os.environ.get("KB_LLM_MODEL", str(raw.get("model") or "")),
+        timeout_seconds=_env_int("KB_LLM_TIMEOUT_SECONDS", raw.get("timeout_seconds"), 120),
+        max_tokens=_env_int("KB_LLM_MAX_TOKENS", raw.get("max_tokens"), 4096),
+        temperature=_env_float("KB_LLM_TEMPERATURE", raw.get("temperature"), 0.1),
+    )
+
+
+def _read_config() -> Dict[str, Any]:
+    path = Path(os.environ.get("KB_INGEST_CONFIG", DEFAULT_CONFIG_PATH))
+    if not path.exists():
+        return {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return data if isinstance(data, dict) else {}
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    return _as_bool(value, default)
+
+
+def _env_int(name: str, value: Any, default: int) -> int:
+    raw = os.environ.get(name, value)
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+def _env_float(name: str, value: Any, default: float) -> float:
+    raw = os.environ.get(name, value)
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+def _as_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "y", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "n", "off"}:
+            return False
+    return default

package/approved/.gitkeep

@@ -0,0 +1 @@
+

package/bin/union_kb_ingest

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/../ingest.py" "$@"

package/config/config.yaml

@@ -0,0 +1,8 @@
+llm:
+  enabled: false
+  timeout_seconds: 120
+  max_tokens: 4096
+  temperature: 0.1
+  api_key: "your-api-key"          # API Key
+  model: "your-model"              # 模型名称
+  base_url: "https://your-model-endpoint"  # 完整模型调用地址

package/drafts/.gitkeep

@@ -0,0 +1 @@
+

package/ingest.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+CURRENT_DIR = Path(__file__).resolve().parent
+if str(CURRENT_DIR) not in sys.path:
+    sys.path.insert(0, str(CURRENT_DIR))
+
+from normalizer import normalize_block
+from parser import iter_input_files, parse_document
+from splitter import split_blocks
+from validator import validate_dir
+from writer import write_item
+
+
+IGNORED_EXISTING_FILES = {".gitkeep", ".DS_Store"}
+
+
+def cmd_parse(args) -> int:
+    input_path = Path(args.input)
+    output_dir = Path(args.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    files = iter_input_files(input_path)
+    for path in files:
+        parsed = parse_document(path)
+        out = output_dir / f"{path.stem}.parsed.md"
+        out.write_text(parsed.markdown, encoding="utf-8")
+        print(f"parsed: {path} -> {out}")
+    print(f"done. files={len(files)}")
+    return 0
+
+
+def cmd_draft(args) -> int:
+    input_path = Path(args.input)
+    output_dir = Path(args.output)
+    approved_dir = Path(args.approved_dir)
+    result_dir = Path(args.result_dir)
+
+    existing = _list_effective_files(output_dir)
+    if existing and not _confirm_overwrite(output_dir, approved_dir, result_dir, existing):
+        print("aborted. existing files were kept.")
+        return 0
+
+    if existing:
+        _clear_generated_files(output_dir, approved_dir, result_dir)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    total_items = 0
+    files = iter_input_files(input_path)
+    for path in files:
+        parsed = parse_document(path)
+        blocks = split_blocks(parsed.blocks, max_chars=args.max_chars)
+        for block in blocks:
+            for item in normalize_block(block, status="draft"):
+                write_item(item, output_dir)
+                total_items += 1
+        print(f"drafted: {path} blocks={len(blocks)}")
+    print(f"done. files={len(files)} draft_items={total_items} output={output_dir}")
+    return 0
+
+
+def _list_effective_files(path: Path) -> list[Path]:
+    if not path.exists():
+        return []
+    return sorted(
+        p for p in path.rglob("*")
+        if p.is_file() and p.name not in IGNORED_EXISTING_FILES
+    )
+
+
+def _confirm_overwrite(
+    output_dir: Path,
+    approved_dir: Path,
+    result_dir: Path,
+    existing: list[Path],
+) -> bool:
+    print(f"found {len(existing)} existing file(s) in {output_dir}.")
+    print("Continuing will delete existing generated files under:")
+    print(f"- {output_dir}")
+    print(f"- {approved_dir}")
+    print(f"- {result_dir}")
+    answer = input("Overwrite and continue? [y/N]: ").strip().lower()
+    return answer in {"y", "yes"}
+
+
+def _clear_generated_files(*dirs: Path) -> None:
+    for directory in dirs:
+        for path in _list_effective_files(directory):
+            path.unlink()
+            print(f"deleted: {path}")
+
+
+def cmd_validate(args) -> int:
+    issues = validate_dir(Path(args.input))
+    for issue in issues:
+        print(f"{issue.level}: {issue.path}: {issue.message}")
+    print(f"done. issues={len(issues)}")
+    return 1 if any(i.level == "error" for i in issues) else 0
+
+
+def cmd_promote(args) -> int:
+    input_dir = Path(args.input)
+    result_dir = Path(args.result_dir)
+    result_dir.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for path in sorted(input_dir.rglob("*.md")):
+        target = result_dir / path.name
+        shutil.copy2(path, target)
+        count += 1
+        print(f"promoted: {path} -> {target}")
+    print(f"done. promoted={count}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Offline document-to-knowledge Markdown generator.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    parse_cmd = sub.add_parser("parse", help="Parse input documents to intermediate Markdown.")
+    parse_cmd.add_argument("--input", default=str(CURRENT_DIR / "input"))
+    parse_cmd.add_argument("--output", default=str(CURRENT_DIR / "parsed"))
+    parse_cmd.set_defaults(func=cmd_parse)
+
+    draft_cmd = sub.add_parser("draft", help="Generate draft knowledge files.")
+    draft_cmd.add_argument("--input", default=str(CURRENT_DIR / "input"))
+    draft_cmd.add_argument("--output", default=str(CURRENT_DIR / "drafts"))
+    draft_cmd.add_argument("--approved-dir", default=str(CURRENT_DIR / "approved"))
+    draft_cmd.add_argument("--result-dir", default=str(CURRENT_DIR / "result"))
+    draft_cmd.add_argument("--max-chars", type=int, default=8000)
+    draft_cmd.set_defaults(func=cmd_draft)
+
+    validate_cmd = sub.add_parser("validate", help="Validate generated Markdown files.")
+    validate_cmd.add_argument("--input", default=str(CURRENT_DIR / "drafts"))
+    validate_cmd.set_defaults(func=cmd_validate)
+
+    promote_cmd = sub.add_parser("promote", help="Copy reviewed files to result.")
+    promote_cmd.add_argument("--input", default=str(CURRENT_DIR / "approved"))
+    promote_cmd.add_argument("--result-dir", default=str(CURRENT_DIR / "result"))
+    promote_cmd.set_defaults(func=cmd_promote)
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/input/.gitkeep

@@ -0,0 +1 @@
+

package/input/pdf/.gitkeep

@@ -0,0 +1 @@
+

package/input/word/.gitkeep

@@ -0,0 +1 @@
+