@josephyan/qingflow-app-builder-mcp 0.2.0-beta.26 → 0.2.0-beta.27

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.26",
+  "version": "0.2.0-beta.27",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/server.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from datetime import date
+
 from mcp.server.fastmcp import FastMCP
 
 from .backend_client import BackendClient
@@ -23,25 +25,88 @@ from .tools.workspace_tools import WorkspaceTools
 
 
 def build_server() -> FastMCP:
+    today = date.today()
+    current_year = today.year
     server = FastMCP(
         "Qingflow MCP",
-        instructions=(
-            "Use auth_login first, then workspace_list and workspace_select. "
-            "All resource tools operate with the logged-in user's Qingflow permissions.\n\n"
-            "If app_key is unknown, use app_list or app_search first to discover current-user visible apps in the selected workspace. "
-            "For analytics, use record_schema_get first, let the model build field_id-based DSL, "
-            "then call record_analyze. record_analyze returns compact business-first output as query/result/ranking/ratios/completeness/presentation; use verbose only for route/debug details. "
-            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
-            "For operational record reads, use record_schema_get first, then record_list or record_get. "
-            "For writes, use record_schema_get and then call record_write once; it performs internal preflight before any apply and refuses fields outside the applicant-node writable schema.\n\n"
-            "Task Center (待办/已办) handling:\n"
-            "- Use task_summary to get headline counts.\n"
-            "- Use task_list for flat task browsing with task_box and flow_status.\n"
-            "- Use task_facets when worksheet or workflow-node buckets matter.\n"
-            "- Use task_mark_read to mark a specific task as read.\n"
-            "- Use task_urge to send an urgent reminder for a pending task.\n"
-            "- After identifying the exact task node and record, use task_approve, task_reject, task_rollback, or task_transfer as needed."
-        ),
+        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+
+## Authentication
+
+Use `auth_login` first, then `workspace_list` and `workspace_select`.
+All resource tools operate with the logged-in user's Qingflow permissions.
+
+## App Discovery
+
+If `app_key` is unknown, use `app_list` or `app_search` first.
+
+## Schema-First Rule
+
+Always call `record_schema_get` before `record_list`, `record_get`, `record_write`, or `record_analyze`.
+
+- All `field_id` values must come from the schema response.
+- Never guess field names or ids.
+
+## Schema Scope
+
+`record_schema_get` returns the current user's applicant-node visible fields only.
+
+- Hidden fields are omitted.
+- Missing fields mean the field is not visible in the current permission scope.
+
+## Analytics Path
+
+`record_schema_get -> record_analyze`
+
+Use this DSL shape:
+
+- `dimensions`: `{{field_id, alias, bucket}}`
+- `metrics`: `{{op, field_id, alias}}`
+- `filters`: `{{field_id, op, value}}`
+- `sort`: `{{by, order}}`
+
+Important key rules:
+
+- Use `op`
+- Do **not** use `type`
+- Do **not** use `agg`
+- Do **not** use `aggregation`
+- Do **not** use `operator`
+
+Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
+
+## Record CRUD Path
+
+`record_schema_get -> record_list / record_get / record_write`
+
+`record_write` uses SQL-like JSON clauses:
+
+- `insert` -> `values`
+- `update` -> `record_id + set`
+- `delete` -> `record_id` or `record_ids`
+
+- Read relation targets from `record_schema_get.target_app_key` / `target_app_name` before preparing relation writes.
+- 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`.
+
+## Task Center Path
+
+`task_summary -> task_list / task_facets -> task action`
+
+## Time Handling
+
+Normalize relative dates before building DSL.
+
+- If the user says `3月` without a year, use the current year: `{current_year}`
+- Convert month-only phrases into explicit legal date ranges
+- Never send impossible dates such as `2026-02-29`
+
+## Environment
+
+Default to `prod` unless the user explicitly specifies `test`.
+
+## Constraints
+
+Avoid builder-side app or schema changes here.""",
     )
     sessions = SessionStore()
     backend = BackendClient()

package/src/qingflow_mcp/server_app_user.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from datetime import date
+
 from mcp.server.fastmcp import FastMCP
 
 from .backend_client import BackendClient
@@ -16,17 +18,83 @@ from .tools.workspace_tools import WorkspaceTools
 
 
 def build_user_server() -> FastMCP:
+    today = date.today()
+    current_year = today.year
     server = FastMCP(
         "Qingflow App User MCP",
-        instructions=(
-            "Use this server for Qingflow operational workflows with a schema-first path. "
-            "If app_key is unknown, use app_list or app_search first to discover current-user visible apps in the selected workspace. "
-            "For records, start with record_schema_get, then choose record_list, record_get, or record_write. "
-            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
-            "For analytics, switch to record_schema_get and record_analyze; its default output is compact query/result/ranking/ratios/completeness/presentation, with route/debug only in verbose mode. "
-            "For task center, use task_summary, task_list, and task_facets before any explicit task action. "
-            "Avoid builder-side app or schema changes here."
-        ),
+        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+
+## App Discovery
+
+If `app_key` is unknown, use `app_list` or `app_search` first.
+
+## Schema-First Rule
+
+Always call `record_schema_get` before `record_list`, `record_get`, `record_write`, or `record_analyze`.
+
+- All `field_id` values must come from the schema response.
+- Never guess field names or ids.
+
+## Schema Scope
+
+`record_schema_get` returns the current user's applicant-node visible fields only.
+
+- Hidden fields are omitted.
+- Missing fields mean the field is not visible in the current permission scope.
+
+## Analytics Path
+
+`record_schema_get -> record_analyze`
+
+Use this DSL shape:
+
+- `dimensions`: `{{field_id, alias, bucket}}`
+- `metrics`: `{{op, field_id, alias}}`
+- `filters`: `{{field_id, op, value}}`
+- `sort`: `{{by, order}}`
+
+Important key rules:
+
+- Use `op`
+- Do **not** use `type`
+- Do **not** use `agg`
+- Do **not** use `aggregation`
+- Do **not** use `operator`
+
+Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
+
+## Record CRUD Path
+
+`record_schema_get -> record_list / record_get / record_write`
+
+`record_write` uses SQL-like JSON clauses:
+
+- `insert` -> `values`
+- `update` -> `record_id + set`
+- `delete` -> `record_id` or `record_ids`
+
+- Read relation targets from `record_schema_get.target_app_key` / `target_app_name` before preparing relation writes.
+- 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`.
+
+## Task Center Path
+
+`task_summary -> task_list / task_facets -> task action`
+
+## Time Handling
+
+Normalize relative dates before building DSL.
+
+- If the user says `3月` without a year, use the current year: `{current_year}`
+- Convert month-only phrases into explicit legal date ranges
+- Never send impossible dates such as `2026-02-29`
+
+## Environment
+
+Default to `prod` unless the user explicitly specifies `test`.
+
+## Constraints
+
+Avoid builder-side app or schema changes here.""",
     )
     sessions = SessionStore()
     backend = BackendClient()

package/src/qingflow_mcp/tools/record_tools.py

@@ -5,7 +5,7 @@ import re
 import time
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from typing import cast
+from typing import Any, cast
 
 from mcp.server.fastmcp import FastMCP
 
@@ -14,6 +14,7 @@ from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject, JSONScalar, JSONValue
 from ..list_type_labels import get_record_list_type_label
 from .base import ToolBase
+from .directory_tools import _directory_has_more, _directory_items
 
 
 DEFAULT_QUERY_PAGE_SIZE = 50
@@ -24,6 +25,8 @@ DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 100
 DEFAULT_ANALYSIS_AUTO_EXPAND_PAGE_CAP = 100
 DEFAULT_ROW_LIMIT = 200
 DEFAULT_OUTPUT_PROFILE = "compact"
+DEFAULT_MEMBER_SCOPE_FETCH_PAGE_SIZE = 200
+MAX_MEMBER_SCOPE_FETCH_PAGES = 20
 MAX_LIST_COLUMN_LIMIT = 20
 MAX_RECORD_COLUMN_LIMIT = 20
 MAX_SUMMARY_PREVIEW_COLUMN_LIMIT = 6
@@ -63,6 +66,12 @@ class FormField:
     system: bool
     options: list[str]
     aliases: list[str]
+    target_app_key: str | None
+    target_app_name_hint: str | None
+    member_select_scope_type: int | None
+    member_select_scope: JSONObject | None
+    dept_select_scope_type: int | None
+    dept_select_scope: JSONObject | None
     raw: JSONObject
 
 
@@ -147,6 +156,7 @@ class RecordTools(ToolBase):
         self._applicant_node_cache: dict[tuple[str, str], WorkflowNodeRef] = {}
         self._view_list_cache: dict[tuple[str, str], list[JSONObject]] = {}
         self._view_config_cache: dict[tuple[str, str], JSONObject] = {}
+        self._app_name_cache: dict[tuple[str, int | None, str], str | None] = {}
 
     def register(self, mcp: FastMCP) -> None:
         @mcp.tool()
@@ -165,6 +175,55 @@ class RecordTools(ToolBase):
                 output_profile=output_profile,
             )
 
+        @mcp.tool(
+            description=(
+                "List current-user candidate members for a member field in the applicant-node visible schema. "
+                "Use record_schema_get first, then pass the member field_id. "
+                "This tool fails closed when the field uses dynamic or external candidate scopes."
+            )
+        )
+        def record_member_candidates(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            field_id: int = 0,
+            keyword: str = "",
+            page_num: int = 1,
+            page_size: int = 20,
+        ) -> JSONObject:
+            return self.record_member_candidates(
+                profile=profile,
+                app_key=app_key,
+                field_id=field_id,
+                keyword=keyword,
+                page_num=page_num,
+                page_size=page_size,
+            )
+
+        @mcp.tool(
+            description=(
+                "List current-user candidate departments for a department field in the applicant-node visible schema. "
+                "Use record_schema_get first, then pass the department field_id. "
+                "This tool supports explicit department scopes and default-all department scopes, but fails closed "
+                "for dynamic or external candidate scopes."
+            )
+        )
+        def record_department_candidates(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            field_id: int = 0,
+            keyword: str = "",
+            page_num: int = 1,
+            page_size: int = 20,
+        ) -> JSONObject:
+            return self.record_department_candidates(
+                profile=profile,
+                app_key=app_key,
+                field_id=field_id,
+                keyword=keyword,
+                page_num=page_num,
+                page_size=page_size,
+            )
+
         @mcp.tool(
             description=(
                 "Run schema-first analytics on a Qingflow app using a restricted DSL. "
@@ -299,7 +358,16 @@ class RecordTools(ToolBase):
             applicant_node = self._resolve_applicant_node(profile, context, app_key, force_refresh=False)
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
             view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
-            fields = [self._schema_field_payload(field, workflow_node_id=applicant_node.workflow_node_id) for field in index.by_id.values()]
+            fields = [
+                self._schema_field_payload(
+                    profile,
+                    context,
+                    field,
+                    workflow_node_id=applicant_node.workflow_node_id,
+                    ws_id=session_profile.selected_ws_id,
+                )
+                for field in index.by_id.values()
+            ]
             suggested_dimensions = [
                 {"field_id": item["field_id"], "title": item["title"]}
                 for item in fields
@@ -342,6 +410,144 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    def record_member_candidates(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        field_id: int,
+        keyword: str,
+        page_num: int,
+        page_size: int,
+    ) -> JSONObject:
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        if field_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("field_id must be positive"))
+        if page_num <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
+        if page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+
+        def runner(session_profile, context):
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            field = self._resolve_field_selector(field_id, index, location="field_id")
+            if field.que_type not in MEMBER_QUE_TYPES:
+                raise_tool_error(
+                    QingflowApiError(
+                        category="config",
+                        message=f"field_id {field_id} is not a member field in the applicant-aware schema",
+                        details={
+                            "error_code": "FIELD_NOT_MEMBER",
+                            "field_id": field.que_id,
+                            "field_title": field.que_title,
+                            "que_type": field.que_type,
+                        },
+                    )
+                )
+            items = self._resolve_member_candidates(context, field, keyword=keyword)
+            total = len(items)
+            start = (page_num - 1) * page_size
+            end = start + page_size
+            page_items = items[start:end]
+            page_amount = (total + page_size - 1) // page_size if total else 0
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": self._request_route_payload(context),
+                "warnings": [],
+                "output_profile": "normal",
+                "data": {
+                    "items": page_items,
+                    "pagination": {
+                        "page": page_num,
+                        "page_size": page_size,
+                        "returned_items": len(page_items),
+                        "reported_total": total,
+                        "page_amount": page_amount,
+                    },
+                    "selection": {
+                        "app_key": app_key,
+                        "field_id": field.que_id,
+                        "field_title": field.que_title,
+                        "keyword": keyword,
+                        "permission_scope": "applicant_node",
+                    },
+                },
+            }
+
+        return self._run_record_tool(profile, runner)
+
+    def record_department_candidates(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        field_id: int,
+        keyword: str,
+        page_num: int,
+        page_size: int,
+    ) -> JSONObject:
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        if field_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("field_id must be positive"))
+        if page_num <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
+        if page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+
+        def runner(session_profile, context):
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            field = self._resolve_field_selector(field_id, index, location="field_id")
+            if field.que_type not in DEPARTMENT_QUE_TYPES:
+                raise_tool_error(
+                    QingflowApiError(
+                        category="config",
+                        message=f"field_id {field_id} is not a department field in the applicant-aware schema",
+                        details={
+                            "error_code": "FIELD_NOT_DEPARTMENT",
+                            "field_id": field.que_id,
+                            "field_title": field.que_title,
+                            "que_type": field.que_type,
+                        },
+                    )
+                )
+            items = self._resolve_department_candidates(context, field, keyword=keyword)
+            total = len(items)
+            start = (page_num - 1) * page_size
+            end = start + page_size
+            page_items = items[start:end]
+            page_amount = (total + page_size - 1) // page_size if total else 0
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "request_route": self._request_route_payload(context),
+                "warnings": [],
+                "output_profile": "normal",
+                "data": {
+                    "items": page_items,
+                    "pagination": {
+                        "page": page_num,
+                        "page_size": page_size,
+                        "returned_items": len(page_items),
+                        "reported_total": total,
+                        "page_amount": page_amount,
+                    },
+                    "selection": {
+                        "app_key": app_key,
+                        "field_id": field.que_id,
+                        "field_title": field.que_title,
+                        "keyword": keyword,
+                        "permission_scope": "applicant_node",
+                    },
+                },
+            }
+
+        return self._run_record_tool(profile, runner)
+
     def record_analyze(
         self,
         *,
@@ -548,23 +754,48 @@ class RecordTools(ToolBase):
                 }
             return response
 
+        # listType 降级顺序：数据管理全部 → 我发起的 → 待办 → 已办 → 抄送
+        _GET_LIST_TYPE_FALLBACKS = [DEFAULT_RECORD_LIST_TYPE, 14, 1, 2, 12]
+
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
             selected_fields = list(index.by_id.values())
-            result = self.backend.request(
-                "GET",
-                context,
-                f"/app/{app_key}/apply/{record_id}",
-                params={"role": 1},
-            )
+            result: JSONObject | None = None
+            used_list_type: int | None = None
+            last_error: QingflowApiError | None = None
+            for lt in _GET_LIST_TYPE_FALLBACKS:
+                try:
+                    result = self.backend.request(
+                        "GET",
+                        context,
+                        f"/app/{app_key}/apply/{record_id}",
+                        params={"role": 1, "listType": lt},
+                    )
+                    used_list_type = lt
+                    break
+                except QingflowApiError as exc:
+                    last_error = exc
+                    if exc.backend_code == 40002:
+                        continue
+                    raise
+            if result is None:
+                if last_error is not None:
+                    raise last_error
+                raise_tool_error(QingflowApiError.config_error("record_get failed: no accessible listType"))
             answer_list = result.get("answers") if isinstance(result, dict) and isinstance(result.get("answers"), list) else []
             row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+            warnings: list[JSONObject] = []
+            if used_list_type is not None and used_list_type != DEFAULT_RECORD_LIST_TYPE:
+                warnings.append({
+                    "code": "LIST_TYPE_FALLBACK",
+                    "message": f"Record not accessible via listType={DEFAULT_RECORD_LIST_TYPE}; fell back to listType={used_list_type} ({get_record_list_type_label(used_list_type)}).",
+                })
             response: JSONObject = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "ok": True,
                 "request_route": self._request_route_payload(context),
-                "warnings": [],
+                "warnings": warnings,
                 "output_profile": normalized_output_profile,
                 "data": {
                     "app_key": app_key,
@@ -577,7 +808,7 @@ class RecordTools(ToolBase):
                 },
             }
             if normalized_output_profile == "verbose":
-                response["data"]["debug"] = {"raw_record": result}
+                response["data"]["debug"] = {"raw_record": result, "list_type_used": used_list_type}
             return response
 
         return self._run_record_tool(profile, runner)
@@ -737,9 +968,9 @@ class RecordTools(ToolBase):
             preflight=None,
         )
 
-    def _schema_field_payload(self, field: FormField, *, workflow_node_id: int) -> JSONObject:
+    def _schema_field_payload(self, profile: str, context, field: FormField, *, workflow_node_id: int, ws_id: int | None) -> JSONObject:  # type: ignore[no-untyped-def]
         write_hints = self._schema_write_hints(field)
-        return {
+        payload = {
             "field_id": field.que_id,
             "title": field.que_title,
             "que_type": field.que_type,
@@ -760,6 +991,17 @@ class RecordTools(ToolBase):
             "requires_existing_row_id": write_hints["requires_existing_row_id"],
             "unsupported_reason": write_hints["unsupported_reason"],
         }
+        if field.que_type in RELATION_QUE_TYPES and field.target_app_key:
+            payload["target_app_key"] = field.target_app_key
+            target_app_name = field.target_app_name_hint or self._resolve_visible_app_name(
+                profile,
+                context,
+                target_app_key=field.target_app_key,
+                ws_id=ws_id,
+            )
+            if target_app_name:
+                payload["target_app_name"] = target_app_name
+        return payload
 
     def _schema_role_hints(self, field: FormField) -> JSONObject:
         field_family = self._schema_field_family(field)
@@ -822,6 +1064,350 @@ class RecordTools(ToolBase):
         }
         return mapping.get(kind, "scalar")
 
+    def _resolve_visible_app_name(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        target_app_key: str,
+        ws_id: int | None,
+    ) -> str | None:
+        cache_key = (profile, ws_id, target_app_key)
+        if cache_key in self._app_name_cache:
+            return self._app_name_cache[cache_key]
+        name: str | None = None
+        try:
+            payload = self.backend.request("GET", context, f"/app/{target_app_key}/baseInfo")
+            if isinstance(payload, dict):
+                name = (
+                    _normalize_optional_text(payload.get("formTitle"))
+                    or _normalize_optional_text(payload.get("appName"))
+                    or _normalize_optional_text(payload.get("appTitle"))
+                )
+        except QingflowApiError:
+            name = None
+        self._app_name_cache[cache_key] = name
+        return name
+
+    def _resolve_member_candidates(self, context, field: FormField, *, keyword: str) -> list[JSONObject]:  # type: ignore[no-untyped-def]
+        scope_type = field.member_select_scope_type
+        scope = field.member_select_scope if isinstance(field.member_select_scope, dict) else {}
+        if _scope_is_default_all(scope_type, scope, keys=("member", "depart", "role")):
+            candidates = [
+                _normalize_candidate_member(item, source_kind="workspace")
+                for item in self._fetch_internal_members(context, department_id=None, role_id=None)
+            ]
+            filtered = _filter_member_candidates([item for item in candidates if item is not None], keyword)
+            filtered.sort(key=lambda item: (_normalize_optional_text(item.get("value")) or "", _coerce_count(item.get("id")) or 0))
+            return filtered
+        if scope_type != 1:
+            raise_tool_error(
+                QingflowApiError(
+                    category="not_supported",
+                    message="record_member_candidates only supports explicit member scopes on the applicant-node form",
+                    details={
+                        "error_code": "MEMBER_CANDIDATES_SCOPE_UNSUPPORTED",
+                        "field_id": field.que_id,
+                        "field_title": field.que_title,
+                        "member_select_scope_type": scope_type,
+                    },
+                )
+            )
+        if _scope_has_dynamic_or_external(scope):
+            raise_tool_error(
+                QingflowApiError(
+                    category="not_supported",
+                    message="record_member_candidates does not support dynamic or external member scopes safely",
+                    details={
+                        "error_code": "MEMBER_CANDIDATES_SCOPE_UNSUPPORTED",
+                        "field_id": field.que_id,
+                        "field_title": field.que_title,
+                        "member_select_scope_type": scope_type,
+                    },
+                )
+            )
+
+        merged: dict[str, JSONObject] = {}
+        for item in cast(list[JSONValue], scope.get("member") or []):
+            normalized = _normalize_candidate_member(item, source_kind="member")
+            if normalized is None:
+                continue
+            self._merge_member_candidate(merged, normalized)
+
+        include_sub = _normalize_bool(scope.get("includeSubDeparts"))
+        for item in cast(list[JSONValue], scope.get("depart") or []):
+            dept_id = _coerce_count(item.get("deptId", item.get("id")) if isinstance(item, dict) else item)
+            if dept_id is None:
+                continue
+            dept_name = _normalize_optional_text(item.get("deptName") if isinstance(item, dict) else None)
+            for member in self._list_members_by_department(context, dept_id=dept_id, include_sub_departments=include_sub):
+                normalized = _normalize_candidate_member(
+                    member,
+                    source_kind="department",
+                    source_id=dept_id,
+                    source_value=dept_name,
+                )
+                if normalized is None:
+                    continue
+                self._merge_member_candidate(merged, normalized)
+
+        for item in cast(list[JSONValue], scope.get("role") or []):
+            role_id = _coerce_count(item.get("roleId", item.get("id")) if isinstance(item, dict) else item)
+            if role_id is None:
+                continue
+            role_name = _normalize_optional_text(item.get("roleName") if isinstance(item, dict) else None)
+            for member in self._list_members_by_role(context, role_id=role_id):
+                normalized = _normalize_candidate_member(
+                    member,
+                    source_kind="role",
+                    source_id=role_id,
+                    source_value=role_name,
+                )
+                if normalized is None:
+                    continue
+                self._merge_member_candidate(merged, normalized)
+
+        candidates = list(merged.values())
+        filtered = _filter_member_candidates(candidates, keyword)
+        filtered.sort(key=lambda item: (_normalize_optional_text(item.get("value")) or "", _coerce_count(item.get("id")) or 0))
+        return filtered
+
+    def _resolve_department_candidates(self, context, field: FormField, *, keyword: str) -> list[JSONObject]:  # type: ignore[no-untyped-def]
+        scope_type = field.dept_select_scope_type
+        scope = field.dept_select_scope if isinstance(field.dept_select_scope, dict) else {}
+        if _scope_has_dynamic_or_external(scope):
+            raise_tool_error(
+                QingflowApiError(
+                    category="not_supported",
+                    message="record_department_candidates does not support dynamic or external department scopes safely",
+                    details={
+                        "error_code": "DEPARTMENT_CANDIDATES_SCOPE_UNSUPPORTED",
+                        "field_id": field.que_id,
+                        "field_title": field.que_title,
+                        "dept_select_scope_type": scope_type,
+                    },
+                )
+            )
+        merged: dict[str, JSONObject] = {}
+        include_sub = _normalize_bool(scope.get("includeSubDeparts"))
+        if _scope_is_default_all(scope_type, scope, keys=("depart",)):
+            for item in self._list_all_departments(context):
+                normalized = _normalize_candidate_department(item, source_kind="workspace")
+                if normalized is not None:
+                    self._merge_department_candidate(merged, normalized)
+        else:
+            if scope_type != 1:
+                raise_tool_error(
+                    QingflowApiError(
+                        category="not_supported",
+                        message="record_department_candidates only supports explicit or default-all department scopes on the applicant-node form",
+                        details={
+                            "error_code": "DEPARTMENT_CANDIDATES_SCOPE_UNSUPPORTED",
+                            "field_id": field.que_id,
+                            "field_title": field.que_title,
+                            "dept_select_scope_type": scope_type,
+                        },
+                    )
+                )
+            for item in cast(list[JSONValue], scope.get("depart") or []):
+                dept_id = _coerce_count(item.get("deptId", item.get("id")) if isinstance(item, dict) else item)
+                if dept_id is None:
+                    continue
+                dept_name = _normalize_optional_text(item.get("deptName", item.get("value")) if isinstance(item, dict) else None)
+                for dept in self._list_departments_by_scope(context, dept_id=dept_id, include_sub_departments=include_sub):
+                    normalized = _normalize_candidate_department(
+                        dept,
+                        source_kind="department",
+                        source_id=dept_id,
+                        source_value=dept_name,
+                    )
+                    if normalized is not None:
+                        self._merge_department_candidate(merged, normalized)
+        filtered = _filter_department_candidates(list(merged.values()), keyword)
+        filtered.sort(key=lambda item: (_normalize_optional_text(item.get("value")) or "", _coerce_count(item.get("id")) or 0))
+        return filtered
+
+    def _merge_member_candidate(self, merged: dict[str, JSONObject], candidate: JSONObject) -> None:
+        key = _member_candidate_key(candidate)
+        if not key:
+            return
+        existing = merged.get(key)
+        if existing is None:
+            merged[key] = candidate
+            return
+        if not existing.get("userId") and candidate.get("userId"):
+            existing["userId"] = candidate["userId"]
+        if not existing.get("email") and candidate.get("email"):
+            existing["email"] = candidate["email"]
+        if (not _normalize_optional_text(existing.get("value"))) and _normalize_optional_text(candidate.get("value")):
+            existing["value"] = candidate["value"]
+        existing_sources = existing.setdefault("sources", [])
+        candidate_sources = candidate.get("sources")
+        if isinstance(existing_sources, list) and isinstance(candidate_sources, list):
+            seen = {json.dumps(item, ensure_ascii=False, sort_keys=True) for item in existing_sources if isinstance(item, dict)}
+            for source in candidate_sources:
+                if not isinstance(source, dict):
+                    continue
+                marker = json.dumps(source, ensure_ascii=False, sort_keys=True)
+                if marker in seen:
+                    continue
+                existing_sources.append(source)
+                seen.add(marker)
+
+    def _list_members_by_department(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        dept_id: int,
+        include_sub_departments: bool,
+    ) -> list[dict[str, Any]]:
+        dept_ids = {dept_id}
+        if include_sub_departments:
+            dept_ids.update(self._expand_department_ids(context, root_dept_id=dept_id))
+        merged: dict[str, dict[str, Any]] = {}
+        for current_dept_id in dept_ids:
+            for item in self._fetch_internal_members(context, department_id=current_dept_id, role_id=None):
+                member_key = _member_candidate_key(item)
+                if member_key and member_key not in merged:
+                    merged[member_key] = item
+        return list(merged.values())
+
+    def _list_members_by_role(self, context, *, role_id: int) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        return self._fetch_internal_members(context, department_id=None, role_id=role_id)
+
+    def _list_departments_by_scope(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        dept_id: int,
+        include_sub_departments: bool,
+    ) -> list[dict[str, Any]]:
+        dept_ids = {dept_id}
+        if include_sub_departments:
+            dept_ids.update(self._expand_department_ids(context, root_dept_id=dept_id))
+        merged: dict[str, dict[str, Any]] = {}
+        for item in self._list_all_departments(context):
+            department_key = _department_candidate_key(item)
+            current_dept_id = _coerce_count(item.get("deptId", item.get("id")))
+            if not department_key or current_dept_id is None or current_dept_id not in dept_ids or department_key in merged:
+                continue
+            merged[department_key] = item
+        return list(merged.values())
+
+    def _list_all_departments(self, context) -> list[dict[str, Any]]:  # type: ignore[no-untyped-def]
+        queue: list[int | None] = [None]
+        seen_ids: set[int] = set()
+        requested_parents: set[int | None] = set()
+        items: list[dict[str, Any]] = []
+        while queue:
+            current_parent = queue.pop(0)
+            if current_parent in requested_parents:
+                continue
+            requested_parents.add(current_parent)
+            params: JSONObject = {}
+            if current_parent is not None:
+                params["parentDeptId"] = current_parent
+            result = self.backend.request("GET", context, "/contact/subDeptList", params=params)
+            page_items = _directory_items(result)
+            if not page_items and current_parent is None:
+                result = self.backend.request("GET", context, "/contact/subDeptList", params={"parentDeptId": 0})
+                page_items = _directory_items(result)
+            for item in page_items:
+                if not isinstance(item, dict):
+                    continue
+                dept_id = _coerce_count(item.get("deptId", item.get("id")))
+                if dept_id is None or dept_id in seen_ids:
+                    continue
+                seen_ids.add(dept_id)
+                normalized = dict(item)
+                if current_parent is not None and "parentDeptId" not in normalized:
+                    normalized["parentDeptId"] = current_parent
+                items.append(normalized)
+                queue.append(dept_id)
+        return items
+
+    def _merge_department_candidate(self, merged: dict[str, JSONObject], candidate: JSONObject) -> None:
+        key = _department_candidate_key(candidate)
+        if not key:
+            return
+        existing = merged.get(key)
+        if existing is None:
+            merged[key] = candidate
+            return
+        if (not _normalize_optional_text(existing.get("value"))) and _normalize_optional_text(candidate.get("value")):
+            existing["value"] = candidate["value"]
+        existing_sources = existing.setdefault("sources", [])
+        candidate_sources = candidate.get("sources")
+        if isinstance(existing_sources, list) and isinstance(candidate_sources, list):
+            seen = {json.dumps(item, ensure_ascii=False, sort_keys=True) for item in existing_sources if isinstance(item, dict)}
+            for source in candidate_sources:
+                if not isinstance(source, dict):
+                    continue
+                marker = json.dumps(source, ensure_ascii=False, sort_keys=True)
+                if marker in seen:
+                    continue
+                existing_sources.append(source)
+                seen.add(marker)
+
+    def _expand_department_ids(self, context, *, root_dept_id: int) -> set[int]:  # type: ignore[no-untyped-def]
+        seen: set[int] = set()
+        queue: list[int] = [root_dept_id]
+        while queue:
+            current_dept_id = queue.pop(0)
+            if current_dept_id in seen:
+                continue
+            seen.add(current_dept_id)
+            result = self.backend.request("GET", context, "/contact/subDeptList", params={"parentDeptId": current_dept_id})
+            for item in _directory_items(result):
+                if not isinstance(item, dict):
+                    continue
+                child_id = _coerce_count(item.get("deptId", item.get("id")))
+                if child_id is None or child_id in seen:
+                    continue
+                queue.append(child_id)
+        return seen
+
+    def _fetch_internal_members(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        department_id: int | None,
+        role_id: int | None,
+    ) -> list[dict[str, Any]]:
+        current_page = 1
+        fetched_pages = 0
+        seen: dict[str, dict[str, Any]] = {}
+        while fetched_pages < MAX_MEMBER_SCOPE_FETCH_PAGES:
+            params: JSONObject = {
+                "pageNum": current_page,
+                "pageSize": DEFAULT_MEMBER_SCOPE_FETCH_PAGE_SIZE,
+                "containDisable": False,
+            }
+            if department_id is not None:
+                params["deptId"] = department_id
+            if role_id is not None:
+                params["roleId"] = role_id
+            result = self.backend.request("GET", context, "/contact", params=params)
+            page_items = _directory_items(result)
+            for item in page_items:
+                if not isinstance(item, dict):
+                    continue
+                normalized = dict(item)
+                member_key = _member_candidate_key(normalized)
+                if not member_key or member_key in seen:
+                    continue
+                seen[member_key] = normalized
+            fetched_pages += 1
+            if not _directory_has_more(
+                result,
+                current_page=current_page,
+                page_size=DEFAULT_MEMBER_SCOPE_FETCH_PAGE_SIZE,
+                returned_items=len(page_items),
+            ):
+                break
+            current_page += 1
+        return list(seen.values())
+
     def _schema_field_family(self, field: FormField) -> str:
         if self._schema_is_identifier_like(field):
             return "text"
@@ -1968,6 +2554,9 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    # listType 降级顺序（内部 record_get）
+    _INTERNAL_GET_LIST_TYPE_FALLBACKS = [DEFAULT_RECORD_LIST_TYPE, 14, 1, 2, 12]
+
     def record_get(
         self,
         *,
@@ -1981,12 +2570,40 @@ class RecordTools(ToolBase):
         normalized_apply_id = self._validate_app_and_record(app_key, apply_id)
 
         def runner(session_profile, context):
-            params: JSONObject = {"role": role}
-            if list_type is not None:
-                params["listType"] = list_type
+            base_params: JSONObject = {"role": role}
             if audit_node_id is not None:
-                params["auditNodeId"] = audit_node_id
-            result = self.backend.request("GET", context, f"/app/{app_key}/apply/{normalized_apply_id}", params=params)
+                base_params["auditNodeId"] = audit_node_id
+
+            # 如果调用方指定了 list_type，直接用，不降级
+            if list_type is not None:
+                base_params["listType"] = list_type
+                result = self.backend.request("GET", context, f"/app/{app_key}/apply/{normalized_apply_id}", params=base_params)
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "request_route": self._request_route_payload(context),
+                    "app_key": app_key,
+                    "apply_id": normalized_apply_id,
+                    "result": result,
+                }
+
+            # 未指定 list_type 时自动降级
+            result: JSONObject | None = None
+            last_error: QingflowApiError | None = None
+            for lt in self._INTERNAL_GET_LIST_TYPE_FALLBACKS:
+                try:
+                    params = {**base_params, "listType": lt}
+                    result = self.backend.request("GET", context, f"/app/{app_key}/apply/{normalized_apply_id}", params=params)
+                    break
+                except QingflowApiError as exc:
+                    last_error = exc
+                    if exc.backend_code == 40002:
+                        continue
+                    raise
+            if result is None:
+                if last_error is not None:
+                    raise last_error
+                raise_tool_error(QingflowApiError.config_error("record_get failed: no accessible listType"))
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -4078,6 +4695,12 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
             system=bool(question.get("system") or question.get("beingSystem") or is_base_question),
             options=_extract_question_options(question),
             aliases=[],
+            target_app_key=_extract_relation_target_app_key(question),
+            target_app_name_hint=_extract_relation_target_app_name_hint(question),
+            member_select_scope_type=_coerce_count(question.get("memberSelectScopeType")),
+            member_select_scope=_normalize_scope_payload(question.get("memberSelectScope")),
+            dept_select_scope_type=_coerce_count(question.get("deptSelectScopeType")),
+            dept_select_scope=_normalize_scope_payload(question.get("deptSelectScope")),
             raw=question,
         )
         if str(que_id) in by_id:
@@ -4090,6 +4713,32 @@ def _build_field_index(schema: JSONObject) -> FieldIndex:
     return FieldIndex(by_id=by_id, by_title=by_title, by_alias=by_alias)
 
 
+def _extract_relation_target_app_key(question: JSONObject) -> str | None:
+    if _coerce_count(question.get("queType")) not in RELATION_QUE_TYPES:
+        return None
+    reference = question.get("referenceConfig")
+    if not isinstance(reference, dict):
+        return None
+    return _normalize_optional_text(reference.get("referAppKey"))
+
+
+def _extract_relation_target_app_name_hint(question: JSONObject) -> str | None:
+    if _coerce_count(question.get("queType")) not in RELATION_QUE_TYPES:
+        return None
+    reference = question.get("referenceConfig")
+    if not isinstance(reference, dict):
+        return None
+    for key in ("referAppName", "referAppTitle", "referFormTitle", "appName", "appTitle"):
+        text = _normalize_optional_text(reference.get(key))
+        if text:
+            return text
+    return None
+
+
+def _normalize_scope_payload(value: JSONValue) -> JSONObject | None:
+    return value if isinstance(value, dict) else None
+
+
 def _flatten_questions(payload: JSONValue) -> list[JSONObject]:
     flattened: list[JSONObject] = []
     if isinstance(payload, dict):
@@ -5260,6 +5909,164 @@ def _relation_value(value: JSONValue) -> JSONObject:
     return {"value": _stringify_json(value)}
 
 
+def _normalize_candidate_member(
+    value: JSONValue,
+    *,
+    source_kind: str,
+    source_id: int | None = None,
+    source_value: str | None = None,
+) -> JSONObject | None:
+    if not isinstance(value, dict):
+        return None
+    member_id = _coerce_count(value.get("uid", value.get("id")))
+    user_id = _normalize_optional_text(value.get("userId"))
+    if member_id is None and not user_id:
+        return None
+    display_value = (
+        _normalize_optional_text(value.get("nickName"))
+        or _normalize_optional_text(value.get("name"))
+        or _normalize_optional_text(value.get("userName"))
+        or _normalize_optional_text(value.get("value"))
+        or (str(member_id) if member_id is not None else user_id)
+    )
+    if not display_value:
+        return None
+    candidate: JSONObject = {"value": display_value, "sources": [{"kind": source_kind}]}
+    if member_id is not None:
+        candidate["id"] = member_id
+    if user_id:
+        candidate["userId"] = user_id
+    email = _normalize_optional_text(value.get("email"))
+    if email:
+        candidate["email"] = email
+    if source_id is not None:
+        cast(list[JSONObject], candidate["sources"])[0]["id"] = source_id
+    if source_value:
+        cast(list[JSONObject], candidate["sources"])[0]["value"] = source_value
+    return candidate
+
+
+def _normalize_candidate_department(
+    value: JSONValue,
+    *,
+    source_kind: str,
+    source_id: int | None = None,
+    source_value: str | None = None,
+) -> JSONObject | None:
+    if not isinstance(value, dict):
+        return None
+    dept_id = _coerce_count(value.get("deptId", value.get("id")))
+    if dept_id is None:
+        return None
+    display_value = (
+        _normalize_optional_text(value.get("deptName"))
+        or _normalize_optional_text(value.get("value"))
+        or _normalize_optional_text(value.get("name"))
+        or str(dept_id)
+    )
+    if not display_value:
+        return None
+    candidate: JSONObject = {"id": dept_id, "value": display_value, "sources": [{"kind": source_kind}]}
+    parent_dept_id = _coerce_count(value.get("parentDeptId"))
+    if parent_dept_id is not None:
+        candidate["parentDeptId"] = parent_dept_id
+    if source_id is not None:
+        cast(list[JSONObject], candidate["sources"])[0]["id"] = source_id
+    if source_value:
+        cast(list[JSONObject], candidate["sources"])[0]["value"] = source_value
+    return candidate
+
+
+def _member_candidate_key(value: JSONValue) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    member_id = _coerce_count(value.get("id", value.get("uid")))
+    if member_id is not None:
+        return f"id:{member_id}"
+    user_id = _normalize_optional_text(value.get("userId"))
+    if user_id:
+        return f"userId:{user_id}"
+    return None
+
+
+def _department_candidate_key(value: JSONValue) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    dept_id = _coerce_count(value.get("id", value.get("deptId")))
+    if dept_id is None:
+        return None
+    return f"id:{dept_id}"
+
+
+def _filter_member_candidates(items: list[JSONObject], keyword: str) -> list[JSONObject]:
+    normalized_keyword = keyword.strip().lower()
+    if not normalized_keyword:
+        return items
+    filtered: list[JSONObject] = []
+    for item in items:
+        haystacks = [
+            _normalize_optional_text(item.get("value")) or "",
+            _normalize_optional_text(item.get("userId")) or "",
+            _normalize_optional_text(item.get("email")) or "",
+        ]
+        if any(normalized_keyword in haystack.lower() for haystack in haystacks if haystack):
+            filtered.append(item)
+    return filtered
+
+
+def _filter_department_candidates(items: list[JSONObject], keyword: str) -> list[JSONObject]:
+    normalized_keyword = keyword.strip().lower()
+    if not normalized_keyword:
+        return items
+    filtered: list[JSONObject] = []
+    for item in items:
+        haystacks = [
+            _normalize_optional_text(item.get("value")) or "",
+            _stringify_json(item.get("id")),
+        ]
+        if any(normalized_keyword in haystack.lower() for haystack in haystacks if haystack):
+            filtered.append(item)
+    return filtered
+
+
+def _scope_has_dynamic_or_external(scope: JSONObject) -> bool:
+    dynamic_items = scope.get("dynamic")
+    external_members = scope.get("externalMemberList")
+    external_departs = scope.get("externalDepartList")
+    return bool(
+        isinstance(dynamic_items, list)
+        and dynamic_items
+        or isinstance(external_members, list)
+        and external_members
+        or isinstance(external_departs, list)
+        and external_departs
+    )
+
+
+def _scope_is_default_all(scope_type: int | None, scope: JSONObject, *, keys: tuple[str, ...]) -> bool:
+    if scope_type == 2:
+        return True
+    if scope_type != 1:
+        return False
+    if _scope_has_dynamic_or_external(scope):
+        return False
+    for key in keys:
+        items = scope.get(key)
+        if isinstance(items, list) and items:
+            return False
+    return True
+
+
+def _normalize_bool(value: JSONValue) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "y", "是"}
+    return False
+
+
 def _field_ref_payload(field: FormField) -> JSONObject:
     payload = {"que_id": field.que_id, "que_title": field.que_title, "que_type": field.que_type}
     if field.aliases: