pasm-framework 0.3.0__py3-none-any.whl

pasm_framework/scaffold.py

@@ -0,0 +1,292 @@
+"""项目脚手架 —— ``pasm-framework new`` 的实现。
+
+目标：从"读文档 20 分钟"变成"一条命令拿到能跑的项目"。
+生成的内容刻意保持**零第三方依赖**（只依赖 pasm-framework 本身），
+所以 ``pip install pasm-framework`` 之后立刻就能 ``python main.py``。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from .errors import FrameworkError
+
+KINDS = ("app", "chatbot", "game_npc")
+
+_MAIN_APP = '''"""最小 AI 应用 —— pasm-framework 脚手架生成。
+
+跑起来：python main.py            （离线，用内置知识库+模板回复）
+接 LLM：PASM_LLM_API_KEY=sk-xxx PASM_LLM_PROVIDER=deepseek python main.py
+"""
+from pasm_framework import SimpleApplication, capability, load
+
+
+class MyApp(SimpleApplication):
+    """把每个能力写成一个方法，用 @capability 声明触发词。"""
+
+    @capability(keywords=("帮助", "help"), description="显示帮助")
+    def help(self, text):
+        return "我能回答资料库里的问题。试着问我：营业时间 / 怎么退货"
+
+    @capability(keywords=("时间", "几点"), description="营业时间")
+    def hours(self, text):
+        return "我们的营业时间是每天 9:00 - 21:00。"
+
+
+def main():
+    # preset 决定"开哪些插件"：minimal / default / chatbot / api / desktop
+    cfg = load(preset_name="default", knowledge_base={
+        "enabled": True, "config": {"kb_dir": "./kb"}})
+
+    app = MyApp("my-app", {"name": "小智", "role": "智能助手"},
+                backend_config=cfg)
+
+    # 导入你的资料（一次性；之后落盘复用）
+    app.teach([
+        {"title": "退货政策", "content": "签收后 7 天内可无理由退货。",
+         "source": "faq", "tags": ["退货"]},
+    ])
+
+    for q in ["怎么退货？", "你们几点下班？"]:
+        print("我：%s" % q)
+        print("AI：%s" % app.ask(q))
+        print("-" * 40)
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+_MAIN_CHATBOT = '''"""站点智能客服 —— pasm-framework 脚手架生成。
+
+跑起来（控制台）：python main.py
+跑起来（对外服务）：python main.py --serve     → 浏览器打开 http://127.0.0.1:8080/
+嵌入站点：<iframe src="http://你的主机:8080/" width="420" height="620"></iframe>
+
+接 LLM（可选）：PASM_LLM_API_KEY=sk-xxx PASM_LLM_PROVIDER=deepseek python main.py
+"""
+import sys
+
+from pasm_framework import SimpleApplication, load
+
+
+class CustomerService(SimpleApplication):
+    """零 LLM 也能"就资料作答、查不到如实说不知道"。"""
+
+    # 检索不到资料时的话术（面向用户，别写开发提示）
+    DEFAULT_UNKNOWN = "抱歉，我暂时没有查到相关资料。你可以换个说法，或联系人工客服 400-000-0000。"
+
+
+def build():
+    cfg = load(
+        preset_name="chatbot",                 # 护栏收紧 + 开 HTTP 网关
+        knowledge_base={"enabled": True, "config": {"kb_dir": "./kb"}},
+        web_gateway={"enabled": True, "config": {"host": "0.0.0.0", "port": 8080}},
+    )
+    app = CustomerService(
+        "shop-cs", {"name": "小智", "role": "智能客服", "tone": "温暖、专业、耐心"},
+        backend_config=cfg,
+    )
+
+    # ====== 把站点资料喂进来（FAQ / 帮助中心 / 商品说明）======
+    # 真实项目里可以从 CMS/数据库/接口拉，然后调 app.teach(...)
+    app.teach([
+        {"title": "退货政策", "content": "商品签收后 7 天内可无理由退货，需保持吊牌完整。",
+         "source": "faq", "tags": ["退货", "售后"]},
+        {"title": "配送时效", "content": "现货 24 小时内发货，偏远地区 3-5 天送达。",
+         "source": "faq", "tags": ["配送", "物流", "发货"]},
+        {"title": "发票", "content": "下单时可勾选电子发票，次日发送至注册邮箱。",
+         "source": "faq", "tags": ["发票"]},
+        {"title": "营业时间", "content": "客服在线时间 9:00-21:00，节假日不休。",
+         "source": "faq", "tags": ["时间"]},
+    ])
+    return app
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    app = build()
+
+    if "--serve" in argv:
+        print("网关已启动：http://0.0.0.0:8080/  （Ctrl+C 退出）")
+        print("嵌入站点：<iframe src='http://你的主机:8080/' width='420' height='620'></iframe>")
+        try:
+            app.serve()
+            import time
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            app.close()
+        return 0
+
+    for q in ["怎么退货？", "多久能发货？", "你们几点上班？",
+              "能开增值税专用发票吗？", "你们老板是谁？"]:
+        print("客户：%s" % q)
+        print("客服：%s" % app.ask(q, session_id="demo-1"))
+        print("-" * 50)
+    print("资料库统计：%s" % app.plugins.get("knowledge_base").stats())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+'''
+
+_MAIN_NPC = '''"""游戏 NPC —— pasm-framework 脚手架生成（离线、零 LLM）。
+
+PASM 的差异点在"身份"：NPC 有性格 / 情绪 / 记忆 / 会被玩家反馈塑形。
+跑起来：python main.py
+
+要点
+----
+· ``observe`` 写记忆，``feel`` 改情绪，``feedback`` 让行为被玩家塑形；
+· 情绪会影响 NPC 的说话温度（warmth 插件）；
+· 状态落盘在 persist_dir，重启后性格/关系还在。
+"""
+from pasm_framework import SimpleApplication, capability, load
+
+
+class Innkeeper(SimpleApplication):
+    """酒馆老板：记得熟客，被夸奖更热情，被欺负会冷淡。"""
+
+    @capability(keywords=("买", "酒", "来一"), description="买酒")
+    def buy(self, text):
+        self.observe(title="玩家买酒", brief=text, tags=["交易"], salience=3)
+        self.feel(0.2)
+        return "给你满上！%s" % ("今天算你便宜点。" if self.mood > 0.3 else "")
+
+    @capability(keywords=("聊", "说说", "故事"), description="闲聊")
+    def chat_about(self, text):
+        hits = self.recall(text, k=2)
+        if hits:
+            return "这个啊……我记得：%s" % hits[0].get("brief", "")
+        return "唉，最近不太平，没什么好说的。"
+
+    @capability(keywords=("打", "揍", "滚"), description="敌对行为")
+    def hostile(self, text):
+        self.feel(-0.5)
+        self.observe(title="玩家挑衅", brief=text, tags=["敌意"], salience=4)
+        return "……你再这样我就叫卫兵了。" if self.mood < -0.3 else "别闹。"
+
+
+def main():
+    cfg = load(preset_name="game_npc")          # 离线优先，不接 LLM
+    npc = Innkeeper("innkeeper-01", {
+        "name": "老橡", "role": "酒馆老板",
+        "tone": "粗嗓门但热心", "temper": 0.7, "energy": 0.4, "play": 0.6,
+    }, backend_config=cfg)
+
+    script = ["打二两酒", "说说镇上的事", "揍你一顿", "打二两酒"]
+    for line in script:
+        reply = npc.ask(line, session_id="player-1")
+        print("玩家：%s" % line)
+        print("老橡：%s   （情绪 %.2f）" % (reply, npc.mood))
+        print("-" * 50)
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+_CONFIG_JSON = '''{
+  "plugins": {
+    "safety":         {"enabled": true,  "config": {"mode": "warn"}},
+    "sessions":       {"enabled": true,  "config": {"max_history": 20}},
+    "knowledge_base": {"enabled": true,  "config": {"kb_dir": "./kb"}},
+    "warmth":         {"enabled": true,  "config": {}},
+    "observability":  {"enabled": true,  "config": {}},
+    "llm_responder":  {"enabled": false, "config": {}},
+    "web_gateway":    {"enabled": false, "config": {"host": "127.0.0.1", "port": 8080}}
+  }
+}
+'''
+
+_README = """# {name}
+
+由 `pasm-framework new` 生成（模板：**{kind}**）。
+
+## 跑起来
+
+```bash
+pip install pasm-framework
+python main.py{serve_hint}
+```
+
+## 换个配置
+
+开关表在 `config.json`（也可用环境变量，见下）。代码里这样加载：
+
+```python
+from pasm_framework import load
+cfg = load("config.json", env=True)
+app = MyApp("my-app", {{"name": "小智"}}, backend_config=cfg)
+```
+
+环境变量（优先级高于 `config.json`）：
+
+| 变量 | 作用 |
+| --- | --- |
+| `PASM_PLUGINS` | `none` / `default` / `safety,sessions,...` |
+| `PASM_KB_DIR` | 知识库目录 |
+| `PASM_SAFETY_MODE` | `warn` 或 `block` |
+| `PASM_LLM_PROVIDER` / `PASM_LLM_MODEL` / `PASM_LLM_API_KEY` | 接入 LLM |
+| `PASM_HTTP_HOST` / `PASM_HTTP_PORT` / `PASM_HTTP_TOKEN` | HTTP 网关与鉴权 |
+
+## 下一步
+
+- 教程：`docs/tutorials/`（从快速上手到多语言接入）
+- 自检：`pasm-framework doctor`
+- 看插件：`pasm-framework plugins`
+"""
+
+_REQ = """pasm-framework>=0.2.1
+# 可选：接 LLM 时不需要额外依赖（内置用标准库 urllib）
+# 可选：读 .yaml 配置时需要
+# pyyaml>=6
+"""
+
+_TEMPLATES: Dict[str, Tuple[str, str]] = {
+    "app": (_MAIN_APP, ""),
+    "chatbot": (_MAIN_CHATBOT, " --serve"),
+    "game_npc": (_MAIN_NPC, ""),
+}
+
+
+def render(kind: str, name: str) -> Dict[str, str]:
+    """返回 ``{相对路径: 内容}``（纯函数，便于测试与预览）。"""
+    if kind not in _TEMPLATES:
+        raise FrameworkError(
+            "未知模板 %r；可用：%s" % (kind, ", ".join(KINDS)))
+    main_py, serve_hint = _TEMPLATES[kind]
+    return {
+        "main.py": main_py,
+        "config.json": _CONFIG_JSON,
+        "requirements.txt": _REQ,
+        "README.md": _README.format(name=name, kind=kind, serve_hint=serve_hint),
+    }
+
+
+def create(target_dir: str, *, kind: str = "app", name: str = "",
+           force: bool = False) -> List[str]:
+    """在 ``target_dir`` 生成项目；返回写出的相对路径列表。
+
+    ``force=False`` 时，若目录已存在同名文件 → 报错，不覆盖用户内容。
+    """
+    root = Path(target_dir)
+    files = render(kind, name or root.name or "my-app")
+    if root.exists() and not root.is_dir():
+        raise FrameworkError("目标已存在且不是目录：%s" % root)
+    if not force:
+        clash = [rel for rel in files if (root / rel).exists()]
+        if clash:
+            raise FrameworkError(
+                "目标目录已存在同名文件：%s（加 --force 覆盖）" % ", ".join(clash))
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "kb").mkdir(exist_ok=True)
+    written: List[str] = []
+    for rel, content in files.items():
+        p = root / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        written.append(rel)
+    return written

pasm_framework/service.py

@@ -0,0 +1,154 @@
+"""CognitiveAssembler + CognitiveService —— 框架与引擎之间的「唯一变动点」。
+
+为什么这层必须存在（V1→V2 不重写智能体/技能的核心机制）
+------------------------------------------------------
+`pasm_skills.sdk.BaseAgent` 已经通过 ``CognitiveBackend`` 协议与引擎解耦（见
+``pasm_skills/sdk/backend.py``）：它只认识协议，不认识 ``pasm.*``。
+
+本模块在协议之上再架一层**装配层**，把"选哪个后端、怎么把它适配成应用可用的认知服务"
+这件事彻底收口：
+
+  · ``CognitiveBackend`` （来自基座 sdk）  —— 引擎侧稳定契约（episode_push/recall/feedback…）。
+  · ``CognitiveService``                 —— 应用侧稳定契约：在后端外面套一层，
+                                            附带 domain 适配器钩子，但**对外仍是
+                                            CognitiveBackend**（这样 BaseAgent 无需改动）。
+  · ``CognitiveAssembler``               —— 装配器：V1 调 :meth:`v1` 拿到 V1 后端；
+                                            V2 只需新增 :meth:`v2` 返回 ``PasmV2Backend``，
+                                            **上层（4 智能体 / 3 技能）一行不改**。
+
+所以"唯一变动点"就是这里：引擎大改时，只有 ``CognitiveAssembler.v2``（以及
+``PasmV2Backend``）需要写，应用层完全不动。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pasm_skills.sdk.backend import (
+    CognitiveBackend,
+    create_v1_backend,
+)
+from .adapter import DomainAdapter, NullDomainAdapter
+
+
+# ============================================================ 认知服务（应用侧契约）
+
+class CognitiveService:
+    """包在 ``CognitiveBackend`` 外面的应用侧认知服务。
+
+    它**实现** ``CognitiveBackend`` 协议（属性 + 方法齐全），因此可以直接作为
+    ``BaseAgent(backend=...)`` 的入参；同时额外携带 ``domain`` 钩子，
+    供 ``BaseApplication`` 在检索/回复时注入领域知识。
+
+    V1→V2：本类不变。变的只是它内部委托的那个 ``_backend`` 是 V1 还是 V2。
+    """
+
+    def __init__(
+        self,
+        backend: CognitiveBackend,
+        domain: DomainAdapter = NullDomainAdapter(),
+    ) -> None:
+        # 不变量：入参必须真满足协议，否则就是"变动点"被改坏了——
+        # surface-guard 会抓这个（见框架 __init__ 的契约断言）。
+        if not isinstance(backend, CognitiveBackend):
+            raise TypeError(
+                "CognitiveService 需要 CognitiveBackend 协议实现，收到 %r"
+                % type(backend).__name__
+            )
+        self._backend = backend
+        self.domain = domain
+
+    # ---- CognitiveBackend 协议：全部委托给后端 ----
+
+    @property
+    def is_core(self) -> bool:
+        return bool(getattr(self._backend, "is_core", False))
+
+    @property
+    def emotion_system(self) -> Optional[Any]:
+        return getattr(self._backend, "emotion_system", None)
+
+    def episode_push(self, *, title, brief, tags, category, salience) -> None:
+        self._backend.episode_push(
+            title=title, brief=brief, tags=tags,
+            category=category, salience=salience,
+        )
+
+    def recall(self, query: str, k: int = 5) -> List[Dict[str, Any]]:
+        # 基础检索走后端；领域知识注入留给 BaseApplication（避免污染协议签名）。
+        return self._backend.recall(query, k=k)
+
+    def feedback(self, kind: str, action: Optional[str] = None) -> Dict[str, float]:
+        fn = getattr(self._backend, "feedback", None)
+        if fn is not None:
+            return fn(kind, action=action)
+        return {}
+
+    def learn_pick(self, candidates: List[str], base=None, **kw) -> str:
+        fn = getattr(self._backend, "learn_pick", None)
+        if fn is not None:
+            try:
+                return fn(candidates, base=base, **kw)
+            except TypeError:
+                try:
+                    return fn(candidates)
+                except Exception:
+                    pass
+            except Exception:
+                pass
+        import random
+        pool = [c for c in candidates if c]
+        return random.choice(pool) if pool else ""
+
+    def counts(self) -> Dict[str, int]:
+        fn = getattr(self._backend, "counts", None)
+        if fn is not None:
+            try:
+                return fn()
+            except Exception:
+                return {}
+        return {}
+
+
+# ============================================================ 装配器（唯一变动点）
+
+class CognitiveAssembler:
+    """把后端装配成应用可用的 ``CognitiveService``。
+
+    这是 V1↔V2 的唯一变动点：
+
+      - ``CognitiveAssembler.v1(...)``  → 返回 V1 后端装配出的服务（当前默认）。
+      - ``CognitiveAssembler.v2(...)``  → （V2.0 落地时新增）返回 V2 后端装配出的服务。
+      上层 ``BaseApplication`` / 4 智能体 / 3 技能只调用装配器，**不直接碰后端类型**，
+      因此换引擎 = 改这一处工厂方法。
+    """
+
+    @classmethod
+    def wrap(
+        cls,
+        backend: CognitiveBackend,
+        domain: Optional[DomainAdapter] = None,
+    ) -> CognitiveService:
+        """把任意 CognitiveBackend 包成 CognitiveService。"""
+        return CognitiveService(backend, domain or NullDomainAdapter())
+
+    @classmethod
+    def v1(
+        cls,
+        persist_dir,
+        persona: Optional[dict] = None,
+        *,
+        use_core: bool = True,
+        stage: int = 0,
+        domain: Optional[DomainAdapter] = None,
+    ) -> CognitiveService:
+        """默认路径：V1 后端（core 优先，降级 light）装配成服务。"""
+        backend = create_v1_backend(
+            persist_dir, persona, use_core=use_core, stage=stage
+        )
+        return cls.wrap(backend, domain)
+
+    # —— V2.0 落地时在此新增（示例，先留接口不实现，避免提前引入 pasm_v2 依赖）：
+    # @classmethod
+    # def v2(cls, persist_dir, persona=None, *, domain=None) -> CognitiveService:
+    #     from pasm_skills.contrib.v2 import create_v2_backend
+    #     return cls.wrap(create_v2_backend(persist_dir, persona), domain)

pasm_framework/simple.py

@@ -0,0 +1,174 @@
+"""SimpleApplication —— 让"最小可用应用"从 30 行降到 3 行。
+
+``BaseApplication`` 继承自 ``BaseAgent``，而 ``BaseAgent`` 是抽象基类，
+要求子类实现 ``action_pool()`` 与 ``_render_reply()``。对"我就想快速做个
+客服/问答/NPC"的人来说这是不必要的门槛 —— 本模块把这两个都给了默认实现，
+并额外提供 ``@capability`` 装饰器，让"加一个能力"= 加一个方法。
+
+三种用法，由简到繁
+------------------
+1. 最简（0 个方法）::
+
+     from pasm_framework import SimpleApplication
+     app = SimpleApplication("demo", {"name": "小智"})
+     print(app.ask("你好"))
+
+2. 自定义回复（传函数）::
+
+     app = SimpleApplication("demo", {"name": "小智"},
+                             reply=lambda text, facts, mood: "你说的是：" + text)
+
+3. 加能力（装饰器）::
+
+     class Shop(SimpleApplication):
+         @capability(keywords=("退货", "退款"))
+         def refund(self, text):
+             return "退货请点这里：/refund"
+
+     Shop("shop", {"name": "客服"}).handle("我要退货")   # → 能力命中
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from .application import BaseApplication
+from .config import load
+from .discovery import Capability
+
+#: ``reply`` 回调签名：``(text, facts, mood) -> str``
+ReplyFn = Callable[[str, List[Dict[str, Any]], float], str]
+
+
+def capability(
+    name: Optional[str] = None,
+    keywords: Any = (),
+    *,
+    predicate: Optional[Callable[[str], bool]] = None,
+    description: str = "",
+    head_chars: int = 12,
+) -> Callable[[Callable[..., str]], Callable[..., str]]:
+    """把实例方法标记为一个能力（动作）。
+
+    被标记的方法签名应为 ``def m(self, text: str) -> str``。
+    命中后 ``text`` 会作为第一个位置参数传入（即它等价于 ``Capability.run``）。
+
+    ``keywords`` 只在**句首 head_chars 个字**内匹配（框架既有语义，防止
+    "我在想退货这事到底……"这种长句被误触发）。
+    """
+
+    def deco(fn: Callable[..., str]) -> Callable[..., str]:
+        fn.__pasm_capability__ = {  # type: ignore[attr-defined]
+            "name": name or fn.__name__,
+            "keywords": tuple(keywords) if not isinstance(keywords, str)
+            else (keywords,),
+            "predicate": predicate,
+            "description": description,
+            "head_chars": head_chars,
+        }
+        return fn
+
+    return deco
+
+
+class SimpleApplication(BaseApplication):
+    """带默认回复实现的通用应用底座。
+
+    参数
+    ----
+    reply : ReplyFn | None
+        自定义回复生成器；缺省用"就资料作答、查不到就如实说"的内置策略。
+    unknown : str | None
+        检索不到资料时的兜底话术（**面向最终用户**，别写开发提示）。
+    backend_config : dict | BackendConfig | None
+        插件开关表；也可用 ``preset=`` 直接指定场景预设。
+    preset : str | None
+        场景预设名（见 :mod:`pasm_framework.config`）。给了 preset 才生效，
+        与 ``backend_config`` 同时给时 ``backend_config`` 优先。
+    """
+
+    #: 检索不到资料时的默认话术（面向用户，不暴露"插件/配置"这类内部概念）。
+    DEFAULT_UNKNOWN = "抱歉，我暂时没有查到相关资料。你可以换个说法再问我，或联系人工客服。"
+
+    #: 子类由 ``__init_subclass__`` 自动填充：``[(method_name, spec), ...]``
+    _PASM_AUTO_CAPS: List[tuple] = []
+
+    def __init_subclass__(cls, **kw: Any) -> None:
+        super().__init_subclass__(**kw)
+        auto: List[tuple] = []
+        for attr, obj in vars(cls).items():
+            spec = getattr(obj, "__pasm_capability__", None)
+            if isinstance(spec, dict):
+                auto.append((attr, spec))
+        if auto:
+            cls._PASM_AUTO_CAPS = auto
+
+    def __init__(
+        self,
+        agent_id: str,
+        persona: Optional[Dict[str, Any]] = None,
+        *,
+        reply: Optional[ReplyFn] = None,
+        capabilities: Optional[List[Capability]] = None,
+        preset: Optional[str] = None,
+        unknown: Optional[str] = None,
+        backend_config: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._reply_fn = reply
+        self._unknown = unknown or self.DEFAULT_UNKNOWN
+        caps = list(capabilities or [])
+        # 把 @capability 标记过的方法转成 Capability 对象。
+        for method_name, spec in type(self)._PASM_AUTO_CAPS:
+            caps.append(Capability(
+                spec["name"],
+                run=self._make_runner(method_name),
+                keywords=spec["keywords"],
+                predicate=spec["predicate"],
+                description=spec["description"],
+                head_chars=spec["head_chars"],
+            ))
+        if backend_config is None and preset is not None:
+            backend_config = load(preset_name=preset)
+        super().__init__(
+            agent_id, persona or {"name": "助手"},
+            capabilities=caps or None,
+            backend_config=backend_config,
+            **kwargs,
+        )
+
+    @staticmethod
+    def _make_runner(method_name: str) -> Callable[..., str]:
+        def run(app: Any, text: str) -> str:
+            return getattr(app, method_name)(text)
+        return run
+
+    # ---- BaseAgent 抽象方法的默认实现 ----
+    def action_pool(self) -> List[str]:  # noqa: D102
+        return ["reply"]
+
+    def _render_reply(  # noqa: D102
+        self, text: str, facts: List[Dict[str, Any]], mood: float
+    ) -> str:
+        if self._reply_fn is not None:
+            return self._reply_fn(text, facts, mood)
+        # 默认策略：只依据"有来源的知识"作答，不编造。
+        knowledge = [f for f in (facts or []) if f.get("source")]
+        if knowledge:
+            top = knowledge[0]
+            body = (top.get("brief") or top.get("title") or "").strip()
+            return body or self._unknown
+        return self._unknown
+
+    # ---- 便捷方法 ----
+    def ask(self, text: str, session_id: str = "default",
+            user_id: Optional[str] = None) -> str:
+        """语义化别名：``handle`` 是框架内部叫法，``ask`` 是给人看的。"""
+        return self.handle(text, session_id=session_id, user_id=user_id)
+
+    def teach(self, items: List[Dict[str, Any]]) -> int:
+        """``ingest`` 的语义化别名（喂资料给知识库，返回新增条数）。
+
+        两个名字等价，统一由 ``BaseApplication.ingest`` 实现；未启用
+        ``knowledge_base`` 时会抛 ``FrameworkError`` 指引开启方式。
+        """
+        return self.ingest(items)