@josephyan/qingflow-app-user-mcp 0.2.0-beta.49 → 0.2.0-beta.50

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.49",
+  "version": "0.2.0-beta.50",
   "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.0b49"
+version = "0.2.0b50"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -34,6 +34,10 @@ Route to exactly one of these specialized paths:
 - 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, 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 creating new records or importing data, prefer `$qingflow-record-crud` under applicant-node schema semantics
+- If the task is about updating an existing record directly, require an explicit accessible `view_id` and then route to `$qingflow-record-crud`
+- If the task is about subtable writes, still route to `$qingflow-record-crud`, but shape the payload through the parent subtable field `rows/tableValues`; do not route users toward top-level leaf selectors
+- If the user sounds like an ordinary workflow assignee rather than a system operator, prefer `$qingflow-task-ops` over direct record mutation whenever both paths could fit
 - 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

@@ -18,9 +18,10 @@ 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. 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`
+3. Insert records: `record_schema_get(schema_mode="applicant") -> record_write(operation="insert")`
+4. Update records: `app_get -> choose accessible view -> record_schema_get(schema_mode="browse", view_id=...) -> record_write(operation="update", view_id=...)`
+5. Run a code-block field: `record_schema_get(schema_mode="applicant") -> record_code_block_run`
+6. Import records: `record_import_template_get -> record_import_verify -> (optional authorized file repair) -> record_import_start -> record_import_status_get`
 
 ## Core Tools
 
@@ -36,7 +37,9 @@ Use exactly one of these default paths:
 - `record_import_status_get`
 
 `record_schema_get(schema_mode="applicant")` exposes the current user's applicant-node visible write/create fields.
+Its top-level `fields` now list only direct applicant-write fields; subtable leaf columns stay under the parent subtable field's `write_format.subfields`.
 `record_schema_get(schema_mode="browse", view_id=...)` exposes browse-schema fields for the selected accessible view.
+In browse mode, `writable=true` means `record_write(operation="update", view_id=...)` can target that field in the selected view; `writable=false` means the chosen view blocks direct update for that field.
 Read top-level `fields` and `suggested_*`; if a field is missing, treat it as unavailable in the current permission scope.
 
 ## Supporting Tools
@@ -68,9 +71,13 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 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
+12. For `insert`, stay on `schema_mode="applicant"` and do not introduce any view selector
+13. For `update`, call `app_get` first, choose an accessible view, and carry that `view_id` into `record_write`
+14. For subtable writes, use the parent subtable field and submit `rows/tableValues`; do not treat subtable leaf titles as top-level write selectors
+15. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
+16. For high-risk writes or production changes, read the current state first whenever practical
+17. After actions, report the affected `record_id`, counts, or returned item count
+18. If the user is an approver, filler, or ordinary workflow assignee rather than a system operator, prefer [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md) over direct record mutation
 
 ## Record Read Rules
 
@@ -91,14 +98,18 @@ Use `record_write` as the only default write tool.
 
 1. Run `record_schema_get(schema_mode="applicant")`
 2. Decide whether the task is `insert`, `update`, or `delete`
-3. For relation fields, read `target_app_key / target_app_name` from schema first
-4. For member fields with unknown ids, run `record_member_candidates`
-5. For department fields with unknown ids, run `record_department_candidates`
-6. Build SQL-like JSON clauses
-7. Run `record_write`
-8. If `ok=false`, explain `field_errors` first, then summarize blockers; do not report a write as executed
-9. If `ok=true`, report the affected `record_id` or created resource
-10. For important writes, keep `verify_write=true`
+3. If this is workflow work for an ordinary assignee, switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md) instead of forcing direct CRUD
+4. If this is `insert`, stay on applicant schema only and do not pass any `view_*` selector
+5. If this is `update`, choose an accessible view first, inspect `record_schema_get(schema_mode="browse", view_id=...)`, and pass that `view_id` into `record_write`
+6. For relation fields, read `target_app_key / target_app_name` from schema first
+7. For member fields with unknown ids, run `record_member_candidates`
+8. For department fields with unknown ids, run `record_department_candidates`
+9. For subtable writes, target the parent subtable field and fill `rows/tableValues`; subtable leaf titles are not valid top-level `record_write` selectors
+10. Build SQL-like JSON clauses
+11. Run `record_write`
+12. If `ok=false`, explain `field_errors` first, then summarize blockers; do not report a write as executed
+13. If `ok=true`, report the affected `record_id` or created resource
+14. For important writes, keep `verify_write=true`
 
 ### SQL-like JSON DSL
 
@@ -115,6 +126,11 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - `insert` uses `values`
 - `update` uses `set`
 - `delete` uses `record_id` or `record_ids`
+- `insert` strictly follows applicant-node write scope and does not accept `view_id / list_type / view_key / view_name`
+- `update` must carry an explicit `view_id / list_type / view_key / view_name`; prefer `view_id` chosen from `app_get.accessible_views`
+- `update` should be treated as “view-scoped direct edit”, not as a task or approval shortcut
+- `record_schema_get(schema_mode="browse").fields[*].writable` is the contract for whether the selected view allows direct update on that field
+- subtable writes must go through the parent subtable field with `rows/tableValues`; top-level subtable leaf selectors now fail fast
 - Do not send raw SQL text
 - Do not invent formulas or expressions
 - Do not use free-form `WHERE` updates or deletes
@@ -133,6 +149,7 @@ The DSL is clause-shaped like SQL, but it is **not raw SQL text**.
 - `department`: `✅ {"field_id":22,"value":{"id":336193,"value":"北斗组"}}` / `✅ {"field_id":22,"value":"北斗组"}` only when it exactly matches a current candidate / `❌ {"field_id":22,"value":"不存在的部门"}`
 - `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"}`
+- `subtable`: `✅ {"field_id":18,"value":{"rows":[{"产品名称":"企业版","数量":2}]}}` / `✅ {"field_id":18,"value":{"tableValues":[{"queId":101,"values":[{"value":"企业版"}]},{"queId":102,"values":[{"value":2}]}]}}` / `❌ {"field_id":101,"value":"企业版"}`
 
 ## Code Block Rules
 
@@ -199,7 +216,11 @@ Use the import tools for file-based bulk data loading, not `record_write`.
 - If `view_id` is a custom view, treat the result as convenience browse output only when `warnings` includes `CUSTOM_VIEW_FILTER_UNVERIFIED`. In that case do not state the saved filter result as a verified fact.
 - Prefer `system:all` plus explicit `where` filters whenever the user needs a trustworthy scoped dataset.
 - `record_write` always performs internal static preflight before any apply
+- `record_write insert` is validated strictly against applicant-node create scope
+- `record_write update` is validated against the selected view for field scope, then against real record edit permission
+- if a subtable leaf is missing from applicant top-level schema, that is expected; inspect the parent subtable field's `write_format.subfields`
 - If `record_write` returns `ok=false`, the write was blocked and not executed
+- If `record_write` raises `WRITE_PERMISSION_DENIED`, explain that direct edit permission is missing and prefer task-center actions for ordinary workflow users
 - Prefer explaining `field_errors` before summarizing top-level blockers
 - If `record_write` returns `ok=true`, still check `verification` and `warnings` before claiming success
 - Prefer canonical schema titles and aliases in your final wording

package/src/qingflow_mcp/builder_facade/models.py

@@ -28,6 +28,11 @@ class PublicFieldType(str, Enum):
     subtable = "subtable"
 
 
+class PublicRelationMode(str, Enum):
+    single = "single"
+    multiple = "multiple"
+
+
 FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
     "textarea": PublicFieldType.long_text,
     "amount": PublicFieldType.amount,
@@ -268,6 +273,7 @@ class FieldPatch(StrictModel):
     target_app_key: str | None = None
     display_field: FieldSelector | None = None
     visible_fields: list[FieldSelector] = Field(default_factory=list)
+    relation_mode: PublicRelationMode | None = Field(default=None, validation_alias=AliasChoices("relation_mode", "relationMode", "selection_mode", "selectionMode"))
     subfields: list["FieldPatch"] = Field(default_factory=list)
 
     @model_validator(mode="after")
@@ -276,8 +282,8 @@ class FieldPatch(StrictModel):
             raise ValueError("relation field requires target_app_key")
         if self.type != PublicFieldType.relation and self.target_app_key:
             raise ValueError("target_app_key is only allowed for relation fields")
-        if self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields):
-            raise ValueError("display_field and visible_fields are only allowed for relation fields")
+        if self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields or self.relation_mode is not None):
+            raise ValueError("display_field, visible_fields, and relation_mode are only allowed for relation fields")
         if self.type == PublicFieldType.subtable and not self.subfields:
             raise ValueError("subtable field requires subfields")
         if self.type != PublicFieldType.subtable and self.subfields:
@@ -299,14 +305,15 @@ class FieldMutation(StrictModel):
     target_app_key: str | None = None
     display_field: FieldSelector | None = None
     visible_fields: list[FieldSelector] | None = None
+    relation_mode: PublicRelationMode | None = Field(default=None, validation_alias=AliasChoices("relation_mode", "relationMode", "selection_mode", "selectionMode"))
     subfields: list[FieldPatch] | None = None
 
     @model_validator(mode="after")
     def validate_shape(self) -> "FieldMutation":
         if self.type == PublicFieldType.relation and not self.target_app_key:
             raise ValueError("relation field requires target_app_key")
-        if self.type is not None and self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields):
-            raise ValueError("display_field and visible_fields are only allowed for relation fields")
+        if self.type is not None and self.type != PublicFieldType.relation and (self.display_field is not None or self.visible_fields or self.relation_mode is not None):
+            raise ValueError("display_field, visible_fields, and relation_mode are only allowed for relation fields")
         if self.type == PublicFieldType.subtable and not self.subfields:
             raise ValueError("subtable field requires subfields")
         return self
@@ -915,11 +922,30 @@ def _normalize_field_payload(value: Any) -> Any:
         normalized_from_id = FIELD_TYPE_ID_ALIASES.get(raw_type)
         if normalized_from_id is not None:
             payload["type"] = normalized_from_id.value
-            return payload
     if isinstance(raw_type, str):
         normalized = FIELD_TYPE_ALIASES.get(raw_type.strip().lower())
         if normalized is not None:
             payload["type"] = normalized.value
+    normalized_relation_mode = _normalize_public_relation_mode(
+        payload.get("relation_mode", payload.get("relationMode", payload.get("selection_mode", payload.get("selectionMode"))))
+    )
+    if normalized_relation_mode is None:
+        for alias_key in ("optional_data_num", "optionalDataNum", "multiple", "allow_multiple"):
+            if alias_key in payload:
+                normalized_relation_mode = _normalize_public_relation_mode(payload.get(alias_key))
+                break
+    if normalized_relation_mode is not None:
+        payload["relation_mode"] = normalized_relation_mode
+    for alias_key in (
+        "relationMode",
+        "selection_mode",
+        "selectionMode",
+        "optional_data_num",
+        "optionalDataNum",
+        "multiple",
+        "allow_multiple",
+    ):
+        payload.pop(alias_key, None)
     return payload
 
 
@@ -927,3 +953,33 @@ def _slugify_title(title: str) -> str:
     normalized = "".join(ch.lower() if ch.isalnum() else "_" for ch in str(title or ""))
     collapsed = "_".join(part for part in normalized.split("_") if part)
     return collapsed or "section"
+
+
+def _normalize_public_relation_mode(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return PublicRelationMode.multiple.value if value else PublicRelationMode.single.value
+    if isinstance(value, int):
+        if value == 0:
+            return PublicRelationMode.multiple.value
+        if value == 1:
+            return PublicRelationMode.single.value
+        return None
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        aliases = {
+            "single": PublicRelationMode.single.value,
+            "single_select": PublicRelationMode.single.value,
+            "single-select": PublicRelationMode.single.value,
+            "one": PublicRelationMode.single.value,
+            "1": PublicRelationMode.single.value,
+            "multiple": PublicRelationMode.multiple.value,
+            "multi": PublicRelationMode.multiple.value,
+            "multi_select": PublicRelationMode.multiple.value,
+            "multi-select": PublicRelationMode.multiple.value,
+            "many": PublicRelationMode.multiple.value,
+            "0": PublicRelationMode.multiple.value,
+        }
+        return aliases.get(normalized, normalized or None)
+    return None