pasm-framework 0.3.0__py3-none-any.whl

pasm_framework/config.py

@@ -0,0 +1,319 @@
+"""配置系统 —— 让"后端选择是否使用某插件"能来自预设 / 文件 / 环境变量 / 代码。
+
+为什么需要
+----------
+v0.2.0 的开关表只能写在 Python 代码里（``BaseApplication(backend_config={...})``），
+部署时想改一个端口、换一个模型，都得改代码再发版。本模块让同一份应用可以：
+
+  · 本地开发   —— ``load(preset="chatbot")``
+  · 部署上线   —— ``load("server.json", env=True)`` 或直接给环境变量
+  · 单元测试   —— ``load(preset="minimal")``（全关，行为退化为 v0.1.0）
+
+合并优先级（后者覆盖前者）
+--------------------------
+    preset  <  file(source)  <  env  <  overrides(显式入参)
+
+只依赖标准库；``yaml`` 是可选加速项（装了就能读 ``.yaml/.yml``，没装则提示改用 JSON）。
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from .errors import FrameworkError
+from .plugins.core import BackendConfig
+
+PLUGIN_NAMES: List[str] = [
+    "safety", "sessions", "knowledge_base", "warmth",
+    "observability", "llm_responder", "web_gateway",
+]
+
+
+def _all(enabled: bool, **cfg) -> Dict[str, Any]:
+    return {"enabled": enabled, "config": dict(cfg)}
+
+
+#: 场景预设。每个预设都**列全 7 个插件**——未列出的插件会被视为"关闭"，
+#: 写全可以避免"我明明没关它，它却没了"的困惑。
+PRESETS: Dict[str, Dict[str, Dict[str, Any]]] = {
+    # 全关：行为退回 v0.1.0（能力路由 → 回落 chat）。测试与嵌入式场景用。
+    "minimal": {n: _all(False) for n in PLUGIN_NAMES},
+
+    # 与框架默认一致：基础/安全能力开，LLM 与网关关。
+    "default": {
+        "safety": _all(True, mode="warn"),
+        "sessions": _all(True),
+        "knowledge_base": _all(True),
+        "warmth": _all(True),
+        "observability": _all(True),
+        "llm_responder": _all(False),
+        "web_gateway": _all(False),
+    },
+
+    # 对外站点智能客服：护栏收紧为 block（面向公众，宁可拦错也别放行）。
+    "chatbot": {
+        "safety": _all(True, mode="block"),
+        "sessions": _all(True, max_history=20),
+        "knowledge_base": _all(True),
+        "warmth": _all(True),
+        "observability": _all(True),
+        "llm_responder": _all(False),
+        "web_gateway": _all(True, host="0.0.0.0", port=8080),
+    },
+
+    # 游戏 NPC：离线优先（不接 LLM），保留情绪润色与会话内记忆。
+    "game_npc": {
+        "safety": _all(True, mode="warn"),
+        "sessions": _all(True, max_history=12),
+        "knowledge_base": _all(True),
+        "warmth": _all(True),
+        "observability": _all(False),
+        "llm_responder": _all(False),
+        "web_gateway": _all(False),
+    },
+
+    # 纯 API 服务：回复要"干净"（不润色），护栏收紧，暴露 HTTP。
+    "api": {
+        "safety": _all(True, mode="block"),
+        "sessions": _all(True, max_history=20),
+        "knowledge_base": _all(True),
+        "warmth": _all(False),
+        "observability": _all(True),
+        "llm_responder": _all(False),
+        "web_gateway": _all(True, host="127.0.0.1", port=8080),
+    },
+
+    # 桌面应用内嵌：只监听本机，避免把服务暴露到局域网。
+    "desktop": {
+        "safety": _all(True, mode="warn"),
+        "sessions": _all(True, max_history=30),
+        "knowledge_base": _all(True),
+        "warmth": _all(True),
+        "observability": _all(False),
+        "llm_responder": _all(False),
+        "web_gateway": _all(True, host="127.0.0.1", port=8765),
+    },
+}
+
+
+def preset(name: str) -> Dict[str, Dict[str, Any]]:
+    """取一份场景预设的**副本**（改它不会污染全局预设）。"""
+    if name not in PRESETS:
+        raise FrameworkError(
+            "未知预设 %r；可用：%s" % (name, ", ".join(sorted(PRESETS)))
+        )
+    return copy.deepcopy(PRESETS[name])
+
+
+def _deep_merge(base: Dict[str, Any], over: Dict[str, Any]) -> Dict[str, Any]:
+    """两层深合并：``{"a":{"enabled":True,"config":{"k":1}}}`` 级别的覆盖。
+
+    只合并到 ``enabled`` / ``config`` 这一层，不再往下钻 ——
+    这样"我只想改 config.port"不会把同插件其它 config 键抹掉。
+    """
+    out = copy.deepcopy(base)
+    for name, spec in (over or {}).items():
+        if not isinstance(spec, dict):
+            continue
+        cur = out.setdefault(name, {"enabled": False, "config": {}})
+        if "enabled" in spec:
+            cur["enabled"] = bool(spec["enabled"])
+        cfg = spec.get("config")
+        if isinstance(cfg, dict):
+            merged = dict(cur.get("config") or {})
+            merged.update(cfg)
+            cur["config"] = merged
+    return out
+
+
+# ---------------------------------------------------------------- 文件
+
+def from_file(path: Union[str, Path]) -> Dict[str, Dict[str, Any]]:
+    """从 JSON / YAML 读取开关表。
+
+    期望结构（``plugins`` 键可省略，直接给插件名也行）::
+
+        {"plugins": {"web_gateway": {"enabled": true, "config": {"port": 9000}}}}
+    """
+    p = Path(path)
+    if not p.exists():
+        raise FrameworkError("配置文件不存在：%s" % p)
+    text = p.read_text(encoding="utf-8")
+    suffix = p.suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        try:
+            import yaml  # type: ignore
+        except Exception as ex:  # noqa: BLE001
+            raise FrameworkError(
+                "读取 %s 需要 pyyaml（pip install pyyaml），或改用 .json 配置。" % p
+            ) from ex
+        data = yaml.safe_load(text) or {}
+    else:
+        try:
+            data = json.loads(text or "{}")
+        except Exception as ex:  # noqa: BLE001
+            raise FrameworkError("配置文件不是合法 JSON：%s（%s）" % (p, ex)) from ex
+    if not isinstance(data, dict):
+        raise FrameworkError("配置文件顶层必须是对象：%s" % p)
+    plugins = data.get("plugins")
+    return plugins if isinstance(plugins, dict) else data
+
+
+# ---------------------------------------------------------------- 环境变量
+
+def from_env(prefix: str = "PASM_") -> Dict[str, Dict[str, Any]]:
+    """把环境变量翻译成开关表覆盖。
+
+    支持（值非空才生效）::
+
+        PASM_PLUGINS=none|default|a,b,c      只启用列出的插件
+        PASM_KB_DIR=/data/kb                 知识库目录
+        PASM_SAFETY_MODE=warn|block
+        PASM_LLM_PROVIDER=deepseek|openai|ollama
+        PASM_LLM_MODEL=deepseek-chat
+        PASM_LLM_BASE_URL=https://...        自建/代理网关
+        PASM_LLM_API_KEY=sk-...              （也接受 OPENAI_API_KEY 等）
+        PASM_HTTP_HOST=0.0.0.0
+        PASM_HTTP_PORT=8080
+        PASM_HTTP_TOKEN=***                  网关 Bearer 鉴权令牌
+    """
+    e = os.environ
+    out: Dict[str, Dict[str, Any]] = {}
+
+    def put(plugin: str, key: str, value: Any, *, enable: bool = False) -> None:
+        spec = out.setdefault(plugin, {"config": {}})
+        if enable:
+            spec["enabled"] = True
+        spec["config"][key] = value
+
+    def g(name: str) -> Optional[str]:
+        v = e.get(prefix + name)
+        return v if v else None
+
+    raw_plugins = g("PLUGINS")
+    if raw_plugins is not None:
+        if raw_plugins.strip().lower() in ("none", "off", ""):
+            for n in PLUGIN_NAMES:
+                out[n] = {"enabled": False}
+        else:
+            keep = {s.strip() for s in raw_plugins.split(",") if s.strip()}
+            for n in PLUGIN_NAMES:
+                out[n] = {"enabled": n in keep}
+
+    if g("KB_DIR"):
+        put("knowledge_base", "kb_dir", g("KB_DIR"), enable=True)
+    if g("SAFETY_MODE"):
+        put("safety", "mode", g("SAFETY_MODE"), enable=True)
+
+    llm_provider = g("LLM_PROVIDER")
+    llm_key = g("LLM_API_KEY")
+    if llm_provider or llm_key or g("LLM_MODEL") or g("LLM_BASE_URL"):
+        # 只要配了任一项，就认为用户想开 LLM（默认关是为了"没配就别联网"）。
+        if llm_provider:
+            put("llm_responder", "provider", llm_provider)
+        if g("LLM_MODEL"):
+            put("llm_responder", "model", g("LLM_MODEL"))
+        if g("LLM_BASE_URL"):
+            put("llm_responder", "base_url", g("LLM_BASE_URL"))
+        if llm_key:
+            put("llm_responder", "api_key", llm_key)
+        out.setdefault("llm_responder", {"config": {}})["enabled"] = True
+
+    if g("HTTP_HOST"):
+        put("web_gateway", "host", g("HTTP_HOST"))
+    if g("HTTP_PORT"):
+        try:
+            put("web_gateway", "port", int(g("HTTP_PORT") or 8080))
+        except ValueError:
+            raise FrameworkError("PASM_HTTP_PORT 必须是整数：%r" % g("HTTP_PORT"))
+    if g("HTTP_TOKEN"):
+        put("web_gateway", "token", g("HTTP_TOKEN"))
+    if any(k in out.get("web_gateway", {}).get("config", {})
+           for k in ("host", "port", "token")):
+        out.setdefault("web_gateway", {"config": {}})["enabled"] = True
+
+    return out
+
+
+# ---------------------------------------------------------------- 统一入口
+
+def load(
+    source: Optional[Union[str, Path, Dict[str, Any]]] = None,
+    *,
+    preset_name: Optional[str] = None,
+    env: bool = False,
+    env_prefix: str = "PASM_",
+    **overrides: Any,
+) -> BackendConfig:
+    """把预设 / 文件 / 环境变量 / 显式覆盖合成一个 :class:`BackendConfig`。
+
+    参数
+    ----
+    source : dict | path | None
+        开关表本体；传路径则按后缀读 JSON/YAML。
+    preset_name : str | None
+        场景预设名（``minimal`` / ``default`` / ``chatbot`` / ``game_npc`` /
+        ``api`` / ``desktop``）。缺省 = ``default``。
+    env : bool
+        是否叠加环境变量。
+    **overrides
+        单个插件的覆盖，如 ``load("api", web_gateway={"enabled": True,
+        "config": {"port": 9000}})``。
+
+    用法::
+
+        from pasm_framework import load
+        cfg = load(preset_name="chatbot", env=True, web_gateway={
+            "enabled": True, "config": {"port": 9000}})
+        app = MyApp("demo", {"name": "小智"}, backend_config=cfg)
+    """
+    data = preset(preset_name or "default")
+    if source is not None:
+        file_data = source if isinstance(source, dict) else from_file(source)
+        data = _deep_merge(data, file_data)
+    if env:
+        data = _deep_merge(data, from_env(env_prefix))
+    if overrides:
+        data = _deep_merge(data, overrides)
+    return BackendConfig(plugins=data)
+
+
+def to_dict(cfg: BackendConfig) -> Dict[str, Any]:
+    """把 ``BackendConfig`` 还原成可序列化的 dict（落盘 / 展示用）。"""
+    plugins: Dict[str, Any] = {}
+    for name in PLUGIN_NAMES:
+        e = cfg.plugins.get(name)
+        if e is None:
+            continue
+        plugins[name] = {"enabled": bool(e.get("enabled", False)),
+                         "config": dict(e.get("config") or {})}
+    return {"plugins": plugins}
+
+
+def save(cfg: BackendConfig, path: Union[str, Path]) -> Path:
+    """写出一份 JSON 配置（可作为部署模板）。"""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(to_dict(cfg), ensure_ascii=False, indent=2) + "\n",
+                 encoding="utf-8")
+    return p
+
+
+def describe(cfg: BackendConfig) -> List[str]:
+    """生成人类可读的开关清单（``doctor`` / CLI 用）。"""
+    lines: List[str] = []
+    for name in PLUGIN_NAMES:
+        e = cfg.plugins.get(name) or {"enabled": False, "config": {}}
+        on = "开" if e.get("enabled") else "关"
+        cfgd = e.get("config") or {}
+        detail = ""
+        if cfgd:
+            # 密钥类只显示"已设置"，不泄露内容
+            safe = {k: ("***" if "key" in k or "token" in k else v)
+                    for k, v in cfgd.items()}
+            detail = "  " + json.dumps(safe, ensure_ascii=False)
+        lines.append("  [%s] %-16s%s" % (on, name, detail))
+    return lines

pasm_framework/demo.py

@@ -0,0 +1,85 @@
+"""开箱即用的演示应用 —— 让 ``pasm-framework serve`` 一条命令就能跑起来。
+
+存在的意义
+----------
+"即插即用"最直观的证明是：装完包，一条命令，浏览器里就能对话。
+本模块提供一个**零 LLM 也能回答**的智能客服实例（靠 ``knowledge_base``
+就资料作答），供 CLI 的 ``serve`` 子命令与教程使用。
+
+它不是生产代码 —— 生产请参考仓库 ``apps/customer_service.py`` 的完整形态。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .config import load
+from .simple import SimpleApplication
+
+#: 演示资料：故意覆盖"能答 / 答不上来"两类问题，方便观察护栏与兜底行为。
+DEMO_FAQ: List[Dict[str, Any]] = [
+    {"title": "退货政策",
+     "content": "商品签收后 7 天内可无理由退货，需保持吊牌完整、不影响二次销售。",
+     "source": "faq", "tags": ["退货", "退款", "售后"]},
+    {"title": "换货流程",
+     "content": "在订单详情页点「申请换货」，选择尺码/颜色后寄回，我们收到当天发出新品。",
+     "source": "faq", "tags": ["换货", "售后"]},
+    {"title": "配送时效",
+     "content": "现货 24 小时内发货；偏远地区 3-5 天送达；支持顺丰加急。",
+     "source": "faq", "tags": ["配送", "物流", "发货"]},
+    {"title": "运费说明",
+     "content": "单笔满 99 元包邮，未满收取 8 元运费；退货运费由我方承担。",
+     "source": "faq", "tags": ["运费", "包邮"]},
+    {"title": "发票",
+     "content": "下单时可勾选电子发票，次日发送至注册邮箱；专票需联系客服登记。",
+     "source": "faq", "tags": ["发票", "开票"]},
+    {"title": "营业时间",
+     "content": "在线客服时间为每天 9:00-21:00，节假日不休。",
+     "source": "faq", "tags": ["时间", "客服"]},
+]
+
+
+class DemoAgent(SimpleApplication):
+    """演示用智能客服（话术面向终端用户）。"""
+
+    DEFAULT_UNKNOWN = "抱歉，我暂时没有查到相关资料。你可以换个说法再问我，或联系人工客服。"
+
+
+def make_demo_app(
+    *,
+    kb_dir: Optional[str] = None,
+    llm: Optional[Dict[str, Any]] = None,
+    host: str = "127.0.0.1",
+    port: int = 8080,
+    agent_id: str = "pasm-demo",
+    preset_name: str = "chatbot",
+    token: Optional[str] = None,
+    teach: bool = True,
+) -> DemoAgent:
+    """构造演示应用（已导入 :data:`DEMO_FAQ`）。
+
+    >>> from pasm_framework.demo import make_demo_app
+    >>> app = make_demo_app(port=8099)
+    >>> "退货" in app.ask("怎么退货？")
+    True
+    """
+    gw: Dict[str, Any] = {"enabled": True, "config": {"host": host, "port": port}}
+    if token:
+        gw["config"]["token"] = token
+    kb: Dict[str, Any] = {"enabled": True}
+    if kb_dir:
+        kb["config"] = {"kb_dir": kb_dir}
+    cfg = load(
+        preset_name=preset_name,
+        knowledge_base=kb,
+        web_gateway=gw,
+        llm_responder={"enabled": bool(llm), "config": dict(llm or {})},
+    )
+    app = DemoAgent(
+        agent_id,
+        {"name": "小智", "role": "智能客服", "tone": "温暖、专业、耐心",
+         "temper": 0.6, "energy": 0.5, "play": 0.4},
+        backend_config=cfg,
+    )
+    if teach:
+        app.teach(DEMO_FAQ)
+    return app

pasm_framework/discovery.py

@@ -0,0 +1,91 @@
+"""CapabilityDiscovery —— 应用"能力"的声明与发现。
+
+为什么单独抽一层
+----------------
+产品智能体当前用一堆散落的 ``if chip == "ad"`` / ``_MAP`` / ``ADAPTERS`` 硬编码分支
+来"识别用户想要什么能力"（广告设计、图文、视频…）。一个能力常有多套入口，
+改一套 ≠ 改完（见项目记忆：广告设计至少三处入口）。
+
+``CapabilityDiscovery`` 把"能力"变成一等公民：
+
+  - 每个能力 = ``Capability(name, match, run)``，自带匹配规则与执行体；
+  - 应用启动时报到注册，运行时按用户输入做**统一**的能力发现；
+  - 匹配规则默认"句首 N 字 + 关键词"，但可逐能力覆盖。
+
+这样新增/删除/排查能力都只动注册表，不动散落分支——又是一处稳定的框架面。
+（注：默认"只匹配句首 12 字"是产品侧故意的设计，这里保留为可调参数，
+不是 bug；见项目记忆。）
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional, Tuple
+
+
+# 默认只匹配句首这么多字符——产品侧有意保留（防止长句里误命中）。
+DEFAULT_HEAD_CHARS = 12
+
+
+@dataclass
+class Capability:
+    """一个可被用户触发的"能力"。
+
+    ``match`` 决定何时命中；``run(app, text) -> str`` 是执行体，
+    接收应用实例与原始输入，返回回复文本。
+    """
+
+    name: str
+    run: Callable[..., str]            # 执行体：run(app, text) -> str
+    # 匹配规则（任选其一或全部）：关键词列表 / 自定义判定 / 句首字数。
+    keywords: Tuple[str, ...] = ()
+    head_chars: int = DEFAULT_HEAD_CHARS
+    predicate: Optional[Callable[[str], bool]] = None
+    description: str = ""
+
+
+class CapabilityDiscovery:
+    """能力注册表 + 统一发现。
+
+    用法：
+        cd = CapabilityDiscovery()
+        cd.register(Capability("广告设计", run=my_ad, keywords=("广告", "海报")))
+        cap = cd.match("帮我设计一张广告")   # -> 该 Capability 或 None
+    """
+
+    def __init__(self, capabilities: Optional[List[Capability]] = None) -> None:
+        self._caps: Dict[str, Capability] = {}
+        for c in (capabilities or []):
+            self.register(c)
+
+    def register(self, cap: Capability) -> None:
+        if not isinstance(cap, Capability):
+            raise TypeError("CapabilityDiscovery 只接受 Capability，收到 %r" % type(cap).__name__)
+        self._caps[cap.name] = cap
+
+    def names(self) -> List[str]:
+        return list(self._caps.keys())
+
+    def has(self, name: str) -> bool:
+        return name in self._caps
+
+    def get(self, name: str) -> Optional[Capability]:
+        return self._caps.get(name)
+
+    def match(self, text: str) -> Optional[Capability]:
+        """按规则匹配能力。
+
+        顺序：先 ``predicate``（精确判定），再 ``keywords``（句首 head_chars 命中）。
+        命中多个时返回**最先注册**的那一个（确定性，避免随机）。
+        """
+        t = (text or "").strip()
+        if not t:
+            return None
+        for cap in self._caps.values():
+            if cap.predicate is not None and cap.predicate(t):
+                return cap
+        for cap in self._caps.values():
+            if cap.keywords:
+                span = t[: max(cap.head_chars, 1)]
+                if any(k and k in span for k in cap.keywords):
+                    return cap
+        return None

pasm_framework/errors.py

@@ -0,0 +1,26 @@
+"""框架异常定义。
+
+框架层只抛这一类错误，方便应用层统一捕获；引擎内部异常（pasm.*）
+一律在后端里被吞掉、降级，不向上污染框架。
+"""
+from __future__ import annotations
+
+
+class FrameworkError(Exception):
+    """框架层统一异常基类。"""
+
+
+class SurfaceMissing(FrameworkError):
+    """某个框架表面（接口）在运行时找不到实现。
+
+    典型场景：``BaseApplication`` 期望 ``DomainAdapter`` 提供了某个方法，
+    但实际注入的是 ``NullDomainAdapter``。用于把"静默降级"变成"明确的红灯"。
+    """
+
+
+class BackendContractBroken(FrameworkError):
+    """后端没有实现 ``CognitiveBackend`` 协议要求的成员。
+
+    surface-guard 会专门抓这一类——只要 V1/V2 后端动了契约，
+    CI 立刻红，而不是让产品智能体在用户机器上崩。
+    """

pasm_framework/plugins/__init__.py

@@ -0,0 +1,42 @@
+"""pasm-framework 插件子系统（即插即用）。
+
+公共 API：
+  · ``Message`` / ``PluginContext``      —— 链上消息与上下文
+  · ``BasePlugin`` / ``Plugin``          —— 插件基类 / 契约
+  · ``PluginManager``                   —— Hook 链编排
+  · ``BackendConfig`` / ``build_manager``/ ``default_config`` —— 后端开关与装配
+  · ``builtin_plugins`` / ``discover_plugins`` —— 内置与第三方插件发现
+
+典型用法见 ``apps/customer_service.py`` 与仓库 README。
+"""
+from __future__ import annotations
+
+from .core import (
+    BackendConfig,
+    BasePlugin,
+    HOOKS,
+    Message,
+    Plugin,
+    PluginContext,
+    PluginManager,
+    build_manager,
+    default_config,
+)
+from .registry import (
+    builtin_plugins,
+    discover_plugins,
+)
+
+__all__ = [
+    "Message",
+    "PluginContext",
+    "BasePlugin",
+    "Plugin",
+    "PluginManager",
+    "BackendConfig",
+    "build_manager",
+    "default_config",
+    "HOOKS",
+    "builtin_plugins",
+    "discover_plugins",
+]

pasm_framework/plugins/builtins/__init__.py

@@ -0,0 +1,30 @@
+"""pasm-framework 内置插件库（即插即用）。
+
+7 个 builtin 插件，全部零强制外部依赖，可在后端配置中按名开关：
+  · ``sessions``        会话 / 租户隔离
+  · ``knowledge_base``  站点数据自学资料库（智能客服核心）
+  · ``llm_responder``   可选 LLM 接入（OpenAI / DeepSeek / Ollama）
+  · ``warmth``          回复温度 / 情感润色
+  · ``safety``          护栏（注入拦截 + PII 脱敏）
+  · ``observability``   可观测（指标 + 健康）
+  · ``web_gateway``     零依赖 HTTP 网关（iframe / REST）
+"""
+from __future__ import annotations
+
+from .knowledge_base import KnowledgeBasePlugin
+from .llm_responder import LLMResponderPlugin
+from .observability import ObservabilityPlugin
+from .safety import SafetyPlugin
+from .sessions import SessionsPlugin
+from .warmth import WarmthPlugin
+from .web_gateway import WebGatewayPlugin
+
+__all__ = [
+    "SessionsPlugin",
+    "KnowledgeBasePlugin",
+    "LLMResponderPlugin",
+    "WarmthPlugin",
+    "SafetyPlugin",
+    "ObservabilityPlugin",
+    "WebGatewayPlugin",
+]