mcai-knowledge 0.2.0__py3-none-any.whl

mcai/corpus.py

@@ -0,0 +1,224 @@
+"""语料装载：把 docx / pdf / txt 统一成带章节路径的段落块。"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+from . import pdftext
+from .text import clean
+
+TERM_LINE = re.compile(
+    r"^\s*([^\s：:，。；、！？()（）《》\"']{2,16})\s*(?:[：:]|——|—|＝|=)\s*(.{8,})$"
+)
+_HEADING_STYLE = re.compile(r"^(Heading|标题)\s*(\d)?", re.I)
+_HEADING_NOISE = re.compile(r"[。！？；，,;]$")
+
+
+@dataclass
+class Block:
+    doc_id: str
+    doc_title: str
+    order: int
+    text: str
+    style: str = "Normal"
+    section: tuple[str, ...] = ()
+    location: str = ""
+
+    @property
+    def is_term_line(self) -> bool:
+        return bool(TERM_LINE.match(self.text))
+
+
+@dataclass
+class Document:
+    doc_id: str
+    title: str
+    path: str
+    kind: str
+    priority: int
+    blocks: list[Block] = field(default_factory=list)
+
+    @property
+    def text(self) -> str:
+        return "\n".join(b.text for b in self.blocks)
+
+    def sections(self) -> list[str]:
+        seen: list[str] = []
+        for b in self.blocks:
+            for s in b.section:
+                if s not in seen:
+                    seen.append(s)
+        return seen
+
+
+@dataclass
+class Corpus:
+    project: dict
+    keywords: list[str]
+    term_blacklist: list[str]
+    slugs: dict[str, str]
+    documents: list[Document]
+
+    @property
+    def blocks(self) -> Iterable[Block]:
+        for doc in self.documents:
+            yield from doc.blocks
+
+    def find(self, doc_id: str) -> Document | None:
+        return next((d for d in self.documents if d.doc_id == doc_id), None)
+
+
+def load_config(path: str | Path) -> dict:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _docx_blocks(doc: Document, path: Path) -> list[Block]:
+    from docx import Document as Docx
+    from docx.table import Table
+    from docx.text.paragraph import Paragraph
+
+    parsed = Docx(str(path))
+    blocks: list[Block] = []
+    section: list[str] = []
+    order = 0
+
+    def push(text: str, style: str, location: str) -> None:
+        nonlocal order
+        # Word 常把多条定义用「手动换行符」塞进同一段落，这里按换行拆开
+        for part in re.split(r"[\r\n\u000b\u2028\u2029]", text or ""):
+            part = clean(part)
+            if not part:
+                continue
+            m = _HEADING_STYLE.match(style or "")
+            if m and style != "Table":
+                level = int(m.group(2) or 1)
+                del section[level - 1:]
+                section.append(part)
+            blocks.append(
+                Block(doc.doc_id, doc.title, order, part, style or "Normal", tuple(section), location)
+            )
+            order += 1
+
+    body = parsed.element.body
+    for child in body.iterchildren():
+        tag = child.tag.split("}")[-1]
+        if tag == "p":
+            para = Paragraph(child, parsed)
+            push(para.text, para.style.name if para.style is not None else "Normal", f"p{order + 1}")
+        elif tag == "tbl":
+            table = Table(child, parsed)
+            for row in table.rows:
+                cells = [clean(c.text.replace("\n", " ")) for c in row.cells]
+                push(" | ".join(c for c in cells if c), "Table", f"t{order + 1}")
+
+    _promote_section_titles(blocks)
+    return blocks
+
+
+def _promote_section_titles(blocks: list[Block]) -> None:
+    """把「元意识体系」这类无样式短标题提升为章节。
+
+    判定：Normal 样式、长度 2-20、无句末标点，且后续三个块内出现「术语：定义」。
+    两遍处理：先定位标题，再按最近标题归属，避免后一个标题被前一个吞掉。
+    """
+    titles: dict[int, str] = {}
+    for i, block in enumerate(blocks):
+        if block.style not in ("Normal", "Normal (Web)"):
+            continue
+        text = block.text
+        if not (2 <= len(text) <= 20) or _HEADING_NOISE.search(text) or text.endswith("："):
+            continue
+        sep = re.search(r"[：:=]|——|—", text)
+        if sep and len(text[: sep.start()].strip()) < 4:
+            continue
+        if TERM_LINE.match(text) or text in ("结论表述", "结论"):
+            continue
+        if any(b.is_term_line for b in blocks[i + 1: i + 4]):
+            titles[i] = text
+
+    current: str | None = None
+    for i, block in enumerate(blocks):
+        if i in titles:
+            current = titles[i]
+        if current and len(block.section) <= 1:
+            block.section = (block.doc_title, current)
+
+
+def _pdf_blocks(doc: Document, path: Path) -> list[Block]:
+    blocks: list[Block] = []
+    for page_no, page in enumerate(pdftext.extract_pdf_text(str(path)), 1):
+        for line_no, line in enumerate(page.split("\n")):
+            text = clean(line)
+            if text:
+                blocks.append(
+                    Block(doc.doc_id, doc.title, len(blocks), text, "PDF", (), f"p{page_no}:{line_no + 1}")
+                )
+    return blocks
+
+
+def _text_blocks(doc: Document, path: Path, style: str) -> list[Block]:
+    blocks: list[Block] = []
+    section: list[str] = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        text = clean(raw)
+        if not text:
+            continue
+        if text.startswith("#"):
+            level = len(text) - len(text.lstrip("#"))
+            title = text.lstrip("#").strip()
+            del section[level - 1:]
+            section.append(title)
+            blocks.append(Block(doc.doc_id, doc.title, len(blocks), title, style, tuple(section), ""))
+        else:
+            blocks.append(Block(doc.doc_id, doc.title, len(blocks), text, style, tuple(section), ""))
+    return blocks
+
+
+def _resolve_path(path: Path) -> Path:
+    """文件被改名（如加了「3、」前缀）时，按文件名后缀就近找回，避免配置失效。"""
+    if path.exists():
+        return path
+    candidates = sorted(p for p in path.parent.glob(f"*{path.suffix}") if p.name.endswith(path.name))
+    return candidates[0] if candidates else path
+
+
+def load_document(spec: dict, base: Path | None = None) -> Document:
+    raw = Path(spec["path"]).expanduser()
+    if not raw.is_absolute() and base is not None:
+        raw = base / raw
+    path = _resolve_path(raw)
+    doc = Document(
+        doc_id=spec["id"],
+        title=spec.get("title") or path.stem,
+        path=str(path),
+        kind=spec.get("kind", "other"),
+        priority=int(spec.get("priority", 50)),
+    )
+    if not path.exists():
+        raise FileNotFoundError(f"语料缺失：{path}")
+    suffix = path.suffix.lower()
+    if suffix == ".docx":
+        doc.blocks = _docx_blocks(doc, path)
+    elif suffix == ".pdf":
+        doc.blocks = _pdf_blocks(doc, path)
+    elif suffix in (".txt", ".md"):
+        doc.blocks = _text_blocks(doc, path, "Text")
+    else:
+        raise ValueError(f"暂不支持的文件类型：{suffix}")
+    return doc
+
+
+def load_corpus(config_path: str | Path) -> Corpus:
+    cfg = load_config(config_path)
+    base = Path(config_path).resolve().parent.parent
+    docs = [load_document(spec, base) for spec in cfg["corpus"]]
+    return Corpus(
+        project=cfg["project"],
+        keywords=cfg.get("keywords", []),
+        term_blacklist=cfg.get("term_blacklist", []),
+        slugs=cfg.get("slugs", {}),
+        documents=docs,
+    )

mcai/dashboard.py

@@ -0,0 +1,229 @@
+"""本地观测台：把自动巡检、调用统计、变更历史汇成一页静态 HTML。"""
+from __future__ import annotations
+
+import html
+import json
+from datetime import datetime
+from pathlib import Path
+
+from .telemetry import Telemetry
+
+CSS = """
+body{margin:0;background:#faf8f4;color:#1c1b19;font-family:"Noto Sans SC","PingFang SC","Microsoft YaHei",system-ui,sans-serif;line-height:1.7}
+.wrap{max-width:1000px;margin:0 auto;padding:32px 24px 64px}
+h1{font-family:"Noto Serif SC",serif;font-size:32px;margin:0 0 6px}
+h2{font-family:"Noto Serif SC",serif;font-size:20px;margin:36px 0 12px;padding-bottom:8px;border-bottom:1px solid #e3ddd2}
+.muted{color:#6b665e;font-size:13px}
+.badge{display:inline-block;padding:2px 10px;border-radius:999px;font-size:12px;background:#e8f3e8;color:#256b2f}
+.badge.bad{background:#fbe6e3;color:#a3311f}
+.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:14px;margin-top:22px}
+.card{background:#fffdf9;border:1px solid #e3ddd2;border-radius:12px;padding:16px}
+.card b{display:block;font-size:26px;font-family:"Noto Serif SC",serif}
+.card span{color:#6b665e;font-size:12px}
+table{width:100%;border-collapse:collapse;font-size:14px;background:#fffdf9;border:1px solid #e3ddd2;border-radius:10px;overflow:hidden}
+th,td{padding:9px 12px;border-bottom:1px solid #eee7db;text-align:left;vertical-align:top}
+th{background:#f3eee4;font-weight:600;font-size:12px;color:#6b665e}
+tr:last-child td{border-bottom:0}
+.bars{display:flex;align-items:flex-end;gap:6px;height:90px;margin-top:12px}
+.bar{flex:1;background:#c9b8a4;border-radius:3px 3px 0 0;min-height:2px}
+.barlabel{font-size:10px;color:#6b665e;text-align:center}
+.pill{display:inline-block;padding:1px 7px;border-radius:4px;background:#efe9df;font-size:11px;color:#6b665e;margin-right:4px}
+a{color:#8a3324;text-decoration:none}
+a:hover{text-decoration:underline}
+.nav a{margin-right:16px}
+.empty{color:#a39c90;font-size:13px;padding:8px 0}
+"""
+
+
+def _read_json(path: Path, default):
+    if not path.exists():
+        return default
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return default
+
+
+def _read_jsonl(path: Path, limit: int = 50) -> list[dict]:
+    if not path.exists():
+        return []
+    rows = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows[-limit:]
+
+
+def _bars(values: dict[str, int]) -> str:
+    if not values or not any(values.values()):
+        return '<div class="empty">暂无调用记录</div>'
+    peak = max(values.values()) or 1
+    out = ['<div class="bars">']
+    for day, count in values.items():
+        height = max(2, int(78 * count / peak))
+        out.append(f'<div class="bar" style="height:{height}px" title="{day}: {count}"></div>')
+    out.append("</div><div style=\"display:flex;gap:6px\">")
+    for day in values:
+        out.append(f'<div class="barlabel" style="flex:1">{day[5:]}</div>')
+    out.append("</div>")
+    return "".join(out)
+
+
+def render(root: str | Path) -> Path:
+    root = Path(root)
+    data = root / "data"
+    dist = root / "dist"
+    dist.mkdir(parents=True, exist_ok=True)
+
+    kb_meta = _read_json(data / "kb.json", {}).get("meta", {})
+    excluded = ((kb_meta.get("stats") or {}).get("policy") or {}).get("excluded_entities") or []
+
+    def redact(text: str) -> str:
+        for e in excluded:
+            text = text.replace(e, "（作者）")
+        return text
+
+    status = _read_json(data / "status.json", {})
+    quality = _read_json(data / "quality.json", {})
+    selftest = _read_json(data / "selftest.json", {})
+    history = _read_jsonl(data / "autopilot.jsonl", 200)
+    changelog = _read_jsonl(data / "changelog.jsonl", 30)
+    tele = Telemetry(data / "usage.jsonl").stats()
+
+    ok = bool(status.get("ok"))
+    badge = f'<span class="badge{"" if ok else " bad"}">{"健康" if ok else "异常"}</span>'
+
+    cards = [
+        ("概念", status.get("concepts", "-")),
+        ("问答", status.get("faqs", "-")),
+        ("关系", status.get("relations", "-")),
+        ("引证", status.get("evidence", "-")),
+        ("质量错误", (quality.get("counts") or {}).get("error", "-")),
+        ("质量警告", (quality.get("counts") or {}).get("warn", "-")),
+        ("自测通过", f"{selftest.get('passed', '-')}/{selftest.get('total', '-')}"),
+        ("业务问答", tele.get("business", 0)),
+        ("命中率", f"{round((tele.get('hit_rate') or 0) * 100)}%"),
+        ("技能调用", (tele.get("by_client_kind") or {}).get("skill", 0)),
+        ("命令行调用", (tele.get("by_client_kind") or {}).get("shell", 0)),
+        ("外部调用", (tele.get("by_origin") or {}).get("external", 0)),
+    ]
+    cards_html = "".join(
+        f'<div class="card"><b>{html.escape(str(v))}</b><span>{html.escape(k)}</span></div>'
+        for k, v in cards
+    )
+
+    # 巡检时间线
+    rows = []
+    for item in reversed(history[-20:]):
+        rebuilt = "是" if item.get("rebuilt") else "否"
+        q = item.get("quality") or {}
+        t = item.get("selftest") or {}
+        rows.append(
+            "<tr>"
+            f"<td>{html.escape(str(item.get('checked_at', '')))}</td>"
+            f"<td>{'✅' if item.get('ok') else '❌'}</td>"
+            f"<td>{rebuilt}</td>"
+            f"<td>{q.get('errors', '-')}/{q.get('warnings', '-')}</td>"
+            f"<td>{t.get('passed', '-')}/{t.get('total', '-')}</td>"
+            f"<td>{item.get('duration_ms', '-')} ms</td>"
+            "</tr>"
+        )
+    timeline = (
+        "<table><tr><th>时间</th><th>健康</th><th>重建</th><th>质量 错/警</th>"
+        "<th>自测</th><th>耗时</th></tr>" + "".join(rows) + "</table>"
+        if rows else '<div class="empty">还没有巡检记录。运行一次 mcai autopilot --once。</div>'
+    )
+
+    # 变更日志
+    change_rows = []
+    for entry in reversed(changelog[-10:]):
+        parts = []
+        if entry.get("added"):
+            parts.append("+ " + "、".join(entry["added"][:5]))
+        if entry.get("removed"):
+            parts.append("− " + "、".join(entry["removed"][:5]))
+        if entry.get("changed"):
+            parts.append("~ " + "、".join(entry["changed"][:5]))
+        change_rows.append(
+            f"<tr><td>{html.escape(str(entry.get('ts', '')))}</td>"
+            f"<td>{html.escape('；'.join(parts) or '（无术语变化）')}</td></tr>"
+        )
+    changelog_html = (
+        "<table><tr><th>时间</th><th>变化</th></tr>" + "".join(change_rows) + "</table>"
+        if change_rows else '<div class="empty">还没有术语变更记录。</div>'
+    )
+
+    # 质量明细
+    issues = (quality.get("errors") or []) + (quality.get("warnings") or [])
+    issue_rows = "".join(
+        f"<tr><td>{html.escape(i.get('level', ''))}</td>"
+        f"<td>{html.escape(i.get('code', ''))}</td>"
+        f"<td>{html.escape(i.get('detail', ''))}</td></tr>"
+        for i in issues[:20]
+    )
+    issues_html = (
+        "<table><tr><th>级别</th><th>代码</th><th>说明</th></tr>" + issue_rows + "</table>"
+        if issue_rows else '<div class="empty">本轮没有错误或警告。提示项只在 quality.json 里。</div>'
+    )
+
+    top_questions = "".join(
+        "<tr><td>{}</td><td>{}</td><td>{}</td></tr>".format(
+            html.escape(redact(q.get("question", ""))),
+            q.get("count", 0),
+            html.escape("、".join(c.get("client", "") for c in q.get("clients", [])) or "(未记录)")
+            + ("　<b>外部</b>" if q.get("external") else ""),
+        )
+        for q in tele.get("top_questions", [])[:10]
+    ) or '<tr><td colspan="3" class="empty">暂无业务问答</td></tr>'
+
+    html_doc = f"""<!DOCTYPE html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>本地观测台 · 元意识知识库</title>
+<style>{CSS}</style></head>
+<body><div class="wrap">
+  <div class="nav muted"><a href="/index.html">知识库</a><a href="/dashboard.html">观测台</a>
+  <a href="/dataset/index.html">数据集</a><a href="/guide.md">接入指南</a></div>
+  <h1>本地观测台 {badge}</h1>
+  <div class="muted">最近一次检查：{html.escape(str(status.get('checked_at', '尚未运行')))} ·
+  服务：{'在线' if status.get('server_ok') else '离线'} ·
+  本轮重建：{'是' if status.get('rebuilt') else '否'}</div>
+
+  <div class="cards">{cards_html}</div>
+
+  <h2>调用趋势（近 14 天）</h2>
+  {_bars(tele.get('by_day', {}))}
+  <div class="muted" style="margin-top:10px">
+    健康探测 {tele.get('probes', 0)} 次 ·
+    本机 {(tele.get('by_origin') or {}).get('local', 0)} ·
+    外部 {(tele.get('by_origin') or {}).get('external', 0)} ·
+    未标记 {(tele.get('by_origin') or {}).get('unknown', 0)}<br>
+    渠道：{html.escape(str(tele.get('by_channel', {})))} ·
+    类型：{html.escape(str(tele.get('by_type', {})))}
+  </div>
+
+  <h2>巡检时间线</h2>
+  {timeline}
+
+  <h2>质量明细</h2>
+  {issues_html}
+
+  <h2>术语变更</h2>
+  {changelog_html}
+
+  <h2>高频问题（仅业务问答，不含健康探测）</h2>
+  <table><tr><th>问题</th><th>次数</th><th>来源</th></tr>{top_questions}</table>
+
+  <p class="muted" style="margin-top:40px">
+    本页由自动驾驶在每次检查后重新生成 · {datetime.now().astimezone().isoformat(timespec='seconds')}
+  </p>
+</div></body></html>"""
+
+    out = dist / "dashboard.html"
+    out.write_text(html_doc, encoding="utf-8")
+    return out

mcai/dataset.py

@@ -0,0 +1,203 @@
+"""数据集导出：JSONL / CSV / 知识图谱 / 数据集卡片。"""
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+
+from .extract import KnowledgeBase
+
+SYSTEM_PROMPT = (
+    "你是「元意识学说」的知识助手。回答时严格使用学说自身的术语体系："
+    "元意识、元态能量、观测创造实在、现象时空、序生、序生智能体、元识、元知、元灵、元子。"
+    "不把学说混同于量子神秘主义或既有哲学流派，不使用未在术语集中定义的表述。"
+)
+
+
+def _write_jsonl(path: Path, rows: list[dict]) -> None:
+    with path.open("w", encoding="utf-8") as fh:
+        for row in rows:
+            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+
+def export(kb: KnowledgeBase, out_dir: str | Path) -> dict:
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    concepts = [
+        {
+            "id": c.id,
+            "term": c.term,
+            "slug": c.slug,
+            "en": c.en,
+            "aliases": c.aliases,
+            "category": c.category,
+            "kind": c.kind,
+            "parent": c.parent,
+            "definition": c.definition,
+            "short_definition": c.short_definition,
+            "source_documents": sorted({s.doc_title for s in c.sources}),
+            "evidence": [
+                {"doc": e["doc_title"], "section": e["section"], "quote": e["quote"], "lang": e["lang"]}
+                for e in c.evidence[:4]
+            ],
+            "status": c.status,
+        }
+        for c in kb.concepts
+    ]
+    _write_jsonl(out / "concepts.jsonl", concepts)
+
+    evidence_rows = [
+        {
+            "term": c.term,
+            "slug": c.slug,
+            "category": c.category,
+            "doc": e["doc_title"],
+            "section": e["section"],
+            "quote": e["quote"],
+            "lang": e["lang"],
+        }
+        for c in kb.concepts
+        for e in c.evidence
+    ]
+    _write_jsonl(out / "evidence.jsonl", evidence_rows)
+
+    faqs = [
+        {
+            "id": f.id,
+            "question": f.question,
+            "answer": f.answer,
+            "short_answer": f.short_answer,
+            "kind": f.kind,
+            "related": f.related,
+            "source_terms": f.source_terms,
+            "confidence": f.confidence,
+            "campaign": f.campaign,
+        }
+        for f in kb.faqs
+    ]
+    _write_jsonl(out / "faq.jsonl", faqs)
+
+    sft = [
+        {
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": f.question},
+                {"role": "assistant", "content": f.answer},
+            ],
+            "metadata": {"faq_id": f.id, "kind": f.kind, "confidence": f.confidence},
+        }
+        for f in kb.faqs
+    ]
+    _write_jsonl(out / "sft.jsonl", sft)
+
+    with (out / "concepts.csv").open("w", encoding="utf-8-sig", newline="") as fh:
+        writer = csv.writer(fh)
+        writer.writerow(["id", "term", "en", "aliases", "category", "definition", "status", "sources"])
+        for c in kb.concepts:
+            writer.writerow([
+                c.id, c.term, c.en, "|".join(c.aliases), c.category,
+                c.definition, c.status, "|".join(sorted({s.doc_title for s in c.sources})),
+            ])
+
+    nodes = [
+        {"id": c.slug, "label": c.term, "category": c.category, "definition": c.short_definition}
+        for c in kb.concepts
+    ]
+    edges = [
+        {"source": c.slug, "target": r["target_id"], "type": r["type"], "evidence": r.get("evidence", "")}
+        for c in kb.concepts
+        for r in c.relations
+        if r.get("target_id")
+    ]
+    graph = {"nodes": nodes, "edges": edges, "meta": {"nodes": len(nodes), "edges": len(edges)}}
+    (out / "knowledge-graph.json").write_text(
+        json.dumps(graph, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+    (out / "dataset-card.md").write_text(_card(kb), encoding="utf-8")
+    return {
+        "dir": str(out),
+        "files": sorted(p.name for p in out.iterdir() if p.is_file()),
+        "concepts": len(concepts),
+        "faqs": len(faqs),
+        "evidence": len(evidence_rows),
+        "edges": len(edges),
+    }
+
+
+def _card(kb: KnowledgeBase) -> str:
+    project = kb.project
+    cats = "\n".join(f"- {name}：{count} 条" for name, count in kb.stats["categories"].items())
+    docs = "\n".join(
+        f"- 《{d['title']}》（{d['kind']}，{d['blocks']} 段）" for d in kb.documents
+    )
+    return f"""# {project['brand']}学说结构化语料库 v1.0
+
+## 数据集简介
+
+本数据集把《{project['brand']}》学说的多份原始文本（术语词源、学说极简版、本体论、元子社会等）
+转换为机器可直接引用的结构化知识资产，用于大模型知识对齐、RAG 检索、知识图谱构建与
+「知识资产数字永生」工程。
+
+- 概念定义：{kb.stats['concepts']} 条
+- 标准问答：{kb.stats['faqs']} 组
+- 概念关系：{kb.stats['relations']} 条
+- 文献引证：{kb.stats.get('evidence', 0)} 条
+- 语料来源：{len(kb.documents)} 份文档 / {kb.stats['blocks']} 个段落 / 约 {kb.stats['characters']:,} 字
+- 构建时间：{kb.built_at}
+- 许可：{project['license']}
+
+## 目录结构
+
+```
+concepts.jsonl          概念定义（一条一行）
+faq.jsonl               标准问答
+evidence.jsonl          文献引证（概念在各著作中的论述原句）
+sft.jsonl               对话微调格式（system/user/assistant）
+concepts.csv            表格版，便于运营审阅
+knowledge-graph.json    节点-边知识图谱
+dataset-card.md         本文件
+```
+
+## 字段说明
+
+### concepts.jsonl
+
+| 字段 | 含义 |
+|---|---|
+| id / slug | 唯一标识与 URL 片段 |
+| term | 规范术语名 |
+| en | 英文对应词 |
+| aliases | 别名、曾用名、英文缩写 |
+| category | 所属体系（元意识体系 / 本体论模型 / 序生体系 / 元子社会） |
+| definition | 主分支定义（已去重、去冲突） |
+| short_definition | 一句话定义 |
+| source_documents | 定义来源文档 |
+| status | ok / conflict / thin，表示质量状态 |
+
+### sft.jsonl
+
+直接用于指令微调，system 提示词已锁定术语边界，避免模型把学说混同于其他体系。
+
+## 概念分布
+
+{cats}
+
+## 语料来源
+
+{docs}
+
+## 使用建议
+
+1. **RAG**：以 `concepts.jsonl` 建立向量库，检索后把 `definition` 作为上下文注入。
+2. **微调**：`sft.jsonl` 可直接用于 LoRA/全参微调；建议与通用语料按 1:4 混合以防灾难性遗忘。
+3. **知识图谱**：`knowledge-graph.json` 可导入 Neo4j / NetworkX，用于多跳问答与概念推荐。
+4. **一致性约束**：`status=conflict` 的条目须先人工裁定后再进入训练集。
+
+## 引用
+
+```
+{project['org']}. {project['brand']}学说结构化语料库 v1.0. {kb.built_at[:10]}.
+```
+"""