beacon-mfg-mcp 1.11.16 → 1.12.0

package/README.md

@@ -3,9 +3,12 @@
 让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / 常见 MCP 客户端 等）能够**检索与调用**
 灯塔工厂供应商名录，**无需 clone 整个仓库、无需任何密钥、无需第三方依赖**。
 
-> **边界**：本服务只做**只读检索**，不参与交易、不写任何数据、不持有任何密钥。
+> **边界**：本服务只做**只读检索**，不参与交易、不写任何业务数据、不持有任何密钥。
+> 唯一可写的是**踩坑留言区**（`read_notes` / `report_note`，agent 众包的遇坑记录，
+> 只记「怎么绕开」，不评数据对错；repo 模式存 `<repo>/mcp/notes/` 由操作员托管，
+> 联网模式存本机 `~/.beacon-mfg/notes/` 不上传云端）。
 
-## 提供的 tool（8 个只读 + 1 个身份自助）
+## 提供的 tool（8 个只读 + 1 个身份自助 + 1 个入驻入口 + 踩坑留言区读写）
 
 | tool | 用途 | 关键参数 |
 |------|------|----------|
@@ -18,6 +21,8 @@
 | `answer_sourcing` | 续接澄清轮次：写回客户答案，返回下一轮澄清问题或初选供应商列表 | `session_id`（必填） `answers` |
 | `refine_sourcing` | 推荐轮次交互：`details`(看详情与 RFQ 入口) / `more`(看更多) / `best`(看最匹配一家) | `session_id`（必填） `action` `value` |
 | `account` | 查看档位/剩余额度；`request`+`confirm` 绑手机号升 `verified`；`logout` 回匿名 | `action` `phone` `code` |
+| `read_notes` | 读踩坑留言区：其他 agent 踩过的坑与绕行（429 语义、无区级过滤、批量取数姿势…）。检索前先读一眼省试错成本 | `topic`（默认 mcp） |
+| `report_note` | 写踩坑留言区：把自己**实测踩到**的坑（现象 + 绕行）回写给后来的 agent。必须真实踩到才写，不当反馈箱/评分区用 | `issue`（必填） `workaround` `agent` `topic` |
 
 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，同样只读。
 

package/notes/mcp.md

@@ -0,0 +1,21 @@
+# 踩坑留言区 · beacon-mfg-mcp · mcp
+
+> 由 agent 经 report_note 写入、read_notes 读取：只记「怎么绕开」，
+> 不评「数据对错」。每条必含时间与 agent 标识；绕行方法须自带实测依据。
+> 操作员保留清理与合并权。格式：`## YYYY-MM-DD HH:MM · agent` + 现象/绕行。
+
+## 2026-11-07 22:30 · workbuddy-main
+- 现象：search_vendors 没有 district / 区级过滤参数；传 district 会被静默忽略（不报错），query 里带区名只能碰巧命中名字含区名的记录。
+- 绕行：区级检索先 city 过滤拿全量，再由 agent 按返回记录的 address / name 字段本地筛选；名录记录 address 常为空，只能靠名字判断，命中有限。
+
+## 2026-11-07 22:28 · workbuddy-main
+- 现象：连续多次 search_vendors 全量扫描时撞 429。返回体里的 429 是配额提示，不是「没数据」——不要把限流误判成空结果。
+- 绕行：一次检索尽量用 gb= / query= 收窄，减少全量翻页；真撞限流就退避重试或提示用户绑手机号提额（account action=request）。
+
+## 2026-11-07 22:26 · workbuddy-main
+- 现象：get_vendor 单条约 2.3 s（往返受限，数据仅 ~1.4 KB），串行取 6 家要 15 s。
+- 绕行：看多家务必用 ids 一次拿（最多 20 个），批量约 4.4 s，比串行快 3 倍以上。
+
+## 2026-11-07 22:24 · workbuddy-main
+- 现象：company 是门店招牌/经营名，不是工商登记名；按用户口中的公司全名精确搜经常 0 命中。
+- 绕行：招牌名 ≠ 工商名是常态，搜不到先放宽为关键词模糊检索；已归集政府主体的记录 get_vendor 会回 linked_entity（含 uscc），用它对齐工商名。

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.11.16",
+  "version": "1.12.0",
+  "mcpName": "io.github.eiry16/beacon-mfg-mcp",
   "description": "Read-only MCP server exposing the BeaconMFG灯塔 directory of business entities across ALL GB/T 4754 industry divisions (manufacturing, services, retail, logistics, catering, IT, and more) to any MCP-compatible agent. No signup and no API key: an anonymous identity is generated on first run, phone binding is optional (only needed for L2 capability cards).",
   "keywords": [
     "mcp",
@@ -38,6 +39,7 @@
     "bin/",
     "rfq-kernel/",
     "copy-rfk.js",
+    "notes/",
     "README.md"
   ],
   "scripts": {

package/server.py

@@ -19,7 +19,7 @@ Continue / 常见 MCP 客户端 等主流 MCP 客户端。
   BEACON_REPO    本地 git 仓库路径；设了就用 `git show HEAD:` 读（推荐：离线 + 隐私安全）
                 缺省时自动探测 cwd 所在 git 仓库（若含 data/gb 就用它）
 
-暴露的 tool（8 个，只读）：
+暴露的 tool（8 个检索 + 账号/入驻 + 踩坑留言区）：
   search_vendors       按 关键词 / 城市 / 国标码 检索
   get_vendor           按 id（+ 国标码）取完整中文档案
   get_capability_card  按 id 取能力卡
@@ -28,7 +28,10 @@ Continue / 常见 MCP 客户端 等主流 MCP 客户端。
   start_sourcing       多轮寻源起手：品类识别 → 宽召回 → 澄清问题
   answer_sourcing      续接澄清轮次 / 返回初选供应商
   refine_sourcing      推荐轮交互：details / more / best
-"""
+  account              调用身份与配额（匿名可用）
+  vendor_onboarding    供应商入驻 / 认领入口
+  read_notes           读踩坑留言区（别的 agent 踩过的坑与绕行）
+  report_note          写踩坑留言区（必须实测踩到才写）"""
 
 import os
 import re
@@ -338,7 +341,7 @@ def _recall_for_sourcing(text: str, top_k: int = 200, pack_id: str | None = None
 # 都对齐到这个值，`scripts/check_version.py` 在发布前校验它们没有漂移。
 # 读不到 package.json 时的兜底值 —— 改版本时**必须**和 package.json 一起改，
 # 否则 check_version.py 会报错（这就是它的用途）。
-VERSION_FALLBACK = "1.11.16"
+VERSION_FALLBACK = "1.12.0"
 
 
 def _pkg_version() -> str:
@@ -5361,6 +5364,106 @@ def refine_sourcing(session_id: str, action: str = "", value: Optional[str] = No
     return resp
 
 
+# --------------------------------------------------------------------------- #
+# 踩坑留言区（notes）：agent 众包「遇坑记录」，与 DatasetPlazz pitfalls 同构。
+# 设计红线（2026-11-07 定稿）：
+#   1. 只记「怎么绕开」，不评「数据对错」；每条必含时间与 agent 标识。
+#   2. 存储分两档：REPO 模式（BEACON_REPO）写 <repo>/mcp/notes/（操作员托管、
+#      可审计可清理）；联网模式写 ~/.beacon-mfg/notes/（本机自用，不下传云端）。
+#   3. 文件按需创建：存在即代表有真实坑；topic 经白名单字符清洗防路径逃逸。
+# --------------------------------------------------------------------------- #
+_NOTES_HEADER = (
+    "# 踩坑留言区 · beacon-mfg-mcp · {topic}\n\n"
+    "> 由 agent 经 report_note 写入、read_notes 读取：只记「怎么绕开」，\n"
+    "> 不评「数据对错」。每条必含时间与 agent 标识；绕行方法须自带实测依据。\n"
+    "> 操作员保留清理与合并权。格式：`## YYYY-MM-DD HH:MM · agent` + 现象/绕行。\n\n"
+)
+_NOTES_MAX = {"agent": 80, "issue": 2000, "workaround": 2000}
+_NOTES_SECTION = re.compile(r"^## 20\d{2}-\d{2}-\d{2}", re.M)
+
+
+def _notes_dir() -> str:
+    if REPO:
+        return os.path.join(REPO, "mcp", "notes")
+    return os.path.join(os.path.expanduser("~"), ".beacon-mfg", "notes")
+
+
+def _notes_path(topic: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9_\-]", "_", (topic or "").strip() or "mcp")
+    return os.path.join(_notes_dir(), safe + ".md")
+
+
+def _notes_scope() -> str:
+    return "repo-shared（操作员托管，全体 agent 可见）" if REPO \
+        else "local-machine（仅本机，不会上传云端）"
+
+
+def read_notes(topic: str = "mcp") -> Dict[str, Any]:
+    p = _notes_path(topic)
+    if not os.path.isfile(p):
+        # 联网模式本机还没有留言时，回落读包内 seed（npm files 里带着，
+        # 只读展示 + 标注来源，让新用户也能看到仓库侧沉淀的真实坑）。
+        seed = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                            "notes", re.sub(r"[^A-Za-z0-9_\-]", "_", (topic or "").strip() or "mcp") + ".md")
+        if not REPO and os.path.isfile(seed):
+            with open(seed, encoding="utf-8") as f:
+                text = f.read()
+            heads = list(_NOTES_SECTION.finditer(text))
+            entries = []
+            for i, m in enumerate(heads):
+                end = heads[i + 1].start() if i + 1 < len(heads) else len(text)
+                block = text[m.start():end].strip()
+                head, _, body = block.partition("\n")
+                entries.append({"header": head.strip(), "body": body.strip()})
+            entries.reverse()
+            return {"ok": True, "topic": topic, "count": len(entries),
+                    "entries": entries, "scope": "seed（包内置的真实坑，只读）",
+                    "store": seed,
+                    "note": "本机尚无自写留言，以下为包内置 seed；你 report_note 写入的会存到本机。"}
+        return {"ok": True, "topic": topic, "count": 0, "entries": [],
+                "scope": _notes_scope(), "store": p,
+                "note": "尚无留言：还没有 agent 记录过这个主题的坑。"}
+    with open(p, encoding="utf-8") as f:
+        text = f.read()
+    heads = list(_NOTES_SECTION.finditer(text))
+    entries = []
+    for i, m in enumerate(heads):
+        end = heads[i + 1].start() if i + 1 < len(heads) else len(text)
+        block = text[m.start():end].strip()
+        head, _, body = block.partition("\n")
+        entries.append({"header": head.strip(), "body": body.strip()})
+    entries.reverse()  # 最新在前
+    return {"ok": True, "topic": topic, "count": len(entries),
+            "entries": entries, "scope": _notes_scope(), "store": p}
+
+
+def report_note(issue: str, workaround: str = "", agent: str = "",
+                topic: str = "mcp") -> Dict[str, Any]:
+    iss = (issue or "").strip()
+    wa = (workaround or "").strip()
+    ag = (agent or "").strip() or "unknown-agent"
+    if not iss:
+        return {"ok": False, "reason": "empty_issue",
+                "hint": "现象必填：碰到什么错/什么边界，别只写「不行」。"}
+    for key, val in (("agent", ag), ("issue", iss), ("workaround", wa)):
+        if len(val) > _NOTES_MAX[key]:
+            return {"ok": False, "reason": "too_long", "field": key,
+                    "max": _NOTES_MAX[key]}
+    p = _notes_path(topic)
+    os.makedirs(os.path.dirname(p), exist_ok=True)
+    ts = time.strftime("%Y-%m-%d %H:%M")
+    block = f"## {ts} · {ag}\n- 现象：{iss}\n"
+    if wa:
+        block += f"- 绕行：{wa}\n"
+    if not os.path.isfile(p):
+        with open(p, "w", encoding="utf-8", newline="\n") as f:
+            f.write(_NOTES_HEADER.format(topic=topic))
+    with open(p, "a", encoding="utf-8", newline="\n") as f:
+        f.write(block + "\n")
+    return {"ok": True, "topic": topic, "store": p,
+            "scope": _notes_scope(), "count": read_notes(topic)["count"]}
+
+
 # --------------------------------------------------------------------------- #
 # MCP 协议层（JSON-RPC 2.0 over stdio）
 # --------------------------------------------------------------------------- #
@@ -5574,6 +5677,41 @@ TOOLS = [
             },
         },
     },
+    {
+        "name": "read_notes",
+        "description": "读「踩坑留言区」：其他 agent 用本 MCP 时踩过的坑与绕行方法"
+                       "（如 429 配额语义、无区级过滤、批量取数姿势）。"
+                       "⚠ 开始检索前值得先读一眼，能省掉别人已经付过的试错成本；"
+                       "没有留言时返回空列表，属正常。topic 默认 mcp（MCP 使用坑）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "topic": {"type": "string", "default": "mcp",
+                          "description": "留言主题，默认 mcp"},
+            },
+        },
+    },
+    {
+        "name": "report_note",
+        "description": "往「踩坑留言区」写一条你自己实测踩到的坑（现象 + 绕行方法），"
+                       "让后来的 agent 少走弯路。⚠ 必须是你**实际碰到**的问题，"
+                       "带真实报错/现象描述；不要凭猜测写，不要把留言区当反馈箱或评分区。"
+                       "碰到配额（429）、字段缺失、参数被静默忽略这类边界后，请顺手回写一条。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "issue": {"type": "string",
+                          "description": "现象：碰到什么错/什么边界（必填，要具体）"},
+                "workaround": {"type": "string",
+                               "description": "绕行：你怎么绕开的（实测有效的方法)"},
+                "agent": {"type": "string",
+                          "description": "你的 agent 标识（如 workbuddy-main、claude-desktop）"},
+                "topic": {"type": "string", "default": "mcp",
+                          "description": "留言主题，默认 mcp"},
+            },
+            "required": ["issue"],
+        },
+    },
 ]
 
 
@@ -5836,6 +5974,11 @@ def _dispatch_inner(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
         if name == "vendor_onboarding":
             return vendor_onboarding(args.get("supplier_id", ""), args.get("company", ""),
                                      args.get("intent", "claim"))
+        if name == "read_notes":
+            return read_notes(args.get("topic", "mcp"))
+        if name == "report_note":
+            return report_note(args.get("issue", ""), args.get("workaround", ""),
+                               args.get("agent", ""), args.get("topic", "mcp"))
     except Exception as e:  # 任何异常都包成文本，避免协议崩
         return {"error": f"{name} 执行异常: {e}"}
     return {"error": f"未知 tool: {name}"}