@josephyan/qingflow-cli 0.2.0-beta.984 → 0.2.0-beta.986

package/src/qingflow_mcp/tools/base.py

@@ -1,14 +1,33 @@
 from __future__ import annotations
 
-from typing import Callable, TypeVar
+import inspect
+from contextvars import ContextVar
+from typing import Any, Callable, TypeVar
 
 from ..backend_client import BackendRequestContext, BackendClient
+from ..config import (
+    get_credit_meter_enabled,
+    get_credit_usage_base_url,
+    get_credit_usage_path,
+)
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
 from ..session_store import BackendSession, SessionProfile, SessionStore
 
 
 T = TypeVar("T")
+_RUN_DEPTH: ContextVar[int] = ContextVar("qingflow_mcp_tool_run_depth", default=0)
+
+
+def tool_cn_name(name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """为 tools 方法声明中文展示名（用于计费 extraInfo 记录）。"""
+    normalized = str(name).strip()
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(func, "__tool_cn_name__", normalized)
+        return func
+
+    return decorator
 
 
 class ToolBase:
@@ -28,18 +47,52 @@ class ToolBase:
         context = BackendRequestContext(
             base_url=backend_session.base_url,
             token=backend_session.token,
-            ws_id=session_profile.selected_ws_id if require_workspace else None,
+            # Keep the selected workspace in context whenever we know it.
+            # Some top-level tools (for example workspace browsing) do not
+            # require a workspace to execute, but credit metering still needs
+            # a stable wsId when the profile already has one selected.
+            ws_id=session_profile.selected_ws_id,
             qf_version=backend_session.qf_version,
             qf_version_source=backend_session.qf_version_source,
         )
         return session_profile, backend_session, context
 
     def _run(self, profile: str, func: Callable[[SessionProfile, BackendRequestContext], T], *, require_workspace: bool = True) -> T:
+        depth = _RUN_DEPTH.get()
+        depth_token = _RUN_DEPTH.set(depth + 1)
+        is_top_level_call = depth == 0
+        session_profile: SessionProfile | None = None
+        backend_session: BackendSession | None = None
+        tool_name = self._resolve_calling_tool_name()
         try:
-            session_profile, _, context = self._require_context(profile, require_workspace=require_workspace)
+            session_profile, backend_session, context = self._require_context(profile, require_workspace=require_workspace)
+            if is_top_level_call:
+                self._charge_tool_call(
+                    profile=profile,
+                    tool_name=tool_name,
+                    session_profile=session_profile,
+                    context=context,
+                )
             return func(session_profile, context)
         except QingflowApiError as error:
+            if (
+                error.looks_like_invalid_token()
+                and session_profile is not None
+                and backend_session is not None
+                and self._refresh_session_from_credential(
+                    profile,
+                    session_profile=session_profile,
+                    backend_session=backend_session,
+                )
+            ):
+                try:
+                    refreshed_profile, _, refreshed_context = self._require_context(profile, require_workspace=require_workspace)
+                    return func(refreshed_profile, refreshed_context)
+                except QingflowApiError as refreshed_error:
+                    self._handle_error(profile, refreshed_error)
             self._handle_error(profile, error)
+        finally:
+            _RUN_DEPTH.reset(depth_token)
         raise AssertionError("unreachable")
 
     def _handle_error(self, profile: str, error: QingflowApiError) -> None:
@@ -47,13 +100,160 @@ class ToolBase:
             self.sessions.invalidate(profile)
             error = QingflowApiError(
                 category="auth",
-                message=f"Qingflow session for profile '{profile}' has expired. Run auth_login again.",
+                message=f"Qingflow session for profile '{profile}' has expired. Run auth_use_credential again.",
                 backend_code=error.backend_code,
                 request_id=error.request_id,
                 http_status=error.http_status,
             )
         raise_tool_error(error)
 
+    def _refresh_session_from_credential(
+        self,
+        profile: str,
+        *,
+        session_profile: SessionProfile,
+        backend_session: BackendSession,
+    ) -> bool:
+        credential = (backend_session.credential or "").strip()
+        if not credential:
+            return False
+        try:
+            response = self.backend.public_request_with_meta(
+                "POST",
+                session_profile.base_url,
+                "/mcp/auth/context",
+                json_body={"credential": credential},
+                qf_version=backend_session.qf_version,
+            )
+            payload = self._unwrap_context_payload(response.data)
+            token = self._normalize_text(payload.get("token"))
+            ws_id = self._coerce_positive_int(payload.get("wsId"))
+            uid = self._coerce_positive_int(payload.get("uid")) or session_profile.uid
+            if not token or ws_id is None:
+                return False
+            backend_qf_version = self._normalize_text(payload.get("qfVersion")) or response.qf_response_version
+            qf_version = backend_qf_version if backend_qf_version is not None else backend_session.qf_version
+            qf_version_source = (
+                "backend_response"
+                if backend_qf_version is not None
+                else backend_session.qf_version_source
+            )
+            base_url = self._normalize_text(payload.get("baseUrl")) or session_profile.base_url
+            ws_name = self._normalize_text(payload.get("wsName")) or session_profile.selected_ws_name
+            self.sessions.save_session(
+                profile=profile,
+                base_url=base_url,
+                qf_version=qf_version,
+                qf_version_source=qf_version_source,
+                token=token,
+                login_token=None,
+                credential=credential,
+                uid=uid,
+                email=self._normalize_text(payload.get("email")) or session_profile.email,
+                nick_name=(
+                    self._normalize_text(payload.get("nickName"))
+                    or self._normalize_text(payload.get("displayName"))
+                    or self._normalize_text(payload.get("name"))
+                    or session_profile.nick_name
+                ),
+                persist=session_profile.persisted,
+            )
+            self.sessions.select_workspace(profile, ws_id=ws_id, ws_name=ws_name)
+            return True
+        except QingflowApiError:
+            return False
+
+    def _unwrap_context_payload(self, payload: Any) -> dict[str, Any]:
+        if not isinstance(payload, dict):
+            return {}
+        nested = payload.get("data")
+        if isinstance(nested, dict):
+            return nested
+        nested = payload.get("result")
+        if isinstance(nested, dict):
+            return nested
+        return payload
+
+    def _normalize_text(self, value: Any) -> str | None:
+        if value is None:
+            return None
+        text = str(value).strip()
+        return text or None
+
+    def _coerce_positive_int(self, value: Any) -> int | None:
+        if isinstance(value, bool) or value is None:
+            return None
+        try:
+            parsed = int(value)
+        except (TypeError, ValueError):
+            return None
+        return parsed if parsed > 0 else None
+
+    def _resolve_calling_tool_name(self) -> str:
+        frame = inspect.currentframe()
+        if frame is None:
+            return "unknown_tool"
+        caller = frame.f_back.f_back if frame.f_back is not None else None
+        try:
+            if caller is None:
+                return "unknown_tool"
+            name = caller.f_code.co_name
+            if not name:
+                return "unknown_tool"
+            method = getattr(self, name, None)
+            cn_name = getattr(method, "__tool_cn_name__", None)
+            if isinstance(cn_name, str) and cn_name.strip():
+                return cn_name.strip()
+            return name
+        finally:
+            del frame
+
+    def _charge_tool_call(
+        self,
+        *,
+        profile: str,
+        tool_name: str,
+        session_profile: SessionProfile,
+        context: BackendRequestContext,
+    ) -> None:
+        if not get_credit_meter_enabled():
+            return
+        if context.ws_id is None:
+            raise_tool_error(QingflowApiError(category="payment", message="credit meter requires wsId in current session context"))
+
+        self._record_credit_usage(
+            tool_name=tool_name,
+            context=context,
+        )
+
+    def _record_credit_usage(
+        self,
+        *,
+        tool_name: str,
+        context: BackendRequestContext,
+    ) -> None:
+        usage_context = BackendRequestContext(
+            base_url=get_credit_usage_base_url() or context.base_url,
+            token=context.token,
+            ws_id=context.ws_id,
+            qf_request_id=context.qf_request_id,
+            qf_version=context.qf_version,
+            qf_version_source=context.qf_version_source,
+        )
+        self.backend.request(
+            "POST",
+            usage_context,
+            get_credit_usage_path(),
+            json_body={
+                "skuType": "MCP",
+                "skuName": "MCP",
+                "modelName": "MCP",
+                "scene": "MCP",
+                "aiBiz": "MCP",
+                "extraInfo": tool_name,
+            },
+        )
+
     def _require_dict(self, payload: JSONObject | None, field_name: str = "payload") -> JSONObject:
         if not isinstance(payload, dict) or not payload:
             raise_tool_error(QingflowApiError.config_error(f"{field_name} must be a non-empty object"))

package/src/qingflow_mcp/tools/code_block_tools.py

@@ -7,6 +7,7 @@ from mcp.server.fastmcp import FastMCP
 from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject, JSONValue
+from .base import tool_cn_name
 from .record_tools import (
     ATTACHMENT_QUE_TYPES,
     DEPARTMENT_QUE_TYPES,
@@ -33,6 +34,15 @@ SUPPORTED_CODE_BLOCK_ROLES = {1, 2, 3, 5}
 
 
 class CodeBlockTools(RecordTools):
+    """代码块工具（中文名：代码块运行与映射）。
+
+    类型：记录增强工具。
+    主要职责：
+    1. 读取代码块字段配置与关联关系；
+    2. 执行代码块并处理返回别名；
+    3. 按规则回写目标字段并输出执行摘要。
+    """
+
     def _get_code_block_relation_schema(
         self,
         profile: str,
@@ -41,6 +51,7 @@ class CodeBlockTools(RecordTools):
         *,
         force_refresh: bool,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         cache_key = (profile, app_key, "code_block_relation_form", 1)
         if not force_refresh and cache_key in self._form_cache:
             return self._form_cache[cache_key]
@@ -55,6 +66,7 @@ class CodeBlockTools(RecordTools):
         return normalized
 
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         super().register(mcp)
 
         @mcp.tool()
@@ -107,6 +119,7 @@ class CodeBlockTools(RecordTools):
                 output_profile=output_profile,
             )
 
+    @tool_cn_name("代码块 Schema")
     def record_code_block_schema_get_public(
         self,
         *,
@@ -114,6 +127,7 @@ class CodeBlockTools(RecordTools):
         app_key: str,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
@@ -177,6 +191,7 @@ class CodeBlockTools(RecordTools):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("运行代码块")
     def record_code_block_run(
         self,
         *,
@@ -194,6 +209,7 @@ class CodeBlockTools(RecordTools):
         force_refresh_form: bool = False,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_record_id = self._validate_app_and_record(app_key, record_id)
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if role not in SUPPORTED_CODE_BLOCK_ROLES:
@@ -408,6 +424,7 @@ class CodeBlockTools(RecordTools):
         role: int,
         audit_node_id: int | None,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         last_error: QingflowApiError | None = None
         for list_type in self._INTERNAL_GET_LIST_TYPE_FALLBACKS:
             params: JSONObject = {"role": role, "listType": list_type}
@@ -427,6 +444,7 @@ class CodeBlockTools(RecordTools):
         raise_tool_error(QingflowApiError.config_error("record answers could not be loaded for code-block execution"))
 
     def _answers_to_open_match_values(self, answers: list[JSONObject], index: FieldIndex) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         values: list[JSONObject] = []
         for answer in answers:
             if not isinstance(answer, dict):
@@ -438,6 +456,7 @@ class CodeBlockTools(RecordTools):
         return values
 
     def _answer_to_open_match_value(self, answer: JSONObject, index: FieldIndex) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         que_id = _coerce_count(answer.get("queId", answer.get("que_id")))
         if que_id is None or que_id <= 0:
             return None
@@ -470,6 +489,7 @@ class CodeBlockTools(RecordTools):
         }
 
     def _answer_values_to_code_block_values(self, answer: JSONObject, field: FormField) -> list[str]:
+        """执行内部辅助逻辑。"""
         if field.que_type in RELATION_QUE_TYPES:
             return _relation_ids_from_answer(answer)
         raw_values = answer.get("values")
@@ -494,6 +514,7 @@ class CodeBlockTools(RecordTools):
         role: int,
         audit_node_id: int | None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if role == 1 and audit_node_id is None:
             return self._verify_record_write_result(
                 context,

package/src/qingflow_mcp/tools/custom_button_tools.py

@@ -5,10 +5,20 @@ from copy import deepcopy
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 class CustomButtonTools(ToolBase):
+    """自定义按钮工具（中文名：按钮配置管理）。
+
+    类型：应用配置工具。
+    主要职责：
+    1. 查询应用自定义按钮；
+    2. 创建、更新、删除按钮配置；
+    3. 支持草稿与发布态按钮配置维护。
+    """
+
+    @tool_cn_name("自定义按钮列表")
     def custom_button_list(
         self,
         *,
@@ -17,6 +27,7 @@ class CustomButtonTools(ToolBase):
         being_draft: bool = True,
         include_raw: bool = False,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -47,6 +58,7 @@ class CustomButtonTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("自定义按钮详情")
     def custom_button_get(
         self,
         *,
@@ -56,6 +68,7 @@ class CustomButtonTools(ToolBase):
         being_draft: bool = True,
         include_raw: bool = False,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         self._require_button_id(button_id)
 
@@ -77,7 +90,9 @@ class CustomButtonTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("创建自定义按钮")
     def custom_button_create(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -87,7 +102,9 @@ class CustomButtonTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新自定义按钮")
     def custom_button_update(self, *, profile: str, app_key: str, button_id: int, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         self._require_button_id(button_id)
         body = self._require_dict(payload)
@@ -113,7 +130,9 @@ class CustomButtonTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("删除自定义按钮")
     def custom_button_delete(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_app_key(app_key)
         self._require_button_id(button_id)
 
@@ -134,14 +153,17 @@ class CustomButtonTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_app_key(self, app_key: str) -> None:
+        """执行内部辅助逻辑。"""
         if not str(app_key or "").strip():
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
     def _require_button_id(self, button_id: int) -> None:
+        """执行内部辅助逻辑。"""
         if not isinstance(button_id, int) or isinstance(button_id, bool) or button_id <= 0:
             raise_tool_error(QingflowApiError.config_error("button_id must be a positive integer"))
 
     def _compact_button_base_info(self, item: dict[str, object]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         creator = item.get("creatorUserInfo") if isinstance(item.get("creatorUserInfo"), dict) else {}
         return {
             "button_id": item.get("buttonId"),
@@ -162,6 +184,7 @@ class CustomButtonTools(ToolBase):
         }
 
     def _compact_button_detail(self, item: dict[str, object]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         return {
             "button_id": item.get("buttonId"),
             "button_text": item.get("buttonText"),

package/src/qingflow_mcp/tools/directory_tools.py

@@ -7,14 +7,24 @@ from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 ALLOWED_DIRECTORY_SEARCH_SCOPES = {"MEMBER", "DEPT"}
 
 
 class DirectoryTools(ToolBase):
+    """组织架构工具（中文名：通讯录与组织目录）。
+
+    类型：组织目录工具。
+    主要职责：
+    1. 搜索用户、部门、外部联系人；
+    2. 列举内部用户与部门层级；
+    3. 为审批/字段候选提供目录侧数据来源。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def directory_search(
             profile: str = DEFAULT_PROFILE,
@@ -122,6 +132,7 @@ class DirectoryTools(ToolBase):
                 simple=simple,
             )
 
+    @tool_cn_name("通讯录搜索")
     def directory_search(
         self,
         *,
@@ -131,6 +142,7 @@ class DirectoryTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
+        """执行组织目录相关逻辑。"""
         normalized_scopes = scopes or ["MEMBER", "DEPT"]
         invalid_scopes = [scope for scope in normalized_scopes if scope not in ALLOWED_DIRECTORY_SEARCH_SCOPES]
         if invalid_scopes:
@@ -172,6 +184,7 @@ class DirectoryTools(ToolBase):
             selection={"query": query, "scopes": normalized_scopes},
         )
 
+    @tool_cn_name("内部成员列表")
     def directory_list_internal_users(
         self,
         *,
@@ -183,6 +196,7 @@ class DirectoryTools(ToolBase):
         page_size: int,
         contain_disable: bool,
     ) -> dict[str, Any]:
+        """执行组织目录相关逻辑。"""
         def runner(session_profile, context):
             params: dict[str, Any] = {
                 "pageNum": page_num,
@@ -218,6 +232,7 @@ class DirectoryTools(ToolBase):
             selection={"keyword": keyword, "department_id": dept_id, "role_id": role_id, "include_disabled": contain_disable},
         )
 
+    @tool_cn_name("内部成员全量")
     def directory_list_all_internal_users(
         self,
         *,
@@ -229,6 +244,7 @@ class DirectoryTools(ToolBase):
         contain_disable: bool,
         max_pages: int,
     ) -> dict[str, Any]:
+        """执行组织目录相关逻辑。"""
         if page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
         if max_pages <= 0:
@@ -295,6 +311,7 @@ class DirectoryTools(ToolBase):
             selection={"keyword": keyword, "department_id": dept_id, "role_id": role_id, "include_disabled": contain_disable},
         )
 
+    @tool_cn_name("内部部门列表")
     def directory_list_internal_departments(
         self,
         *,
@@ -303,6 +320,7 @@ class DirectoryTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
+        """执行组织目录相关逻辑。"""
         if page_num <= 0:
             raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
         if page_size <= 0:
@@ -377,6 +395,7 @@ class DirectoryTools(ToolBase):
             selection={"keyword": normalized_keyword},
         )
 
+    @tool_cn_name("部门树全量")
     def directory_list_all_departments(
         self,
         *,
@@ -385,6 +404,7 @@ class DirectoryTools(ToolBase):
         max_depth: int,
         max_items: int,
     ) -> dict[str, Any]:
+        """执行组织目录相关逻辑。"""
         if max_depth < 0:
             raise_tool_error(QingflowApiError.config_error("max_depth must be non-negative"))
         if max_items <= 0:
@@ -427,7 +447,9 @@ class DirectoryTools(ToolBase):
             selection={"parent_department_id": parent_dept_id, "max_depth": max_depth, "max_items": max_items},
         )
 
+    @tool_cn_name("子部门列表")
     def directory_list_sub_departments(self, *, profile: str, parent_dept_id: int | None) -> dict[str, Any]:
+        """执行组织目录相关逻辑。"""
         def runner(session_profile, context):
             params: dict[str, Any] = {}
             if parent_dept_id is not None:
@@ -449,6 +471,7 @@ class DirectoryTools(ToolBase):
             selection={"parent_department_id": parent_dept_id},
         )
 
+    @tool_cn_name("外部联系人列表")
     def directory_list_external_members(
         self,
         *,
@@ -458,6 +481,7 @@ class DirectoryTools(ToolBase):
         page_size: int,
         simple: bool,
     ) -> dict[str, Any]:
+        """执行组织目录相关逻辑。"""
         def runner(session_profile, context):
             if simple:
                 result = self.backend.request(
@@ -495,6 +519,7 @@ class DirectoryTools(ToolBase):
         )
 
     def _request_route_payload(self, context) -> dict[str, Any]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         describe_route = getattr(self.backend, "describe_route", None)
         if callable(describe_route):
             payload = describe_route(context)
@@ -514,6 +539,7 @@ class DirectoryTools(ToolBase):
         pagination: dict[str, Any],
         selection: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         response = dict(raw)
         response["ok"] = bool(raw.get("ok", True))
         response["warnings"] = []
@@ -533,6 +559,7 @@ class DirectoryTools(ToolBase):
         max_depth: int,
         max_items: int,
     ) -> tuple[list[dict[str, Any]], bool, int]:
+        """执行内部辅助逻辑。"""
         queue: deque[tuple[int | None, int]] = deque([(parent_dept_id, 0)])
         seen_ids: set[int] = set()
         requested_parents: set[int | None] = set()

package/src/qingflow_mcp/tools/feedback_tools.py

@@ -8,6 +8,7 @@ from ..backend_client import BackendClient
 from ..config import get_feedback_app_key, get_feedback_base_url, get_feedback_qsource_token, normalize_base_url
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
+from .base import tool_cn_name
 
 
 CATEGORY_MAP = {
@@ -32,6 +33,7 @@ class FeedbackTools:
     mcp_side: str
 
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def feedback_submit(
             category: str = "",
@@ -66,6 +68,7 @@ class FeedbackTools:
                 note=note,
             )
 
+    @tool_cn_name("提交反馈")
     def feedback_submit(
         self,
         *,
@@ -81,6 +84,7 @@ class FeedbackTools:
         workflow_node_id: str | int | None,
         note: str | None,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         qsource_token = get_feedback_qsource_token()
         if not qsource_token:
             raise_tool_error(
@@ -161,6 +165,7 @@ class FeedbackTools:
         workflow_node_id: str | int | None,
         note: str | None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         payload: JSONObject = {
             "title": self._require_text("title", title),
             "category": self._normalize_label("category", category, CATEGORY_MAP, required=True),
@@ -193,6 +198,7 @@ class FeedbackTools:
         return payload
 
     def _normalize_label(self, field: str, value: str, mapping: dict[str, str], *, required: bool) -> str:
+        """执行内部辅助逻辑。"""
         text = str(value or "").strip()
         if not text:
             if required:
@@ -218,12 +224,14 @@ class FeedbackTools:
         )
 
     def _require_text(self, field: str, value: str) -> str:
+        """执行内部辅助逻辑。"""
         normalized = str(value or "").strip()
         if not normalized:
             raise_tool_error(QingflowApiError.config_error(f"{field} is required"))
         return normalized
 
     def _normalize_optional_text(self, value: str | None) -> str | None:
+        """执行内部辅助逻辑。"""
         if value is None:
             return None
         normalized = str(value).strip()