@gobi-starweaver/ws-cli 0.3.1 → 0.3.2

package/{mcp → dist/mcp}/servers/doc-toolchain-server.js

@@ -1,23 +1,23 @@
 #!/usr/bin/env node
 import {
   killProcessTree
-} from "../../chunks/chunk-S7EGXUII.js";
+} from "../../chunks/chunk-B2GIIUZ7.js";
 import {
   __name,
   init_esbuild_shims
-} from "../../chunks/chunk-BUBNMVFA.js";
+} from "../../chunks/chunk-PJQH2TDX.js";
 
-// packages/core/src/mcp/servers/doc-toolchain-server.ts
+// ../core/src/mcp/servers/doc-toolchain-server.ts
 init_esbuild_shims();
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import * as fs2 from "node:fs";
 import * as path2 from "node:path";
 
-// packages/core/src/mcp/servers/doc-toolchain/ooxml.ts
+// ../core/src/mcp/servers/doc-toolchain/ooxml.ts
 init_esbuild_shims();
 
-// packages/core/src/mcp/servers/doc-toolchain/zip.ts
+// ../core/src/mcp/servers/doc-toolchain/zip.ts
 init_esbuild_shims();
 import { deflateRawSync, inflateRawSync } from "node:zlib";
 var EOCD_SIGNATURE = 101010256;
@@ -181,7 +181,7 @@ function writeZip(inputs) {
 }
 __name(writeZip, "writeZip");
 
-// packages/core/src/mcp/servers/doc-toolchain/ooxml.ts
+// ../core/src/mcp/servers/doc-toolchain/ooxml.ts
 var XML_DECLARATION = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`;
 var OoxmlFormatError = class extends Error {
   static {
@@ -659,7 +659,7 @@ function editDocx(buffer, ops) {
 }
 __name(editDocx, "editDocx");
 
-// packages/core/src/mcp/servers/doc-toolchain/convert.ts
+// ../core/src/mcp/servers/doc-toolchain/convert.ts
 init_esbuild_shims();
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
@@ -1190,7 +1190,7 @@ async function probeEnvironment(deps = {}) {
 }
 __name(probeEnvironment, "probeEnvironment");
 
-// packages/core/src/mcp/servers/doc-toolchain-server.ts
+// ../core/src/mcp/servers/doc-toolchain-server.ts
 var DOC_TOOLCHAIN_SERVER_NAME = "doc_toolchain";
 var DOC_TOOLCHAIN_TOOL_PREFIX = "mcp__doc_toolchain__";
 var EDIT_OPS = ["replace_paragraph_text", "insert_paragraph", "delete_paragraph", "append_paragraph"];

package/{mcp → dist/mcp}/servers/ws-vision-ocr-server.js

@@ -13,8 +13,8 @@ import {
   releaseVisionImageRef,
   resolveVisionGatewayTarget,
   runWsVisionMcpServer
-} from "../../chunks/chunk-O2SA6W2I.js";
-import "../../chunks/chunk-BUBNMVFA.js";
+} from "../../chunks/chunk-EMOHUSKW.js";
+import "../../chunks/chunk-PJQH2TDX.js";
 export {
   VISION_TOOL_DEFINITIONS,
   WS_VISION_BRIDGE_TIMEOUT_MS,

package/dist/vendor/hj_corpus/hj_corpus_mcp_server.py

@@ -0,0 +1,436 @@
+"""中古史学术IDE · 汉籍语料索引 MCP server（插件 v0.1 · 北辰 CLI vendored 副本）
+
+★ vendored 自 mvp_backend/hj_corpus_mcp_server.py（检索核心单源不复制原则的例外=同源两份）：
+  改库/改检索逻辑一律先改主 IDE 源 mvp_backend/，本副本跟版同步；两件的差异只许在
+  ①本段 vendored 注记 ②工具 annotations（readOnlyHint·⑥通用免问机制）
+  ③B3 远程模式分支（方案 v0.8 §三「库在线」指定分叉：本地库不可用 → 四器改打北辰网关
+    /hj/* 端点·订阅令牌鉴权·读 ~/.ws/auth.json；本地模式与主源逐字一致）。
+依赖：python 3.10+ + `pip install mcp`（FastMCP）；库路径经 HJ_CORPUS_DB 环境变量注入
+  （CLI settings 默认注入已配好；无库时 CLI 不注入本服务·隐身）。
+
+汉籍索引库封装进 agent，用插件组装，agent 用 MCP 协议访问。
+
+定位：hj_4_jt_fts.sqlite（4.86GB trigram FTS5 全库，66876 篇，含《唐六典》全 30 卷）的
+只读检索 MCP 服务（stdio JSON-RPC）。检索核心复用 hj_index_search.py（单源不复制）。
+
+本服务修缺三件（agent 多词组合 0 命中、误报「本地无《唐六典》」）：
+1. 多词组合检索（hj_search mode=all_terms）——旧接口把整串归一化成连续短语
+   （normalize_with_map 连空格一并吞掉），多词查询必然 0 命中；
+2. 书名/卷名定位（hj_find_book）——旧接口没有「库里有没有某书、有哪些卷」的问法；
+3. 命中总数如实报（total_hits）——旧接口 hit_count=截断后条数（1061 条真实命中报 10），
+   配 offset 分页，不静默截断（A-26 量具之报）。
+另补 hj_get_article 按篇取全文（分片，防一次取爆）。
+
+trigram 索引固有边界（如实报，不掩饰）：规范化后少于 3 字的词进不了 trigram 倒排，
+all_terms 模式下短词以 LIKE 在命中集内过滤（原文若被标点隔断则匹配不到，warning 注明）。
+
+安全边界：file:?mode=ro + PRAGMA query_only=ON，只读；绝不写库。
+证据政策每返回必带：命中只作出处候选与上下文依据，不作页码依据（page_basis=false）。
+
+运行：python hj_corpus_mcp_server.py [--db <path>]      # stdio MCP server
+直测：python hj_corpus_mcp_server.py --selftest         # 不经协议直测 SQL 层
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sqlite3
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+BACKEND_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(BACKEND_DIR))
+
+import hj_index_search as hj  # 检索核心单源：normalize/fts_phrase/open/context/candidate/policy
+
+DB_PATH = Path(os.environ.get("HJ_CORPUS_DB") or hj.DEFAULT_DB)
+
+# ===== B3 远程模式（方案 v0.8 §三·库在线）=====
+# 本地库不可用（HJ_CORPUS_DB 未设或指向文件不存在）→ 四器改打北辰网关 /hj/* 端点
+# （验卡同款：Authorization Bearer 卡密 + x-polaris-device 设备头·读 ~/.ws/auth.json）。
+HJ_REMOTE_BASE_URL = os.environ.get(
+    "HJ_REMOTE_BASE_URL", "https://api.gobi-starweaver.cn:8443").rstrip("/")
+_HJ_REMOTE_TIMEOUT = int(os.environ.get("HJ_REMOTE_TIMEOUT", "60"))
+
+
+def _local_db_available() -> bool:
+    try:
+        return DB_PATH.exists()
+    except OSError:
+        return False
+
+
+def _read_auth() -> tuple[str, str]:
+    """读 ~/.ws/auth.json → (card_token, device_id)；无文件/损坏/缺字段 → ("", "")。"""
+    try:
+        raw = Path.home().joinpath(".ws", "auth.json").read_text(encoding="utf-8")
+        data = json.loads(raw)
+        return str(data.get("card_token") or ""), str(data.get("device_id") or "")
+    except Exception:
+        return "", ""
+
+
+def _remote_call(endpoint: str, payload: dict[str, Any]) -> dict[str, Any]:
+    """POST 网关 /hj/<endpoint>；回包 dict 原样（与本地 do_* 同构契约）。
+    未登录/网络异常 → error dict 如实报（不 raise·与 do_* 的错误随包契约一致）。"""
+    token, device = _read_auth()
+    if not token or not device:
+        return {"error": "远程汉籍库需要登录态：未读到有效登录（~/.ws/auth.json），"
+                         "请先在 CLI 内 /login 后重试。"}
+    req = urllib.request.Request(
+        f"{HJ_REMOTE_BASE_URL}/hj/{endpoint}",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+            "x-polaris-device": device,
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_HJ_REMOTE_TIMEOUT) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        try:
+            return json.loads(e.read().decode("utf-8"))
+        except Exception:
+            return {"error": f"网关回 HTTP {e.code}（远程汉籍库暂不可用）。"}
+    except Exception as e:
+        return {"error": f"远程汉籍库连接失败：{type(e).__name__}（请检查网络后重试）。"}
+
+ARTICLE_SLICE_MAX = 8000
+SEARCH_LIMIT_MAX = 50
+
+
+def _connect() -> sqlite3.Connection:
+    return hj.open_hj_index(DB_PATH)
+
+
+def _policy() -> dict[str, Any]:
+    return dict(hj.EVIDENCE_POLICY)
+
+
+def _terms_of(query: str) -> tuple[list[str], list[str], list[str]]:
+    """按空白拆词并归一化；返回 (全部词原貌, 可进 trigram 的词≥3字, 短词<3字)。"""
+    raw_terms = [t for t in hj.compact_query(query).split(" ") if t]
+    long_terms: list[str] = []
+    short_terms: list[str] = []
+    for t in raw_terms:
+        n = hj.normalize_query(t)
+        if len(n) >= 3:
+            long_terms.append(n)
+        elif n:
+            short_terms.append(t)  # 短词留原貌走 LIKE
+    return raw_terms, long_terms, short_terms
+
+
+def do_find_book(name_like: str, limit: int = 50) -> dict[str, Any]:
+    name_like = hj.compact_query(name_like)
+    if not name_like:
+        return {"error": "name_like 不能为空。"}
+    limit = max(1, min(int(limit), 200))
+    if not _local_db_available():
+        return _remote_call("find_book", {"name_like": name_like, "limit": limit})
+    conn = _connect()
+    try:
+        pattern = f"%{name_like}%"
+        total = conn.execute(
+            "SELECT COUNT(*) FROM docs WHERE title LIKE ?", (pattern,)
+        ).fetchone()[0]
+        rows = conn.execute(
+            "SELECT docid, title, book_base, article_no, char_count FROM docs "
+            "WHERE title LIKE ? ORDER BY book_base, article_no LIMIT ?",
+            (pattern, limit),
+        ).fetchall()
+    finally:
+        conn.close()
+    return {
+        "name_like": name_like,
+        "total_matches": total,
+        "returned": len(rows),
+        "note": "按篇名（title，形如「唐六典·卷五·尚书兵部」）模糊匹配；total_matches 为全库真实总数。",
+        "items": [
+            {"docid": r["docid"], "title": r["title"], "book_base": r["book_base"],
+             "article_no": r["article_no"], "char_count": r["char_count"]}
+            for r in rows
+        ],
+        "evidence_policy": _policy(),
+    }
+
+
+def do_search(query: str, mode: str = "phrase", title_like: str = "",
+              limit: int = 10, offset: int = 0, context_chars: int = 80) -> dict[str, Any]:
+    raw_query = hj.compact_query(query)
+    if not raw_query:
+        return {"error": "query 不能为空。"}
+    mode = (mode or "phrase").strip().lower()
+    if mode not in ("phrase", "all_terms"):
+        return {"error": f"mode 须为 phrase 或 all_terms，收到：{mode}"}
+    limit = max(1, min(int(limit), SEARCH_LIMIT_MAX))
+    offset = max(0, int(offset))
+    context_chars = max(20, min(int(context_chars), 400))
+    if not _local_db_available():
+        return _remote_call("search", {
+            "query": raw_query, "mode": mode, "title_like": title_like,
+            "limit": limit, "offset": offset, "context_chars": context_chars,
+        })
+    warnings: list[str] = []
+
+    where: list[str] = []
+    params: list[object] = []
+    from_clause = "FROM docs_fts JOIN docs AS d ON d.docid = docs_fts.rowid"
+    rank_select = "bm25(docs_fts) AS rank"
+    order_by = "ORDER BY rank"
+    like_filter_terms: list[str] = []
+
+    if mode == "phrase":
+        normalized = hj.normalize_query(raw_query)
+        if len(normalized) < 3:
+            return {"error": "短语经规范化后不足 3 字，trigram 索引无法命中；"
+                             "请加长短语，或用 all_terms 模式与较长词组合。"}
+        where.append("docs_fts MATCH ?")
+        params.append(hj.fts_phrase(normalized))
+        primary_terms = [raw_query]
+    else:  # all_terms
+        raw_terms, long_terms, short_terms = _terms_of(raw_query)
+        if not raw_terms:
+            return {"error": "query 不能为空。"}
+        if not long_terms:
+            return {"error": "all_terms 模式至少需要一个规范化后 ≥3 字的词"
+                             "（trigram 索引边界）；全部短词请改用更长的词或加长短语。"}
+        where.append("docs_fts MATCH ?")
+        params.append(" AND ".join(hj.fts_phrase(t) for t in long_terms))
+        like_filter_terms = short_terms
+        for st in short_terms:
+            where.append("d.body LIKE ?")
+            params.append(f"%{st}%")
+        if short_terms:
+            warnings.append(
+                f"短词 {short_terms} 以 LIKE 在命中集内过滤（不足 3 字进不了 trigram 倒排）；"
+                "原文中若被标点/空白隔断则匹配不到。"
+            )
+        primary_terms = raw_terms
+
+    if title_like:
+        where.append("d.title LIKE ?")
+        params.append(f"%{hj.compact_query(title_like)}%")
+
+    where_sql = " AND ".join(where)
+    conn = _connect()
+    try:
+        total_hits = conn.execute(
+            f"SELECT COUNT(*) {from_clause} WHERE {where_sql}", params
+        ).fetchone()[0]
+        rows = conn.execute(
+            f"SELECT d.docid, d.rel_path, d.book_base, d.article_no, d.title, d.source, "
+            f"d.body, d.char_count, {rank_select} {from_clause} WHERE {where_sql} "
+            f"{order_by} LIMIT ? OFFSET ?",
+            [*params, limit, offset],
+        ).fetchall()
+    finally:
+        conn.close()
+
+    locate_term = primary_terms[0]
+    normalized_locate = hj.normalize_query(locate_term)
+    candidates = [
+        hj.row_to_candidate(row, locate_term, normalized_locate, context_chars)
+        for row in rows
+    ]
+    if total_hits > offset + len(candidates):
+        warnings.append(
+            f"total_hits={total_hits}，本次仅返回第 {offset + 1}—{offset + len(candidates)} 条"
+            f"（bm25 相关度序）；其余经 offset 翻页取。"
+        )
+    return {
+        "query": raw_query,
+        "mode": mode,
+        "title_like": title_like or None,
+        "total_hits": total_hits,
+        "offset": offset,
+        "returned": len(candidates),
+        "warnings": warnings,
+        "results": candidates,
+        "evidence_policy": _policy(),
+    }
+
+
+def do_get_article(docid: int = 0, title: str = "",
+                   body_offset: int = 0, length: int = 4000) -> dict[str, Any]:
+    if not docid and not title:
+        return {"error": "docid 与 title 至少给一个（title 须精确篇名，可先经 hj_find_book 取得）。"}
+    body_offset = max(0, int(body_offset))
+    length = max(200, min(int(length), ARTICLE_SLICE_MAX))
+    if not _local_db_available():
+        return _remote_call("get_article", {
+            "docid": docid, "title": title,
+            "body_offset": body_offset, "length": length,
+        })
+    conn = _connect()
+    try:
+        if docid:
+            row = conn.execute(
+                "SELECT docid, rel_path, book_base, article_no, title, source, body, char_count "
+                "FROM docs WHERE docid = ?", (int(docid),)
+            ).fetchone()
+        else:
+            exact = hj.compact_query(title)
+            row = conn.execute(
+                "SELECT docid, rel_path, book_base, article_no, title, source, body, char_count "
+                "FROM docs WHERE title = ?", (exact,)
+            ).fetchone()
+            if row is None:
+                cands = conn.execute(
+                    "SELECT docid, title FROM docs WHERE title LIKE ? LIMIT 8",
+                    (f"%{exact}%",),
+                ).fetchall()
+                return {"error": f"未找到精确篇名「{exact}」。",
+                        "near_titles": [{"docid": c["docid"], "title": c["title"]} for c in cands]}
+    finally:
+        conn.close()
+    if row is None:
+        return {"error": f"docid={docid} 不存在。"}
+    body = row["body"] or ""
+    piece = body[body_offset: body_offset + length]
+    return {
+        "docid": row["docid"],
+        "title": row["title"],
+        "book_base": row["book_base"],
+        "article_no": row["article_no"],
+        "source": row["source"],
+        "body_total_chars": len(body),
+        "body_offset": body_offset,
+        "returned_chars": len(piece),
+        "has_more": body_offset + len(piece) < len(body),
+        "note": "全文按片返回（单片上限 8000 字）；has_more=true 时调大 body_offset 继续取。",
+        "body": piece,
+        "evidence_policy": _policy(),
+    }
+
+
+def do_stats() -> dict[str, Any]:
+    if not _local_db_available():
+        return _remote_call("stats", {})
+    info = hj.inspect_hj_index(DB_PATH)
+    info["note"] = ("汉籍语料索引（trigram FTS5）只读服务；检索命中只作出处候选与上下文依据，"
+                    "不作页码依据。")
+    return info
+
+
+# ---- MCP server（FastMCP，stdio）----
+
+def build_mcp_app():
+    from mcp.server.fastmcp import FastMCP
+    from mcp.types import ToolAnnotations
+
+    # 只读自声明（⑥通用免问机制）：本服务确实只读（file:?mode=ro + PRAGMA query_only=ON·
+    # 绝不写库），如实挂 readOnlyHint——宿主 CLI 权限层凭它对 mcp 工具免 ask（A-26 如实消费）。
+    # 注意：hj_stats 同为只读，一并挂（handoff 旧稿列 3 工具为笔误，4 个全只读）。
+    READ_ONLY = ToolAnnotations(readOnlyHint=True)
+
+    app = FastMCP(
+        "hj-corpus",
+        instructions=(
+            "汉籍语料索引只读检索服务（含两《唐书》《唐六典》《资治通鉴》等；"
+            "实际篇数以 hj_stats 返回为准——封装核心库已剔清明清以后小说戏曲簇，篇数少于开发全量库）。"
+            "用法：hj_find_book 先定位书/卷；hj_search 检索（phrase=连续短语、"
+            "all_terms=多词组合 AND，title_like 可限定在某书内）；hj_get_article 按篇取全文。"
+            "铁律：命中只作出处候选与上下文依据，不作页码依据（page_basis=false）；"
+            "版本/卷次细目/页码须按拟引用版本另行人工核定。"
+            "边界：本库若为分发核心版，已剔 C07/C08/非 allowlist 的 C09 明清小说秘史簇"
+            "与 D02 文学戏曲辅助簇及大型元曲杂剧；hj 未命中只能说核心库未命中，不等于汉籍无该出处。"
+        ),
+    )
+
+    @app.tool(annotations=READ_ONLY)
+    def hj_find_book(name_like: str, limit: int = 50) -> dict:
+        """书名/卷名定位：按篇名模糊匹配（如「唐六典」可列出全部 30 卷），返回全库真实总数
+        total_matches 与篇目清单（docid/title/book_base/char_count）。检索正文前先用本工具
+        确认书在不在库、篇名长什么样。"""
+        return do_find_book(name_like, limit)
+
+    @app.tool(annotations=READ_ONLY)
+    def hj_search(query: str, mode: str = "phrase", title_like: str = "",
+                  limit: int = 10, offset: int = 0, context_chars: int = 80) -> dict:
+        """全库正文检索（trigram FTS5，bm25 相关度排序）。mode=phrase：query 作连续短语
+        （引文原句用这个）；mode=all_terms：query 按空格拆多词 AND 组合（如「骠骑将军 品级」，
+        概念组合用这个；规范化后不足 3 字的短词以 LIKE 过滤并报 warning）。title_like 限定
+        在某书/某卷内检索（如「唐六典」）。返回 total_hits 全库真实命中总数 + offset 分页。
+        命中只作出处候选与上下文依据，不作页码依据（page_basis=false）。"""
+        return do_search(query, mode, title_like, limit, offset, context_chars)
+
+    @app.tool(annotations=READ_ONLY)
+    def hj_get_article(docid: int = 0, title: str = "",
+                       body_offset: int = 0, length: int = 4000) -> dict:
+        """按篇取全文：docid（hj_find_book/hj_search 返回）或精确篇名二选一。全文分片返回
+        （单片上限 8000 字，has_more=true 时调大 body_offset 续取）。引用校核须取全文上下文
+        时用本工具，不要只凭检索摘录下判断。"""
+        return do_get_article(docid, title, body_offset, length)
+
+    @app.tool(annotations=READ_ONLY)
+    def hj_stats() -> dict:
+        """库概况：篇目总数、构建元数据、只读状态、证据政策。"""
+        return do_stats()
+
+    return app
+
+
+def selftest() -> int:
+    checks: dict[str, bool] = {}
+    fb = do_find_book("唐六典")
+    checks["find_book 唐六典 30 卷"] = fb["total_matches"] == 30
+    checks["find_book 含诸卫府卷"] = any("卷二十五·诸卫府" in i["title"] for i in fb["items"])
+
+    s1 = do_search("骠骑将军", mode="phrase", title_like="唐六典")
+    checks["phrase 骠骑将军@唐六典 命中2"] = s1["total_hits"] == 2
+    checks["命中含卷五尚书兵部"] = any("卷五" in r["title"] for r in s1["results"])
+    checks["命中含卷二十五诸卫府"] = any("卷二十五" in r["title"] for r in s1["results"])
+
+    s2 = do_search("骠骑将军 车骑将军 折冲", mode="all_terms")
+    checks["all_terms 三词组合有命中(血证查询)"] = s2["total_hits"] > 0
+    s2b = do_search("骠骑将军 车骑将军 折冲", mode="phrase")
+    checks["同串 phrase 0 命中(旧缺陷对照)"] = s2b["total_hits"] == 0
+
+    s3 = do_search("骠骑将军", mode="phrase")
+    checks["total_hits 如实报全库 1061"] = s3["total_hits"] == 1061
+    checks["返回带分页 warning"] = any("total_hits=1061" in w for w in s3["warnings"])
+
+    twentyfive = next(i for i in fb["items"] if "卷二十五·诸卫府" in i["title"])
+    art = do_get_article(docid=twentyfive["docid"], body_offset=0, length=2000)
+    checks["get_article 取卷二十五全文片"] = art["returned_chars"] == 2000 and art["has_more"]
+    art2 = do_get_article(title="唐六典·卷二十五·诸卫府", body_offset=0, length=500)
+    checks["get_article 精确篇名可取"] = art2.get("docid") == twentyfive["docid"]
+
+    st = do_stats()
+    checks["stats 只读 66876 篇"] = st["doc_count"] == 66876 and st["query_only"] == 1
+    checks["evidence_policy 必带"] = all(
+        "evidence_policy" in x for x in (fb, s1, s2, s3, art, st)
+    )
+
+    for k, v in checks.items():
+        print(("PASS" if v else "FAIL"), k)
+    ok = all(checks.values())
+    print("==>", "ALL PASS" if ok else "HAS FAILURE")
+    return 0 if ok else 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="汉籍语料索引 MCP server（只读）")
+    parser.add_argument("--db", default="", help="hj_4_jt_fts.sqlite 路径（缺省=项目内全库）")
+    parser.add_argument("--selftest", action="store_true", help="直测 SQL 层（不起 MCP）")
+    args = parser.parse_args()
+    global DB_PATH
+    if args.db:
+        DB_PATH = Path(args.db)
+    if args.selftest:
+        return selftest()
+    build_mcp_app().run()  # stdio transport
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())