union_kb_ingest 1.0.2 → 1.0.3

package/README.md

@@ -8,7 +8,7 @@
 2. 通过 Docling slim 的离线文本解析能力生成统一 Markdown 中间格式。
 3. 按章节、场景、规则、指标等粒度切割。
 4. 可选调用大模型，把内容整理为项目知识库规范要求的 Markdown 文件。
-5. 默认生成 `status: draft` 草稿，不进入现有 RAG 检索。
+5. 默认生成可直接交给知识库项目使用的 `status: active` Markdown 文件。
 
 启用大模型时，工具会把 `prompts/联合运维知识库建立规范.md` 作为格式和质量约束放入提示词，要求模型依据原文语义判断业务场景、模块、角色、标签和风险等级。代码中的启发式生成只作为未启用大模型或调用失败时的兜底，不使用预设业务关键词去指导大模型输出。
 
@@ -37,13 +37,13 @@ python -m pip install -r requirements.txt
 input/
 ```
 
-生成草稿：
+生成知识库文件：
 
 ```bash
 python ingest.py draft
 ```
 
-如果 `drafts/` 中已有草稿文件，命令会先询问是否覆盖。选择 `y` 后会清空 `drafts/`、`approved/` 和 `result/` 中已有生成文件，再重新生成；选择其他内容会直接退出，避免多次生成结果相互影响。
+如果 `result/` 中已有生成文件，命令会先询问是否覆盖。选择 `y` 后会清空 `result/` 中已有生成文件，再重新生成；选择其他内容会直接退出，避免多次生成结果相互影响。
 
 只解析为中间 Markdown：
 
@@ -51,25 +51,23 @@ python ingest.py draft
 python ingest.py parse
 ```
 
-校验草稿：
+校验生成结果：
 
 ```bash
 python ingest.py validate
 ```
 
-审核后复制到知识库：
+默认目录为 `input/`、`parsed/` 和 `result/`。只有需要处理其他目录时，才使用 `--input` 或 `--output` 覆盖。
 
-```bash
-python ingest.py promote
-```
+`draft` 默认按 `config/config.yaml` 的 `draft.max_chars` 控制单次送入模型的原文长度，并额外提供文档目录和相邻片段摘要作为辅助上下文。这样可以降低私有模型单轮负载，同时尽量保留前后章节关系。命令行仍可用 `--max-chars` 临时覆盖。
 
-默认目录为 `input/`、`parsed/`、`drafts/`、`approved/` 和 `result/`。只有需要处理其他目录时，才使用 `--input`、`--output` 或 `--result-dir` 覆盖。
+每条知识库文件会写入分类画像元数据：`category`、`category_description` 和 `category_keywords`。这些字段优先来自源文件一级标题、首页标题、章节目录和文件名，用于标识一个批次/业务场景的大类。后续 RAG 入库和检索时，应把这些字段写入向量库 metadata，并用于分类过滤、查询路由或重排加权，降低不同场景之间因为相似词命中而串场的概率。
 
-`draft` 默认按 `config/config.yaml` 的 `draft.max_chars` 控制单次送入模型的原文长度，并额外提供文档目录和相邻片段摘要作为辅助上下文。这样可以降低私有模型单轮负载，同时尽量保留前后章节关系。命令行仍可用 `--max-chars` 临时覆盖。
+生成结果会按原始输入遍历顺序写入 `source_order`，并用 `000001-...md` 这样的文件名前缀保持目录排序与原文从上到下的顺序一致。页码只写入 Front Matter 的 `source_pages`/`source_trace` 和正文 `## 5. 来源依据`，不会进入正文 `## 1. 核心内容` 到 `## 4. 关联能力`。
 
 ## 大模型配置
 
-默认不强制调用大模型，会使用启发式模板生成 `draft` 文件。
+默认不强制调用大模型，会使用启发式模板生成知识库文件。
 
 如果要启用大模型整理，修改 `config/config.yaml`：
 
@@ -98,10 +96,10 @@ export KB_LLM_API_KEY="your-zhipu-api-key"
 export KB_LLM_MODEL="glm-4.7"
 ```
 
-工具通过 ZhipuAI SDK 调用 GLM，不再包含 OpenAI 调用路径。`base_url` 使用 ZhipuAI SDK 的服务根地址即可。工具不 import 项目 `src` 代码。
+工具通过 Z.AI 新版 Python SDK 调用中文智谱开放平台 GLM，依赖固定为 `zai-sdk==0.2.2`，客户端固定使用官方中文写法 `from zai import ZhipuAiClient`，`base_url` 使用 `https://open.bigmodel.cn/api/paas/v4/`。工具不再包含旧 `zhipuai` SDK、国际版 `ZaiClient` 或 OpenAI 调用路径，也不 import 项目 `src` 代码。
 
 ## 与线上项目的关系
 
-这个工具只产出符合规范的 `*.md` 文件。确认无误后，人工把 `status: draft` 改为 `active`，再放入 `result/`，后续由线上知识库加载流程处理。
+这个工具只产出符合规范的 `*.md` 文件到 `result/`，后续由线上知识库加载流程处理。
 
 建议线上打包时排除整个 `tools/kb_ingest` 目录。

package/config/config.yaml

@@ -1,9 +1,9 @@
 llm:
-  enabled: true
+  enabled: false
   timeout_seconds: 120
   max_tokens: 8192
   temperature: 0.1
-  api_key: "15f066c4509845038027ea5746524af5.w4CLSC6ODiKVC1wK"
+  api_key: "your-zhipu-api-key"
   model: "GLM-4.7-Flash"
   base_url: "https://open.bigmodel.cn/api/paas/v4/"
 

package/ingest.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 import argparse
-import shutil
 import sys
 from pathlib import Path
 from typing import List
@@ -41,20 +40,19 @@ def cmd_parse(args) -> int:
 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):
+    if existing and not _confirm_overwrite(output_dir, existing):
         print("aborted. existing files were kept.")
         return 0
 
     if existing:
-        _clear_generated_files(output_dir, approved_dir, result_dir)
+        _clear_generated_files(output_dir)
 
     output_dir.mkdir(parents=True, exist_ok=True)
 
     total_items = 0
+    source_order = 0
     draft_config = get_draft_config()
     max_chars = args.max_chars or draft_config.max_chars
     files = iter_input_files(input_path)
@@ -67,7 +65,11 @@ def cmd_draft(args) -> int:
             outline_max_sections=draft_config.outline_max_sections,
         )
         for block in blocks:
-            for item in normalize_block(block, status="draft"):
+            for item in normalize_block(block, status=args.status):
+                source_order += 1
+                item.source_order = source_order
+                item.source_pages = sorted(set(block.pages))
+                item.source_trace = _source_trace(block)
                 write_item(item, output_dir)
                 total_items += 1
         print(f"drafted: {path} blocks={len(blocks)}")
@@ -86,15 +88,11 @@ def _list_effective_files(path: Path) -> list[Path]:
 
 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"}
 
@@ -120,6 +118,13 @@ def _attach_block_context(
         parts = []
         if outline:
             parts.append(f"文档章节目录：\n{outline}")
+        if block.category_description:
+            parts.append(
+                "知识大类说明：\n"
+                f"大类：{block.category}\n"
+                f"说明：{block.category_description}\n"
+                f"关键词：{', '.join(block.category_keywords)}"
+            )
         if idx > 0:
             parts.append(
                 "上一片段摘要：\n"
@@ -139,6 +144,9 @@ def _attach_block_context(
             pages=block.pages,
             order=block.order,
             context="\n\n".join(parts),
+            category=block.category,
+            category_description=block.category_description,
+            category_keywords=block.category_keywords,
         ))
     return output
 
@@ -167,6 +175,13 @@ def _compact_context_text(text: str, limit: int) -> str:
     return compact[:limit].rstrip() + "..."
 
 
+def _source_trace(block: ParsedBlock) -> str:
+    parts = [f"section={block.source_section}"]
+    if block.pages:
+        parts.append(f"pages={','.join(map(str, sorted(set(block.pages))))}")
+    return "; ".join(parts)
+
+
 def cmd_validate(args) -> int:
     issues = validate_dir(Path(args.input))
     for issue in issues:
@@ -175,20 +190,6 @@ def cmd_validate(args) -> int:
     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)
@@ -200,21 +201,15 @@ def build_parser() -> argparse.ArgumentParser:
 
     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("--output", default=str(CURRENT_DIR / "result"))
+    draft_cmd.add_argument("--status", default="active", choices=["draft", "active"])
     draft_cmd.add_argument("--max-chars", type=int, default=None)
     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.add_argument("--input", default=str(CURRENT_DIR / "result"))
     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