@josephyan/qingflow-cli 0.2.0-beta.985 → 0.2.0-beta.987

package/src/qingflow_mcp/tools/record_tools.py

@@ -21,7 +21,7 @@ from ..list_type_labels import (
     get_system_view_id,
     get_system_view_name,
 )
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 from .directory_tools import _directory_has_more, _directory_items
 
 
@@ -240,7 +240,17 @@ FIELD_LOOKUP_STRIP_RE = re.compile(r"[\s_()（）\[\]【】{}<>·/\\:：-]+")
 
 
 class RecordTools(ToolBase):
+    """记录工具（中文名：记录读写与分析）。
+
+    类型：业务数据操作工具。
+    主要职责：
+    1. 提供记录 Schema、记录查询、记录 CRUD；
+    2. 提供成员/部门候选与代码块相关能力；
+    3. 提供面向分析场景的数据读取与字段归一化能力。
+    """
+
     def __init__(self, sessions, backend) -> None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
         self._form_cache: dict[tuple[str, str, str, int | None], JSONObject] = {}
         self._applicant_node_cache: dict[tuple[str, str], WorkflowNodeRef] = {}
@@ -250,6 +260,7 @@ class RecordTools(ToolBase):
         self._relation_base_info_cache: dict[tuple[str, int], JSONObject] = {}
 
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def record_insert_schema_get(
             app_key: str = "",
@@ -506,6 +517,7 @@ class RecordTools(ToolBase):
                 output_profile=output_profile,
             )
 
+    @tool_cn_name("记录 Schema")
     def record_schema_get(
         self,
         *,
@@ -518,6 +530,7 @@ class RecordTools(ToolBase):
         view_name: str | None = None,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         normalized_schema_mode = schema_mode.strip().lower()
@@ -630,6 +643,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("新增记录 Schema")
     def record_insert_schema_get_public(
         self,
         *,
@@ -637,6 +651,7 @@ class RecordTools(ToolBase):
         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)
@@ -745,6 +760,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("浏览记录 Schema")
     def record_browse_schema_get_public(
         self,
         *,
@@ -753,6 +769,7 @@ class RecordTools(ToolBase):
         view_id: str,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         return self.record_schema_get(
             profile=profile,
             app_key=app_key,
@@ -761,6 +778,7 @@ class RecordTools(ToolBase):
             output_profile=output_profile,
         )
 
+    @tool_cn_name("更新记录 Schema")
     def record_update_schema_get_public(
         self,
         *,
@@ -769,6 +787,7 @@ class RecordTools(ToolBase):
         record_id: int,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if record_id <= 0:
@@ -981,6 +1000,7 @@ class RecordTools(ToolBase):
         view_probe_summary: list[JSONObject],
         ambiguous_fields: list[JSONObject],
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         response: JSONObject = {
             "profile": profile,
             "ws_id": ws_id,
@@ -1010,7 +1030,9 @@ class RecordTools(ToolBase):
         ws_id: int | None,
         required_override: bool | None,
         linkage_payloads_by_field_id: dict[str, JSONObject] | None = None,
+        include_field_id: bool = True,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         kind = self._ready_schema_kind(field)
         row_fields: list[JSONObject] = []
         if kind == "subtable":
@@ -1025,11 +1047,12 @@ class RecordTools(ToolBase):
         else:
             required = bool(required_override) if required_override is not None else bool(field.required)
         payload: JSONObject = {
-            "field_id": field.que_id,
             "title": field.que_title,
             "kind": kind,
             "required": required,
         }
+        if include_field_id:
+            payload["field_id"] = field.que_id
         if kind in {"single_select", "multi_select"} and field.options:
             payload["options"] = list(field.options)
         if kind in {"member", "department", "relation"}:
@@ -1077,6 +1100,7 @@ class RecordTools(ToolBase):
         reason: str,
         linkage_payloads_by_field_id: dict[str, JSONObject] | None = None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         payload = self._ready_schema_field_payload(
             profile,
             context,
@@ -1084,6 +1108,7 @@ class RecordTools(ToolBase):
             ws_id=ws_id,
             required_override=True,
             linkage_payloads_by_field_id=linkage_payloads_by_field_id,
+            include_field_id=False,
         )
         payload["reason"] = reason
         self._attach_ready_schema_linkage(
@@ -1102,6 +1127,7 @@ class RecordTools(ToolBase):
         linkage_payloads_by_field_id: dict[str, JSONObject] | None,
         role_override: str | None = None,
     ) -> None:
+        """执行内部辅助逻辑。"""
         if not linkage_payloads_by_field_id:
             return
         linkage_payload = linkage_payloads_by_field_id.get(field_id)
@@ -1118,6 +1144,7 @@ class RecordTools(ToolBase):
         *,
         runtime_linked_field_ids: set[str],
     ) -> bool:
+        """执行内部辅助逻辑。"""
         if not bool(field.required) or bool(field.system) or not bool(field.readonly):
             return False
         if str(field.que_id) not in runtime_linked_field_ids:
@@ -1139,6 +1166,7 @@ class RecordTools(ToolBase):
         ws_id: int | None,
         linkage_payloads_by_field_id: dict[str, JSONObject] | None = None,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         raw = field.raw if isinstance(field.raw, dict) else {}
         columns_source = raw.get("subQuestions")
         if isinstance(columns_source, list):
@@ -1161,11 +1189,13 @@ class RecordTools(ToolBase):
                     ws_id=ws_id,
                     required_override=bool(subfield.required),
                     linkage_payloads_by_field_id=linkage_payloads_by_field_id,
+                    include_field_id=False,
                 )
             )
         return payloads
 
     def _ready_schema_kind(self, field: FormField) -> str:
+        """执行内部辅助逻辑。"""
         write_format = _write_format_for_field(field)
         write_kind = _normalize_optional_text(write_format.get("kind")) or "scalar_text"
         if write_kind == "subtable_rows":
@@ -1198,6 +1228,7 @@ class RecordTools(ToolBase):
         return "text"
 
     def _ready_schema_template_value(self, field_payload: JSONObject) -> JSONValue:
+        """执行内部辅助逻辑。"""
         kind = _normalize_optional_text(field_payload.get("kind")) or "text"
         if kind == "number":
             return "<number>"
@@ -1243,6 +1274,7 @@ class RecordTools(ToolBase):
             ]
         return "<text>"
 
+    @tool_cn_name("成员候选项")
     def record_member_candidates(
         self,
         *,
@@ -1256,6 +1288,7 @@ class RecordTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if field_id <= 0:
@@ -1345,6 +1378,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("部门候选项")
     def record_department_candidates(
         self,
         *,
@@ -1358,6 +1392,7 @@ class RecordTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if field_id <= 0:
@@ -1464,6 +1499,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("记录分析")
     def record_analyze(
         self,
         *,
@@ -1481,6 +1517,7 @@ class RecordTools(ToolBase):
         view_name: str | None = None,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if limit <= 0:
@@ -1551,6 +1588,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("记录列表")
     def record_list(
         self,
         *,
@@ -1567,6 +1605,7 @@ class RecordTools(ToolBase):
         view_name: str | None = None,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile, allow_normalized=True)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -1708,6 +1747,7 @@ class RecordTools(ToolBase):
             }
         return response
 
+    @tool_cn_name("记录详情")
     def record_get_public(
         self,
         *,
@@ -1719,6 +1759,7 @@ class RecordTools(ToolBase):
         workflow_node_id: int | None = None,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile, allow_normalized=True)
         if record_id <= 0:
             raise_tool_error(QingflowApiError.config_error("record_id must be positive"))
@@ -1851,6 +1892,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("新增记录")
     def record_insert_public(
         self,
         *,
@@ -1860,6 +1902,7 @@ class RecordTools(ToolBase):
         verify_write: bool = True,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -1926,6 +1969,7 @@ class RecordTools(ToolBase):
             preflight=raw_preflight,
         )
 
+    @tool_cn_name("更新记录")
     def record_update_public(
         self,
         *,
@@ -1938,6 +1982,7 @@ class RecordTools(ToolBase):
         verify_write: bool = True,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -1982,6 +2027,7 @@ class RecordTools(ToolBase):
         verify_write: bool,
         output_profile: str,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         raw_preflight = self._preflight_record_update_with_auto_view(
             profile=profile,
             app_key=app_key,
@@ -2047,6 +2093,7 @@ class RecordTools(ToolBase):
         verify_write: bool,
         output_profile: str,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         preflight_responses = [
             self._record_update_public_preflight_response(
                 profile=profile,
@@ -2115,6 +2162,7 @@ class RecordTools(ToolBase):
         fields: JSONObject,
         output_profile: str,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         raw_preflight = self._preflight_record_update_with_auto_view(
             profile=profile,
             app_key=app_key,
@@ -2157,6 +2205,7 @@ class RecordTools(ToolBase):
         fields: JSONObject | None,
         items: list[JSONObject] | None,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if record_id is not None or fields is not None:
             raise_tool_error(
                 QingflowApiError.config_error("record_update batch mode does not accept record_id or fields")
@@ -2191,6 +2240,7 @@ class RecordTools(ToolBase):
         output_profile: str,
         dry_run: bool,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         summary = self._record_update_batch_summary(responses)
         batch_items = [self._record_update_batch_item_from_response(response, output_profile=output_profile) for response in responses]
         status, ok, message = self._record_update_batch_envelope_status(summary=summary, dry_run=dry_run)
@@ -2214,6 +2264,7 @@ class RecordTools(ToolBase):
         }
 
     def _record_update_batch_summary(self, responses: list[JSONObject]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         summary: JSONObject = {
             "total": len(responses),
             "ready_count": 0,
@@ -2250,6 +2301,7 @@ class RecordTools(ToolBase):
         return summary
 
     def _record_update_batch_envelope_status(self, *, summary: JSONObject, dry_run: bool) -> tuple[str, bool, str]:
+        """执行内部辅助逻辑。"""
         if int(summary["blocked_count"]) > 0:
             return "blocked", False, "batch update preflight blocked"
         if int(summary["confirmation_count"]) > 0:
@@ -2261,6 +2313,7 @@ class RecordTools(ToolBase):
         return "success", True, "batch update completed"
 
     def _record_update_batch_item_from_response(self, response: JSONObject, *, output_profile: str) -> JSONObject:
+        """执行内部辅助逻辑。"""
         data = cast(JSONObject, response.get("data", {}))
         item: JSONObject = {
             "resource": data.get("resource"),
@@ -2292,6 +2345,7 @@ class RecordTools(ToolBase):
         fields: JSONObject,
         force_refresh_form: bool,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         def runner(session_profile, context):
             request_route = self._request_route_payload(context)
             def build_once(*, effective_force_refresh: bool) -> JSONObject:
@@ -2583,6 +2637,7 @@ class RecordTools(ToolBase):
         matched_routes: list[AccessibleViewRoute],
         force_refresh_form: bool,
     ) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         if len(matched_routes) < 2:
             return None
 
@@ -2745,6 +2800,7 @@ class RecordTools(ToolBase):
         view_probe_summary: list[JSONObject],
         template: JSONObject | None = None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         blocked_data: JSONObject = dict(template or {})
         validation = blocked_data.get("validation")
         if not isinstance(validation, dict):
@@ -2788,6 +2844,7 @@ class RecordTools(ToolBase):
         context,  # type: ignore[no-untyped-def]
         app_key: str,
     ) -> list[AccessibleViewRoute]:
+        """执行内部辅助逻辑。"""
         candidates: list[AccessibleViewRoute] = []
         for view_id, list_type, name in SYSTEM_VIEW_DEFINITIONS:
             candidates.append(
@@ -2996,6 +3053,7 @@ class RecordTools(ToolBase):
         *,
         resolved_view: AccessibleViewRoute,
     ) -> bool:
+        """执行内部辅助逻辑。"""
         if resolved_view.kind == "system":
             return True
         return self._matches_view_selection(
@@ -3005,6 +3063,7 @@ class RecordTools(ToolBase):
             dept_member_cache={},
         )
 
+    @tool_cn_name("删除记录")
     def record_delete_public(
         self,
         *,
@@ -3014,6 +3073,7 @@ class RecordTools(ToolBase):
         record_ids: list[int] | None = None,
         output_profile: str = "normal",
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -3038,6 +3098,7 @@ class RecordTools(ToolBase):
             preflight=None,
         )
 
+    @tool_cn_name("写入记录")
     def record_write(
         self,
         *,
@@ -3057,6 +3118,7 @@ class RecordTools(ToolBase):
         output_profile: str = "normal",
         mode: str | None = None,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         normalized_operation = operation.strip().lower()
         if normalized_operation not in {"insert", "update", "delete"}:
@@ -3261,6 +3323,7 @@ class RecordTools(ToolBase):
         schema_mode: str = "applicant",
         browse_writable: bool | None = None,
     ) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         write_hints = self._schema_write_hints(field)
         if schema_mode == "applicant":
             writable = write_hints["writable"]
@@ -3305,6 +3368,7 @@ class RecordTools(ToolBase):
         return payload
 
     def _schema_role_hints(self, field: FormField) -> JSONObject:
+        """执行内部辅助逻辑。"""
         field_family = self._schema_field_family(field)
         time_candidate = field.que_type in DATE_QUE_TYPES
         identifier_like = self._schema_is_identifier_like(field, field_family=field_family)
@@ -3323,6 +3387,7 @@ class RecordTools(ToolBase):
         }
 
     def _schema_write_hints(self, field: FormField) -> JSONObject:
+        """执行内部辅助逻辑。"""
         write_format = _write_format_for_field(field)
         kind = _normalize_optional_text(write_format.get("kind")) or "scalar_text"
         support_level = _normalize_optional_text(write_format.get("support_level")) or "full"
@@ -3350,6 +3415,7 @@ class RecordTools(ToolBase):
         }
 
     def _schema_write_kind(self, kind: str) -> str:
+        """执行内部辅助逻辑。"""
         mapping = {
             "single_select": "select",
             "multi_select": "select",
@@ -3373,6 +3439,7 @@ class RecordTools(ToolBase):
         target_app_key: str,
         ws_id: int | None,
     ) -> str | None:
+        """执行内部辅助逻辑。"""
         cache_key = (profile, ws_id, target_app_key)
         if cache_key in self._app_name_cache:
             return self._app_name_cache[cache_key]
@@ -3391,6 +3458,7 @@ class RecordTools(ToolBase):
         return name
 
     def _lookup_context_answers(self, state: LookupResolutionState) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         merged: dict[int, JSONObject] = {}
         ordered_ids: list[int] = []
         for answer in state.base_answers:
@@ -3414,6 +3482,7 @@ class RecordTools(ToolBase):
         return [merged[que_id] for que_id in ordered_ids]
 
     def _answers_to_lookup_key_values(self, answers: list[JSONObject], index: FieldIndex) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         values: list[JSONObject] = []
         for answer in answers:
             if not isinstance(answer, dict):
@@ -3425,6 +3494,7 @@ class RecordTools(ToolBase):
         return values
 
     def _answer_to_lookup_key_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
@@ -3456,6 +3526,7 @@ class RecordTools(ToolBase):
         }
 
     def _answer_values_to_lookup_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")
@@ -3492,6 +3563,7 @@ class RecordTools(ToolBase):
         return normalized
 
     def _lookup_key_que_values(self, state: LookupResolutionState) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         answers = self._lookup_context_answers(state)
         if not answers:
             return []
@@ -3506,6 +3578,7 @@ class RecordTools(ToolBase):
         page_num: int = 1,
         page_size: int = LOOKUP_RELATION_FILTER_PAGE_SIZE,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         payload: JSONObject = {
             "role": 1,
             "pageNum": page_num,
@@ -3525,6 +3598,7 @@ class RecordTools(ToolBase):
         return payload
 
     def _relation_base_info(self, context, *, app_key: str, field: FormField) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         cache_key = (app_key, field.que_id)
         if cache_key in self._relation_base_info_cache:
             return self._relation_base_info_cache[cache_key]
@@ -3544,6 +3618,7 @@ class RecordTools(ToolBase):
         app_key: str,
         field: FormField,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         direct = _relation_searchable_fields_for_question(field.raw)
         return direct
 
@@ -3554,6 +3629,7 @@ class RecordTools(ToolBase):
         field: FormField,
         app_key: str,
     ) -> list[tuple[JSONObject, FormField]]:
+        """执行内部辅助逻辑。"""
         searchable_fields = self._relation_searchable_fields_for_field(context, app_key=app_key, field=field)
         if not searchable_fields:
             return []
@@ -3607,6 +3683,7 @@ class RecordTools(ToolBase):
         page_num: int = 1,
         page_size: int = LOOKUP_RELATION_FILTER_PAGE_SIZE,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         payload: JSONObject = {
             "appKey": state.app_key,
             "queId": field.que_id,
@@ -3628,6 +3705,7 @@ class RecordTools(ToolBase):
         return payload
 
     def _normalize_relation_candidate_value(self, value: JSONValue) -> JSONValue:
+        """执行内部辅助逻辑。"""
         if value is None:
             return None
         if isinstance(value, dict):
@@ -3656,6 +3734,7 @@ class RecordTools(ToolBase):
         *,
         field_defs: list[tuple[JSONObject, FormField]],
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if not isinstance(payload, dict):
             return []
         rows = payload.get("list")
@@ -3731,6 +3810,7 @@ class RecordTools(ToolBase):
         return candidates
 
     def _relation_confirmation_candidates(self, candidates: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         payloads: list[JSONObject] = []
         for candidate in candidates[:LOOKUP_CONFIRMATION_CANDIDATE_LIMIT]:
             payloads.append(
@@ -3753,6 +3833,7 @@ class RecordTools(ToolBase):
         keyword: str,
         state: LookupResolutionState,
     ) -> tuple[list[JSONObject], list[JSONObject]]:
+        """执行内部辅助逻辑。"""
         field_defs = self._relation_search_field_defs(context, field=field, app_key=state.app_key)
         searchable_fields = [item for item, _ in field_defs]
         try:
@@ -3781,6 +3862,7 @@ class RecordTools(ToolBase):
         return self._normalize_relation_candidates(result, field_defs=field_defs), searchable_fields
 
     def _lookup_context_is_incomplete(self, state: LookupResolutionState | None) -> bool:
+        """执行内部辅助逻辑。"""
         return bool(state is not None and not state.context_complete)
 
     def _candidate_lookup_uses_runtime_scope(
@@ -3790,6 +3872,7 @@ class RecordTools(ToolBase):
         workflow_node_id: int | None,
         fields: JSONObject | None,
     ) -> bool:
+        """执行内部辅助逻辑。"""
         return bool(
             (record_id is not None and record_id > 0)
             or (workflow_node_id is not None and workflow_node_id > 0)
@@ -3806,6 +3889,7 @@ class RecordTools(ToolBase):
         workflow_node_id: int | None,
         fields: JSONObject,
     ) -> LookupResolutionState:
+        """执行内部辅助逻辑。"""
         index = self._get_field_index(profile, context, app_key, force_refresh=False)
         apply_id = record_id if isinstance(record_id, int) and record_id > 0 else None
         base_answers: list[JSONObject] = []
@@ -3851,6 +3935,7 @@ class RecordTools(ToolBase):
         location: str,
         explicit_fix_hint: str,
     ) -> None:
+        """执行内部辅助逻辑。"""
         raise RecordInputError(
             message=(
                 f"{kind} auto resolution for field '{field.que_title}' requires the current record context, "
@@ -3866,6 +3951,7 @@ class RecordTools(ToolBase):
         )
 
     def _normalize_backend_member_candidates(self, payload: JSONValue, *, external: bool) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         candidates: list[JSONObject] = []
         if not isinstance(payload, dict):
             return candidates
@@ -3882,6 +3968,7 @@ class RecordTools(ToolBase):
         return candidates
 
     def _normalize_backend_department_candidates(self, payload: JSONValue, *, external: bool) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         candidates: list[JSONObject] = []
         if not isinstance(payload, dict):
             return candidates
@@ -3900,6 +3987,7 @@ class RecordTools(ToolBase):
         return candidates
 
     def _department_candidate_path(self, value: JSONValue) -> str | None:
+        """执行内部辅助逻辑。"""
         if not isinstance(value, dict):
             return None
         name = _normalize_optional_text(value.get("deptName", value.get("value", value.get("name"))))
@@ -3915,6 +4003,7 @@ class RecordTools(ToolBase):
         return " / ".join(list(reversed(parent_names)) + [name])
 
     def _rank_member_candidates(self, keyword: str, candidates: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         requested = _normalize_field_lookup_key(keyword)
         ranked: list[JSONObject] = []
         for candidate in candidates:
@@ -3960,6 +4049,7 @@ class RecordTools(ToolBase):
         return ranked
 
     def _rank_department_candidates(self, keyword: str, candidates: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         requested = _normalize_field_lookup_key(keyword)
         ranked: list[JSONObject] = []
         for candidate in candidates:
@@ -4002,6 +4092,7 @@ class RecordTools(ToolBase):
         *,
         searchable_fields: list[JSONObject],
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         requested = _normalize_field_lookup_key(keyword)
         primary_titles = {
             _normalize_field_lookup_key(_stringify_json(item.get("title")))
@@ -4046,6 +4137,7 @@ class RecordTools(ToolBase):
         return ranked
 
     def _resolve_ranked_lookup_candidate(self, ranked_candidates: list[JSONObject]) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         if not ranked_candidates:
             return None
         top = ranked_candidates[0]
@@ -4066,6 +4158,7 @@ class RecordTools(ToolBase):
         method: str,
         confidence: float,
     ) -> None:
+        """执行内部辅助逻辑。"""
         if state is None:
             return
         state.resolved_fields.append(
@@ -4089,6 +4182,7 @@ class RecordTools(ToolBase):
         parent_field: FormField | None = None,
         row_ordinal: int | None = None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         payload: JSONObject = {
             "field": field.que_title,
             "kind": kind,
@@ -4112,6 +4206,7 @@ class RecordTools(ToolBase):
         parent_field: FormField | None = None,
         row_ordinal: int | None = None,
     ) -> None:
+        """执行内部辅助逻辑。"""
         if state is None:
             return
         state.confirmation_requests.append(request)
@@ -4120,6 +4215,7 @@ class RecordTools(ToolBase):
             state.unresolved_subtable_cells.add((parent_field.que_id, row_ordinal, field.que_id))
 
     def _candidate_resolution_method(self, candidate: JSONObject, *, explicit_method: str | None = None) -> str:
+        """执行内部辅助逻辑。"""
         if explicit_method:
             return explicit_method
         reason = _normalize_optional_text(candidate.get("match_reason")) or "resolved"
@@ -4140,6 +4236,7 @@ class RecordTools(ToolBase):
         state: LookupResolutionState | None,
         explicit_guidance: str,
     ) -> str:
+        """执行内部辅助逻辑。"""
         if state is not None and self._candidate_lookup_uses_runtime_scope(
             record_id=state.apply_id,
             workflow_node_id=state.workflow_node_id,
@@ -4156,6 +4253,7 @@ class RecordTools(ToolBase):
         )
 
     def _resolve_member_candidates(self, context, field: FormField, *, keyword: str) -> list[JSONObject]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         scope_type = field.member_select_scope_type
         scope = field.member_select_scope if isinstance(field.member_select_scope, dict) else {}
         if _scope_is_default_all(scope_type, scope, keys=("member", "depart", "role")):
@@ -4239,6 +4337,7 @@ class RecordTools(ToolBase):
         return filtered
 
     def _resolve_department_candidates(self, context, field: FormField, *, keyword: str) -> list[JSONObject]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         scope_type = field.dept_select_scope_type
         scope = field.dept_select_scope if isinstance(field.dept_select_scope, dict) else {}
         if _scope_has_dynamic_or_external(scope):
@@ -4302,6 +4401,7 @@ class RecordTools(ToolBase):
         return filtered
 
     def _merge_member_candidate(self, merged: dict[str, JSONObject], candidate: JSONObject) -> None:
+        """执行内部辅助逻辑。"""
         key = _member_candidate_key(candidate)
         if not key:
             return
@@ -4335,6 +4435,7 @@ class RecordTools(ToolBase):
         dept_id: int,
         include_sub_departments: bool,
     ) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         dept_ids = {dept_id}
         if include_sub_departments:
             dept_ids.update(self._expand_department_ids(context, root_dept_id=dept_id))
@@ -4347,6 +4448,7 @@ class RecordTools(ToolBase):
         return list(merged.values())
 
     def _list_members_by_role(self, context, *, role_id: int) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         return self._fetch_internal_members(context, department_id=None, role_id=role_id)
 
     def _list_departments_by_scope(
@@ -4356,6 +4458,7 @@ class RecordTools(ToolBase):
         dept_id: int,
         include_sub_departments: bool,
     ) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         dept_ids = {dept_id}
         if include_sub_departments:
             dept_ids.update(self._expand_department_ids(context, root_dept_id=dept_id))
@@ -4369,6 +4472,7 @@ class RecordTools(ToolBase):
         return list(merged.values())
 
     def _list_all_departments(self, context) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         queue: list[int | None] = [None]
         seen_ids: set[int] = set()
         requested_parents: set[int | None] = set()
@@ -4401,6 +4505,7 @@ class RecordTools(ToolBase):
         return items
 
     def _merge_department_candidate(self, merged: dict[str, JSONObject], candidate: JSONObject) -> None:
+        """执行内部辅助逻辑。"""
         key = _department_candidate_key(candidate)
         if not key:
             return
@@ -4424,6 +4529,7 @@ class RecordTools(ToolBase):
                 seen.add(marker)
 
     def _expand_department_ids(self, context, *, root_dept_id: int) -> set[int]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         seen: set[int] = set()
         queue: list[int] = [root_dept_id]
         while queue:
@@ -4448,6 +4554,7 @@ class RecordTools(ToolBase):
         department_id: int | None,
         role_id: int | None,
     ) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         current_page = 1
         fetched_pages = 0
         seen: dict[str, dict[str, Any]] = {}
@@ -4483,9 +4590,11 @@ class RecordTools(ToolBase):
         return list(seen.values())
 
     def _search_workspace_members(self, context, *, keyword: str) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         return self._search_workspace_directory_dimension(context, dimension="MEMBER", bucket_key="member", keyword=keyword)
 
     def _search_workspace_departments(self, context, *, keyword: str) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         return self._search_workspace_directory_dimension(context, dimension="DEPT", bucket_key="dept", keyword=keyword)
 
     def _search_workspace_directory_dimension(
@@ -4496,6 +4605,7 @@ class RecordTools(ToolBase):
         bucket_key: str,
         keyword: str,
     ) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         current_page = 1
         fetched_pages = 0
         seen: dict[str, dict[str, Any]] = {}
@@ -4533,6 +4643,7 @@ class RecordTools(ToolBase):
         return list(seen.values())
 
     def _schema_field_family(self, field: FormField) -> str:
+        """执行内部辅助逻辑。"""
         if self._schema_is_identifier_like(field):
             return "text"
         que_type = field.que_type
@@ -4555,6 +4666,7 @@ class RecordTools(ToolBase):
         return "text"
 
     def _schema_is_identifier_like(self, field: FormField, *, field_family: str | None = None) -> bool:
+        """执行内部辅助逻辑。"""
         normalized_title = _normalize_field_lookup_key(field.que_title)
         if field.que_id == 0:
             return True
@@ -4565,6 +4677,7 @@ class RecordTools(ToolBase):
         return False
 
     def _schema_supported_metric_ops(self, field: FormField, *, field_family: str) -> list[str]:
+        """执行内部辅助逻辑。"""
         if field.que_type in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES:
             return []
         if self._schema_is_identifier_like(field, field_family=field_family):
@@ -4576,6 +4689,7 @@ class RecordTools(ToolBase):
         return []
 
     def _schema_semantic_hint(self, field: FormField, *, field_family: str) -> str:
+        """执行内部辅助逻辑。"""
         if self._schema_is_identifier_like(field, field_family=field_family):
             return "unknown"
         if field_family != "number":
@@ -4590,6 +4704,7 @@ class RecordTools(ToolBase):
         return "unknown"
 
     def _resolve_field_by_id(self, field_id: int | None, index: FieldIndex, *, location: str) -> FormField:
+        """执行内部辅助逻辑。"""
         if field_id is None:
             raise RecordInputError(
                 message=f"{location} requires field_id",
@@ -4614,6 +4729,7 @@ class RecordTools(ToolBase):
         allowed_keys: set[str],
         example: str,
     ) -> None:
+        """执行内部辅助逻辑。"""
         unexpected_keys = sorted(str(key) for key in item.keys() if str(key) not in allowed_keys)
         if unexpected_keys:
             raise RecordInputError(
@@ -4635,6 +4751,7 @@ class RecordTools(ToolBase):
         value: JSONValue,
         location: str,
     ) -> JSONValue:
+        """执行内部辅助逻辑。"""
         if op in {"is_null", "not_null"}:
             if value is not None:
                 raise RecordInputError(
@@ -4765,6 +4882,7 @@ class RecordTools(ToolBase):
         return value
 
     def _validate_strict_date_filter_value(self, value: JSONValue, *, location: str) -> datetime:
+        """执行内部辅助逻辑。"""
         text = _normalize_optional_text(value)
         if text is None:
             raise RecordInputError(
@@ -4784,6 +4902,7 @@ class RecordTools(ToolBase):
         return parsed
 
     def _compile_analyze_dimensions(self, index: FieldIndex, dimensions: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         supported_buckets = {None, "day", "week", "month", "quarter", "year"}
         compiled: list[JSONObject] = []
         used_aliases: set[str] = set()
@@ -4828,6 +4947,7 @@ class RecordTools(ToolBase):
         return compiled
 
     def _compile_analyze_metrics(self, index: FieldIndex, metrics: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         requested_metrics = metrics or [{"op": "count", "alias": "记录数"}]
         supported_ops = {"count", "sum", "avg", "min", "max", "distinct_count"}
         compiled: list[JSONObject] = []
@@ -4891,6 +5011,7 @@ class RecordTools(ToolBase):
         return compiled
 
     def _compile_analyze_filters(self, index: FieldIndex, filters: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         supported_ops = {"eq", "neq", "in", "not_in", "gt", "gte", "lt", "lte", "between", "contains", "is_null", "not_null"}
         compiled: list[JSONObject] = []
         for idx, item in enumerate(filters):
@@ -4925,6 +5046,7 @@ class RecordTools(ToolBase):
         return compiled
 
     def _compile_analyze_sort(self, sort: list[JSONObject], dimensions: list[JSONObject], metrics: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         dimension_aliases = {str(item["alias"]) for item in dimensions}
         metric_aliases = {str(item["alias"]) for item in metrics}
         compiled: list[JSONObject] = []
@@ -4986,6 +5108,7 @@ class RecordTools(ToolBase):
         output_profile: str,
         extra_warnings: list[JSONObject] | None = None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         started_at = time.perf_counter()
         analysis_paging = _fixed_analysis_scan_policy()
         page_size = int(analysis_paging["page_size"])
@@ -5207,6 +5330,7 @@ class RecordTools(ToolBase):
         return response
 
     def _build_analyze_group_payload(self, answer_list: list[JSONValue], dimensions: list[JSONObject]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if not dimensions:
             return {}
         payload: JSONObject = {}
@@ -5221,6 +5345,7 @@ class RecordTools(ToolBase):
         return payload
 
     def _initialize_metric_states(self, metrics: list[JSONObject]) -> dict[str, JSONObject]:
+        """执行内部辅助逻辑。"""
         states: dict[str, JSONObject] = {}
         for item in metrics:
             states[str(item["alias"])] = {
@@ -5233,9 +5358,11 @@ class RecordTools(ToolBase):
         return states
 
     def _analysis_group_key(self, payload: JSONObject) -> tuple[tuple[str, object], ...]:
+        """执行内部辅助逻辑。"""
         return tuple((key, self._freeze_group_key_value(value)) for key, value in payload.items())
 
     def _freeze_group_key_value(self, value: JSONValue) -> object:
+        """执行内部辅助逻辑。"""
         if isinstance(value, dict):
             return tuple((key, self._freeze_group_key_value(item)) for key, item in sorted(value.items()))
         if isinstance(value, list):
@@ -5243,6 +5370,7 @@ class RecordTools(ToolBase):
         return value
 
     def _apply_metric_states(self, states: dict[str, JSONObject], metrics: list[JSONObject], answer_list: list[JSONValue]) -> None:
+        """执行内部辅助逻辑。"""
         for item in metrics:
             alias = cast(str, item["alias"])
             op = cast(str, item["op"])
@@ -5265,6 +5393,7 @@ class RecordTools(ToolBase):
             state["max"] = amount if state["max"] is None else max(float(state["max"]), amount)
 
     def _render_metric_values(self, states: dict[str, JSONObject], metrics: list[JSONObject]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         rendered: JSONObject = {}
         for item in metrics:
             alias = cast(str, item["alias"])
@@ -5287,6 +5416,7 @@ class RecordTools(ToolBase):
         return rendered
 
     def _matches_analyze_filters(self, answer_list: list[JSONValue], filters: list[JSONObject]) -> bool:
+        """执行内部辅助逻辑。"""
         for item in filters:
             field = cast(FormField, item["field"])
             if not _match_analyze_filter(_extract_field_value(answer_list, field), cast(str, item["op"]), item.get("value")):
@@ -5300,6 +5430,7 @@ class RecordTools(ToolBase):
         dimensions: list[JSONObject],
         metrics: list[JSONObject],
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if not rows or not sort:
             if dimensions and any(item.get("bucket") for item in dimensions):
                 return sorted(rows, key=lambda item: json.dumps(item.get("dimensions", {}), ensure_ascii=False, sort_keys=True))
@@ -5324,6 +5455,7 @@ class RecordTools(ToolBase):
         rows_truncated: bool,
         extra_warnings: list[JSONObject],
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         warnings: list[JSONObject] = []
         warnings.extend(extra_warnings)
         if local_filtering:
@@ -5347,6 +5479,7 @@ class RecordTools(ToolBase):
         view_key: str | None,
         view_name: str | None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
@@ -5410,6 +5543,7 @@ class RecordTools(ToolBase):
         existing_answers_override: list[JSONObject] | None = None,
         field_index_override: FieldIndex | None = None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         schema = self._get_form_schema(profile, context, app_key, force_refresh=force_refresh_form)
         base_index = field_index_override or _build_applicant_top_level_field_index(schema)
         question_relations = _collect_question_relations(schema)
@@ -5727,6 +5861,7 @@ class RecordTools(ToolBase):
         app_key: str,
         apply_id: int,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         record = self.backend.request(
             "GET",
             context,
@@ -5744,6 +5879,7 @@ class RecordTools(ToolBase):
         selector_index: FieldIndex,
         visible_question_ids: set[int],
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         invalid_fields: list[JSONObject] = []
         if not visible_question_ids:
             return invalid_fields
@@ -5787,6 +5923,7 @@ class RecordTools(ToolBase):
         full_index: FieldIndex,
         skip_cells: set[tuple[int, int, int]] | None = None,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         missing_required_fields: list[JSONObject] = []
         skipped = skip_cells or set()
         answers_by_field_id = {
@@ -5884,6 +6021,7 @@ class RecordTools(ToolBase):
         existing_answers: list[JSONObject],
         patch_answers: list[JSONObject],
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         merged_by_id: dict[int, JSONObject] = {}
         order: list[int] = []
         for source in (existing_answers, patch_answers):
@@ -5896,6 +6034,7 @@ class RecordTools(ToolBase):
                 merged_by_id[que_id] = item
         return [merged_by_id[que_id] for que_id in order]
 
+    @tool_cn_name("查询记录")
     def record_query(
         self,
         *,
@@ -5923,6 +6062,7 @@ class RecordTools(ToolBase):
         view_key: str | None = None,
         view_name: str | None = None,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         resolved_mode = _resolve_query_mode(query_mode, apply_id=apply_id, amount_column=amount_column, time_range=time_range, stat_policy=stat_policy)
         if resolved_mode == "summary":
             raise_tool_error(
@@ -5972,6 +6112,7 @@ class RecordTools(ToolBase):
             view_name=view_name,
         )
 
+    @tool_cn_name("创建记录")
     def record_create(
         self,
         *,
@@ -5983,6 +6124,7 @@ class RecordTools(ToolBase):
         verify_write: bool = False,
         force_refresh_form: bool = False,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if submit_type not in (0, 1):
             raise_tool_error(QingflowApiError.config_error("submit_type must be 0 or 1"))
 
@@ -6030,6 +6172,7 @@ class RecordTools(ToolBase):
     # listType 降级顺序（内部 record_get）
     _INTERNAL_GET_LIST_TYPE_FALLBACKS = [DEFAULT_RECORD_LIST_TYPE, 14, 1, 2, 12]
 
+    @tool_cn_name("获取记录")
     def record_get(
         self,
         *,
@@ -6040,6 +6183,7 @@ class RecordTools(ToolBase):
         list_type: int | None,
         audit_node_id: int | None,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_apply_id = self._validate_app_and_record(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -6088,6 +6232,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("搜索记录")
     def record_search(
         self,
         *,
@@ -6103,6 +6248,7 @@ class RecordTools(ToolBase):
         view_key: str | None = None,
         view_name: str | None = None,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
@@ -6165,6 +6311,7 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("修改记录")
     def record_update(
         self,
         *,
@@ -6177,6 +6324,7 @@ class RecordTools(ToolBase):
         verify_write: bool = False,
         force_refresh_form: bool = False,
     ) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_apply_id = self._validate_app_and_record(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -6227,7 +6375,9 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    @tool_cn_name("删除记录（兼容）")
     def record_delete(self, *, profile: str, app_key: str, apply_id: int, list_type: int) -> JSONObject:
+        """执行记录相关逻辑。"""
         normalized_apply_id = self._validate_app_and_record(app_key, apply_id)
 
         def runner(session_profile, context):
@@ -6263,6 +6413,7 @@ class RecordTools(ToolBase):
         output_profile: str,
         list_type: int,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if apply_id is None or apply_id <= 0:
@@ -6362,6 +6513,7 @@ class RecordTools(ToolBase):
         view_key: str | None = None,
         view_name: str | None = None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if not select_columns:
@@ -6624,6 +6776,7 @@ class RecordTools(ToolBase):
         return self._run_record_tool(profile, runner)
 
     def _get_form_schema(self, profile: str, context, app_key: str, *, force_refresh: bool) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         cache_key = (profile, app_key, "applicant_node", None)
         if not force_refresh and cache_key in self._form_cache:
             return self._form_cache[cache_key]
@@ -6638,6 +6791,7 @@ class RecordTools(ToolBase):
         return normalized
 
     def _get_field_index(self, profile: str, context, app_key: str, *, force_refresh: bool) -> FieldIndex:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         return _build_field_index(self._get_form_schema(profile, context, app_key, force_refresh=force_refresh))
 
     def _get_applicant_top_level_field_index(
@@ -6648,11 +6802,13 @@ class RecordTools(ToolBase):
         *,
         force_refresh: bool,
     ) -> FieldIndex:
+        """执行内部辅助逻辑。"""
         return _build_applicant_top_level_field_index(
             self._get_form_schema(profile, context, app_key, force_refresh=force_refresh)
         )
 
     def _resolve_applicant_node(self, profile: str, context, app_key: str, *, force_refresh: bool) -> WorkflowNodeRef:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         cache_key = (profile, app_key)
         if not force_refresh and cache_key in self._applicant_node_cache:
             return self._applicant_node_cache[cache_key]
@@ -6673,6 +6829,7 @@ class RecordTools(ToolBase):
         return applicant_node
 
     def _get_view_list(self, profile: str, context, app_key: str) -> list[JSONObject]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         cache_key = (profile, app_key)
         if cache_key in self._view_list_cache:
             return self._view_list_cache[cache_key]
@@ -6682,6 +6839,7 @@ class RecordTools(ToolBase):
         return normalized
 
     def _get_view_form_schema(self, profile: str, context, view_key: str, *, force_refresh: bool) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         cache_key = (profile, f"view:{view_key}", "browse_view", None)
         if not force_refresh and cache_key in self._form_cache:
             return self._form_cache[cache_key]
@@ -6698,6 +6856,7 @@ class RecordTools(ToolBase):
         *,
         force_refresh: bool = False,
     ) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         cache_key = (profile, view_key)
         if not force_refresh and cache_key in self._view_config_cache:
             return self._view_config_cache[cache_key]
@@ -6730,6 +6889,7 @@ class RecordTools(ToolBase):
         resolved_view: AccessibleViewRoute | None = None,
         clear_view_caches: bool = False,
     ) -> None:
+        """执行内部辅助逻辑。"""
         view_key = (
             resolved_view.view_selection.view_key
             if resolved_view is not None and resolved_view.view_selection is not None
@@ -6756,10 +6916,12 @@ class RecordTools(ToolBase):
                 self._view_config_cache.pop(cache_key, None)
 
     def _record_preflight_used_force_refresh(self, raw_preflight: JSONObject) -> bool:
+        """执行内部辅助逻辑。"""
         data = raw_preflight.get("data")
         return bool(isinstance(data, dict) and data.get("schema_force_refreshed"))
 
     def _record_preflight_suggests_stale_schema(self, plan_data: JSONObject) -> bool:
+        """执行内部辅助逻辑。"""
         validation = plan_data.get("validation")
         invalid_fields = validation.get("invalid_fields") if isinstance(validation, dict) else None
         if not isinstance(invalid_fields, list):
@@ -6767,6 +6929,7 @@ class RecordTools(ToolBase):
         return any(self._field_error_suggests_stale_schema(entry) for entry in invalid_fields if isinstance(entry, dict))
 
     def _field_error_suggests_stale_schema(self, entry: JSONObject) -> bool:
+        """执行内部辅助逻辑。"""
         error_code = _normalize_optional_text(entry.get("error_code"))
         if error_code == "VIEW_SCOPE_FIELD_HIDDEN":
             return False
@@ -6786,6 +6949,7 @@ class RecordTools(ToolBase):
         record: JSONObject,
         normalized_record: JSONObject,
     ) -> bool:
+        """执行内部辅助逻辑。"""
         for field in selected_fields:
             if field.que_type not in SUBTABLE_QUE_TYPES:
                 continue
@@ -6809,6 +6973,7 @@ class RecordTools(ToolBase):
         list_type: int,
         force_refresh: bool,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         cache_key = (profile, app_key, "browse_system", list_type)
         if not force_refresh and cache_key in self._form_cache:
             return self._form_cache[cache_key]
@@ -6825,6 +6990,7 @@ class RecordTools(ToolBase):
         return normalized
 
     def _get_view_field_index(self, profile: str, context, view_key: str, *, force_refresh: bool) -> FieldIndex:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         return _build_field_index(self._get_view_form_schema(profile, context, view_key, force_refresh=force_refresh))
 
     def _get_system_browse_field_index(
@@ -6836,6 +7002,7 @@ class RecordTools(ToolBase):
         list_type: int,
         force_refresh: bool,
     ) -> FieldIndex:
+        """执行内部辅助逻辑。"""
         return _build_field_index(
             self._get_system_browse_schema(
                 profile,
@@ -6855,6 +7022,7 @@ class RecordTools(ToolBase):
         *,
         force_refresh: bool,
     ) -> FieldIndex:
+        """执行内部辅助逻辑。"""
         return self._build_browse_write_scope(
             profile,
             context,
@@ -6872,6 +7040,7 @@ class RecordTools(ToolBase):
         *,
         force_refresh: bool,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         applicant_index: FieldIndex | None
         applicant_writable_field_ids: set[int]
         try:
@@ -6969,6 +7138,7 @@ class RecordTools(ToolBase):
         app_key: str,
         resolved_view: AccessibleViewRoute,
     ) -> list[int]:
+        """执行内部辅助逻辑。"""
         def runner(_session_profile, context):
             return self._derive_public_list_columns(profile, context, app_key, resolved_view)
 
@@ -6981,6 +7151,7 @@ class RecordTools(ToolBase):
         app_key: str,
         resolved_view: AccessibleViewRoute,
     ) -> list[int]:
+        """执行内部辅助逻辑。"""
         browse_scope = self._build_browse_write_scope(
             profile,
             context,
@@ -7018,6 +7189,7 @@ class RecordTools(ToolBase):
         return field_ids
 
     def _get_view_question_ids(self, profile: str, context, view_key: str) -> set[int]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         try:
             payload = self.backend.request("GET", context, f"/view/{view_key}/question")
         except QingflowApiError as exc:
@@ -7045,6 +7217,7 @@ class RecordTools(ToolBase):
         schema_mode: str,
         resolved_view: AccessibleViewRoute | None,
     ) -> list[FormField]:
+        """执行内部辅助逻辑。"""
         return list(index.by_id.values())
 
     def _probe_list_type_access(
@@ -7054,6 +7227,7 @@ class RecordTools(ToolBase):
         app_key: str,
         list_type: int,
     ) -> bool:
+        """执行内部辅助逻辑。"""
         try:
             self.backend.request(
                 "POST",
@@ -7078,6 +7252,7 @@ class RecordTools(ToolBase):
         view_name: str | None,
         allow_default: bool,
     ) -> tuple[AccessibleViewRoute, list[JSONObject]]:
+        """执行内部辅助逻辑。"""
         def runner(_session_profile, context):
             return self._resolve_accessible_view_route(
                 profile,
@@ -7104,6 +7279,7 @@ class RecordTools(ToolBase):
         view_name: str | None,
         allow_default: bool,
     ) -> tuple[AccessibleViewRoute, list[JSONObject]]:
+        """执行内部辅助逻辑。"""
         warnings: list[JSONObject] = []
         normalized_view_id = _normalize_optional_text(view_id)
         if normalized_view_id:
@@ -7209,6 +7385,7 @@ class RecordTools(ToolBase):
         view_key: str | None,
         view_name: str | None,
     ) -> ViewSelection | None:
+        """执行内部辅助逻辑。"""
         requested_key = _normalize_optional_text(view_key)
         requested_name = _normalize_optional_text(view_name)
         if requested_key is None and requested_name is None:
@@ -7253,6 +7430,7 @@ class RecordTools(ToolBase):
         )
 
     def _get_department_member_ids(self, context, dept_id: int) -> set[int]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         page_num = 1
         page_size = 200
         member_ids: set[int] = set()
@@ -7288,6 +7466,7 @@ class RecordTools(ToolBase):
         view_selection: ViewSelection | None,
         dept_member_cache: dict[int, set[int]],
     ) -> bool:
+        """执行内部辅助逻辑。"""
         if view_selection is None or not view_selection.conditions:
             return True
         for group in view_selection.conditions:
@@ -7312,6 +7491,7 @@ class RecordTools(ToolBase):
         arguments: JSONObject,
         view_selection: ViewSelection | None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         routed_mode = _resolve_query_mode(
             str(arguments.get("query_mode", "auto")),
             apply_id=_coerce_count(arguments.get("apply_id")),
@@ -7376,6 +7556,7 @@ class RecordTools(ToolBase):
         search_que_ids: list[int] | None,
         list_type: int,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if view_selection is not None and _is_board_view_type(view_selection.view_type):
             return self._search_board_view_page(
                 context,
@@ -7406,6 +7587,7 @@ class RecordTools(ToolBase):
         return result if isinstance(result, dict) else {}
 
     def _should_retry_list_type_fallback(self, error: QingflowApiError) -> bool:
+        """执行内部辅助逻辑。"""
         if error.backend_code in {40002, 40027, 404}:
             return True
         if error.http_status in {404, 500}:
@@ -7424,6 +7606,7 @@ class RecordTools(ToolBase):
         list_type: int,
         include_list_type: bool,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         body: JSONObject = {"pageNum": page_num, "pageSize": page_size}
         if include_list_type:
             body["type"] = list_type
@@ -7453,6 +7636,7 @@ class RecordTools(ToolBase):
         return body
 
     def _get_board_lane_ids(self, context, *, view_key: str) -> list[int]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         payload = self.backend.request(
             "GET",
             context,
@@ -7485,6 +7669,7 @@ class RecordTools(ToolBase):
         offset: int,
         limit: int,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if limit <= 0:
             return []
         request_page_size = max(_coerce_count(filter_payload.get("pageSize")) or 1, 1)
@@ -7532,6 +7717,7 @@ class RecordTools(ToolBase):
         sorts: list[JSONObject],
         search_que_ids: list[int] | None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         filter_payload = self._build_view_filter_payload(
             page_num=page_num,
             page_size=page_size,
@@ -7628,6 +7814,7 @@ class RecordTools(ToolBase):
         resolution_state: LookupResolutionState | None = None,
         field_index_override: FieldIndex | None = None,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if not answers and not fields:
@@ -7674,6 +7861,7 @@ class RecordTools(ToolBase):
         *,
         resolution_state: LookupResolutionState | None = None,
     ) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         field = self._resolve_field_from_answer_item(item, index)
         if field.que_type in SUBTABLE_QUE_TYPES:
             table_values_input: JSONValue = item.get("tableValues")
@@ -7747,6 +7935,7 @@ class RecordTools(ToolBase):
         *,
         resolution_state: LookupResolutionState | None = None,
     ) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         field = self._resolve_field_selector(field_selector, index, location="fields")
         if field.que_type in SUBTABLE_QUE_TYPES:
             return {
@@ -7802,6 +7991,7 @@ class RecordTools(ToolBase):
         parent_field: FormField | None = None,
         row_ordinal: int | None = None,
     ) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         values: list[JSONObject] = []
         refer_values: list[JSONObject] = []
         for raw_value in _expand_values(raw_values):
@@ -7830,6 +8020,7 @@ class RecordTools(ToolBase):
         }
 
     def _raise_if_verify_unsupported_write_field(self, field: FormField, raw_value: JSONValue, *, location: str) -> None:
+        """执行内部辅助逻辑。"""
         if field.que_type not in VERIFY_UNSUPPORTED_WRITE_QUE_TYPES:
             return
         raise RecordInputError(
@@ -7854,6 +8045,7 @@ class RecordTools(ToolBase):
         resolution_state: LookupResolutionState | None = None,
         location: str = "field",
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if field.que_type in SINGLE_SELECT_QUE_TYPES:
             return [_option_value(raw_values[0], field)]
         if field.que_type in MULTI_SELECT_QUE_TYPES:
@@ -7906,6 +8098,7 @@ class RecordTools(ToolBase):
         location: str,
         resolution_state: LookupResolutionState | None = None,
     ) -> list[list[JSONObject]]:
+        """执行内部辅助逻辑。"""
         row_values = raw_rows
         if isinstance(raw_rows, dict):
             if "rows" in raw_rows:
@@ -7950,6 +8143,7 @@ class RecordTools(ToolBase):
         location: str,
         resolution_state: LookupResolutionState | None = None,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         row_id: int | None = None
         normalized_cells: list[JSONObject] = []
         if isinstance(row, dict):
@@ -8068,6 +8262,7 @@ class RecordTools(ToolBase):
         parent_field: FormField | None = None,
         row_ordinal: int | None = None,
     ) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         field = self._resolve_field_from_answer_item(item, subtable_index)
         if field.que_type in SUBTABLE_QUE_TYPES:
             raise RecordInputError(
@@ -8132,6 +8327,7 @@ class RecordTools(ToolBase):
         parent_field: FormField | None = None,
         row_ordinal: int | None = None,
     ) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         field = self._resolve_field_selector(field_selector, subtable_index, location=location)
         if field.que_type in SUBTABLE_QUE_TYPES:
             raise RecordInputError(
@@ -8171,6 +8367,7 @@ class RecordTools(ToolBase):
         }
 
     def _subtable_field_index(self, table_field: FormField) -> FieldIndex:
+        """执行内部辅助逻辑。"""
         raw = table_field.raw if isinstance(table_field.raw, dict) else {}
         schema: JSONObject = {}
         if isinstance(raw.get("subQuestions"), list):
@@ -8188,6 +8385,7 @@ class RecordTools(ToolBase):
         return index
 
     def _subtable_field_index_optional(self, table_field: FormField | None) -> FieldIndex | None:
+        """执行内部辅助逻辑。"""
         if table_field is None:
             return None
         try:
@@ -8196,6 +8394,7 @@ class RecordTools(ToolBase):
             return None
 
     def _run_record_tool(self, profile: str, func, *, require_workspace: bool = True):  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         try:
             return self._run(profile, func, require_workspace=require_workspace)
         except RecordInputError as error:
@@ -8213,6 +8412,7 @@ class RecordTools(ToolBase):
             )
 
     def _request_route_payload(self, context) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         describe_route = getattr(self.backend, "describe_route", None)
         if callable(describe_route):
             payload = describe_route(context)
@@ -8225,6 +8425,7 @@ class RecordTools(ToolBase):
         }
 
     def _normalize_public_output_profile(self, output_profile: str, *, allow_normalized: bool = False) -> str:
+        """执行内部辅助逻辑。"""
         normalized = (output_profile or "normal").strip().lower()
         allowed = {"normal", "verbose"}
         if allow_normalized:
@@ -8235,6 +8436,7 @@ class RecordTools(ToolBase):
         return normalized
 
     def _normalize_record_list_where(self, where: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         normalized: list[JSONObject] = []
         for idx, item in enumerate(where):
             if not isinstance(item, dict):
@@ -8260,6 +8462,7 @@ class RecordTools(ToolBase):
         return normalized
 
     def _normalize_record_list_order_by(self, order_by: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         normalized: list[JSONObject] = []
         for idx, item in enumerate(order_by):
             if not isinstance(item, dict):
@@ -8280,6 +8483,7 @@ class RecordTools(ToolBase):
         return normalized
 
     def _normalize_record_write_submit_type(self, submit_type: str | int) -> int:
+        """执行内部辅助逻辑。"""
         if isinstance(submit_type, int):
             if submit_type in {0, 1}:
                 return submit_type
@@ -8292,6 +8496,7 @@ class RecordTools(ToolBase):
         raise_tool_error(QingflowApiError.config_error("submit_type must be save or submit"))
 
     def _normalize_record_write_clauses(self, clauses: list[JSONObject], *, location: str) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         normalized: list[JSONObject] = []
         for idx, item in enumerate(clauses):
             if not isinstance(item, dict):
@@ -8319,6 +8524,7 @@ class RecordTools(ToolBase):
         submit_type: int,
         selection: JSONObject | None = None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         payload: JSONObject = {
             "operation": operation,
             "record_id": record_id,
@@ -8337,6 +8543,7 @@ class RecordTools(ToolBase):
         fields: JSONObject,
         selector_index: FieldIndex,
     ) -> tuple[list[JSONObject], JSONObject]:
+        """执行内部辅助逻辑。"""
         canonical_answers: list[JSONObject] = []
         for item in answers:
             if not isinstance(item, dict):
@@ -8358,6 +8565,7 @@ class RecordTools(ToolBase):
         return canonical_answers, canonical_fields
 
     def _record_write_human_review_payload(self, operation: str, *, enabled: bool) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         if not enabled:
             return None
         return {
@@ -8375,6 +8583,7 @@ class RecordTools(ToolBase):
         record_id: int | None,
         selection: JSONObject | None,
     ) -> None:
+        """执行内部辅助逻辑。"""
         if exc.backend_code != 40002:
             raise exc
         raise_tool_error(
@@ -8409,6 +8618,7 @@ class RecordTools(ToolBase):
         human_review: bool,
         target_resource: JSONObject,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         plan_data = cast(JSONObject, raw_preflight.get("data", {}))
         validation = cast(JSONObject, plan_data.get("validation", {}))
         field_errors = self._record_write_public_field_errors(plan_data)
@@ -8454,6 +8664,7 @@ class RecordTools(ToolBase):
         human_review: bool,
         target_resource: JSONObject,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         plan_data = cast(JSONObject, raw_preflight.get("data", {}))
         validation = cast(JSONObject, plan_data.get("validation", {}))
         resolved_fields = cast(list[JSONObject], plan_data.get("lookup_resolved_fields", []))
@@ -8496,6 +8707,7 @@ class RecordTools(ToolBase):
         human_review: bool,
         preflight: JSONObject | None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         preflight_data = cast(JSONObject, preflight.get("data", {})) if isinstance(preflight, dict) else {}
         validation = cast(JSONObject, preflight_data.get("validation", {}))
         warnings_payload = validation.get("warnings", [])
@@ -8547,6 +8759,7 @@ class RecordTools(ToolBase):
         output_profile: str,
         human_review: bool,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         error_payload: JSONObject = {
             "error_code": "RECORD_WRITE_EXECUTION_FAILED",
             "message": str(exc),
@@ -8598,6 +8811,7 @@ class RecordTools(ToolBase):
         return response
 
     def _record_write_public_field_errors(self, plan_data: JSONObject) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         existing = plan_data.get("field_errors")
         if isinstance(existing, list):
             return [cast(JSONObject, item) for item in existing if isinstance(item, dict)]
@@ -8618,6 +8832,7 @@ class RecordTools(ToolBase):
         missing_required_fields: list[JSONObject],
         readonly_or_system_fields: list[JSONObject],
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         errors: list[JSONObject] = []
         for item in invalid_fields:
             payload: JSONObject = {
@@ -8686,6 +8901,7 @@ class RecordTools(ToolBase):
         return errors
 
     def _record_delete_many(self, *, profile: str, app_key: str, record_ids: list[int]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         normalized_ids = [item for item in record_ids if isinstance(item, int) and item > 0]
@@ -8711,6 +8927,7 @@ class RecordTools(ToolBase):
         return self._run_record_tool(profile, runner)
 
     def _resolve_field_selector(self, selector: str | int | None, index: FieldIndex, *, location: str) -> FormField:
+        """执行内部辅助逻辑。"""
         if selector is None:
             raise RecordInputError(
                 message=f"{location} requires a field selector",
@@ -8796,6 +9013,7 @@ class RecordTools(ToolBase):
         matches: list[SubtableLeafRef],
         matched_via: str,
     ) -> RecordInputError:
+        """执行内部辅助逻辑。"""
         if len(matches) > 1:
             return RecordInputError(
                 message=f"{location} field '{requested}' matches subtable leaf fields under multiple parent tables",
@@ -8840,6 +9058,7 @@ class RecordTools(ToolBase):
         )
 
     def _resolve_field_from_answer_item(self, item: JSONObject, index: FieldIndex) -> FormField:
+        """执行内部辅助逻辑。"""
         for key in ("queId", "que_id", "queTitle", "que_title", "field_id", "fieldId"):
             if key in item:
                 return self._resolve_field_selector(cast(str | int, item[key]), index, location="answers")
@@ -8857,6 +9076,7 @@ class RecordTools(ToolBase):
         max_columns: int | None,
         default_limit: int,
     ) -> list[FormField]:
+        """执行内部辅助逻辑。"""
         if not selectors:
             raise_tool_error(QingflowApiError.config_error("select_columns is required"))
         limit = _bounded_column_limit(max_columns, default_limit=default_limit, hard_limit=default_limit)
@@ -8881,6 +9101,7 @@ class RecordTools(ToolBase):
         *,
         max_columns: int | None,
     ) -> list[FormField]:
+        """执行内部辅助逻辑。"""
         if selectors:
             return self._resolve_select_columns(
                 selectors,
@@ -8904,6 +9125,7 @@ class RecordTools(ToolBase):
         return candidates[:limit]
 
     def _resolve_match_rules(self, context, filters: list[JSONObject], index: FieldIndex) -> list[JSONObject]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         rules: list[JSONObject] = []
         for item in filters:
             if not isinstance(item, dict):
@@ -8972,6 +9194,7 @@ class RecordTools(ToolBase):
         return rules
 
     def _build_department_filter_rule(self, context, field: FormField, item: JSONObject) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         raw_value: JSONValue | None = None
         for key in ("search_options", "searchOptions", "search_keys", "searchKeys", "search_key", "searchKey", "value", "values"):
             if key in item:
@@ -8986,6 +9209,7 @@ class RecordTools(ToolBase):
         return _department_filter_rule(field.que_id, field.que_type, details, judge_type=judge_type)
 
     def _resolve_department_filter_details(self, context, raw_value: JSONValue) -> list[JSONObject]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         values = raw_value if isinstance(raw_value, list) else [raw_value]
         details: list[JSONObject] = []
         seen: set[int] = set()
@@ -8999,6 +9223,7 @@ class RecordTools(ToolBase):
         return details
 
     def _resolve_department_filter_detail(self, context, raw_value: JSONValue) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         if isinstance(raw_value, dict):
             dept_id = _coerce_count(raw_value.get("id", raw_value.get("deptId")))
             if dept_id is not None:
@@ -9029,9 +9254,11 @@ class RecordTools(ToolBase):
         return self._lookup_department_filter_detail(context, keyword)
 
     def _lookup_department_filter_detail(self, context, keyword: str) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         return self._lookup_department_detail(context, keyword, purpose="filter")
 
     def _candidate_lookup_sample(self, candidates: list[JSONObject], *, kind: str) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         sample: list[JSONObject] = []
         for item in candidates[:10]:
             if kind == "relation":
@@ -9066,6 +9293,7 @@ class RecordTools(ToolBase):
         value: JSONValue,
         error: QingflowApiError,
     ) -> None:
+        """执行内部辅助逻辑。"""
         field_kind = "member" if kind == "member" else "department"
         raise RecordInputError(
             message=f"{field_kind} candidates for field '{field.que_title}' could not be loaded",
@@ -9088,6 +9316,7 @@ class RecordTools(ToolBase):
         text_keys: tuple[str, ...],
         fallback_id_keys: tuple[str, ...] = (),
     ) -> str:
+        """执行内部辅助逻辑。"""
         if isinstance(value, dict):
             for key in text_keys:
                 text = _normalize_optional_text(value.get(key))
@@ -9111,6 +9340,7 @@ class RecordTools(ToolBase):
         keyword: str,
         state: LookupResolutionState,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         scope = field.member_select_scope if isinstance(field.member_select_scope, dict) else {}
         use_external = bool(
             isinstance(scope.get("externalMemberList"), list) and scope.get("externalMemberList")
@@ -9132,6 +9362,7 @@ class RecordTools(ToolBase):
         return self._normalize_backend_member_candidates(result, external=use_external)
 
     def _member_confirmation_candidates(self, candidates: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         payloads: list[JSONObject] = []
         for candidate in candidates[:LOOKUP_CONFIRMATION_CANDIDATE_LIMIT]:
             source_labels = []
@@ -9169,6 +9400,7 @@ class RecordTools(ToolBase):
         resolution_state: LookupResolutionState | None = None,
         location: str,
     ) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         explicit_member_id: int | None = None
         explicit_user_id: str | None = None
         explicit_email: str | None = None
@@ -9298,6 +9530,7 @@ class RecordTools(ToolBase):
         return None
 
     def _match_member_candidates(self, candidates: list[JSONObject], value: JSONValue) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         member_id: int | None = None
         user_id: str | None = None
         email: str | None = None
@@ -9339,6 +9572,7 @@ class RecordTools(ToolBase):
         return matches
 
     def _lookup_department_detail(self, context, keyword: str, *, purpose: str) -> JSONObject:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         payload = self.backend.request(
             "GET",
             context,
@@ -9372,6 +9606,7 @@ class RecordTools(ToolBase):
         return {"id": dept_id, "value": _stringify_json(matched.get("deptName", matched.get("value", matched.get("name", dept_id))))}
 
     def _match_department_candidates(self, candidates: list[JSONObject], value: JSONValue) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         dept_id: int | None = None
         display: str | None = None
         if isinstance(value, dict):
@@ -9401,6 +9636,7 @@ class RecordTools(ToolBase):
         keyword: str,
         state: LookupResolutionState,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         scope = field.dept_select_scope if isinstance(field.dept_select_scope, dict) else {}
         external = bool(
             isinstance(scope.get("externalDepartList"), list) and scope.get("externalDepartList")
@@ -9411,6 +9647,7 @@ class RecordTools(ToolBase):
         return self._normalize_backend_department_candidates(result, external=external)
 
     def _department_confirmation_candidates(self, candidates: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         payloads: list[JSONObject] = []
         for candidate in candidates[:LOOKUP_CONFIRMATION_CANDIDATE_LIMIT]:
             payloads.append(
@@ -9435,6 +9672,7 @@ class RecordTools(ToolBase):
         resolution_state: LookupResolutionState | None = None,
         location: str,
     ) -> JSONObject | None:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         explicit_dept_id: int | None = None
         explicit_label: str | None = None
         if isinstance(value, dict):
@@ -9577,6 +9815,7 @@ class RecordTools(ToolBase):
         parent_field: FormField | None = None,
         row_ordinal: int | None = None,
     ) -> tuple[JSONObject | None, JSONObject | None]:
+        """执行内部辅助逻辑。"""
         explicit_apply_id: str | None = None
         keyword: str | None = None
         if isinstance(value, dict):
@@ -9707,6 +9946,7 @@ class RecordTools(ToolBase):
         return None, None
 
     def _resolve_filter_field_entries(self, filters: list[JSONObject], index: FieldIndex) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         entries: list[JSONObject] = []
         for item in filters:
             if not isinstance(item, dict):
@@ -9719,6 +9959,7 @@ class RecordTools(ToolBase):
         return entries
 
     def _resolve_sorts(self, sorts: list[JSONObject], index: FieldIndex) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         resolved: list[JSONObject] = []
         for item in sorts:
             if not isinstance(item, dict):
@@ -9732,6 +9973,7 @@ class RecordTools(ToolBase):
         return resolved
 
     def _resolve_time_range_column(self, time_range: JSONObject, index: FieldIndex) -> FormField | None:
+        """执行内部辅助逻辑。"""
         if not time_range or not isinstance(time_range, dict):
             return None
         column = time_range.get("column")
@@ -9740,6 +9982,7 @@ class RecordTools(ToolBase):
         return self._resolve_field_selector(cast(str | int, column), index, location="time_range.column")
 
     def _build_time_range_filter(self, time_range: JSONObject, field: FormField) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         if not time_range:
             return None
         value_from = time_range.get("from")
@@ -9761,6 +10004,7 @@ class RecordTools(ToolBase):
         time_range: JSONObject,
         field: FormField | None,
     ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if field is None:
             return match_rules
         time_rule = self._build_time_range_filter(time_range, field)
@@ -9776,6 +10020,7 @@ class RecordTools(ToolBase):
         return [*match_rules, time_rule]
 
     def _collect_write_plan_field_refs(self, *, fields: JSONObject, answers: list[JSONObject], index: FieldIndex) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         refs: list[JSONObject] = []
         for field_key in fields.keys():
             refs.append(self._resolve_write_plan_field_ref("fields", field_key, index))
@@ -9792,6 +10037,7 @@ class RecordTools(ToolBase):
         return refs
 
     def _resolve_write_plan_field_ref(self, source: str, requested: str, index: FieldIndex) -> JSONObject:
+        """执行内部辅助逻辑。"""
         try:
             field = self._resolve_field_selector(requested, index, location=source)
             return {
@@ -9823,6 +10069,7 @@ class RecordTools(ToolBase):
             }
 
     def _validate_app_and_record(self, app_key: str, apply_id: int | str) -> int:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         normalized_apply_id = _coerce_count(apply_id)
@@ -9831,6 +10078,7 @@ class RecordTools(ToolBase):
         return normalized_apply_id
 
     def _validate_record_write(self, app_key: str, answers: list[JSONObject], apply_id: int | None = None) -> None:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if apply_id is not None and apply_id <= 0:
@@ -9848,6 +10096,7 @@ class RecordTools(ToolBase):
         index: FieldIndex,
         verify_list_type: int = DEFAULT_RECORD_LIST_TYPE,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if apply_id is None:
             return {
                 "verified": False,
@@ -9942,6 +10191,7 @@ class RecordTools(ToolBase):
         apply_id: int,
         original_error: QingflowApiError,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         for page_num in range(1, VERIFY_TASK_FALLBACK_MAX_PAGES + 1):
             task_page = self.backend.request(
                 "POST",
@@ -10013,6 +10263,7 @@ class RecordTools(ToolBase):
         empty_fields: list[JSONObject],
         count_mismatches: list[JSONObject],
     ) -> None:
+        """执行内部辅助逻辑。"""
         field_payload = _field_ref_payload(field) if field is not None else {"que_id": None}
         if not actual_rows:
             empty_fields.append(field_payload)
@@ -10090,6 +10341,7 @@ class RecordTools(ToolBase):
                     )
 
     def _score_field_matches(self, requested: str, index: FieldIndex, *, fuzzy: bool, top_k: int) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         requested_text = requested.strip()
         requested_key = _normalize_field_lookup_key(requested_text)
         if not requested_key:
@@ -10126,6 +10378,7 @@ class RecordTools(ToolBase):
         return matches[: max(top_k, 1)]
 
     def _raise_need_more_data(self, completeness: JSONObject, evidence: JSONObject, message: str) -> None:
+        """执行内部辅助逻辑。"""
         raise RuntimeError(
             json.dumps(
                 {