@qingflow-tech/qingflow-app-user-mcp 1.0.1 → 1.0.3

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.1
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.3
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.1 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.3 qingflow-app-user-mcp
 ```
 
 Environment:

package/docs/local-agent-install.md

@@ -20,6 +20,12 @@
 
 `auth_use_credential` 是本地唯一鉴权主路径。
 
+补充说明：
+
+- 对 stdio MCP 来说，主路径仍然只有 `auth_use_credential`。
+- 如果你是在终端里直接使用 `qingflow` CLI，可以额外使用 `qingflow auth login` 作为“人类登录”入口；默认会提示轻流邮箱和隐藏密码，拿到 `token` 后建立本地 CLI 会话。
+- 也就是说，这次新增的是 CLI 的登录入口，不是给 MCP 增加第二套会话模型。
+
 ## npm 安装器适用场景
 
 适合这类本地 agent / gateway：
@@ -211,7 +217,7 @@ qingflow-app-builder-mcp
       "command": "npx",
       "args": [
         "-y",
-        "@qingflow-tech/qingflow-app-user-mcp"
+        "@josephyan/qingflow-app-user-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -224,7 +230,7 @@ qingflow-app-builder-mcp
       "command": "npx",
       "args": [
         "-y",
-        "@qingflow-tech/qingflow-app-builder-mcp"
+        "@josephyan/qingflow-app-builder-mcp"
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
@@ -266,7 +272,7 @@ npm install
 
 如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
 
-1. 不要混用不同版本的 `@qingflow-tech/qingflow-cli`、`@qingflow-tech/qingflow-app-user-mcp`、`@qingflow-tech/qingflow-app-builder-mcp`
+1. 不要混用不同版本的 `@josephyan/qingflow-cli`、`@josephyan/qingflow-app-user-mcp`、`@josephyan/qingflow-app-builder-mcp`
 2. 删除安装目录下的 `.npm-python`
 3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
 4. 再启动 MCP 客户端

package/npm/lib/runtime.mjs

@@ -287,7 +287,12 @@ function forwardSignal(child, signal) {
   });
 }
 
-export function spawnServer(packageRoot, args, commandName = "qingflow-mcp", { allowRuntimeBootstrap = false } = {}) {
+export function spawnServer(
+  packageRoot,
+  args,
+  commandName = "qingflow-mcp",
+  { allowRuntimeBootstrap = false, stdio = "proxy" } = {},
+) {
   let runtime = inspectPythonEnv(packageRoot, commandName);
   let serverCommand = runtime.serverCommand;
 
@@ -315,12 +320,14 @@ export function spawnServer(packageRoot, args, commandName = "qingflow-mcp", { a
   }
 
   const child = spawn(serverCommand, args, {
-    stdio: ["pipe", "pipe", "pipe"],
+    stdio: stdio === "inherit" ? "inherit" : ["pipe", "pipe", "pipe"],
     env: process.env,
     windowsHide: true,
   });
 
-  proxyStreams(child);
+  if (stdio !== "inherit") {
+    proxyStreams(child);
+  }
   forwardSignal(child, "SIGINT");
   forwardSignal(child, "SIGTERM");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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.0b87"
+version = "1.0.3"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -11,31 +11,35 @@ metadata:
 
 This skill is a lightweight router for operational Qingflow work.
 Assumes MCP is connected, authenticated, and on the correct workspace.
+Before routing, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
 
 ## Default Paths
 
 Route to exactly one of these specialized paths:
 
 1. Record insert  
-   Switch to [$qingflow-record-insert](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-insert/SKILL.md)
+   Switch to [$qingflow-record-insert](../qingflow-record-insert/SKILL.md)
 
 2. Record update  
-   Switch to [$qingflow-record-update](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-update/SKILL.md)
+   Switch to [$qingflow-record-update](../qingflow-record-update/SKILL.md)
 
 3. Record delete  
-   Switch to [$qingflow-record-delete](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-delete/SKILL.md)
+   Switch to [$qingflow-record-delete](../qingflow-record-delete/SKILL.md)
 
 4. Record import  
-   Switch to [$qingflow-record-import](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-import/SKILL.md)
+   Switch to [$qingflow-record-import](../qingflow-record-import/SKILL.md)
 
 5. Task workflow operations  
-   Switch to [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md)
+   Switch to [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
 
 6. Analysis  
-   Switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+   Switch to [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
 
 7. MCP connection / auth / workspace selection  
-   Switch to [$qingflow-mcp-setup](/Users/yanqidong/.codex/skills/qingflow-mcp-setup/SKILL.md)
+   Switch to [$qingflow-mcp-setup](../qingflow-mcp-setup/SKILL.md)
+
+8. App / view / workflow / chart / portal / package configuration
+   Switch to [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)
 
 ## Routing Rules
 
@@ -46,11 +50,13 @@ Route to exactly one of these specialized paths:
 - If the task is about deleting records directly, switch to `$qingflow-record-delete`
 - If the task is about import templates, import capability discovery, import-file verification, authorized local file repair, import execution, or import status, switch to `$qingflow-record-import`
 - 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 package, app, field, layout, workflow, view, chart, portal, visibility, icon, or app base configuration, switch to `$qingflow-app-builder`
 - If the task involves member, department, or relation fields and the user only has natural names/titles, keep the same route; direct write now supports backend-native auto resolution and may return `needs_confirmation` with candidates instead of failing blind
 - If the task involves linked visibility, upstream/downstream field dependencies, reference-driven auto fill, or formula-driven defaulting, keep the same insert/update route and read field-level `linkage` from the schema before composing payloads
 - If the task is about subtable writes, still route to the matching insert/update skill, but shape the payload as parent subtable field -> row array; do not route users toward top-level leaf selectors
 - If the task is insert-focused and readback consistency matters, keep the same route and prefer `record_get / record_list` with `output_profile="normalized"` after the write
 - 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 task discovery by natural language query, still route to `$qingflow-task-ops`; `task_list --query` now uses backend search first and only falls back to local matching when backend returns zero rows
 - 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`
 
@@ -72,8 +78,11 @@ Route to exactly one of these specialized paths:
 
 ## Resources
 
-- Record insert: [$qingflow-record-insert](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-insert/SKILL.md)
-- Record update: [$qingflow-record-update](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-update/SKILL.md)
-- Record delete: [$qingflow-record-delete](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-delete/SKILL.md)
-- Record import: [$qingflow-record-import](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-import/SKILL.md)
-- Dedicated analysis workflow: [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
+- Shared public-surface baseline: [public-surface-sync.md](references/public-surface-sync.md)
+- Record insert: [$qingflow-record-insert](../qingflow-record-insert/SKILL.md)
+- Record update: [$qingflow-record-update](../qingflow-record-update/SKILL.md)
+- Record delete: [$qingflow-record-delete](../qingflow-record-delete/SKILL.md)
+- Record import: [$qingflow-record-import](../qingflow-record-import/SKILL.md)
+- Task workflow operations: [$qingflow-task-ops](../qingflow-task-ops/SKILL.md)
+- Dedicated analysis workflow: [$qingflow-record-analysis](../qingflow-record-analysis/SKILL.md)
+- Builder workflow: [$qingflow-app-builder](../qingflow-app-builder/SKILL.md)

package/skills/qingflow-app-user/references/data-gotchas.md

@@ -1,6 +1,6 @@
 # Data Gotchas
 
-For final statistics, grouped distributions, rankings, trends, or insight-style conclusions, use [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md) instead of keeping that reasoning inside `$qingflow-app-user`.
+For final statistics, grouped distributions, rankings, trends, or insight-style conclusions, use [$qingflow-record-analysis](../../qingflow-record-analysis/SKILL.md) instead of keeping that reasoning inside `$qingflow-app-user`.
 
 ## Record Reads
 

package/skills/qingflow-app-user/references/public-surface-sync.md

@@ -0,0 +1,70 @@
+# Qingflow Core Public Surface Sync
+
+Use this file as the maintenance baseline for the core Qingflow skills.  
+It is not a user-facing product spec. It exists to prevent skill drift.
+
+## Current Public Defaults
+
+### User data
+
+- Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
+- Standard flows:
+  - browse / export detail: `app_get -> record_browse_schema_get -> record_list / record_get`
+  - insert: `record_insert_schema_get -> record_insert`
+  - update: `record_update_schema_get -> record_update`
+  - analyze: `app_get -> record_browse_schema_get -> record_analyze`
+
+### Tasks
+
+- Discovery stays on `task_list`
+- `task_list --query` uses backend search first and only applies local fallback when backend returns zero rows
+- Public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+  - `save_only`
+- `reject` requires `payload.audit_feedback`
+- `save_only` requires non-empty `fields`
+- `TASK_RUNTIME_CONSUMED_AFTER_ACTION` is a normal post-success warning when the current node runtime is consumed and `46001` appears on re-read
+
+### Builder
+
+- Official package entry: `package_get`, `package_apply`
+- Official builder writes:
+  - `app_schema_apply`
+  - `app_layout_apply`
+  - `app_flow_apply`
+  - `app_views_apply`
+  - `app_charts_apply`
+  - `portal_apply`
+  - `app_publish_verify`
+- `portal_apply` edit mode may omit `sections` for base-info-only updates
+- `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
+- `app_get.editability` uses:
+  - `can_edit_app_base`
+  - `can_edit_form`
+  - `can_edit_flow`
+  - `can_edit_views`
+  - `can_edit_charts`
+
+## Known High-Drift Areas
+
+- Task actions, especially `save_only`, reject payload requirements, and `46001` post-action interpretation
+- Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
+- App editability: do not let `can_edit_form` imply app base-info writes
+- Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
+- Analysis fallback: standard path stays `record_analyze`, but complex tables may require explicit fallback modes
+
+## Release Checklist For Skill Maintenance
+
+After each beta that changes public behavior, re-check:
+
+1. `public_surface.py`
+2. `README.md`
+3. `server_app_builder.py` and `server.py` top-level guidance
+4. CLI help for `task`, `builder package`, `builder portal`, `builder charts`
+5. Whether new warnings or verification fields need to be explained in skills
+
+If a tool behavior changed but the public surface did not, prefer updating the relevant skill section instead of expanding this file.

package/skills/qingflow-app-user/references/record-patterns.md

@@ -1,6 +1,6 @@
 # Record Patterns
 
-If the task shifts into grouped analysis, ratio, ranking, trend, or any final statistical conclusion, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md).
+If the task shifts into grouped analysis, ratio, ranking, trend, or any final statistical conclusion, switch to [$qingflow-record-analysis](../../qingflow-record-analysis/SKILL.md).
 
 ## Browse Pattern
 

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

@@ -17,7 +17,42 @@ If `app_get.accessible_views` marks a view with `analysis_supported=false`, do n
 
 This is the ONLY execution order. Never skip `app_get` when the browse range is unclear. Never call `record_analyze` without a browse schema.
 
-Core tools: `app_get`, `record_browse_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples; task/comment work stays in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md).
+Core tools: `app_get`, `record_browse_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples or an explicit fallback. Task/comment work stays in [$qingflow-task-ops](../qingflow-task-ops/SKILL.md).
+
+## Execution Modes
+
+Choose the lightest mode that can still support a trustworthy conclusion:
+
+1. `server_aggregate`
+   - Default and preferred path
+   - Use `record_analyze` directly after `app_get -> record_browse_schema_get`
+
+2. `client_aggregate_from_record_list`
+   - Allowed fallback when `record_analyze` is unstable, unsupported on the target view, or the table is complex enough that service-side aggregation is not trustworthy
+   - Still requires `app_get -> record_browse_schema_get` first
+   - Use only after disclosing that the result is a fallback built from detail rows
+
+3. `cross_app_manual_reconcile`
+   - Use when the question depends on joining multiple apps, organization-history alias mapping, or other business logic that current public tools do not express directly
+   - Be explicit that the conclusion is based on manual reconciliation rules, not one single DSL execution
+
+## Fallback Ladder
+
+Trigger a fallback when any of these are true:
+
+- `record_analyze` is unstable or cannot complete the scan reliably
+- the target view is unsupported for analysis
+- field semantics are ambiguous enough that a server aggregate would be misleading
+- the question requires cross-app reconciliation
+- the question depends on organization-tree scope, historical department aliases, or other business rules that are not first-class MCP filters
+
+When you fall back:
+
+1. Keep the standard read order: `app_get -> record_browse_schema_get`
+2. State which fallback mode you chose
+3. State whether the result is still full-scope or only a verified subset
+4. State the time field, organization scope, and any alias mapping used
+5. Prefer concrete numbers plus a conservative conclusion over broad wording
 
 ---
 
@@ -129,7 +164,7 @@ Top-level arguments:
 - Do not pass field titles, aliases, or guessed ids.
 - If `completeness.statement_scope=returned_groups_only` or `completeness.rows_truncated=true`, downgrade wording to returned groups only.
 - One DSL per question. Multiple small DSLs > one overloaded request.
-- `record_list` is NEVER the basis for final statistics.
+- `record_list` is not the default basis for final statistics. Use it only in an explicit fallback mode and disclose that fallback in the final answer.
 - Set `alias` for any metric you will sort by, compare, or quote.
 
 ---
@@ -137,12 +172,18 @@ Top-level arguments:
 ## OUTPUT
 
 - Final answer must show concrete numbers.
+- Final answer must state which execution mode was used whenever the answer is not a straightforward `server_aggregate`
 - If `result.rows` exists, list each returned row; if there are more than 20 rows, show Top 20 and say so.
 - 占比 = 行指标值 / `result.totals.metric_totals` 总值；如 `metric_totals` 缺失，用各行之和作分母。
 - Prefer the structured `ranking` block when it exists.
 - `safe_for_final_conclusion=true` → `全量可信结论`
 - Otherwise → `初步观察`
 - `rows_truncated=true` → 用 `前 N 个分组`, 不用 `全部`/`所有`
+- If you used a fallback mode, explicitly disclose:
+  - whether this is full-scope or a manually curated subset
+  - which time field was used
+  - which organization scope was used
+  - whether any historical department aliases or cross-app joins were applied
 
 ## Feedback Escalation
 
@@ -152,6 +193,7 @@ Top-level arguments:
 
 ## Resources
 
+- Shared public-surface baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md)
 - DSL templates: [references/dsl-templates.md](references/dsl-templates.md)
 - Analysis patterns: [references/analysis-patterns.md](references/analysis-patterns.md)
 - Confidence reporting: [references/confidence-reporting.md](references/confidence-reporting.md)

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

@@ -36,6 +36,8 @@ metadata:
 13. If the write returns `status="needs_confirmation"`, stop and surface the candidates
 14. Retry with explicit ids / objects only after the user confirms
 15. Keep `verify_write=true` for production inserts
+16. If post-write readback consistency matters, prefer `record_get(..., output_profile="normalized")` and surface `normalized_ambiguous_fields` instead of pretending same-title columns are unambiguous
+17. Treat nested schema shape as guidance, not a brittle contract; do not hard-code transient implementation details like optional nested `field_id` shape when composing inserts
 
 ## Field Notes
 
@@ -56,3 +58,4 @@ metadata:
 - Do not invent missing required fields
 - Do not flatten subtable leaf fields to the top level
 - Do not silently guess member / department / relation ids
+- Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape

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

@@ -33,6 +33,8 @@ metadata:
 11. If the write returns `status="needs_confirmation"`, stop and surface the candidates
 12. Do not assume any arbitrary combination of writable fields will succeed; one single matched accessible view still has to cover the payload
 13. Do not look for any extra context bucket in update schema; lookup behavior stays inline on the field definitions themselves
+14. When update context feels unstable, trust `record_update_schema_get`'s route-aware matched-view result over guessed `view_id` or remembered UI scope
+15. If readback consistency matters, prefer `record_get(..., output_profile="normalized")` after the write and surface `normalized_ambiguous_fields` instead of hiding same-title conflicts
 
 ## Do Not
 
@@ -40,3 +42,4 @@ metadata:
 - Do not update fields missing from `writable_fields`
 - Do not resolve lookup fields against a guessed record context
 - Do not ignore `linkage.affects_fields` when changing source-like fields on complex forms
+- Do not fall back to guessed browse scopes when `record_update_schema_get` already tells you which matched route can or cannot execute the payload

package/skills/qingflow-task-ops/SKILL.md

@@ -11,6 +11,7 @@ metadata:
 
 This skill is for task workflow operations only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
+Before executing, skim the shared maintenance baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md).
 
 ## Default Paths
 
@@ -28,6 +29,9 @@ Use exactly one of these default paths:
 4. Execute workflow action  
    `task_list -> exact target -> task_get -> task_action_execute`
 
+5. Execute a user-specified action on an already-clear target
+   `task_list -> exact target -> (optional task_get) -> task_action_execute`
+
 ## Core Tools
 
 - `task_list`
@@ -43,16 +47,25 @@ Use exactly one of these default paths:
 
 ## Standard Operating Order
 
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Discover the exact target with `task_list`
-4. Read node context with `task_get`
-5. Before giving any approval recommendation, read `task_workflow_log_get`
-6. If `task_get` returns any `associated_reports`, read every visible report through `task_associated_report_detail_get`
-7. Give an approval recommendation only after reviewing the node context, workflow log, and associated report details
-8. Wait for explicit user confirmation before `task_action_execute`
-9. Execute through `task_action_execute`
-10. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, and executed action
+Use one of these two modes:
+
+1. Recommendation mode
+   1. Ensure auth exists
+   2. Ensure workspace is selected
+   3. Discover the exact target with `task_list`
+   4. Read node context with `task_get`
+   5. Before giving any approval recommendation, read `task_workflow_log_get`
+   6. If `task_get` returns any `associated_reports`, read every visible report through `task_associated_report_detail_get`
+   7. Give a recommendation only after reviewing node context, workflow log, and associated reports
+   8. Wait for explicit user confirmation before `task_action_execute`
+
+2. User-directed execution mode
+   1. Ensure auth exists
+   2. Ensure workspace is selected
+   3. Discover the exact target with `task_list`
+   4. If the target or action requirements are ambiguous, read `task_get`; otherwise go straight to `task_action_execute`
+   5. Execute through `task_action_execute`
+   6. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, executed action, and any warnings
 
 ## Task-Center Rules
 
@@ -74,6 +87,7 @@ Use exactly one of these default paths:
   - `unread`
   - `ended`
 - `task_list` is the only public task discovery path in this MCP surface
+- `task_list --query` uses backend `searchKey` first; only when backend returns zero rows does MCP apply a local fallback match on normalized `app_name / workflow_node_name / app_key / record_id`
 - Treat `task_id` as a locator only; the action primary key is `app_key + record_id + workflow_node_id`
 - Default box usage:
   - `todo`: `task_list -> task_get -> task_workflow_log_get / task_associated_report_detail_get -> recommendation -> explicit user confirmation -> task_action_execute`
@@ -91,15 +105,20 @@ Use exactly one of these default paths:
   - `rollback`
   - `transfer`
   - `urge`
+  - `save_only`
 - Before any approve/reject/rollback/transfer recommendation, always review `task_workflow_log_get` when `task_get.visibility.audit_record_visible=true`
 - If `task_get` returns visible `associated_reports`, review each one with `task_associated_report_detail_get`; do not rely on report summary alone
 - Do not give an approval recommendation based only on `task_get`
 - Do not execute `task_action_execute` until the user explicitly confirms the chosen action
+- Exception: if the user has already explicitly authorized a concrete action on exact targets, you may execute directly after exact target resolution
 - Avoid actions on ambiguous tasks or records
 - Summarize the final action and the exact `app_key / record_id / workflow_node_id`
+- `reject` requires `payload.audit_feedback`
+- `save_only` requires non-empty `fields` and is only available when the backend exposes editable fields for the current node
 - `task_action_execute` now distinguishes action execution from workflow continuation. Read `verification.runtime_continuation_verified` before claiming the workflow actually moved on.
 - If `task_action_execute` returns `partial_success` with `WORKFLOW_CONTINUATION_UNVERIFIED`, report the action as sent but the downstream continuation as unverified.
 - If `task_action_execute` returns `TASK_CONTEXT_VISIBILITY_UNVERIFIED` after a `46001`-style context loss, do not claim the task was already processed unless the workflow log or record state proves it.
+- If `task_action_execute` returns `TASK_RUNTIME_CONSUMED_AFTER_ACTION`, treat that as a normal post-success state: the current node runtime was consumed, the workflow likely continued, and `46001` does not by itself mean the action failed
 
 ## Feedback Escalation
 
@@ -110,11 +129,13 @@ Use exactly one of these default paths:
 ## Response Interpretation
 
 - `task_list` returns normalized todo rows and is the only default discovery path
+- `task_list` may return `TASK_LIST_QUERY_FALLBACK_APPLIED`; this means backend search missed the query and MCP recovered the result through local exact-field fallback
 - `task_get` returns node context summary, not full historical report data
 - `task_associated_report_detail_get` may return either:
   - `result_type=view_list`
   - `result_type=chart_data`
 - `task_workflow_log_get` returns workflow log detail only when the node grants log visibility
+- A successful approve/reject/rollback/transfer may still lose the current-node runtime immediately; treat `record_state_readable=false + backend 46001` as a post-action runtime loss unless continuation verification says otherwise
 - Treat `request_route` as the source of truth for live route debugging
 - If only part of the requested work is completed, explicitly disclose which parts are done and which are not
 

package/src/qingflow_mcp/__init__.py

@@ -1,5 +1,37 @@
 from __future__ import annotations
 
+from importlib.metadata import PackageNotFoundError, packages_distributions, version as _dist_version
+from pathlib import Path
+
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b87"
+_FALLBACK_VERSION = "0.2.0b998"
+
+
+def _resolve_local_pyproject_version() -> str | None:
+    module_path = Path(__file__).resolve()
+    for parent in module_path.parents:
+        candidate = parent / "pyproject.toml"
+        if not candidate.is_file():
+            continue
+        for line in candidate.read_text(encoding="utf-8").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("version = "):
+                return stripped.split("=", 1)[1].strip().strip('"')
+        break
+    return None
+
+
+def _resolve_runtime_version() -> str:
+    local_version = _resolve_local_pyproject_version()
+    if local_version:
+        return local_version
+    for dist_name in packages_distributions().get("qingflow_mcp", []):
+        try:
+            return _dist_version(dist_name)
+        except PackageNotFoundError:
+            continue
+    return _FALLBACK_VERSION
+
+
+__version__ = _resolve_runtime_version()

package/src/qingflow_mcp/builder_facade/models.py

@@ -819,6 +819,10 @@ class FieldMutation(StrictModel):
         validation_alias=AliasChoices("custom_button_text", "customButtonText", "custom_btn_text", "customBtnText"),
     )
     subfields: list[FieldPatch] | None = None
+    subfield_updates: list["FieldUpdatePatch"] | None = Field(
+        default=None,
+        validation_alias=AliasChoices("subfield_updates", "subfieldUpdates"),
+    )
 
     @model_validator(mode="after")
     def validate_shape(self) -> "FieldMutation":
@@ -848,8 +852,12 @@ class FieldMutation(StrictModel):
             or self.custom_button_text is not None
         ):
             raise ValueError("code_block_config, code_block_binding, auto_trigger, custom_button_text_enabled, and custom_button_text are only allowed for code_block fields")
-        if self.type == PublicFieldType.subtable and not self.subfields:
-            raise ValueError("subtable field requires subfields")
+        if self.type == PublicFieldType.subtable and not self.subfields and not self.subfield_updates:
+            raise ValueError("subtable field requires subfields or subfield_updates")
+        if self.type is not None and self.type != PublicFieldType.subtable and self.subfield_updates:
+            raise ValueError("subfield_updates are only allowed for subtable fields")
+        if self.subfields and self.subfield_updates:
+            raise ValueError("subfields and subfield_updates cannot be used together")
         return self
 
     @model_validator(mode="before")
@@ -1528,14 +1536,16 @@ class PortalApplyRequest(StrictModel):
             raise ValueError("package_tag_id is required when dash_key is empty")
         if not self.dash_key and not self.dash_name:
             raise ValueError("dash_name is required when creating a portal")
-        if not self.sections:
-            raise ValueError("portal apply requires a non-empty sections list")
+        if not self.dash_key and not self.sections:
+            raise ValueError("portal apply requires a non-empty sections list when creating a portal")
         if self.visibility is not None and self.auth is not None:
             raise ValueError("visibility and auth cannot be provided together")
         return self
 
 
 FieldPatch.model_rebuild()
+FieldMutation.model_rebuild()
+FieldUpdatePatch.model_rebuild()
 
 
 class AppGetResponse(StrictModel):