@qingflow-tech/qingflow-cli 1.1.47-beta.5 → 1.1.48-beta.1

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.47-beta.5
+npm install @qingflow-tech/qingflow-cli@1.1.48-beta.1
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.47-beta.5 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.48-beta.1 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.47-beta.5 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.48-beta.1 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/npm/lib/runtime.mjs

@@ -569,6 +569,34 @@ function findOfflineProjectWheel(findLinksDir) {
   return path.join(findLinksDir, wheels[wheels.length - 1]);
 }
 
+function hasEnv(env, name) {
+  return Object.prototype.hasOwnProperty.call(env, name);
+}
+
+export function buildPipInstallArgs(env = process.env) {
+  const standardNoIndexConfigured = hasEnv(env, "PIP_NO_INDEX");
+  const standardFindLinksConfigured = hasEnv(env, "PIP_FIND_LINKS");
+
+  const noIndex = (standardNoIndexConfigured ? env.PIP_NO_INDEX : env.QINGFLOW_MCP_PIP_NO_INDEX) === "1";
+  const findLinks = String(
+    standardFindLinksConfigured ? env.PIP_FIND_LINKS ?? "" : env.QINGFLOW_MCP_PIP_FIND_LINKS ?? "",
+  ).trim();
+
+  const pipArgs = ["install", "--disable-pip-version-check"];
+  if (noIndex) {
+    pipArgs.push("--no-index");
+  }
+  if (findLinks) {
+    pipArgs.push("--find-links", findLinks);
+  }
+  if (noIndex && findLinks) {
+    pipArgs.push(findOfflineProjectWheel(findLinks));
+  } else {
+    pipArgs.push(".");
+  }
+  return pipArgs;
+}
+
 export function findPython() {
   const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
   const candidates = preferred
@@ -629,19 +657,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   }
 
   const pip = getVenvPip(packageRoot);
-  const pipArgs = ["install", "--disable-pip-version-check"];
-  const offlineFindLinks = process.env.QINGFLOW_MCP_PIP_FIND_LINKS?.trim();
-  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1") {
-    pipArgs.push("--no-index");
-  }
-  if (offlineFindLinks) {
-    pipArgs.push("--find-links", offlineFindLinks);
-  }
-  if (process.env.QINGFLOW_MCP_PIP_NO_INDEX === "1" && offlineFindLinks) {
-    pipArgs.push(findOfflineProjectWheel(offlineFindLinks));
-  } else {
-    pipArgs.push(".");
-  }
+  const pipArgs = buildPipInstallArgs();
   runChecked(pip, pipArgs, { cwd: packageRoot });
 
   const probe = probePythonRuntime(packageRoot, commandName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.47-beta.5",
+  "version": "1.1.48-beta.1",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/src/qingflow_mcp/cli/commands/data.py

@@ -1,20 +1,41 @@
 from __future__ import annotations
 
 import argparse
+import textwrap
 
 from ..context import CliContext
 from .common import load_list_arg, require_list_arg, require_object_arg, raise_config_error
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    parser = subparsers.add_parser("data", help="视图无关的应用数据面")
+    parser = subparsers.add_parser(
+        "data",
+        help="视图无关的应用数据面",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""
+            JSON 文件约定：
+              columns.json  [101, 102]
+              where.json    [{"field_id": 101, "op": "eq", "value": "A"}]
+              sort.json     [{"field_id": 101, "direction": "asc"}]
+              items.json    [{"fields": {"101": "A"}}]
+              fields.json   {"101": "B"}
+            query/get/insert/update 默认返回 field_capabilities；可用 --no-schema 关闭。
+        """).strip(),
+    )
     commands = parser.add_subparsers(dest="data_command", required=True, metavar="{query,get,insert,update,delete}")
 
-    query = commands.add_parser("query", help="分页查询应用数据")
+    query = commands.add_parser(
+        "query", help="分页查询应用数据", formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='最小示例：qingflow data query --app-key APP_1 --where-file where.json\n'
+               'where.json: [{"field_id": 101, "op": "eq", "value": "A"}]',
+    )
     query.add_argument("--app-key", required=True)
-    query.add_argument("--columns-file")
-    query.add_argument("--where-file")
-    query.add_argument("--sort-file")
+    query.add_argument("--columns-file", help='JSON 数组，例如 [101, 102]')
+    query.add_argument(
+        "--where-file",
+        help='JSON 数组；项为 {"field_id":101,"op":"eq","value":"A"}，in/not_in 的 value 必须为数组',
+    )
+    query.add_argument("--sort-file", help='JSON 数组，例如 [{"field_id":101,"direction":"asc"}]')
     query.add_argument("--search", default="")
     query.add_argument("--page", type=int, default=1)
     query.add_argument("--page-size", type=int, default=100)
@@ -29,16 +50,22 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     get.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
     get.set_defaults(handler=_handle_get, format_hint="data_get")
 
-    insert = commands.add_parser("insert", help="新增应用数据")
+    insert = commands.add_parser(
+        "insert", help="新增应用数据", formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='最小示例：items.json = [{"fields": {"101": "A"}}]',
+    )
     insert.add_argument("--app-key", required=True)
-    insert.add_argument("--items-file", required=True)
+    insert.add_argument("--items-file", required=True, help='JSON 数组，项为 {"fields":{"字段ID":值}}')
     insert.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
     insert.set_defaults(handler=_handle_insert, format_hint="data_insert")
 
-    update = commands.add_parser("update", help="更新应用数据")
+    update = commands.add_parser(
+        "update", help="更新应用数据", formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='最小示例：fields.json = {"101": "B"}',
+    )
     update.add_argument("--app-key", required=True)
     update.add_argument("--record-id", required=True)
-    update.add_argument("--fields-file", required=True)
+    update.add_argument("--fields-file", required=True, help='JSON 对象，键为字符串形式 field_id')
     update.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
     update.set_defaults(handler=_handle_update, format_hint="data_update")
 

package/src/qingflow_mcp/cli/formatters.py

@@ -8,7 +8,10 @@ from typing import Any, TextIO
 def emit_text_result(result: dict[str, Any], *, hint: str, stream: TextIO) -> None:
     text = _format_cancelled_result(result)
     if text is None:
-        if _is_failed_result(result) and hint != "task_action_execute":
+        if hint in _DATA_FORMAT_HINTS:
+            # 数据面失败也必须保留 field_errors 与列表型 hints，不能先走通用失败裁剪。
+            text = _format_data_result(result)
+        elif _is_failed_result(result) and hint != "task_action_execute":
             text = _format_failed_result(result)
         else:
             formatter = _FORMATTERS.get(hint, _format_generic)
@@ -90,6 +93,92 @@ def _format_generic(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_data_result(result: dict[str, Any]) -> str:
+    lines = [f"Status: {result.get('status') or ('success' if result.get('ok') is not False else 'failed')}"]
+    if result.get("format") == "csv":
+        files = result.get("files") if isinstance(result.get("files"), list) else []
+        lines.extend(
+            [
+                f"Local dir: {result.get('local_dir') or '-'}",
+                f"Files: {len(files)}",
+            ]
+        )
+        for item in files:
+            if isinstance(item, dict):
+                lines.append(
+                    f"- part {item.get('part')}: {item.get('local_path')} ({item.get('row_count')} rows)"
+                )
+        lines.extend(
+            [
+                f"Rows: {result.get('row_count')}",
+                f"Complete: {result.get('complete')}",
+                f"Truncated: {result.get('truncated')}",
+                f"Safe for final conclusion: {result.get('safe_for_final_conclusion')}",
+                f"Stopped reason: {result.get('stopped_reason') or '-'}",
+            ]
+        )
+    access = result.get("access") if isinstance(result.get("access"), dict) else {}
+    if access:
+        sources = access.get("scope_sources") if isinstance(access.get("scope_sources"), list) else []
+        lines.append(
+            f"Access: level={access.get('level') or '-'} / can_write={access.get('can_write')}"
+            f" / scope_sources={','.join(str(item) for item in sources) or '-'}"
+        )
+
+    records = result.get("records") if isinstance(result.get("records"), dict) else {}
+    if records:
+        items = records.get("items") if isinstance(records.get("items"), list) else []
+        lines.append(
+            "Pagination: "
+            f"page={records.get('page')} / requested_page_size={records.get('requested_page_size')} / "
+            f"page_size={records.get('page_size')} / total={records.get('total')} / "
+            f"has_more={records.get('has_more')} / returned={len(items)}"
+        )
+    record = result.get("record") if isinstance(result.get("record"), dict) else {}
+    if record:
+        lines.append(f"Record ID: {record.get('record_id') or '-'}")
+    items = result.get("items") if isinstance(result.get("items"), list) else []
+    if items:
+        lines.append(f"Items: {len(items)}")
+
+    for key, label in (
+        ("error_code", "Error Code"),
+        ("message", "Message"),
+        ("write_executed", "Write Executed"),
+        ("retry_safe", "Retry Safe"),
+    ):
+        if key in result:
+            lines.append(f"{label}: {result.get(key)}")
+
+    field_errors = result.get("field_errors") if isinstance(result.get("field_errors"), list) else []
+    if field_errors:
+        lines.append("Field Errors:")
+        _append_data_field_errors(lines, field_errors)
+    for index, item in enumerate(items):
+        if not isinstance(item, dict) or not isinstance(item.get("field_errors"), list):
+            continue
+        lines.append(f"Item {index} Field Errors:")
+        _append_data_field_errors(lines, item["field_errors"])
+
+    hints = result.get("hints") if isinstance(result.get("hints"), list) else []
+    lines.append(f"Hints: {len(hints)}")
+    for hint in hints:
+        if isinstance(hint, dict):
+            lines.append(f"- {hint.get('code') or '-'}: {hint.get('message') or '-'}")
+        else:
+            lines.append(f"- {hint}")
+    return "\n".join(lines) + "\n"
+
+
+def _append_data_field_errors(lines: list[str], field_errors: list[Any]) -> None:
+    for error in field_errors:
+        if isinstance(error, dict):
+            lines.append(
+                f"- {error.get('path') or '-'}: {error.get('message') or '-'}"
+                f" / fix_hint={error.get('fix_hint') or '-'}"
+            )
+
+
 def _format_whoami(result: dict[str, Any]) -> str:
     lines = [
         f"User: {result.get('nick_name') or '-'} ({result.get('email') or '-'})",
@@ -1668,4 +1757,11 @@ _FORMATTERS = {
     "builder_summary": _format_builder_summary,
     "file_upload_local": _format_file_upload_local,
     "feedback_submit": _format_feedback_submit,
+    "data_query": _format_data_result,
+    "data_get": _format_data_result,
+    "data_insert": _format_data_result,
+    "data_update": _format_data_result,
+    "data_delete": _format_data_result,
 }
+
+_DATA_FORMAT_HINTS = {"data_query", "data_get", "data_insert", "data_update", "data_delete"}

package/src/qingflow_mcp/tools/data_tools.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from datetime import datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal, TypedDict
 
 from mcp.server.fastmcp import FastMCP
 
@@ -19,6 +19,32 @@ DATA_CSV_SHARD_ROWS = 20_000
 DATA_UNBOUNDED_ROW_THRESHOLD = 50_000
 DATA_CSV_TIME_BUDGET_SECONDS = 55.0
 
+DataFilterOperator = Literal[
+    "eq", "ne", "contains", "not_contains", "gt", "gte", "lt", "lte", "in", "not_in"
+]
+DataSortDirection = Literal["asc", "desc"]
+
+
+class DataWhereItem(TypedDict):
+    """数据面筛选项；in/not_in 使用数组，其余操作符使用单值。"""
+
+    field_id: int
+    op: DataFilterOperator
+    value: JSONValue
+
+
+class DataSortItem(TypedDict):
+    """数据面排序项。"""
+
+    field_id: int
+    direction: DataSortDirection
+
+
+class DataInsertItem(TypedDict):
+    """数据面新增项，fields 的键为字符串形式 field_id。"""
+
+    fields: dict[str, JSONValue]
+
 
 class DataTools(ToolBase):
     """视图无关的应用数据面工具。"""
@@ -29,8 +55,8 @@ class DataTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             columns: list[int] | None = None,
-            where: list[dict] | None = None,
-            sort: list[dict] | None = None,
+            where: list[DataWhereItem] | None = None,
+            sort: list[DataSortItem] | None = None,
             search: str = "",
             page: int = 1,
             page_size: int = 100,
@@ -38,6 +64,7 @@ class DataTools(ToolBase):
             all_pages: bool = False,
             output: str = "json",
         ) -> JSONObject:
+            """按字段 ID 查询应用数据；先读取 field_capabilities 再构造 where 和 sort。"""
             return self.data_query(
                 profile=profile, app_key=app_key, columns=columns or [], where=where or [], sort=sort or [],
                 search=search, page=page, page_size=page_size, include_schema=include_schema,
@@ -52,9 +79,10 @@ class DataTools(ToolBase):
 
         @mcp.tool()
         def data_insert(
-            profile: str = DEFAULT_PROFILE, app_key: str = "", items: list[dict] | None = None,
+            profile: str = DEFAULT_PROFILE, app_key: str = "", items: list[DataInsertItem] | None = None,
             include_schema: bool = True,
         ) -> JSONObject:
+            """新增应用数据；每项形如 {"fields": {"字段ID": 值}}。"""
             return self.data_insert(profile=profile, app_key=app_key, items=items or [], include_schema=include_schema)
 
         @mcp.tool()
@@ -74,7 +102,8 @@ class DataTools(ToolBase):
             return self.data_delete(profile=profile, app_key=app_key, record_ids=record_ids or [])
 
     def data_query(
-        self, *, profile: str, app_key: str, columns: list[int], where: list[dict], sort: list[dict],
+        self, *, profile: str, app_key: str, columns: list[int], where: list[DataWhereItem],
+        sort: list[DataSortItem],
         search: str = "", page: int = 1, page_size: int = 100, include_schema: bool = True,
         all_pages: bool = False, output: str = "json",
     ) -> JSONObject:
@@ -113,7 +142,9 @@ class DataTools(ToolBase):
             tool_name="数据面单条读取",
         )
 
-    def data_insert(self, *, profile: str, app_key: str, items: list[dict], include_schema: bool = True) -> JSONObject:
+    def data_insert(
+        self, *, profile: str, app_key: str, items: list[DataInsertItem], include_schema: bool = True
+    ) -> JSONObject:
         self._require_app_key(app_key)
         return self._write(profile, app_key, "POST", self._base_path(app_key), {"items": items, "include_schema": include_schema}, "数据面新增")