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

package/src/qingflow_mcp/tools/file_tools.py

@@ -14,7 +14,7 @@ from mcp.server.fastmcp import FastMCP
 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
 
 
 ATTACHMENT_UPLOAD_INFO_FALLBACK_CODES = {"40118", 40118}
@@ -22,7 +22,17 @@ LEGACY_OSS_FORM_REQUIRED_KEYS = ("key", "policy", "signature", "ossAccessKeyId")
 
 
 class FileTools(ToolBase):
+    """文件工具（中文名：上传与下载中转）。
+
+    类型：文件传输工具。
+    主要职责：
+    1. 申请上传凭证与上传地址；
+    2. 支持本地路径、URL、Base64 内容三类上传输入；
+    3. 返回标准化文件元信息供导入与记录附件使用。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def file_get_upload_info(
             profile: str = DEFAULT_PROFILE,
@@ -69,6 +79,7 @@ class FileTools(ToolBase):
                 file_related_url=file_related_url,
             )
 
+    @tool_cn_name("文件上传信息")
     def file_get_upload_info(
         self,
         *,
@@ -82,6 +93,7 @@ class FileTools(ToolBase):
         path_id: int | None = None,
         file_related_url: str | None = None,
     ) -> dict[str, Any]:
+        """执行文件处理相关逻辑。"""
         def runner(session_profile, context):
             upload_info = self._request_upload_info_with_fallback(
                 context,
@@ -110,6 +122,7 @@ class FileTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("本地文件上传")
     def file_upload_local(
         self,
         *,
@@ -122,6 +135,7 @@ class FileTools(ToolBase):
         path_id: int | None = None,
         file_related_url: str | None = None,
     ) -> dict[str, Any]:
+        """执行文件处理相关逻辑。"""
         path = Path(file_path).expanduser()
         if not path.is_file():
             raise_tool_error(QingflowApiError.config_error("file_path must point to an existing file"))
@@ -202,6 +216,7 @@ class FileTools(ToolBase):
         path_id: int | None,
         file_related_url: str | None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         if not file_name:
             raise_tool_error(QingflowApiError.config_error("file_name is required"))
         if file_size <= 0:
@@ -225,6 +240,7 @@ class FileTools(ToolBase):
         return payload
 
     def _resolve_upload_endpoint(self, upload_kind: str) -> str:
+        """执行内部辅助逻辑。"""
         normalized = upload_kind.strip().lower()
         if normalized == "attachment":
             return "/upload/puburl"
@@ -236,10 +252,12 @@ class FileTools(ToolBase):
         raise AssertionError("unreachable")
 
     def _encode_formula(self, formula: str) -> str:
+        """执行内部辅助逻辑。"""
         encoded = base64.b64encode(quote(formula, safe="").encode("utf-8")).decode("utf-8")
         return f"{self._random_string(16)}{encoded}{self._random_string(16)}"
 
     def _random_string(self, length: int) -> str:
+        """执行内部辅助逻辑。"""
         alphabet = string.ascii_letters + string.digits
         return "".join(random.choice(alphabet) for _ in range(length))
 
@@ -256,6 +274,7 @@ class FileTools(ToolBase):
         path_id: int | None,
         file_related_url: str | None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         requested_kind = upload_kind.strip().lower()
         attempted_kinds = [requested_kind]
         if requested_kind == "attachment":
@@ -305,6 +324,7 @@ class FileTools(ToolBase):
         path_id: int | None,
         file_related_url: str | None,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         endpoint = self._resolve_upload_endpoint(upload_kind)
         file_upload_bo = self._build_file_upload_bo(
             upload_kind=upload_kind,
@@ -336,6 +356,7 @@ class FileTools(ToolBase):
         attempted_kind: str,
         error: QingflowApiError,
     ) -> bool:
+        """执行内部辅助逻辑。"""
         return (
             requested_kind == "attachment"
             and attempted_kind == "attachment"
@@ -343,6 +364,7 @@ class FileTools(ToolBase):
         )
 
     def _is_legacy_oss_form_upload(self, payload: JSONObject) -> bool:
+        """执行内部辅助逻辑。"""
         return all(str(payload.get(key) or "").strip() for key in LEGACY_OSS_FORM_REQUIRED_KEYS)
 
     def _upload_legacy_oss_form(
@@ -353,6 +375,7 @@ class FileTools(ToolBase):
         content: bytes,
         content_type: str,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         upload_url = self._resolve_legacy_oss_form_url(upload_info)
         if not upload_url:
             raise QingflowApiError.config_error("legacy upload payload is missing host/uploadAccelerateHost")
@@ -375,6 +398,7 @@ class FileTools(ToolBase):
         )
 
     def _resolve_legacy_oss_form_url(self, upload_info: JSONObject) -> str:
+        """执行内部辅助逻辑。"""
         for key in ("uploadAccelerateHost", "host", "uploadUrl"):
             value = str(upload_info.get(key) or "").strip()
             if not value:

package/src/qingflow_mcp/tools/import_tools.py

@@ -21,7 +21,7 @@ from ..errors import QingflowApiError
 from ..import_store import ImportJobStore, ImportVerificationStore
 from ..json_types import JSONObject
 from .app_tools import _derive_import_capability
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 from .file_tools import FileTools
 from .record_tools import RecordTools, _build_field_index, _normalize_form_schema
 
@@ -40,6 +40,15 @@ EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
 
 
 class ImportTools(ToolBase):
+    """导入工具（中文名：数据导入与校验）。
+
+    类型：批量数据导入工具。
+    主要职责：
+    1. 获取导入模板与导入 schema；
+    2. 执行导入文件校验与本地修复；
+    3. 启动导入任务并查询导入进度与结果。
+    """
+
     def __init__(
         self,
         sessions,
@@ -48,6 +57,7 @@ class ImportTools(ToolBase):
         verification_store: ImportVerificationStore | None = None,
         job_store: ImportJobStore | None = None,
     ) -> None:
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
         self._record_tools = RecordTools(sessions, backend)
         self._file_tools = FileTools(sessions, backend)
@@ -55,6 +65,7 @@ class ImportTools(ToolBase):
         self._job_store = job_store or ImportJobStore()
 
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def record_import_schema_get(
             app_key: str = "",
@@ -155,6 +166,7 @@ class ImportTools(ToolBase):
                 process_id_str=process_id_str,
             )
 
+    @tool_cn_name("导入 Schema")
     def record_import_schema_get(
         self,
         *,
@@ -162,6 +174,7 @@ class ImportTools(ToolBase):
         app_key: str,
         output_profile: str = "normal",
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         if not app_key.strip():
             return {
                 "ok": False,
@@ -217,6 +230,7 @@ class ImportTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("导入模板")
     def record_import_template_get(
         self,
         *,
@@ -224,6 +238,7 @@ class ImportTools(ToolBase):
         app_key: str,
         download_to_path: str | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         if not app_key.strip():
             return self._failed_template_result(app_key=app_key, error_code="IMPORT_TEMPLATE_UNAUTHORIZED", message="app_key is required")
 
@@ -316,6 +331,7 @@ class ImportTools(ToolBase):
         except RuntimeError as exc:
             return self._runtime_error_as_result(exc, error_code="IMPORT_TEMPLATE_UNAUTHORIZED")
 
+    @tool_cn_name("导入校验")
     def record_import_verify(
         self,
         *,
@@ -323,6 +339,7 @@ class ImportTools(ToolBase):
         app_key: str,
         file_path: str,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         if not app_key.strip():
             return self._failed_verify_result(app_key=app_key, file_path=file_path, error_code="IMPORT_VERIFICATION_FAILED", message="app_key is required")
         path = Path(file_path).expanduser()
@@ -531,6 +548,7 @@ class ImportTools(ToolBase):
         except RuntimeError as exc:
             return self._runtime_error_as_result(exc, error_code="IMPORT_VERIFICATION_FAILED", extra={"can_import": False})
 
+    @tool_cn_name("导入修复")
     def record_import_repair_local(
         self,
         *,
@@ -540,6 +558,7 @@ class ImportTools(ToolBase):
         output_path: str | None = None,
         selected_repairs: list[str] | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         if not verification_id.strip():
             return self._failed_repair_result(error_code="IMPORT_VERIFICATION_FAILED", message="verification_id is required")
         if not authorized_file_modification:
@@ -639,6 +658,7 @@ class ImportTools(ToolBase):
         except RuntimeError as exc:
             return self._runtime_error_as_result(exc, error_code="IMPORT_REPAIR_FORMAT_UNSUPPORTED")
 
+    @tool_cn_name("开始导入")
     def record_import_start(
         self,
         *,
@@ -648,6 +668,7 @@ class ImportTools(ToolBase):
         being_enter_auditing: bool | None,
         view_key: str | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         if being_enter_auditing is None:
             return self._failed_start_result(error_code="IMPORT_VERIFICATION_FAILED", message="being_enter_auditing must be passed explicitly")
 
@@ -744,6 +765,7 @@ class ImportTools(ToolBase):
         except RuntimeError as exc:
             return self._runtime_error_as_result(exc, error_code="IMPORT_VERIFICATION_FAILED", extra={"accepted": False})
 
+    @tool_cn_name("导入状态")
     def record_import_status_get(
         self,
         *,
@@ -752,6 +774,7 @@ class ImportTools(ToolBase):
         import_id: str | None = None,
         process_id_str: str | None = None,
     ) -> dict[str, Any]:
+        """执行记录相关逻辑。"""
         normalized_app_key = (app_key or "").strip()
         normalized_import_id = _normalize_optional_text(import_id)
         normalized_process_id = _normalize_optional_text(process_id_str)
@@ -883,6 +906,7 @@ class ImportTools(ToolBase):
         *,
         import_capability: JSONObject | None = None,
     ) -> tuple[Any, list[JSONObject], str]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         auth_source = _normalize_optional_text((import_capability or {}).get("auth_source")) or "unknown"
         if auth_source == "data_manage_auth":
             schema = self.backend.request("GET", context, f"/app/{app_key}/form", params={"type": 1})
@@ -929,6 +953,7 @@ class ImportTools(ToolBase):
         *,
         import_capability: JSONObject | None = None,
     ) -> tuple[list[JSONObject], str]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         _, expected_columns, schema_fingerprint = self._resolve_import_schema_bundle(
             profile,
             context,
@@ -949,6 +974,7 @@ class ImportTools(ToolBase):
         allowed_header_titles: list[str] | None,
         schema_fingerprint: str,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         extension = path.suffix.lower()
         file_sha256 = _sha256_file(path)
         base_result = {
@@ -1065,6 +1091,7 @@ class ImportTools(ToolBase):
         expected_columns: list[JSONObject],
         field_index: Any,
     ) -> tuple[list[JSONObject], list[JSONObject]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         issues: list[JSONObject] = []
         warnings: list[JSONObject] = []
         header_positions = _sheet_header_positions(sheet)
@@ -1144,6 +1171,7 @@ class ImportTools(ToolBase):
         column: JSONObject,
         field,
     ) -> tuple[JSONObject | None, JSONObject | None]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         invalid_email_samples: list[str] = []
         scope_miss_samples: list[str] = []
         checked_values: set[str] = set()
@@ -1202,6 +1230,7 @@ class ImportTools(ToolBase):
         column: JSONObject,
         field,
     ) -> tuple[JSONObject | None, JSONObject | None]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         scope_miss_samples: list[str] = []
         checked_values: set[str] = set()
         for row_index in range(2, sheet.max_row + 1):
@@ -1248,6 +1277,7 @@ class ImportTools(ToolBase):
         import_capability: JSONObject | None = None,
         expected_columns: list[JSONObject] | None = None,
     ) -> tuple[dict[str, Any], list[JSONObject]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         warnings: list[JSONObject] = []
         try:
             payload = self.backend.request("GET", context, f"/app/{app_key}/apply/excelTemplate")
@@ -1298,6 +1328,7 @@ class ImportTools(ToolBase):
         template_header_profile: dict[str, Any],
         local_check: dict[str, Any],
     ) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         if source_path.suffix.lower() != ".xlsx":
             return None
         try:
@@ -1345,6 +1376,7 @@ class ImportTools(ToolBase):
             return normalized
 
     def _fetch_import_capability(self, context, app_key: str) -> tuple[JSONObject, list[JSONObject]]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         try:
             payload = self.backend.request("GET", context, f"/app/{app_key}/baseInfo")
         except QingflowApiError:
@@ -1358,6 +1390,7 @@ class ImportTools(ToolBase):
         destination_hint: str | None,
         app_key: str,
     ) -> str:
+        """执行内部辅助逻辑。"""
         if destination_hint:
             destination = _resolve_template_download_path(destination_hint, app_key=app_key)
         else:
@@ -1378,6 +1411,7 @@ class ImportTools(ToolBase):
         message: str,
         request_route: JSONObject | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         return {
             "ok": False,
             "status": "failed",
@@ -1402,6 +1436,7 @@ class ImportTools(ToolBase):
         message: str,
         extra: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         payload = {
             "ok": True,
             "status": "failed",
@@ -1434,6 +1469,7 @@ class ImportTools(ToolBase):
         return payload
 
     def _failed_repair_result(self, *, error_code: str, message: str, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         payload = {
             "ok": False,
             "status": "failed",
@@ -1457,6 +1493,7 @@ class ImportTools(ToolBase):
         return payload
 
     def _failed_start_result(self, *, error_code: str, message: str, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         payload = {
             "ok": False,
             "status": "failed",
@@ -1481,6 +1518,7 @@ class ImportTools(ToolBase):
         return payload
 
     def _failed_status_result(self, *, error_code: str, message: str, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         payload = {
             "ok": False,
             "status": "failed",
@@ -1514,6 +1552,7 @@ class ImportTools(ToolBase):
         error_code: str,
         extra: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         try:
             payload = json.loads(str(error))
         except json.JSONDecodeError:

package/src/qingflow_mcp/tools/navigation_tools.py

@@ -5,11 +5,21 @@ from mcp.server.fastmcp import FastMCP
 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 NavigationTools(ToolBase):
+    """导航工具（中文名：导航菜单管理）。
+
+    类型：门户导航配置工具。
+    主要职责：
+    1. 查询导航结构与发布状态；
+    2. 读取指定导航详情；
+    3. 应用导航配置变更。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def navigation_list_published(profile: str = DEFAULT_PROFILE, page_num: int = 1, page_size: int = 50) -> JSONObject:
             return self.navigation_list_published(profile=profile, page_num=page_num, page_size=page_size)
@@ -59,14 +69,18 @@ class NavigationTools(ToolBase):
         def navigation_reorder(profile: str = DEFAULT_PROFILE, payload: list[JSONObject] | None = None) -> JSONObject:
             return self.navigation_reorder(profile=profile, payload=payload or [])
 
+    @tool_cn_name("导航已发布列表")
     def navigation_list_published(self, *, profile: str, page_num: int = 1, page_size: int = 50) -> JSONObject:
+        """执行工具方法逻辑。"""
         def runner(session_profile, context):
             result = self.backend.request("GET", context, "/navigation", params={"pageNum": page_num, "pageSize": page_size})
             return {"profile": profile, "ws_id": session_profile.selected_ws_id, "page": result}
 
         return self._run(profile, runner)
 
+    @tool_cn_name("导航草稿分页")
     def navigation_list_draft_page(self, *, profile: str, page_num: int = 1, page_size: int = 50, query_key: str | None = None) -> JSONObject:
+        """执行工具方法逻辑。"""
         def runner(session_profile, context):
             params: JSONObject = {"pageNum": page_num, "pageSize": page_size}
             if query_key:
@@ -76,7 +90,9 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("导航草稿全量")
     def navigation_list_draft_all(self, *, profile: str, query_key: str | None = None) -> JSONObject:
+        """执行工具方法逻辑。"""
         def runner(session_profile, context):
             params: JSONObject = {}
             if query_key:
@@ -86,7 +102,9 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("导航详情")
     def navigation_get_detail(self, *, profile: str, navigation_item_id: int, status: str = "draft") -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_navigation_item_id(navigation_item_id)
 
         def runner(session_profile, context):
@@ -100,14 +118,18 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("导航发布状态")
     def navigation_get_status(self, *, profile: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         def runner(session_profile, context):
             result = self.backend.request("GET", context, "/navigation/status")
             return {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
 
         return self._run(profile, runner)
 
+    @tool_cn_name("设置导航可见性")
     def navigation_set_visible(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
@@ -116,7 +138,9 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("创建导航项")
     def navigation_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
@@ -125,7 +149,9 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新导航项")
     def navigation_update(self, *, profile: str, navigation_item_id: int, payload: JSONObject) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_navigation_item_id(navigation_item_id)
         body = self._require_dict(payload)
 
@@ -139,7 +165,9 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("删除导航项")
     def navigation_delete(self, *, profile: str, navigation_item_id: int) -> JSONObject:
+        """执行工具方法逻辑。"""
         self._require_navigation_item_id(navigation_item_id)
 
         def runner(session_profile, context):
@@ -152,7 +180,9 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("发布导航")
     def navigation_publish(self, *, profile: str, navigation_id: int) -> JSONObject:
+        """执行工具方法逻辑。"""
         if navigation_id <= 0:
             raise_tool_error(QingflowApiError.config_error("navigation_id must be positive"))
 
@@ -162,7 +192,9 @@ class NavigationTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("导航排序")
     def navigation_reorder(self, *, profile: str, payload: list[JSONObject]) -> JSONObject:
+        """执行工具方法逻辑。"""
         if not isinstance(payload, list) or not payload:
             raise_tool_error(QingflowApiError.config_error("payload must be a non-empty array"))
 
@@ -173,5 +205,6 @@ class NavigationTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_navigation_item_id(self, navigation_item_id: int) -> None:
+        """执行内部辅助逻辑。"""
         if navigation_item_id <= 0:
             raise_tool_error(QingflowApiError.config_error("navigation_item_id must be positive"))

package/src/qingflow_mcp/tools/package_tools.py

@@ -7,11 +7,21 @@ from mcp.server.fastmcp import FastMCP
 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 PackageTools(ToolBase):
+    """分组工具（中文名：分组与归档管理）。
+
+    类型：资源组织工具。
+    主要职责：
+    1. 查询、解析、创建分组；
+    2. 管理应用与分组的挂载关系；
+    3. 为应用搭建提供分组定位能力。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all", include_raw: bool = False) -> JSONObject:
             return self.package_list(profile=profile, trial_status=trial_status, include_raw=include_raw)
@@ -36,7 +46,9 @@ class PackageTools(ToolBase):
         def package_delete(profile: str = DEFAULT_PROFILE, tag_id: int = 0, deleted_all_data: bool = False) -> JSONObject:
             return self.package_delete(profile=profile, tag_id=tag_id, deleted_all_data=deleted_all_data)
 
+    @tool_cn_name("分组列表")
     def package_list(self, *, profile: str, trial_status: str = "all", include_raw: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         def runner(session_profile, context):
             result = self.backend.request("GET", context, "/tag", params={"trialStatus": trial_status})
             raw_items, source_shape = self._extract_package_items(result)
@@ -57,7 +69,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("分组详情")
     def package_get(self, *, profile: str, tag_id: int, include_raw: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_tag_id(tag_id)
 
         def runner(session_profile, context):
@@ -80,7 +94,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("分组基础信息")
     def package_get_base(self, *, profile: str, tag_id: int, include_raw: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_readable_tag_id(tag_id)
 
         def runner(session_profile, context):
@@ -99,7 +115,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("创建分组")
     def package_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
@@ -108,7 +126,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新分组")
     def package_update(self, *, profile: str, tag_id: int, payload: JSONObject) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_tag_id(tag_id)
         body = self._require_dict(payload)
 
@@ -128,7 +148,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("分组排序")
     def package_sort_items(self, *, profile: str, tag_id: int, tag_items: list[JSONObject]) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_tag_id(tag_id)
 
         def runner(session_profile, context):
@@ -142,7 +164,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("创建分组分栏")
     def package_group_create(self, *, profile: str, tag_id: int, group_name: str) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_tag_id(tag_id)
         normalized_name = str(group_name or "").strip()
         if not normalized_name:
@@ -159,7 +183,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新分组分栏")
     def package_group_update(self, *, profile: str, tag_id: int, group_id: int, group_name: str) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_tag_id(tag_id)
         self._require_group_id(group_id)
         normalized_name = str(group_name or "").strip()
@@ -177,7 +203,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("删除分组分栏")
     def package_group_delete(self, *, profile: str, tag_id: int, group_id: int) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_tag_id(tag_id)
         self._require_group_id(group_id)
 
@@ -187,7 +215,9 @@ class PackageTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("删除分组")
     def package_delete(self, *, profile: str, tag_id: int, deleted_all_data: bool = False) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         self._require_tag_id(tag_id)
 
         def runner(session_profile, context):
@@ -206,18 +236,22 @@ class PackageTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_tag_id(self, tag_id: int) -> None:
+        """执行内部辅助逻辑。"""
         if tag_id <= 0:
             raise_tool_error(QingflowApiError.config_error("tag_id must be positive"))
 
     def _require_group_id(self, group_id: int) -> None:
+        """执行内部辅助逻辑。"""
         if group_id <= 0:
             raise_tool_error(QingflowApiError.config_error("group_id must be positive"))
 
     def _require_readable_tag_id(self, tag_id: int) -> None:
+        """执行内部辅助逻辑。"""
         if tag_id < 0:
             raise_tool_error(QingflowApiError.config_error("tag_id must be non-negative"))
 
     def _normalize_package_payload(self, payload: JSONObject, existing: JSONObject | None = None) -> JSONObject:
+        """执行内部辅助逻辑。"""
         data = deepcopy(existing) if isinstance(existing, dict) else {}
         data.update(deepcopy(payload))
         data.pop("tagId", None)
@@ -232,6 +266,7 @@ class PackageTools(ToolBase):
         return data
 
     def _compact_package(self, result: dict[str, object], *, base_info: dict[str, object] | None = None) -> JSONObject:
+        """执行内部辅助逻辑。"""
         tag_items = result.get("tagItems") if isinstance(result.get("tagItems"), list) else []
         permission_source = base_info if isinstance(base_info, dict) else result
         preview = []
@@ -262,6 +297,7 @@ class PackageTools(ToolBase):
         return {key: value for key, value in compact.items() if value is not None}
 
     def _extract_package_items(self, result: object) -> tuple[list[dict[str, object]], str]:
+        """执行内部辅助逻辑。"""
         if isinstance(result, list):
             return [item for item in result if isinstance(item, dict)], "list"
         if isinstance(result, dict):