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

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -40,7 +40,7 @@ from ..builder_facade.models import (
 )
 from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
 from .app_tools import AppTools
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 from .custom_button_tools import CustomButtonTools
 from .directory_tools import DirectoryTools
 from .package_tools import PackageTools
@@ -55,7 +55,17 @@ PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook",
 
 
 class AiBuilderTools(ToolBase):
+    """AI Builder 工具（中文名：AI 搭建编排）。
+
+    类型：应用搭建编排工具。
+    主要职责：
+    1. 编排 schema/layout/views/flow/charts 的计划与应用；
+    2. 聚合 builder 侧读写与校验能力；
+    3. 将复杂搭建流程收敛为可执行步骤。
+    """
+
     def __init__(self, sessions, backend) -> None:
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
         self._facade = AiBuilderFacade(
             apps=AppTools(sessions, backend),
@@ -71,6 +81,7 @@ class AiBuilderTools(ToolBase):
         )
 
     def register(self, mcp) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def builder_tool_contract(tool_name: str = "") -> JSONObject:
             return self.builder_tool_contract(tool_name=tool_name)
@@ -451,7 +462,9 @@ class AiBuilderTools(ToolBase):
                 expected_package_id=expected_package_id,
             )
 
+    @tool_cn_name("分组列表查询")
     def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
+        """执行分组与包相关逻辑。"""
         normalized_args = {"trial_status": trial_status}
         return _safe_tool_call(
             lambda: self._facade.package_list(profile=profile, trial_status=trial_status),
@@ -460,7 +473,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status}},
         )
 
+    @tool_cn_name("分组解析")
     def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         normalized_args = {"package_name": package_name}
         return _safe_tool_call(
             lambda: self._facade.package_resolve(profile=profile, package_name=package_name),
@@ -469,7 +484,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "package_resolve", "arguments": {"profile": profile, "package_name": package_name}},
         )
 
+    @tool_cn_name("搭建工具契约查询")
     def builder_tool_contract(self, *, tool_name: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         requested = str(tool_name or "").strip()
         public_tool_names = public_builder_contract_tool_names()
         if requested in _PRIVATE_BUILDER_TOOL_CONTRACTS:
@@ -519,6 +536,7 @@ class AiBuilderTools(ToolBase):
             "contract": contract,
         }
 
+    @tool_cn_name("分组创建")
     def package_create(
         self,
         *,
@@ -528,6 +546,7 @@ class AiBuilderTools(ToolBase):
         color: str | None = None,
         visibility: JSONObject | None = None,
     ) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         visibility_patch = None
         if visibility is not None:
             try:
@@ -562,7 +581,9 @@ class AiBuilderTools(ToolBase):
             },
         )
 
+    @tool_cn_name("分组详情查询")
     def package_get(self, *, profile: str, package_id: int | None = None) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         normalized_args = {"package_id": package_id}
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.package_get(profile=profile, package_id=package_id),
@@ -571,6 +592,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
         ))
 
+    @tool_cn_name("分组配置应用")
     def package_apply(
         self,
         *,
@@ -584,6 +606,7 @@ class AiBuilderTools(ToolBase):
         items: list[dict] | None = None,
         allow_detach: bool = False,
     ) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         visibility_patch = None
         if visibility is not None:
             try:
@@ -617,6 +640,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "package_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    @tool_cn_name("分组更新")
     def package_update(
         self,
         *,
@@ -627,6 +651,7 @@ class AiBuilderTools(ToolBase):
         color: str | None = None,
         visibility: JSONObject | None = None,
     ) -> JSONObject:
+        """执行分组与包相关逻辑。"""
         visibility_patch = None
         if visibility is not None:
             try:
@@ -654,6 +679,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "package_update", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("方案安装")
     def solution_install(
         self,
         *,
@@ -662,6 +688,7 @@ class AiBuilderTools(ToolBase):
         being_copy_data: bool = True,
         solution_source: str = "solutionDetail",
     ) -> JSONObject:
+        """执行方案相关逻辑。"""
         normalized_args = {
             "solution_key": solution_key,
             "being_copy_data": being_copy_data,
@@ -679,6 +706,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "solution_install", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("成员检索")
     def member_search(
         self,
         *,
@@ -688,6 +716,7 @@ class AiBuilderTools(ToolBase):
         page_size: int = 20,
         contain_disable: bool = False,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         normalized_args = {
             "query": query,
             "page_num": page_num,
@@ -707,7 +736,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "member_search", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("角色检索")
     def role_search(self, *, profile: str, keyword: str, page_num: int = 1, page_size: int = 20) -> JSONObject:
+        """执行角色相关逻辑。"""
         normalized_args = {"keyword": keyword, "page_num": page_num, "page_size": page_size}
         return _safe_tool_call(
             lambda: self._facade.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size),
@@ -716,6 +747,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("角色创建")
     def role_create(
         self,
         *,
@@ -726,6 +758,7 @@ class AiBuilderTools(ToolBase):
         member_names: list[str],
         role_icon: str = "ex-user-outlined",
     ) -> JSONObject:
+        """执行角色相关逻辑。"""
         normalized_args = {
             "role_name": role_name,
             "member_uids": member_uids,
@@ -747,7 +780,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "role_create", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("分组挂载应用")
     def package_attach_app(self, *, profile: str, tag_id: int, app_key: str, app_title: str = "") -> JSONObject:
+        """执行分组与包相关逻辑。"""
         normalized_args = {"tag_id": tag_id, "app_key": app_key, "app_title": app_title}
         result = _safe_tool_call(
             lambda: self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title),
@@ -766,6 +801,7 @@ class AiBuilderTools(ToolBase):
             ),
         )
 
+    @tool_cn_name("释放应用编辑锁")
     def app_release_edit_lock_if_mine(
         self,
         *,
@@ -774,6 +810,7 @@ class AiBuilderTools(ToolBase):
         lock_owner_email: str = "",
         lock_owner_name: str = "",
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {
             "app_key": app_key,
             "lock_owner_email": lock_owner_email,
@@ -791,6 +828,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用解析")
     def app_resolve(
         self,
         *,
@@ -799,6 +837,7 @@ class AiBuilderTools(ToolBase):
         app_name: str = "",
         package_id: int | None = None,
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key, "app_name": app_name, "package_id": package_id}
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_resolve(profile=profile, app_key=app_key, app_name=app_name, package_tag_id=package_id),
@@ -807,7 +846,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_resolve", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    @tool_cn_name("应用按钮列表")
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_custom_button_list(profile=profile, app_key=app_key),
@@ -816,7 +857,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_custom_button_list", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用按钮详情")
     def app_custom_button_get(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key, "button_id": button_id}
         return _safe_tool_call(
             lambda: self._facade.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id),
@@ -825,7 +868,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_custom_button_get", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用按钮创建")
     def app_custom_button_create(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         try:
             request = CustomButtonPatch.model_validate(payload)
         except ValidationError as exc:
@@ -857,7 +902,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_custom_button_create", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用按钮更新")
     def app_custom_button_update(self, *, profile: str, app_key: str, button_id: int, payload: JSONObject) -> JSONObject:
+        """执行应用相关逻辑。"""
         try:
             request = CustomButtonPatch.model_validate(payload)
         except ValidationError as exc:
@@ -890,7 +937,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_custom_button_update", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用按钮删除")
     def app_custom_button_delete(self, *, profile: str, app_key: str, button_id: int) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key, "button_id": button_id}
         return _safe_tool_call(
             lambda: self._facade.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id),
@@ -899,7 +948,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_custom_button_delete", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用摘要读取")
     def app_read_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_read_summary(profile=profile, app_key=app_key),
@@ -908,7 +959,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
         ))
 
+    @tool_cn_name("应用详情查询")
     def app_get(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_get(profile=profile, app_key=app_key),
@@ -917,7 +970,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
         ))
 
+    @tool_cn_name("应用字段摘要读取")
     def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_read_fields(profile=profile, app_key=app_key),
@@ -926,7 +981,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用字段详情查询")
     def app_get_fields(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_fields(profile=profile, app_key=app_key),
@@ -935,6 +992,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("修复代码块字段")
     def app_repair_code_blocks(
         self,
         *,
@@ -943,6 +1001,7 @@ class AiBuilderTools(ToolBase):
         field: str | None = None,
         apply: bool = False,
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key, "field": field, "apply": apply}
         return _safe_tool_call(
             lambda: self._facade.app_repair_code_blocks(profile=profile, app_key=app_key, field=field, apply=apply),
@@ -951,7 +1010,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_repair_code_blocks", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用布局摘要读取")
     def app_read_layout_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_read_layout_summary(profile=profile, app_key=app_key),
@@ -960,7 +1021,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_layout", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用布局详情查询")
     def app_get_layout(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_layout(profile=profile, app_key=app_key),
@@ -969,7 +1032,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_layout", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用视图摘要读取")
     def app_read_views_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_read_views_summary(profile=profile, app_key=app_key),
@@ -978,7 +1043,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用视图详情查询")
     def app_get_views(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_views(profile=profile, app_key=app_key),
@@ -987,7 +1054,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用流程摘要读取")
     def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
@@ -996,7 +1065,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用流程详情查询")
     def app_get_flow(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_flow(profile=profile, app_key=app_key),
@@ -1005,7 +1076,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用图表摘要读取")
     def app_read_charts_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_read_charts_summary(profile=profile, app_key=app_key),
@@ -1014,7 +1087,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_charts", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("应用图表详情查询")
     def app_get_charts(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_charts(profile=profile, app_key=app_key),
@@ -1023,7 +1098,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_charts", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
+    @tool_cn_name("门户列表查询")
     def portal_list(self, *, profile: str) -> JSONObject:
+        """执行门户相关逻辑。"""
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_list(profile=profile),
             error_code="PORTAL_LIST_FAILED",
@@ -1031,7 +1108,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "portal_list", "arguments": {"profile": profile}},
         ))
 
+    @tool_cn_name("门户详情查询")
     def portal_get(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
+        """执行门户相关逻辑。"""
         normalized_args = {"dash_key": dash_key, "being_draft": being_draft}
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft),
@@ -1040,7 +1119,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    @tool_cn_name("门户摘要读取")
     def portal_read_summary(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
+        """执行门户相关逻辑。"""
         normalized_args = {"dash_key": dash_key, "being_draft": being_draft}
         return _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_read_summary(profile=profile, dash_key=dash_key, being_draft=being_draft),
@@ -1049,7 +1130,9 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    @tool_cn_name("视图详情查询")
     def view_get(self, *, profile: str, view_key: str = "", viewgraph_key: str = "") -> JSONObject:
+        """执行视图相关逻辑。"""
         resolved_view_key = str(view_key or viewgraph_key or "").strip()
         normalized_args = {"view_key": resolved_view_key}
         return _safe_tool_call(
@@ -1059,12 +1142,14 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("图表详情查询")
     def chart_get(
         self,
         *,
         profile: str,
         chart_id: str,
     ) -> JSONObject:
+        """执行图表相关逻辑。"""
         normalized_args = {"chart_id": chart_id}
         return _safe_tool_call(
             lambda: self._facade.chart_get(profile=profile, chart_id=chart_id),
@@ -1073,6 +1158,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "chart_get", "arguments": {"profile": profile, "chart_id": chart_id}},
         )
 
+    @tool_cn_name("应用结构规划")
     def app_schema_plan(
         self,
         *,
@@ -1088,6 +1174,7 @@ class AiBuilderTools(ToolBase):
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         try:
             request = SchemaPlanRequest.model_validate(
                 {
@@ -1133,6 +1220,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_schema_plan", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    @tool_cn_name("应用布局规划")
     def app_layout_plan(
         self,
         *,
@@ -1142,6 +1230,7 @@ class AiBuilderTools(ToolBase):
         sections: list[JSONObject] | None = None,
         preset: str | None = None,
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         try:
             request = LayoutPlanRequest.model_validate(
                 {
@@ -1179,6 +1268,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_request}},
         )
 
+    @tool_cn_name("应用流程规划")
     def app_flow_plan(
         self,
         *,
@@ -1189,6 +1279,7 @@ class AiBuilderTools(ToolBase):
         transitions: list[JSONObject] | None = None,
         preset: str | None = None,
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         try:
             request = FlowPlanRequest.model_validate(
                 {
@@ -1223,6 +1314,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
         )
 
+    @tool_cn_name("应用视图规划")
     def app_views_plan(
         self,
         *,
@@ -1232,6 +1324,7 @@ class AiBuilderTools(ToolBase):
         remove_views: list[str] | None = None,
         preset: str | None = None,
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         try:
             request = ViewsPlanRequest.model_validate(
                 {
@@ -1264,6 +1357,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_views_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
         )
 
+    @tool_cn_name("应用结构应用")
     def app_schema_apply(
         self,
         *,
@@ -1281,6 +1375,7 @@ class AiBuilderTools(ToolBase):
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         result = self._app_schema_apply_once(
             profile=profile,
             app_key=app_key,
@@ -1333,6 +1428,7 @@ class AiBuilderTools(ToolBase):
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         effective_app_name = app_name or app_title
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_schema_plan(
@@ -1419,7 +1515,9 @@ class AiBuilderTools(ToolBase):
         )
         return _publicize_package_fields(result)
 
+    @tool_cn_name("应用布局应用")
     def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
+        """执行应用相关逻辑。"""
         result = self._app_layout_apply_once(
             profile=profile,
             app_key=app_key,
@@ -1440,6 +1538,7 @@ class AiBuilderTools(ToolBase):
         )
 
     def _app_layout_apply_once(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
+        """执行内部辅助逻辑。"""
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_layout_plan(
                 profile=profile,
@@ -1496,6 +1595,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_layout_apply", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用流程应用")
     def app_flow_apply(
         self,
         *,
@@ -1506,6 +1606,7 @@ class AiBuilderTools(ToolBase):
         nodes: list[JSONObject],
         transitions: list[JSONObject],
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         result = self._app_flow_apply_once(
             profile=profile,
             app_key=app_key,
@@ -1537,6 +1638,7 @@ class AiBuilderTools(ToolBase):
         nodes: list[JSONObject],
         transitions: list[JSONObject],
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_flow_plan(
                 profile=profile,
@@ -1604,6 +1706,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("应用视图应用")
     def app_views_apply(
         self,
         *,
@@ -1613,6 +1716,7 @@ class AiBuilderTools(ToolBase):
         upsert_views: list[JSONObject],
         remove_views: list[str],
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         result = self._app_views_apply_once(
             profile=profile,
             app_key=app_key,
@@ -1641,6 +1745,7 @@ class AiBuilderTools(ToolBase):
         upsert_views: list[JSONObject],
         remove_views: list[str],
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_views_plan(
                 profile=profile,
@@ -1696,6 +1801,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("图表配置应用")
     def chart_apply(
         self,
         *,
@@ -1705,6 +1811,7 @@ class AiBuilderTools(ToolBase):
         remove_chart_ids: list[str],
         reorder_chart_ids: list[str],
     ) -> JSONObject:
+        """执行图表相关逻辑。"""
         return self.app_charts_apply(
             profile=profile,
             app_key=app_key,
@@ -1713,6 +1820,7 @@ class AiBuilderTools(ToolBase):
             reorder_chart_ids=reorder_chart_ids,
         )
 
+    @tool_cn_name("应用图表应用")
     def app_charts_apply(
         self,
         *,
@@ -1722,6 +1830,7 @@ class AiBuilderTools(ToolBase):
         remove_chart_ids: list[str],
         reorder_chart_ids: list[str],
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         try:
             request = ChartApplyRequest.model_validate(
                 {
@@ -1755,6 +1864,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_charts_apply", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    @tool_cn_name("门户配置应用")
     def portal_apply(
         self,
         *,
@@ -1772,6 +1882,7 @@ class AiBuilderTools(ToolBase):
         dash_global_config: JSONObject | None = None,
         config: JSONObject | None = None,
     ) -> JSONObject:
+        """执行门户相关逻辑。"""
         try:
             request = PortalApplyRequest.model_validate(
                 {
@@ -1820,6 +1931,7 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
 
+    @tool_cn_name("应用发布校验")
     def app_publish_verify(
         self,
         *,
@@ -1827,6 +1939,7 @@ class AiBuilderTools(ToolBase):
         app_key: str,
         expected_package_id: int | None = None,
     ) -> JSONObject:
+        """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key, "expected_package_id": expected_package_id}
         result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_id),
@@ -1845,6 +1958,7 @@ class AiBuilderTools(ToolBase):
         ))
 
     def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if not isinstance(result, dict) or result.get("status") != "failed" or result.get("error_code") != "APP_EDIT_LOCKED":
             return result
         suggested = result.get("suggested_next_call")
@@ -1910,6 +2024,7 @@ class AiBuilderTools(ToolBase):
         plan_tool_name: str,
         apply_tool_name: str,
     ) -> JSONObject:
+        """执行内部辅助逻辑。"""
         if not isinstance(result, dict):
             return result
         rewritten = dict(result)
@@ -2616,6 +2731,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.autoTrigger": "field.auto_trigger",
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
+            "field.subfieldUpdates": "field.subfield_updates",
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],