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

package/src/qingflow_mcp/tools/task_tools.py

@@ -7,7 +7,7 @@ from mcp.server.fastmcp import FastMCP
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..list_type_labels import get_record_list_type_label, get_task_type_label
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 TASK_BOX_TO_TYPE = {
     "todo": 1,
@@ -31,7 +31,9 @@ FLOW_STATUS_TO_PROCESS_STATUS = {
 
 
 class TaskTools(ToolBase):
-    """任务中心（待办/已办）相关工具
+    """任务中心工具（中文名：任务列表与操作）
+
+    类型：流程任务运营工具。
 
     提供对工作流任务的管理功能，包括：
     - 查询待办/已办列表
@@ -59,6 +61,7 @@ class TaskTools(ToolBase):
     """
 
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def task_summary(
             profile: str = DEFAULT_PROFILE,
@@ -139,12 +142,14 @@ class TaskTools(ToolBase):
         ) -> dict[str, Any]:
             return self.task_urge_public(profile=profile, app_key=app_key, record_id=record_id)
 
+    @tool_cn_name("任务摘要")
     def task_summary(
         self,
         *,
         profile: str,
         app_key: str | None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         raw = self.task_statistics(profile=profile, app_key=app_key)
         statistics = raw.get("statistics", {})
         summary = self._normalize_task_summary_payload(statistics)
@@ -160,6 +165,7 @@ class TaskTools(ToolBase):
             },
         }
 
+    @tool_cn_name("任务列表")
     def task_list_public(
         self,
         *,
@@ -174,6 +180,7 @@ class TaskTools(ToolBase):
         sort_by: str | None,
         sort_direction: str,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         normalized_type = self._task_box_to_type(task_box)
         normalized_status = self._flow_status_to_process_status(flow_status)
         create_time_asc = self._task_sort_to_create_time_asc(sort_by, sort_direction)
@@ -216,6 +223,7 @@ class TaskTools(ToolBase):
             },
         }
 
+    @tool_cn_name("任务分面统计")
     def task_facets(
         self,
         *,
@@ -227,6 +235,7 @@ class TaskTools(ToolBase):
         query: str | None,
         limit: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         normalized_type = self._task_box_to_type(task_box)
         normalized_status = self._flow_status_to_process_status(flow_status)
         if dimension not in {"worksheet", "workflow_node"}:
@@ -288,6 +297,7 @@ class TaskTools(ToolBase):
             },
         }
 
+    @tool_cn_name("任务标记已读")
     def task_mark_read_public(
         self,
         *,
@@ -296,6 +306,7 @@ class TaskTools(ToolBase):
         task_id: int,
         task_box: str,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         raw = self.task_mark_read(profile=profile, app_key=app_key, id=task_id, type=self._task_box_to_type(task_box))
         return self._public_task_action_response(
             raw,
@@ -304,12 +315,14 @@ class TaskTools(ToolBase):
             selection={"task_box": task_box},
         )
 
+    @tool_cn_name("抄送全部已读")
     def task_mark_all_cc_read_public(
         self,
         *,
         profile: str,
         flow_status: str,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         raw = self.task_mark_all_cc_read(profile=profile, type=TASK_BOX_TO_TYPE["cc"], process_status=self._flow_status_to_process_status(flow_status))
         return self._public_task_action_response(
             raw,
@@ -318,6 +331,7 @@ class TaskTools(ToolBase):
             selection={"task_box": "cc", "flow_status": flow_status},
         )
 
+    @tool_cn_name("任务催办")
     def task_urge_public(
         self,
         *,
@@ -325,6 +339,7 @@ class TaskTools(ToolBase):
         app_key: str,
         record_id: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         raw = self.task_urge(profile=profile, app_key=app_key, row_record_id=record_id)
         return self._public_task_action_response(
             raw,
@@ -333,6 +348,7 @@ class TaskTools(ToolBase):
             selection={},
         )
 
+    @tool_cn_name("任务列表（兼容）")
     def task_list(
         self,
         *,
@@ -346,9 +362,9 @@ class TaskTools(ToolBase):
         page_size: int,
         create_time_asc: bool | None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._validate_type(type)
         self._validate_process_status(process_status)
-
         def runner(session_profile, context):
             payload: dict[str, Any] = {
                 "type": type,
@@ -379,6 +395,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务分组列表")
     def task_list_grouped(
         self,
         *,
@@ -391,6 +408,7 @@ class TaskTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._validate_type(type)
         self._validate_process_status(process_status)
 
@@ -422,12 +440,14 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务统计")
     def task_statistics(
         self,
         *,
         profile: str,
         app_key: str | None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         def runner(session_profile, context):
             params: dict[str, Any] = {}
             if app_key:
@@ -443,6 +463,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务流程节点")
     def task_workflow_nodes(
         self,
         *,
@@ -454,6 +475,7 @@ class TaskTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._validate_type(type)
 
         def runner(session_profile, context):
@@ -482,6 +504,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务节点统计")
     def task_node_statistics(
         self,
         *,
@@ -490,6 +513,7 @@ class TaskTools(ToolBase):
         type: int,
         search_key: str | None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._validate_type(type)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
@@ -516,6 +540,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务应用统计")
     def task_worksheet_statistics(
         self,
         *,
@@ -525,6 +550,7 @@ class TaskTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._validate_type(type)
 
         def runner(session_profile, context):
@@ -549,6 +575,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务已读（兼容）")
     def task_mark_read(
         self,
         *,
@@ -557,6 +584,7 @@ class TaskTools(ToolBase):
         id: int,
         type: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if id <= 0:
@@ -583,6 +611,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("抄送已读（兼容）")
     def task_mark_all_cc_read(
         self,
         *,
@@ -590,6 +619,7 @@ class TaskTools(ToolBase):
         type: int,
         process_status: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         self._validate_type(type)
         self._validate_process_status(process_status)
 
@@ -612,6 +642,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务催办（兼容）")
     def task_urge(
         self,
         *,
@@ -619,6 +650,7 @@ class TaskTools(ToolBase):
         app_key: str,
         row_record_id: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if row_record_id <= 0:
@@ -641,6 +673,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("任务分组详情")
     def task_group_detail(
         self,
         *,
@@ -648,6 +681,7 @@ class TaskTools(ToolBase):
         app_key: str,
         group_id: int,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
         if group_id <= 0:
@@ -670,6 +704,7 @@ class TaskTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("批处理任务数量")
     def task_batch_processing_amount(
         self,
         *,
@@ -678,6 +713,7 @@ class TaskTools(ToolBase):
         list_type: int,
         task_center_filter: dict[str, Any] | None,
     ) -> dict[str, Any]:
+        """执行任务相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
 
@@ -707,6 +743,7 @@ class TaskTools(ToolBase):
         return self._run(profile, runner)
 
     def _validate_type(self, type: int) -> None:
+        """执行内部辅助逻辑。"""
         valid_types = [1, 2, 3, 5]  # TODO, INITIATED, CC, DONE
         if type not in valid_types:
             raise_tool_error(
@@ -716,6 +753,7 @@ class TaskTools(ToolBase):
             )
 
     def _validate_process_status(self, process_status: int) -> None:
+        """执行内部辅助逻辑。"""
         valid_statuses = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
         if process_status not in valid_statuses:
             raise_tool_error(
@@ -725,12 +763,14 @@ class TaskTools(ToolBase):
             )
 
     def _task_box_to_type(self, task_box: str) -> int:
+        """执行内部辅助逻辑。"""
         normalized = (task_box or "").strip().lower()
         if normalized not in TASK_BOX_TO_TYPE:
             raise_tool_error(QingflowApiError.config_error("task_box must be todo, initiated, cc, or done"))
         return TASK_BOX_TO_TYPE[normalized]
 
     def _flow_status_to_process_status(self, flow_status: str) -> int:
+        """执行内部辅助逻辑。"""
         normalized = (flow_status or "").strip().lower()
         if normalized not in FLOW_STATUS_TO_PROCESS_STATUS:
             raise_tool_error(
@@ -741,6 +781,7 @@ class TaskTools(ToolBase):
         return FLOW_STATUS_TO_PROCESS_STATUS[normalized]
 
     def _task_sort_to_create_time_asc(self, sort_by: str | None, sort_direction: str) -> bool | None:
+        """执行内部辅助逻辑。"""
         normalized_sort_by = (sort_by or "").strip().lower() if sort_by is not None else ""
         normalized_direction = (sort_direction or "desc").strip().lower()
         if normalized_direction not in {"asc", "desc"}:
@@ -752,11 +793,13 @@ class TaskTools(ToolBase):
         return normalized_direction == "asc"
 
     def _task_applied_sort(self, sort_by: str | None, sort_direction: str) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         if not sort_by:
             return []
         return [{"by": "created_at", "order": (sort_direction or "desc").strip().lower()}]
 
     def _normalize_task_summary_payload(self, payload: Any) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         if not isinstance(payload, dict):
             return {}
         return {
@@ -769,6 +812,7 @@ class TaskTools(ToolBase):
         }
 
     def _normalize_task_facets(self, payload: Any) -> list[dict[str, Any]]:
+        """执行内部辅助逻辑。"""
         items = _task_page_items(payload)
         groups: list[dict[str, Any]] = []
         for item in items:
@@ -788,6 +832,7 @@ class TaskTools(ToolBase):
         resource: dict[str, Any],
         selection: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         response = dict(raw)
         response["ok"] = bool(raw.get("ok", True))
         response["warnings"] = []
@@ -801,6 +846,7 @@ class TaskTools(ToolBase):
         return response
 
     def _request_route_payload(self, context) -> dict[str, Any]:  # type: ignore[no-untyped-def]
+        """执行内部辅助逻辑。"""
         describe_route = getattr(self.backend, "describe_route", None)
         if callable(describe_route):
             payload = describe_route(context)

package/src/qingflow_mcp/tools/view_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, JSONValue
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 class ViewTools(ToolBase):
+    """视图工具（中文名：视图查询与配置读取）。
+
+    类型：视图配置工具。
+    主要职责：
+    1. 查询应用视图列表；
+    2. 获取视图配置与结构信息；
+    3. 为记录查询和分析提供视图侧元数据。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def view_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.view_list(profile=profile, app_key=app_key)
@@ -46,15 +56,21 @@ class ViewTools(ToolBase):
         def view_get_workflow_status(profile: str = DEFAULT_PROFILE, viewgraph_key: str = "", row_record_id: int = 0) -> JSONObject:
             return self.view_get_workflow_status(profile=profile, viewgraph_key=viewgraph_key, row_record_id=row_record_id)
 
+    @tool_cn_name("视图列表")
     def view_list(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_app_key(app_key)
         return self._request(profile, "GET", f"/app/{app_key}/view/viewList", app_key=app_key)
 
+    @tool_cn_name("视图列表（扁平）")
     def view_list_flat(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_app_key(app_key)
         return self._request(profile, "GET", f"/app/{app_key}/view/views", app_key=app_key)
 
+    @tool_cn_name("视图排序")
     def view_reorder(self, *, profile: str, app_key: str, payload: list[JSONObject]) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_app_key(app_key)
         if not isinstance(payload, list) or not payload:
             raise_tool_error(QingflowApiError.config_error("payload must be a non-empty array"))
@@ -66,26 +82,36 @@ class ViewTools(ToolBase):
             json_body=self._normalize_reorder_payload(payload),
         )
 
+    @tool_cn_name("设置视图列宽")
     def view_set_column_width(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
         return self._request(profile, "POST", f"/app/{app_key}/view/que/width", app_key=app_key, json_body=body)
 
+    @tool_cn_name("创建视图")
     def view_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         body = self._require_dict(payload)
         app_key = str(body.get("appKey") or "")
         return self._request(profile, "POST", "/view/viewConfig", app_key=app_key, json_body=body)
 
+    @tool_cn_name("视图配置")
     def view_get_config(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         return self._request(profile, "GET", f"/view/{viewgraph_key}/viewConfig", viewgraph_key=viewgraph_key)
 
+    @tool_cn_name("视图基础信息")
     def view_get_base_info(self, *, profile: str, viewgraph_key: str, passcode: str | None) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         params = {"pass": passcode} if passcode else None
         return self._request(profile, "GET", f"/view/{viewgraph_key}/viewConfig/baseInfo", viewgraph_key=viewgraph_key, params=params)
 
+    @tool_cn_name("更新视图配置")
     def view_update(self, *, profile: str, viewgraph_key: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         body = self._require_dict(payload)
         return self._request(
@@ -98,7 +124,9 @@ class ViewTools(ToolBase):
             risk_target="view configuration",
         )
 
+    @tool_cn_name("删除视图")
     def view_delete(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         return self._request(
             profile,
@@ -109,19 +137,27 @@ class ViewTools(ToolBase):
             risk_target="view configuration",
         )
 
+    @tool_cn_name("复制视图")
     def view_copy(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         return self._request(profile, "POST", f"/view/{viewgraph_key}/copy", viewgraph_key=viewgraph_key)
 
+    @tool_cn_name("视图字段列表")
     def view_list_questions(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         return self._request(profile, "GET", f"/view/{viewgraph_key}/question", viewgraph_key=viewgraph_key)
 
+    @tool_cn_name("视图关联列表")
     def view_list_associations(self, *, profile: str, viewgraph_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         return self._request(profile, "GET", f"/view/{viewgraph_key}/association", viewgraph_key=viewgraph_key)
 
+    @tool_cn_name("更新视图成员配置")
     def view_update_member_config(self, *, profile: str, viewgraph_key: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         body = self._require_dict(payload)
         return self._request(
@@ -134,7 +170,9 @@ class ViewTools(ToolBase):
             risk_target="view member visibility",
         )
 
+    @tool_cn_name("更新视图数据配置")
     def view_update_apply_config(self, *, profile: str, viewgraph_key: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         body = self._require_dict(payload)
         return self._request(
@@ -147,7 +185,9 @@ class ViewTools(ToolBase):
             risk_target="view apply visibility",
         )
 
+    @tool_cn_name("看板泳道配置")
     def view_board_set_lane_config(self, *, profile: str, viewgraph_key: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         body = self._require_dict(payload)
         return self._request(
@@ -160,7 +200,9 @@ class ViewTools(ToolBase):
             risk_target="board lane configuration",
         )
 
+    @tool_cn_name("看板泳道基础信息")
     def view_board_get_lane_base_info(self, *, profile: str, viewgraph_key: str, page_num: int, page_size: int) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         return self._request(
             profile,
@@ -170,7 +212,9 @@ class ViewTools(ToolBase):
             params={"pageNum": page_num, "pageSize": page_size},
         )
 
+    @tool_cn_name("甘特图自动校准")
     def view_gantt_switch_auto_calibration(self, *, profile: str, viewgraph_key: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         body = self._require_dict(payload)
         return self._request(
@@ -183,7 +227,9 @@ class ViewTools(ToolBase):
             risk_target="gantt auto calibration settings",
         )
 
+    @tool_cn_name("甘特图批量更新时间")
     def view_gantt_batch_update_time(self, *, profile: str, viewgraph_key: str, payload: JSONObject) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         body = self._require_dict(payload)
         return self._request(
@@ -196,7 +242,9 @@ class ViewTools(ToolBase):
             risk_target="gantt task timing",
         )
 
+    @tool_cn_name("视图后续节点")
     def view_get_future_nodes(self, *, profile: str, viewgraph_key: str, apply_id: int, app_key: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         self._require_app_key(app_key)
         self._require_positive("apply_id", apply_id)
@@ -210,7 +258,9 @@ class ViewTools(ToolBase):
             params={"appKey": app_key},
         )
 
+    @tool_cn_name("视图流程状态")
     def view_get_workflow_status(self, *, profile: str, viewgraph_key: str, row_record_id: int) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_viewgraph_key(viewgraph_key)
         self._require_positive("row_record_id", row_record_id)
         return self._request(profile, "GET", f"/view/{viewgraph_key}/workflow/status/{row_record_id}", viewgraph_key=viewgraph_key, row_record_id=row_record_id)
@@ -227,6 +277,7 @@ class ViewTools(ToolBase):
         risk_target: str | None = None,
         **extra: JSONValue,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         def runner(session_profile, context):
             result = self.backend.request(method, context, path, json_body=json_body, params=params)
             response: JSONObject = {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
@@ -238,18 +289,22 @@ class ViewTools(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 _require_viewgraph_key(self, viewgraph_key: str) -> None:
+        """执行内部辅助逻辑。"""
         if not viewgraph_key:
             raise_tool_error(QingflowApiError.config_error("viewgraph_key is required"))
 
     def _require_positive(self, field_name: str, value: int) -> None:
+        """执行内部辅助逻辑。"""
         if value <= 0:
             raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
 
     def _normalize_reorder_payload(self, payload: list[JSONObject]) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         first_item = payload[0]
         if "ordinalType" in first_item and "viewKeyList" in first_item:
             return payload