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

package/src/qingflow_mcp/tools/repository_dev_tools.py

@@ -19,7 +19,7 @@ from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject, JSONValue
 from ..repository_store import RepositoryMetadataStore
 from ..session_store import SessionProfile
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 
 
 _STREAM_EVENT_RE = re.compile(r"^type=(?P<type>[^,]+),timestamp=(?P<timestamp>[^,]+),data=(?P<data>.*)$")
@@ -27,11 +27,23 @@ _STREAM_NEWLINE_TOKEN = "<wingsBr>"
 
 
 class RepositoryDevTools(ToolBase):
+    """仓库开发工具（中文名：仓库初始化与绑定）。
+
+    类型：开发辅助工具。
+    主要职责：
+    1. 初始化仓库开发元数据；
+    2. 维护仓库模板与分组映射；
+    3. 为 AI Builder 的仓库流程提供状态读写。
+    """
+
     def __init__(self, sessions, backend, *, metadata_store: RepositoryMetadataStore | None = None) -> None:
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
         self._metadata = metadata_store or RepositoryMetadataStore()
 
+    @tool_cn_name("仓库初始化")
     def repository_init(self, *, profile: str, group_name: str, repo_template: str) -> JSONObject:
+        """执行工具方法逻辑。"""
         normalized_group = str(group_name or "").strip()
         normalized_template = str(repo_template or "").strip()
         if not normalized_group:
@@ -69,6 +81,7 @@ class RepositoryDevTools(ToolBase):
 
         return self._run(profile, runner, require_workspace=True)
 
+    @tool_cn_name("仓库生成")
     def repository_generate(
         self,
         *,
@@ -87,6 +100,7 @@ class RepositoryDevTools(ToolBase):
         session_id: str | None = None,
         round_version: int | None = None,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         normalized_repo = str(repo_name or "").strip()
         normalized_query = str(query or "").strip()
         if not normalized_repo:
@@ -162,6 +176,7 @@ class RepositoryDevTools(ToolBase):
 
         return self._run(profile, runner, require_workspace=True)
 
+    @tool_cn_name("仓库发布生产")
     def repository_publish_prod(
         self,
         *,
@@ -169,6 +184,7 @@ class RepositoryDevTools(ToolBase):
         repo_name: str,
         confirm: bool = False,
     ) -> JSONObject:
+        """执行工具方法逻辑。"""
         normalized_repo = str(repo_name or "").strip()
         if not normalized_repo:
             raise_tool_error(QingflowApiError.config_error("repo_name is required"))
@@ -200,6 +216,7 @@ class RepositoryDevTools(ToolBase):
         return self._run(profile, runner, require_workspace=True)
 
     def _custom_page_route_warning(self) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
         if get_repository_internal_base_url() and get_repository_internal_share_token():
             return []
         return [
@@ -223,6 +240,7 @@ class RepositoryDevTools(ToolBase):
         params: JSONObject | None = None,
         json_body: JSONValue = None,
     ) -> JSONValue:
+        """执行内部辅助逻辑。"""
         internal_route = _resolve_internal_custom_page_route(session_profile)
         if internal_route is not None:
             return self.backend.public_request_with_headers(
@@ -246,6 +264,7 @@ class RepositoryDevTools(ToolBase):
         params: JSONObject | None = None,
         json_body: JSONValue = None,
     ) -> list[str]:
+        """执行内部辅助逻辑。"""
         internal_route = _resolve_internal_custom_page_route(session_profile)
         if internal_route is not None:
             return self.backend.public_stream_request(
@@ -302,7 +321,7 @@ def _resolve_internal_custom_page_route(session_profile: SessionProfile) -> dict
         )
     if session_profile.selected_ws_id is None:
         raise_tool_error(
-            QingflowApiError.config_error("workspace_select is required before using the internal custom-page route")
+            QingflowApiError.config_error("auth_use_credential must return a valid wsId before using the internal custom-page route")
         )
     return {
         "base_url": base_url,

package/src/qingflow_mcp/tools/resource_read_tools.py

@@ -8,17 +8,29 @@ from ..json_types import JSONObject
 from ..list_type_labels import SYSTEM_VIEW_DEFINITIONS
 from .app_tools import _analysis_supported_for_view_type
 from .app_tools import AppTools
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 from .qingbi_report_tools import QingbiReportTools
 
 
 class ResourceReadTools(ToolBase):
+    """资源读取工具（中文名：统一只读聚合）。
+
+    类型：只读聚合工具。
+    主要职责：
+    1. 聚合应用、视图、图表等读取能力；
+    2. 为上层流程提供统一资源读取入口；
+    3. 避免多工具重复初始化造成的调用复杂度。
+    """
+
     def __init__(self, sessions, backend) -> None:
+        """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
         self.apps = AppTools(sessions, backend)
         self.charts = QingbiReportTools(sessions, backend)
 
+    @tool_cn_name("资源读取-门户列表")
     def portal_list(self, *, profile: str) -> JSONObject:
+        """执行门户相关逻辑。"""
         def runner(session_profile, context):
             raw_items = self.backend.request("GET", context, "/dash")
             items = _normalize_portal_list_items(raw_items)
@@ -36,7 +48,9 @@ class ResourceReadTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("资源读取-门户详情")
     def portal_get(self, *, profile: str, dash_key: str) -> JSONObject:
+        """执行门户相关逻辑。"""
         self._require_dash_key(dash_key)
 
         def runner(session_profile, context):
@@ -71,7 +85,9 @@ class ResourceReadTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("资源读取-视图详情")
     def view_get(self, *, profile: str, view_id: str) -> JSONObject:
+        """执行视图相关逻辑。"""
         self._require_view_id(view_id)
         view_key = _extract_custom_view_key(view_id)
         system_view = _lookup_system_view_descriptor(view_id)
@@ -175,7 +191,9 @@ class ResourceReadTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("资源读取-报表详情")
     def chart_get(self, *, profile: str, chart_id: str) -> JSONObject:
+        """执行图表相关逻辑。"""
         self._require_chart_id(chart_id)
 
         def runner(session_profile, _context):
@@ -204,18 +222,22 @@ class ResourceReadTools(ToolBase):
         return self._run(profile, runner)
 
     def _require_dash_key(self, dash_key: str) -> None:
+        """执行内部辅助逻辑。"""
         if not dash_key:
             raise_tool_error(QingflowApiError.config_error("dash_key is required"))
 
     def _require_view_id(self, view_id: str) -> None:
+        """执行内部辅助逻辑。"""
         if not view_id:
             raise_tool_error(QingflowApiError.config_error("view_id is required"))
 
     def _require_chart_id(self, chart_id: str) -> None:
+        """执行内部辅助逻辑。"""
         if not chart_id:
             raise_tool_error(QingflowApiError.config_error("chart_id is required"))
 
     def _resolve_app_key_from_form_id(self, *, profile: str, form_id: int | None) -> str | None:
+        """执行内部辅助逻辑。"""
         if form_id is None:
             return None
         try:

package/src/qingflow_mcp/tools/role_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 RoleTools(ToolBase):
+    """角色工具（中文名：角色检索与创建）。
+
+    类型：组织权限工具。
+    主要职责：
+    1. 搜索角色并提供候选列表；
+    2. 创建角色并返回标准角色信息；
+    3. 服务流程节点与权限配置场景。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def role_search(
             profile: str = DEFAULT_PROFILE,
@@ -35,7 +45,9 @@ class RoleTools(ToolBase):
         def role_delete(profile: str = DEFAULT_PROFILE, role_ids: list[int] | None = None) -> JSONObject:
             return self.role_delete(profile=profile, role_ids=role_ids or [])
 
+    @tool_cn_name("角色搜索")
     def role_search(self, *, profile: str, keyword: str, page_num: int, page_size: int) -> JSONObject:
+        """执行角色相关逻辑。"""
         if page_num <= 0 or page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_num and page_size must be positive"))
 
@@ -55,7 +67,9 @@ class RoleTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("创建角色")
     def role_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
+        """执行角色相关逻辑。"""
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
@@ -64,7 +78,9 @@ class RoleTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("更新角色")
     def role_update(self, *, profile: str, role_id: int, payload: JSONObject) -> JSONObject:
+        """执行角色相关逻辑。"""
         if role_id <= 0:
             raise_tool_error(QingflowApiError.config_error("role_id must be positive"))
         body = self._require_dict(payload)
@@ -79,7 +95,9 @@ class RoleTools(ToolBase):
 
         return self._run(profile, runner)
 
+    @tool_cn_name("删除角色")
     def role_delete(self, *, profile: str, role_ids: list[int]) -> JSONObject:
+        """执行角色相关逻辑。"""
         if not role_ids or any(role_id <= 0 for role_id in role_ids):
             raise_tool_error(QingflowApiError.config_error("role_ids must be a non-empty array of positive integers"))
 

package/src/qingflow_mcp/tools/solution_tools.py

@@ -30,7 +30,7 @@ from ..solution.spec_models import (
     ViewsBuildSpec,
 )
 from .app_tools import AppTools
-from .base import ToolBase
+from .base import ToolBase, tool_cn_name
 from .navigation_tools import NavigationTools
 from .package_tools import PackageTools
 from .portal_tools import PortalTools
@@ -126,7 +126,17 @@ SOLUTION_SCHEMA_INTENT_ALIASES = {
 
 
 class SolutionTools(ToolBase):
+    """解决方案工具（中文名：方案会话与安装执行）。
+
+    类型：解决方案编排工具。
+    主要职责：
+    1. 管理设计会话与运行会话；
+    2. 安装与应用 SolutionSpec；
+    3. 输出安装结果、阶段状态与故障信息。
+    """
+
     def register(self, mcp: FastMCP) -> None:
+        """注册当前工具到 MCP 服务。"""
         @mcp.tool()
         def solution_design_session(
             action: str = "get",
@@ -347,6 +357,7 @@ class SolutionTools(ToolBase):
         def solution_build_status(build_id: str = "") -> dict[str, Any]:
             return self.solution_build_status(build_id=build_id)
 
+    @tool_cn_name("方案设计会话")
     def solution_design_session(
         self,
         *,
@@ -356,6 +367,7 @@ class SolutionTools(ToolBase):
         design_patch: dict[str, Any],
         metadata: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         try:
             if action == "start" and not session_id:
                 session_id = _generate_session_id(metadata=metadata, stage=stage)
@@ -416,6 +428,7 @@ class SolutionTools(ToolBase):
         except Exception as exc:  # noqa: BLE001
             return self._design_failure_response(session_id, action, "runtime", str(exc))
 
+    @tool_cn_name("方案启动搭建")
     def solution_bootstrap(
         self,
         *,
@@ -428,6 +441,7 @@ class SolutionTools(ToolBase):
         target: dict[str, Any],
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         if mode not in {"preflight", "plan", "apply", "repair"}:
             return self._failure_response(mode, idempotency_key, "config", "mode must be one of: preflight, plan, apply, repair")
@@ -515,6 +529,7 @@ class SolutionTools(ToolBase):
             return runner()
         return self._run(profile, lambda _session_profile, _context: runner())
 
+    @tool_cn_name("搭建应用流程")
     def solution_build_app_flow(
         self,
         *,
@@ -527,6 +542,7 @@ class SolutionTools(ToolBase):
         target: dict[str, Any],
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         return self._stage_build(
             profile=profile,
@@ -541,6 +557,7 @@ class SolutionTools(ToolBase):
             repair_patch=repair_patch,
         )
 
+    @tool_cn_name("搭建应用")
     def solution_build_app(
         self,
         *,
@@ -556,6 +573,7 @@ class SolutionTools(ToolBase):
         target: dict[str, Any],
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         resolved_app_spec = deepcopy(app_spec) if isinstance(app_spec, dict) else {}
         if not resolved_app_spec and build_id:
@@ -582,6 +600,7 @@ class SolutionTools(ToolBase):
             projection_name="app",
         )
 
+    @tool_cn_name("从需求搭建应用")
     def solution_build_app_from_requirements(
         self,
         *,
@@ -599,6 +618,7 @@ class SolutionTools(ToolBase):
         run_label: str | None,
         include_generated_spec: bool,
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         if mode in {"preflight", "plan"} and not build_id:
             build_id = _generate_build_id(run_label=run_label, stage_name="app")
@@ -703,6 +723,7 @@ class SolutionTools(ToolBase):
             include_generated_spec=include_generated_spec,
         )
 
+    @tool_cn_name("搭建流程")
     def solution_build_flow(
         self,
         *,
@@ -714,6 +735,7 @@ class SolutionTools(ToolBase):
         run_label: str | None,
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         return self._stage_build(
             profile=profile,
@@ -731,6 +753,7 @@ class SolutionTools(ToolBase):
             projection_name="flow",
         )
 
+    @tool_cn_name("一键搭建全部")
     def solution_build_all(
         self,
         *,
@@ -744,6 +767,7 @@ class SolutionTools(ToolBase):
         repair_patch: dict[str, Any],
         verify: bool,
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         if mode in {"preflight", "plan"} and not build_id:
             build_id = _generate_build_id(run_label=run_label, stage_name="all")
@@ -918,6 +942,7 @@ class SolutionTools(ToolBase):
             return runner()
         return self._run(profile, lambda _session_profile, _context: runner())
 
+    @tool_cn_name("搭建视图")
     def solution_build_views(
         self,
         *,
@@ -929,6 +954,7 @@ class SolutionTools(ToolBase):
         run_label: str | None,
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         return self._stage_build(
             profile=profile,
@@ -943,6 +969,7 @@ class SolutionTools(ToolBase):
             repair_patch=repair_patch,
         )
 
+    @tool_cn_name("方案 Schema 示例")
     def solution_schema_example(
         self,
         *,
@@ -951,6 +978,7 @@ class SolutionTools(ToolBase):
         include_examples: bool = False,
         include_selected_example: bool = False,
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         resolved_stage = _normalize_solution_schema_stage(stage)
         resolved_intent = _normalize_solution_schema_intent(intent)
         if resolved_stage is None:
@@ -991,6 +1019,7 @@ class SolutionTools(ToolBase):
         response["resolved_intent"] = resolved_intent
         return response
 
+    @tool_cn_name("搭建分析门户")
     def solution_build_analytics_portal(
         self,
         *,
@@ -1002,6 +1031,7 @@ class SolutionTools(ToolBase):
         run_label: str | None,
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         return self._stage_build(
             profile=profile,
@@ -1016,6 +1046,7 @@ class SolutionTools(ToolBase):
             repair_patch=repair_patch,
         )
 
+    @tool_cn_name("搭建导航")
     def solution_build_navigation(
         self,
         *,
@@ -1027,6 +1058,7 @@ class SolutionTools(ToolBase):
         run_label: str | None,
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         return self._stage_build(
             profile=profile,
@@ -1041,7 +1073,9 @@ class SolutionTools(ToolBase):
             repair_patch=repair_patch,
         )
 
+    @tool_cn_name("搭建状态")
     def solution_build_status(self, *, build_id: str) -> dict[str, Any]:
+        """执行方案相关逻辑。"""
         if not build_id:
             error_fields = _solution_error_fields(
                 category="config",
@@ -1077,6 +1111,7 @@ class SolutionTools(ToolBase):
         tool_name: str | None = None,
         projection_name: str | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         mode = _normalize_staged_build_mode(mode)
         public_stage_name = public_stage_name or stage_name
         tool_name = tool_name or STAGE_TOOL_NAMES.get(stage_name, "solution_build_app_flow")
@@ -1133,6 +1168,7 @@ class SolutionTools(ToolBase):
         tool_name: str,
         projection_name: str,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         try:
             resolved_stage_payload = self._resolve_stage_payload(
                 assembly=assembly,
@@ -1320,6 +1356,7 @@ class SolutionTools(ToolBase):
         stage_model: type[BaseModel],
         projection_name: str,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         existing_stage_payload = (assembly.data.get("stage_specs", {}) or {}).get(stage_name, {}) or {}
         base_payload: dict[str, Any] = {}
         if mode == "repair":
@@ -1357,6 +1394,7 @@ class SolutionTools(ToolBase):
         mode: str,
         repair_patch: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         base_payload = deepcopy(solution_spec)
         if mode == "repair" and repair_patch:
             base_payload = deep_merge(base_payload, repair_patch)
@@ -1364,6 +1402,7 @@ class SolutionTools(ToolBase):
         return parsed.model_dump(mode="json", exclude_unset=True)
 
     def _build_executor(self) -> SolutionExecutor:
+        """执行内部辅助逻辑。"""
         return SolutionExecutor(
             workspace_tools=WorkspaceTools(self.sessions, self.backend),
             package_tools=PackageTools(self.sessions, self.backend),
@@ -1385,6 +1424,7 @@ class SolutionTools(ToolBase):
         artifacts: dict[str, Any],
         solution_spec: dict[str, Any],
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         verification = {
             "build_id": build_id,
             "status": "success",
@@ -1507,6 +1547,7 @@ class SolutionTools(ToolBase):
         solution_spec: dict[str, Any],
         target: dict[str, Any],
     ) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         if public_stage_name != "app":
             return None
         app_tools = AppTools(self.sessions, self.backend)
@@ -1592,6 +1633,7 @@ class SolutionTools(ToolBase):
         return verification
 
     def _failure_response(self, mode: str, idempotency_key: str, category: str, detail: Any) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         error_fields = _solution_error_fields(
             category=category,
             detail=detail,
@@ -1624,6 +1666,7 @@ class SolutionTools(ToolBase):
         *,
         tool_name: str,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         error_fields = _solution_error_fields(
             category=category,
             detail=detail,
@@ -1662,6 +1705,7 @@ class SolutionTools(ToolBase):
         assembly: BuildAssemblyStore,
         tool_name: str,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         return {
             "build_id": build_id,
             "stage": stage_name,
@@ -1701,6 +1745,7 @@ class SolutionTools(ToolBase):
         tool_name: str,
         verification: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         response = {
             "build_id": build_id,
             "stage": stage_name,
@@ -1729,6 +1774,7 @@ class SolutionTools(ToolBase):
         return response
 
     def _design_failure_response(self, session_id: str, action: str, category: str, detail: Any) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         error_fields = _solution_error_fields(
             category=category,
             detail=detail,
@@ -1750,6 +1796,7 @@ class SolutionTools(ToolBase):
         }
 
     def _design_summary(self, store: DesignSessionStore) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         summary = store.summary()
         current_stage = summary["current_stage"]
         summary["next_stage"] = None if summary["status"] == "finalized" else current_stage
@@ -1758,6 +1805,7 @@ class SolutionTools(ToolBase):
         return summary
 
     def _all_failure_response(self, build_id: str, mode: str, category: str, detail: Any) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         error_fields = _solution_error_fields(
             category=category,
             detail=detail,
@@ -1780,6 +1828,7 @@ class SolutionTools(ToolBase):
         }
 
     def _load_generated_app_spec(self, build_id: str) -> dict[str, Any] | None:
+        """执行内部辅助逻辑。"""
         if not build_id:
             return None
         try:
@@ -1802,6 +1851,7 @@ class SolutionTools(ToolBase):
         requirement_text: str,
         layout_style: str,
     ) -> None:
+        """执行内部辅助逻辑。"""
         assembly = BuildAssemblyStore.open(build_id=build_id)
         builder_state = assembly.get_builder_state()
         generated_specs = builder_state.get("generated_specs", {})
@@ -1826,6 +1876,7 @@ class SolutionTools(ToolBase):
         stage_payload: dict[str, Any],
         errors: list[dict[str, Any]],
     ) -> tuple[str | None, int]:
+        """执行内部辅助逻辑。"""
         signature = _failure_signature_for_stage(stage_name=stage_name, stage_payload=stage_payload, errors=errors)
         if signature is None:
             return None, 0
@@ -1849,6 +1900,7 @@ class SolutionTools(ToolBase):
         package_tag_id: int,
         package_name: str,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         packages = PackageTools(self.sessions, self.backend)
         normalized_name = package_name.strip()
         if package_tag_id > 0:
@@ -1998,6 +2050,7 @@ class SolutionTools(ToolBase):
         package_resolution: dict[str, Any],
         update_only: bool,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         normalized_app_key = str(app_key or "").strip()
         if not normalized_app_key:
             if update_only:
@@ -2120,6 +2173,7 @@ class SolutionTools(ToolBase):
         invalid_field_types: list[str] | None = None,
         error_details: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         suggested_next_call = (
             {"tool_name": "solution_build_app", "arguments": {"mode": "plan", "build_id": build_id}}
             if build_id and self._load_generated_app_spec(build_id)
@@ -2185,6 +2239,7 @@ class SolutionTools(ToolBase):
         stage_result: dict[str, Any],
         include_generated_spec: bool,
     ) -> dict[str, Any]:
+        """执行内部辅助逻辑。"""
         next_call = stage_result.get("suggested_next_call")
         response = {
             "status": stage_result.get("status"),