pasm-framework 0.3.0__tar.gz → 0.4.0__tar.gz

{pasm_framework-0.3.0 → pasm_framework-0.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: pasm-framework
-Version: 0.3.0
+Version: 0.4.0
 Summary: PASM 应用开发框架 —— 产品智能体/应用与认知引擎之间的防腐层（V1↔V2 唯一变动点）
 Author: arronzheng
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://gitee.com/arronzheng/pasm-framework
 Project-URL: Repository, https://github.com/arronJack/pasm-framework
 Project-URL: Source, https://gitee.com/arronzheng/pasm-framework
@@ -11,7 +11,6 @@ Project-URL: Issues, https://gitee.com/arronzheng/pasm-framework/issues
 Keywords: pasm,agent,application-framework,anti-corruption-layer,cognitive,capability,skill,domain-adapter
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -54,7 +53,7 @@ PASM V1 → V2 升级时，**不重写 4 个产品智能体 + 3 个技能**。
 
 `CognitiveBackend` 协议的**单一真相源仍在基座** `pasm_skills.sdk.backend`，本包只做重导出。
 
-## 流式与工具调用（v0.3.0 新增）
+## 流式与工具调用（v0.3.0）
 
 **真流式（SSE）** —— `stream()` 与 `handle()` **共用同一条管线**，不会行为漂移：
 
@@ -163,6 +162,48 @@ sla = "my_pkg.my_module:SlaPlugin"
 ⚠️ 插件名**拼错不会静默通过**：`app.plugins.unknown()`、`app.app_summary()["plugin_config_unknown"]`
 以及 `pasm-framework doctor` 都会报告。
 
+## 一键起在线客服（v0.4.0）
+
+**一条命令**拿到：访客对话页 + 站长管理台 + 一行嵌入代码 + REST 示例（双令牌自动生成）。
+
+```bash
+pasm-framework cs --port 8080 --name "小智客服"
+```
+
+输出会直接给你三段：
+
+```
+① 访客对话页        http://127.0.0.1:8080/
+② 站长管理台        http://127.0.0.1:8080/console?token=<管理令牌>
+③ 嵌入任意语言站点    <script src=".../embed.js" data-pasm-token="<公开令牌>" ...></script>
+```
+
+**站点接入只要一行**（PHP / Java / Node / 静态页都行）：
+
+```html
+<script src="http://你的服务器:8080/embed.js"
+        data-pasm-token="公开令牌"
+        data-title="在线客服"
+        data-greeting="你好！我是智能客服，有什么可以帮你？"
+        data-color="#2563eb" defer></script>
+```
+
+> ⚠️ 属性名必须是 **`data-pasm-token`**（写成 `data-token` 挂件拿不到令牌 → 401）。
+
+**双令牌作用域**（安全红线，selftest 已固化）：
+
+| 令牌 | 能做什么 |
+| --- | --- |
+| `token`（管理） | 全部接口：对话 + 导入资料 + 看会话 + 管理台 |
+| `public_token`（访客） | **仅** `/api/chat`、`/api/chat/stream`；配了它时挂件页对访客开放 |
+
+`serve_token` **只返回 `public_token`，绝不回落管理令牌** —— 挂件页是给访客看的，
+一旦回落，源码里就能读到后台令牌。未配 `public_token` 时挂件页本身也不公开。
+`/embed.js` 与 `/healthz` 是唯一无条件公开的路径（本身不含密钥）。
+
+管理台里可以**粘贴整篇帮助文档**（`POST /api/ingest/text`）自动切块、识别「问：/答：」存成问答对，
+访客立刻就能问到 —— 这就是"资料库自学"的入口。
+
 ## 参考实现：站点智能客服
 
 `apps/customer_service.py` 用插件组合出一个可上线的客服 Agent（零 LLM 也能回答）。
@@ -258,7 +299,7 @@ print(app.handle("你好"))          # → "reply:你好"（回落 chat）
 ## 快速自检
 
 ```bash
-python -m pasm_framework selftest      # 44 项
+python -m pasm_framework selftest      # 55 项
 python -m pasm_framework doctor        # 真装配一遍插件并报拼错的名字
 python -m pasm_framework version
 ```
@@ -273,6 +314,8 @@ python -m pasm_framework version
 | [`docs/cross-platform-strategy.md`](docs/cross-platform-strategy.md) | 桌面端跨 Linux/macOS、手机端换架构方案 |
 | [`docs/customer-service-plugin.md`](docs/customer-service-plugin.md) | 智能客服可行性与部署形态研究 |
 | [`docs/audit-2026-09-20.md`](docs/audit-2026-09-20.md) | v0.2.0 体检报告 |
+| [`docs/plugin-ownership.md`](docs/plugin-ownership.md) | 插件放子目录还是独立仓（决策 + 理由） |
+| [`docs/audit-7repos-2026-09-20.md`](docs/audit-7repos-2026-09-20.md) | **七仓全盘审计**（含跨平台实测） |
 | [`docs/openapi.yaml`](docs/openapi.yaml) | HTTP 契约（单一真相源） |
 | [`sdks/`](sdks/README.md) | C# / Java / PHP / Node / Go / Python 客户端 |
 

{pasm_framework-0.3.0 → pasm_framework-0.4.0}/README.md

@@ -26,7 +26,7 @@ PASM V1 → V2 升级时，**不重写 4 个产品智能体 + 3 个技能**。
 
 `CognitiveBackend` 协议的**单一真相源仍在基座** `pasm_skills.sdk.backend`，本包只做重导出。
 
-## 流式与工具调用（v0.3.0 新增）
+## 流式与工具调用（v0.3.0）
 
 **真流式（SSE）** —— `stream()` 与 `handle()` **共用同一条管线**，不会行为漂移：
 
@@ -135,6 +135,48 @@ sla = "my_pkg.my_module:SlaPlugin"
 ⚠️ 插件名**拼错不会静默通过**：`app.plugins.unknown()`、`app.app_summary()["plugin_config_unknown"]`
 以及 `pasm-framework doctor` 都会报告。
 
+## 一键起在线客服（v0.4.0）
+
+**一条命令**拿到：访客对话页 + 站长管理台 + 一行嵌入代码 + REST 示例（双令牌自动生成）。
+
+```bash
+pasm-framework cs --port 8080 --name "小智客服"
+```
+
+输出会直接给你三段：
+
+```
+① 访客对话页        http://127.0.0.1:8080/
+② 站长管理台        http://127.0.0.1:8080/console?token=<管理令牌>
+③ 嵌入任意语言站点    <script src=".../embed.js" data-pasm-token="<公开令牌>" ...></script>
+```
+
+**站点接入只要一行**（PHP / Java / Node / 静态页都行）：
+
+```html
+<script src="http://你的服务器:8080/embed.js"
+        data-pasm-token="公开令牌"
+        data-title="在线客服"
+        data-greeting="你好！我是智能客服，有什么可以帮你？"
+        data-color="#2563eb" defer></script>
+```
+
+> ⚠️ 属性名必须是 **`data-pasm-token`**（写成 `data-token` 挂件拿不到令牌 → 401）。
+
+**双令牌作用域**（安全红线，selftest 已固化）：
+
+| 令牌 | 能做什么 |
+| --- | --- |
+| `token`（管理） | 全部接口：对话 + 导入资料 + 看会话 + 管理台 |
+| `public_token`（访客） | **仅** `/api/chat`、`/api/chat/stream`；配了它时挂件页对访客开放 |
+
+`serve_token` **只返回 `public_token`，绝不回落管理令牌** —— 挂件页是给访客看的，
+一旦回落，源码里就能读到后台令牌。未配 `public_token` 时挂件页本身也不公开。
+`/embed.js` 与 `/healthz` 是唯一无条件公开的路径（本身不含密钥）。
+
+管理台里可以**粘贴整篇帮助文档**（`POST /api/ingest/text`）自动切块、识别「问：/答：」存成问答对，
+访客立刻就能问到 —— 这就是"资料库自学"的入口。
+
 ## 参考实现：站点智能客服
 
 `apps/customer_service.py` 用插件组合出一个可上线的客服 Agent（零 LLM 也能回答）。
@@ -230,7 +272,7 @@ print(app.handle("你好"))          # → "reply:你好"（回落 chat）
 ## 快速自检
 
 ```bash
-python -m pasm_framework selftest      # 44 项
+python -m pasm_framework selftest      # 55 项
 python -m pasm_framework doctor        # 真装配一遍插件并报拼错的名字
 python -m pasm_framework version
 ```
@@ -245,6 +287,8 @@ python -m pasm_framework version
 | [`docs/cross-platform-strategy.md`](docs/cross-platform-strategy.md) | 桌面端跨 Linux/macOS、手机端换架构方案 |
 | [`docs/customer-service-plugin.md`](docs/customer-service-plugin.md) | 智能客服可行性与部署形态研究 |
 | [`docs/audit-2026-09-20.md`](docs/audit-2026-09-20.md) | v0.2.0 体检报告 |
+| [`docs/plugin-ownership.md`](docs/plugin-ownership.md) | 插件放子目录还是独立仓（决策 + 理由） |
+| [`docs/audit-7repos-2026-09-20.md`](docs/audit-7repos-2026-09-20.md) | **七仓全盘审计**（含跨平台实测） |
 | [`docs/openapi.yaml`](docs/openapi.yaml) | HTTP 契约（单一真相源） |
 | [`sdks/`](sdks/README.md) | C# / Java / PHP / Node / Go / Python 客户端 |
 

{pasm_framework-0.3.0 → pasm_framework-0.4.0}/pasm_framework/__init__.py

@@ -39,7 +39,7 @@ PASM V1→V2 升级时，**不重写 4 个产品智能体 + 3 个技能**。手
 """
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from .adapter import (  # noqa: F401
     DomainAdapter,
@@ -292,6 +292,45 @@ def selftest() -> bool:
             gw = pm.get("web_gateway")
             check(gw is not None, "web_gateway 插件可构造（不启动服务器）")
 
+            # ---- v0.3.1 站点插件安全不变式（不需要起服务器）----
+            # `_Handler._gw` 读的是 `self.server.gateway`，所以给个假 server 就能
+            # 直接调鉴权逻辑，无需真的监听端口。
+            from .plugins.builtins.web_gateway import _Handler as _GWHandler
+
+            class _ProbeHandler(_GWHandler):
+                def __init__(self, gateway, path, headers=None):
+                    self.server = type("_S", (), {"gateway": gateway})()
+                    self.path = path
+                    self.headers = headers or {}
+
+            def _probe(gateway, path, tok=None):
+                h = _ProbeHandler(gateway, path,
+                                  {"Authorization": "Bearer " + tok} if tok else {})
+                return h._authorized(path)
+
+            _g = type(gw)({"token": "ADMIN", "public_token": "PUB"})
+            check(_probe(_g, "/console", "ADMIN") and not _probe(_g, "/console", "PUB"),
+                  "网关：管理台只认管理令牌（公开令牌被拒）")
+            check(not _probe(_g, "/console?token=PUB", "PUB"),
+                  "网关：?token= 携带公开令牌也进不了管理台")
+            _h = _ProbeHandler(_g, "/api/chat", {"Authorization": "Bearer PUB"})
+            check(_h._authorized("/api/chat", admin=False)
+                  and not _h._authorized("/api/chat", admin=True),
+                  "网关：公开令牌仅限对话作用域")
+            check(_probe(_g, "/embed.js") and _probe(_g, "/healthz"),
+                  "网关：/embed.js 与 /healthz 无条件可达")
+            _g2 = type(gw)({"token": "ADMIN"})       # 没配 public_token
+            check(_g2.serve_token == "",
+                  "★ 未配 public_token 时 serve_token 为空（绝不回落管理令牌）")
+            check(_ProbeHandler(_g2, "/")._authorized("/") is False,
+                  "★ 未配 public_token 时挂件页不公开（不泄漏管理令牌）")
+            check(_ProbeHandler(_g2, "/",
+                                {"Authorization": "Bearer ADMIN"})._authorized("/"),
+                  "网关：站长用管理令牌仍可打开挂件页")
+            _g3 = type(gw)({})                       # 无令牌 = 开发开放模式
+            check(_ProbeHandler(_g3, "/console")._authorized("/console"),
+                  "网关：无令牌配置时保持开放（兼容本机开发）")
+
             # ---- v0.2.1 收尾阶段不变式 ----
             # 1) on_reply_final 对**每条**回复路径恰好跑一次（生成/能力/模板）。
             class _Probe(BasePlugin):

{pasm_framework-0.3.0 → pasm_framework-0.4.0}/pasm_framework/__main__.py

@@ -6,8 +6,9 @@
     pasm-framework plugins            列出内置插件与默认开关
     pasm-framework config [--preset X | --file f.json] [--env]   查看解析后的开关表
     pasm-framework doctor             环境体检（能不能跑、缺什么）
-    pasm-framework new <dir> [--kind app|chatbot|game_npc] [--force]   生成项目
+    pasm-framework new <dir> [--kind app|chatbot|game_npc|customer_service] [--force]   生成项目
     pasm-framework serve [--port 8080] [--host 0.0.0.0] [--kb ./kb]   起一个演示客服
+    pasm-framework cs [--port 8080] [--name X]      一键起在线客服（双令牌+嵌入码+管理台）
 
 设计约束：只用标准库 ``argparse``，不引入 CLI 框架 —— 保证"装完就能跑"。
 """
@@ -210,6 +211,74 @@ def _cmd_serve(args) -> int:
     return 0
 
 
+def _cmd_cs(args) -> int:
+    """一键起在线客服：自动生成双令牌，打印可分享链接与嵌入代码。
+
+    面向"不懂代码也能跑"：一条命令拿到
+      · 访客对话页（可直接分享 / iframe 嵌入）
+      · 站长管理台（粘贴资料 → 立即生效）
+      · 一行 <script> 嵌入代码（任意语言开发的站点都能挂）
+    """
+    import time
+    import secrets
+
+    from .demo import make_demo_app
+
+    serve_token = args.serve_token or secrets.token_hex(8)
+    public_token = args.public_token or secrets.token_hex(8)
+
+    llm = None
+    if args.llm_provider:
+        llm = {"provider": args.llm_provider}
+        if args.llm_model:
+            llm["model"] = args.llm_model
+        if args.llm_key:
+            llm["api_key"] = args.llm_key
+
+    app = make_demo_app(kb_dir=args.kb, llm=llm, host=args.host, port=args.port,
+                        token=serve_token, public_token=public_token,
+                        preset_name="chatbot")
+
+    shown_host = args.host if args.host != "0.0.0.0" else "127.0.0.1"
+    base = "http://%s:%d" % (shown_host, args.port)
+    lan = "http://<你的局域网IP>:%d" % args.port if args.host == "0.0.0.0" else base
+    # 属性名必须与 embed.js 读取的一致（data-pasm-token），否则挂件拿不到令牌。
+    embed = ("<script src=\"%s/embed.js\"\n"
+             "        data-pasm-token=\"%s\"\n"
+             "        data-title=\"%s\"\n"
+             "        data-greeting=\"你好！我是智能客服，有什么可以帮你？\"\n"
+             "        data-color=\"#2563eb\" defer></script>"
+             % (lan, public_token, args.name))
+
+    print("=" * 62)
+    print("在线客服已启动（%s）" % args.name)
+    print("=" * 62)
+    print("① 访客对话页（分享给客户 / 直接打开测试）:")
+    print("     %s/" % base)
+    print("② 站长管理台（粘贴资料 → 访客立即能答）:")
+    print("     %s/console?token=%s" % (base, serve_token))
+    print("     （链接已带管理令牌；打开后令牌会从地址栏消失，存进本次会话）")
+    print("③ 嵌入你自己的站点（任意语言：PHP/Java/Node/静态页均可）:")
+    print("     在 </body> 前加这几行：")
+    print("       %s" % embed.replace("\n", "\n       "))
+    print("④ REST 接口（程序对接）:")
+    print("     POST %s/api/chat   {\"text\": \"...\"}" % base)
+    print("     Header: Authorization: Bearer %s" % public_token)
+    print("-" * 62)
+    print("令牌说明：公开令牌只能对话；管理令牌才能导入资料/看会话。")
+    print("资料来源：启动时自动导入演示 FAQ；往 %s 放 .txt/.md 或在管理台粘贴即可。" % (args.kb or "~/.pasm_framework/kb"))
+    print("Ctrl+C 退出")
+    print("=" * 62)
+    try:
+        app.serve()
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\n已停止。")
+        app.close()
+    return 0
+
+
 def main(argv=None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
     cmd = argv[0] if argv else "selftest"
@@ -260,6 +329,21 @@ def main(argv=None) -> int:
     p_srv.add_argument("--llm-model", default=None)
     p_srv.add_argument("--llm-key", default=None)
 
+    p_cs = sub.add_parser("cs", help="一键起在线客服（双令牌 + 可分享链接 + 嵌入代码）")
+    p_cs.add_argument("--name", default="在线客服", help="客服名（打印在横幅里）")
+    p_cs.add_argument("--host", default="127.0.0.1",
+                      help="0.0.0.0 表示允许局域网访问")
+    p_cs.add_argument("--port", type=int, default=8080)
+    p_cs.add_argument("--kb", default=None, help="知识库目录（默认 ~/.pasm_framework/kb）")
+    p_cs.add_argument("--serve-token", dest="serve_token", default=None,
+                      help="管理令牌（缺省自动生成）")
+    p_cs.add_argument("--public-token", dest="public_token", default=None,
+                      help="公开令牌（缺省自动生成）")
+    p_cs.add_argument("--llm-provider", default=None,
+                      help="openai / deepseek / ollama（不填则离线模式）")
+    p_cs.add_argument("--llm-model", default=None)
+    p_cs.add_argument("--llm-key", default=None)
+
     try:
         ns = parser.parse_args(argv)
     except SystemExit as ex:            # argparse 的报错也是退出
@@ -271,6 +355,7 @@ def main(argv=None) -> int:
         "doctor": _cmd_doctor,
         "new": _cmd_new,
         "serve": _cmd_serve,
+        "cs": _cmd_cs,
     }.get(ns.sub)
     if handler is None:
         print(USAGE)

{pasm_framework-0.3.0 → pasm_framework-0.4.0}/pasm_framework/application.py

@@ -106,8 +106,11 @@ class BaseApplication(BaseAgent):
         去重按 ``title``；凡"有依据的知识"（领域 / 知识库）都带 ``source``，
         纯对话记忆（episodic）不带 —— 应用可据此区分"资料"与"闲聊"。
         """
-        hits = super().recall(query, k=k)
-        seen = {h.get("title") for h in hits}
+        # 对话记忆（episodic）—— 不带 source。
+        memories = super().recall(query, k=k)
+        seen = {h.get("title") for h in memories}
+        # 「有依据的知识」单独收集：领域 + 知识库。
+        sourced: List[Dict[str, Any]] = []
 
         if hasattr(self.domain, "knowledge_for"):
             try:
@@ -118,7 +121,7 @@ class BaseApplication(BaseAgent):
                     it = dict(item)
                     it.setdefault("source",
                                   "domain:%s" % type(self.domain).__name__)
-                    hits.append(it)
+                    sourced.append(it)
                     seen.add(it.get("title"))
             except Exception:
                 pass
@@ -132,12 +135,41 @@ class BaseApplication(BaseAgent):
                     for item in kb.recall(query, k=k):
                         if item.get("title") in seen:
                             continue
-                        hits.append(item)
+                        sourced.append(item)
                         seen.add(item.get("title"))
                 except Exception:
                     pass
 
-        return hits[:k] if k else hits
+        # 排序：**有依据的知识优先于对话记忆**。
+        # 否则"上次聊过一句提到过某个词"的闲聊记忆会排到 FAQ 前面，
+        # 客服就变成"答非所问"（实测过：闲聊记忆抢占，资料库排到了后面）。
+        merged = sourced + memories
+        return merged[:k] if k else merged
+
+    # ---- 区分「资料」与「闲聊」---------------------------------
+    def knowledge_facts(
+        self, facts: Optional[List[Dict[str, Any]]]
+    ) -> List[Dict[str, Any]]:
+        """从检索结果里挑出**有依据的知识**（带 ``source`` 的那些）。
+
+        为什么必须有这个方法：``recall()`` 返回的是**混合**结果 ——
+        引擎的对话记忆（episodic，不带 ``source``）+ 领域知识 + 知识库资料
+        （都带 ``source``）。写 ``_render_reply`` 时如果直接取 ``facts[0]``
+        就会把"上一轮用户自己说过的话"当成资料答回去。
+
+        实测过的翻车现场：用户问"你们老板叫什么"，
+        系统把上一轮的"积分怎么算"当成资料答了出来 ——
+        因为那条对话记忆被检索命中，而它**不是知识**。
+
+        所以任何"就资料作答"的回复策略都应该先过这个过滤器::
+
+            def _render_reply(self, text, facts, mood):
+                k = self.knowledge_facts(facts)
+                return k[0]["brief"] if k else "抱歉，我暂时没有相关资料。"
+
+        保持原顺序（资料在前、且各自内部已按相关度排序），只做过滤不做重排。
+        """
+        return [f for f in (facts or []) if f.get("source")]
 
     # ---- 对话（覆盖基类，支持注入已检索事实）-----------------
     def chat(self, text: str, facts: Optional[List[Dict[str, Any]]] = None) -> str:

{pasm_framework-0.3.0 → pasm_framework-0.4.0}/pasm_framework/demo.py

@@ -53,10 +53,14 @@ def make_demo_app(
     agent_id: str = "pasm-demo",
     preset_name: str = "chatbot",
     token: Optional[str] = None,
+    public_token: Optional[str] = None,
     teach: bool = True,
 ) -> DemoAgent:
     """构造演示应用（已导入 :data:`DEMO_FAQ`）。
 
+    ``token`` 是**管理令牌**（全部接口）；``public_token`` 是**访客令牌**
+    （仅对话接口，可安全嵌进第三方站点）。只给 ``token`` 时行为同旧版。
+
     >>> from pasm_framework.demo import make_demo_app
     >>> app = make_demo_app(port=8099)
     >>> "退货" in app.ask("怎么退货？")
@@ -65,6 +69,8 @@ def make_demo_app(
     gw: Dict[str, Any] = {"enabled": True, "config": {"host": host, "port": port}}
     if token:
         gw["config"]["token"] = token
+    if public_token:
+        gw["config"]["public_token"] = public_token
     kb: Dict[str, Any] = {"enabled": True}
     if kb_dir:
         kb["config"] = {"kb_dir": kb_dir}