master-skill 0.10.0 → 0.11.0

package/tools/skill_writer.py

@@ -0,0 +1,230 @@
+"""
+Skill Writer — creates and updates teacher skill directories.
+Adapted from colleague-skill's skill_writer.py for Buddhist master context.
+"""
+
+import json
+import os
+import re
+import shutil
+from datetime import datetime
+from typing import Optional
+
+try:
+    from pypinyin import lazy_pinyin, Style
+    HAS_PYPINYIN = True
+except ImportError:
+    HAS_PYPINYIN = False
+
+
+# Generated teaching/voice content is LLM output derived from external FoJin
+# data. Before it is written into SKILL.md (which the agent later loads and
+# follows as instructions) strip C0/C1 control chars except \n and \t: ANSI
+# escapes / NULs serve no purpose in Buddhist-text markdown and could be used
+# to hide content or spoof a terminal. Defense-in-depth alongside the prompt-
+# level injection guards (prompts/sutra_analyzer.md, rag_instructions.md).
+_CONTROL_CHARS = re.compile(
+    r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f"
+    r"\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]"
+)
+
+REQUIRED_CITATION_CLAIMS = [
+    "doctrinal_claim",
+    "practice_guidance",
+    "text_interpretation",
+]
+
+
+def sanitize_generated(content: str) -> str:
+    """Strip control characters from generated content before persisting."""
+    if not content:
+        return content
+    return _CONTROL_CHARS.sub("", content)
+
+
+def derive_citation_contract(sources: list[dict]) -> dict:
+    """Build the exact version-1 contract for a non-empty source manifest."""
+    if not isinstance(sources, list) or not sources:
+        raise ValueError("sources must be a non-empty list")
+
+    source_types: list[str] = []
+    for index, source in enumerate(sources):
+        source_type = source.get("type") if isinstance(source, dict) else None
+        if not isinstance(source_type, str) or not source_type.strip():
+            raise ValueError(
+                f"sources[{index}].type must be a non-empty string"
+            )
+        source_types.append(source_type)
+
+    return {
+        "version": 1,
+        "claim_policy": "declared_sources_only",
+        "required_for": list(REQUIRED_CITATION_CLAIMS),
+        "allowed_source_types": sorted(set(source_types)),
+        "minimum_claim_coverage": 0.9,
+        "live_retrieval_allowed": True,
+    }
+
+
+SKILL_MD_TEMPLATE = """---
+name: master-{slug}
+description: 依据{name}（{tradition}{school}）的教学风格与教义体系
+user-invocable: true
+---
+
+# {name}
+
+{disclaimer}
+
+---
+
+## PART A — 教义体系
+
+{teaching_content}
+
+## PART B — 说法风格
+
+{voice_content}
+
+## 运行规则
+
+1. 收到提问后，先依据 voice.md Layer 0 硬规则检查
+2. 依据 voice.md Layer 1-3 确定回答的风格和方式
+3. 依据 teaching.md 检索相关教义内容
+4. 以该法师的风格组织回答
+5. 教义断言、修行指导、文本解释必须引用 `meta.json.sources[]` 中的 `source_id`，且来源类型须列于 `citation_contract.allowed_source_types`
+6. live 结果只有在返回的来源类型与标识可解析到上述声明来源时才可引用；否则剥离相关断言
+7. 遇到超出范围的问题，坦诚说明并建议查阅相关传承
+"""
+
+DISCLAIMER = "本内容依据历史佛教文献生成，仅供参考学习。如需正式修行指导，请亲近善知识。所有回答均须附 persona 已声明且可核验的来源。"
+
+
+def slugify(name: str) -> str:
+    """Convert teacher name to URL-safe slug."""
+    if HAS_PYPINYIN:
+        pinyin_list = lazy_pinyin(name, style=Style.NORMAL)
+        slug = "-".join(pinyin_list)
+    else:
+        slug = name
+    slug = slug.lower().replace(" ", "-")
+    slug = "".join(c for c in slug if c.isalnum() or c == "-")
+    slug = slug.strip("-")
+    return slug
+
+
+def create_teacher(
+    base_dir: str,
+    name: str,
+    tradition: str,
+    school: str,
+    era: str,
+    languages: list,
+    teaching_content: str,
+    voice_content: str,
+    fojin_entity_id: Optional[str] = None,
+    sources: Optional[list] = None,
+    citation_contract: Optional[dict] = None,
+) -> str:
+    """Create a new teacher skill directory."""
+    source_manifest = sources if sources is not None else []
+    expected_contract = derive_citation_contract(source_manifest)
+    if citation_contract is None:
+        citation_contract = expected_contract
+    elif citation_contract != expected_contract:
+        raise ValueError(
+            "citation_contract must equal the contract derived from sources[].type"
+        )
+
+    teaching_content = sanitize_generated(teaching_content)
+    voice_content = sanitize_generated(voice_content)
+    slug = slugify(name)
+    teacher_dir = os.path.join(base_dir, f"master-{slug}")
+    os.makedirs(teacher_dir, exist_ok=True)
+    os.makedirs(os.path.join(teacher_dir, "versions"), exist_ok=True)
+
+    with open(os.path.join(teacher_dir, "teaching.md"), "w", encoding="utf-8") as f:
+        f.write(teaching_content)
+
+    with open(os.path.join(teacher_dir, "voice.md"), "w", encoding="utf-8") as f:
+        f.write(voice_content)
+
+    skill_content = SKILL_MD_TEMPLATE.format(
+        slug=slug, name=name, tradition=tradition, school=school,
+        disclaimer=DISCLAIMER, teaching_content=teaching_content,
+        voice_content=voice_content,
+    )
+    with open(os.path.join(teacher_dir, "SKILL.md"), "w", encoding="utf-8") as f:
+        f.write(skill_content)
+
+    meta = {
+        "name": name, "slug": slug, "tradition": tradition, "school": school,
+        "era": era, "languages": languages, "fojin_entity_id": fojin_entity_id,
+        "sources": source_manifest, "citation_contract": citation_contract,
+        "version": "1.0.0",
+        "created_at": datetime.now().strftime("%Y-%m-%d"),
+        "updated_at": datetime.now().strftime("%Y-%m-%d"),
+        "disclaimer": DISCLAIMER,
+    }
+    with open(os.path.join(teacher_dir, "meta.json"), "w", encoding="utf-8") as f:
+        json.dump(meta, f, ensure_ascii=False, indent=2)
+
+    return teacher_dir
+
+
+def update_teacher(teacher_dir: str, teaching_patch: Optional[str] = None, voice_patch: Optional[str] = None) -> str:
+    """Update an existing teacher skill with new content. Archives current version before updating."""
+    meta_path = os.path.join(teacher_dir, "meta.json")
+    with open(meta_path, "r", encoding="utf-8") as f:
+        meta = json.load(f)
+
+    version = meta.get("version", "1.0.0")
+    version_dir = os.path.join(teacher_dir, "versions", f"v{version}")
+    os.makedirs(version_dir, exist_ok=True)
+    for fname in ["SKILL.md", "teaching.md", "voice.md", "meta.json"]:
+        src = os.path.join(teacher_dir, fname)
+        if os.path.exists(src):
+            shutil.copy2(src, version_dir)
+
+    if teaching_patch:
+        with open(os.path.join(teacher_dir, "teaching.md"), "a", encoding="utf-8") as f:
+            f.write("\n\n" + sanitize_generated(teaching_patch))
+
+    if voice_patch:
+        with open(os.path.join(teacher_dir, "voice.md"), "a", encoding="utf-8") as f:
+            f.write("\n\n" + sanitize_generated(voice_patch))
+
+    parts = version.split(".")
+    parts[1] = str(int(parts[1]) + 1)
+    new_version = ".".join(parts)
+
+    meta["version"] = new_version
+    meta["updated_at"] = datetime.now().strftime("%Y-%m-%d")
+    with open(meta_path, "w", encoding="utf-8") as f:
+        json.dump(meta, f, ensure_ascii=False, indent=2)
+
+    teaching_content = open(os.path.join(teacher_dir, "teaching.md"), encoding="utf-8").read()
+    voice_content = open(os.path.join(teacher_dir, "voice.md"), encoding="utf-8").read()
+    skill_content = SKILL_MD_TEMPLATE.format(
+        slug=meta["slug"], name=meta["name"], tradition=meta["tradition"],
+        school=meta["school"], disclaimer=DISCLAIMER,
+        teaching_content=teaching_content, voice_content=voice_content,
+    )
+    with open(os.path.join(teacher_dir, "SKILL.md"), "w", encoding="utf-8") as f:
+        f.write(skill_content)
+
+    return new_version
+
+
+def list_teachers(base_dir: str) -> list:
+    """List all teacher skills in a directory."""
+    teachers = []
+    if not os.path.exists(base_dir):
+        return teachers
+    for entry in sorted(os.listdir(base_dir)):
+        meta_path = os.path.join(base_dir, entry, "meta.json")
+        if os.path.isfile(meta_path):
+            with open(meta_path, "r", encoding="utf-8") as f:
+                meta = json.load(f)
+            teachers.append(meta)
+    return teachers

package/tools/sutra_collector.py

@@ -0,0 +1,237 @@
+"""
+Sutra Collector — gathers Buddhist texts and metadata for a specific teacher.
+
+Orchestrates FoJin Bridge calls to collect:
+1. Teacher's KG entity and relations (lineage, school, texts)
+2. Core texts associated with the teacher
+3. Text content (selected juans)
+4. Dictionary terms related to the teacher's tradition
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Optional
+
+from fojin_bridge import FojinBridge, create_bridge
+from skill_writer import derive_citation_contract
+
+
+def _source_identity_from_text(text: dict) -> tuple[str, str] | None:
+    """Normalize one FoJin text record to the source-neutral identity schema."""
+    source_type = text.get("source_type")
+    source_id = text.get("source_id")
+    if not source_type and text.get("cbeta_id"):
+        source_type = "cbeta"
+        source_id = text["cbeta_id"]
+    if not isinstance(source_type, str) or not isinstance(source_id, str):
+        return None
+    if not source_type.strip() or not source_id.strip():
+        return None
+    return source_type.strip(), source_id.strip()
+
+
+def _declared_sources_from_texts(texts: list[dict]) -> list[dict]:
+    """Extract only canonical source identifiers returned by FoJin."""
+    sources: list[dict] = []
+    seen: set[tuple[str, str]] = set()
+    for text in texts:
+        identity = _source_identity_from_text(text)
+        if identity is None:
+            continue
+        source_type, source_id = identity
+        member = identity
+        if member in seen:
+            continue
+        seen.add(member)
+        sources.append(
+            {
+                "type": source_type,
+                "id": source_id,
+                "title": text.get("title") or text.get("title_zh") or source_id,
+            }
+        )
+    return sources
+
+
+def collect_teacher_data(
+    teacher_name: str,
+    tradition: Optional[str] = None,
+    bridge: Optional[FojinBridge] = None,
+) -> dict:
+    """Collect all available data about a teacher from FoJin."""
+    if bridge is None:
+        bridge = create_bridge()
+
+    result = {
+        "entity": None,
+        "lineage": [],
+        "texts": [],
+        "content_samples": [],
+        "terms": [],
+        "sources": [],
+    }
+
+    # Step 1: Find teacher in KG
+    kg_results = bridge.search_kg_entities(teacher_name, entity_type="person")
+    if kg_results.get("results"):
+        entity = kg_results["results"][0]
+        result["entity"] = entity
+        detail = bridge.get_kg_entity(entity["id"])
+        result["entity"] = detail
+        for rel in detail.get("relations", []):
+            if rel["predicate"] in (
+                "teacher_of", "student_of", "lineage_holder",
+                "transmitted_to", "received_from",
+            ):
+                result["lineage"].append(rel)
+
+    # Step 2: Search for associated texts
+    text_results = bridge.search_texts(teacher_name, size=50)
+    if text_results.get("results"):
+        result["texts"] = text_results["results"]
+        result["sources"] = _declared_sources_from_texts(result["texts"])
+        if result["sources"]:
+            result["citation_contract"] = derive_citation_contract(result["sources"])
+
+    # Step 3: Collect content samples from top texts
+    for text in result["texts"][:5]:
+        text_id = text.get("id")
+        if not text_id:
+            continue
+        try:
+            content = bridge.get_text_content(text_id, juan_num=1)
+            sample = {
+                "text_id": text_id,
+                "title": text.get("title_zh", ""),
+                "content": content.get("content", "")[:3000],
+            }
+            identity = _source_identity_from_text(text)
+            if identity is not None:
+                sample["source_type"], sample["source_id"] = identity
+            result["content_samples"].append(sample)
+        except Exception:
+            continue
+
+    # Step 4: Collect tradition-specific terms
+    if tradition:
+        tradition_terms = {
+            "汉传": ["净土", "禅", "般若", "菩提", "念佛"],
+            "南传": ["vipassana", "satipatthana", "anicca", "dukkha", "anatta"],
+            "藏传": ["菩提道次第", "空性", "菩提心", "止观", "三主要道"],
+        }
+        for term in tradition_terms.get(tradition, []):
+            dict_results = bridge.search_dictionary(term, size=5)
+            if dict_results.get("results"):
+                result["terms"].extend(dict_results["results"])
+
+    return result
+
+
+def collect_specific_texts(
+    cbeta_ids: list,
+    bridge: Optional[FojinBridge] = None,
+) -> list:
+    """Collect full content for specific texts by CBETA ID."""
+    if bridge is None:
+        bridge = create_bridge()
+
+    texts = []
+    id_map = bridge.lookup_cbeta_ids(",".join(cbeta_ids))
+
+    for cbeta_id, text_id in id_map.items():
+        if not text_id:
+            continue
+        text_meta = bridge.get_text(text_id)
+        juan_list = bridge.get_text_juans(text_id)
+
+        text_data = {
+            "cbeta_id": cbeta_id,
+            "text_id": text_id,
+            "title": text_meta.get("title_zh", ""),
+            "juans": [],
+        }
+
+        for juan in juan_list.get("juans", [])[:10]:
+            content = bridge.get_text_content(text_id, juan["juan_num"])
+            text_data["juans"].append({
+                "juan_num": juan["juan_num"],
+                "content": content.get("content", ""),
+            })
+
+        texts.append(text_data)
+
+    return texts
+
+
+def save_collected_data(data: dict, output_path: str) -> str:
+    """Save collected data to JSON file."""
+    parent = os.path.dirname(output_path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+    return os.path.abspath(output_path)
+
+
+def offline_smoke_data(name: str, tradition: str | None) -> dict:
+    """Return deterministic no-network data for installed-runtime smoke tests."""
+    sources = [
+        {
+            "type": "compiled_teaching",
+            "id": "OfflineSmoke:Deterministic",
+            "title": "Deterministic offline smoke source",
+        }
+    ]
+    return {
+        "entity": {
+            "name_zh": name,
+            "entity_type": "person",
+            "description": "deterministic offline smoke",
+        },
+        "tradition": tradition,
+        "lineage": [],
+        "texts": [],
+        "content_samples": [],
+        "terms": [],
+        "sources": sources,
+        "citation_contract": derive_citation_contract(sources),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Collect declared Buddhist source data for create-master"
+    )
+    parser.add_argument("--name", required=True, help="historical teacher name")
+    parser.add_argument("--tradition", default=None, help="汉传 / 藏传 / 南传")
+    parser.add_argument("--output", required=True, help="output JSON manifest")
+    parser.add_argument(
+        "--offline-smoke",
+        action="store_true",
+        help="write deterministic source data without network access",
+    )
+    args = parser.parse_args(argv)
+
+    if args.offline_smoke:
+        data = offline_smoke_data(args.name, args.tradition)
+    else:
+        data = collect_teacher_data(args.name, args.tradition)
+        if not data.get("sources"):
+            print(
+                "ERROR: FoJin returned no canonical declared source identifiers; "
+                "curate sources[] before review",
+                file=sys.stderr,
+            )
+            return 1
+
+    destination = save_collected_data(data, args.output)
+    print(f"collected data written: {destination}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())