@josephyan/qingflow-app-user-mcp 0.2.0-beta.46 → 0.2.0-beta.48

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.46
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.48
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.46 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.48 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.46",
+  "version": "0.2.0-beta.48",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b46"
+version = "0.2.0b48"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-user/SKILL.md

@@ -32,7 +32,7 @@ Route to exactly one of these specialized paths:
 
 - If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
 - If the app is known but the available data range is unclear, call `app_get` first and inspect `accessible_views`
-- If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, member/department-field candidate lookup, import templates, import capability discovery, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-crud`
+- If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, member/department-field candidate lookup, code-block field execution, import templates, import capability discovery, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-crud`
 - If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`
 - If the MCP is not connected, authenticated, or bound to the right workspace, switch to `$qingflow-mcp-setup`

package/skills/qingflow-record-crud/SKILL.md

@@ -19,7 +19,8 @@ Use exactly one of these default paths:
 1. Browse records: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list`
 2. Read one record: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_get`
 3. Write records: `record_schema_get(schema_mode="applicant") -> record_write`
-4. Import records: `record_import_template_get -> record_import_verify -> (optional authorized file repair) -> record_import_start -> record_import_status_get`
+4. Run a code-block field: `record_schema_get(schema_mode="applicant") -> record_code_block_run`
+5. Import records: `record_import_template_get -> record_import_verify -> (optional authorized file repair) -> record_import_start -> record_import_status_get`
 
 ## Core Tools
 
@@ -27,6 +28,7 @@ Use exactly one of these default paths:
 - `record_list`
 - `record_get`
 - `record_write`
+- `record_code_block_run`
 - `record_import_template_get`
 - `record_import_verify`
 - `record_import_repair_local`
@@ -63,11 +65,12 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 6. Run `record_schema_get(schema_mode="browse", view_id=...)` before browse/read
 7. Run `record_schema_get(schema_mode="applicant")` before write
 8. If the request is import-like, decide whether the user needs template download, file verification, file repair, import execution, or import status before changing any file
-9. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
-10. If the request is write-like, decide `insert / update / delete` before building any payload
-11. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
-12. For high-risk writes or production changes, read the current state first whenever practical
-13. After actions, report the affected `record_id`, counts, or returned item count
+9. If the request is code-block-like, inspect applicant schema first and confirm the exact `code_block_field`
+10. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+11. If the request is write-like, decide `insert / update / delete` before building any payload
+12. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
+13. For high-risk writes or production changes, read the current state first whenever practical
+14. After actions, report the affected `record_id`, counts, or returned item count
 
 ## Record Read Rules
 
@@ -131,6 +134,35 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - `relation`: `✅ {"field_id":25,"value":{"apply_id":5001}}` / `❌ {"field_id":25,"value":"客户A"}`
 - `attachment`: upload first, then `✅ {"field_id":13,"value":{"value":"https://.../a.pdf","name":"a.pdf"}}` / `❌ {"field_id":13,"value":"/tmp/a.pdf"}`
 
+## Code Block Rules
+
+Use `record_code_block_run` when the user wants to run a form code-block field against an existing record and optionally let Qingflow auto-write bound relation outputs back into the same record.
+
+### Code block workflow
+
+1. Run `record_schema_get(schema_mode="applicant")`
+2. Select the exact code-block field from schema
+3. Confirm the target `record_id`
+4. Choose the right execution context:
+   - default record context: `role=1`
+   - workflow task context: pass `role=3` and `workflow_node_id`
+5. Run `record_code_block_run`
+6. Check:
+   - `outputs.alias_results`
+   - `relation.target_fields`
+   - `writeback.applied`
+   - `writeback.verification`
+
+### Code block discipline
+
+- `code_block_field` must resolve to a real code-block field; do not guess by approximate title
+- Prefer the current stored record answers as inputs
+- Only pass temporary `answers` or `fields` overrides when the user explicitly wants a what-if execution or the current record data is known to be incomplete
+- Treat this tool as a write-capable operation, not a pure read
+- If the code block is bound to relation outputs, MCP will trigger Qingflow's relation-calculation chain and may auto-write calculated answers back to the record
+- If `verify_writeback=true`, read `writeback.write_verified` and `writeback.verification` before claiming success
+- In workflow context, `workflow_node_id` is required when `role=3`
+
 ## Import Rules
 
 Use the import tools for file-based bulk data loading, not `record_write`.

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b46"
+__version__ = "0.2.0b48"

package/src/qingflow_mcp/builder_facade/service.py

@@ -1250,7 +1250,7 @@ class AiBuilderFacade:
             if app_result.get("status") != "success":
                 return app_result
             resolved_app_key = str(app_result.get("app_key") or app_key)
-            items = self.charts.qingbi_report_list(profile=profile, app_key=resolved_app_key).get("items") or []
+            items, list_source = self._load_chart_list_for_builder(profile=profile, app_key=resolved_app_key)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             return _failed_from_api_error(
@@ -1278,12 +1278,22 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None,
             "noop": False,
-            "warnings": [],
-            "verification": {"app_exists": True},
+            "warnings": [] if list_source == "sorted" else [_warning("CHART_ORDER_UNVERIFIED", "chart summary order uses fallback listing and may not reflect saved chart sort order")],
+            "verification": {"app_exists": True, "chart_order_verified": list_source == "sorted", "chart_list_source": list_source},
             "verified": True,
             **response.model_dump(mode="json"),
         }
 
+    def _load_chart_list_for_builder(self, *, profile: str, app_key: str) -> tuple[list[dict[str, Any]], str]:
+        try:
+            sorted_items = self.charts.qingbi_report_list_sorted(profile=profile, app_key=app_key, page_num=1, page_size=500).get("items") or []
+            if isinstance(sorted_items, list):
+                return sorted_items, "sorted"
+        except (QingflowApiError, RuntimeError):
+            pass
+        fallback_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
+        return list(fallback_items) if isinstance(fallback_items, list) else [], "fallback"
+
     def portal_read_summary(self, *, profile: str, dash_key: str, being_draft: bool = True) -> JSONObject:
         try:
             result = self.portals.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft).get("result") or {}
@@ -3231,7 +3241,7 @@ class AiBuilderFacade:
             parsed = schema_state.get("parsed") if isinstance(schema_state.get("parsed"), dict) else {}
             fields = parsed.get("fields") if isinstance(parsed.get("fields"), list) else []
             qingbi_fields = self.charts.qingbi_report_list_fields(profile=profile, app_key=app_key).get("items") or []
-            existing_chart_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
+            existing_chart_items, existing_chart_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
         except (QingflowApiError, RuntimeError) as error:
             api_error = _coerce_api_error(error)
             return _failed_from_api_error(
@@ -3305,7 +3315,7 @@ class AiBuilderFacade:
                     create_result = self.charts.qingbi_report_create(profile=profile, payload=create_payload).get("result") or {}
                     created_chart_id = _extract_chart_identifier(create_result or {})
                     if not created_chart_id:
-                        refreshed_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
+                        refreshed_items, _ = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
                         refreshed_matches = _find_charts_by_name(
                             refreshed_items,
                             chart_name=patch.name,
@@ -3331,10 +3341,23 @@ class AiBuilderFacade:
                     existing_by_id[chart_id] = deepcopy(created_chart)
                     existing_by_name.setdefault(patch.name, []).append(deepcopy(created_chart))
                 elif existing_name != patch.name or existing_type != target_type:
+                    base_info = self.charts.qingbi_report_get_base(profile=profile, chart_id=chart_id).get("result") or {}
                     self.charts.qingbi_report_update_base(
                         profile=profile,
                         chart_id=chart_id,
-                        payload={"chartName": patch.name, "chartType": target_type},
+                        payload={
+                            "chartId": chart_id,
+                            "chartName": patch.name,
+                            "chartType": target_type,
+                            "dataSourceType": base_info.get("dataSourceType") or (existing or {}).get("dataSourceType") or "qingflow",
+                            "tagId": "0",
+                            "parentId": "0",
+                            "dataSourceId": base_info.get("dataSourceId") or app_key,
+                            "visibleAuth": deepcopy(base_info.get("visibleAuth") or qingbi_workspace_visible_auth()),
+                            "editAuthList": deepcopy(base_info.get("editAuthList") or []),
+                            "editAuthType": base_info.get("editAuthType") or "ws",
+                            "editAuthIncludeSubDept": bool(base_info.get("editAuthIncludeSubDept", True)),
+                        },
                     )
                     updated_ids.append(chart_id)
                     updated_chart = deepcopy(existing or {})
@@ -3417,7 +3440,14 @@ class AiBuilderFacade:
         reordered = False
         if request.reorder_chart_ids:
             try:
-                self.charts.qingbi_report_reorder(profile=profile, app_key=app_key, chart_ids=request.reorder_chart_ids)
+                current_order = [
+                    _extract_chart_identifier(item)
+                    for item in existing_chart_items
+                    if isinstance(item, dict) and _extract_chart_identifier(item)
+                ]
+                desired_display_order = list(request.reorder_chart_ids) + [chart_id for chart_id in current_order if chart_id not in request.reorder_chart_ids]
+                backend_reorder_ids = list(reversed(desired_display_order))
+                self.charts.qingbi_report_reorder(profile=profile, app_key=app_key, chart_ids=backend_reorder_ids)
                 reordered = True
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
@@ -3434,7 +3464,7 @@ class AiBuilderFacade:
 
         noop = not created_ids and not updated_ids and not removed_ids and not reordered and not failed_items
         try:
-            readback_items = self.charts.qingbi_report_list(profile=profile, app_key=app_key).get("items") or []
+            readback_items, readback_list_source = self._load_chart_list_for_builder(profile=profile, app_key=app_key)
             readback_ids = {
                 _extract_chart_identifier(item)
                 for item in readback_items
@@ -3451,11 +3481,12 @@ class AiBuilderFacade:
                     if isinstance(item, dict) and _extract_chart_identifier(item)
                 ]
                 requested_existing = [chart_id for chart_id in request.reorder_chart_ids if chart_id in ordered_readback]
-                verified = verified and ordered_readback[: len(requested_existing)] == requested_existing
+                verified = verified and readback_list_source == "sorted" and ordered_readback[: len(requested_existing)] == requested_existing
             readback_unavailable = False
         except (QingflowApiError, RuntimeError):
             verified = False
             readback_unavailable = True
+            readback_list_source = None
 
         if failed_items:
             successful_changes = bool(created_ids or updated_ids or removed_ids or reordered)
@@ -3478,7 +3509,12 @@ class AiBuilderFacade:
                     readback_unavailable=readback_unavailable,
                     verified=False if failed_items else verified,
                 ),
-                "verification": {"charts_verified": False if failed_items else verified, "readback_unavailable": readback_unavailable},
+                "verification": {
+                    "charts_verified": False if failed_items else verified,
+                    "readback_unavailable": readback_unavailable,
+                    "chart_order_verified": False if request.reorder_chart_ids else (readback_list_source == "sorted"),
+                    "chart_list_source": readback_list_source or existing_chart_list_source,
+                },
                 "app_key": app_key,
                 "chart_results": chart_results,
                 "verified": False if failed_items else verified,
@@ -3501,7 +3537,12 @@ class AiBuilderFacade:
                 readback_unavailable=False if noop else readback_unavailable,
                 verified=result_verified,
             ),
-            "verification": {"charts_verified": result_verified, "readback_unavailable": False if noop else readback_unavailable},
+            "verification": {
+                "charts_verified": result_verified,
+                "readback_unavailable": False if noop else readback_unavailable,
+                "chart_order_verified": True if noop and not request.reorder_chart_ids else (readback_list_source == "sorted" and result_verified if request.reorder_chart_ids else readback_list_source == "sorted"),
+                "chart_list_source": existing_chart_list_source if noop else readback_list_source,
+            },
             "app_key": app_key,
             "chart_results": chart_results,
             "verified": result_verified,

package/src/qingflow_mcp/server.py

@@ -8,6 +8,7 @@ from .backend_client import BackendClient
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
+from .tools.code_block_tools import CodeBlockTools
 from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
@@ -16,7 +17,6 @@ from .tools.navigation_tools import NavigationTools
 from .tools.directory_tools import DirectoryTools
 from .tools.portal_tools import PortalTools
 from .tools.qingbi_report_tools import QingbiReportTools
-from .tools.record_tools import RecordTools
 from .tools.role_tools import RoleTools
 from .tools.solution_tools import SolutionTools
 from .tools.task_context_tools import TaskContextTools
@@ -95,6 +95,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list / record_get`
 `record_schema_get(schema_mode="applicant") -> record_write`
+`record_schema_get(schema_mode="applicant") -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
 - Use `where` items as `{{field_id, op, value}}`
@@ -111,6 +112,16 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Code Block Path
+
+Use `record_code_block_run` when the user wants to execute a form code-block field against an existing record.
+
+- Always resolve the exact code-block field from `record_schema_get(schema_mode="applicant")` first.
+- Treat code-block execution as write-capable, not read-only.
+- If the code block is bound to relation outputs, Qingflow may calculate target answers and write them back automatically.
+- In workflow context, pass `role=3` and the exact `workflow_node_id`.
+- After execution, inspect `outputs.alias_results`, `relation.target_fields`, and `writeback.verification` before claiming success.
+
 ## Import Path
 
 `app_get -> record_import_template_get -> record_import_verify -> (optional authorized record_import_repair_local) -> record_import_start -> record_import_status_get`
@@ -161,7 +172,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)
     ImportTools(sessions, backend).register(server)
-    RecordTools(sessions, backend).register(server)
+    CodeBlockTools(sessions, backend).register(server)
     TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)
     AppTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_user.py

@@ -9,11 +9,11 @@ from .config import DEFAULT_PROFILE
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
 from .tools.auth_tools import AuthTools
+from .tools.code_block_tools import CodeBlockTools
 from .tools.directory_tools import DirectoryTools
 from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
-from .tools.record_tools import RecordTools
 from .tools.task_context_tools import TaskContextTools
 from .tools.workspace_tools import WorkspaceTools
 
@@ -83,6 +83,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list / record_get`
 `record_schema_get(schema_mode="applicant") -> record_write`
+`record_schema_get(schema_mode="applicant") -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
 - Use `where` items as `{{field_id, op, value}}`
@@ -99,6 +100,16 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
 - For default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
+## Code Block Path
+
+Use `record_code_block_run` when the user wants to execute a form code-block field against an existing record.
+
+- Always resolve the exact code-block field from `record_schema_get(schema_mode="applicant")` first.
+- Treat code-block execution as write-capable, not read-only.
+- If the code block is bound to relation outputs, Qingflow may calculate target answers and write them back automatically.
+- In workflow context, pass `role=3` and the exact `workflow_node_id`.
+- After execution, inspect `outputs.alias_results`, `relation.target_fields`, and `writeback.verification` before claiming success.
+
 ## Import Path
 
 `app_get -> record_import_template_get -> record_import_verify -> (optional authorized record_import_repair_local) -> record_import_start -> record_import_status_get`
@@ -274,7 +285,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     imports.register(server)
 
     feedback.register(server)
-    RecordTools(sessions, backend).register(server)
+    CodeBlockTools(sessions, backend).register(server)
     TaskContextTools(sessions, backend).register(server)
     DirectoryTools(sessions, backend).register(server)
 

package/src/qingflow_mcp/tools/code_block_tools.py

@@ -0,0 +1,584 @@
+from __future__ import annotations
+
+from typing import cast
+
+from mcp.server.fastmcp import FastMCP
+
+from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject, JSONValue
+from .record_tools import (
+    ATTACHMENT_QUE_TYPES,
+    DEPARTMENT_QUE_TYPES,
+    MEMBER_QUE_TYPES,
+    MULTI_SELECT_QUE_TYPES,
+    RELATION_QUE_TYPES,
+    SINGLE_SELECT_QUE_TYPES,
+    SUBTABLE_QUE_TYPES,
+    FieldIndex,
+    FormField,
+    RecordTools,
+    _coerce_count,
+    _collect_question_relations,
+    _field_ref_payload,
+    _normalize_optional_text,
+    _relation_ids_from_answer,
+    _stringify_json,
+)
+
+
+CODE_BLOCK_QUE_TYPE = 26
+CODE_BLOCK_RELATION_TYPE = 3
+SUPPORTED_CODE_BLOCK_ROLES = {1, 2, 3, 5}
+
+
+class CodeBlockTools(RecordTools):
+    def register(self, mcp: FastMCP) -> None:
+        super().register(mcp)
+
+        @mcp.tool(
+            description=(
+                "Run a form code-block field against the current record data, then reuse Qingflow's existing "
+                "relation-calculation chain to compute bound outputs and write them back automatically. "
+                "Use an exact code-block field selector from the form schema."
+            )
+        )
+        def record_code_block_run(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            record_id: int = 0,
+            code_block_field: str = "",
+            role: int = 1,
+            workflow_node_id: int | None = None,
+            answers: list[JSONObject] | None = None,
+            fields: JSONObject | None = None,
+            manual: bool = True,
+            verify_writeback: bool = True,
+            force_refresh_form: bool = False,
+            output_profile: str = "normal",
+        ) -> JSONObject:
+            return self.record_code_block_run(
+                profile=profile,
+                app_key=app_key,
+                record_id=record_id,
+                code_block_field=code_block_field,
+                role=role,
+                workflow_node_id=workflow_node_id,
+                answers=answers or [],
+                fields=fields or {},
+                manual=manual,
+                verify_writeback=verify_writeback,
+                force_refresh_form=force_refresh_form,
+                output_profile=output_profile,
+            )
+
+    def record_code_block_run(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        code_block_field: str,
+        role: int = 1,
+        workflow_node_id: int | None = None,
+        answers: list[JSONObject] | None = None,
+        fields: JSONObject | None = None,
+        manual: bool = True,
+        verify_writeback: bool = True,
+        force_refresh_form: bool = False,
+        output_profile: str = "normal",
+    ) -> JSONObject:
+        normalized_record_id = self._validate_app_and_record(app_key, record_id)
+        normalized_output_profile = self._normalize_public_output_profile(output_profile)
+        if role not in SUPPORTED_CODE_BLOCK_ROLES:
+            raise_tool_error(QingflowApiError.config_error("role must be one of 1, 2, 3, or 5"))
+        if role == 3 and (workflow_node_id is None or workflow_node_id <= 0):
+            raise_tool_error(QingflowApiError.config_error("workflow_node_id is required when role=3"))
+        if not code_block_field:
+            raise_tool_error(QingflowApiError.config_error("code_block_field is required"))
+
+        def runner(session_profile, context):
+            schema = self._get_form_schema(profile, context, app_key, force_refresh=force_refresh_form)
+            index = self._get_field_index(profile, context, app_key, force_refresh=force_refresh_form)
+            code_block = self._resolve_field_selector(code_block_field, index, location="code_block_field")
+            if code_block.que_type != CODE_BLOCK_QUE_TYPE:
+                raise_tool_error(
+                    QingflowApiError(
+                        category="config",
+                        message=f"field '{code_block.que_title}' is not a code-block field",
+                        backend_code="CODE_BLOCK_FIELD_REQUIRED",
+                        details={
+                            "error_code": "CODE_BLOCK_FIELD_REQUIRED",
+                            "field": _field_ref_payload(code_block),
+                            "expected_que_type": CODE_BLOCK_QUE_TYPE,
+                        },
+                    )
+                )
+
+            current_answers = self._load_record_answers_for_code_block(
+                context,
+                app_key=app_key,
+                apply_id=normalized_record_id,
+                role=role,
+                audit_node_id=workflow_node_id,
+            )
+            override_answers = (
+                self._resolve_answers(
+                    profile,
+                    context,
+                    app_key,
+                    answers=answers or [],
+                    fields=fields or {},
+                    force_refresh_form=force_refresh_form,
+                )
+                if answers or fields
+                else []
+            )
+            merged_answers = self._merge_record_answers(current_answers, override_answers) if override_answers else current_answers
+            key_que_values = self._answers_to_open_match_values(merged_answers, index)
+            run_body: JSONObject = {
+                "role": role,
+                "manual": bool(manual),
+                "applyId": normalized_record_id,
+                "appKey": app_key,
+                "queryQuestions": [{"queId": code_block.que_id, "ordinal": None}],
+                "keyQueValues": key_que_values,
+            }
+            if workflow_node_id is not None:
+                run_body["auditNodeId"] = workflow_node_id
+            run_result = self.backend.request(
+                "POST",
+                context,
+                f"/app/{app_key}/codeBlock/working",
+                json_body=run_body,
+            )
+            alias_results = _normalize_code_block_alias_results(run_result)
+            relation_target_fields = _collect_code_block_relation_targets(
+                _collect_question_relations(schema),
+                code_block_que_id=code_block.que_id,
+            )
+            relation_errors: list[JSONObject] = []
+            relation_items: list[JSONObject] = []
+            calculated_answers: list[JSONObject] = []
+            relation_result: JSONObject | None = None
+            if relation_target_fields:
+                relation_body: JSONObject = {
+                    "role": role,
+                    "manual": bool(manual),
+                    "applyId": normalized_record_id,
+                    "appKey": app_key,
+                    "queryQuestions": [{"queId": target["que_id"], "ordinal": None} for target in relation_target_fields],
+                    "keyQueValues": key_que_values,
+                    "codeBlockValues": [{"queId": code_block.que_id, "values": alias_results}],
+                }
+                if workflow_node_id is not None:
+                    relation_body["auditNodeId"] = workflow_node_id
+                relation_result = self.backend.request("POST", context, "/que/actuator", json_body=relation_body)
+                relation_items = _relation_result_items(relation_result)
+                relation_errors = _relation_result_errors(relation_items)
+                calculated_answers = _relation_result_answers(relation_items)
+            write_result: JSONObject | None = None
+            verification: JSONObject | None = None
+            writeback_attempted = False
+            writeback_applied = False
+            status = "completed"
+            ok = True
+            if relation_target_fields and calculated_answers:
+                write_body: JSONObject = {"role": role, "answers": calculated_answers}
+                if workflow_node_id is not None:
+                    write_body["auditNodeId"] = workflow_node_id
+                writeback_attempted = True
+                write_result = cast(
+                    JSONObject,
+                    self.backend.request(
+                        "POST",
+                        context,
+                        f"/app/{app_key}/apply/{normalized_record_id}",
+                        json_body=write_body,
+                    ),
+                )
+                writeback_applied = True
+                if verify_writeback:
+                    verification = self._verify_code_block_writeback_result(
+                        context,
+                        app_key=app_key,
+                        apply_id=normalized_record_id,
+                        expected_answers=calculated_answers,
+                        index=index,
+                        role=role,
+                        audit_node_id=workflow_node_id,
+                    )
+                    if not bool(verification.get("verified")):
+                        status = "verification_failed"
+                        ok = False
+            elif relation_errors:
+                status = "relation_failed"
+                ok = False
+            else:
+                status = "no_writeback"
+            response: JSONObject = {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
+                "app_key": app_key,
+                "record_id": normalized_record_id,
+                "apply_id": normalized_record_id,
+                "status": status,
+                "ok": ok,
+                "code_block_field": _field_ref_payload(code_block),
+                "execution": {
+                    "executed": True,
+                    "role": role,
+                    "workflow_node_id": workflow_node_id,
+                    "manual": bool(manual),
+                    "result_count": len(alias_results),
+                },
+                "outputs": {
+                    "alias_results": alias_results,
+                    "alias_map": _build_alias_result_map(alias_results),
+                },
+                "relation": {
+                    "target_fields": relation_target_fields,
+                    "result_item_count": len(relation_items),
+                    "calculated_answer_count": len(calculated_answers),
+                    "errors": relation_errors,
+                },
+                "writeback": {
+                    "attempted": writeback_attempted,
+                    "applied": writeback_applied,
+                    "verify_writeback": verify_writeback,
+                    "write_verified": bool(verification.get("verified")) if verification is not None else None,
+                    "result": write_result,
+                    "verification": verification,
+                },
+                "resource": {"apply_id": normalized_record_id},
+            }
+            if normalized_output_profile == "verbose":
+                response["debug"] = {
+                    "run_body": run_body,
+                    "relation_result": relation_result,
+                    "calculated_answers": calculated_answers,
+                    "merged_answers": merged_answers,
+                    "key_que_values": key_que_values,
+                }
+            return response
+
+        return self._run_record_tool(profile, runner)
+
+    def _load_record_answers_for_code_block(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        role: int,
+        audit_node_id: int | None,
+    ) -> list[JSONObject]:
+        last_error: QingflowApiError | None = None
+        for list_type in self._INTERNAL_GET_LIST_TYPE_FALLBACKS:
+            params: JSONObject = {"role": role, "listType": list_type}
+            if audit_node_id is not None:
+                params["auditNodeId"] = audit_node_id
+            try:
+                record = self.backend.request("GET", context, f"/app/{app_key}/apply/{apply_id}", params=params)
+                answers = record.get("answers") if isinstance(record, dict) else None
+                return [item for item in answers if isinstance(item, dict)] if isinstance(answers, list) else []
+            except QingflowApiError as exc:
+                last_error = exc
+                if exc.backend_code == 40002:
+                    continue
+                raise
+        if last_error is not None:
+            raise last_error
+        raise_tool_error(QingflowApiError.config_error("record answers could not be loaded for code-block execution"))
+
+    def _answers_to_open_match_values(self, answers: list[JSONObject], index: FieldIndex) -> list[JSONObject]:
+        values: list[JSONObject] = []
+        for answer in answers:
+            if not isinstance(answer, dict):
+                continue
+            open_match = self._answer_to_open_match_value(answer, index)
+            if open_match is None:
+                continue
+            values.append(open_match)
+        return values
+
+    def _answer_to_open_match_value(self, answer: JSONObject, index: FieldIndex) -> JSONObject | None:
+        que_id = _coerce_count(answer.get("queId", answer.get("que_id")))
+        if que_id is None or que_id <= 0:
+            return None
+        field = index.by_id.get(str(que_id))
+        if field is None:
+            return None
+        ordinal = _coerce_count(answer.get("ordinal"))
+        if field.que_type in SUBTABLE_QUE_TYPES:
+            rows = answer.get("tableValues")
+            row_values: list[list[JSONObject]] = []
+            subtable_index = self._subtable_field_index_optional(field)
+            if isinstance(rows, list) and subtable_index is not None:
+                for row in rows:
+                    if not isinstance(row, list):
+                        continue
+                    normalized_row: list[JSONObject] = []
+                    for cell in row:
+                        if not isinstance(cell, dict):
+                            continue
+                        converted = self._answer_to_open_match_value(cell, subtable_index)
+                        if converted is not None:
+                            normalized_row.append(converted)
+                    row_values.append(normalized_row)
+            payload: JSONObject = {"keyQueId": field.que_id, "ordinal": ordinal, "values": [], "tableValues": row_values}
+            return payload
+        return {
+            "keyQueId": field.que_id,
+            "ordinal": ordinal,
+            "values": self._answer_values_to_code_block_values(answer, field),
+        }
+
+    def _answer_values_to_code_block_values(self, answer: JSONObject, field: FormField) -> list[str]:
+        if field.que_type in RELATION_QUE_TYPES:
+            return _relation_ids_from_answer(answer)
+        raw_values = answer.get("values")
+        if not isinstance(raw_values, list):
+            return []
+        normalized: list[str] = []
+        for item in raw_values:
+            normalized_value = _normalize_code_block_value_item(item, field)
+            if normalized_value is None:
+                continue
+            normalized.append(normalized_value)
+        return normalized
+
+    def _verify_code_block_writeback_result(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        expected_answers: list[JSONObject],
+        index: FieldIndex,
+        role: int,
+        audit_node_id: int | None,
+    ) -> JSONObject:
+        if role == 1 and audit_node_id is None:
+            return self._verify_record_write_result(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                normalized_answers=expected_answers,
+                index=index,
+                verify_list_type=DEFAULT_RECORD_LIST_TYPE,
+            )
+        actual_answers = self._load_record_answers_for_code_block(
+            context,
+            app_key=app_key,
+            apply_id=apply_id,
+            role=role,
+            audit_node_id=audit_node_id,
+        )
+        actual_by_id = {
+            que_id: item
+            for item in actual_answers
+            if isinstance(item, dict) and (que_id := _coerce_count(item.get("queId"))) is not None
+        }
+        missing_fields: list[JSONObject] = []
+        empty_fields: list[JSONObject] = []
+        count_mismatches: list[JSONObject] = []
+        for answer in expected_answers:
+            que_id = _coerce_count(answer.get("queId"))
+            if que_id is None or que_id <= 0:
+                continue
+            actual = actual_by_id.get(que_id)
+            field = index.by_id.get(str(que_id))
+            field_payload = _field_ref_payload(field) if field is not None else {"que_id": que_id}
+            if actual is None:
+                missing_fields.append(field_payload)
+                continue
+            expected_rows = answer.get("tableValues") if isinstance(answer.get("tableValues"), list) else []
+            if expected_rows:
+                actual_rows = actual.get("tableValues") if isinstance(actual.get("tableValues"), list) else []
+                self._verify_subtable_write_result(
+                    field=field,
+                    expected_rows=expected_rows,
+                    actual_rows=actual_rows,
+                    missing_fields=missing_fields,
+                    empty_fields=empty_fields,
+                    count_mismatches=count_mismatches,
+                )
+                continue
+            if field is not None and field.que_type in RELATION_QUE_TYPES:
+                expected_relation_ids = _relation_ids_from_answer(answer)
+                actual_relation_ids = _relation_ids_from_answer(actual)
+                if expected_relation_ids and not actual_relation_ids:
+                    empty_fields.append(field_payload)
+                    continue
+                if expected_relation_ids:
+                    actual_id_set = set(actual_relation_ids)
+                    missing_ids = [value for value in expected_relation_ids if value not in actual_id_set]
+                    if missing_ids:
+                        count_mismatches.append(
+                            {
+                                **field_payload,
+                                "expected_ids": expected_relation_ids,
+                                "actual_ids": actual_relation_ids,
+                                "missing_ids": missing_ids,
+                            }
+                        )
+                continue
+            actual_values = actual.get("values") if isinstance(actual.get("values"), list) else []
+            if not actual_values:
+                empty_fields.append(field_payload)
+                continue
+            expected_values = answer.get("values") if isinstance(answer.get("values"), list) else []
+            if expected_values and len(actual_values) < len(expected_values):
+                count_mismatches.append(
+                    {
+                        **field_payload,
+                        "expected_count": len(expected_values),
+                        "actual_count": len(actual_values),
+                    }
+                )
+        return {
+            "verified": not missing_fields and not empty_fields and not count_mismatches,
+            "verification_mode": "role_record_view",
+            "field_level_verified": True,
+            "missing_fields": missing_fields,
+            "empty_fields": empty_fields,
+            "count_mismatches": count_mismatches,
+        }
+
+
+def _normalize_code_block_value_item(value: JSONValue, field: FormField) -> str | None:
+    if field.que_type in SINGLE_SELECT_QUE_TYPES | MULTI_SELECT_QUE_TYPES:
+        return _selector_numeric_or_text(value, ("optionId", "optId", "id"), allow_text=False)
+    if field.que_type in MEMBER_QUE_TYPES:
+        return _selector_numeric_or_text(value, ("id", "uid"), allow_text=False)
+    if field.que_type in DEPARTMENT_QUE_TYPES:
+        return _selector_numeric_or_text(value, ("id", "deptId"), allow_text=False)
+    if field.que_type in ATTACHMENT_QUE_TYPES:
+        return _selector_numeric_or_text(value, ("value", "url", "otherInfo", "name", "fileName"), allow_text=True)
+    if isinstance(value, dict):
+        scalar = value.get("value")
+        return _stringify_json(scalar) if scalar is not None else None
+    text = _normalize_optional_text(value)
+    return text if text is not None else None
+
+
+def _selector_numeric_or_text(value: JSONValue, keys: tuple[str, ...], *, allow_text: bool) -> str | None:
+    numeric = _coerce_count(value)
+    if numeric is not None:
+        return str(numeric)
+    if not isinstance(value, dict):
+        if not allow_text:
+            return None
+        text = _normalize_optional_text(value)
+        return text if text is not None else None
+    for key in keys:
+        if key not in value:
+            continue
+        candidate = value.get(key)
+        if candidate is None:
+            continue
+        numeric = _coerce_count(candidate)
+        if numeric is not None:
+            return str(numeric)
+        if allow_text:
+            text = _normalize_optional_text(candidate)
+            if text is not None:
+                return text
+    return _normalize_optional_text(value.get("value")) if allow_text and isinstance(value.get("value"), (str, int, float)) else None
+
+
+def _normalize_code_block_alias_results(payload: JSONValue) -> list[JSONObject]:
+    if not isinstance(payload, dict):
+        return []
+    raw_results = payload.get("result")
+    if not isinstance(raw_results, list):
+        return []
+    results: list[JSONObject] = []
+    for item in raw_results:
+        if not isinstance(item, dict):
+            continue
+        values = item.get("value")
+        result: JSONObject = {
+            "parentAliasId": _coerce_count(item.get("parentAliasId")),
+            "parentAlias": _normalize_optional_text(item.get("parentAlias")),
+            "aliasId": _coerce_count(item.get("aliasId")),
+            "alias": _normalize_optional_text(item.get("alias")),
+            "value": [_stringify_json(entry) for entry in values] if isinstance(values, list) else [],
+        }
+        results.append(result)
+    return results
+
+
+def _build_alias_result_map(alias_results: list[JSONObject]) -> JSONObject:
+    alias_map: JSONObject = {}
+    for item in alias_results:
+        alias = _normalize_optional_text(item.get("alias"))
+        if alias is None:
+            continue
+        parent_alias = _normalize_optional_text(item.get("parentAlias"))
+        key = f"{parent_alias}.{alias}" if parent_alias else alias
+        values = item.get("value")
+        alias_map[key] = values if isinstance(values, list) else []
+    return alias_map
+
+
+def _collect_code_block_relation_targets(question_relations: list[JSONObject], *, code_block_que_id: int) -> list[JSONObject]:
+    targets: list[JSONObject] = []
+    seen: set[int] = set()
+    for relation in question_relations:
+        if _coerce_count(relation.get("relationType")) != CODE_BLOCK_RELATION_TYPE:
+            continue
+        if _coerce_count(relation.get("qlinkerQueId")) != code_block_que_id:
+            continue
+        target_id = _coerce_count(
+            relation.get("queId", relation.get("targetQueId", relation.get("displayedQueId")))
+        )
+        if target_id is None or target_id in seen:
+            continue
+        seen.add(target_id)
+        targets.append(
+            {
+                "que_id": target_id,
+                "alias_id": _coerce_count(relation.get("aliasId")),
+                "qlinker_que_id": _coerce_count(relation.get("qlinkerQueId")),
+            }
+        )
+    return targets
+
+
+def _relation_result_items(payload: JSONValue) -> list[JSONObject]:
+    if not isinstance(payload, dict):
+        return []
+    result = payload.get("result")
+    return [item for item in result if isinstance(item, dict)] if isinstance(result, list) else []
+
+
+def _relation_result_answers(items: list[JSONObject]) -> list[JSONObject]:
+    answers: list[JSONObject] = []
+    for item in items:
+        raw_answers = item.get("answers")
+        if not isinstance(raw_answers, list):
+            continue
+        for answer in raw_answers:
+            if isinstance(answer, dict):
+                answers.append(answer)
+    return answers
+
+
+def _relation_result_errors(items: list[JSONObject]) -> list[JSONObject]:
+    errors: list[JSONObject] = []
+    for item in items:
+        message = _normalize_optional_text(item.get("errorMsg"))
+        if message is None:
+            continue
+        errors.append(
+            {
+                "que_id": _coerce_count(item.get("queId")),
+                "que_title": _normalize_optional_text(item.get("queTitle")),
+                "ordinal": _coerce_count(item.get("ordinal")),
+                "message": message,
+            }
+        )
+    return errors

package/src/qingflow_mcp/tools/import_tools.py

@@ -1132,11 +1132,35 @@ def _analyze_headers(
     issues: list[JSONObject] = []
     repair_suggestions: list[str] = []
     if missing:
-        issues.append(_issue("MISSING_COLUMNS", f"Missing expected columns: {', '.join(missing)}", severity="error"))
+        issues.append(
+            _issue(
+                "MISSING_COLUMNS",
+                f"Missing expected columns: {', '.join(missing)}",
+                severity="error",
+                repairable=True,
+                repair_code="normalize_headers",
+            )
+        )
     if extra:
-        issues.append(_issue("EXTRA_COLUMNS", f"Unexpected columns: {', '.join(extra)}", severity="error"))
+        issues.append(
+            _issue(
+                "EXTRA_COLUMNS",
+                f"Unexpected columns: {', '.join(extra)}",
+                severity="error",
+                repairable=True,
+                repair_code="normalize_headers",
+            )
+        )
     if duplicates:
-        issues.append(_issue("DUPLICATE_COLUMNS", f"Duplicate columns: {', '.join(sorted(set(duplicates)))}", severity="error"))
+        issues.append(
+            _issue(
+                "DUPLICATE_COLUMNS",
+                f"Duplicate columns: {', '.join(sorted(set(duplicates)))}",
+                severity="error",
+                repairable=True,
+                repair_code="normalize_headers",
+            )
+        )
     normalized_changes = []
     for text in actual_headers:
         if not text:
@@ -1144,7 +1168,7 @@ def _analyze_headers(
         canonical = allowed_by_key.get(_normalize_header_key(text))
         if canonical and canonical != text:
             normalized_changes.append((text, canonical))
-    if normalized_changes:
+    if missing or extra or duplicates or normalized_changes:
         repair_suggestions.append("normalize_headers")
     return {"issues": issues, "repair_suggestions": repair_suggestions}
 
@@ -1194,7 +1218,8 @@ def _sheet_header_map(sheet) -> dict[str, int]:  # type: ignore[no-untyped-def]
 def _repair_headers(sheet, expected_columns: list[JSONObject]) -> bool:  # type: ignore[no-untyped-def]
     changed = False
     expected_by_key = {_normalize_header_key(item["title"]): item["title"] for item in expected_columns}
-    for cell in next(sheet.iter_rows(min_row=1, max_row=1), []):
+    header_cells = list(next(sheet.iter_rows(min_row=1, max_row=1), []))
+    for cell in header_cells:
         text = _normalize_optional_text(cell.value)
         if text is None:
             continue
@@ -1202,6 +1227,19 @@ def _repair_headers(sheet, expected_columns: list[JSONObject]) -> bool:  # type:
         if canonical and canonical != text:
             cell.value = canonical
             changed = True
+    if changed:
+        return True
+
+    # Fallback for template-based files where headers were edited into non-canonical
+    # values but column order is still intact. Keep any extra trailing system columns.
+    for index, column in enumerate(expected_columns, start=1):
+        if index > len(header_cells):
+            break
+        expected_title = str(column["title"]).strip()
+        current_title = _normalize_optional_text(header_cells[index - 1].value)
+        if current_title != expected_title:
+            header_cells[index - 1].value = expected_title
+            changed = True
     return changed
 
 

package/src/qingflow_mcp/tools/qingbi_report_tools.py

@@ -95,6 +95,32 @@ class QingbiReportTools(ToolBase):
         self._require_app_key(app_key)
         return self._request(profile, "GET", f"/qingbi/charts/data/bichart/{app_key}", app_key=app_key, items_key="items")
 
+    def qingbi_report_list_sorted(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        page_num: int = 1,
+        page_size: int = 500,
+        search_key: str | None = None,
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        body: JSONObject = {"appKey": app_key, "pageNum": page_num, "pageSize": page_size}
+        if search_key:
+            body["searchKey"] = search_key
+        return self._request(
+            profile,
+            "POST",
+            "/qingbi/charts/chart/list",
+            app_key=app_key,
+            page_num=page_num,
+            page_size=page_size,
+            search_key=search_key,
+            items_key="items",
+            result_transform=_extract_sorted_chart_items,
+            json_body=body,
+        )
+
     def qingbi_report_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
         body = self._require_dict(payload)
         return self._request(profile, "POST", "/qingbi/charts", json_body=body)
@@ -233,3 +259,11 @@ def _extract_dataset_fields(result: JSONValue) -> list[JSONObject]:
     if isinstance(result, list):
         return result
     return []
+
+
+def _extract_sorted_chart_items(result: JSONValue) -> list[JSONObject]:
+    if isinstance(result, dict) and isinstance(result.get("list"), list):
+        return result["list"]
+    if isinstance(result, list):
+        return result
+    return []