@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

package/skills/qingflow-cli/reference/record/insert/README.md

@@ -0,0 +1,125 @@
+# Qingflow CLI Record Insert
+
+## Default Path
+
+`record schema insert -> record insert --items-file -> optional record get/readback`
+
+Default to batch-shaped insert. A single new record is `items` with one row.
+
+## Core Tools
+
+- `qingflow record schema insert`
+- `qingflow record insert --items-file`
+- `qingflow record member-candidates`
+- `qingflow record department-candidates`
+- file upload command when attachments are required
+
+## Working Rules
+
+1. Start with `record schema insert`
+2. Read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`
+3. Inside every field bucket, read field-level `linkage` first when present; it is the canonical static hint for linked visibility, reference-driven auto fill, or formula-driven fields
+4. Inside `optional_fields`, pay special attention to any field with `may_become_required=true`; these are writable fields that can become required when linked visibility or option-driven rules activate
+5. Build `items` as `[{"fields": {...}}]`, where each `fields` map uses field titles from the insert schema
+6. Treat `runtime_linked_required_fields` as required-but-not-directly-writable runtime/upstream dependencies, not as fields to hand-fill blindly
+7. For `linkage.kind=logic_visibility`, read `sources` as upstream trigger fields and treat `role=manual_input_after_activation` as "fill this only after the upstream condition is satisfied"
+8. For `linkage.kind=reference_fill`, prefer filling the source field first; treat target fields with `role=auto_fill_preferred` or `auto_fill_only` as reference-driven outputs rather than blind manual inputs
+9. For `linkage.kind=formula_fill`, treat the field as formula/default-auto-fill driven unless the user explicitly asks to override it and the field is still writable
+10. If insert succeeds and single-record detail/readback matters, prefer `record get`; use `record list` only for batch row-shaped normalized readback
+11. Keep subtable payloads under the parent field as a row array
+12. Member / department / relation fields may accept natural strings directly, such as `"张三"`, `"直销部"`, or `"海军军医大学"`; do not pre-query ids by default
+13. If the write returns `status="needs_confirmation"`, stop and surface the candidates
+14. Retry failed rows only with explicit ids / objects after the user confirms
+15. Keep `verify_write=true` for production inserts
+16. If post-write detail context matters, read `record get` fields, `media_assets.items[].local_path`, `file_assets.items[].local_path`, `file_assets.items[].extraction.text_path`, and `semantic_context`; `record get` follows the frontend storage cookie redirect path for Qingflow attachments, so prefer local paths over remote URLs and do not expect legacy `data.normalized_record`
+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
+18. For `partial_success`, read `created_record_ids`, then repair only the failed `items[].row_number` using `failed_fields`; never retry the whole batch after any row has `write_executed=true`
+19. For numeric / amount-like fields, follow insert schema `expected_format` and `example_value`, not the builder field name alone. If the schema or error says decimals are not allowed, retry only the failed row with an integer value.
+
+## Field Value Quick Table
+
+Use this table after reading `record schema insert`. Field titles, options, candidates, and requiredness always come from the schema of the target app.
+
+| Field kind | Write value | Notes |
+| --- | --- | --- |
+| Text / long text | JSON string | Use exact field title as key. Do not write system fields such as `编号` or `创建时间`. |
+| Number / amount / score / rate | JSON number | Follow `expected_format`, `example_value`, and `allow_decimal`; if decimals are rejected, retry failed rows only with integers. |
+| Date | `YYYY-MM-DD` | Use schema format if it differs. |
+| Datetime | `YYYY-MM-DD HH:mm:ss` | Keep timezone/business date consistent with the user's request. |
+| Single select | Exact option text or option id | Option text must exist in schema `options`; do not invent synonyms such as `月检` when the option is `每月`. |
+| Multi select | Array of exact option texts or ids | Example: `["重点", "续约"]`. |
+| Boolean / yes-no | Schema-supported boolean value | Prefer the schema example; some apps use option-like text. |
+| Member | Natural name first, candidate object/id only after `needs_confirmation` | Example: `"张三"`. Do not pre-query admin contacts by default. |
+| Department | Natural department name first, candidate object/id only after `needs_confirmation` | Example: `"销售部"`. Do not use ContactAuth/admin department tree as fallback. |
+| Relation / reference record | Real `record_id/apply_id` for batch-created upstream rows; natural name only when unique | In full systems, insert upstream master data first, then use returned ids for downstream rows. |
+| Subtable | Parent field value is an array of row objects | Keep subtable leaf fields inside the parent array; do not flatten subfields to top level. |
+| Attachment | Upload first, then write returned attachment value/object | Do not write a local path directly unless the upload command returned that shape. |
+| Formula / reference-fill / auto-fill | Fill the source/driver field, not the auto-filled target | Override only if schema says writable and user explicitly asks. |
+
+## Copyable Shape Example
+
+This file shape is the default for both one row and many rows. Replace field titles, option texts, record ids, and attachment values with values from `record schema insert`.
+
+```json
+[
+  {
+    "fields": {
+      "客户名称": "上海样例客户",
+      "客户状态": "有效",
+      "客户标签": ["重点", "续约"],
+      "预计金额": 12000,
+      "预计签约日期": "2026-07-15",
+      "负责人": "张三",
+      "所属部门": "销售部",
+      "关联客户": "540000000000000001",
+      "明细子表": [
+        {"明细名称": "首批巡检", "数量": 2, "结果": "正常"}
+      ],
+      "备注": "由 CLI 样例创建"
+    }
+  }
+]
+```
+
+Full shape example: [record_insert_all_field_types.example.json](../../examples/record/record_insert_all_field_types.example.json).
+
+## Field Notes
+
+- `searchable_fields` on relation fields defines the backend-native searchable columns
+- `accepts_natural_input=true` means the field may accept a natural string before explicit id fallback
+- `may_become_required=true` means the field is writable now, but may turn required after linked visibility or option rules activate
+- `linkage.kind=logic_visibility` means the field is statically tied to linked visibility or option-driven rules
+- `linkage.kind=reference_fill` means the field participates in reference-based auto fill or default matching logic
+- `linkage.kind=formula_fill` means the field usually comes from formula/default auto-fill logic
+- `linkage.sources` lists the upstream field titles that influence the current field
+- `linkage.affects_fields` lists downstream field titles that may change when this field changes
+- `linkage.role=auto_fill_only` means "normally do not hand-fill this unless the product explicitly requires it"
+- `requires_upload=true` means upload the file first, then write the returned value
+- `failed_fields[].next_action` tells the next repair step for that row
+- `allow_decimal=false` or errors like `requires an integer amount` mean the current write path wants an integer even if the business label says hours, rate, or score
+
+## CLI Pattern
+
+Use a JSON array file:
+
+```bash
+qingflow record insert --app-key APP_KEY --items-file records.json --json
+```
+
+`records.json`:
+
+```json
+[
+  { "fields": { "客户名称": "测试客户", "负责人": "张三" } }
+]
+```
+
+## Do Not
+
+- Do not skip `record schema insert`
+- Do not invent missing required fields
+- Do not flatten subtable leaf fields to the top level
+- Do not pre-query or silently guess member / department / relation ids when a natural string is enough
+- Do not retry a whole batch after `created_record_ids` is non-empty
+- Do not bind logic to a transient nested schema serialization detail when the field title and parent table already identify the legal payload shape
+- Do not infer decimal support from the field label or builder type; the insert schema is the write contract

package/skills/qingflow-cli/reference/schema_apply_add_fields_all_types.json

@@ -3,7 +3,7 @@
     "name": "QFCLI_AT_text",
     "type": "text",
     "as_data_title": true,
-    "description": "【本文件用法】推荐一次成功：npx @qingflow-tech/qingflow-cli --profile default builder schema apply --package-id <你的包tag_id> --app-name \"新应用名\" --create-if-missing --no-publish --add-fields-file schema_apply_add_fields_all_types.json。内含19种搭建 type（另含远程查询/代码块所需辅助 text），且已在本字段标记 as_data_title。关联字段 target_app_key 默认为本仓库实测用的模板应用 ead8ims5i401（须含「单行文字」「多行文字」）；其它租户请改成你方可读的目标应用 app_key。若用 --app-key 向已有应用追加：须无「关联」字段且字段名不重复；每应用仅允许一个 relation。"
+    "description": "【本文件用法】字段能力覆盖探针，不是正式新建应用主模板。正式新建应用优先使用 form；完整系统优先使用 examples/schema/schema_multi_app_form_relation_layout.example.json。此文件用于测试 19 种搭建 type（另含远程查询/代码块所需辅助 text），关联字段 target_app_key 默认为本仓库实测模板应用 ead8ims5i401；其它租户请改成你方可读的目标应用 app_key。"
   },
   {"name": "QFCLI_AT_long_text", "type": "long_text"},
   {"name": "QFCLI_AT_number", "type": "number"},

package/skills/qingflow-cli/reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md

@@ -0,0 +1,153 @@
+# 任务上下文 SOP：待办列表 → 详情 → 审批历史 → 关联报表 → 执行动作
+
+本文与 **MCP / 服务端公开工具命名**对齐，并给出已安装的 `**qingflow` CLI** 等价命令。编写前已在当前环境对 `**task list` / `task get` / `task log`** 实跑；`**task report`** 在抽样任务上遇到过后端 `**40038` Object not exist**（见文末「实测排障」），属数据/权限/报表生命周期问题，**不否定**标准编排顺序。
+
+**必须落盘**：`task` 的 `list`、`get`、`log`、`report` 以及 `**task action` 的响应**若体积大，均应 `> tmp/qingflow_*.json`，与主技能 [SKILL.md](../../SKILL.md) 一致。
+
+**输出解包**：`task list/get/log/report` 的主数据通常在 `data` 下，不要求有顶层 `status`。没有顶层 `status` 不代表失败；先检查是否有错误字段，再按 `task list -> data.items[]`、`task get -> data.task / data.available_actions`、`task log -> data.items[]`、`task report -> data` 解包。
+
+---
+
+## 1. 编排顺序（固定）
+
+
+| 步骤  | 工具名（文档/编排常用）                        | CLI 子命令                         | 说明                                                                            |
+| --- | ----------------------------------- | ------------------------------- | ----------------------------------------------------------------------------- |
+| 1   | `task_list`                         | `qingflow [--json] task list`   | `--task-box todo` 为待办（可省略则默认 todo）                                            |
+| 2   | `task_get`                          | `qingflow [--json] task get`    | **优先** `--task-id`；从响应中取动作能力、关联报表摘要                                           |
+| 3   | `task_workflow_log_get`             | `qingflow [--json] task log`    | 当前任务上下文的流程/审批历史条目（与详情独立接口，勿与 `extras.workflow_log` 混为一谈；记录级全量日志用 `record logs`） |
+| 4   | `task_associated_report_detail_get` | `qingflow [--json] task report` | **必须** `--report-id`；ID 来自 **步骤 2** 的关联报表列表                                   |
+| 5   | `task_action_execute`               | `qingflow [--json] task action` | **无 `--dry-run`**；调用即生效，`**--action` 须落在 `task get` 的 `available_actions` 内** |
+
+
+实现侧 CLI 将上述工具映射到 `qingflow_mcp` 的 `TaskContextTools`（`task` 子命令源码：`task list/get/log/report/action` → `task_list`、`task_get`、`task_workflow_log_get`、`task_associated_report_detail_get`、`task_action_execute`）。
+
+---
+
+## 2. 定位方式
+
+- **唯一默认路径**：全程使用列表里拿到的 `**task_id`**（字符串十进制；与大雪花 ID 一致时保持 **引号 / JSON 字符串** 习惯，避免其它子系统精度问题）。`task_id` 必须来自 `task_list.data.items[].task_id`，不是列表序号、record_id 或 workflow_node_id。
+- `task_action_execute` / `task action` **只使用 `task_id` 定位**。不要传 `app_key`、`record_id`、`workflow_node_id`，也不要从其它输出里自行拼三键。
+- `task get` / `task log` / `task report` 的底层读接口仍可能保留完整 locator 作为兼容排障能力；主链路不使用。
+
+---
+
+## 3. 步骤说明与命令模板
+
+### 3.1 `task_list`（`task list`）
+
+```bash
+qingflow --json task list \
+  --task-box todo \
+  --flow-status all \
+  --page 1 \
+  --page-size 50 \
+  > tmp/qingflow_tasks_todo.json
+```
+
+- `**--task-box**`：`todo`（待办）、`done`（已办）、`cc`（抄送）、`initiated`（我发起）等；与 `**--flow-status**`（箱内流程状态）为 **两个独立维度**，可同一次请求带给后端。
+- `**--query`**：优先走后端检索；若后端零条，公开列表可能 **本地回退**匹配应用名、节点名、`app_key`、`record_id`（JSON 中可能出现 `TASK_LIST_QUERY_FALLBACK_APPLIED` 类警告）。
+- `**--app-key`**：列表阶段 **常省略**（不按应用过滤）；与下钻阶段不同。
+
+从 `data.items[]` 取 `**task_id`** 进入下一步。
+
+### 3.2 `task_get`（`task get`）
+
+```bash
+qingflow --json task get \
+  --task-id "<TASK_ID>" \
+  > tmp/qingflow_task_get.json
+```
+
+可选（默认开启，大响应可关）：`--no-include-candidates`、`--no-include-associated-reports`。
+
+**解析要点**（以 CLI `--json` 紧凑载荷为准，字段名以你环境实际 JSON 为准）：
+
+- `**data.task`**：`app_key`、`record_id`、`workflow_node_id`、`workflow_node_name`、`actionable`、`task_id`。
+- `**data.available_actions`**：当前节点 **允许** 的动作子集（**下文 `task action` 的 `--action` 必须落在此列表中**，否则 CLI 报 config）。
+- `**data.editable_fields`**：可编辑字段（与 `**save_only`** 等配合）。
+- `**data.extras**`：摘要信息，例如 `**workflow_log**`（是否可见、条数提示等）、`**associated_reports**`（`count`、`items[]`，每项含 `**report_id**` / `chart_key` / `chart_name` 等）。
+
+### 3.3 `task_workflow_log_get`（`task log`）
+
+```bash
+qingflow --json task log \
+  --task-id "<TASK_ID>" \
+  > tmp/qingflow_task_log.json
+```
+
+- 典型结构：`data.items[]` 含节点、操作者、`operation`、`operation_time`、备注与附件等（具体字段以后端为准）。
+- `**data.visibility**`：审计/机器人日志可见性等元数据。
+- 这不是记录详情页的全量数据日志工具；如果用户要某条记录的完整数据日志 + 流程日志，先定位 `app_key/record_id/view_id`，再用 `qingflow --json record logs ...`。
+
+### 3.4 `task_associated_report_detail_get`（`task report`）
+
+1. 在 `**task get**` 的 `**data.extras.associated_reports.items**` 中选一条，读取其 `**report_id**`（整数）。
+2. 若 `**count == 0**`，跳过本步，无 `**--report-id**` 可填。
+
+```bash
+qingflow --json task report \
+  --task-id "<TASK_ID>" \
+  --report-id <REPORT_ID> \
+  --page 1 \
+  --page-size 20 \
+  > tmp/qingflow_task_report.json
+```
+
+- 定位方式与 `task get` 相同：默认传 `task_list.data.items[].task_id`。
+- 若关联项是 QingBI 报表，详情读取优先走前端同源的 **`/qingbi/charts/data/qflow/{chartId}/detail`**，再按 qflow `asos` 降级；只有 qflow 路由明确不存在/不适用时才退回旧 BI 数据接口。不要把中间 **`CHART_SEE` / 40002** 当成任务关联报表最终不可见。
+
+### 3.5 `task_action_execute`（`task action`）
+
+```bash
+qingflow --json task action \
+  --task-id "<TASK_ID>" \
+  --action <ACTION> \
+  [--payload-file tmp/task_action_payload.json] \
+  [--fields-file tmp/task_action_fields.json] \
+  > tmp/qingflow_task_action.json
+```
+
+`**--action` 允许字面量**（实现校验，大小写不敏感）：
+`approve`、`reject`、`rollback`、`transfer`、`urge`、`save_only`。
+
+**约束摘要**（与实现一致）：
+
+- **定位只认 `task_id`**：来自 `task list` 的 `data.items[].task_id`；`app_key`、`record_id`、`workflow_node_id` 不是动作执行入参。
+- `**approve` / `reject`**：执行上下文以当前待办详情或用户/前端已给出的显式 `formId` 为准；只有缺少 `formId` 时才兜底读取应用 baseInfo。不要把应用 baseInfo 的 `40002` 当作待办动作最终无权结论，最终是否可执行以后端审批动作接口为准。
+- `**save_only`**：必须 提供非空 `**--fields-file`**（或 payload 与 fields 不能同时塞 `answers` 与 fields，具体以报错为准）。以当前待办节点的 `data.editable_fields` / `editableQueIds` 为准；若 `editableQueIds` 被当前权限链路挡住，但任务详情里的 `queAuthSetting` 已暴露可编辑字段，CLI 会按任务详情继续允许 save-only，并由最终保存接口裁决。申请表单 schema 或辅助 `editableQueIds` 的 `40002` 不是待办字段保存的最终无权结论。
+- `**transfer**`：`**payload` 内需要** `target_member_id`（或别名 `uid` / `targetMemberId`）；不能转给当前登录人。
+- **意见必填**：若详情里 `**action_constraints.feedback_required_for`** 包含当前动作，需在 `**payload.audit_feedback`**（实现从 payload 抽取审计意见，具体键名以 `--help` / 服务端为准）中提供，否则会 config 错误。
+- `**urge`**：**不支持** 与 `fields` 同时提交。
+- **禁止臆测动作**：只允许 `**data.available_actions`** 中出现的动作；`approve` 不在列表则不可硬放行。
+
+`**--payload-file` / `--fields-file`**：UTF-8 JSON 对象，与 `record update` 同类「文件用 JSON」习惯一致。
+
+---
+
+## 4. 与「应用内 `record list`」的边界
+
+- **任务中心待办 / 已办 / 抄送**：用 `**task list --task-box …`**，**不要**再用过时的 `record list --view-id system:todo` 等当作任务箱。
+- **业务表读数**：仍在 `app get` 的 `**accessible_views`** 里选 `**custom:`* 等**，走 [QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md](../core/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md)。
+
+---
+
+## 5. 实测与排障（编写时实跑）
+
+
+| 命令                                      | 结果                                                                                                                                                          |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task list --task-box todo`             | 返回多条，`items[].task_id` 为字符串；列表项可能不含 `app_key`（详情阶段再解析）。                                                                                                     |
+| `task get --task-id …`                  | `data.task` 含完整定位；`available_actions` 示例含 `approve`/`reject`/`rollback`/`transfer`；`extras.associated_reports` 可为 `count: 0` 或大于 0。                         |
+| `task log --task-id …`                  | 返回 `data.items` 审批/流程历史。                                                                                                                                    |
+| `task report --task-id … --report-id …` | 某条 `**count>0`** 的抽样上曾返回后端 `**40038` Object not exist**；同一 `task get` 里仍列出 `report_id`。**建议**：换 `report_id`、确认报表未删除、核对轻流 BI 权限与节点关联；仍失败时保留 `request_id` 报障。 |
+
+
+**说明**：本文编写时仅用读接口抽样校验；`**task action`** 可依照 **第 3.5 节** 在自动化剧本中直接调用，由编排侧控制目标待办与动作，避免误批。
+
+---
+
+## 6. 交叉引用
+
+- 主技能 [SKILL.md](../../SKILL.md)：**落盘规则**、`**task-box` / `flow-status`** 枚举、与 `record` 混用雷区。
+- [QINGFLOW_CLI_MEMBER_CHEATSHEET.md](../core/QINGFLOW_CLI_MEMBER_CHEATSHEET.md)：成员侧最短路径。

package/skills/qingflow-cli/reference/task/ops/README.md

@@ -0,0 +1,134 @@
+# Qingflow CLI Task Ops
+
+## Overview
+
+This section is for task workflow operations only. Do not use it for record CRUD or final statistical analysis.
+
+## Default Paths
+
+Use exactly one of these default paths:
+
+1. Find target todos
+   `qingflow task list`
+
+2. Read one task context
+   `task list -> exact target -> task get`
+
+3. Read associated approval context
+   `task get -> task report` or `task log`
+
+4. Execute workflow action
+   `task list -> exact target -> task get -> task action`
+
+5. Execute a user-specified action on an already-clear target
+   `task list -> exact target -> (optional task get) -> task action`
+
+## Core Tools
+
+- `qingflow task list`
+- `qingflow task get`
+- `qingflow task action`
+- `qingflow task report`
+- `qingflow task log`
+
+## Supporting Tools
+
+- `app_list`
+- `app_search`
+
+## Standard Operating Order
+
+Before any task action, comment, transfer, urge, approve, reject, or rollback, resolve the target environment with [environments.md](./environments.md). If the user does not specify one, default to `prod`.
+
+Use one of these two modes:
+
+1. Recommendation mode
+   1. Discover the exact target with `task list`
+   2. Read node context with `task get`
+   3. Before giving any approval recommendation, read `task log`
+   4. If `task get` returns any `associated_reports`, read every visible report through `task report`
+   5. Give a recommendation only after reviewing node context, workflow log, and associated reports
+   6. Wait for explicit user confirmation before `task action`
+
+2. User-directed execution mode
+   1. Discover the exact target with `task list`
+   2. If the target or action requirements are ambiguous, read `task get`; otherwise go straight to `task action`
+   3. Execute through `task action --task-id ...`
+   4. After actions, report the exact `task_id`, executed action, and any returned `app_key / record_id` plus warnings
+
+## Task-Center Rules
+
+- Use `task list` for flat browsing
+- `task_box` must be one of:
+  - `todo`
+  - `initiated`
+  - `cc`
+  - `done`
+- `flow_status` must be one of:
+  - `all`
+  - `in_progress`
+  - `approved`
+  - `rejected`
+  - `pending_fix`
+  - `urged`
+  - `overdue`
+  - `due_soon`
+  - `unread`
+  - `ended`
+- `task list` is the only public task discovery path
+- `task list --query` uses backend `searchKey` first; only when backend returns zero rows does CLI apply a local fallback match on normalized `app_name / workflow_node_name / app_key / record_id`
+- Treat `task_id` from `task list.data.items[]` as the public action locator. Do not reconstruct action identity from `app_key + record_id + workflow_node_id`.
+- Default box usage:
+  - `todo`: `task list -> task get -> task log / task report -> recommendation -> explicit user confirmation -> task action`
+  - `initiated`: `task list -> record get`
+  - `done`: `task list -> record get`
+  - `cc`: `task list -> record get`
+- Treat `initiated`, `done`, and `cc` primarily as list-plus-record-detail flows, not task action flows
+
+## Workflow Usage Actions
+
+- `task get.capabilities.available_actions` is the source of truth for executable actions
+- Current public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+  - `save_only`
+- Before any approve/reject/rollback/transfer recommendation, always review `task log` when `task get.visibility.audit_record_visible=true`
+- If `task get` returns visible `associated_reports`, review each one with `task report`; do not rely on report summary alone
+- Do not give an approval recommendation based only on `task get`
+- Do not execute `task action` 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 `task_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` distinguishes action execution from workflow continuation. Read `verification.runtime_continuation_verified` before claiming the workflow actually moved on.
+- If `task action` returns `partial_success` with `WORKFLOW_CONTINUATION_UNVERIFIED`, report the action as sent but the downstream continuation as unverified.
+- If `task action` 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
+
+- If task capabilities, associated report detail, workflow log visibility, or action support still cannot satisfy the user's goal after reasonable use of this skill, summarize the exact gap in plain language.
+- Ask whether the user wants you to submit product feedback.
+- Only after explicit user confirmation, call `feedback_submit`.
+
+## 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
+
+## Resources
+
+- Environment switching: [environments.md](./environments.md)
+- Workflow and task usage actions: [workflow-usage.md](./workflow-usage.md)

package/skills/qingflow-cli/reference/task/ops/environments.md

@@ -0,0 +1,43 @@
+# Environment Switching
+
+Use this reference before any workflow usage action, comment, or task-center operation that might affect live work.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the task targets:
+
+- `test`: demo, mock data, smoke usage validation, training scenarios
+- `prod`: real operational tasks, comments, and workflow actions
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Use test for:
+
+- workflow walkthroughs
+- user acceptance demos
+- comment or transfer rehearsals
+
+## Production Environment
+
+Use production for:
+
+- live task-center operations
+- live comments on real business records
+- approve / reject / rollback / transfer / urge on real work
+
+Production guardrails:
+
+- never assume a task id, record id, or workflow node id
+- find the exact target first
+- if the task can be answered read-only, do not act
+
+## Reporting Rule
+
+For task ops, always report:
+
+- active environment
+- target app or task box
+- operation type: read, comment, approve, reject, rollback, transfer, urge, or mark_read
+- affected task ids or record ids

package/skills/qingflow-cli/reference/task/ops/workflow-usage.md

@@ -0,0 +1,29 @@
+# Workflow and Task Usage Actions
+
+Use these when the user is operating inside an existing process, not redesigning it.
+
+Examples:
+
+- add a comment to a record
+- approve or reject a workflow task
+- transfer a task
+- roll back a task
+- list todo, initiated, done, or cc tasks
+- inspect workload by worksheet or workflow node
+- urge a pending task
+
+Rules:
+
+- if the user starts from inbox, todo, workload, cc, or bottleneck language, use `task_*` first
+- use `task_summary` for headline counts
+- use `task_list` for flat browsing
+- use `task_facets` when worksheet or workflow-node buckets matter
+- treat task counts as task-center counts, not record counts
+- switch to `record_get` only after locating the exact business record behind a task
+- identify the exact target first through `task_list`
+- for approve, reject, rollback, transfer, urge, or save-only, use only `task_list.data.items[].task_id` as the public action locator
+- read `task_get` before action when the allowed action or required payload is not already explicit; `task_get.data.available_actions` is the source of truth
+- avoid usage-side workflow actions on ambiguous records
+- do not reconstruct an action target from `app_key + record_id + workflow_node_id`; those fields are readback/debug context, not the default action input
+- execute actions through `task action --task-id ... --action ...`
+- summarize the final action and exact `task_id`; include record ids only as returned context

package/skills/qingflow-cli/reference/views_upsert_table_minimal.example.json

@@ -1,7 +1,42 @@
-[
-  {
-    "name": "示例表视图_CLI模板",
-    "type": "table",
-    "columns": ["单行文字", "多行文字"]
-  }
-]
+{
+  "views": [
+    {
+      "operation": "upsert",
+      "app_key": "APP_KEY",
+      "name": "示例业务操作视图_CLI模板",
+      "type": "table",
+      "columns": ["主记录编号", "主记录名称", "状态", "负责人"],
+      "filters": [
+        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
+      ],
+      "query_conditions": {
+        "enabled": true,
+        "exact": false,
+        "hide_before_query": false,
+        "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
+      },
+      "action_buttons": [
+        {
+          "text": "行内创建子记录",
+          "action": "add_data",
+          "target_app_key": "TARGET_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联主记录"}
+          ],
+          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+          "placement": "list"
+        },
+        {
+          "text": "详情创建子记录",
+          "action": "add_data",
+          "target_app_key": "TARGET_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联主记录"}
+          ],
+          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+          "placement": "detail"
+        }
+      ]
+    }
+  ]
+}