@josephyan/qingflow-app-user-mcp 0.2.0-beta.985 → 0.2.0-beta.987

package/README.md

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

package/docs/local-agent-install.md

@@ -6,6 +6,20 @@
 2. 记录/待办优先的 `qingflow-app-user-mcp`
 3. 精简 builder 的 `qingflow-app-builder-mcp`
 
+## 本地鉴权推荐方案
+
+本地模式现在推荐优先使用 `credential` 建立会话，而不是直接注入 `token`。
+
+推荐链路：
+
+1. createClaw 或其它本地宿主为当前实例保存 `credential`
+2. 本地 MCP 调用 `auth_use_credential`
+3. MCP 用该 `credential` 请求 apaas `/mcp/auth/context`
+4. 解析并保存 `token / wsId / qfVersion / uid`
+5. 业务工具直接使用这份上下文
+
+`auth_use_credential` 是本地唯一鉴权主路径。
+
 ## npm 安装器适用场景
 
 适合这类本地 agent / gateway：
@@ -63,17 +77,17 @@ npm run pack:npm
 会生成：
 
 ```bash
-dist/npm/josephyan-qingflow-cli-<version>.tgz
-dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
-dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
+dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
+dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
+dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
 
 然后在目标机器安装：
 
 ```bash
-npm install /absolute/path/to/dist/npm/josephyan-qingflow-cli-<version>.tgz
-npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
-npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
 ```
 
 安装时会自动：
@@ -136,7 +150,10 @@ qingflow-app-builder-mcp
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -153,7 +170,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -170,7 +190,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -191,7 +214,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-user-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     },
     "qingflow-builder": {
@@ -201,7 +227,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-builder-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -212,6 +241,7 @@ qingflow-app-builder-mcp
 - 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow.mjs`、`node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
 - `npx` 方式适合临时安装或容器化本地 agent
 - 全局安装方式更适合长期固定使用的本机开发环境
+- 计费接口使用当前登录会话的 `token` 与 `wsId` 请求头，可通过 `QINGFLOW_MCP_CREDIT_APAAS_BASE_URL/PATH` 覆盖调用记录接口地址
 
 ## 排障
 
@@ -242,3 +272,32 @@ npm install
 4. 再启动 MCP 客户端
 
 现在 stdio MCP 入口会拒绝在启动瞬间“边启动边重建 Python 运行时”，因为安装日志一旦写进 stdout，就会破坏 MCP 握手并表现成 `Transport closed`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。
+
+## createClaw 本地接入示例
+
+如果 createClaw 已经为当前本地实例保存了 `credential`，推荐在首次建链时调用：
+
+```bash
+qingflow auth use-credential \
+  --base-url https://qingflow.com/api \
+  --credential-stdin
+```
+
+然后把 `credential` 写到 stdin。
+
+等价 MCP 工具调用参数：
+
+```json
+{
+  "profile": "default",
+  "base_url": "https://qingflow.com/api",
+  "credential": "1602853_277941",
+  "persist": false
+}
+```
+
+说明：
+
+- 本地会把解析后的 `token` 和原始 `credential` 写入 profile 文件，用于后续 CLI 命令恢复会话
+- `persist=true` 时，本地还会优先把解析后的 `token` 和原始 `credential` 同步写入系统 keychain
+- 当前工作区以 `/mcp/auth/context` 返回的 `wsId` 为准，不再通过本地 MCP 显式切换

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.985",
+  "version": "0.2.0-beta.987",
   "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.0b985"
+version = "0.2.0b987"
 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

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b985"
+_FALLBACK_VERSION = "0.2.0b987"
 
 
 def _resolve_local_pyproject_version() -> str | None: