#!/usr/bin/env python3
"""探索工具 server 的只读取数实现（阶段 D）。

边界合同中的工具 server 组件：给创作智能体提供只读取数能力的统一入口。
每个工具声明读什么表、什么版本语义、返回什么结构；不提供裸查询，不写库。
连接固定 `muse_db.connect(readonly=True)`（会话级只读，写语句被库直接拒）。

查询语义与 assemble-context 的三个一等取数端保持一致（按边界合同工具 server
自持实现，不跨 Skill 导入）：已确认细纲、已确认文风投影、已确认范式绑定；
另加正文章节读取与实体检索两个探索工具。

CLI：`read_tools.py <工具名> '<json 参数>'`，JSON 结果输出到 stdout；
未知工具或参数非法退出码 2（合同拒绝），运行时错误退出码 1。
`--list` 输出工具登记表（名称、描述、读取表），供扩展与测试对账。
"""
from __future__ import annotations

import json
import sys
from typing import Any, Callable, Mapping

import muse_db

# 返回规模上限：防御性裁剪，避免单次工具返回撑爆模型上下文。
MAX_TEXT_CHARS = 30000
MAX_ROWS = 50
MAX_DESC_CHARS = 500


def _payload(value: Any) -> Any:
    """规划行 payload 统一解成对象（库里可能是 jsonb 或字符串）。"""

    if isinstance(value, str):
        return json.loads(value)
    return value


def _style_constraints(style_payload: Any) -> list[str]:
    """把文风投影成约束字符串列表（与 assemble-context 口径一致）。"""

    if isinstance(style_payload, str):
        text = style_payload.strip()
        return [text] if text else []
    if isinstance(style_payload, dict):
        rules = []
        for aspect, value in style_payload.items():
            text = str(value).strip()
            if text:
                rules.append(f"{aspect}：{text}")
        return rules
    return []


def _require_int(args: Mapping[str, Any], name: str) -> int:
    value = args.get(name)
    if isinstance(value, bool) or not isinstance(value, int):
        raise ValueError(f"参数 {name} 必须是整数")
    return value


def read_fine_outline(conn, args: Mapping[str, Any]) -> dict[str, Any]:
    """读指定章最新一条已确认细纲（state=confirmed，version 倒序）。"""

    work_id = _require_int(args, "work_id")
    target_chapter = _require_int(args, "target_chapter")
    row = conn.execute(
        "SELECT payload, version FROM example_planning_section WHERE work_id=%s AND "
        "section_type='fine_outline' AND target_chapter=%s AND state='confirmed' AND "
        "deleted=false ORDER BY version DESC LIMIT 1",
        (work_id, target_chapter),
    ).fetchone()
    if not row:
        return {"found": False, "reason": f"无第{target_chapter}章已确认细纲"}
    return {"found": True, "version": row[1], "payload": _payload(row[0])}


def read_style_constraints(conn, args: Mapping[str, Any]) -> dict[str, Any]:
    """读已确认文风并投影为约束；优先独立 style 行，回退设定行 style 字段。"""

    work_id = _require_int(args, "work_id")
    row = conn.execute(
        "SELECT payload FROM example_planning_section WHERE work_id=%s AND "
        "schema_type='style' AND state='confirmed' AND deleted=false "
        "ORDER BY version DESC LIMIT 1",
        (work_id,),
    ).fetchone()
    if row:
        return {"constraints": _style_constraints(_payload(row[0]))}
    setting = conn.execute(
        "SELECT payload FROM example_planning_section WHERE work_id=%s AND "
        "section_type='setting' AND state='confirmed' AND deleted=false "
        "ORDER BY version DESC LIMIT 1",
        (work_id,),
    ).fetchone()
    if setting:
        payload = _payload(setting[0])
        if isinstance(payload, dict):
            return {"constraints": _style_constraints(payload.get("style"))}
    return {"constraints": []}


def read_pattern_bindings(conn, args: Mapping[str, Any]) -> dict[str, Any]:
    """读最新一条已确认 assembly 规划行的 patternReferences；无绑定诚实返空。"""

    work_id = _require_int(args, "work_id")
    row = conn.execute(
        "SELECT payload FROM example_planning_section WHERE work_id=%s AND "
        "section_type='assembly' AND state='confirmed' AND deleted=false "
        "ORDER BY version DESC LIMIT 1",
        (work_id,),
    ).fetchone()
    if not row:
        return {"bindings": []}
    payload = _payload(row[0])
    if not isinstance(payload, dict):
        return {"bindings": []}
    references = payload.get("patternReferences", [])
    return {"bindings": [dict(item) for item in references if isinstance(item, dict)]}


def read_chapter_text(conn, args: Mapping[str, Any]) -> dict[str, Any]:
    """读指定章正式正文（章节行 + 正文块按序拼接）；超长截断并标记。"""

    work_id = _require_int(args, "work_id")
    chapter_order = _require_int(args, "chapter_order")
    chapter = conn.execute(
        "SELECT c.id, c.order_no, c.title FROM muse_content_chapter c "
        "WHERE c.work_id=%s AND c.order_no=%s AND c.deleted=false LIMIT 1",
        (work_id, chapter_order),
    ).fetchone()
    if not chapter:
        return {"found": False, "reason": f"无第{chapter_order}章（work={work_id}）"}
    blocks = conn.execute(
        "SELECT b.content_text FROM muse_content_block b "
        "WHERE b.chapter_id=%s AND b.deleted=false ORDER BY b.order_no",
        (chapter[0],),
    ).fetchall()
    text = "\n".join(str(block[0] or "") for block in blocks)
    truncated = len(text) > MAX_TEXT_CHARS
    return {
        "found": True,
        "chapterOrder": chapter[1],
        "title": chapter[2],
        "text": text[:MAX_TEXT_CHARS],
        "truncated": truncated,
        "totalChars": len(text),
    }


def search_entities(conn, args: Mapping[str, Any]) -> dict[str, Any]:
    """按名称模糊检索作品实体（人物、势力、地点、力量体系等）；结果有界。"""

    work_id = _require_int(args, "work_id")
    keyword = str(args.get("keyword") or "").strip()
    if not keyword:
        raise ValueError("参数 keyword 不能为空")
    entity_type = args.get("entity_type")
    if entity_type is not None and not isinstance(entity_type, str):
        raise ValueError("参数 entity_type 必须是字符串")
    query = (
        "SELECT entity_type, normalized_name, description, status "
        "FROM muse_knowledge_entity WHERE work_id=%s AND deleted=false "
        "AND normalized_name ILIKE %s"
    )
    params: list[Any] = [work_id, f"%{keyword}%"]
    if entity_type:
        query += " AND entity_type=%s"
        params.append(entity_type)
    query += " ORDER BY normalized_name LIMIT %s"
    params.append(MAX_ROWS)
    rows = conn.execute(query, tuple(params)).fetchall()
    return {
        "entities": [
            {
                "entityType": row[0],
                "name": row[1],
                "description": str(row[2] or "")[:MAX_DESC_CHARS],
                "status": row[3],
            }
            for row in rows
        ]
    }


# 工具登记表：名称 -> （描述、读取表、参数、实现）。扩展与测试以此对账，保证单一事实源。
# args 是参数说明：{参数名: 类型}，类型取 int / str；可选参数名后加 ?。
TOOL_REGISTRY: dict[str, dict[str, Any]] = {
    "read_fine_outline": {
        "description": "读指定作品指定章的最新一条已确认细纲（结构骨架与硬约束）。",
        "tables": ("example_planning_section",),
        "args": {"work_id": "int", "target_chapter": "int"},
        "impl": read_fine_outline,
    },
    "read_style_constraints": {
        "description": "读作品已确认文风并投影为约束列表。",
        "tables": ("example_planning_section",),
        "args": {"work_id": "int"},
        "impl": read_style_constraints,
    },
    "read_pattern_bindings": {
        "description": "读作品已确认的范式绑定（规划期选定，写作期只消费）。",
        "tables": ("example_planning_section",),
        "args": {"work_id": "int"},
        "impl": read_pattern_bindings,
    },
    "read_chapter_text": {
        "description": "读指定章的正式正文全文（超长截断并标记）。",
        "tables": ("muse_content_chapter", "muse_content_block"),
        "args": {"work_id": "int", "chapter_order": "int"},
        "impl": read_chapter_text,
    },
    "search_entities": {
        "description": "按名称模糊检索作品实体（人物、势力、地点、力量体系等）。",
        "tables": ("muse_knowledge_entity",),
        "args": {"work_id": "int", "keyword": "str", "entity_type?": "str"},
        "impl": search_entities,
    },
}


def execute_tool(name: str, args: Mapping[str, Any], connect: Callable[..., Any] | None = None) -> dict[str, Any]:
    """执行一个登记工具；只读连接，未知工具拒绝。"""

    entry = TOOL_REGISTRY.get(name)
    if entry is None:
        raise KeyError(f"未知探索工具: {name}")
    factory = connect or (lambda: muse_db.connect(readonly=True))
    conn = factory()
    try:
        return entry["impl"](conn, args)
    finally:
        closer = getattr(conn, "close", None)
        if callable(closer):
            closer()


def main(argv: list[str]) -> int:
    if argv and argv[0] == "--list":
        listing = {
            name: {
                "description": entry["description"],
                "tables": list(entry["tables"]),
                "args": entry.get("args", {}),
            }
            for name, entry in TOOL_REGISTRY.items()
        }
        print(json.dumps(listing, ensure_ascii=False, indent=1))
        return 0
    if len(argv) != 2:
        print("用法: read_tools.py <工具名> '<json 参数>' | --list", file=sys.stderr)
        return 2
    name, raw_args = argv
    if name not in TOOL_REGISTRY:
        print(f"未知探索工具: {name}", file=sys.stderr)
        return 2
    try:
        args = json.loads(raw_args)
    except json.JSONDecodeError:
        print("参数不是合法 JSON", file=sys.stderr)
        return 2
    if not isinstance(args, dict):
        print("参数必须是 JSON 对象", file=sys.stderr)
        return 2
    try:
        result = execute_tool(name, args)
    except ValueError as exc:
        print(f"参数合同拒绝: {exc}", file=sys.stderr)
        return 2
    except Exception as exc:  # 运行时失败如实上报，不静默
        print(f"工具执行失败: {type(exc).__name__}: {exc}", file=sys.stderr)
        return 1
    print(json.dumps(result, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))


__all__ = ["TOOL_REGISTRY", "execute_tool", "main"]