master-skill 0.10.1 → 0.12.0

package/skill-catalog.json

@@ -6,133 +6,196 @@
       "kind": "persona",
       "source": "prebuilt/master-nagarjuna",
       "install_dir": "master-nagarjuna",
-      "aliases": ["nagarjuna", "master-nagarjuna"]
+      "aliases": [
+        "nagarjuna",
+        "master-nagarjuna"
+      ]
     },
     {
       "name": "master-xuanzang",
       "kind": "persona",
       "source": "prebuilt/master-xuanzang",
       "install_dir": "master-xuanzang",
-      "aliases": ["xuanzang", "master-xuanzang"]
+      "aliases": [
+        "xuanzang",
+        "master-xuanzang"
+      ]
     },
     {
       "name": "master-kumarajiva",
       "kind": "persona",
       "source": "prebuilt/master-kumarajiva",
       "install_dir": "master-kumarajiva",
-      "aliases": ["kumarajiva", "master-kumarajiva"]
+      "aliases": [
+        "kumarajiva",
+        "master-kumarajiva"
+      ]
     },
     {
       "name": "master-huineng",
       "kind": "persona",
       "source": "prebuilt/master-huineng",
       "install_dir": "master-huineng",
-      "aliases": ["huineng", "master-huineng"]
+      "aliases": [
+        "huineng",
+        "master-huineng"
+      ]
     },
     {
       "name": "master-zhiyi",
       "kind": "persona",
       "source": "prebuilt/master-zhiyi",
       "install_dir": "master-zhiyi",
-      "aliases": ["zhiyi", "master-zhiyi"]
+      "aliases": [
+        "zhiyi",
+        "master-zhiyi"
+      ]
     },
     {
       "name": "master-fazang",
       "kind": "persona",
       "source": "prebuilt/master-fazang",
       "install_dir": "master-fazang",
-      "aliases": ["fazang", "master-fazang"]
+      "aliases": [
+        "fazang",
+        "master-fazang"
+      ]
     },
     {
       "name": "master-yinguang",
       "kind": "persona",
       "source": "prebuilt/master-yinguang",
       "install_dir": "master-yinguang",
-      "aliases": ["yinguang", "master-yinguang"]
+      "aliases": [
+        "yinguang",
+        "master-yinguang"
+      ]
     },
     {
       "name": "master-ouyi",
       "kind": "persona",
       "source": "prebuilt/master-ouyi",
       "install_dir": "master-ouyi",
-      "aliases": ["ouyi", "master-ouyi"]
+      "aliases": [
+        "ouyi",
+        "master-ouyi"
+      ]
     },
     {
       "name": "master-xuyun",
       "kind": "persona",
       "source": "prebuilt/master-xuyun",
       "install_dir": "master-xuyun",
-      "aliases": ["xuyun", "master-xuyun"]
+      "aliases": [
+        "xuyun",
+        "master-xuyun"
+      ]
     },
     {
       "name": "master-atisha",
       "kind": "persona",
       "source": "prebuilt/master-atisha",
       "install_dir": "master-atisha",
-      "aliases": ["atisha", "master-atisha"]
+      "aliases": [
+        "atisha",
+        "master-atisha"
+      ]
     },
     {
       "name": "master-tsongkhapa",
       "kind": "persona",
       "source": "prebuilt/master-tsongkhapa",
       "install_dir": "master-tsongkhapa",
-      "aliases": ["tsongkhapa", "master-tsongkhapa"]
+      "aliases": [
+        "tsongkhapa",
+        "master-tsongkhapa"
+      ]
     },
     {
       "name": "master-milarepa",
       "kind": "persona",
       "source": "prebuilt/master-milarepa",
       "install_dir": "master-milarepa",
-      "aliases": ["milarepa", "master-milarepa"]
+      "aliases": [
+        "milarepa",
+        "master-milarepa"
+      ]
     },
     {
       "name": "master-buddhaghosa",
       "kind": "persona",
       "source": "prebuilt/master-buddhaghosa",
       "install_dir": "master-buddhaghosa",
-      "aliases": ["buddhaghosa", "master-buddhaghosa"]
+      "aliases": [
+        "buddhaghosa",
+        "master-buddhaghosa"
+      ]
     },
     {
       "name": "master-mahasi-sayadaw",
       "kind": "persona",
       "source": "prebuilt/master-mahasi-sayadaw",
       "install_dir": "master-mahasi-sayadaw",
-      "aliases": ["mahasi-sayadaw", "master-mahasi-sayadaw"]
+      "aliases": [
+        "mahasi-sayadaw",
+        "master-mahasi-sayadaw"
+      ]
     },
     {
       "name": "master-ajahn-chah",
       "kind": "persona",
       "source": "prebuilt/master-ajahn-chah",
       "install_dir": "master-ajahn-chah",
-      "aliases": ["ajahn-chah", "master-ajahn-chah"]
+      "aliases": [
+        "ajahn-chah",
+        "master-ajahn-chah"
+      ]
     },
     {
       "name": "compare-masters",
       "kind": "teaching-mode",
-      "source": "prebuilt/compare",
+      "source": "prebuilt/compare-masters",
       "install_dir": "compare-masters",
-      "aliases": ["compare-masters"]
+      "aliases": [
+        "compare-masters"
+      ]
     },
     {
       "name": "master-debate",
       "kind": "teaching-mode",
       "source": "prebuilt/master-debate",
       "install_dir": "master-debate",
-      "aliases": ["master-debate"]
+      "aliases": [
+        "master-debate"
+      ]
     },
     {
       "name": "master-curriculum",
       "kind": "teaching-mode",
       "source": "prebuilt/master-curriculum",
       "install_dir": "master-curriculum",
-      "aliases": ["master-curriculum"]
+      "aliases": [
+        "master-curriculum"
+      ]
+    },
+    {
+      "name": "master-help",
+      "kind": "teaching-mode",
+      "source": "prebuilt/master-help",
+      "install_dir": "master-help",
+      "aliases": [
+        "help",
+        "master-help"
+      ]
     },
     {
       "name": "create-master",
       "kind": "generator",
       "source": ".",
       "install_dir": "create-master",
-      "aliases": ["create-master"],
+      "aliases": [
+        "create-master"
+      ],
       "bundle_paths": [
         "SKILL.md",
         "tools",

package/tools/cross_reference.py

@@ -9,6 +9,7 @@ Usage:
 
 import argparse
 import json
+import re
 import os
 import sys
 from pathlib import Path
@@ -18,7 +19,7 @@ from typing import Optional
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(PROJECT_ROOT / "tools"))
 
-from fojin_bridge import FojinBridge, create_bridge
+from fojin_bridge import FojinBridge, FojinConfigError, create_bridge
 
 
 # ── Teacher registry ────────────────────────────────────────────
@@ -26,9 +27,27 @@ from fojin_bridge import FojinBridge, create_bridge
 PREBUILT_DIR = PROJECT_ROOT / "prebuilt"
 
 
+# Slugs reach this module from `--teachers xuanzang,kumarajiva`, split on
+# commas and joined onto PREBUILT_DIR. Without a charset restriction
+# `--teachers ../../../../etc` read a meta.json from anywhere on the machine —
+# verified before this guard existed. Every other entry point in this repo
+# already had one: `_SAFE_MASTER` in scripts/verify_citations.py and
+# scripts/query.py, `isSafeName` in bin/cli.mjs. This file was the gap.
+_SAFE_SLUG = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
 def load_teacher_meta(slug: str) -> dict:
     """Load a teacher's meta.json by slug."""
+    if not _SAFE_SLUG.match(slug):
+        raise ValueError(
+            f"invalid teacher slug: {slug!r} (letters, digits, '-' and '_' only)"
+        )
     meta_path = PREBUILT_DIR / slug / "meta.json"
+    # Resolved and re-checked rather than trusted to the charset alone: the
+    # charset is the rule, this is the assertion that the rule held.
+    resolved = meta_path.resolve()
+    if not resolved.is_relative_to(PREBUILT_DIR.resolve()):
+        raise ValueError(f"teacher slug escapes prebuilt/: {slug!r}")
     if not meta_path.exists():
         raise FileNotFoundError(f"Teacher not found: {slug}")
     with open(meta_path, "r", encoding="utf-8") as f:
@@ -347,16 +366,31 @@ def main():
         parser.print_help()
         return
 
-    bridge = create_bridge()
+    try:
+        bridge = create_bridge()
+    except FojinConfigError as error:
+        # Matches the contract the other entry points keep: a message a person
+        # can act on, and an exit code, instead of a traceback.
+        print(f"[配置错误] {error}", file=sys.stderr)
+        sys.exit(2)
 
-    if args.command == "lineage":
-        output = cmd_lineage(bridge, args.person_a, args.person_b)
-    elif args.command == "concept":
-        teacher_slugs = [s.strip() for s in args.teachers.split(",")]
-        output = cmd_concept(bridge, args.concept, teacher_slugs)
-    else:
-        parser.print_help()
-        return
+    try:
+        if args.command == "lineage":
+            output = cmd_lineage(bridge, args.person_a, args.person_b)
+        elif args.command == "concept":
+            teacher_slugs = [s.strip() for s in args.teachers.split(",")]
+            output = cmd_concept(bridge, args.concept, teacher_slugs)
+        else:
+            parser.print_help()
+            return
+    except ValueError as error:
+        # Raised by load_teacher_meta for a slug outside the allowed charset.
+        # scripts/query.py answers the same mistake the same way, exit 2.
+        print(f"{error}", file=sys.stderr)
+        sys.exit(2)
+    except FileNotFoundError as error:
+        print(f"{error}", file=sys.stderr)
+        sys.exit(1)
 
     print(output)
 

package/tools/fojin-known-absent.json

@@ -0,0 +1,14 @@
+{
+  "_comment": "FoJin 确认不收录的 CBETA id。每条都必须写明理由与核验日期。verify_sources.py 用它把周检的『Not found』分成『已知缺失』与『新出现的缺失』——前者不再每周开 issue，后者照常。清单本身也会失效：列在这里的 id 若哪天在 FoJin 查得到，同样报告并要求删除该条，所以它不会悄悄烂掉。",
+  "absent": [
+    {
+      "cbeta_id": "J36nB348",
+      "short_cbeta_id": "JB348",
+      "title": "灵峰宗论",
+      "used_by": ["master-ouyi"],
+      "reason": "嘉兴藏（J）不在 FoJin 的收录范围内。2026-09-13 以 tools/fojin_bridge.py 直接查证：lookup-cbeta 对 'JB348' 与 'J36nB348' 均返回 {}，而同一次请求里的 'T0235' 正常解析为 text_id=7 —— 是缺这部书，不是接口不通。",
+      "verified_absent_on": "2026-09-13",
+      "consequence": "master-ouyi 引用《灵峰宗论》时拿不到 fojin.app 活链接。离线审计不受影响：J36nB348 在 meta.json 里已声明，verify_citations.py 照常解析。"
+    }
+  ]
+}

package/tools/fojin_bridge.py

@@ -1,30 +1,101 @@
 """
 FoJin Data Bridge — connects Master-skill to FoJin's Buddhist text platform.
 
-Two modes:
-- API mode (default): calls fojin.app REST API, works for any user
-- Local mode: direct database access, for FoJin developers only
+Every call goes through the fojin.app REST API. The `mode` argument (and
+`FOJIN_MODE`) is accepted but inert: the "local mode: direct database access"
+this docstring advertised for two years was never implemented, and describing
+an unwritten feature as a shipped one is its own kind of unverified claim.
 """
 
+from __future__ import annotations
+
 import json
 import logging
 import os
+import time
 from typing import Optional
+from urllib.parse import urlparse
 
 import requests
 
+# A response this big is a broken endpoint or a hostile one, never a real
+# search result — the largest legitimate payload observed is a full juan at
+# well under 2 MB. Without a cap, `resp.json()` reads the whole body into
+# memory first, so a wedged or redirected host can take the process out.
+MAX_RESPONSE_BYTES = 16 * 1024 * 1024
+
+# (connect, read). One scalar timeout applies the same value to both, so a
+# host that accepts the connection and then says nothing held the old code for
+# the full 30s. Connecting is either fast or not happening.
+DEFAULT_TIMEOUT = (5, 30)
+
+# Wall clock for a whole streamed body. `stream=True` applies the read timeout
+# to each chunk, not to the transfer, so a slow drip never trips it.
+READ_DEADLINE = 60.0
+
 
 class FojinUnavailableError(Exception):
     """Raised when FoJin API is unreachable. Callers should handle gracefully."""
     pass
 
 
+class FojinConfigError(ValueError):
+    """Raised when FOJIN_URL is not a usable https base URL."""
+    pass
+
+
+def _validate_base_url(url: str) -> str:
+    """Reject a base URL that is not plain https.
+
+    FOJIN_URL is read from the environment and every request is built on top of
+    it, so it decides where citations are verified against. Allowing `http://`
+    or a `file://`-ish scheme through would silently downgrade or redirect that
+    check.
+
+    Two deliberate exits from that rule:
+
+      - `http://localhost` (and 127.0.0.1 / ::1) is always allowed; the traffic
+        never leaves the machine.
+      - `FOJIN_ALLOW_INSECURE_URL=1` allows any http host, for someone running
+        FoJin on a LAN or inside a container network. It is opt-in because the
+        default has to be the safe one, and because self-hosting is not
+        documented anywhere in this repo — an earlier version of this docstring
+        claimed references/fojin-api.md covered the local path; that file does
+        not mention it at all.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme == "https":
+        return url.rstrip("/")
+    if parsed.scheme == "http":
+        if parsed.hostname in ("localhost", "127.0.0.1", "::1"):
+            return url.rstrip("/")
+        if os.environ.get("FOJIN_ALLOW_INSECURE_URL") == "1":
+            logging.getLogger(__name__).warning(
+                "FOJIN_URL is plain http (%s); citations will be verified over "
+                "an unauthenticated connection", url
+            )
+            return url.rstrip("/")
+    raise FojinConfigError(
+        f"FOJIN_URL must be https: {url!r}. http is allowed on localhost, or "
+        "anywhere if you set FOJIN_ALLOW_INSECURE_URL=1 deliberately."
+    )
+
+
 class FojinBridge:
     """Bridge to FoJin Buddhist text platform."""
 
     def __init__(self, mode: str = "api", base_url: str = "https://fojin.app"):
-        self.mode = mode
-        self.base_url = base_url.rstrip("/")
+        # `mode` has never done anything: the docstring's "local mode: direct
+        # database access" was never implemented, and every call goes through
+        # the REST path regardless. Kept as an accepted argument so existing
+        # callers and FOJIN_MODE=… do not break, but it is now recorded as
+        # inert rather than left looking like a feature.
+        if mode not in ("api", ""):
+            logging.getLogger(__name__).warning(
+                "FojinBridge mode=%r is not implemented; using the REST API", mode
+            )
+        self.mode = "api"
+        self.base_url = _validate_base_url(base_url)
         self.session = requests.Session()
         self.session.headers.update({"Accept": "application/json"})
 
@@ -121,14 +192,70 @@ class FojinBridge:
             requests.HTTPError: On 4xx/5xx responses
         """
         url = f"{self.base_url}{path}"
+        resp = None
         try:
-            resp = self.session.get(url, params=params, timeout=30)
+            # stream=True so the body is not pulled into memory before its
+            # size can be checked.
+            resp = self.session.get(
+                url, params=params, timeout=DEFAULT_TIMEOUT, stream=True
+            )
             resp.raise_for_status()
-            return resp.json()
+            body = self._read_capped(resp)
         except requests.ConnectionError as e:
             raise FojinUnavailableError(f"FoJin API unreachable: {e}") from e
         except requests.Timeout as e:
             raise FojinUnavailableError(f"FoJin API timeout: {e}") from e
+        finally:
+            # A streamed response holds its connection until closed.
+            if resp is not None:
+                resp.close()
+        return json.loads(body)
+
+    @staticmethod
+    def _read_capped(resp, deadline: float | None = None) -> bytearray:
+        """Read a response body, refusing one that is too large or too slow.
+
+        The size is checked while reading rather than from Content-Length,
+        which a hostile or merely chunked response need not send truthfully.
+
+        Two things the first version missed:
+
+        - it accumulated a list of chunks and then `b"".join`ed them, so at the
+          16 MB cap the peak was ~32 MB — the copy defeats part of the point of
+          capping at all. A single bytearray grows in place.
+        - `stream=True` moves the read timeout to *per chunk*, so a sender
+          dripping one byte inside every read window could hold the connection
+          indefinitely without ever tripping the size cap. A wall-clock
+          deadline closes that.
+        """
+        budget = READ_DEADLINE if deadline is None else None
+        limit = time.monotonic() + READ_DEADLINE if deadline is None else deadline
+        body = bytearray()
+        for chunk in resp.iter_content(64 * 1024):
+            body += chunk
+            if len(body) > MAX_RESPONSE_BYTES:
+                raise FojinUnavailableError(
+                    f"FoJin API response exceeded {MAX_RESPONSE_BYTES} bytes; "
+                    "refusing to buffer it"
+                )
+            if time.monotonic() > limit:
+                # Reports the deadline actually in force. The first version
+                # interpolated the module constant regardless of what the
+                # caller passed, so a 0.05s deadline announced itself as 60s —
+                # and the test asserting on that message locked the lie in.
+                howlong = (
+                    f"{budget}s" if budget is not None else "the caller's deadline"
+                )
+                raise FojinUnavailableError(
+                    f"FoJin API response took longer than {howlong} to arrive; "
+                    "abandoning it"
+                )
+        # The bytearray IS the return value. `bytes(body)` was a second full
+        # copy — precisely the allocation `b"".join` used to make — and
+        # measured *worse* than the code it replaced: 33.64 MB peak against
+        # 32.03 MB, for a 16 MB body. `json.loads` accepts a bytearray, so the
+        # copy bought nothing at all.
+        return body
 
     def test_connection(self) -> bool:
         """Test if FoJin API is reachable."""
@@ -140,7 +267,10 @@ class FojinBridge:
 
 
 def create_bridge() -> FojinBridge:
-    """Create a FojinBridge from environment variables."""
+    """Create a FojinBridge from environment variables.
+
+    Raises FojinConfigError if FOJIN_URL is not a usable https base URL.
+    """
     mode = os.environ.get("FOJIN_MODE", "api")
     url = os.environ.get("FOJIN_URL", "https://fojin.app")
     return FojinBridge(mode=mode, base_url=url)

package/tools/rag_query.py

@@ -17,7 +17,7 @@ import os
 # Ensure tools/ is on the path so we can import fojin_bridge
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-from fojin_bridge import create_bridge, FojinUnavailableError
+from fojin_bridge import create_bridge, FojinConfigError, FojinUnavailableError
 
 
 def source_identity(item: dict) -> tuple[str, str]:
@@ -243,14 +243,37 @@ _CONTROL_CHARS = re.compile(
 )
 
 
+# Everything this tool prints lands in an agent's context window, and the
+# formatters cap each snippet but not how many there are — they render whatever
+# `items` the endpoint returned. Asking for `--top_k 5` and being handed 10,000
+# produced 6.4 million characters in a measurement, from a service this repo
+# does not control and whose data is enriched from third-party editable sources.
+#
+# The cap lives here rather than in each formatter because `emit` is the single
+# place all four commands pass through: a formatter added later cannot route
+# around it. Truncation is announced, so a short answer is never mistaken for a
+# complete one.
+MAX_EMIT_CHARS = 60_000
+
+
 def emit(body: str) -> None:
     """Print a retrieval result wrapped in a data boundary, with control chars
-    and any forged boundary lines stripped so the fence can't be broken out of."""
+    and any forged boundary lines stripped so the fence can't be broken out of,
+    and the whole thing capped so it cannot flood the caller's context."""
     cleaned = _CONTROL_CHARS.sub("", body or "")
     # Loop until stable — a single replace pass is defeatable by overlapping
     # boundary lines that rejoin into a fresh marker after the inner one is cut.
     while _EMIT_HEADER in cleaned or _EMIT_FOOTER in cleaned:
         cleaned = cleaned.replace(_EMIT_HEADER, "").replace(_EMIT_FOOTER, "")
+    if len(cleaned) > MAX_EMIT_CHARS:
+        # Truncated AFTER the boundary strip, so the cut cannot leave a partial
+        # marker behind that the next pass would not see.
+        dropped = len(cleaned) - MAX_EMIT_CHARS
+        cleaned = (
+            cleaned[:MAX_EMIT_CHARS]
+            + f"\n[已截断:检索结果超过 {MAX_EMIT_CHARS} 字符,省略 {dropped} 字符。"
+            "这不是完整结果 —— 缩小查询范围或降低 --top_k 后重试。]"
+        )
     print(f"{_EMIT_HEADER}\n{cleaned}\n{_EMIT_FOOTER}")
 
 
@@ -316,8 +339,28 @@ def main():
 
     try:
         args.func(args)
+    except FojinConfigError as e:
+        # A misconfigured FOJIN_URL is not the same as FoJin being down, but it
+        # reaches the agent the same way: no retrieval. Routing it through the
+        # documented degradation contract (the marker on stdout, exit 0 — see
+        # prompts/rag_instructions.md §50) keeps a self-hoster's typo from
+        # blowing up a `set -e` pipeline the agent wrote, while the operator
+        # gets the actionable reason on stderr.
+        print("[FoJin API 当前不可用]")
+        print("配置有误,未发起检索。法师将仅基于预置 teaching.md 回答。")
+        print(f"[配置错误] {e}", file=sys.stderr)
+        sys.exit(0)
     except FojinUnavailableError:
+        # exit 0 是**故意**的,不是本仓一直在修的那个「假绿」形状 ——
+        # 这里的调用方是读 stdout 的 agent,不是读退出码的脚本:
+        # prompts/rag_instructions.md §50 规定它按 "[FoJin API 当前不可用]"
+        # 这行字判断降级。非零退出会让 agent 顺手写的 `set -e` 管道整条炸掉,
+        # 换来的是它本来就不看的一个信号。
+        # 同一行同时写到 stderr,好让确实在看退出状态的脚本至少能在日志里
+        # 分辨「检索不到」与「检索成功」。契约由
+        # tests/test_rag_query.py::test_unavailable_* 钉住。
         print("[FoJin API 当前不可用]")
+        print("[FoJin API 当前不可用] 无检索结果,输出仅来自预置内容", file=sys.stderr)
         print("无法检索真实经文。法师将仅基于预置 teaching.md 回答。")
         print("建议：")
         print("- 稍后重试")