beacon-mfg-mcp 0.1.4 → 1.3.0

package/README.md

@@ -51,6 +51,12 @@ npm i -g beacon-mfg-mcp      # 或不安装直接用 npx beacon-mfg-mcp
 
 不填 `BEACON_REPO` 时默认走 `https://beacon-mfg.pages.dev`，即开即用。
 
+> **v1.3.0 起 npm 包自带 `rfq-kernel`**：`start_sourcing` / `answer_sourcing` / `refine_sourcing`
+> 三个寻源 tool 依赖该桥接模块。`prepack` 会把仓库平级的 `skills/rfq-kernel` 打进包内，
+> 所以 `npm i -g beacon-mfg-mcp`（≥1.3.0）后 6 个 tool 全部可用。
+> ⚠️ **早于此版本的 npm 包不含 rfq-kernel**，那 3 个寻源 tool 会返回「桥接未就绪」——
+> 要么升级到 1.3.0+，要么改用「方式 A / 方式 B」源码接入。
+
 **方式 A — 本地 git 仓库（离线 + 隐私安全 + 零 CF 流量）**
 
 ```jsonc
@@ -66,9 +72,15 @@ npm i -g beacon-mfg-mcp      # 或不安装直接用 npx beacon-mfg-mcp
 }
 ```
 
-本地模式只通过 `git show HEAD:<path>` 读取**已提交**内容——这是掩码态手机号（138\*\*\*\*0000），
+本地模式通过 `git show HEAD:<path>` 读取已提交内容——这是掩码态手机号（138\*\*\*\*0000），
 且不会触发 `maskphone` 的 smudge、不会碰 git index 锁。
 
+> **闭合检索缺口（v1.3.0 新增）**：默认 `BEACON_WORKTREE=1`，本地模式会**优先读工作树文件**
+> （含尚未提交 / 刚修改的数据），只在文件缺失或单对象 JSON 解析失败（cron 写入中途的半成品）时
+> 退回 `git show HEAD` 已提交快照，再否则走 HTTP。这样 cron 刚写入、尚未 `git commit` 的记录也能被
+> `get_vendor` / `search_vendors` 检索到。设 `BEACON_WORKTREE=0` 可恢复「只读已提交快照」的严格行为
+> （仍不触发 smudge / 不碰 index 锁）。
+
 **方式 B — Cloudflare Pages 公开端点（最省事，需联网）**
 
 不设置 `BEACON_REPO` 即可，默认基址 `https://beacon-mfg.pages.dev`。可改：
@@ -80,6 +92,41 @@ npm i -g beacon-mfg-mcp      # 或不安装直接用 npx beacon-mfg-mcp
 HTTP 模式带正确 `User-Agent` 与 `ETag` 304 缓存（与 App 同款策略），并落盘 `~/.cache/beacon-mcp-cache`，
 重复查询零传输。CF 部署版手机号可能是全号——隐私敏感场景请用方式 A。
 
+## 远程 HTTP 端点（Streamable HTTP）
+
+`server.py` 本体是 **stdio**；`http_server.py` 是它的 **HTTP 传输适配层**（复用同一份 `_dispatch`/`TOOLS`，
+业务逻辑一行没动，所以 stdio 与 HTTP 两条链路不会分叉）。
+
+```bash
+MCP_PORT=8787 python http_server.py      # 默认 0.0.0.0:8787，端点 /mcp，健康检查 /health
+```
+
+客户端配置（`type: http` 即 Streamable HTTP）：
+
+```jsonc
+{ "mcpServers": { "beacon-mfg": { "type": "http", "url": "https://<你的地址>/mcp" } } }
+```
+
+**先用隧道验证**（零成本、今天即可验证协议，但 PC 关机即失效）：
+
+```bash
+cloudflared tunnel --url http://localhost:8787     # 拿到 https://xxx.trycloudflare.com
+# 客户端填 https://xxx.trycloudflare.com/mcp
+```
+
+> ⚠️ **现状说明**：`*.trycloudflare.com` 是本机隧道，**不是 7×24**。
+> 若要做成真正常驻的远程端点，需要一台常驻 Python 宿主（云主机 / 容器 PaaS）。
+> 注意 `server.py` 用了 `ThreadPoolExecutor` 并行拉分片，因此**不适合** Cloudflare Python Workers（beta，线程受限）。
+
+### 已实测（本地 HTTP 全流程）
+
+`GET /health` 200 → `POST /mcp initialize` 200 并下发 `Mcp-Session-Id` →
+`notifications/initialized` **202 空体** → `tools/list` 6 个 tool →
+`tools/call search_vendors{city:苏州, query:"精密 加工"}` 返回 **3742 条命中**（`via_index: true`）。
+
+实现要点：`initialize` 响应 `protocolVersion: 2024-11-05`；本服务**不提供** server→client 的 SSE
+主动推送（只读检索不需要），故 `GET /mcp` 返回 405 —— 这是 MCP 规范允许的（MAY NOT）。
+
 ## 影响评估（对现有系统为零影响）
 
 ### 1) 对 Android App（Beacon-MFG）— 无影响
@@ -94,8 +141,10 @@ cron / GUI 是**写方**：`fetch_batch` / `postfetch` 改写 `data/gb`、`data/
 （经 maskphone clean 过滤脱敏），再发布到 R2 / Pages / GitHub（`fetch_batch` 还持有仓库级 PID 锁
 `.fetch_batch.lock`）。MCP 是**只读**且不调用任何后端脚本，因此：
 
-- **硬规则 1 — 只读已发布快照，不碰实时工作树**：MCP 只从「CF 公开端点」或「`git show HEAD:` 已提交内容」
-  读取，**绝不读 cron 正在写的实时工作树**，避免读到半成品 JSON。本服务严格按此实现。
+- **硬规则 1 — 默认只读已提交快照，工作树读取受控**：MCP 只从「CF 公开端点」或「`git show HEAD:` 已提交内容」
+  读取；`BEACON_WORKTREE=1`（默认）时额外优先读工作树文件以闭合检索缺口，但**仅直接 `open()` 工作树、
+  不触发 `git checkout`/smudge、不碰 index 锁**，因此不会重掩码手机号，也只在单对象 JSON 解析失败
+  （半成品）时退回 HEAD，避免读到损坏内容。`BEACON_WORKTREE=0` 则恢复纯「只读已提交快照」。
 - **硬规则 2 — 绝不 `git checkout` / `git restore` 本仓库**：这是历史「42578 个手机号被无声掩码」事故的
   根因——smudge 过滤器会把 index 里的脱敏内容写回工作树，且 `git status` 仍显干净。本服务**只**用
   `git show HEAD:`（不触发 smudge、不碰 index 锁），从根上避开。
@@ -120,10 +169,11 @@ MCP 服务有两种发布渠道（详见 `mcp/RELEASE.md`）：
 
 - **GitHub Release（已配 CI）**：推送 `mcp-v*` 标签即由 `.github/workflows/mcp-release.yml`
   自动打包 `mcp/` 目录为 `beacon-mfg-mcp-mcp-vX.Y.Z.tar.gz` 并创建 Release。
-- **npm 包（已发布 ✅）**：`beacon-mfg-mcp` 已于 **2026-09-24** 发布到 npm 公共仓库，当前版本 **`0.1.3`**
+- **npm 包（已发布 ✅）**：`beacon-mfg-mcp` 已发布到 npm 公共仓库，当前版本 **`1.3.0`**
   （<https://www.npmjs.com/package/beacon-mfg-mcp>）。第三方可直接 `npm i -g beacon-mfg-mcp`
   或 `npx beacon-mfg-mcp`，客户端配置 `"command": "beacon-mfg-mcp"` 即可，无需 clone、无需填路径。
-  已实测：安装 → MCP 握手 → `tools/list` 全通（暴露 6 个 tool）。
+  **1.3.0 起 npm 包自带 rfq-kernel**，安装 → MCP 握手 → `tools/list` 暴露 6 个 tool 且全部可用
+  （含 `start/answer/refine_sourcing` 三个寻源 tool；更早版本不含该桥接，那 3 个 tool 会降级）。
 
 ### 发布到 npm 的步骤（需要 Access Token，不是 2FA 种子）
 

package/RELEASE.md

@@ -1,4 +1,4 @@
-# Beacon-MFG 只读 MCP 服务 · v0.1.0
+# Beacon-MFG 只读 MCP 服务 · v1.3.0
 
 让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / WorkBuddy 等）能够
 **检索与调用**已发布到 Cloudflare Pages（或 GitHub）的灯塔工厂供应商数据，
@@ -8,17 +8,31 @@
 MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流水线**不进 MCP、不暴露、不持密钥**，
 也不会落在任何写路径上。对 Android App 与 cron/GUI 流水线**零影响**（详见 `mcp/README.md`）。
 
-## 三个只读 tool
+## 六个只读 tool
 | tool | 用途 | 关键参数 |
 |------|------|----------|
 | `search_vendors` | 按 关键词 / 城市 / 国标码 检索，返回精简档案 | `query` `city` `gb` `limit` `offset` |
 | `get_vendor` | 按 id（+国标码）取完整中文档案 | `id`（必填） `gb`（可选） |
 | `get_capability_card` | 按 id 取能力卡（工艺/设备/产能/认证） | `id`（必填） |
+| `start_sourcing` | 【客户 agent 自动触发】识别找厂/代工/采购意图 → 品类识别→宽召回→澄清，返回 `session_id` | `demand_text`（必填） `audience_id` |
+| `answer_sourcing` | 续接澄清轮次：写回客户答案，返回下一轮澄清或初选列表 | `session_id`（必填） `answers` |
+| `refine_sourcing` | 推荐轮次交互：`details`/`more`/`best` | `session_id`（必填） `action` `value` |
+
+后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
+依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
+
+## 本次更新（v1.3.0）
+- **npm 包自带 rfq-kernel**：`prepack` 会把 `skills/rfq-kernel` 打进包内，因此 `npm i -g beacon-mfg-mcp`
+  安装后 6 个 tool 全部可用（早于此版本的 npm 包不含该桥接，3 个寻源 tool 会降级）。
+  GitHub Release tarball 同步包含 `rfq-kernel/`。
+- **闭合检索缺口**：本地 git 模式默认 `BEACON_WORKTREE=1`，优先读工作树文件（含未提交/刚修改的数据），
+  仅在文件缺失或单对象 JSON 解析失败（半成品）时退回 `git show HEAD`，再否则走 HTTP。
+  设 `BEACON_WORKTREE=0` 可恢复「只读已提交快照」的严格行为。
 
 ## 安装（三选一）
 
 ### 1. 从 GitHub Release 下载（推荐，零依赖）
-下载本 Release 的 `beacon-mfg-mcp-mcp-v0.1.0.tar.gz`，解压后：
+下载本 Release 的 `beacon-mfg-mcp-mcp-v1.3.0.tar.gz`，解压后：
 ```jsonc
 {
   "mcpServers": {
@@ -53,8 +67,9 @@ git clone https://github.com/eiry16/beacon-mfg.git
 ```
 
 ## 环境变量
-- `BEACON_REPO`：本地 git 仓库路径；设了就用 `git show HEAD:` 读（推荐：离线 + 掩码态隐私安全）。
+- `BEACON_REPO`：本地 git 仓库路径；设了就用 `git show HEAD:` + 工作树 读（推荐：离线 + 掩码态隐私安全）。
 - `BEACON_SOURCE`：HTTP 基址，默认 `https://beacon-mfg.pages.dev`（可改自定义域名）。
+- `BEACON_WORKTREE`：本地模式是否优先读工作树（默认 `1`；设 `0` 恢复「只读已提交快照」）。
 
 ## 许可
 MIT

package/copy-rfk.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+// prepack 步骤：把仓库平级的 skills/rfq-kernel 拷进 mcp/rfq-kernel，
+// 使 npm 包与 GitHub Release tarball 自带 rfq-kernel —— 否则 start_sourcing /
+// answer_sourcing / refine_sourcing 三个寻源 tool 会因桥接缺失而降级失效。
+// 幂等：每次先清掉旧副本再拷；跳过 __pycache__ 与 *.pyc。
+const fs = require('fs');
+const path = require('path');
+
+const HERE = __dirname;                 // mcp
+const SRC = path.resolve(HERE, '..', 'skills', 'rfq-kernel');
+const DEST = path.join(HERE, 'rfq-kernel');
+
+function rmSync(p) {
+  if (!fs.existsSync(p)) return;
+  const st = fs.statSync(p);
+  if (st.isDirectory()) {
+    for (const e of fs.readdirSync(p)) rmSync(path.join(p, e));
+    try { fs.rmdirSync(p); } catch (e) {}
+  } else {
+    try { fs.unlinkSync(p); } catch (e) {}
+  }
+}
+
+function copySync(src, dest) {
+  const st = fs.statSync(src);
+  if (st.isDirectory()) {
+    if (path.basename(src) === '__pycache__') return;   // 不携带编译缓存
+    fs.mkdirSync(dest, { recursive: true });
+    for (const e of fs.readdirSync(src)) copySync(path.join(src, e), path.join(dest, e));
+  } else {
+    if (src.endsWith('.pyc')) return;
+    fs.copyFileSync(src, dest);
+  }
+}
+
+if (!fs.existsSync(SRC) || !fs.statSync(SRC).isDirectory()) {
+  process.stderr.write('[copy-rfk] 源目录不存在，跳过：' + SRC + '\n');
+  process.exit(0);
+}
+rmSync(DEST);
+copySync(SRC, DEST);
+rmSync(path.join(DEST, '__pycache__'));
+process.stdout.write('[copy-rfk] 已同步 rfq-kernel -> ' + DEST + '\n');

package/http_server.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""beacon-mfg MCP —— Streamable HTTP 传输适配层（远程端点的第一步）。
+
+设计要点
+--------
+* **不改动 server.py 本体**：直接复用它的 `_dispatch` / `TOOLS`，业务逻辑一行不动，
+  因此「本地 stdio」与「远程 HTTP」两条链路共用同一份检索实现，不会分叉。
+* 协议：MCP **Streamable HTTP**（2025-03-26）。请求一律 `POST /mcp`，
+  响应 `application/json`；`initialize` 时下发 `Mcp-Session-Id`。
+* 本服务器**不提供** server→client 的 SSE 主动推送（只读检索不需要），
+  故 `GET /mcp` 返回 405 —— 这是规范允许的（MAY NOT）。
+* 仅用 Python 标准库，与 server.py 的零依赖原则一致。
+
+用法
+----
+    MCP_PORT=8787 python http_server.py
+    # 健康检查：GET /health
+    # 客户端配置：{ "type": "http", "url": "https://<你的地址>/mcp" }
+"""
+
+import json
+import os
+import sys
+import uuid
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+# 保证可直接 `python http_server.py` 运行（同级 import server）
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import server as S  # noqa: E402
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_INFO = {"name": "beacon-mfg-readonly", "version": "1.3.0"}
+MCP_PATH = os.environ.get("MCP_PATH", "/mcp")
+
+_sessions = set()
+_lock = threading.Lock()
+
+
+def _log(msg: str) -> None:
+    sys.stderr.write("[beacon-mcp-http] " + msg + "\n")
+    sys.stderr.flush()
+
+
+def _result(mid, result):
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def _error(mid, code, message):
+    return {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": message}}
+
+
+def _handle_msg(msg):
+    """处理单条 JSON-RPC 消息。
+
+    返回 (响应对象 | None, 是否需要新建会话)。
+    响应为 None 表示这是通知（notification），按规范回 202、无 body。
+    """
+    if not isinstance(msg, dict):
+        return _error(None, -32600, "Invalid Request"), False
+
+    method = msg.get("method") or ""
+    mid = msg.get("id")
+
+    if method == "initialize":
+        return _result(mid, {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": SERVER_INFO,
+        }), True
+
+    if method.startswith("notifications/"):
+        return None, False
+
+    if method == "ping":
+        return _result(mid, {}), False
+
+    if method == "tools/list":
+        return _result(mid, {"tools": S.TOOLS}), False
+
+    if method == "tools/call":
+        params = msg.get("params") or {}
+        name = params.get("name", "")
+        res = S._dispatch(name, params.get("arguments") or {})
+        return _result(mid, {
+            "content": [{"type": "text", "text": json.dumps(res, ensure_ascii=False)}],
+            "isError": isinstance(res, dict) and "error" in res,
+        }), False
+
+    if mid is not None:
+        return _result(mid, {}), False
+    return None, False
+
+
+class MCPHandler(BaseHTTPRequestHandler):
+    server_version = "beacon-mcp-http/1.0"
+    protocol_version = "HTTP/1.1"
+
+    # ── 工具方法 ──────────────────────────────────────────────
+    def _cors(self):
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS")
+        self.send_header(
+            "Access-Control-Allow-Headers",
+            "Content-Type, Accept, Mcp-Session-Id, MCP-Protocol-Version, Authorization",
+        )
+        self.send_header("Access-Control-Expose-Headers", "Mcp-Session-Id")
+
+    def _send_json(self, code, obj, sid=None, body_empty=False):
+        payload = b"" if body_empty else json.dumps(obj, ensure_ascii=False).encode("utf-8")
+        self.send_response(code)
+        if not body_empty:
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(payload)))
+        else:
+            self.send_header("Content-Length", "0")
+        if sid:
+            self.send_header("Mcp-Session-Id", sid)
+        self._cors()
+        self.end_headers()
+        if payload:
+            self.wfile.write(payload)
+
+    def log_message(self, fmt, *args):  # 静音默认访问日志，统一走 stderr
+        _log(fmt % args)
+
+    # ── 路由 ─────────────────────────────────────────────────
+    def do_OPTIONS(self):
+        self.send_response(204)
+        self._cors()
+        self.end_headers()
+
+    def do_GET(self):
+        path = self.path.split("?")[0].rstrip("/")
+        if path.endswith("/health"):
+            self._send_json(200, {
+                "ok": True,
+                "server": SERVER_INFO,
+                "protocolVersion": PROTOCOL_VERSION,
+                "mcpPath": MCP_PATH,
+                "source": getattr(S, "BEACON_SOURCE", ""),
+                "tools": [t["name"] for t in S.TOOLS],
+            })
+            return
+        if path == MCP_PATH.rstrip("/"):
+            # 本服务不提供 server→client 的 SSE 主动推送（只读检索不需要）
+            self._send_json(405, _error(None, -32000, "SSE stream not offered; use POST"))
+            return
+        self._send_json(404, _error(None, -32000, "not found"))
+
+    def do_DELETE(self):
+        path = self.path.split("?")[0].rstrip("/")
+        if path == MCP_PATH.rstrip("/"):
+            sid = self.headers.get("Mcp-Session-Id")
+            if sid:
+                with _lock:
+                    _sessions.discard(sid)
+            self.send_response(204)
+            self._cors()
+            self.end_headers()
+            return
+        self._send_json(404, _error(None, -32000, "not found"))
+
+    def do_POST(self):
+        path = self.path.split("?")[0].rstrip("/")
+        if path != MCP_PATH.rstrip("/"):
+            self._send_json(404, _error(None, -32000, "not found"))
+            return
+
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length).decode("utf-8") if length else ""
+        try:
+            msg = json.loads(raw)
+        except Exception:
+            self._send_json(400, _error(None, -32700, "Parse error"))
+            return
+
+        sid = self.headers.get("Mcp-Session-Id")
+
+        # 批量请求：逐条处理，整体回数组
+        if isinstance(msg, list):
+            out = []
+            for m in msg:
+                resp, _ = _handle_msg(m)
+                if resp is not None:
+                    out.append(resp)
+            self._send_json(200, out, sid=sid)
+            return
+
+        try:
+            resp, need_new_session = _handle_msg(msg)
+        except BaseException as e:  # noqa: BLE001
+            self._send_json(500, _error(msg.get("id"), -32603, f"Internal error: {e}"))
+            return
+
+        if need_new_session:
+            sid = uuid.uuid4().hex
+            with _lock:
+                _sessions.add(sid)
+
+        if resp is None:
+            self._send_json(202, None, sid=sid, body_empty=True)
+            return
+        self._send_json(200, resp, sid=sid)
+
+
+def main() -> None:
+    host = os.environ.get("MCP_HOST", "0.0.0.0")
+    port = int(os.environ.get("MCP_PORT", "8787"))
+    httpd = ThreadingHTTPServer((host, port), MCPHandler)
+    _log(f"listening http://{host}:{port}{MCP_PATH}  source={getattr(S, 'BEACON_SOURCE', '')}")
+    _log(f"tools: {[t['name'] for t in S.TOOLS]}")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,35 +1,42 @@
-{
-  "name": "beacon-mfg-mcp",
-  "version": "0.1.4",
-  "description": "Read-only MCP server exposing the BeaconMFG灯塔工厂 supplier directory (search vendors, get vendor detail, get capability card) to any MCP-compatible agent. No API key, no repo clone required.",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "beacon-mfg",
-    "suppliers",
-    "manufacturing",
-    "china"
-  ],
-  "homepage": "https://github.com/eiry16/beacon-mfg#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/eiry16/beacon-mfg.git"
-  },
-  "bugs": {
-    "url": "https://github.com/eiry16/beacon-mfg/issues"
-  },
-  "license": "MIT",
-  "bin": {
-    "beacon-mfg-mcp": "bin/beacon-mfg-mcp.js"
-  },
-  "files": [
-    "server.py",
-    "bin/",
-    "README.md",
-    "RELEASE.md"
-  ],
-  "engines": {
-    "node": ">=16"
-  },
-  "dependencies": {}
-}
+{
+  "name": "beacon-mfg-mcp",
+  "version": "1.3.0",
+  "description": "Read-only MCP server exposing the BeaconMFG灯塔工厂 supplier directory (search vendors, get vendor detail, get capability card, multi-turn sourcing) to any MCP-compatible agent. No API key required.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "beacon-mfg",
+    "suppliers",
+    "manufacturing",
+    "china",
+    "sourcing"
+  ],
+  "homepage": "https://github.com/eiry16/beacon-mfg#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiry16/beacon-mfg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiry16/beacon-mfg/issues"
+  },
+  "license": "MIT",
+  "bin": {
+    "beacon-mfg-mcp": "bin/beacon-mfg-mcp.js"
+  },
+  "files": [
+    "server.py",
+    "http_server.py",
+    "bin/",
+    "rfq-kernel/",
+    "copy-rfk.js",
+    "README.md",
+    "RELEASE.md"
+  ],
+  "scripts": {
+    "prepack": "node copy-rfk.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {}
+}

package/rfq-kernel/README.md

@@ -0,0 +1,98 @@
+# rfq-kernel（已移植进 beacon-mfg）
+
+原 `rfq-kernel/` 原型（需求侧接客引擎）整体移植到 beacon-mfg，作为
+`skills/rfq-kernel/`。后续修改都在 beacon-mfg 项目内进行。
+
+## 目录
+
+```
+skills/rfq-kernel/
+  SKILL.md                        # agent 侧 skill 说明，含与能力卡的关系
+  demo.py                         # 端到端演示（示例场景 + 认证强校验 + 真实卡接入）
+  schema/
+    rfq.schema.json               # 标准询价单 RFQ
+    envelope.schema.json          # 工厂响应统一信封
+    supplier_card.schema.json     # 标准化供应商卡（含认证对象强校验）
+  industry/                       # 行业 pack（11 个）：drinkware / mattress / sheet_metal /
+                                  #   machining / injection / die_casting / electronics /
+                                  #   surface_treatment / fasteners / raw_material /
+                                  #   material_handling（输送/物流搬运，2026-09-22 新增）
+  audience/                       # 客户视图：intl_buyer / domestic_downstream
+  suppliers/                      # 示例供应商卡（认证已改为对象格式）
+  src/
+    kernel.py                     # 协议内核 + cert_satisfied
+    intake.py                     # 需求侧流程（解析/召回/澄清/精筛/投影）
+    beacon_adapter.py             # beacon-mfg L1 能力卡 → 标准供应商卡（单向）
+```
+
+## 三个关键结论（对应主人的三问）
+
+1. **固化接入**：rfq-kernel 现在住在 beacon-mfg 内，通过 `beacon_adapter.py`
+   单向消费 beacon-mfg 的真实能力卡，不重写、不替代它。
+
+2. **认证必须三方可验证**：`certifications` 改为对象 `{code, cert_no, issuer,
+   valid_until, verified}`。`cert_satisfied()` 规定——**只有 `verified=true`
+   且 `cert_no` 非空才「作数」**。ISO9001 这类认证需要上传证书号并被核验才算数，
+   裸声称等同没有（见 demo 的「认证强校验单元」）。
+
+3. **它和能力卡不是一回事，不能直接替代**：
+   - beacon-mfg 能力卡 = 供给数据（工厂能做什么），由采集/认领流水线生成。
+   - rfq-kernel = 需求解析 + 匹配引擎，能力卡是它的输入。
+   - **能跑通**：`beacon_adapter` 把真实卡转成标准供应商卡后，内核零改动即可匹配
+     （新增 `sheet_metal` pack 验证）。但今天 beacon-mfg 自动卡 `limits` 全 null、
+     `certifications` 为 null，**匹配会优雅降级**——交期/认证标「需向工厂确认」，
+     而非编造数字。这正是「静态优先、动态降级」的设计。
+
+## 验证
+
+```bash
+cd skills/rfq-kernel && PYTHONIOENCODING=utf-8 python demo.py
+```
+
+预期：示例场景 3 家可承接 / 2 家结构化拒单；认证强校验三档（满足/未核验/缺失）；
+真实卡 `CN-MFG-0029509` 经适配器接入后工艺匹配但硬指标全空 → 降级不中断；
+跨行业 mattress 复用同一内核。
+
+## 生产接线（怎么真正跑起来）
+
+两层协作，互不替代：
+
+| 层 | 位置 | 职责 |
+|---|---|---|
+| 需求侧匹配 | `skills/rfq-kernel/`（本技能） | 模糊需求 → 宽召回 → 澄清 → 精筛 → 结构化 RFQ 信封 + 候选 |
+| 供给侧投递 | `server/routers/rfq.py`（`POST /v1/rfq`） | 读候选卡的 `rfq` 块拿入口 → 投递 → 收讫确认 → 审计存证 |
+
+- **适配器读权威卡路径**：`beacon_adapter.load_real_card()` 优先读
+  `skills/registry/capability/{id}.json`（与 `rfq.py` 投递读取同源），`skills/vendors/{id}/`
+  兜底。生产环境不要再 grep `data/gb` 分片。
+- **适配器携带三个关键信息**：能力卡上的 `rfq` 块（`endpoint`/`protocol`，决定能否投递）、
+  `claim.status`（信任等级锚点）、`quality.certifications`（按 `evidence` + `number`
+  判定 `verified`）。
+- **客户 Agent 流程**：rfq-kernel 匹配出候选 → 对带 `rfq` 块的候选调用 `POST /v1/rfq`
+  投递（平台中转：强制 Bearer 凭证、审计存证、非本机地址默认不真实投递）。
+
+## 企业怎么"按新方案建立 skill"（空 skill 无意义 / 认领入口已存在）
+
+- **不用建空 skill**：框架就是能力卡本身。自动采集的卡 `claim.status=unclaimed`、
+  limits 全 null，正是 14000+ 家爬来企业的现状——再写空 skill 只是重复现状。
+- **正确做法 = 认领后自填**：走 `server/routers/claim.py` 微信验证码认领流
+  （App 端入口，对接 `docs/vendor-onboarding-design.html`），`claim.status` 由
+  `unclaimed→claimed→verified`，随后在卡上补全 `limits` / `materials` /
+  `quality.certifications` / `rfq` 块即可。
+- **RFQ 可达性 = 能力卡上的 `rfq` 块**（`{schema:"rfq/v1", protocol, endpoint}`）。
+  全库已有 7 家声明了 `rfq` 块，含两家非采集真实企业：苏州赤兔 `CN-I-0000001`、
+  耐特斯 `CN-MFG-0020317`。
+- `schema/supplier.schema.json` 的 `agent.capabilities`（含 `rfq`）是 L0 记录上的
+  Phase-1 预留字段，当前未启用；**生效的 RFQ 能力位是能力卡上的 `rfq` 块**。
+
+## 双源重叠已修复（mattress）
+
+床垫 pack 曾把 `BS5852/CA TB117/GB8624` 同时放进 `fire_retardant`（行业属性）和
+`certifications`（内核认证），造成两套真相。已砍掉：
+
+- `fire_retardant` 改为**物理阻燃特性**（`有阻燃处理` / `无阻燃处理` / `未指定`，`late` 档），
+  不再含标准码。
+- 标准合规（`BS5852/CA TB117/GB8624/CertiPUR/OEKO-TEX`）只留在 `certifications`，
+  作为三方可验证的合规真相源。
+- 示例卡 `suppliers/SUP-MT-001.json` 的 `industry_ext.fire_retardant` 同步改为 `["有阻燃处理"]`。
+- demo 验证：`certifications_required` 出现 `BS5852`，`fire_retardant` 不再出现标准码。