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

package/src/qingflow_mcp/tools/app_tools.py

@@ -10,11 +10,21 @@ from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject
 from ..list_type_labels import SYSTEM_VIEW_DEFINITIONS, get_app_publish_status_label
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 class AppTools(ToolBase):
+    """应用工具（中文名：应用与表单管理）。
+
+    类型：应用元数据与配置工具。
+    主要职责：
+    1. 查询应用列表、搜索应用、读取应用详情；
+    2. 读取与更新应用基础配置、表单结构与发布状态；
+    3. 提供应用创建、删除、发布等管理能力。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def app_list(profile: str = DEFAULT_PROFILE, ship_auth: bool = False) -> JSONObject:
             return self.app_list(profile=profile, ship_auth=ship_auth)
@@ -79,6 +89,7 @@ class AppTools(ToolBase):
         ) -> JSONObject:
             return self.app_publish(profile=profile, app_key=app_key, payload=payload or {})
 
+    @tool_cn_name("应用列表")
     def app_list(self, *, profile: str, ship_auth: bool = False) -> JSONObject:
         """List current-user visible apps in the selected workspace."""
         def runner(session_profile, context):
@@ -97,6 +108,7 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("应用搜索")
     def app_search(self, *, profile: str, keyword: str = "", page_num: int = 1, page_size: int = 50) -> JSONObject:
         """Search apps by keyword in name/title using backend search API.
         Useful for finding BUG-related apps across all packages."""
@@ -136,7 +148,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("应用详情")
     def app_get(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -196,7 +210,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("应用基础信息")
     def app_get_base(self, *, profile: str, app_key: str, include_raw: bool = False) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -218,7 +234,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新应用基础信息")
     def app_update_base(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -232,6 +250,7 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("应用表单结构")
     def app_get_form_schema(
         self,
         *,
@@ -243,6 +262,7 @@ class AppTools(ToolBase):
         audit_node_id: int | None,
         include_raw: bool = False,
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
         resolved_form_type = _normalize_form_type(form_type)
 
@@ -271,7 +291,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("应用编辑版本号")
     def app_get_edit_version_no(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -280,7 +302,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("应用流程基础信息")
     def app_get_apply_base_info(self, *, profile: str, app_key: str, list_type: int) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
         if not isinstance(list_type, int) or isinstance(list_type, bool) or list_type <= 0:
             raise_tool_error(QingflowApiError.config_error("list_type must be a positive integer"))
@@ -297,7 +321,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新应用流程配置")
     def app_update_apply_config(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -316,7 +342,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新应用表单结构")
     def app_update_form_schema(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -330,7 +358,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("应用编辑完成")
     def app_edit_finished(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -340,7 +370,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("创建应用")
     def app_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
@@ -386,7 +418,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("删除应用")
     def app_delete(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -399,7 +433,9 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("发布应用")
     def app_publish(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -410,10 +446,12 @@ class AppTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_app_key(self, app_key: str) -> None:
+        """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
     def _probe_create_access(self, context: BackendRequestContext, app_key: str) -> bool:
+        """执行内部辅助逻辑。"""
         try:
             self.backend.request(
                 "GET",
@@ -428,6 +466,7 @@ class AppTools(ToolBase):
             raise
 
     def _probe_list_type_access(self, context: BackendRequestContext, app_key: str, list_type: int) -> bool:
+        """执行内部辅助逻辑。"""
         try:
             self.backend.request(
                 "POST",
@@ -442,6 +481,7 @@ class AppTools(ToolBase):
             raise
 
     def _resolve_accessible_system_views(self, context: BackendRequestContext, app_key: str) -> tuple[list[JSONObject], list[JSONObject]]:
+        """执行内部辅助逻辑。"""
         items: list[JSONObject] = []
         warnings: list[JSONObject] = []
         for view_id, list_type, name in SYSTEM_VIEW_DEFINITIONS:
@@ -466,6 +506,7 @@ class AppTools(ToolBase):
         return items, warnings
 
     def _resolve_accessible_custom_views(self, context: BackendRequestContext, app_key: str) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         try:
             payload = self.backend.request("GET", context, f"/app/{app_key}/view/viewList")
         except QingflowApiError as exc:
@@ -491,6 +532,7 @@ class AppTools(ToolBase):
         return items
 
     def _compact_base_info(self, result: dict[str, Any]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         publish_status = result.get("appPublishStatus")
         auth = result.get("auth") if isinstance(result.get("auth"), dict) else {}
         contact_auth = auth.get("contactAuth") if isinstance(auth, dict) and isinstance(auth.get("contactAuth"), dict) else {}
@@ -532,6 +574,7 @@ class AppTools(ToolBase):
         }
 
     def _compact_form_schema(self, result: dict[str, Any]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         base_questions_raw = result.get("baseQues") if isinstance(result.get("baseQues"), list) else []
         form_questions_raw = result.get("formQues") if isinstance(result.get("formQues"), list) else []
         base_questions = [self._compact_question(question) for question in base_questions_raw if isinstance(question, dict)]
@@ -568,6 +611,7 @@ class AppTools(ToolBase):
         }
 
     def _compact_user(self, user: Any) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         if not isinstance(user, dict):
             return None
         return {
@@ -578,6 +622,7 @@ class AppTools(ToolBase):
         }
 
     def _compact_tag_item(self, item: dict[str, Any]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         return {
             "itemType": item.get("itemType"),
             "title": item.get("title"),
@@ -588,6 +633,7 @@ class AppTools(ToolBase):
         }
 
     def _compact_question(self, question: dict[str, Any]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         options = question.get("options")
         inner_questions = question.get("innerQuestions")
         sub_questions = question.get("subQuestions")
@@ -610,6 +656,7 @@ class AppTools(ToolBase):
         return {key: value for key, value in compact.items() if value is not None}
 
     def _extract_visible_apps(self, result: Any) -> tuple[list[JSONObject], str]:
+        """执行内部辅助逻辑。"""
         apps: list[JSONObject] = []
         seen: set[str] = set()
 
@@ -674,6 +721,7 @@ class AppTools(ToolBase):
         group_id: int | None,
         group_name: str | None,
     ) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
         app_key = str(item.get("appKey") or item.get("app_key") or "").strip()
         if not app_key:
             return None
@@ -692,6 +740,7 @@ class AppTools(ToolBase):
         return {key: value for key, value in compact.items() if value not in (None, [], "", {})}
 
     def _count_auth_members(self, auth_payload: Any, member_key: str) -> int:
+        """执行内部辅助逻辑。"""
         if not isinstance(auth_payload, dict):
             return 0
         auth_members = auth_payload.get("authMembers")
@@ -701,6 +750,7 @@ class AppTools(ToolBase):
         return len(members) if isinstance(members, list) else 0
 
     def _extract_include_sub_departs(self, auth_payload: Any) -> bool | None:
+        """执行内部辅助逻辑。"""
         if not isinstance(auth_payload, dict):
             return None
         auth_members = auth_payload.get("authMembers")