netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/cards/defaults.py

@@ -0,0 +1,213 @@
+"""Current-chat session defaults form; state travels on the real card."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+from uuid import uuid4
+
+from lark_channel import OutboundCard
+
+from ..domain import FeishuScope, ScopeKind
+from ..model_settings import ModelCatalog
+from ..projects import Project
+from ..session_settings import SessionSettings
+from .callbacks import CardActionError, _builder, _notice, _plain, _plain_text
+from .controls import decode_session_settings_form, session_settings_form_elements
+
+
+_VERSION = 1
+_FORM_PREFIX = "defaults_project_v1__"
+_SESSION_PREFIX = "defaults_session"
+_STATE_FIELDS = {"v", "scope", "chat_kind", "id", "expected_revision"}
+_PROJECT_ALIAS = re.compile(r"[a-z0-9][a-z0-9_-]{0,63}")
+_RECORD_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,127}")
+_NONCE = re.compile(r"[0-9a-f]{32}")
+
+
+def _encoded(value: Mapping[str, Any]) -> str:
+    return base64.urlsafe_b64encode(
+        json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode()
+    ).decode().rstrip("=")
+
+
+def _decoded(value: Any) -> dict[str, Any]:
+    if not isinstance(value, str) or not value or len(value) > 8192:
+        raise CardActionError("请选择默认会话使用的 Project。")
+    try:
+        result = json.loads(base64.b64decode(
+            value + "=" * (-len(value) % 4), altchars=b"-_", validate=True,
+        ))
+    except (ValueError, UnicodeError) as error:
+        raise CardActionError("默认会话配置选项无效，请重新发送 /defaults。") from error
+    if not isinstance(result, dict):
+        raise CardActionError("默认会话配置选项无效，请重新发送 /defaults。")
+    return result
+
+
+def _validate_state(scope: FeishuScope, state: Mapping[str, Any]) -> None:
+    if type(state.get("v")) is not int or state["v"] != _VERSION:
+        raise CardActionError("默认会话配置卡片已过期，请重新发送 /defaults。")
+    if state.get("scope") != scope.key:
+        raise CardActionError("默认会话配置卡片与原消息位置不一致。")
+    if not isinstance(state.get("chat_kind"), str) or state["chat_kind"] not in {"group", "p2p"}:
+        raise CardActionError("默认会话配置缺少聊天类型，请重新发送 /defaults。")
+    if scope.kind is ScopeKind.DIRECT and state["chat_kind"] != "p2p":
+        raise CardActionError("默认会话配置卡片与聊天类型不一致。")
+    if scope.kind is ScopeKind.GROUP and state["chat_kind"] != "group":
+        raise CardActionError("默认会话配置卡片与聊天类型不一致。")
+    record_id, revision = state.get("id"), state.get("expected_revision")
+    if record_id is None and revision is None:
+        return
+    if (not isinstance(record_id, str) or _RECORD_ID.fullmatch(record_id) is None
+            or type(revision) is not int or revision < 1):
+        raise CardActionError("默认会话配置版本无效，请重新发送 /defaults。")
+
+
+def defaults_card(
+    scope: FeishuScope,
+    view: Mapping[str, Any],
+    projects: Sequence[Project],
+    catalog: ModelCatalog | None,
+    notice: str | None = None,
+    notice_is_error: bool = False,
+) -> OutboundCard:
+    """One editable form for the enclosing chat, including from topic scopes."""
+    exact = view.get("exact")
+    effective = exact if exact is not None else view.get("effective")
+    state = {
+        "v": _VERSION, "scope": scope.key, "chat_kind": view.get("chat_kind"),
+        "id": exact["id"] if exact is not None else None,
+        "expected_revision": exact["revision"] if exact is not None else None,
+    }
+    _validate_state(scope, state)
+    if effective is None:
+        settings = SessionSettings.new_defaults(catalog)
+        selected_project = None
+    else:
+        raw_settings = effective["session_settings"]
+        settings = raw_settings if isinstance(raw_settings, SessionSettings) else SessionSettings.from_dict(raw_settings)
+        selected_project = effective["project"]
+
+    builder = _builder("默认会话配置", "当前聊天")
+    kind_label = "单聊" if state["chat_kind"] == "p2p" else "群聊"
+    builder.raw(_plain(f"作用于当前{kind_label}：{scope.chat_id}（包含其中的话题）。"))
+    if exact is not None:
+        builder.raw(_plain("当前使用本聊天的精确配置；修改后保存，仅影响之后自动创建的会话。"))
+    elif effective is not None:
+        builder.raw(_plain(f"当前使用群名包含「{effective['keyword']}」的规则；保存后将成为本聊天的精确配置。"))
+    else:
+        builder.raw(_plain("尚未配置默认会话，请选择 Project 后保存。"))
+    if view.get("match_error"):
+        builder.raw(_notice(str(view["match_error"]), error=True))
+    if notice:
+        builder.raw(_notice(notice, error=notice_is_error))
+
+    enabled_projects = [project for project in projects if project.enabled]
+    project_options: list[dict[str, Any]] = []
+    selected_value = None
+    for project in enabled_projects:
+        option = _encoded({**state, "project": project.alias, "project_revision": project.revision})
+        project_options.append({"text": _plain_text(f"{project.alias} · {project.cwd}"), "value": option})
+        if project.alias == selected_project:
+            selected_value = option
+    if selected_project is not None and selected_value is None:
+        selected_value = _encoded({**state, "project": selected_project, "project_revision": None})
+        project_options.append({"text": _plain_text(f"{selected_project} · 不可用（保留原配置）"), "value": selected_value})
+        builder.raw(_notice(f"Project「{selected_project}」已停用或不可用；请选择可用项目后保存，或删除本聊天的默认配置。", error=True))
+    if not enabled_projects:
+        builder.raw(_notice("没有可用 Project，请先通过 /settings 登记或启用项目。"))
+    if not project_options:
+        # Feishu cannot render an empty static select. There is no saved exact
+        # record to delete in this branch; opening again after /settings gives
+        # the ordinary single form without inventing a default Project.
+        return OutboundCard(card=builder.to_dict())
+
+    # Each redraw gives form submissions a fresh SDK dedup identity. This is
+    # transport state, not a persisted card session or a management revision.
+    project_select: dict[str, Any] = {
+        "tag": "select_static", "name": _FORM_PREFIX + uuid4().hex,
+        "required": True, "placeholder": _plain_text("选择 Project"),
+        "options": project_options,
+    }
+    if selected_value is not None:
+        project_select["initial_option"] = selected_value
+    builder.raw({"tag": "form", "name": "defaults_v1", "elements": [
+        _plain("Project"), project_select,
+        *session_settings_form_elements(
+            prefix=_SESSION_PREFIX, settings=settings, catalog=catalog,
+            allow_context_mode=state["chat_kind"] == "group",
+        ),
+        {"tag": "button", "name": "defaults_save", "text": _plain_text("保存默认配置"),
+         "type": "primary_filled", "width": "fill", "form_action_type": "submit"},
+    ]})
+    if exact is not None:
+        builder.raw({
+            "tag": "button", "text": _plain_text("删除默认配置"), "type": "danger", "width": "fill",
+            "behaviors": [{"type": "callback", "value": {
+                "kind": "netizen_defaults", "action": "delete", "nonce": uuid4().hex, **state,
+            }}],
+        })
+        builder.raw(_plain("删除后仍可能使用匹配的群名规则；已有会话不受影响。"))
+    return OutboundCard(card=builder.to_dict())
+
+
+def is_defaults_card_action(value: Any, form: Any = None) -> bool:
+    return (isinstance(value, Mapping) and value.get("kind") == "netizen_defaults") or (
+        isinstance(form, Mapping)
+        and any(isinstance(name, str) and name.startswith(_FORM_PREFIX) for name in form)
+    )
+
+
+def _request(scope: FeishuScope, state: Mapping[str, Any], mode: str) -> dict[str, Any]:
+    result = {
+        "mode": mode, "kind": "chat", "chat_id": scope.chat_id,
+        "expected_revision": state["expected_revision"],
+    }
+    if state["id"] is not None:
+        result["id"] = state["id"]
+    return result
+
+
+def decode_defaults_action(scope: FeishuScope, value: Any, form: Any = None) -> dict[str, Any]:
+    """Decode strict form values; the caller verifies the real card location."""
+    if form is not None and form != {}:
+        if value is not None and value != {}:
+            raise CardActionError("默认会话配置表单混入其他操作。")
+        if not isinstance(form, Mapping):
+            raise CardActionError("默认会话配置表单无效。")
+        names = [name for name in form if isinstance(name, str) and name.startswith(_FORM_PREFIX)]
+        if len(names) != 1 or _NONCE.fullmatch(names[0][len(_FORM_PREFIX):]) is None:
+            raise CardActionError("默认会话配置表单身份无效，请重新发送 /defaults。")
+        state = _decoded(form[names[0]])
+        if set(state) != _STATE_FIELDS | {"project", "project_revision"}:
+            raise CardActionError("默认会话配置选项字段无效。")
+        _validate_state(scope, state)
+        project = state["project"]
+        if not isinstance(project, str) or _PROJECT_ALIAS.fullmatch(project) is None:
+            raise CardActionError("默认会话配置 Project 无效。")
+        revision = state["project_revision"]
+        if revision is not None and (type(revision) is not int or revision < 1):
+            raise CardActionError("默认会话配置 Project 版本无效。")
+        fields = {key: item for key, item in form.items() if key != names[0]}
+        if state["chat_kind"] == "p2p" and f"{_SESSION_PREFIX}_context_mode" in fields:
+            raise CardActionError("单聊不支持补充历史上下文。")
+        if state["chat_kind"] == "group" and f"{_SESSION_PREFIX}_context_mode" not in fields:
+            raise CardActionError("默认会话配置表单缺少上下文设置。")
+        settings = decode_session_settings_form(fields, prefix=_SESSION_PREFIX)
+        return {
+            **_request(scope, state, "save"), "project": project,
+            "expected_project_revision": revision, "session_settings": settings.to_dict(),
+        }
+    if not isinstance(value, Mapping) or set(value) != _STATE_FIELDS | {"kind", "action", "nonce"}:
+        raise CardActionError("默认会话配置动作无效，请重新发送 /defaults。")
+    if (value["kind"] != "netizen_defaults" or value["action"] != "delete"
+            or not isinstance(value["nonce"], str) or _NONCE.fullmatch(value["nonce"]) is None):
+        raise CardActionError("默认会话配置动作无效，请重新发送 /defaults。")
+    _validate_state(scope, value)
+    if value["id"] is None:
+        raise CardActionError("当前聊天没有可删除的精确配置。")
+    return _request(scope, value, "delete")

netizen_cli/cards/model_info.py

@@ -0,0 +1,80 @@
+"""Read-only model catalog information, with no selection callbacks or state."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from ..model_settings import ModelCatalog, ModelOption
+from .callbacks import _plain, _plain_text
+from .reply import TURN_FILE_CARD_JSON_LIMIT_BYTES
+
+
+def _text(value: object, limit: int = 600) -> str:
+    if not isinstance(value, str):
+        return ""
+    value = value.strip()
+    return value if len(value) <= limit else value[:limit] + "…（已省略）"
+
+
+def _model_description(model: ModelOption) -> str:
+    lines = [_text(model.description) or "模型目录未提供简介。"]
+    if model.input_modalities:
+        labels = {"text": "文字", "image": "图片", "audio": "音频"}
+        lines.append("支持输入：" + "、".join(
+            labels.get(item, _text(item, 40)) for item in model.input_modalities
+        ))
+    info = model.upgrade_info
+    upgrade = _text(info.model if info is not None else model.upgrade, 120)
+    if upgrade:
+        lines.append("建议迁移至：" + upgrade + "（不会自动切换）")
+    if info is not None:
+        if copy := _text(info.upgrade_copy):
+            lines.append(copy)
+        if isinstance(info.retirement_at, int) and not isinstance(info.retirement_at, bool):
+            try:
+                retirement = datetime.fromtimestamp(info.retirement_at, timezone.utc)
+            except (ValueError, OverflowError, OSError):
+                pass
+            else:
+                lines.append("目录提示的退役时间：" + retirement.strftime("%Y-%m-%d %H:%M UTC"))
+        if migration := _text(info.migration_markdown, 1000):
+            lines.append("迁移说明：" + migration)
+        if link := _text(info.model_link, 500):
+            lines.append("详情：" + link)
+    # Catalog prose is plain text: HTML, Markdown and mention-like strings
+    # must never become interactive card markup or callback payloads.
+    return "\n\n".join(lines)
+
+
+def with_model_details(card: dict[str, Any], catalog: ModelCatalog | None) -> dict[str, Any]:
+    """Append bounded optional information without changing the original form."""
+    if catalog is None or not catalog.models:
+        return card
+    note = _plain("以下为打开卡片时的模型目录说明；展开对应模型查阅，不会改变选择或保存配置。")
+    panel: dict[str, Any] = {
+        "tag": "collapsible_panel", "expanded": False,
+        "header": {"title": _plain_text("模型介绍与迁移提示")},
+        "elements": [note],
+    }
+    card["body"]["elements"].append(panel)
+    shown = 0
+    for model in catalog.models[:40]:
+        entry = {
+            "tag": "collapsible_panel", "expanded": False,
+            "header": {"title": _plain_text(_text(model.display_name, 100))},
+            "elements": [_plain(_model_description(model))],
+        }
+        panel["elements"].append(entry)
+        # Reserve space for the omission notice. Presentation cannot prevent
+        # users from receiving or submitting the original model picker.
+        if len(json.dumps(card, ensure_ascii=False).encode("utf-8")) > TURN_FILE_CARD_JSON_LIMIT_BYTES - 600:
+            panel["elements"].pop()
+            break
+        shown += 1
+    if shown < len(catalog.models):
+        panel["elements"].append(_plain("卡片空间有限，部分模型介绍未展示；模型选项和保存逻辑不受影响。"))
+    if len(json.dumps(card, ensure_ascii=False).encode("utf-8")) > TURN_FILE_CARD_JSON_LIMIT_BYTES:
+        card["body"]["elements"].pop()
+    return card

netizen_cli/cards/questions.py

@@ -0,0 +1,220 @@
+"""Self-contained question forms; callback answers use ordinary input admission."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+from lark_channel import OutboundCard
+
+from ..user_questions import (
+    BindingQuestionTarget,
+    QuestionRequest,
+    QuestionTarget,
+    SideQuestionTarget,
+    UserQuestion,
+    format_question_answer,
+    question_target_payload,
+)
+from .callbacks import CardActionError, _builder, _notice, _plain, _plain_text
+from .reply import TURN_FILE_CARD_JSON_LIMIT_BYTES
+
+
+_KIND = "netizen_question"
+_VERSION = 2
+_CHOICE = "netizen_question_choice"
+_TEXT = "netizen_question_text"
+_MAX_ANSWER_CHARS = 1000
+QUESTION_CARD_JSON_LIMIT_BYTES = TURN_FILE_CARD_JSON_LIMIT_BYTES
+
+
+@dataclass(frozen=True, slots=True)
+class QuestionCardContext:
+    target: QuestionTarget
+    item_id: str
+    question_index: int
+    question: UserQuestion
+
+
+@dataclass(frozen=True, slots=True)
+class QuestionAnswer(QuestionCardContext):
+    answer: str
+    choice: str
+
+    @property
+    def prompt(self) -> str:
+        return format_question_answer(
+            self.item_id, self.question_index, self.question.title, self.answer
+        )
+
+
+def is_question_card_action(value: Any, form_value: Any = None) -> bool:
+    return (
+        isinstance(value, Mapping) and value.get("kind") == _KIND
+    ) or (
+        isinstance(form_value, Mapping)
+        and bool({_CHOICE, _TEXT} & form_value.keys())
+    )
+
+
+def _payload(context: QuestionCardContext) -> dict[str, Any]:
+    return {
+        "kind": _KIND,
+        "v": _VERSION,
+        "target": question_target_payload(context.target),
+        "item_id": context.item_id,
+        "question_index": context.question_index,
+        "title": context.question.title,
+        "options": list(context.question.options),
+        "nonce": uuid4().hex,
+    }
+
+
+def _target(payload: Mapping[str, Any]) -> QuestionTarget:
+    try:
+        if payload["v"] == 1:
+            return BindingQuestionTarget(payload["binding_id"])
+        target = payload["target"]
+        if isinstance(target, Mapping) and set(target) == {"kind", "id"}:
+            if target["kind"] == "binding":
+                return BindingQuestionTarget(target["id"])
+            if target["kind"] == "side":
+                return SideQuestionTarget(target["id"])
+    except (TypeError, ValueError):
+        pass
+    raise CardActionError("问题卡片的会话目标无效。")
+
+
+def _decoded(payload: Any) -> dict[str, Any]:
+    if not isinstance(payload, Mapping):
+        raise CardActionError("问题卡片字段不完整或含未知字段。")
+    payload = dict(payload)
+    payload.pop("nonce", None)  # Transport dedup only, never a business precondition.
+    version = payload.get("v")
+    if payload.get("kind") != _KIND or type(version) is not int or version not in {1, _VERSION}:
+        raise CardActionError("问题卡片版本无效，请在会话中直接回答。")
+    fields = {"kind", "v", "item_id", "question_index", "title", "options"}
+    fields.add("binding_id" if version == 1 else "target")
+    if set(payload) != fields:
+        raise CardActionError("问题卡片字段不完整或含未知字段。")
+    _target(payload)
+    item_id = payload["item_id"]
+    index = payload["question_index"]
+    title = payload["title"]
+    options = payload["options"]
+    if (
+        not isinstance(item_id, str)
+        or not item_id.strip()
+        or len(item_id) > 2048
+        or type(index) is not int
+        or not 0 <= index < 1000
+        or not isinstance(title, str)
+        or not title.strip()
+        or not isinstance(options, list)
+        or len(options) > 99
+        or any(not isinstance(option, str) or not option.strip() for option in options)
+    ):
+        raise CardActionError("问题卡片的会话、题目或选项无效。")
+    result = dict(payload)
+    if len(json.dumps(result, ensure_ascii=False).encode("utf-8")) > QUESTION_CARD_JSON_LIMIT_BYTES:
+        raise CardActionError("问题内容较长，无法展示完整选择卡片；请在会话中直接回答。")
+    return result
+
+
+def _context(payload: Mapping[str, Any]) -> QuestionCardContext:
+    return QuestionCardContext(
+        target=_target(payload),
+        item_id=payload["item_id"],
+        question_index=payload["question_index"],
+        question=UserQuestion(payload["title"], tuple(payload["options"])),
+    )
+
+
+def decode_question_context(value: Any) -> QuestionCardContext:
+    """Recover retry context even when the submitted answer is empty."""
+
+    return _context(_decoded(value))
+
+
+def decode_question_answer(value: Any, form_value: Any = None) -> QuestionAnswer:
+    payload = _decoded(value)
+    if not isinstance(form_value, Mapping) or set(form_value) - {_CHOICE, _TEXT}:
+        raise CardActionError("问题表单字段不匹配，请重新打开卡片。")
+    choice = form_value.get(_CHOICE, "free")
+    if not isinstance(choice, str) or choice not in {"free", *(str(index) for index in range(len(payload["options"])))}:
+        raise CardActionError("问题选项无效，请重新选择。")
+    if choice == "free":
+        answer = form_value.get(_TEXT) or ""
+        if not isinstance(answer, str) or len(answer) > _MAX_ANSWER_CHARS:
+            raise CardActionError("填写的回答无效或过长，请在会话中直接发送。")
+        if not answer.strip():
+            raise CardActionError("请选择一个建议，或选择自行填写并输入回答，然后点击提交。")
+    else:
+        answer = payload["options"][int(choice)]
+    context = _context(payload)
+    return QuestionAnswer(
+        context.target, context.item_id, context.question_index,
+        context.question, answer, choice,
+    )
+
+
+def render_question_card(
+    target: QuestionTarget,
+    request: QuestionRequest,
+    question_index: int,
+    *,
+    notice: str | None = None,
+) -> OutboundCard:
+    if type(question_index) is not int or not 0 <= question_index < len(request.questions):
+        raise CardActionError("问题序号无效。")
+    return render_question_context_card(
+        QuestionCardContext(target, request.item_id, question_index, request.questions[question_index]),
+        notice=notice,
+    )
+
+
+def render_question_context_card(
+    context: QuestionCardContext,
+    *,
+    notice: str | None = None,
+) -> OutboundCard:
+    payload = _payload(context)
+    _decoded(payload)
+    builder = _builder("Codex 提问", "选择建议或自行填写，再提交回答")
+    if notice:
+        builder.raw(_notice(notice))
+    builder.raw(_plain(context.question.title))
+    for index, option in enumerate(context.question.options):
+        builder.raw(_plain(f"{index + 1}. {option}"))
+    options = [{"text": _plain_text("自行填写"), "value": "free"}]
+    options.extend(
+        {"text": _plain_text(f"选项 {index + 1}"), "value": str(index)}
+        for index in range(len(context.question.options))
+    )
+    initial_choice = context.choice if isinstance(context, QuestionAnswer) else "free"
+    initial_text = context.answer if isinstance(context, QuestionAnswer) and context.choice == "free" else ""
+    builder.raw({
+        "tag": "form",
+        "name": "netizen_question",
+        "elements": [
+            {"tag": "select_static", "name": _CHOICE, "required": True,
+             "width": "fill", "options": options, "initial_option": initial_choice,
+             "placeholder": _plain_text("选择建议或自行填写")},
+            {"tag": "input", "name": _TEXT, "required": False,
+             "input_type": "multiline_text", "max_length": _MAX_ANSWER_CHARS,
+             "width": "fill", "placeholder": _plain_text("仅选择“自行填写”时提交此处内容"),
+             "default_value": initial_text},
+            {"tag": "button", "name": "netizen_question_submit", "text": _plain_text("提交回答"),
+             "type": "primary_filled", "width": "fill", "form_action_type": "submit",
+             "behaviors": [{"type": "callback", "value": payload}]},
+        ],
+    })
+    builder.raw(_plain("提交后请查看聊天中的处理反馈；如需重发，请在原会话直接发送回答。"))
+    card = builder.to_dict()
+    card["config"]["width_mode"] = "compact"
+    if len(json.dumps(card, ensure_ascii=False).encode("utf-8")) > QUESTION_CARD_JSON_LIMIT_BYTES:
+        raise CardActionError("问题内容较长，无法展示完整选择卡片；请在会话中直接回答。")
+    return OutboundCard(card=card)